Merchant API v1beta 已于 2026 年 2 月 28 日停用并关停。如需了解迁移到最新稳定版的步骤，请参阅从 v1beta 迁移到 v1。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

“会员目标客户匹配”服务概览

本指南介绍了如何在 Merchant API 中使用“会员客户匹配”服务。借助此服务，商家可以管理客户忠诚度数据（例如用户标识符和会员等级信息），以便在 Google 搜索中实现自然个性化，而无需拥有有效的 Google Ads 账号。

概览

使用会员目标客户匹配服务上传会员数据，然后使用这些数据在 Google 搜索中提供会员个性化功能（例如显示会员专属价格）。您可以使用 ManageLoyaltyCustomerMatch 自定义方法将客户与会员回馈计划等级相关联，从而根据用户标识符插入、更新或移除客户的会员状态。

主要概念

统一的接口：用于添加、更新或移除客户忠诚度等级详细信息的唯一端点。
隐私至上设计：为了保护用户隐私并防止未经授权的账号探测，该 API 不支持 GET 或 LIST 操作，确保在不检索或审核数据的情况下管理数据。
灵活的标识方式：使用至少一个有效标识符（例如电子邮件地址、实际地址或电话号码）来匹配用户。
基于用户同意情况的数据处理：只有在最终用户已向 Google 授予必要的同意权限时，相应服务才会存储和使用客户数据。为了保护用户并防止探测账号是否存在或同意情况，如果未找到匹配项或用户未授予同意，该服务会返回静默成功。

前提条件

如需使用“忠诚度计划目标客户匹配”服务，您必须满足以下要求：

账号设置：确保您拥有有效的 Merchant Center 账号。您无需创建 Google Ads 账号即可使用“忠诚度客户匹配”服务。
会员回馈活动配置：在 Merchant Center 账号中启用会员回馈活动，并确保您已定义会员层级。
了解会员等级顺序：请注意会员等级在 Merchant Center 界面中的定义顺序。 API 会使用此确切的序列进行枚举映射。

方法：`ManageLoyaltyCustomerMatch`

ManageLoyaltyCustomerMatch 方法是用于管理客户忠诚度关联的中心接口。根据提供的输入，该服务会自动确定是插入、更新还是移除客户的会员等级状态。相应操作是幂等的：重复的相同请求与单个请求具有相同的效果。

以下请求演示了如何通过 API 管理客户忠诚度关联：

POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage

此请求定义了以下必需的路径参数：

api_version：API 版本，例如 v1。
account_id：Merchant Center 账号 ID。

在请求正文中添加 loyaltyCustomer 对象。

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

loyaltyCustomer 字段

userIdentifier：用于匹配客户的标识符集。必须提供 userIdentifier 中的至少一个字段，且该字段必须有效。
loyaltyTier：要与客户关联的会员等级。与 Merchant Center 设置中的层级顺序相对应。如需了解详情，请参阅了解 loyaltyTier 映射。使用 NON_MEMBER 可移除现有关联。
pointBalance：客户当前的积分余额。

userIdentifier 字段

必须至少提供以下字段中的一个：

emailAddress：客户的电子邮件地址。
address：客户的实际地址。必须提供 PostalCode。
phoneNumber：客户的电话号码。建议采用 E.164 格式。

了解 `loyaltyTier` 映射

该 API 不使用自定义名称。loyaltyTier 枚举值（TIER1 到 TIER7）是语义标签。它们不会使用您在 Merchant Center 界面中分配的自定义名称（例如“Gold Rewards”）或自定义标签（例如“gold_tier”）。而是严格按照您在 Merchant Center 的会员回馈活动设置中定义层级的顺序进行映射：

TIER1：对应于 Merchant Center 会员回馈活动配置中列出的第一个层级。
TIER2：对应于 Merchant Center 会员回馈活动配置中列出的第二个层级。
TIER3 至 TIER7：对应于 Merchant Center 会员回馈活动配置中列出的第三至第七个层级。

示例：

如果您的 Merchant Center 会员回馈活动按以下顺序定义了层级：

层级名称：“白银会员”，层级标签：“白银”
层级名称：“黄金会员”，层级标签：“黄金”
层级名称："Platinum Elite"，层级标签："platinum"

然后，在 accounts.loyaltyCustomers.manage API 调用中：

如需将客户分配到“白银状态”，您必须使用 loyaltyTier: TIER1。
如需将客户分配给“黄金会员”，您必须使用 loyaltyTier: TIER2。
如需将客户分配给“白金精英”，您必须使用 loyaltyTier: TIER3。

LoyaltyTier 枚举值

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER（用于表示移除客户的会员关联）

了解 ManageLoyaltyCustomerMatch 响应正文

ManageLoyaltyCustomerMatch 方法会返回一个 ManageLoyaltyCustomerMatchResponse 对象：

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

有关可能回答的重要注意事项：

成功进行 upsert（已存储数据）：若要成功存储或更新客户的会员等级关联，请满足以下条件：
- 您与提供的 userIdentifier 匹配的 Google 用户
- 您将请求中的 loyaltyTier 设置为除 NON_MEMBER 以外的有效值
- 匹配的用户已同意使用会员数据

响应包含您请求中的 loyaltyCustomer 对象，表明数据已成功处理并存储：

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}

成功删除：如需成功移除客户与相应商家的所有现有会员关联，必须满足以下条件：
- 您与提供的 userIdentifier 匹配的 Google 用户
- 您将请求中的 loyaltyTier 设置为 NON_MEMBER

响应是一个空的 JSON 对象：

{}

