REST Resource: accounts.promotions

리소스: 프로모션

프로모션을 나타냅니다. 자세한 내용은 다음 도움말을 참고하세요.

데이터 유효성 검사를 통과하는 데 필요한 프로모션 입력 속성은 기본적으로 아래에 정의되어 있습니다.

프로모션 입력을 삽입하거나 업데이트한 후 최종 프로모션을 가져오는 데 몇 분 정도 걸릴 수 있습니다.

JSON 표현 
{
  "name": string,
  "promotionId": string,
  "contentLanguage": string,
  "targetCountry": string,
  "redemptionChannel": [
    enum (RedemptionChannel)
  ],
  "dataSource": string,
  "attributes": {
    object (Attributes)
  },
  "customAttributes": [
    {
      object (CustomAttribute)
    }
  ],
  "promotionStatus": {
    object (PromotionStatus)
  },
  "versionNumber": string
}
필드
name

string

식별자. 프로모션의 이름입니다. 형식: accounts/{account}/promotions/{promotion}
promotionId

string

필수입니다. 사용자가 프로모션을 고유하게 식별하기 위해 프로모션 ID를 제공했습니다. 최소 요구사항을 준수하여 프로모션 비승인을 방지하세요.
contentLanguage

string

필수입니다. 프로모션의 두 글자 ISO 639-1 언어 코드입니다.

프로모션은 일부 언어로만 제공됩니다.
targetCountry

string

필수입니다. 고유 식별자의 일부로 사용되는 대상 국가입니다. CLDR 지역 코드로 표시됩니다.

프로모션은 일부 국가의 무료 등록정보 및 쇼핑 광고 오프라인 판매점 인벤토리 광고에서만 사용할 수 있습니다.
redemptionChannel[]

enum (RedemptionChannel)

필수입니다. 프로모션의 사용 채널입니다. 채널이 하나 이상 필요합니다.
dataSource

string

출력 전용입니다. 프로모션의 기본 데이터 소스입니다.
attributes

object (Attributes)

선택사항입니다. 프로모션 속성 목록입니다.
customAttributes[]

object (CustomAttribute)

선택사항입니다. 맞춤 (판매자 제공) 속성 목록입니다. 데이터 사양의 속성을 일반 형식 (예: { "name": "size type", "value": "regular" })으로 제출하는 데도 사용할 수 있습니다. 이는 API에서 명시적으로 노출하지 않는 속성을 제출하는 데 유용합니다.
promotionStatus

object (PromotionStatus)

출력 전용입니다. 프로모션 상태, 데이터 유효성 검사 문제, 즉 비동기식으로 계산된 프로모션에 대한 정보입니다.
versionNumber

string (int64 format)

선택사항입니다. 프로모션의 기존 버전 (최신성)을 나타냅니다. 이 버전은 여러 업데이트가 동시에 실행될 때 올바른 순서를 유지하는 데 사용할 수 있습니다.

이 옵션을 설정하면 버전 번호가 기존 프로모션의 현재 버전 번호보다 낮은 경우 삽입이 방지됩니다. 현재 versionNumber를 사용하여 재삽입 (예: 30일 후 프로모션 새로고침)을 실행할 수 있습니다.

작업이 방지되면 중단된 예외가 발생합니다.

RedemptionChannel

프로모션 채널입니다.

열거형
REDEMPTION_CHANNEL_UNSPECIFIED 채널이 지정되지 않았음을 나타냅니다.
IN_STORE 채널이 매장에 있음을 나타냅니다. 이는 products에 사용되는 local 채널과 동일합니다.
ONLINE 채널이 온라인 상태임을 나타냅니다.

속성

속성

