중요: Content API for Shopping은 2026년 8월 18일 에 지원 중단되었습니다.

2026년 9월 1일부터 Content API for Shopping 요청에 점진적인 오류가 발생합니다. Content API 지원 중단 가이드를 검토하세요.

Merchant API로 이전하는 데 추가 시간이 필요한 경우 Content API for Shopping에 대한 액세스 기간 연장을 신청하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

포인트 멤버십 개요

포인트 멤버십을 사용하여 Google에 매장 혜택을 표시하세요. 무료 배송, 포인트 적립, 회원 전용 가격 등 다양한 혜택을 제출할 수 있습니다. 포인트 멤버십 혜택은 Google 검색, 쇼핑 탭, Google 월렛을 비롯한 Google 서비스 전반의 무료 등록정보, 쇼핑 광고, 오프라인 판매점 인벤토리 광고에 표시될 수 있습니다.

판매자 API를 사용하면 판매자와 판매자를 대신하는 서드 파티 포인트 멤버십 제공업체가 LoyaltyProgramService를 사용하여 프로그래매틱 방식으로 포인트 멤버십을 구성하고 유지할 수 있습니다. 이 서비스를 사용하면 포인트 멤버십을 만들고, 검색하고, 나열하고, 업데이트하고, 삭제할 수 있습니다.

비즈니스 요구사항 및 정책 가이드라인에 대한 자세한 내용은 판매자 센터 고객센터의 판매자 포인트 멤버십 정보를 참고하세요.

주요 개념

포인트 멤버십을 사용할 때는 다음 개념과 제한사항에 유의하세요.

계정 수준 식별자: Merchant API는 소유 판매자 센터 계정 ID로 포인트 멤버십을 식별합니다.
단일 포인트 멤버십 한도: Merchant API는 판매자 계정당 하나의 포인트 멤버십만 지원합니다.
직접 계정 소유권: 포인트 멤버십은 대상 판매자 계정(accounts/{ACCOUNT_ID})에서 직접 구성해야 합니다. 이 서비스는 하위 계정의 고급 계정 수준에서 포인트 멤버십을 관리하는 것을 지원하지 않습니다. 판매자 계정에 대한 승인된 액세스 권한이 있는 서드 파티 포인트 멤버십 제공업체는 판매자를 대신하여 프로그램을 관리할 수 있습니다.
광고 소재 검토: 포인트 멤버십을 만들거나 업데이트하면 프로그램이 검토를 거칩니다. review_result.review_status 필드는 프로그램이 UNDER_REVIEW, APPROVED 또는 REJECTED인지 여부를 나타냅니다. 업데이트가 성공할 때마다 업데이트로 인해 중요한 변경사항이 없더라도 프로그램이 검토 대기열로 다시 전송됩니다. Google은 검토 과정에서 쇼핑객에게 프로그램을 숨깁니다. 검토에 최대 48시간이 걸릴 수 있습니다.
지원되는 지역: 판매자 포인트 멤버십은 대한민국, 네덜란드, 독일, 멕시코, 미국, 브라질, 스페인, 영국, 오스트레일리아, 이탈리아, 인도, 일본, 캐나다, 프랑스를 포함한 지원되는 국가에서 사용할 수 있습니다.
활성 지역: 포인트 멤버십의 regionCodes은 accounts/{ACCOUNT_ID}/programs/loyalty의 activeRegionCodes의 하위 집합이어야 합니다. 그렇지 않으면 생성, 업데이트, 삭제 요청이 LOYALTY_PROGRAM_DISABLED 오류와 함께 실패합니다. Google은 포인트 멤버십 부가기능이 사용 설정되어 있고 계정이 해당 국가의 자격 요건을 충족하는 경우 지원되는 국가를 활성화합니다. 예를 들어 무료 등록정보 프로그램이 사용 설정되어 있고 기본 제품 데이터 소스가 FREE_LISTINGS 대상의 국가를 타겟팅하는 경우 계정이 자격 요건을 충족합니다. 국가가 활성 상태가 아닌 이유를 알아보려면 활성 지역 확인을 참조하세요.
등급 요구사항: 등급은 가입 비용이 없거나, 멤버십 수수료가 필요하거나, 지출 기준액이 필요하거나, 판매자 브랜드 신용카드가 필요할 수 있습니다. 직업 기반 등급(예: 학생 또는 군인 등급)은 지원되지 않습니다.
혜택: 프로그램은 무료 배송, 사용 가능한 포인트, 회원 가격을 지원합니다. 광고에서 회원 가격은 정상가 또는 할인가보다 5% 또는 5통화 단위 이상 할인되어야 합니다.

