REST Resource: accounts.promotions

Recurso: promoção

Representa uma promoção. Consulte os artigos a seguir para mais detalhes.

Os atributos de entrada de promoção obrigatórios para passar nas verificações de validação de dados são definidos principalmente abaixo:

Depois de inserir ou atualizar uma entrada de promoção, pode levar vários minutos até que a promoção final seja recuperada.

Representação 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
}
Campos
name

string

Identificador. Nome da promoção. Formato: accounts/{account}/promotions/{promotion}
promotionId

string

Obrigatório. O usuário forneceu o ID da promoção para identificar exclusivamente a promoção. Siga os requisitos mínimos para evitar reprovações de promoção.
contentLanguage

string

Obrigatório. O código de idioma ISO 639-1 de duas letras da promoção.

As promoções são exibidas apenas em alguns idiomas.
targetCountry

string

Obrigatório. O país de destino usado como parte do identificador exclusivo. Representado como um código de território CLDR.

As promoções estão disponíveis apenas em alguns países, listagens sem custo financeiro e anúncios do Shopping anúncios de inventário local
redemptionChannel[]

enum (RedemptionChannel)

Obrigatório. Canal de resgate da promoção. É necessário ter pelo menos um canal.
dataSource

string

Apenas saída. A origem de dados principal da promoção.
attributes

object (Attributes)

Opcional. Uma lista de atributos de promoção.
customAttributes[]

object (CustomAttribute)

Opcional. Uma lista de atributos personalizados (fornecidos pelo comerciante). Ele também pode ser usado para enviar qualquer atributo da especificação de dados na forma genérica (por exemplo, { "name": "size type", "value": "regular" }). Isso é útil para enviar atributos não expostos explicitamente pela API.
promotionStatus

object (PromotionStatus)

Apenas saída. O status de uma promoção, problemas de validação de dados, ou seja, informações sobre uma promoção computada de forma assíncrona.
versionNumber

string (int64 format)

Opcional. Representa a versão existente (atualização) da promoção, que pode ser usada para preservar a ordem correta quando várias atualizações são feitas ao mesmo tempo.

Se definido, a inserção é impedida quando o número da versão é menor que o número da versão atual da promoção. A reinserção (por exemplo, atualização da promoção após 30 dias) pode ser realizada com o versionNumber atual.

Se a operação for impedida, a exceção será lançada.

RedemptionChannel

Canal de uma promoção.

Enums
REDEMPTION_CHANNEL_UNSPECIFIED Indica que o canal não foi especificado.
IN_STORE Indica que o canal está na loja. Isto é o mesmo que o canal local usado para products.
ONLINE Indica que o canal está on-line.

Atributos

Atributos.

Representação 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
}
Campos
productApplicability

enum (ProductApplicability)

Obrigatório. A aplicabilidade da promoção a todos os produtos ou apenas a produtos específicos.
offerType

enum (OfferType)

Obrigatório. Tipo da promoção. Use esse atributo para indicar se os clientes precisam ou não de um código do cupom para resgatar a promoção.
genericRedemptionCode

string

Opcional. Código de resgate genérico da promoção. Para ser usado com o campo offerType, ele precisa atender aos requisitos mínimos.
longTitle

string

Obrigatório. Título longo da promoção.
couponValueType

enum (CouponValueType)

Obrigatório. O atributo tipo de valor do cupom para indicar o tipo de promoção que você está exibindo. Dependendo do tipo de valor do cupom selecionado, alguns atributos são obrigatórios.
promotionDestinations[]

enum (DestinationEnum)

Obrigatório. A lista de destinos a que a promoção se aplica. Se você não especificar um destino incluindo um valor compatível na sua fonte de dados, a promoção vai aparecer nos anúncios do Shopping e nas listagens sem custo financeiro por padrão.

