会员回馈活动概览

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

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

重要提示： 此服务仅适用于部分商家。请与支持团队联系，表明您有意参与，方法是在购物广告 API 支持表单中提交列入许可清单的申请，并在问题/疑问是什么？> 许可名单申请 > 其他。

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

主要概念

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

• 账号级标识符：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 帮助中的设置会员回馈活动一文中的说明操作。
  • Programs 子 API：以编程方式启用计划，如在 Programs 子 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 用于设置会员回馈计划的唯一标识符。例如，提供标签 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 执行部分更新，或省略掩码以执行完全替换。

重要提示： 更新会员回馈计划时，无法就地更新重复字段（例如 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 参考文档。