JSON 표현 
{
  "productApplicability": enum (ProductApplicability),
  "offerType": enum (OfferType),
  "genericRedemptionCode": string,
  "longTitle": string,
  "couponValueType": enum (CouponValueType),
  "promotionDestinations": [
    enum (DestinationEnum)
  ],
  "itemIdInclusion": [
    string
  ],
  "brandInclusion": [
    string
  ],
  "itemGroupIdInclusion": [
    string
  ],
  "productTypeInclusion": [
    string
  ],
  "itemIdExclusion": [
    string
  ],
  "brandExclusion": [
    string
  ],
  "itemGroupIdExclusion": [
    string
  ],
  "productTypeExclusion": [
    string
  ],
  "minimumPurchaseAmount": {
    object (Price)
  },
  "minimumPurchaseQuantity": string,
  "limitQuantity": string,
  "limitValue": {
    object (Price)
  },
  "percentOff": string,
  "moneyOffAmount": {
    object (Price)
  },
  "getThisQuantityDiscounted": string,
  "freeGiftValue": {
    object (Price)
  },
  "freeGiftDescription": string,
  "freeGiftItemId": string,
  "promotionEffectiveTimePeriod": {
    object (Interval)
  },
  "promotionDisplayTimePeriod": {
    object (Interval)
  },
  "storeApplicability": enum (StoreApplicability),
  "storeCodesInclusion": [
    string
  ],
  "storeCodesExclusion": [
    string
  ],
  "promotionUrl": string
}
필드
productApplicability

enum (ProductApplicability)

필수입니다. 프로모션이 모든 제품에 적용되는지 또는 특정 제품에만 적용되는지 여부입니다.
offerType

enum (OfferType)

필수입니다. 프로모션 유형입니다. 이 속성을 사용하여 고객이 프로모션을 적용받는 데 쿠폰 코드가 필요한지 여부를 표시합니다.
genericRedemptionCode

string

선택사항입니다. 프로모션의 일반 사용 코드입니다. offerType 필드와 함께 사용되며 최소 요구사항을 충족해야 합니다.
longTitle

string

필수입니다. 프로모션의 긴 제목입니다.
couponValueType

enum (CouponValueType)

필수입니다. 쿠폰 값 유형 속성을 사용하여 진행 중인 프로모션의 유형을 알립니다. 선택한 쿠폰 값 유형에 따라 일부 속성은 필수입니다.
promotionDestinations[]

enum (DestinationEnum)

필수입니다. 프로모션이 적용되는 대상의 목록입니다. 데이터 소스에 지원 값을 포함하여 대상 유형을 지정하지 않으면 기본적으로 프로모션이 쇼핑 광고와 무료 등록정보에 표시됩니다.

이전에는 제품의 대상 유형으로 Shopping Actions, Surfaces across Google, Local surfaces across Google 값을 제출했습니다. 이러한 값을 나타내려면 FREE_LISTINGS, FREE_LOCAL_LISTINGS, LOCAL_INVENTORY_ADS를 사용하세요. 자세한 내용은 프로모션 대상을 참고하세요.
itemIdInclusion[]

string

선택사항입니다. 프로모션의 상품 ID별 제품 필터입니다. 제품 필터 속성은 프로모션 적용 여부productApplicability 속성이 specific_products로 설정된 경우에만 적용됩니다.
brandInclusion[]

string

선택사항입니다. 프로모션의 브랜드별 제품 필터입니다. 제품 필터 속성은 프로모션 적용 여부productApplicability 속성이 specific_products로 설정된 경우에만 적용됩니다.
itemGroupIdInclusion[]

string

선택사항입니다. 프로모션의 상품 그룹 ID별 제품 필터입니다. 제품 필터 속성은 프로모션 적용 여부[productApplicability] 속성이 specific_products로 설정된 경우에만 적용됩니다.
productTypeInclusion[]

string

선택사항입니다. 프로모션의 제품 유형별 제품 필터입니다. 제품 필터 속성은 프로모션 적용 여부productApplicability 속성이 specific_products로 설정된 경우에만 적용됩니다.
itemIdExclusion[]

string

선택사항입니다. 프로모션의 상품 ID 제외를 기준으로 제품을 필터링합니다. 제품 필터 속성은 프로모션 적용 여부productApplicability 속성이 specific_products로 설정된 경우에만 적용됩니다.
brandExclusion[]

