Visão geral da API Merchant Promotions

Use promoções para mostrar ofertas especiais dos produtos que você vende no Google. As promoções aparecem em diferentes Serviços do Google, incluindo a Pesquisa Google, o Shopping e o Chrome. As promoções precisam atender a determinados critérios para serem aprovadas. Para mais informações, consulte Critérios de promoção.

Quando você adiciona uma promoção aos seus produtos, os compradores veem um link de oferta especial. Por exemplo, "15% de desconto" ou "frete grátis". Os links de oferta podem aumentar a atratividade dos seus produtos e incentivar os compradores a fazer uma compra. Todas as promoções são aplicadas na finalização da compra ou no ponto de venda.

Para mais informações, consulte Noções básicas sobre promoções.

Pré-requisitos

O Google precisa que você forneça informações específicas sobre sua empresa e produtos antes de mostrar suas promoções. Você precisa ter o seguinte:

Além disso, você precisa inscrever sua conta de comerciante no programa Promoções. Se você não tiver certeza se já se inscreveu, verifique no Merchant Center.

Se você não estiver inscrito, preencha o formulário de solicitação. A equipe de promoções vai informar quando você estiver pronto para iniciar a implementação.

Para mais informações, consulte Critérios e políticas de participação.

Criar uma fonte de dados

Use o método accounts.dataSources.create para criar uma fonte de dados de promoção. Se uma fonte de dados de promoção estiver disponível, use o método accounts.dataSources.list para extrair todas as fontes de dados. Em seguida, use o campo name da fonte de dados de promoções para criar promoções.

A solicitação a seguir mostra como criar uma fonte de dados para adicionar promoções:

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

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

Substitua:

  • {ACCOUNT_ID}: o identificador exclusivo da sua conta conforme aparece na interface do Merchant Center.
  • {DISPLAY_NAME}: o nome de exibição da fonte de dados.
  • {CONTENT_LANGUAGE}: o código de idioma ISO 639-1 de duas letras dos produtos na fonte de dados.
  • {TARGET_COUNTRY}: o código de território CLDR do país de destino em que você quer que as promoções fiquem visíveis.

Depois que a solicitação for concluída, você vai receber a seguinte resposta, que contém detalhes sobre a fonte de dados de promoções recém-criada:

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

Crie promoções

Use o método accounts.promotions.insert para criar ou atualizar uma promoção. O método accounts.promotions.insert usa um recurso promotions e um nome de fonte de dados como entrada. Ele retorna a promoção nova ou atualizada, se bem-sucedido.

A criação de uma promoção exige o nome da fonte de dados. Também é necessário fornecer valores para os seguintes campos na solicitação:

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

O Google analisa e aprova as promoções antes da distribuição. Para mais informações, consulte Processo de aprovação de promoções.

Recomendamos que você leia as políticas de promoções para garantir que as promoções criadas agreguem valor e obedeçam às políticas de anúncios do Shopping.

A solicitação abaixo demonstra como criar uma promoção on-line:

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}"
}

Para saber mais sobre as regras aplicáveis à definição do ID da promoção, consulte Requisitos mínimos para o atributo ID da promoção.

Os valores válidos para o campo obrigatório offerType são NO_CODE e GENERIC_CODE. Se você não fornecer um desses valores, a solicitação da API falhará com a resposta HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. Uma mensagem de erro semelhante será retornada se você não fornecer nenhum dos campos obrigatórios.

Se você não fornecer um valor para o campo attributes.genericRedemptionCode, a solicitação falhará com a resposta HTTP 400 [genericRedemptionCode] No redemption code provided.

Os valores dos campos promotion.attributes.promotionDisplayTimePeriod.startTime e promotion.attributes.promotionDisplayTimePeriod.endTime precisam estar no formato yyyy-mm-ddThh:mm:ssZ. Substitua os valores desses campos por datas futuras.

Para mais informações, consulte Especificação de dados de promoções.

Para conferir as práticas recomendadas sobre como criar uma promoção, consulte Práticas recomendadas para promoções.

Para conferir uma lista de atributos relacionados a promoções, consulte Adicionar atributos de dados estruturados.

Depois que a solicitação de criação de promoção é executada com sucesso, pode levar alguns minutos para que a promoção seja recuperada usando a API ou apareça no Merchant Center.

Confira a seguir alguns exemplos de promoções que você pode usar para começar.

Uma promoção local aplicável a todos os produtos e lojas

O exemplo de solicitação a seguir mostra como criar uma promoção local que é aplicável a todos os produtos na sua conta do Merchant Center e a todas as lojas adicionadas na conta vinculada do Perfil da Empresa.

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}"
}

