중요: Content API for Shopping은 2026년 8월 18일에 지원 종료됩니다.

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인지 나타냅니다.
지원되는 지역: 판매자 포인트 멤버십은 대한민국, 네덜란드, 독일, 멕시코, 미국, 브라질, 스페인, 영국, 오스트레일리아, 이탈리아, 인도, 캐나다, 프랑스를 비롯한 지원되는 국가에서 사용할 수 있습니다.
등급 요건: 등급은 가입 비용이 없거나, 멤버십 수수료가 필요하거나, 지출 기준이 필요하거나, 판매자 브랜드 신용카드가 필요할 수 있습니다. 직업 기반 등급 (예: 학생 또는 군인 등급)은 지원되지 않습니다.
혜택: 프로그램은 무료 배송, 사용 가능한 포인트, 회원 가격을 지원합니다. 광고에서 회원 가격을 표시하려면 정상가 또는 할인가보다 5% 또는 5단위 통화 이상 할인되어야 합니다.

기본 요건

Merchant API로 포인트 멤버십을 관리하기 전에 다음 요구사항을 충족해야 합니다.

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

다음은 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

메서드

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

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 참조를 참고하세요.

Manage customer loyalty data

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

주요 개념

기본 요건

HTTP

cURL

메서드

포인트 멤버십 만들기

HTTP

포인트 멤버십 가져오기

HTTP

포인트 멤버십 목록

HTTP

포인트 멤버십 업데이트

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

HTTP

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

HTTP

포인트 멤버십 삭제

HTTP

다음 단계

포인트 멤버십 개요