无匹配项 / 未征得同意（静默成功）：如果提供的 userIdentifier 与任何 Google 账号都不匹配，或者匹配的用户未同意使用会员数据，则 API 会返回 HTTP 200 OK 状态，并附带一个空的 JSON 对象：{}。无论是尝试进行 upsert 还是移除，都会发生这种情况。

示例

TIER1 对应于商家的第一个已定义的层级，即 "Basic"，而 TIER2 对应于第二个层级，即 "Premium"

如需使用电子邮件地址将客户添加到 TIER2 或更新其状态，请发送以下请求：

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

当用户成功配对并表示同意后，API 会返回以下响应：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

如果没有匹配项或用户未同意，API 会返回以下响应：

{}

如需使用电话号码移除客户的会员关联，请发送以下请求：

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

无论记录是否存在，API 都会返回以下成功响应：

{}

如需使用多个标识符添加或更新客户，请发送以下请求：

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

响应与第一个示例类似，具体取决于匹配情况和用户同意情况。

错误处理

该 API 使用标准 HTTP 代码。常见的错误字符串包括：

HTTP 代码	错误字符串	说明
400	INVALID_ARGUMENT	缺少 user_identifier 或 loyalty_tier，或者标识符为空。
401	UNAUTHENTICATED	凭据无效或缺失。
403	PERMISSION_DENIED	经过身份验证的用户无权访问指定的 Merchant Center 账号。
404	NOT_FOUND	您的配置中不存在指定的会员层级标签。
412	FAILED_PRECONDITION	您尚未在账号中配置会员回馈活动。
429	RESOURCE_EXHAUSTED	已达到配额限制。

错误示例

404 NOT_FOUND 的示例：

向未配置会员回馈活动的账号 ID 发出的任何有效请求。

API 返回以下错误响应：

{
  "error": {
    "code": 404,
    "message": "The loyalty program is not found for account: {account_id}.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "notFound",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_ID": "{account_id}",
          "REASON": "NOT_FOUND_LOYALTY_PROGRAM"
        }
      }
    ]
  }
}

原因：相应路径中的商家账号没有有效的会员回馈计划。

400 INVALID_ARGUMENT 的示例：

如果请求包含的 loyaltyTier 字段的值无效，则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

API 返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "loyalty_customer.loyalty_tier",
            "description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
          }
        ]
      }
    ]
  }
}

原因： TIER11 不是 loyaltyTier 的有效枚举值。如果只有一个层级可用，但您尝试指定 TIER2，也会发生同样的错误。

如果请求正文中缺少必需的 loyaltyTier 字段，则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "pointBalance": 100
  }
}

API 返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.loyalty_tier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

原因：loyaltyTier 字段是必填字段。

如果地址标识符不完整（例如缺少 postalCode 字段），则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "address": {
        "locality": "Sunnyvale",
        "administrativeArea": "CA",
        "regionCode": "US"
      }
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API 返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

原因：虽然提供了地址，但缺少必需的 postalCode 字段，因此不被视为有效标识符。

如果您请求的层级指数超出配置的计划的范围，则会发生错误：

场景：商家在 Merchant Center 中仅配置了一个层级。

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 100
  }
}

API 返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.loyalty_tier",
          "PATTERN": "valid LoyaltyTier",
          "FIELD_VALUE": "TIER2",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

原因：请求了 TIER2，但与账号关联的会员计划未定义第二层级。

如果请求包含格式错误的 emailAddress，则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@google"
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API 返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

原因：电子邮件地址格式无效。

如果 userIdentifier 对象为空，则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {},
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API 返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.user_identifier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

原因：userIdentifier 对象存在，但不包含实际的标识符字段。

有关标识符验证的注意事项：

该 API 会对标识符执行基本格式检查（例如，电子邮件结构、地址中是否存在 postalCode）。
不过，有些通过初始检查的标识符可能与任何 Google 用户账号都不匹配，或者可能采用后端匹配系统无法识别的格式。在这种情况下，您将收到 HTTP 状态为 200 OK 的静默成功空响应 {}。

最佳做法

请遵循以下最佳实践来优化集成。

对于大规模集成：由于该 API 是按请求运行的，因此需要客户端并行化才能实现大型数据集所需的吞吐量。您应设计集成来管理多个并发请求。如需了解如何通过并行化来处理更大量的数据，请参阅我们关于如何发送多个请求的指南。
配额管理：默认配额为每天 1,000,000 次请求和每分钟 10,000 次请求。如需了解如何监控和检查配额，请参阅配额和限制。
优先使用电子邮件地址：尽可能在 userIdentifier 中添加客户的 emailAddress。电子邮件地址通常是用于将用户与其 Google 账号进行匹配的最准确可靠的标识符。
处理空响应：设计应用以正确将空 {} 响应解读为成功，并了解这意味着由于隐私原因（没有匹配的数据或未征得同意），数据未存储。不重试请求。
验证会员等级顺序：请务必在 Merchant Center 界面中确认会员等级的顺序，以确保您在 API 调用中使用了正确的 TIER1 到 TIER7 枚举值。此映射基于界面中定义的顺序，而不是名称。
监控错误：记录并监控 API 响应，注意任何 4xx 错误，以便发现集成问题，尤其是 404 错误，这类错误可能表明层级理解不一致。

“会员目标客户匹配”服务概览 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

主要概念

前提条件

方法：ManageLoyaltyCustomerMatch

了解 loyaltyTier 映射

了解 ManageLoyaltyCustomerMatch 响应正文

有关可能回答的重要注意事项：

示例

错误处理

错误示例

最佳做法

“会员目标客户匹配”服务概览

方法：`ManageLoyaltyCustomerMatch`

了解 `loyaltyTier` 映射