이 페이지는 Cloud Translation API를 통해 번역되었습니다.

판매자 프로모션 API 개요

프로모션을 사용하여 Google에서 판매하는 제품의 특별 이벤트를 표시하세요. 프로모션은 Google 검색, 쇼핑, Chrome 등 다양한 Google 서비스에 표시됩니다. 프로모션이 승인되려면 특정 기준을 충족해야 합니다. 자세한 내용은 프로모션 기준을 참고하세요.

제품에 프로모션을 추가하면 쇼핑객에게 특별 이벤트 링크가 표시됩니다. 예: '15% 할인' 또는 '무료 배송' 제품 링크를 사용하면 제품에 대한 관심을 끌고 쇼핑객의 구매를 유도할 수 있습니다. 모든 프로모션은 결제 또는 판매 시점에 적용됩니다.

자세한 내용은 프로모션 기본사항을 참고하세요.

기본 요건

프로모션을 표시하려면 먼저 비즈니스와 제품에 대한 구체적인 정보를 Google에 제공해야 합니다. 다음이 있어야 합니다.

Google 판매자 센터에 활성 제품 피드가 있어야 합니다.
Google 판매자 센터에 활성 프로모션 피드가 있어야 합니다.
쇼핑 캠페인용 Google Ads 계정

또한 프로모션 프로그램에 판매자 계정을 등록해야 합니다. 이미 등록되었는지 확실하지 않다면 판매자 센터를 확인하세요.

등록하지 않은 경우 요청 양식을 작성합니다. 구현할 준비가 되면 프로모션팀에서 알려 드립니다.

자세한 내용은 참여 기준 및 정책을 참고하세요.

데이터 소스 만들기

accounts.dataSources.create 메서드를 사용하여 프로모션 데이터 소스를 만들 수 있습니다. 기존 프로모션 데이터 소스를 사용할 수 있는 경우 accounts.dataSources.list 메서드를 사용하여 모든 데이터 소스를 가져옵니다. 그런 다음 프로모션 데이터 소스의 name 필드를 사용하여 프로모션을 만듭니다.

다음 요청은 프로모션을 추가하기 위한 데이터 소스를 만드는 방법을 보여줍니다.

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

다음을 바꿉니다.

{ACCOUNT_ID}: 판매자 센터 UI에 표시되는 계정의 고유 식별자입니다.
{DISPLAY_NAME}: 데이터 소스의 표시 이름입니다.
{CONTENT_LANGUAGE}: 데이터 소스의 제품에 대한 두 글자 ISO 639-1 언어 코드입니다.
{TARGET_COUNTRY}: 프로모션을 표시할 대상 국가의 CLDR 지역 코드입니다.

요청이 실행되면 새로 만든 프로모션 데이터 소스에 관한 세부정보가 포함된 다음 응답이 표시됩니다.

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

프로모션 만들기

accounts.promotions.insert 메서드를 사용하여 프로모션을 만들거나 업데이트할 수 있습니다. accounts.promotions.insert 메서드는 promotions 리소스와 데이터 소스 이름을 입력으로 사용합니다. 성공하면 새 프로모션 또는 업데이트된 프로모션을 반환합니다.

프로모션을 만들려면 데이터 소스의 이름이 필요합니다. 요청에 다음 필드의 값도 제공해야 합니다.

contentLanguage
redemptionChannel
promotionId
targetCountry
attributes.offerType
attributes.genericRedemptionCode
attributes.couponValueType
attributes.productApplicability
attributes.promotionEffectiveTimePeriod.endTime
attributes.promotionEffectiveTimePeriod.startTime
attributes.longTitle

Google에서는 프로모션을 검토하고 승인한 다음 배포합니다. 자세한 내용은 프로모션 승인 절차를 참고하세요.

프로모션 정책을 검토하여 만드는 프로모션이 가치를 더하고 쇼핑 광고 정책을 준수하는지 확인하는 것이 좋습니다.

다음 요청은 온라인 프로모션을 만드는 방법을 보여줍니다.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

프로모션 ID 설정에 적용되는 규칙에 대한 자세한 내용은 프로모션 ID 속성의 최소 요구사항을 참고하세요.

필수 offerType 필드의 유효한 값은 NO_CODE 및 GENERIC_CODE입니다. 이러한 값 중 하나를 제공하지 않으면 API 요청이 HTTP 400 응답 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type과 함께 실패합니다. 필수 입력란을 제공하지 않으면 유사한 오류 메시지가 반환됩니다.

attributes.genericRedemptionCode 필드의 값을 제공하지 않으면 HTTP 400 응답 [genericRedemptionCode] No redemption code provided과 함께 요청이 실패합니다.

promotion.attributes.promotionDisplayTimePeriod.startTime 및 promotion.attributes.promotionDisplayTimePeriod.endTime 필드의 값은 yyyy-mm-ddThh:mm:ssZ 형식이어야 합니다. 이러한 입력란의 값을 미래 날짜로 바꿔야 합니다.

자세한 내용은 프로모션 데이터 사양을 참고하세요.

프로모션 만들기 권장사항은 프로모션 권장사항을 참고하세요.

프로모션 관련 속성 목록은 구조화된 데이터 속성 추가를 참고하세요.

프로모션 생성 요청이 실행되고 나서 API를 사용하여 프로모션을 검색하거나 판매자 센터에 표시되기까지 몇 분 정도 걸릴 수 있습니다.

다음은 시작하는 데 사용할 수 있는 샘플 프로모션입니다.

모든 제품 및 모든 매장에 적용되는 지역 프로모션

다음 샘플 요청은 판매자 센터 계정의 모든 제품과 연결된 비즈니스 프로필 계정에 추가된 모든 매장에 적용되는 오프라인 프로모션을 만드는 방법을 보여줍니다.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

