會員方案總覽

使用會員方案在 Google 上展示商店福利。你可以提交多項福利，例如免運費、可兌換的點數和會員專屬價格。會員方案福利可顯示在 Google 平台上的免費產品資訊、購物廣告和店面商品目錄廣告，包括 Google 搜尋、「購物」分頁和 Google 錢包。

商家和代表商家行事的第三方會員方案供應商，可透過 Merchant API 使用 LoyaltyProgramService，以程式輔助方式設定及維護會員方案。這項服務可讓您建立、擷取、列出、更新及刪除會員方案。

重要事項： 這項服務僅適用於特定商家。如要參與這項前測服務，請透過購物 API 支援表單提交許可清單申請，並在「問題/疑問為何？」> 許可清單要求 > 其他。

如要進一步瞭解商家規定和政策規範，請參閱 Merchant Center 說明中心的「關於商家會員方案」。

核心概念

使用會員方案時，請注意下列概念和限制：

• 帳戶層級 ID：Merchant API 會根據所屬 Merchant Center 帳戶 ID 識別會員方案。
• 單一方案限制：每個商家帳戶只能透過 Merchant API 支援一個會員方案。
• 直接擁有帳戶：會員方案必須直接在目標商家帳戶 (accounts/{ACCOUNT_ID}) 中設定。這項服務不支援在子帳戶的進階帳戶層級管理會員方案。獲得商家帳戶授權的第三方會員方案供應商，可以代表商家管理方案。
• 編輯審查：建立或更新會員方案後，系統會對方案進行審查。review_result.review_status 欄位會指出節目是 UNDER_REVIEW、APPROVED 或 REJECTED。
• 支援的地區：商家會員方案適用於支援的國家/地區，包括澳洲、巴西、加拿大、法國、德國、印度、義大利、墨西哥、荷蘭、韓國、西班牙、英國和美國。
• 等級規定：加入等級可能無須支付費用、須支付會費、須達到消費門檻，或須使用商家品牌的信用卡。系統不支援以職業分類的級別 (例如學生或軍人)。
• 福利：方案支援免運費、可兌換的點數和會員價。在廣告中，會員價的折扣必須至少為原價或特價的 5%，或至少 5 個單位貨幣。

必要條件

使用 Merchant API 管理會員方案前，請確認你符合下列規定：

• 你必須擁有有效的 Merchant Center 帳戶 (如果你是第三方會員方案供應商，則必須獲得商家帳戶的授權存取權)。
• 為帳戶啟用會員方案外掛程式。你可以使用下列任一選項啟用外掛程式：
  • Merchant Center 使用者介面：請按照 Merchant Center 說明中的「設定會員方案」操作。
  • 「計畫」子 API：如要以程式輔助方式啟用計畫，請參閱「在『計畫』子 API 中啟用計畫」。

以下是使用 Programs 子 API 啟用會員方案附加功能的範例要求：

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

cURL

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

方法

你可以透過下列方式管理會員方案：

• loyaltyPrograms.create
• loyaltyPrograms.get
• loyaltyPrograms.list
• loyaltyPrograms.update
• loyaltyPrograms.delete

建立會員方案

如要為帳戶建立新的會員方案，請使用 loyaltyPrograms.create 方法。指定詳細資料，例如方案說明、註冊網址，以及各方案層級的專屬福利和條件。

必要 program_label 會設定會員方案的專屬 ID。舉例來說，提供標籤 my-rewards 會產生 accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards 的 name 資源。

以下是範例要求：

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

將 {ACCOUNT_ID} 替換為 Merchant Center 帳戶的專屬 ID。

以下是成功要求的回應範例：

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

擷取會員方案

如要擷取特定自有會員方案的詳細資料，請使用 loyaltyPrograms.get 方法。

注意： 即使尚未啟用會員方案外掛程式，這個端點仍會回應相符的會員方案，不會傳回錯誤。

以下是範例要求：

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

將 {ACCOUNT_ID} 替換為帳戶 ID，並將 {PROGRAM_LABEL} 替換為會員方案的專屬標籤 (例如 my-rewards)。

以下是成功要求的回應範例：

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

列出會員方案

如要列出與帳戶相關聯的所有自有會員方案，請使用 loyaltyPrograms.list 方法。

注意： 這個方法只會列出指定帳戶直接擁有的會員方案，不會列出與子帳戶相關聯的方案。即使停用 Loyalty 計畫外掛程式，這個端點仍會回應現有計畫，不會傳回錯誤。

以下是範例要求：

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

以下是成功要求的回應範例：

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

更新會員方案

如要更新現有會員方案，請使用 loyaltyPrograms.update 方法。使用 update_mask 執行部分更新，或省略遮罩來執行完整替換。

重要事項： 更新會員方案時，重複的欄位 (例如 programDescriptions 和 tiers) 無法就地更新。更新中包含的任何重複欄位都會取代整個現有清單。為避免意外遺失資料，請先傳送 get 要求來擷取目前的值，再更新重複欄位。

使用更新遮罩進行部分更新

update_mask 可讓您指定要更新的確切欄位。系統只會修改遮罩中列出的欄位，未列出的欄位則維持不變。如果更新遮罩中省略任何欄位，系統會忽略這些欄位，即使要求主體中提供這些欄位也一樣。

下列範例要求只會更新 programDescriptions 和 advancedSettings：

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

在本例中，服務會忽略 signupUrl，因為 update_mask 中未包含該項目。programDescriptions 欄位會完全取代先前設定的說明。

以下是成功要求的回應範例：

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

完整取代，不使用更新遮罩

如果省略 update_mask 參數，要求會完整取代會員方案設定。

以下是範例要求：

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

以下是成功要求的回應範例：

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

刪除會員方案

如要從帳戶中刪除會員方案，請使用 loyaltyPrograms.delete 方法。

以下是範例要求：

HTTP

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

如果成功，回應主體會留白。

後續步驟

• 如要在 Google 搜尋上進行有機個人化，將個別購物者與會員方案等級建立關聯，請參閱會員顧客比對服務指南。
• 如要為帳戶啟用或停用購物計畫，請參閱計畫子 API 指南。
• 如要瞭解商家設定詳情、編輯政策和報表，請參閱 Merchant Center 說明的「關於商家會員方案」。
• 如要探索 API 方法和資源定義，請參閱 Merchant API 參考資料。