이 가이드에서는 Merchant API에서 포인트 고객 일치 서비스를 사용하는 방법을 설명합니다. 이 서비스를 통해 판매자는 활성 Google Ads 계정 없이도 Google 검색의 자연 검색 결과를 개인화하기 위한 사용자 식별자 및 등급 정보와 같은 고객 충성도 데이터를 관리할 수 있습니다.
개요
포인트 멤버십 고객 일치 타겟팅 서비스를 사용하여 포인트 멤버십 데이터를 업로드합니다. 이 데이터는 회원별 가격 표시와 같은 Google 검색의 자연 포인트 멤버십 맞춤설정 기능을 제공하는 데 사용됩니다. ManageLoyaltyCustomerMatch 맞춤 메서드를 사용하여 고객을 포인트 멤버십 등급과 연결하면 사용자 식별자를 기반으로 포인트 멤버십 상태를 삽입, 업데이트 또는 삭제할 수 있습니다.
주요 개념
- 통합 인터페이스: 고객 포인트 등급 세부정보를 추가, 업데이트 또는 삭제하는 고유 엔드포인트입니다.
- 개인 정보 보호 우선 설계: 사용자 개인 정보를 보호하고 무단 계정 조사를 방지하기 위해 API는 GET 또는 LIST 작업을 지원하지 않으므로 검색이나 감사 없이 데이터가 관리됩니다.
- 유연한 식별: 이메일 주소, 실제 주소, 전화번호와 같은 유효한 식별자를 하나 이상 사용하여 사용자를 일치시킵니다.
- 동의 기반 처리: 서비스는 최종 사용자가 필요한 Google 동의를 부여한 경우에만 고객 데이터를 저장하고 사용합니다. 계정 존재 여부 확인 또는 동의 상태를 보호하고 방지하기 위해 서비스는 일치하는 항목이 없거나 동의가 부여되지 않은 경우 자동 성공을 반환합니다.
기본 요건
로열티 고객 일치 타겟팅 서비스를 사용하려면 다음 요구사항을 따라야 합니다.
- 계정 설정: 활성 상태의 판매자 센터 계정이 있어야 합니다. 충성도 고객 매치 타겟팅 서비스를 사용하기 위해 Google Ads 계정을 만들 필요는 없습니다.
- 포인트 멤버십 구성: 판매자 센터 계정에서 포인트 멤버십을 사용 설정하고 포인트 멤버십 등급을 정의했는지 확인합니다.
- 등급 순서 인식: 판매자 센터 UI에서 포인트 멤버십 등급이 정의된 순서를 파악합니다. API는 enum 매핑에 이 정확한 시퀀스를 사용합니다.
메서드: ManageLoyaltyCustomerMatch
ManageLoyaltyCustomerMatch 메서드는 고객 충성도 연결을 관리하는 중앙 인터페이스 역할을 합니다. 제공된 입력을 기반으로 서비스는 고객의 포인트 등급 상태를 삽입, 업데이트 또는 삭제할지 여부를 자동으로 결정합니다. 이 작업은 멱등성을 갖습니다. 동일한 요청을 반복해도 단일 요청과 동일한 효과가 있습니다.
다음 요청은 API를 통해 고객 충성도 연결을 관리하는 방법을 보여줍니다.
POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage
이 요청은 다음 필수 경로 매개변수를 정의합니다.
api_version: API 버전입니다(예: v1).account_id: 판매자 센터 계정 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: 고객과 연결할 포인트 등급입니다. 판매자 센터 설정의 등급 순서에 매핑됩니다.
자세한 내용은
loyaltyTier매핑 이해를 참고하세요. 기존 연결을 삭제하려면 NON_MEMBER를 사용합니다. - pointBalance: 고객의 현재 포인트 잔액입니다.
userIdentifier 필드
다음 필드 중 하나 이상을 입력해야 합니다.
- emailAddress: 고객의 이메일 주소입니다.
- address: 고객의 실제 주소입니다. PostalCode는 필수 항목입니다.
- phoneNumber: 고객의 전화번호입니다. E.164 형식을 사용하는 것이 좋습니다.
loyaltyTier 매핑 이해
API는 맞춤 이름을 사용하지 않습니다. loyaltyTier enum 값 (TIER1~TIER7)은 시맨틱 라벨입니다. 판매자 센터 UI에서 할당한 맞춤 이름 (예: '골드 리워드') 또는 맞춤 라벨 (예: 'gold_tier')을 사용하지 않습니다. 대신 판매자 센터의 포인트 멤버십 설정에서 등급을 정의한 순서에 따라 엄격하게 매핑됩니다.
TIER1: 판매자 센터 포인트 멤버십 구성에 나열된 첫 번째 등급에 해당합니다.TIER2: 판매자 센터 포인트 멤버십 구성에 나열된 두 번째 등급에 해당합니다.TIER3~TIER7: 판매자 센터 포인트 멤버십 구성에 나열된 3~7등급에 해당합니다.
예:
판매자 센터 포인트 멤버십에 다음과 같은 순서로 등급이 정의되어 있는 경우
- 등급 이름: '실버 등급', 등급 라벨: 'silver'
- 등급 이름: '골드 회원', 등급 라벨: 'gold'
- 등급 이름: 'Platinum Elite', 등급 라벨: 'platinum'
그런 다음 accounts.loyaltyCustomers.manage API 호출에서 다음을 수행합니다.
- 고객을 '실버 등급'에 할당하려면
loyaltyTier: TIER1를 사용해야 합니다. - 고객을 '골드 회원'에 할당하려면
loyaltyTier: TIER2를 사용해야 합니다. - 고객을 '플래티넘 엘리트'에 할당하려면
loyaltyTier: TIER3를 사용해야 합니다.
LoyaltyTier enum 값
TIER1TIER2TIER3TIER4TIER5TIER6TIER7NON_MEMBER(고객의 포인트 멤버십 연결 삭제를 알리는 데 사용됨)
ManageLoyaltyCustomerMatch 응답 본문 이해하기
ManageLoyaltyCustomerMatch 메서드는 ManageLoyaltyCustomerMatchResponse 객체를 반환합니다.
{
"loyaltyCustomer": {
// loyaltyCustomer object from the request
}
}
가능한 대답에 관한 중요 고려사항:
성공적인 삽입/업데이트 (데이터 스토어): 고객의 충성도 등급 연결을 성공적으로 저장하거나 업데이트하려면 다음 조건을 충족해야 합니다.
- 제공된
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는 빈 JSON 객체({})와 함께 HTTP 200 OK 상태를 반환합니다. 이 문제는 삽입/업데이트 시도와 삭제 시도 모두에서 발생합니다.
예
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 | 인증된 사용자에게 지정된 판매자 센터 계정에 대한 액세스 권한이 없습니다. |
| 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 필드는 필수입니다.
우편번호 필드가 누락된 경우와 같이 주소 식별자가 불완전하면 오류가 발생합니다.
{
"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 필드가 누락되어 유효한 식별자로 간주되지 않습니다.
구성된 프로그램의 범위를 벗어나는 등급 색인을 요청하면 오류가 발생합니다.
시나리오: 판매자가 판매자 센터에 하나의 등급만 구성했습니다.
{
"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 UI에서 항상 포인트 등급의 순서를 확인하여 API 호출에서 올바른
TIER1~TIER7enum 값을 사용하고 있는지 확인합니다. 이 매핑은 이름이 아닌 UI에 정의된 순서를 기반으로 합니다.오류 모니터링: API 응답을 로깅하고 모니터링하여
4xx오류를 파악하여 통합 문제를 포착합니다. 특히 등급 이해의 불일치를 나타낼 수 있는404오류에 주의하세요.