O campo productApplicability é obrigatório. Ele sinaliza a aplicabilidade da promoção a todos os produtos ou apenas a produtos específicos. Os valores aceitos são ALL_PRODUCTS e SPECIFIC_PRODUCTS. Para mais informações, consulte Escolher produtos para sua promoção.

O campo couponValueType é obrigatório. Ele sinaliza o tipo de promoção que você está veiculando. Para conferir a lista de valores de suporte, consulte Tipo de valor do cupom. Dependendo do tipo de valor de cupom selecionado, alguns atributos são necessários.

O campo minimumPurchaseQuantity permite definir o valor da quantidade mínima de compra necessária para resgatar a oferta promocional. Para mais informações, consulte Quantidade mínima de compra da promoção.

Da mesma forma, você pode usar o campo minimumPurchaseAmount para definir o valor mínimo de compra necessário para resgatar a promoção. Para mais informações, consulte Valor mínimo de compra.

Para mais informações sobre os valores que você precisa fornecer para criar uma promoção local, consulte Especificações da fonte de dados para promoções locais.

Uma promoção on-line que se aplica a produtos selecionados com um código de resgate

O exemplo de solicitação a seguir mostra como criar uma promoção on-line que se aplica a produtos selecionados com um código de resgate.

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"
}

Ver promoções

Para conferir uma promoção, use accounts.promotions.get. Esta solicitação GET é somente leitura. Ele requer seu merchantId e o ID da promoção. O método GET retorna o recurso de promoções correspondente.

Exemplo:

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

Substitua:

  • {ACCOUNT_ID}: o identificador exclusivo da sua conta do Merchant Center.
  • {PROMOTION_ID}: o identificador exclusivo da promoção que você quer recuperar. O formato é {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

Uma promoção recém-criada leva alguns minutos para ser recuperada usando a API.

Conferir uma promoção local

O exemplo de solicitação a seguir recupera uma promoção local com o 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

Depois que a solicitação for bem-sucedida, você vai receber a seguinte resposta:

{
 "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"
}

O campo moneyOffAmount neste exemplo fornece o desconto oferecido na promoção. Para mais informações, consulte Valor do desconto monetário de uma promoção.

O campo promotionUrl neste exemplo fornece o link para o site da loja, onde os compradores podem encontrar mais informações sobre a promoção. As promoções de anúncios de inventário local retornam um erro se você não incluir o campo promotionUrl.

Acessar uma promoção on-line

O exemplo de solicitação a seguir recupera uma promoção on-line com o 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}"
}

O campo itemIdInclusion usado neste exemplo menciona os produtos que são qualificados para a promoção. Para mais informações, consulte ID do produto para promoção.

Listar promoções

Você pode usar o método promotions.list para conferir todas as promoções criadas.

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

A resposta contém a lista de todas as promoções na sua conta. Para cada promoção, você pode conferir detalhes como promotionId, redemptionChannel, dataSource, promotionStatus e muito mais.

Conferir o status de uma promoção

Para conferir o status de uma promoção, consulte o atributo promotionStatus retornado pelo método promotions.get ou promotions.list.

O campo promotionStatus pode ter os seguintes valores:

  • IN_REVIEW: a promoção ainda 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 pela conta.
  • EXPIRED: a promoção não está mais ativa.
  • PENDING: a promoção não foi interrompida e todas as análises foram aprovadas, mas a data de ativação é futura.
  • STATE_UNSPECIFIED: estado de promoção desconhecido.

Para entender o processo de aprovação de uma promoção que você criou, consulte Processo de aprovação de promoções.

Exemplo de status de promoção

Os exemplos a seguir demonstram a diferença entre solicitações bem-sucedidas e com falha.

Mapeamento de produto ausente

O corpo de resposta a seguir mostra uma promoção on-line reprovada devido à falta de mapeamento de produtos.

  "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"
        ]
      }
    ]
  }

Para resolver problemas de promoções reprovadas e saber como evitar reprovações futuras, consulte Corrigir problemas de promoções reprovadas.

Se uma promoção criada por você não for aprovada, você vai receber um e-mail com o motivo da rejeição e instruções para corrigir os problemas.

Promoção em avaliação

O corpo de resposta a seguir mostra uma promoção que ainda está sendo avaliada.

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

Uma promoção ativa e aprovada

O corpo de resposta a seguir mostra uma promoção que é visível para os compradores.

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

Para mais informações, consulte as Perguntas frequentes sobre o status da promoção.

Saiba mais