Panoramica dell'API Merchant Promotions

Utilizza le promozioni per mettere in evidenza le offerte speciali dei prodotti che vendi su Google. Le promozioni vengono visualizzate su diverse proprietà di Google, tra cui Ricerca Google, Shopping e Chrome.

Quando aggiungi Promozioni ai tuoi prodotti, gli acquirenti visualizzano un link a un'offerta speciale per esempio "15% di sconto" o "Spedizione gratuita". I link alle offerte possono aumentare l'attrattiva i tuoi prodotti e incoraggia gli acquirenti a effettuare un acquisto.

Per ulteriori informazioni, consulta la sezione Promozione di base.

Prerequisiti

Google ha bisogno che tu fornisca informazioni specifiche sulla tua attività e i tuoi prodotti prima di mostrare le tue promozioni. Devi disporre di quanto segue:

Inoltre, devi registrare il tuo account commerciante al programma Promozioni. Se non sai se hai già effettuato la registrazione, controlla la scheda Commerciante assistenza.

Se non hai effettuato la registrazione, completa la richiesta modulo. La team Promozioni ti avviserà quando è tutto pronto per iniziare l'implementazione.

Per ulteriori informazioni, vedi Criteri di partecipazione e .

Creare un'origine dati

Utilizza l'API datasource.create per creare un feed delle promozioni. Se un'istanza esistente Il feed delle promozioni è disponibile; utilizza datasource.get per recuperare il datasource.name

Il modulo della richiesta è il seguente:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{account}/dataSources/{datasource}

Esempio

L'esempio mostra una richiesta e una risposta tipiche.

Richiesta:

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

Risposta:

{
  "name": "accounts/123/dataSources/1000000573361824",
  "dataSourceId": "1000000573361824",
  "displayName": "test api feed",
  "promotionDataSource": {
    "targetCountry": "US",
    "contentLanguage": "en"
  },
  "input": "API"
}

Crea promozioni

Puoi utilizzare lo accounts.promotions.insert per creare o aggiornare una promozione. Il metodo accounts.promotions.insert prende una risorsa promotions e un nome origine dati come input. Restituisce il valore promozione nuova o aggiornata, se riuscita.

Per creare una promozione è necessario datasource.name:

Google esamina e approva le tue promozioni prima di distribuirle. Per ulteriori informazioni informazioni, consulta la sezione Approvazione delle promozioni .

Il modulo della richiesta:

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

Esamina i seguenti esempi di promozioni come riferimento.

Esempio 1: un video promozionale valida per tutti i prodotti e tutti i negozi

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"
      },
      "minimum_purchase_quantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/123/dataSources/1000000573361824"
}

Esempio 2: una promozione online applicata a prodotti selezionati con un utilizzo codice

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

Note speciali

Dopo aver creato la promozione, potrebbero essere necessari alcuni minuti per crearla.

Per un elenco degli attributi correlati alle promozioni, consulta Aggiungere dati strutturati attributi.

Prima di creare e gestire le promozioni, consulta la sezione Migliori promozioni Pratiche.

Visualizza le promozioni

Per visualizzare una promozione, utilizza accounts.promotions.get Questa richiesta è di sola lettura. Richiede il tuo merchantId e l'ID del promozione. Il metodo get restituisce la risorsa di promozione corrispondente.

Ad esempio:

GET https://merchantapi.googleapis.com/promotions/v1beta/{name=accounts/*/promotions/*}

Studia questi campioni.

Esempio 1: una promozione locale

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"
   },
   "minimum_purchase_quantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/123/dataSources/1000000573361824"
}

Esempio 2. Una promozione online

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

Elenco promozioni

Puoi utilizzare lo promotions.list per visualizzare tutte le promozioni create.

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

Stato della promozione

Per visualizzare lo stato di una promozione, puoi visualizzare l'attributo promotionStatus restituito da promotions.get: e promotions.list.

Per comprendere la procedura di approvazione, consulta la sezione Approvazione delle promozioni. .

Esempio di stato della promozione

I seguenti esempi dimostrano la differenza tra riusciti e non riusciti richieste.

Esempio 1. Il corpo della risposta seguente mostra una promozione online che sarebbe rifiutato a causa di una mappatura prodotti mancante.

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

Esempio 2. Il seguente corpo della risposta mostra una promozione approvata.

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

Esempio 3. Una promozione approvata e attiva

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

Scopri di più

Per ulteriori dettagli, consulta la Guida Promozioni assistenza.

Per scoprire di più sulla migrazione dall'API Content for Shopping, consulta l'articolo Eseguire la migrazione delle promozioni dei modelli.