productApplicability 필드는 필수 입력란입니다. 프로모션이 모든 제품에 적용되는지 아니면 특정 제품에만 적용되는지를 나타냅니다. 지원되는 값은 ALL_PRODUCTS 및 SPECIFIC_PRODUCTS입니다. 자세한 내용은 프로모션할 제품 선택하기를 참고하세요.

couponValueType 필드는 필수 입력란입니다. 운영 중인 프로모션 유형을 나타냅니다. 지원되는 값 목록은 쿠폰 값 유형을 참고하세요. 선택한 쿠폰 값 유형에 따라 일부 속성은 필수입니다.

minimumPurchaseQuantity 필드를 사용하면 프로모션 혜택을 사용하려면 필요한 최소 구매 수량의 값을 설정할 수 있습니다. 자세한 내용은 프로모션 최소 구매 수량을 참고하세요.

마찬가지로 minimumPurchaseAmount 필드를 사용하여 프로모션을 사용하려면 필요한 최소 구매 금액을 설정할 수 있습니다. 자세한 내용은 최소 구매 금액을 참고하세요.

오프라인 프로모션을 만들 때 제공해야 하는 값에 관한 자세한 내용은 오프라인 프로모션의 데이터 소스 사양을 참고하세요.

쿠폰 사용 코드가 있는 일부 제품에 적용되는 온라인 프로모션

다음 샘플 요청은 일부 제품에 적용되는 온라인 프로모션을 사용 코드와 함께 만드는 방법을 보여줍니다.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

프로모션 보기

프로모션을 보려면 accounts.promotions.get를 사용합니다. 이 GET 요청은 읽기 전용입니다. merchantId 및 프로모션 ID가 필요합니다. GET 메서드는 상응하는 프로모션 리소스를 반환합니다.

예를 들면 다음과 같습니다.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

다음을 바꿉니다.

{ACCOUNT_ID}: 판매자 센터 계정의 고유 식별자입니다.
{PROMOTION_ID}: 가져오려는 프로모션의 고유 식별자입니다. 형식은 {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}입니다.

새로 만든 프로모션을 API를 사용하여 검색할 수 있기까지 몇 분 정도 걸립니다.

지역 프로모션 보기

다음 샘플 요청은 프로모션 ID가 in_store~en~US~buy_2_get_10_off인 지역 프로모션을 가져옵니다.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

요청이 성공하면 다음과 같은 응답이 표시됩니다.

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

이 샘플의 moneyOffAmount 필드는 프로모션에서 제공되는 할인을 제공합니다. 자세한 내용은 프로모션의 금액 할인 금액을 참고하세요.

이 샘플의 promotionUrl 필드는 쇼핑객이 프로모션에 대한 자세한 정보를 확인할 수 있는 매장 웹사이트로 연결되는 링크를 제공합니다. promotionUrl 필드를 포함하지 않으면 오프라인 판매점 인벤토리 광고 프로모션에서 오류가 반환됩니다.

온라인 프로모션 보기

다음 샘플 요청은 프로모션 ID가 online~en~US~25_pct_off인 온라인 프로모션을 가져옵니다.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

이 샘플에서 사용된 itemIdInclusion 필드는 프로모션 대상 제품을 언급합니다. 자세한 내용은 프로모션용 제품 ID를 참고하세요.

프로모션 목록

promotions.list 메서드를 사용하여 생성된 모든 프로모션을 볼 수 있습니다.

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

응답에는 계정의 모든 프로모션 목록이 포함됩니다. 각 프로모션의 promotionId, redemptionChannel, dataSource, promotionStatus 등의 세부정보를 확인할 수 있습니다.

프로모션 상태 보기

프로모션 상태를 확인하려면 promotions.get 또는 promotions.list 메서드에서 반환된 promotionStatus 속성을 참고하세요.

promotionStatus 필드는 다음 값을 가질 수 있습니다.

IN_REVIEW: 아직 프로모션이 검토 중입니다.
REJECTED: 프로모션이 비승인되었습니다.
LIVE: 프로모션이 승인되어 활성 상태입니다.
STOPPED: 계정에서 프로모션을 중지했습니다.
EXPIRED: 프로모션이 더 이상 활성 상태가 아닙니다.
PENDING: 프로모션이 중지되지 않았고 모든 검토가 승인되었지만 활성일이 향후입니다.
STATE_UNSPECIFIED: 알 수 없는 프로모션 상태입니다.

내가 만든 프로모션의 승인 절차를 알아보려면 프로모션 승인 절차를 참고하세요.

샘플 프로모션 상태

다음 샘플은 성공적인 요청과 실패한 요청의 차이를 보여줍니다.

제품 매핑 누락

다음 응답 본문에는 제품 매핑 누락으로 인해 비승인된 온라인 프로모션이 표시됩니다.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

비승인된 프로모션 문제를 해결하고 향후 비승인을 방지하는 방법을 알아보려면 비승인된 프로모션 문제 해결하기를 참고하세요.

내가 만든 프로모션이 승인되지 않으면 거부 사유와 문제를 해결하는 방법이 안내된 이메일이 전송됩니다.

평가 중인 프로모션

다음 응답 본문에는 아직 평가 중인 프로모션이 표시됩니다.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

승인되어 진행 중인 프로모션

다음 응답 본문에는 쇼핑객에게 표시되는 프로모션이 표시됩니다.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

자세한 내용은 프로모션 상태 FAQ를 참고하세요.

자세히 알아보기

자세한 내용은 프로모션 고객센터를 참고하세요.
일반적인 문제를 해결하려면 Merchant Promotions API와 관련된 문제 해결하기를 참고하세요.
Content API for Shopping에서 이전하는 방법을 알아보려면 프로모션 관리 이전을 참고하세요.