Merchant API phiên bản v1beta đã ngừng hoạt động và ngừng cung cấp từ ngày 28 tháng 2 năm 2026. Để biết các bước chuyển đổi sang phiên bản ổn định mới nhất, hãy xem phần Di chuyển từ v1beta sang v1.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Tổng quan về Dịch vụ So khớp khách hàng trong chương trình khách hàng thân thiết

Hướng dẫn này mô tả cách sử dụng Dịch vụ so khớp khách hàng thân thiết trong Merchant API. Dịch vụ này cho phép người bán quản lý dữ liệu về chương trình khách hàng thân thiết, chẳng hạn như thông tin về cấp bậc và giá trị nhận dạng người dùng, để cá nhân hoá tự nhiên trên Google Tìm kiếm mà không cần có tài khoản Google Ads đang hoạt động.

Tổng quan

Sử dụng Dịch vụ So khớp khách hàng thân thiết để tải dữ liệu khách hàng thân thiết lên. Sau đó, dữ liệu này sẽ được dùng để cung cấp các tính năng cá nhân hoá tự nhiên trong chương trình khách hàng thân thiết trên Google Tìm kiếm, chẳng hạn như hiển thị mức giá dành riêng cho thành viên. Bạn sử dụng phương thức tuỳ chỉnh ManageLoyaltyCustomerMatch để liên kết khách hàng với các cấp độ của chương trình khách hàng thân thiết, cho phép bạn chèn, cập nhật hoặc xoá trạng thái khách hàng thân thiết của họ dựa trên giá trị nhận dạng người dùng.

Khái niệm chính

Giao diện hợp nhất: Một điểm cuối duy nhất để thêm, cập nhật hoặc xoá thông tin chi tiết về cấp độ khách hàng thân thiết.
Thiết kế ưu tiên quyền riêng tư: Để bảo vệ quyền riêng tư của người dùng và ngăn chặn hành vi dò xét tài khoản trái phép, API này không hỗ trợ các thao tác GET hoặc LIST, đảm bảo rằng dữ liệu được quản lý mà không cần truy xuất hoặc kiểm tra.
Nhận dạng linh hoạt: So khớp người dùng bằng ít nhất một giá trị nhận dạng hợp lệ, chẳng hạn như địa chỉ email, địa chỉ thực tế hoặc số điện thoại.
Xử lý dựa trên sự đồng ý: Dịch vụ chỉ lưu trữ và sử dụng dữ liệu khách hàng khi người dùng cuối đã cấp sự đồng ý cần thiết cho Google. Để bảo vệ và ngăn chặn việc thăm dò sự tồn tại của tài khoản hoặc trạng thái đồng ý, dịch vụ sẽ trả về trạng thái thành công thầm lặng nếu không tìm thấy kết quả trùng khớp hoặc người dùng không đồng ý.

Điều kiện tiên quyết

Hãy tuân thủ các yêu cầu sau để sử dụng Dịch vụ So khớp khách hàng thân thiết:

Thiết lập tài khoản: Đảm bảo bạn có một tài khoản Merchant Center đang hoạt động. Bạn không cần tạo tài khoản Google Ads để sử dụng Dịch vụ so khớp khách hàng trong chương trình khách hàng thân thiết.
Cấu hình chương trình khách hàng thân thiết: Bật chương trình khách hàng thân thiết trong tài khoản Merchant Center và đảm bảo rằng bạn đã xác định các cấp của chương trình khách hàng thân thiết.
Nhận biết thứ tự cấp: Nhận biết thứ tự mà các cấp khách hàng thân thiết của bạn được xác định trong giao diện người dùng Merchant Center. API này sử dụng chính xác trình tự này để liên kết enum.

Phương thức: `ManageLoyaltyCustomerMatch`

