重要事項：Content API for Shopping 將於 2026 年 8 月 18 日終止服務。

如果需要更多時間遷移至 Merchant API，請申請延長 Content API for Shopping 的存取權。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

會員目標顧客比對服務總覽

本指南說明如何使用 Merchant API 中的會員目標顧客比對服務。這項服務可讓商家和代表商家的第三方會員方案供應商，管理顧客會員資料 (例如使用者 ID 和等級資訊)，在 Google 搜尋上提供自然個人化體驗，不需要有效的 Google Ads 帳戶。

總覽

使用會員目標顧客比對服務上傳會員資料，即可在 Google 搜尋上提供自然會員個人化功能，例如顯示會員專屬價格。您可以使用 ManageLoyaltyCustomerMatch 自訂方法，將顧客與會員方案等級建立關聯，以便根據使用者 ID 插入、更新或移除會員狀態。

核心概念

統一介面：用於新增、更新或移除顧客會員等級詳細資料的專屬端點。
隱私權優先設計：為保護使用者隱私，並防止未經授權的帳戶探查，API 不支援 GET 或 LIST 作業，確保資料管理時不會擷取或稽核。
彈性識別：使用至少一項有效 ID (例如電子郵件地址、實際地址或電話號碼) 比對使用者。
依據同意聲明處理：只有在使用者向 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：用於比對顧客的一組 ID。userIdentifier 內至少須提供一個有效欄位。
loyaltyTier：與顧客相關聯的會員等級。對應 Merchant Center 設定中的等級順序。詳情請參閱「瞭解 loyaltyTier 對應」。使用 NON_MEMBER 移除現有關聯。
pointBalance：顧客目前的點數餘額。

userIdentifier 欄位

請至少提供下列其中一項欄位：

emailAddress：顧客的電子郵件地址。
address：顧客的實際地址。必須提供郵遞區號。
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 Status"，等級標籤："silver"
等級名稱：Gold Member，等級標籤：gold
等級名稱："Platinum Elite"，等級標籤："platinum"

接著，在 accounts.loyaltyCustomers.manage API 呼叫中：

如要將客戶指派為「銀級狀態」，必須使用 loyaltyTier: TIER1。
如要將客戶指派給「黃金會員」，您必須使用 loyaltyTier: TIER2。
如要將客戶指派給「Platinum Elite」，則必須使用 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 都會傳回下列成功回應：

{}

如要使用多個 ID 新增或更新顧客，請傳送下列要求：

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，或 ID 為空白。
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 為必填欄位。

如果地址 ID 不完整 (例如缺少 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 欄位，因此無法視為有效 ID。

如果要求的級別索引超出設定方案的範圍，就會發生錯誤：

情境：商家在 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 物件存在，但不含實際 ID 欄位。

注意：ID 驗證。

API 會對 ID 執行基本格式檢查 (例如電子郵件結構、地址中是否有 postalCode)。
不過，部分通過初始檢查的 ID 可能與任何 Google 使用者帳戶都不相符，或格式不符合後端比對系統的規定。在這種情況下，您會收到空白回應 {}，表示作業成功，HTTP 狀態為 200 OK。

最佳做法

請按照下列最佳做法，充分發揮整合效益。

大規模整合：由於 API 是以個別要求為基礎運作，因此需要用戶端平行處理，才能達到大型資料集所需的處理量。請務必設計整合功能，以便管理多項並行要求。如要瞭解如何建構實作，透過平行處理處理大量資料，請參閱如何傳送多個要求指南。
配額管理：預設配額為每天 1,000,000 項要求和每分鐘 10,000 項要求。如要瞭解如何監控及查看配額，請參閱「配額與限制」。
優先提供電子郵件地址：請盡可能在 userIdentifier 中加入顧客的 emailAddress。一般來說，電子郵件地址是最準確可靠的 ID，可用來比對使用者與其 Google 帳戶。
處理空白回應：請將應用程式設計為正確解讀空白 {} 回應，並視為成功，瞭解這代表資料因隱私權原因 (不相符或未同意) 而未儲存。請勿重試要求。
確認等級順序：請務必在 Merchant Center 使用者介面中確認會員等級順序，確保在 API 呼叫中使用正確的 TIER1 到 TIER7 列舉值。這項對應是根據使用者介面中定義的順序，而非名稱。
監控錯誤：記錄並監控 API 回應，留意任何 4xx 錯誤，找出整合問題，尤其是 404 錯誤，這可能表示對等級的理解不一致。

Manage loyalty programs

會員目標顧客比對服務總覽 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

核心概念

必要條件

方法：ManageLoyaltyCustomerMatch

瞭解loyaltyTier對應

瞭解 ManageLoyaltyCustomerMatch 回應主體

回覆的重要注意事項

範例

錯誤處理

錯誤範例

最佳做法

會員目標顧客比對服務總覽

方法：`ManageLoyaltyCustomerMatch`

瞭解`loyaltyTier`對應