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 中使用 Loyalty Customer Match Service。借助此服务，商家可以管理客户忠诚度数据（例如用户标识符和层级信息），以便在 Google 搜索中实现自然个性化，而无需拥有有效的 Google Ads 账号。

概览

您可以使用 Loyalty Customer Match Service 上传忠诚度数据，这些数据随后会用于在 Google 搜索中提供自然忠诚度个性化功能，例如显示会员专属价格。您可以使用 ManageLoyaltyCustomerMatch 自定义方法将客户与会员回馈活动层级相关联，以便根据用户标识符插入、更新或移除客户的忠诚度状态。

主要概念

统一界面：用于添加、更新或移除客户忠诚度层级详细信息的唯一端点。
隐私至上设计：为了保护用户隐私并防止未经授权的账号探测，该 API 不支持 GET 或 LIST 操作，确保在不检索或审核数据的情况下管理数据。
灵活的身份识别：使用至少一个有效标识符（例如电子邮件地址、实际地址或电话号码）匹配用户。
基于意见征求的处理：只有在最终用户向 Google 授予必要的意见征求后，该服务才会存储和使用客户数据。为了保护账号并防止账号存在探测或意见征求状态，该服务会返回静默成功，如果未进行匹配或未授予意见征求。

前提条件

如需使用 Loyalty Customer Match Service，请满足以下要求：

账号设置 ：确保您拥有有效的 Merchant Center 账号。您无需创建 Google Ads 账号即可使用 Loyalty Customer Match Service。
会员回馈活动配置：在 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 会员回馈活动按以下顺序定义了层级：

层级名称：“白银身份”，层级标签：“silver”
层级名称：“黄金会员”，层级标签：“gold”
层级名称：“铂金精英”，层级标签：“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（数据已存储） ：如需成功存储或更新客户的忠诚度层级关联，请满足以下条件：
- 您将 Google 用户 与提供的 userIdentifier 相匹配
- 您将请求中的 loyaltyTier 设置为 NON_MEMBER 以外的有效值
- 匹配的用户已同意 使用忠诚度数据

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

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

成功删除 ：如需成功移除客户与此商家之间的任何现有忠诚度关联，必须满足以下条件：
- 您将 Google 用户 与提供的 userIdentifier 相匹配
- 您将请求中的 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` 映射