Phương thức ManageLoyaltyCustomerMatch đóng vai trò là giao diện trung tâm để quản lý các mối liên kết về chương trình khách hàng thân thiết. Dựa trên thông tin đầu vào được cung cấp, dịch vụ sẽ tự động xác định xem có nên chèn, cập nhật hay xoá trạng thái cấp độ khách hàng thân thiết của khách hàng hay không. Thao tác này là đẳng phương: các yêu cầu giống hệt nhau lặp lại sẽ có cùng hiệu ứng như một yêu cầu duy nhất.

Yêu cầu sau đây minh hoạ cách quản lý mối liên kết với chương trình khách hàng thân thiết thông qua API:

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

Yêu cầu này xác định các tham số bắt buộc sau đây về đường dẫn:

api_version: Phiên bản API, chẳng hạn như v1.
account_id: Mã tài khoản Merchant Center.

Thêm một đối tượng loyaltyCustomer vào nội dung yêu cầu.

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

các trường loyaltyCustomer

userIdentifier: Nhóm giá trị nhận dạng được dùng để so khớp khách hàng. Bạn phải cung cấp ít nhất một trường hợp lệ trong userIdentifier.
loyaltyTier: Bậc khách hàng thân thiết cần liên kết với khách hàng. Ánh xạ đến thứ tự của cấp trong chế độ thiết lập Merchant Center. Để biết thông tin chi tiết, hãy xem phần Tìm hiểu về việc lập bản đồ loyaltyTier. Sử dụng NON_MEMBER để xoá mối liên kết hiện có.
pointBalance: Số dư điểm hiện tại của khách hàng.

Trường userIdentifier

Bạn phải cung cấp ít nhất một trong các trường sau:

emailAddress: Địa chỉ email của khách hàng.
address: Địa chỉ thực tế của khách hàng. Bạn phải nhập PostalCode.
phoneNumber: Số điện thoại của khách hàng. Bạn nên dùng định dạng E.164.

Tìm hiểu về việc liên kết `loyaltyTier`

API này không sử dụng tên tuỳ chỉnh. Các giá trị enum loyaltyTier (từ TIER1 đến TIER7) là nhãn ngữ nghĩa. Họ không sử dụng tên tuỳ chỉnh (ví dụ: "Phần thưởng vàng") hoặc nhãn tuỳ chỉnh (ví dụ: "gold_tier") mà bạn đã chỉ định trong giao diện người dùng Merchant Center. Thay vào đó, các cấp này sẽ liên kết chặt chẽ với thứ tự mà bạn đã xác định các cấp trong chế độ cài đặt chương trình khách hàng thân thiết trong Merchant Center:

TIER1: Tương ứng với cấp đầu tiên được liệt kê trong cấu hình chương trình khách hàng thân thiết của bạn trong Merchant Center.
TIER2: Tương ứng với cấp thứ hai được liệt kê trong cấu hình chương trình khách hàng thân thiết của bạn trong Merchant Center.
TIER3 đến TIER7: Tương ứng với cấp thứ 3 đến cấp thứ 7 trong cấu hình chương trình khách hàng thân thiết của bạn trên Merchant Center.

Ví dụ:

Nếu chương trình khách hàng thân thiết của bạn trong Merchant Center có các cấp được xác định theo thứ tự sau:

Tên cấp: "Trạng thái bạc", Nhãn cấp: "bạc"
Tên cấp: "Thành viên vàng", Nhãn cấp: "gold"
Tên cấp: "Platinum Elite", Nhãn cấp: "platinum"

Sau đó, trong các lệnh gọi API accounts.loyaltyCustomers.manage:

Để chỉ định một khách hàng có "Trạng thái bạc", bạn phải sử dụng loyaltyTier: TIER1.
Để chỉ định một khách hàng là "Thành viên vàng", bạn phải sử dụng loyaltyTier: TIER2.
Để chỉ định một khách hàng là "Platinum Elite", bạn phải sử dụng loyaltyTier: TIER3.

Giá trị enum LoyaltyTier

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER (Dùng để báo hiệu việc xoá mối liên kết của khách hàng với chương trình khách hàng thân thiết)

Tìm hiểu về nội dung phản hồi ManageLoyaltyCustomerMatch