기본 요건

Merchant API로 포인트 멤버십을 관리하기 전에 다음 요구사항을 충족하는지 확인하세요.

활성 상태의 판매자 센터 계정이 있어야 합니다(서드 파티 포인트 멤버십 제공업체인 경우 판매자 계정에 대한 승인된 액세스 권한이 있어야 함).
계정에서 포인트 멤버십 부가기능을 사용 설정합니다. 다음 옵션 중 하나를 사용하여 부가기능을 사용 설정할 수 있습니다.
- 판매자 센터 UI: 판매자 센터 도움말의 포인트 멤버십 설정 안내를 따릅니다.
- Programs 하위 API: Programs 하위 API에서 프로그램 사용 설정에 설명된 대로 프로그래매틱 방식으로 프로그램을 사용 설정합니다. accounts.programs.enable 메서드에는 관리자 액세스가 필요합니다.
포인트 멤버십을 제공하려는 국가가 계정에서 활성화되어 있어야 합니다. 활성 상태인 국가를 확인하려면 활성 리전 확인을 참조하세요.

다음은 Programs 하위 API를 사용하여 포인트 멤버십 부가기능을 사용 설정하는 요청 샘플입니다.

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

cURL

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

활성 리전 확인

포인트 멤버십 부가기능을 사용 설정한 후 accounts/{ACCOUNT_ID}/programs/loyalty의 accounts.programs.get 메서드를 호출합니다. 응답에는 포인트 멤버십을 사용할 수 있는 위치와 지원되는 다른 국가가 비활성 상태인 이유가 표시됩니다.

다음은 샘플 요청입니다.

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty

cURL

curl --request GET \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --compressed

{ACCOUNT_ID}를 판매자 센터 계정의 고유 식별자로 바꿉니다.

다음은 부가기능을 사용 설정했으며 미국에서만 사용할 수 있는 계정의 샘플 응답입니다.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}

이 응답에서 다음 필드를 확인합니다.

activeRegionCodes: 포인트 멤버십의 regionCodes에서 사용할 수 있는 국가입니다. 위 샘플에서는 US만 활성 상태입니다.
unmetRequirements: 지원되는 다른 국가가 비활성 상태인 이유입니다. 포인트 멤버십의 경우 IS_ELIGIBLE_FOR_LOYALTY 요구사항입니다.
- affectedRegionCodes: 계정이 지원되지 않는 국가
- documentationUri: 자격 요건 링크입니다.

위 샘플에서는 아직 affectedRegionCodes의 국가를 사용할 수 없습니다. 포인트 멤버십의 regionCodes에 이러한 문자가 포함된 경우 생성, 업데이트, 삭제 요청이 LOYALTY_PROGRAM_DISABLED 오류와 함께 실패합니다. 국가를 활성화하려면 다음을 수행합니다.

해당 국가에서 계정을 사용할 수 있도록 합니다. 예를 들어 무료 등록정보 프로그램을 사용 설정하고 FREE_LISTINGS 대상의 국가를 타겟팅하도록 기본 제품 데이터 소스를 설정합니다. 자격 요건을 충족하는 모든 방법은 자격 요건을 참조하세요.
accounts.programs.get를 다시 호출하고 국가가 activeRegionCodes에 있는지 확인합니다.

affectedRegionCodes에는 판매하지 않는 국가가 포함될 수 있습니다. 이러한 국가에 대해서는 별도의 조치를 취하지 않아도 됩니다. activeRegionCodes의 국가에는 영향을 미치지 않습니다.

메서드

다음 방법을 사용하여 포인트 멤버십을 관리합니다.

loyaltyPrograms.create
loyaltyPrograms.get
loyaltyPrograms.list
loyaltyPrograms.update
loyaltyPrograms.delete

포인트 멤버십 만들기