Talvez você já tenha enviado os seguintes valores como destinos para seus produtos: Shopping Actions, Google plataformas e Plataformas locais do Google. Para representar esses valores, use FREE_LISTINGS, FREE_LOCAL_LISTINGS e LOCAL_INVENTORY_ADS. Para mais detalhes, consulte Destino da promoção.
itemIdInclusion[]

string

Opcional. Filtre por ID do item para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo aplicabilidade do produto productApplicability dos produtos qualificados para a promoção está definido como specific_products.
brandInclusion[]

string

Opcional. Filtre por marca para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo aplicabilidade do produto productApplicability dos produtos qualificados para a promoção está definido como specific_products.
itemGroupIdInclusion[]

string

Opcional. Filtro de produtos por ID do grupo de itens para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo aplicabilidade do produto [productApplicability] dos produtos qualificados para a promoção está definido como specific_products.
productTypeInclusion[]

string

Opcional. Filtro de produto por tipo de produto para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo aplicabilidade do produto productApplicability dos produtos qualificados para a promoção está definido como specific_products.
itemIdExclusion[]

string

Opcional. Filtre por exclusão de ID do item para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo aplicabilidade do produto productApplicability dos produtos qualificados para a promoção está definido como specific_products.
brandExclusion[]

string

Opcional. Filtro de produtos por exclusão de marca para a promoção. Os atributos de filtro do produto só se aplicam quando o atributo aplicabilidade do produto productApplicability dos produtos qualificados para a promoção está definido como specific_products.
itemGroupIdExclusion[]

string

Opcional. Filtre por ID do grupo de itens. Os atributos de filtro do produto só se aplicam quando o atributo aplicabilidade do produto productApplicability dos produtos qualificados para a promoção está definido como specific_products.
productTypeExclusion[]

string

Opcional. Filtre por exclusão de tipo de produto para a promoção. Os atributos de filtro de produto só se aplicam quando o atributo productApplicability dos produtos qualificados para aplicabilidade do produto em promoção está definido como specific_products.
minimumPurchaseAmount

object (Price)

Opcional. Montante mínimo da compra da promoção.
minimumPurchaseQuantity

string (int64 format)

Opcional. Quantidade mínima de compra da promoção.
limitQuantity

string (int64 format)

Opcional. Quantidade de compra máxima da promoção.
limitValue

object (Price)

Opcional. Preço máximo do produto na promoção.
percentOff

string (int64 format)

Opcional. O desconto percentual oferecido na promoção.
moneyOffAmount

object (Price)

Opcional. O valor do desconto oferecido na promoção.
getThisQuantityDiscounted

string (int64 format)

Opcional. O número de itens com desconto na promoção. O atributo é definido quando couponValueType é igual a buy_m_get_n_money_off ou buy_m_get_n_percent_off.
freeGiftValue

object (Price)

Opcional. Valor do brinde da promoção.
freeGiftDescription

string

Opcional. Descrição do brinde da promoção.
freeGiftItemId

string

Opcional. ID do item de brinde da promoção.
promotionEffectiveTimePeriod

object (Interval)

Obrigatório. TimePeriod representação das datas de início da promoção. Esse atributo especifica que a promoção pode ser testada na sua loja on-line durante esse período.
promotionDisplayTimePeriod

object (Interval)

Opcional. Representação TimePeriod das datas de exibição da promoção. Esse atributo especifica a data e o período em que a promoção será publicada no Google.com.br e nos anúncios do Shopping. Se o atributo período de exibição da promoção promotionDisplayTimePeriod não for especificado, o período de vigência da promoção promotionEffectiveTimePeriod determinará a data e o período em que a promoção estará ativa no Google.com.br e nos anúncios do Shopping.
storeApplicability

enum (StoreApplicability)

Opcional. Se a promoção se aplica a todas as lojas ou apenas a lojas específicas. As promoções de anúncios de inventário local vão gerar um erro se nenhuma aplicabilidade à loja for incluída. Um erro INVALID_ARGUMENT será gerado se storeApplicability for definido como ALL_STORES e storeCodesInclusion ou score_code_exclusion estiver definido como um valor.
storeCodesInclusion[]

