Panoramica dell'API Merchant Promotions

Utilizza le promozioni per mostrare offerte speciali per i prodotti che vendi su Google. Le promozioni vengono visualizzate su diverse proprietà di Google, tra cui la Ricerca Google, Shopping e Chrome. Le promozioni devono soddisfare determinati criteri per essere approvate. Per ulteriori informazioni, consulta i criteri di promozione.

Quando aggiungi una promozione ai tuoi prodotti, gli acquirenti visualizzano un link che rimanda a un'offerta speciale. Ad esempio, "15% di sconto" o "Spedizione gratuita". I link alle offerte possono aumentare l'interesse nei confronti dei tuoi prodotti e incoraggiare gli acquirenti a effettuare un acquisto. Tutte le promozioni vengono applicate al momento del pagamento o presso il point of sale.

Per ulteriori informazioni, consulta la sezione Nozioni di base sulle promozioni.

Prerequisiti

Prima di poter mostrare le tue promozioni, Google ha bisogno che tu fornisca una serie di informazioni specifiche sulla tua attività e sui tuoi prodotti. Devi disporre di quanto segue:

Inoltre, devi registrare il tuo account commerciante al programma Promozioni. Se non hai la certezza di aver già effettuato la registrazione, consulta Merchant Center.

Se non hai effettuato la registrazione, compila il modulo di richiesta. Il team di Promozioni ti farà sapere quando potrai iniziare l'implementazione.

Per saperne di più, consulta i criteri e le norme di partecipazione.

Creare un'origine dati

Puoi utilizzare il metodo accounts.dataSources.create per creare un'origine dati delle promozioni. Se è disponibile un'origine dati delle promozioni esistente, utilizza il metodo accounts.dataSources.list per recuperare tutte le origini dati. Puoi quindi utilizzare il campo name dell'origine dati delle promozioni per creare promozioni.

La seguente richiesta mostra come creare un'origine dati per l'aggiunta di promozioni:

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

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

Sostituisci quanto segue:

  • {ACCOUNT_ID}: l'identificatore univoco del tuo account come visualizzato nell'interfaccia utente di Merchant Center.
  • {DISPLAY_NAME}: il nome visualizzato dell'origine dati.
  • {CONTENT_LANGUAGE}: il codice lingua ISO 639-1 a due lettere dei prodotti nell'origine dati.
  • {TARGET_COUNTRY}: il codice di territorio CLDR del paese di destinazione in cui vuoi che le promozioni siano visibili.

Una volta eseguita la richiesta, viene visualizzata la seguente risposta che contiene i dettagli dell'origine dati delle promozioni appena creata:

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

Crea promozioni

Puoi utilizzare il metodo accounts.promotions.insert per creare o aggiornare una promozione. Il metodo accounts.promotions.insert accetta come input una risorsa promotions e il nome di un'origine dati. Restituisce la promozione nuova o aggiornata, se l'operazione ha esito positivo.

La creazione di una promozione richiede il nome dell'origine dati. Nella richiesta devi anche fornire i valori per i seguenti campi:

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

Google esamina e approva le promozioni prima di distribuirle. Per ulteriori informazioni, consulta la procedura di approvazione delle promozioni.

Ti consigliamo di leggere le norme relative alle promozioni per assicurarti che le promozioni che crei aggiungano valore e rispettino le norme relative agli annunci Shopping.

La seguente richiesta mostra come creare una promozione online:

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

Per informazioni sulle regole applicabili all'impostazione dell'ID promozione, consulta Requisiti minimi per l'attributo ID promozione.

I valori validi per il campo obbligatorio offerType sono NO_CODE e GENERIC_CODE. Se non fornisci uno di questi valori, la richiesta API non va a buon fine con la risposta HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. Viene restituito un messaggio di errore simile se non fornisci nessuno dei campi obbligatori.

Se non fornisci un valore per il campo attributes.genericRedemptionCode, la richiesta non va a buon fine con la risposta HTTP 400 [genericRedemptionCode] No redemption code provided.

I valori dei campi promotion.attributes.promotionDisplayTimePeriod.startTime e promotion.attributes.promotionDisplayTimePeriod.endTime devono essere nel formato yyyy-mm-ddThh:mm:ssZ. Assicurati di sostituire i valori di questi campi con date future.

Per ulteriori informazioni, consulta la specifica dei dati delle promozioni.

Per le best practice sulla creazione di una promozione, consulta Best practice per le promozioni.

Per un elenco degli attributi relativi alle promozioni, consulta Aggiungere gli attributi dei dati strutturati.

Una volta eseguita correttamente la richiesta di creazione della promozione, possono essere necessari alcuni minuti per recuperare la promozione utilizzando l'API o per visualizzarla in Merchant Center.

Di seguito sono riportate alcune promozioni di esempio che puoi utilizzare per iniziare.

Una promozione locale applicabile a tutti i prodotti e a tutti i negozi