string

선택사항입니다. 프로모션의 브랜드 제외를 기준으로 한 제품 필터입니다. 제품 필터 속성은 프로모션 적용 여부productApplicability 속성이 specific_products로 설정된 경우에만 적용됩니다.
itemGroupIdExclusion[]

string

선택사항입니다. 상품 그룹 ID로 제품 필터링 제품 필터 속성은 프로모션 적용 여부productApplicability 속성이 specific_products로 설정된 경우에만 적용됩니다.
productTypeExclusion[]

string

선택사항입니다. 프로모션의 제품 유형 제외별 제품 필터입니다. 제품 필터 속성은 프로모션 적용 여부productApplicability 속성이 specific_products로 설정된 경우에만 적용됩니다.
minimumPurchaseAmount

object (Price)

선택사항입니다. 프로모션의 최소 구매액입니다.
minimumPurchaseQuantity

string (int64 format)

선택사항입니다. 프로모션의 최소 구매 수량입니다.
limitQuantity

string (int64 format)

선택사항입니다. 프로모션의 최대 구매 수량입니다.
limitValue

object (Price)

선택사항입니다. 프로모션의 제품 최고 가격입니다.
percentOff

string (int64 format)

선택사항입니다. 프로모션에서 제공하는 할인율입니다.
moneyOffAmount

object (Price)

선택사항입니다. 프로모션에서 제공하는 할인 금액입니다.
getThisQuantityDiscounted

string (int64 format)

선택사항입니다. 프로모션에서 할인된 상품의 수입니다. 이 속성은 couponValueType가 buy_m_get_n_money_off 또는 buy_m_get_n_percent_off와 같을 때 설정됩니다.
freeGiftValue

object (Price)

선택사항입니다. 프로모션의 사은품 가치입니다.
freeGiftDescription

string

선택사항입니다. 프로모션의 사은품 설명입니다.
freeGiftItemId

string

선택사항입니다. 프로모션의 사은품 상품 ID입니다.
promotionEffectiveTimePeriod

object (Interval)

필수입니다. TimePeriod 프로모션 적용 기간을 나타냅니다. 이 속성은 이 기간 동안 온라인 상점에서 프로모션을 테스트할 수 있음을 지정합니다.
promotionDisplayTimePeriod

object (Interval)

선택사항입니다. TimePeriod 프로모션의 표시 날짜 표현 이 속성은 프로모션이 Google.com 및 쇼핑 광고에 게재되는 날짜와 시간을 지정합니다. 프로모션 표시 기간promotionDisplayTimePeriod 속성을 지정하지 않으면 프로모션 적용 기간promotionEffectiveTimePeriod에 따라 프로모션이 Google.com 및 쇼핑 광고에 게재되는 날짜와 기간이 결정됩니다.
storeApplicability

enum (StoreApplicability)

선택사항입니다. 프로모션이 모든 매장에 적용되는지 또는 지정된 매장에만 적용되는지 여부입니다. 오프라인 판매점 인벤토리 광고 프로모션에 매장 적용 범위가 포함되지 않으면 오류가 발생합니다. storeApplicability이 ALL_STORES로 설정되고 storeCodesInclusion 또는 score_code_exclusion가 값으로 설정되면 INVALID_ARGUMENT 오류가 발생합니다.
storeCodesInclusion[]

string

선택사항입니다. 프로모션에 포함할 매장 코드 매장 필터 속성은 storeApplicability 속성이 specific_stores로 설정된 경우에만 적용됩니다.

제품이 판매되는 오프라인 매장의 판매점 코드 (비즈니스 프로필의 매장 ID)입니다. 자세한 내용은 오프라인 제품 인벤토리 데이터 사양을 참고하세요.
storeCodesExclusion[]

string

선택사항입니다. 프로모션에서 제외할 매장 코드 매장 필터 속성은 storeApplicability 속성이 specific_stores로 설정된 경우에만 적용됩니다.
promotionUrl