Phương thức ManageLoyaltyCustomerMatch trả về một đối tượng ManageLoyaltyCustomerMatchResponse:

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

Những điểm quan trọng cần cân nhắc về các câu trả lời có thể có:

Upsert thành công (dữ liệu được lưu trữ): Để lưu trữ hoặc cập nhật thành công mối liên kết giữa khách hàng và cấp độ khách hàng thân thiết, hãy đáp ứng các điều kiện sau:
- bạn so khớp một người dùng Google với userIdentifier được cung cấp
- bạn đặt loyaltyTier trong yêu cầu thành một giá trị hợp lệ khác với NON_MEMBER
- người dùng được so khớp đã đồng ý với việc sử dụng dữ liệu khách hàng thân thiết

Phản hồi chứa đối tượng loyaltyCustomer trong yêu cầu của bạn, cho biết dữ liệu đã được xử lý và lưu trữ thành công:

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

Xoá thành công: Để xoá thành công mọi mối liên kết hiện có giữa khách hàng và chương trình khách hàng thân thiết của người bán này, bạn phải đáp ứng các điều kiện sau:
- bạn so khớp một người dùng Google với userIdentifier được cung cấp
- bạn đặt loyaltyTier trong yêu cầu thành NON_MEMBER

Phản hồi là một đối tượng JSON trống:

{}

Không khớp / không đồng ý (thành công âm thầm): Nếu userIdentifier được cung cấp không khớp với Tài khoản Google hoặc nếu người dùng khớp chưa đồng ý sử dụng dữ liệu khách hàng thân thiết, thì API sẽ trả về trạng thái HTTP 200 OK với một đối tượng JSON trống: {}. Điều này xảy ra cho cả các lần thử chèn và xoá.

Ví dụ

TIER1 tương ứng với cấp đầu tiên được xác định của người bán, cấp này có tên là "Cơ bản" và TIER2 tương ứng với cấp thứ hai của họ – "Cao cấp"

Để thêm khách hàng vào TIER2 hoặc cập nhật trạng thái của họ bằng địa chỉ email, hãy gửi yêu cầu sau:

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

Khi người dùng được ghép nối thành công và đã đồng ý, API sẽ trả về phản hồi sau:

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

Khi không có kết quả trùng khớp hoặc người dùng chưa đồng ý, API sẽ trả về phản hồi sau:

{}

Để xoá mối liên kết của khách hàng với chương trình khách hàng thân thiết bằng số điện thoại, hãy gửi yêu cầu sau:

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

Bất kể có bản ghi hay không, API đều trả về phản hồi thành công sau đây:

{}

Để thêm hoặc cập nhật khách hàng bằng nhiều giá trị nhận dạng, hãy gửi yêu cầu sau:

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

Phản hồi tương tự như ví dụ đầu tiên, tuỳ thuộc vào mức độ trùng khớp và sự đồng ý.

Xử lý lỗi

API này sử dụng các mã HTTP tiêu chuẩn. Sau đây là các chuỗi lỗi thường gặp:

Mã HTTP	Chuỗi lỗi	Nội dung mô tả
400	INVALID_ARGUMENT	Thiếu user_identifier hoặc loyalty_tier, hoặc giá trị nhận dạng bị trống.
401	UNAUTHENTICATED	Thông tin đăng nhập không hợp lệ hoặc bị thiếu.
403	PERMISSION_DENIED	Người dùng được xác thực không có quyền truy cập vào tài khoản Merchant Center được chỉ định.
404	NOT_FOUND	Nhãn phân cấp khách hàng thân thiết được chỉ định không có trong cấu hình của bạn.
412	FAILED_PRECONDITION	Bạn chưa định cấu hình chương trình khách hàng thân thiết trong tài khoản của mình.
429	RESOURCE_EXHAUSTED	Đã đạt đến hạn mức.

Các ví dụ về lỗi

Ví dụ về 404 NOT_FOUND:

Mọi yêu cầu hợp lệ đối với một mã tài khoản chưa được định cấu hình chương trình khách hàng thân thiết.