string

Opcional. Códigos da loja a serem incluídos na promoção. Os atributos de filtro da loja só se aplicam quando o atributo storeApplicability está definido como specific_stores.

O código da loja (o ID da loja do seu Perfil da Empresa) da loja física em que o produto é vendido. Consulte a Especificação dos dados do inventário de produtos locais para mais informações.
storeCodesExclusion[]

string

Opcional. Códigos de loja a serem excluídos da promoção. Os atributos de filtro da loja só se aplicam quando o atributo storeApplicability está definido como specific_stores.
promotionUrl

string

Opcional. URL da página no site do comerciante em que a promoção aparece. As promoções de anúncios de inventário local geram um erro se nenhum promotionUrl for incluído. O URL é usado para confirmar se a promoção é válida e pode ser resgatada.

ProductApplicability

A qual produto ou lista de produtos a promoção se aplica.

Enums
PRODUCT_APPLICABILITY_UNSPECIFIED Não é possível saber quais produtos a promoção se aplica.
ALL_PRODUCTS Aplicável a todos os produtos.
SPECIFIC_PRODUCTS Aplicável apenas a um único produto ou lista de produtos.

OfferType

Tipo de oferta de uma promoção.

Enums
OFFER_TYPE_UNSPECIFIED Tipo de oferta desconhecido.
NO_CODE Tipo de oferta sem código.
GENERIC_CODE Tipo de oferta com um código. O código de resgate genérico para a promoção é necessário quando offerType = GENERIC_CODE.

CouponValueType

Tipo de valor do cupom de uma promoção.

Enums
COUPON_VALUE_TYPE_UNSPECIFIED Indica que o tipo de valor do cupom não foi especificado.
MONEY_OFF Tipo de valor do cupom de desconto.
PERCENT_OFF Percentual de desconto do tipo de valor do cupom.
BUY_M_GET_N_MONEY_OFF Compre M unidades e ganhe N de desconto do tipo de valor do cupom. minimumPurchaseQuantity e getThisQuantityDiscounted precisam estar presentes. O campo moneyOffAmount também precisa estar presente.
BUY_M_GET_N_PERCENT_OFF Compre M unidades e ganhe N% de desconto no tipo de valor do cupom. minimumPurchaseQuantity e getThisQuantityDiscounted precisam estar presentes. percent_off_percentage também precisa estar presente.
BUY_M_GET_MONEY_OFF Compre M unidades e ganhe um desconto. minimumPurchaseQuantity e moneyOffAmount precisam estar presentes.
BUY_M_GET_PERCENT_OFF Compre M unidades e ganhe um desconto. minimumPurchaseQuantity e percent_off_percentage precisam estar presentes.
FREE_GIFT Brinde apenas com descrição.
FREE_GIFT_WITH_VALUE Brinde com valor monetário.
FREE_GIFT_WITH_ITEM_ID Brinde com ID do item.
FREE_SHIPPING_STANDARD Tipo de valor do cupom de frete grátis padrão.
FREE_SHIPPING_OVERNIGHT Tipo de valor do cupom de frete noturno sem custo financeiro.
FREE_SHIPPING_TWO_DAY Tipo de valor do cupom de frete grátis em dois dias.

DestinationEnum

Valores de destino.

