Merchant API (v1beta) 已於 2026 年 2 月 28 日終止服務並停用。如要瞭解如何改用最新穩定版，請參閱「從 v1beta 遷移至 v1」。

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：用於比對顧客的識別項組合。必須在 userIdentifier 中提供至少一個有效欄位。
loyaltyTier：要與顧客建立關聯的會員等級。對應至 Merchant Center 設定中的層級順序。詳情請參閱「瞭解 loyaltyTier 對應」。使用 NON_MEMBER 移除現有關聯。
pointBalance：顧客目前的點數餘額。

userIdentifier 欄位

您必須提供下列至少其中一項欄位資料：

emailAddress：顧客的電子郵件地址。
address：顧客的實際地址。必須提供郵遞區號。
phoneNumber：顧客的電話號碼。建議使用 E.164 格式。

瞭解 `loyaltyTier` 對應

API 不會使用自訂名稱，loyaltyTier 列舉值 (TIER1 至 TIER7) 是語意標籤。系統不會使用你在 Merchant Center 使用者介面中指派的自訂名稱 (例如「黃金獎勵」) 或自訂標籤 (例如「gold_tier」)。而是嚴格對應你在 Merchant Center 會員方案設定中定義等級的順序：

TIER1：對應至 Merchant Center 會員方案設定中列出的第一個等級。
TIER2：對應於 Merchant Center 會員方案設定中列出的第二個等級。
TIER3 至 TIER7：對應 Merchant Center 會員方案設定中列出的第三至第七個等級。

範例：

如果 Merchant Center 會員方案的等級定義順序如下：

等級名稱：「銀級狀態」，等級標籤：「silver」
等級名稱：「黃金會員」，等級標籤：「gold」
等級名稱：「白金菁英」，等級標籤：「白金」

接著，在 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 物件：{}。無論是嘗試新增或更新，還是移除，都會發生這種情況。

範例

TIER1 對應於商家定義的第一個層級，也就是「基本」，TIER2 則對應於第二個層級，也就是「進階」

如要使用電子郵件地址將客戶新增至 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	未通過驗證	憑證無效或遺失。
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。一般來說，電子郵件地址是比對使用者與 Google 帳戶時，最準確可靠的 ID。
處理空白回應：設計應用程式時，請務必正確解讀空白 {} 回應，並瞭解這表示系統基於隱私權考量 (沒有相符項目或未取得同意聲明)，因此未儲存資料。請勿重試要求。
確認等級順序：請務必在 Merchant Center 使用者介面中確認會員等級的順序，確保在 API 呼叫中使用的 TIER1 至 TIER7 列舉值正確無誤。這項對應關係是根據 UI 中定義的順序，而非名稱。
監控錯誤：記錄及監控 API 回應，並注意任何 4xx 錯誤，以找出整合問題，尤其是 404 錯誤，這可能表示對層級的理解不一致。

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

總覽

核心概念

必要條件

方法：ManageLoyaltyCustomerMatch

瞭解 loyaltyTier 對應

瞭解 ManageLoyaltyCustomerMatch 回應主體

可能的回覆內容重要事項：

範例

處理錯誤

錯誤範例

最佳做法

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

方法：`ManageLoyaltyCustomerMatch`

瞭解 `loyaltyTier` 對應