重要提示： Content API for Shopping 已于 2026 年 8 月 18 日 停用。

自 2026 年 9 月 1 日 起，Content API for Shopping 请求将逐渐出现错误。请参阅 Content API 停用指南。

如果您需要更多时间来迁移到 Merchant API，请申请延长 Content API for Shopping 的访问权限。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

会员回馈活动概览

通过会员回馈活动在 Google 上展示您的商店福利。您可以提交各种福利，例如免运费、可兑换的积分和会员专享价。您的会员回馈活动福利可以显示在 Google 平台（包括 Google 搜索、“购物”标签页和 Google 钱包）上的非付费商品详情、购物广告和本地商品目录广告中。

借助 Merchant API，商家和代表商家的第三方会员回馈活动提供商可以使用 LoyaltyProgramService 以编程方式配置和维护会员回馈活动。借助此服务，您可以创建、检索、列出、更新和删除会员回馈活动。

如需详细了解业务要求和政策指南，请参阅 Merchant Center 帮助中心内的商家会员回馈活动简介。

主要概念

使用会员回馈活动时，请注意以下概念和限制：

账号级标识符：Merchant API 通过所属 Merchant Center 账号 ID 标识会员回馈活动。
单一计划限制：Merchant API 仅支持每个商家账号一个会员回馈活动。
直接账号所有权：会员回馈活动必须直接在目标商家账号 (accounts/{ACCOUNT_ID}) 中配置。该服务不支持在高级账号级别为子账号管理会员回馈活动。获得商家账号授权访问权限的第三方会员回馈活动提供商可以代表商家管理会员回馈活动。
编辑审核：创建或更新会员回馈活动后，该活动会接受审核。review_result.review_status 字段指明程序是 UNDER_REVIEW、APPROVED 还是 REJECTED。每次成功更新都会将计划重新发送到审核队列，即使更新未更改任何主要内容也是如此。在审核过程中，Google 会向买家隐藏该计划。审核最多可能需要 48 小时。
支持的地区：商家会员回馈活动可在受支持的国家/地区使用，包括澳大利亚、巴西、加拿大、法国、德国、印度、意大利、日本、墨西哥、荷兰、韩国、西班牙、英国和美国。
活跃区域：会员回馈活动的 regionCodes 必须是 accounts/{ACCOUNT_ID}/programs/loyalty 的 activeRegionCodes 的子集。否则，创建、更新和删除请求将失败，并显示 LOYALTY_PROGRAM_DISABLED 错误。当您启用会员回馈活动插件且账号符合相应国家/地区的资格要求时，Google 会激活该国家/地区。例如，如果账号已启用非付费商品详情计划，并且主要商品数据源定位到 FREE_LISTINGS 目标平台对应的国家/地区，则该账号符合条件。如需了解某个国家/地区未处于有效状态的原因，请参阅检查有效区域。
层级要求：层级可以免费加入，也可以要求支付会员费、达到消费门槛或持有商家品牌信用卡。不支持基于职业的层级（例如学生或军人层级）。
福利和权益：会员回馈活动支持免运费、积分兑换和会员价格。在广告中，会员价必须比正常价或促销价至少低 5% 或 5 个货币单位。

前提条件

在使用 Merchant API 管理会员回馈活动之前，请确保您满足以下要求：

您必须拥有有效的 Merchant Center 账号（如果您是第三方会员卡提供商，则必须拥有对商家账号的授权访问权限）。
为您的账号启用会员计划插件。您可以使用以下任一选项启用该插件：
- Merchant Center 界面：按照 Merchant Center 帮助中的设置会员回馈活动中的说明操作。
- Programs sub-API：按照在 Programs sub-API 中启用计划中的说明，以编程方式启用计划。accounts.programs.enable 方法需要管理员访问权限。
您希望提供会员回馈活动的国家/地区必须在您的账号中处于有效状态。如需了解哪些国家/地区处于活跃状态，请参阅查看活跃区域。

以下是使用 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

检查活跃区域

启用会员回馈活动插件后，请为 accounts/{ACCOUNT_ID}/programs/loyalty 调用 accounts.programs.get 方法。回答会显示您可以在哪些国家/地区使用会员回馈活动，以及其他受支持的国家/地区为何处于无效状态。

以下是请求示例：

HTTP

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

cURL

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

将 {ACCOUNT_ID} 替换为您的 Merchant Center 账号的唯一标识符。

以下是已启用该插件且仅在美国符合条件的账号的示例响应：

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}

在此响应中，请注意以下字段：

activeRegionCodes：您可以在会员回馈活动的 regionCodes 中使用的国家/地区。在前面的示例中，只有 US 处于活跃状态。
unmetRequirements：其他受支持的国家/地区处于无效状态的原因。对于会员回馈活动，这是 IS_ELIGIBLE_FOR_LOYALTY 要求。
- affectedRegionCodes：账号不符合条件的支持国家/地区。
- documentationUri：指向资格要求的链接。

在前面的示例中，您还无法使用 affectedRegionCodes 中的国家/地区。如果您的会员回馈活动的 regionCodes 包含其中一个，则创建、更新和删除请求会失败，并显示 LOYALTY_PROGRAM_DISABLED 错误。如需激活某个国家/地区，请执行以下操作：

使该账号在相应国家/地区符合条件。例如，启用非付费商品详情计划，并设置主要商品数据源，以定位到 FREE_LISTINGS 目标平台的国家/地区。如需了解所有符合条件的方式，请参阅资格要求。
再次调用 accounts.programs.get，并检查国家/地区是否在 activeRegionCodes 中。

affectedRegionCodes可能包含您不销售商品的国家/地区。对于这些国家/地区，您无需采取任何行动。它们不会影响 activeRegionCodes 中的国家/地区。

方法

您可以使用以下方法管理会员回馈活动：

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

创建会员回馈活动

如需为账号创建新的会员回馈活动，请使用 loyaltyPrograms.create 方法。指定计划说明、注册网址、计划层级及其专属福利和要求等详细信息。

必需的 program_label 用于设置会员回馈活动的唯一标识符。例如，提供标签 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 账号的唯一标识符。

以下是成功请求的示例响应：

{
  "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}

如果成功，则响应正文为空。

后续步骤

如需将个别买家与您的会员回馈活动层级相关联，以便在 Google 搜索上进行自然个性化，请参阅会员目标客户匹配服务指南。
如需为您的账号启用或停用购物计划，请参阅计划子 API 指南。
如需了解商家设置详情、广告编辑政策和报告，请参阅 Merchant Center 帮助中的商家会员回馈活动简介。
如需探索 API 方法和资源定义，请参阅 Merchant API 参考文档。

Overview

Manage customer loyalty data

会员回馈活动概览 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

主要概念

前提条件

HTTP

cURL

检查活跃区域

HTTP

cURL

方法

创建会员回馈活动

HTTP

检索会员回馈活动

HTTP

列出会员回馈活动

HTTP

更新会员回馈活动

使用更新掩码进行部分更新

HTTP

完全替换（不使用更新掩码）

HTTP

删除会员回馈活动

HTTP

后续步骤

会员回馈活动概览