string

선택사항입니다. 프로모션이 표시되는 판매자 사이트의 페이지 URL입니다. promotionUrl가 포함되지 않으면 오프라인 판매점 인벤토리 광고 프로모션에 오류가 발생합니다. URL은 프로모션의 유효성 및 사용 가능 여부를 확인하는 데 사용됩니다.

ProductApplicability

프로모션이 적용되는 제품 또는 제품 목록입니다.

열거형
PRODUCT_APPLICABILITY_UNSPECIFIED 프로모션이 적용되는 제품을 알 수 없습니다.
ALL_PRODUCTS 모든 제품에 적용됩니다.
SPECIFIC_PRODUCTS 단일 제품 또는 제품 목록에만 적용됩니다.

OfferType

프로모션의 혜택 유형입니다.

열거형
OFFER_TYPE_UNSPECIFIED 알 수 없는 제품 유형입니다.
NO_CODE 코드가 없는 제품 유형입니다.
GENERIC_CODE 코드가 있는 혜택 유형입니다. offerType = GENERIC_CODE인 경우 프로모션의 일반 쿠폰 사용 코드가 필요합니다.

CouponValueType

프로모션의 쿠폰 값 유형입니다.

열거형
COUPON_VALUE_TYPE_UNSPECIFIED 쿠폰 값 유형이 지정되지 않았음을 나타냅니다.
MONEY_OFF 할인 쿠폰 값 유형입니다.
PERCENT_OFF 할인율 쿠폰 값 유형입니다.
BUY_M_GET_N_MONEY_OFF M개 구매 시 N 할인 쿠폰 값 유형 minimumPurchaseQuantity 및 getThisQuantityDiscounted가 있어야 합니다. moneyOffAmount도 있어야 합니다.
BUY_M_GET_N_PERCENT_OFF M개 구매 시 N% 할인 쿠폰 값 유형 minimumPurchaseQuantity 및 getThisQuantityDiscounted가 있어야 합니다. percent_off_percentage도 있어야 합니다.
BUY_M_GET_MONEY_OFF M개 구매 시 할인. minimumPurchaseQuantity 및 moneyOffAmount가 있어야 합니다.
BUY_M_GET_PERCENT_OFF M개 구매 시 할인. minimumPurchaseQuantity 및 percent_off_percentage가 있어야 합니다.
FREE_GIFT 설명이 포함된 사은품만 제공됩니다.
FREE_GIFT_WITH_VALUE 금전적 가치가 있는 사은품
FREE_GIFT_WITH_ITEM_ID 상품 ID에 따른 사은품
FREE_SHIPPING_STANDARD 일반 무료 배송 쿠폰 값 유형입니다. 온라인 프로모션에만 사용할 수 있습니다.
FREE_SHIPPING_OVERNIGHT 익일 무료 배송 쿠폰 값 유형입니다. 온라인 프로모션에만 사용할 수 있습니다.
FREE_SHIPPING_TWO_DAY 2일 이내 무료 배송 쿠폰 값 유형입니다. 온라인 프로모션에만 사용할 수 있습니다.

DestinationEnum

도착 값

열거형
DESTINATION_ENUM_UNSPECIFIED 지정되지 않음
SHOPPING_ADS 쇼핑 광고
DISPLAY_ADS 디스플레이 광고
LOCAL_INVENTORY_ADS 오프라인 판매점 인벤토리 광고.
FREE_LISTINGS 무료 등록정보
FREE_LOCAL_LISTINGS 무료 오프라인 제품 등록정보
YOUTUBE_SHOPPING YouTube Shopping
YOUTUBE_SHOPPING_CHECKOUT YouTube Shopping 결제
YOUTUBE_AFFILIATE YouTube 제휴사
FREE_VEHICLE_LISTINGS 무료 차량 등록정보
VEHICLE_ADS 차량 광고
CLOUD_RETAIL Cloud Retail
LOCAL_CLOUD_RETAIL 로컬 Cloud Retail

