會員方案總覽

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

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

如要進一步瞭解業務需求和政策規範，請參閱 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 帳戶 (如果您是第三方會員方案供應商，則須具備商家帳戶的授權存取權)。
  • 為帳戶啟用會員方案外掛程式。您可以透過下列任一選項啟用外掛程式：

以下是使用 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 方法。指定方案說明、註冊網址、方案等級等詳細資料，以及各等級的專屬福利和規定。

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 方法。

以下是要求範例：

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 執行部分更新，或省略遮罩來執行完整替換。

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

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}

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

後續步驟

上一頁
Overview
下一頁
Manage customer loyalty data