계정에 새 포인트 멤버십을 만들려면 loyaltyPrograms.create 메서드를 사용합니다. 포인트 멤버십 설명, 가입 URL, 포인트 멤버십 등급과 고유한 혜택 및 요구사항과 같은 세부정보를 지정합니다.

필수 program_label는 포인트 멤버십의 고유 식별자를 설정합니다. 예를 들어 my-rewards 라벨을 제공하면 accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards의 name 리소스가 생성됩니다.

다음은 샘플 요청입니다.

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

{ACCOUNT_ID}를 판매자 센터 계정의 고유 식별자로 바꿉니다.

다음은 성공적인 요청의 샘플 응답입니다.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

포인트 멤버십 가져오기

특정 자체 소유 포인트 멤버십의 세부정보를 가져오려면 loyaltyPrograms.get 메서드를 사용합니다.

다음은 샘플 요청입니다.

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{ACCOUNT_ID}를 계정 ID로 바꾸고 {PROGRAM_LABEL}를 포인트 멤버십의 고유 라벨(예: my-rewards)로 바꿉니다.

다음은 성공적인 요청의 샘플 응답입니다.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

포인트 멤버십 나열

계정과 연결된 모든 자체 소유 포인트 멤버십을 나열하려면 loyaltyPrograms.list 메서드를 사용합니다.

다음은 샘플 요청입니다.

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

다음은 성공적인 요청의 샘플 응답입니다.

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

포인트 멤버십 업데이트

기존 포인트 멤버십을 업데이트하려면 loyaltyPrograms.update 메서드를 사용합니다. update_mask을 사용하여 부분 업데이트를 수행하거나 마스크를 생략하여 전체 교체를 수행합니다. 업데이트가 성공할 때마다 새로운 편집 검토가 트리거되므로 값이 변경될 때만 업데이트를 전송하세요.

업데이트 마스크를 사용한 부분 업데이트

update_mask를 사용하면 업데이트할 정확한 필드를 지정할 수 있습니다. 마스크에 나열된 필드만 수정되고 나열되지 않은 필드는 변경되지 않습니다. 업데이트 마스크에서 생략된 필드는 요청 본문에 제공되더라도 무시됩니다.

다음 샘플 요청은 programDescriptions 및 advancedSettings만 업데이트합니다.

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

이 예시에서 서비스는 update_mask에 포함되지 않으므로 signupUrl를 무시합니다. programDescriptions 필드는 이전에 구성된 설명을 완전히 대체합니다.

다음은 성공적인 요청에 대한 샘플 응답입니다.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

업데이트 마스크 없이 전체 교체

update_mask 매개변수를 생략하면 요청은 포인트 멤버십 구성의 전체 교체를 수행합니다.

다음은 샘플 요청입니다.

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

다음은 성공적인 요청에 대한 샘플 응답입니다.

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

포인트 멤버십 삭제

계정에서 포인트 멤버십을 삭제하려면 loyaltyPrograms.delete 메서드를 사용합니다.

다음은 샘플 요청입니다.

HTTP

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

성공한 경우 응답 본문은 비어 있습니다.

다음 단계

Google 검색에서 자연스러운 맞춤설정을 위해 개별 쇼핑객을 포인트 멤버십 등급과 연결하려면 포인트 멤버십 고객 일치 타겟팅 서비스 가이드를 참고하세요.
계정의 쇼핑 프로그램을 사용 설정하거나 중지하려면 프로그램 하위 API 가이드를 참고하세요.
비즈니스 설정 세부정보, 광고 소재 정책, 보고에 관한 내용은 판매자 센터 도움말의 판매자 포인트 멤버십 정보를 참고하세요.
API 메서드 및 리소스 정의를 살펴보려면 Merchant API 참조를 확인하세요.

Overview

Manage customer loyalty data

포인트 멤버십 개요 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

주요 개념

기본 요건

HTTP

cURL

활성 리전 확인

HTTP

cURL

메서드

포인트 멤버십 만들기

HTTP

포인트 멤버십 가져오기

HTTP

포인트 멤버십 나열

HTTP

포인트 멤버십 업데이트

업데이트 마스크를 사용한 부분 업데이트

HTTP

업데이트 마스크 없이 전체 교체

HTTP

포인트 멤버십 삭제

HTTP

다음 단계

포인트 멤버십 개요