StoreApplicability

프로모션이 적용되는 판매점 코드 또는 판매점 코드 목록입니다. 오프라인 판매점 인벤토리 광고 프로모션에만 사용할 수 있습니다.

열거형
STORE_APPLICABILITY_UNSPECIFIED 프로모션이 적용되는 매장 코드가 알 수 없습니다.
ALL_STORES 모든 매장에 프로모션이 적용됩니다.
SPECIFIC_STORES 프로모션이 지정된 매장에만 적용됩니다.

PromotionStatus

프로모션 상태입니다.

JSON 표현 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
필드
destinationStatuses[]

object (DestinationStatus)

출력 전용입니다. 프로모션의 의도한 대상 유형입니다.
itemLevelIssues[]

object (ItemLevelIssue)

출력 전용입니다. 프로모션과 관련된 문제 목록입니다.
creationDate

string (Timestamp format)

출력 전용입니다. 프로모션이 생성된 날짜입니다. ISO 8601 형식: 날짜, 시간, 오프셋(예: 2020-01-02T09:00:00+01:00 또는 2020-01-02T09:00:00Z)
lastUpdateDate

string (Timestamp format)

출력 전용입니다. 프로모션 상태가 마지막으로 업데이트된 날짜입니다. ISO 8601 형식: 날짜, 시간, 오프셋(예: 2020-01-02T09:00:00+01:00 또는 2020-01-02T09:00:00Z)

DestinationStatus

지정된 대상의 상태입니다.

JSON 표현 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
필드
reportingContext

enum (ReportingContextEnum)

출력 전용입니다. 프로모션 대상의 이름입니다.
status

enum (State)

출력 전용입니다. 지정된 대상의 상태입니다.

주

프로모션의 현재 상태입니다.

열거형
STATE_UNSPECIFIED 알 수 없는 프로모션 상태입니다.
IN_REVIEW 프로모션이 검토 중입니다.
REJECTED 프로모션이 비승인되었습니다.
LIVE 프로모션이 승인되어 활성 상태입니다.
STOPPED 판매자가 프로모션을 중지했습니다.
EXPIRED 프로모션이 더 이상 진행되지 않습니다.
PENDING 프로모션이 중지되지 않았고 모든 검토가 승인되었지만 활성 날짜가 아직 지나지 않았습니다.

ItemLevelIssue

프로모션과 관련된 문제입니다.

JSON 표현 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
필드
code

string

출력 전용입니다. 문제의 오류 코드
severity

enum (Severity)

출력 전용입니다. 이 문제가 프로모션 게재에 미치는 영향
resolution

string

출력 전용입니다. 판매자가 문제를 해결할 수 있는지 여부
attribute

string

출력 전용입니다. 문제가 단일 속성으로 인해 발생한 경우 속성의 이름.
reportingContext

enum (ReportingContextEnum)

출력 전용입니다. 문제가 적용되는 대상 위치.
description

string

출력 전용입니다. 간단한 문제 설명(영어)
detail

string

출력 전용입니다. 자세한 문제 설명(영어)
documentation

string

출력 전용입니다. 이 문제를 해결하는 데 도움이 되는 웹페이지의 URL
applicableCountries[]

string

출력 전용입니다. 제품에 문제가 적용되는 국가 코드 (ISO 3166-1 alpha-2) 목록입니다.

심각도

문제의 심각도입니다.

열거형
SEVERITY_UNSPECIFIED 지정되지 않음
NOT_IMPACTED 이 문제는 경고를 나타내며 프로모션에 직접적인 영향을 미치지 않습니다.
DEMOTED 프로모션이 강등되어 검색 결과에서 실적이 제한될 가능성이 큽니다.
DISAPPROVED 문제로 인해 프로모션이 비승인됩니다.

메서드

get

 판매자 센터 계정에서 프로모션을 가져옵니다.

insert

 판매자 센터 계정의 프로모션을 삽입합니다.

list

 판매자 센터 계정의 프로모션을 나열합니다.