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.

Quando você adiciona promoções aos seus produtos, os compradores veem um link de oferta especial, por exemplo, "15% de desconto" ou "Frete grátis". Os links de ofertas podem aumentar a atratividade dos produtos e incentivar os compradores a fazer uma compra.

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 a API datasource.create para criar um feed de promoção. Se um feed de promoção existente estiver disponível, use o método accounts.dataSources.get para buscar o nome da fonte de dados.

O formato da solicitação é o seguinte:

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

Exemplo

O exemplo mostra uma solicitação e uma resposta típicas.

Solicitação:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/123/dataSources {"displayName": "test api feed", "promotionDataSource":{"targetCountry":"US", "contentLanguage":"en"}}

Resposta:

{
  "name": "accounts/123/dataSources/1000000573361824",
  "dataSourceId": "1000000573361824",
  "displayName": "test api feed",
  "promotionDataSource": {
    "targetCountry": "US",
    "contentLanguage": "en"
  },
  "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 for bem-sucedido.

Para criar uma promoção, é necessário informar o nome da fonte de dados.

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

O formato da solicitação:

POST https://merchantapi.googleapis.com/promotions/v1beta/{parent=accounts/*/}promotions:insert

Estude os exemplos de promoções a seguir para referência.

Exemplo 1: uma promoção local aplicável a todos os produtos e lojas

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/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/123/dataSources/1000000573361824"
}

Exemplo 2: uma promoção on-line aplicada a produtos selecionados com um código de resgate

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/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/123/dataSources/1000000573361824"
}

Observações especiais

Após a criação da promoção, pode levar alguns minutos para que ela apareça no banco de dados do Shopping.

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

Antes de criar e gerenciar promoções, consulte as práticas recomendadas para promoções.

Ver promoções

Para conferir uma promoção, use accounts.promotions.get. Este 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/{name=accounts/*/promotions/*}

Estude estes exemplos.

Exemplo 1: uma promoção local

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

{
 "name": "accounts/123/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/123/dataSources/1000000573361824"
}

Exemplo 2. Uma promoção on-line

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/promotions/online~en~US~25_pct_off
{
 "name": "accounts/123/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}/dataSources/{dataSource}"
}

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/{parent=accounts/*}/promotions

Status da promoção

Para conferir o status de uma promoção, consulte o atributo promotionStatus retornado por promotions.get e promotions.list.

Para entender o processo de aprovação, 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.

Exemplo 1. O corpo de resposta a seguir mostra uma promoção on-line que seria rejeitada 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"
        ]
      }
    ]
  }

Exemplo 2. 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": []
  }

Exemplo 3. Uma promoção ativa e aprovada

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

Saiba mais

Para mais detalhes, consulte a Central de Ajuda de promoções.

Para saber como migrar da API Content for Shopping, consulte Migrar o gerenciamento de promoções.