Enums
DESTINATION_ENUM_UNSPECIFIED Não especificado.
SHOPPING_ADS Anúncios do Shopping.
DISPLAY_ADS Anúncios de display.
LOCAL_INVENTORY_ADS Anúncios de inventário local.
FREE_LISTINGS Listagens sem custo financeiro.
FREE_LOCAL_LISTINGS Listagens sem custo financeiro de produtos locais.
YOUTUBE_SHOPPING YouTube Shopping.
YOUTUBE_SHOPPING_CHECKOUT Finalizar a compra no YouTube Shopping.
YOUTUBE_AFFILIATE Afiliado do YouTube.
FREE_VEHICLE_LISTINGS Listagens sem custo financeiro de veículos.
VEHICLE_ADS Anúncios de veículos.
CLOUD_RETAIL Varejo na nuvem.
LOCAL_CLOUD_RETAIL Varejo local na nuvem.

StoreApplicability

Códigos de loja ou lista de códigos de loja aplicáveis à promoção. Somente para promoções de anúncios de inventário local.

Enums
STORE_APPLICABILITY_UNSPECIFIED Não é possível saber quais códigos de loja a promoção se aplica.
ALL_STORES A promoção se aplica a todas as lojas.
SPECIFIC_STORES A promoção se aplica apenas às lojas especificadas.

PromotionStatus

O status da promoção.

Representação JSON 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
Campos
destinationStatuses[]

object (DestinationStatus)

Apenas saída. Os destinos pretendidos para a promoção.
itemLevelIssues[]

object (ItemLevelIssue)

Apenas saída. Uma lista de problemas associados à promoção.
creationDate

string (Timestamp format)

Apenas saída. Data em que a promoção foi criada no formato ISO 8601: data, hora e deslocamento, por exemplo, 2020-01-02T09:00:00+01:00 ou 2020-01-02T09:00:00Z
lastUpdateDate

string (Timestamp format)

Apenas saída. Data em que o status da promoção foi atualizado pela última vez no formato ISO 8601: data, hora e deslocamento, por exemplo, 2020-01-02T09:00:00+01:00 ou 2020-01-02T09:00:00Z

DestinationStatus

O status do destino especificado.

Representação JSON 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
Campos
reportingContext

enum (ReportingContextEnum)

Apenas saída. O nome do destino da promoção.
status

enum (State)

Apenas saída. O status do destino especificado.

Estado

O estado atual da promoção.

Enums
STATE_UNSPECIFIED Estado de promoção desconhecido.
IN_REVIEW A promoção está em análise.
REJECTED A promoção foi reprovada.
LIVE A promoção foi aprovada e está ativa.
STOPPED A promoção foi interrompida pelo comerciante.
EXPIRED A promoção não está mais ativa.
PENDING A promoção não foi interrompida, e todas as revisões foram aprovadas, mas a data de atividade está no futuro.

ItemLevelIssue

O problema associado à promoção.

Representação JSON 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
Campos
code

string

Apenas saída. O código de erro do problema.
severity

enum (Severity)

Apenas saída. Como esse problema afeta a veiculação da promoção.
resolution

string

Apenas saída. Se o problema pode ser resolvido pelo comerciante.
attribute

string

Apenas saída. O nome do atributo, se o problema for causado por um único atributo
reportingContext

enum (ReportingContextEnum)

Apenas saída. O destino a que o problema se aplica.
description

string

Apenas saída. Uma breve descrição do problema em inglês.
detail

string

Apenas saída. Uma descrição detalhada do problema em inglês.
documentation

string

Apenas saída. O URL de uma página da Web para ajudar a resolver esse problema.
applicableCountries[]

string

Apenas saída. Lista de códigos de países (ISO 3166-1 alfa-2) em que o problema se aplica à oferta.

Gravidade

A gravidade do problema.

Enums
SEVERITY_UNSPECIFIED Não especificado.
NOT_IMPACTED Esse problema representa um aviso e não tem um efeito direto na promoção.
DEMOTED A promoção é rebaixada e provavelmente tem desempenho limitado nos resultados da pesquisa
DISAPPROVED O problema reprova a promoção.

Métodos

get

 Recupera a promoção da sua conta do Merchant Center.

insert

 Insere uma promoção na sua conta do Merchant Center.

list

 Lista as promoções na sua conta do Merchant Center.