La seguente richiesta di esempio mostra come creare una promozione locale applicabile a tutti i prodotti nel tuo account Merchant Center e a tutti i negozi aggiunti nel tuo account Profilo dell'attività collegato.

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

Il campo productApplicability è obbligatorio. Indica l'applicabilità della promozione a tutti i prodotti o solo a prodotti specifici. I valori supportati sono ALL_PRODUCTS e SPECIFIC_PRODUCTS. Per ulteriori informazioni, consulta Scegliere i prodotti per la tua promozione.

Il campo couponValueType è obbligatorio. Indica il tipo di promozione che stai pubblicando. Per l'elenco dei valori di supporto, consulta Tipo di valore del coupon. A seconda del tipo di valore del coupon selezionato, alcuni attributi sono obbligatori.

Il campo minimumPurchaseQuantity ti consente di impostare il valore della quantità minima di acquisto richiesta per utilizzare l'offerta promozionale. Per ulteriori informazioni, consulta la sezione Quantità minima di acquisto per la promozione.

Analogamente, puoi utilizzare il campo minimumPurchaseAmount per impostare l'importo minimo di acquisto richiesto per utilizzare la promozione. Per ulteriori informazioni, consulta la sezione Importo minimo di acquisto.

Per saperne di più sui valori da fornire per creare una promozione locale, consulta le specifiche delle origini dati per le promozioni locali.

Una promozione online che si applica a prodotti selezionati con un codice promozionale

La seguente richiesta di esempio mostra come creare una promozione online applicata a prodotti selezionati con un codice promozionale.

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

Visualizza le promozioni

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

Ad esempio:

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

Sostituisci quanto segue:

  • {ACCOUNT_ID}: l'identificatore univoco del tuo account Merchant Center.
  • {PROMOTION_ID}: l'identificatore univoco della promozione che vuoi recuperare. Il formato è {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

Tieni presente che sono necessari alcuni minuti prima che una promozione appena creata possa essere recuperata utilizzando l'API.

Visualizzare una promozione locale

La seguente richiesta di esempio recupera una promozione locale il cui ID promozione è 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

Una volta che la richiesta è andata a buon fine, viene visualizzata la seguente risposta:

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

Il campo moneyOffAmount in questo esempio fornisce lo sconto offerto nella promozione. Per ulteriori informazioni, consulta la sezione Importo dello sconto monetario di una promozione.

Il campo promotionUrl in questo esempio fornisce il link al sito web del negozio dove gli acquirenti possono trovare ulteriori informazioni sulla promozione. Le promozioni degli annunci di inventario locale restituiscono un errore se non includi il campo promotionUrl.

Visualizzare una promozione online

La seguente richiesta di esempio recupera una promozione online il cui ID promozione è 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}"
}

Il campo itemIdInclusion utilizzato in questo esempio menziona i prodotti idonei per la promozione. Per ulteriori informazioni, consulta ID prodotto per la promozione.

Elenco promozioni

Puoi utilizzare il metodo promotions.list per visualizzare tutte le promozioni create.

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

La risposta contiene l'elenco di tutte le promozioni nel tuo account. Per ogni promozione, puoi visualizzare dettagli come promotionId, redemptionChannel, dataSource, promotionStatus e altri ancora.

Visualizzare lo stato di una promozione

Per visualizzare lo stato di una promozione, consulta l'attributo promotionStatus restituito dal metodo promotions.get o promotions.list.

Il campo promotionStatus può avere i seguenti valori:

  • IN_REVIEW: la promozione è ancora in corso di revisione.
  • REJECTED: la promozione non è approvata.
  • LIVE: la promozione è approvata e attiva.
  • STOPPED: la promozione è stata interrotta dall'account.
  • EXPIRED: la promozione non è più attiva.
  • PENDING: la promozione non è interrotta e tutte le revisioni sono state approvate, ma la data di attivazione è futura.
  • STATE_UNSPECIFIED: stato della promozione sconosciuto.

Per comprendere la procedura di approvazione di una promozione che hai creato, consulta la procedura di approvazione delle promozioni.

Stato della promozione di esempio

I seguenti esempi mostrano la differenza tra richieste andate a buon fine e richieste con errori.

Mappatura dei prodotti mancante

Il seguente corpo della risposta mostra una promozione online non approvata a causa della mancata mappatura dei prodotti.

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

Per risolvere i problemi relativi alle promozioni non approvate e per scoprire come evitare disapprovazioni future, consulta Risolvere i problemi relativi alle promozioni non approvate.

Se una promozione che hai creato non viene approvata, riceverai un'email con il motivo del rifiuto e le istruzioni per risolvere i problemi.

Promozione in fase di valutazione

Il seguente corpo della risposta mostra una promozione ancora in fase di valutazione.

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

Una promozione approvata e pubblicata

Il seguente corpo della risposta mostra una promozione visibile agli acquirenti.

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

Per saperne di più, consulta le Domande frequenti sullo stato della promozione.

Scopri di più