REST Resource: accounts.promotions

Recurso: promoção

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

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

Depois de inserir e atualizar a entrada de uma 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 ID da promoção fornecido pelo usuário para identificar a promoção de maneira exclusiva. Siga os requisitos mínimos para evitar reprovações de promoções.
contentLanguage

string

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

As promoções só estão disponíveis em idiomas selecionados.
targetCountry

string

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

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

enum (RedemptionChannel)

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

string

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

object (Attributes)

Opcional. Uma lista de atributos da 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 e os problemas de validação de dados, ou seja, informações sobre uma promoção calculadas 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 será impedida quando o número da versão for menor que o número da versão atual da promoção existente. A reinserção (por exemplo, atualização de promoção após 30 dias) pode ser realizada com o versionNumber atual.

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

RedemptionChannel

Canal de uma promoção.

Tipos enumerados
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. Aplicabilidade da promoção a todos os produtos ou apenas a produtos específicos.
offerType

enum (OfferType)

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

string

Opcional. Código de desconto genérico da promoção. Para ser usado com o campo offerType e 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 do 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 incluir um valor compatível na sua fonte de dados para especificar um destino, sua promoção será exibida 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 productApplicability dos produtos qualificados para aplicabilidade do produto em 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 productApplicability dos produtos qualificados para aplicabilidade do produto em 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 de produto só são válidos quando o atributo de aplicabilidade do produto na promoção [productApplicability] aos produtos qualificados 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 productApplicability dos produtos qualificados para aplicabilidade do produto em 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 productApplicability dos produtos qualificados para aplicabilidade do produto em promoção está definido como specific_products.
brandExclusion[]

string

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

string

Opcional. Filtre por ID do grupo de itens. Os atributos de filtro de produto só são válidos quando o atributo productApplicability da aplicabilidade do produto em 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 do 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. 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. Código do item de brinde da promoção.
promotionEffectiveTimePeriod

object (Interval)

Obrigatório. Representação de TimePeriod do início da vigência 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. Indica se a promoção se aplica a todas as lojas ou apenas lojas específicas. As promoções de anúncios de inventário local geram um erro se nenhuma aplicabilidade à loja estiver 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 de 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.

Código da loja física (o ID no seu Perfil da Empresa) da loja física em que o produto é vendido. Consulte a especificação dos dados do inventário de produtos disponíveis na loja física 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 para a página do site do comerciante em que a promoção aparece. As promoções de anúncios de inventário local vão gerar um erro se nenhum promotionUrl for incluído. é usado para confirmar que a promoção é válida e pode ser resgatada.

ProductApplicability

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

Tipos enumerados
PRODUCT_APPLICABILITY_UNSPECIFIED Os produtos a que a promoção se aplica são desconhecidos.
ALL_PRODUCTS Aplicável a todos os produtos.
SPECIFIC_PRODUCTS Aplicável a apenas um produto ou uma lista de produtos.

OfferType

Tipo de oferta de uma promoção.

Tipos enumerados
OFFER_TYPE_UNSPECIFIED Tipo de oferta desconhecido.
NO_CODE Tipo de oferta sem um código.
GENERIC_CODE Tipo de oferta com um código. É necessário um código de desconto genérico da promoção quando offerType = GENERIC_CODE.

CouponValueType

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

Tipos enumerados
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 Tipo de valor do cupom de porcentagem de desconto.
BUY_M_GET_N_MONEY_OFF Compre uma quantidade M e ganhe N de desconto no tipo de valor do cupom. minimumPurchaseQuantity e getThisQuantityDiscounted precisam estar presentes. moneyOffAmount também precisa estar presente.
BUY_M_GET_N_PERCENT_OFF Compre a quantidade M e ganhe N com o 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 a quantidade M e ganhe um desconto de dinheiro. É necessário incluir minimumPurchaseQuantity e moneyOffAmount.
BUY_M_GET_PERCENT_OFF Compre a quantidade M e ganhe um desconto de dinheiro. É necessário incluir minimumPurchaseQuantity e percent_off_percentage.
FREE_GIFT Brinde apenas com descrição.
FREE_GIFT_WITH_VALUE Brinde com valor monetário.
FREE_GIFT_WITH_ITEM_ID Brinde com código 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 grátis de um dia para o outro.
FREE_SHIPPING_TWO_DAY Tipo de valor do cupom de frete grátis em dois dias.

DestinationEnum

Valores de destino.

Tipos enumerados
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:

StoreApplicability

Códigos da loja ou lista de códigos da loja a que a promoção se aplica. Apenas para promoções de anúncios de inventário local.

Tipos enumerados
STORE_APPLICABILITY_UNSPECIFIED Os códigos da loja a que a promoção se aplica são desconhecidos.
ALL_STORES A promoção é válida para todas as lojas.
SPECIFIC_STORES A promoção é válida somente para as lojas especificadas.

PromotionStatus

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 da 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. Nome do destino da promoção.
status

enum (State)

Apenas saída. O status do destino especificado.

Estado

O estado atual da promoção.

Tipos enumerados
STATE_UNSPECIFIED Status 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 o problema.
applicableCountries[]

string

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

Gravidade

A gravidade do problema.

Tipos enumerados
SEVERITY_UNSPECIFIED Não especificado.
NOT_IMPACTED Esse problema representa um alerta e não tem efeito direto na promoção.
DEMOTED A promoção foi rebaixada e provavelmente tem performance limitada 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.