REST Resource: accounts.promotions

Risorsa: Promozione

Rappresenta una promozione. Per ulteriori dettagli, leggi gli articoli seguenti.

Di seguito sono definiti principalmente gli attributi di input delle promozioni obbligatori per superare i controlli di convalida dei dati:

Dopo l'inserimento o l'aggiornamento di un input della promozione, potrebbero essere necessari diversi minuti prima che sia possibile recuperare la promozione finale.

Rappresentazione 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
}
Campi
name

string

Identificatore. Il nome della promozione. Formato: accounts/{account}/promotions/{promotion}
promotionId

string

Obbligatorio. L'utente ha fornito l'ID promozione per identificare in modo univoco la promozione. Rispetta i requisiti minimi per evitare la mancata approvazione delle promozioni.
contentLanguage

string

Obbligatorio. Il codice lingua ISO 639-1 di due lettere per la promozione.

Le promozioni sono disponibili solo per alcune lingue selezionate.
targetCountry

string

Obbligatorio. Il paese di destinazione utilizzato come parte dell'identificatore univoco. Rappresentato come codice di territorio CLDR.

Le promozioni sono disponibili solo in alcuni paesi, Schede senza costi e annunci Shopping Annunci di inventario locale
redemptionChannel[]

enum (RedemptionChannel)

Obbligatorio. Canale di utilizzo della promozione. È richiesto almeno un canale.
dataSource

string

Solo output. L'origine dati principale della promozione.
attributes

object (Attributes)

(Facoltativo) Un elenco di attributi della promozione.
customAttributes[]

object (CustomAttribute)

(Facoltativo) Un elenco di attributi personalizzati (forniti dal commerciante). Può essere utilizzato anche per inviare qualsiasi attributo della specifica dei dati in forma generica (ad esempio, { "name": "size type", "value": "regular" }). Ciò è utile per inviare attributi non esposti esplicitamente dall'API.
promotionStatus

object (PromotionStatus)

Solo output. Lo stato di una promozione, i problemi di convalida dei dati, ovvero le informazioni su una promozione calcolata in modo asincrono.
versionNumber

string (int64 format)

(Facoltativo) Rappresenta la versione esistente (aggiornamento) della promozione, che può essere utilizzata per mantenere l'ordine corretto quando vengono eseguiti più aggiornamenti contemporaneamente.

Se impostato, l'inserimento viene impedito quando il numero di versione è inferiore al numero di versione corrente della promozione esistente. La reintegrazione (ad esempio l'aggiornamento della promozione dopo 30 giorni) può essere eseguita con l'attuale versionNumber.

Se l'operazione viene impedita, verrà restituita l'eccezione interrotta.

RedemptionChannel

Canale di una promozione.

Enum
REDEMPTION_CHANNEL_UNSPECIFIED Indica che il canale non è specificato.
IN_STORE Indica che il canale è disponibile in negozio. È lo stesso canale local utilizzato per products.
ONLINE Indica che il canale è online.

Attributi

Attributi.

Rappresentazione 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
}
Campi
productApplicability

enum (ProductApplicability)

Obbligatorio. Applicabilità della promozione a tutti i prodotti o solo a prodotti specifici.
offerType

enum (OfferType)

Obbligatorio. Tipo della promozione. Utilizza questo attributo per indicare se i clienti hanno bisogno o meno di un codice coupon per utilizzare la tua promozione.
genericRedemptionCode

string

(Facoltativo) Codice promozionale generico per la promozione. Per essere utilizzato con il campo offerType e deve soddisfare i requisiti minimi.
longTitle

string

Obbligatorio. Titolo lungo della promozione.
couponValueType

enum (CouponValueType)

Obbligatorio. L'attributo tipo di valore del coupon per indicare il tipo di promozione che vuoi pubblicare. A seconda del tipo di valore del coupon selezionato, alcuni attributi sono obbligatori.
promotionDestinations[]

enum (DestinationEnum)

Obbligatorio. L'elenco delle destinazioni a cui si applica la promozione. Se non specifichi una destinazione includendo un valore supportato nell'origine dati, per impostazione predefinita la promozione verrà visualizzata negli annunci Shopping e nelle schede senza costi.

Potresti aver già inviato i seguenti valori come destinazioni per i tuoi prodotti: Shopping Actions, Surfaces across Google, Local surfaces across Google. Per rappresentare questi valori, utilizza FREE_LISTINGS, FREE_LOCAL_LISTINGS, LOCAL_INVENTORY_ADS. Per maggiori dettagli, consulta Destinazione della promozione.
itemIdInclusion[]

string

(Facoltativo) Filtro dei prodotti per ID articolo per la promozione. Gli attributi del filtro di prodotto si applicano solo quando l'attributo prodotti idonei alla promozione productApplicability è impostato su specific_products.
brandInclusion[]

string

(Facoltativo) Filtro prodotto in base al brand per la promozione. Gli attributi del filtro di prodotto si applicano solo quando l'attributo prodotti idonei alla promozione productApplicability è impostato su specific_products.
itemGroupIdInclusion[]

string

(Facoltativo) Filtro dei prodotti per ID gruppo di articoli per la promozione. Gli attributi del filtro di prodotto si applicano solo quando l'attributo prodotti idonei alla promozione [productApplicability] è impostato su specific_products.
productTypeInclusion[]

string

(Facoltativo) Filtro dei prodotti per tipo di prodotto per la promozione. Gli attributi del filtro di prodotto si applicano solo quando l'attributo prodotti idonei alla promozione productApplicability è impostato su specific_products.
itemIdExclusion[]

string

(Facoltativo) Filtra il prodotto in base all'esclusione di ID articolo per la promozione. Gli attributi del filtro di prodotto si applicano solo quando l'attributo prodotti idonei alla promozione productApplicability è impostato su specific_products.
brandExclusion[]

string

(Facoltativo) Filtro dei prodotti per esclusione del brand per la promozione. Gli attributi del filtro di prodotto si applicano solo quando l'attributo prodotti idonei alla promozione productApplicability è impostato su specific_products.
itemGroupIdExclusion[]

string

(Facoltativo) Filtro dei prodotti per ID gruppo di articoli. Gli attributi del filtro di prodotto si applicano solo quando l'attributo prodotti idonei all'applicabilità del prodotto della promozione productApplicability è impostato su specific_products.
productTypeExclusion[]

string

(Facoltativo) Filtro prodotto in base all'esclusione del tipo di prodotto per la promozione. Gli attributi del filtro di prodotto si applicano solo quando l'attributo prodotti idonei all'applicabilità del prodotto in promozione productApplicability è impostato su specific_products.
minimumPurchaseAmount

object (Price)

(Facoltativo) Soglia minima di acquisto per la promozione.
minimumPurchaseQuantity

string (int64 format)

(Facoltativo) Quantità minima di acquisto per la promozione.
limitQuantity

string (int64 format)

(Facoltativo) Quantità massima di acquisto per la promozione.
limitValue

object (Price)

(Facoltativo) Prezzo massimo del prodotto per la promozione.
percentOff

string (int64 format)

(Facoltativo) Lo sconto percentuale offerto nella promozione.
moneyOffAmount

object (Price)

(Facoltativo) L'importo dello sconto offerto nella promozione.
getThisQuantityDiscounted

string (int64 format)

(Facoltativo) Il numero di articoli scontati nella promozione. L'attributo è impostato quando couponValueType è uguale a buy_m_get_n_money_off o buy_m_get_n_percent_off.
freeGiftValue

object (Price)

(Facoltativo) Valore del regalo per la promozione.
freeGiftDescription

string

(Facoltativo) Descrizione del regalo per la promozione.
freeGiftItemId

string

(Facoltativo) ID articolo del regalo per la promozione.
promotionEffectiveTimePeriod

object (Interval)

Obbligatorio. TimePeriod rappresentazione delle date di validità della promozione. Questo attributo specifica che la promozione può essere testata nel tuo negozio online durante questo periodo di tempo.
promotionDisplayTimePeriod

object (Interval)

(Facoltativo) TimePeriod rappresentazione delle date di visualizzazione della promozione. Questo attributo specifica la data e l'intervallo di tempo in cui la promozione verrà pubblicata su Google.com e negli annunci Shopping. Se l'attributo periodo di visualizzazione della promozione promotionDisplayTimePeriod non è specificato, il periodo di tempo di validità della promozione promotionEffectiveTimePeriod determina la data e l'intervallo di tempo in cui la promozione sarà attiva su Google.com e negli annunci Shopping.
storeApplicability

enum (StoreApplicability)

(Facoltativo) Indica se la promozione si applica a tutti i negozi o solo a negozi specifici. Le promozioni degli annunci di inventario locale generano un errore se non è inclusa l'applicabilità al negozio. Se storeApplicability è impostato su ALL_STORES e storeCodesInclusion o score_code_exclusion è impostato su un valore, viene generato un errore INVALID_ARGUMENT.
storeCodesInclusion[]

string

(Facoltativo) Codici negozio da includere per la promozione. Gli attributi del filtro dei negozi si applicano solo quando l'attributo storeApplicability è impostato su specific_stores.

Codice negozio (l'ID negozio presente nel profilo dell'attività) del negozio fisico in cui viene venduto il prodotto. Per ulteriori informazioni, consulta la specifica dei dati di inventario locale dei prodotti.
storeCodesExclusion[]

string

(Facoltativo) Codici negozio da escludere per la promozione. Gli attributi del filtro del negozio si applicano solo quando l'attributo storeApplicability è impostato su specific_stores.
promotionUrl

string

(Facoltativo) URL della pagina del sito del commerciante in cui viene visualizzata la promozione. Le promozioni per gli annunci di inventario locale generano un errore se non viene incluso promotionUrl. L'URL viene utilizzato per verificare l'utilizzabilità e la validità della promozione.

ProductApplicability

Il prodotto o l'elenco di prodotti a cui si applica la promozione.

Enum
PRODUCT_APPLICABILITY_UNSPECIFIED Non è noto a quali prodotti si applica la promozione.
ALL_PRODUCTS Applicabile a tutti i prodotti.
SPECIFIC_PRODUCTS Applicabile a un solo prodotto o elenco di prodotti.

OfferType

Tipo di offerta di una promozione.

Enum
OFFER_TYPE_UNSPECIFIED Tipo di offerta sconosciuto.
NO_CODE Tipo di offerta senza codice.
GENERIC_CODE Tipo di offerta con un codice. Il codice promozionale generico per la promozione è obbligatorio quando offerType = GENERIC_CODE.

CouponValueType

Tipo di valore del coupon di una promozione.

Enum
COUPON_VALUE_TYPE_UNSPECIFIED Indica che il tipo di valore del coupon non è specificato.
MONEY_OFF Tipo di valore del coupon sconto.
PERCENT_OFF Tipo di valore del coupon con percentuale di sconto.
BUY_M_GET_N_MONEY_OFF Tipo di valore del coupon Acquista una quantità M e ricevi uno sconto in denaro di N. minimumPurchaseQuantity e getThisQuantityDiscounted devono essere presenti. Deve essere presente anche moneyOffAmount.
BUY_M_GET_N_PERCENT_OFF Acquista una quantità M e ottieni una percentuale di sconto pari a N per il tipo di valore del coupon. minimumPurchaseQuantity e getThisQuantityDiscounted devono essere presenti. Deve essere presente anche percent_off_percentage.
BUY_M_GET_MONEY_OFF Acquista una quantità M e ottieni uno sconto in denaro. minimumPurchaseQuantity e moneyOffAmount devono essere presenti.
BUY_M_GET_PERCENT_OFF Acquista una quantità M e ottieni uno sconto in denaro. minimumPurchaseQuantity e percent_off_percentage devono essere presenti.
FREE_GIFT Regalo senza costi solo con descrizione.
FREE_GIFT_WITH_VALUE Regalo con valore monetario.
FREE_GIFT_WITH_ITEM_ID Regalo con ID articolo.
FREE_SHIPPING_STANDARD Tipo di valore del coupon per la spedizione gratuita standard.
FREE_SHIPPING_OVERNIGHT Tipo di valore del coupon per la spedizione gratuita il giorno successivo.
FREE_SHIPPING_TWO_DAY Tipo di valore del coupon con spedizione gratuita in due giorni.

DestinationEnum

Valori di destinazione.

Enum
DESTINATION_ENUM_UNSPECIFIED Non specificato.
SHOPPING_ADS Annunci Shopping.
DISPLAY_ADS Annunci display.
LOCAL_INVENTORY_ADS Annunci di prodotti disponibili localmente.
FREE_LISTINGS Schede senza costi.
FREE_LOCAL_LISTINGS Schede di prodotto locali senza costi.
YOUTUBE_SHOPPING YouTube Shopping.
YOUTUBE_SHOPPING_CHECKOUT Pagamento su YouTube Shopping.
YOUTUBE_AFFILIATE Programma di affiliazione di YouTube.
FREE_VEHICLE_LISTINGS Schede senza costi di veicoli.
VEHICLE_ADS Annunci di veicoli.
CLOUD_RETAIL Cloud per la vendita al dettaglio.
LOCAL_CLOUD_RETAIL Cloud per la vendita al dettaglio locale.

StoreApplicability

Codici negozio o elenco di codici negozio a cui si applica la promozione. Solo per le promozioni degli annunci di inventario locale.

Enum
STORE_APPLICABILITY_UNSPECIFIED Non è noto a quali codici negozio si applica la promozione.
ALL_STORES La promozione si applica a tutti i negozi.
SPECIFIC_STORES La promozione si applica solo ai negozi specificati.

PromotionStatus

Lo stato della promozione.

Rappresentazione JSON 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
Campi
destinationStatuses[]

object (DestinationStatus)

Solo output. Le destinazioni previste per la promozione.
itemLevelIssues[]

object (ItemLevelIssue)

Solo output. Un elenco dei problemi associati alla promozione.
creationDate

string (Timestamp format)

Solo output. Data di creazione della promozione nel formato ISO 8601: data, ora e offset, ad esempio 2020-01-02T09:00:00+01:00 o 2020-01-02T09:00:00Z
lastUpdateDate

string (Timestamp format)

Solo output. Data dell'ultimo aggiornamento dello stato della promozione nel formato ISO 8601: data, ora e offset, ad esempio 2020-01-02T09:00:00+01:00 o 2020-01-02T09:00:00Z

DestinationStatus

Lo stato della destinazione specificata.

Rappresentazione JSON 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
Campi
reportingContext

enum (ReportingContextEnum)

Solo output. Il nome della destinazione della promozione.
status

enum (State)

Solo output. Lo stato della destinazione specificata.

Stato

Lo stato attuale della promozione.

Enum
STATE_UNSPECIFIED Stato promozione sconosciuto.
IN_REVIEW La promozione è in corso di revisione.
REJECTED La promozione non è stata approvata.
LIVE La promozione sia approvata e attiva.
STOPPED La promozione è stata interrotta dal commerciante.
EXPIRED La promozione non è più attiva.
PENDING La promozione non è interrotta e tutte le revisioni sono state approvate, ma la data di attivazione è futura.

ItemLevelIssue

Il problema associato alla promozione.

Rappresentazione JSON 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
Campi
code

string

Solo output. Il codice di errore del problema.
severity

enum (Severity)

Solo output. L'impatto di questo problema sulla pubblicazione della promozione.
resolution

string

Solo output. Indica se il problema può essere risolto dal commerciante.
attribute

string

Solo output. Il nome dell'attributo, se il problema è causato da un singolo attributo.
reportingContext

enum (ReportingContextEnum)

Solo output. La destinazione a cui si applica il problema.
description

string

Solo output. Una breve descrizione del problema in inglese.
detail

string

Solo output. Una descrizione dettagliata del problema in inglese.
documentation

string

Solo output. L'URL di una pagina web che possa aiutarci a risolvere il problema.
applicableCountries[]

string

Solo output. Elenco dei codici paese (ISO 3166-1 alpha-2) in cui il problema si applica all'offerta.

Gravità

La gravità del problema.

Enum
SEVERITY_UNSPECIFIED Non specificato.
NOT_IMPACTED Questo problema rappresenta un avviso e non ha un impatto diretto sulla promozione.
DEMOTED La promozione è retrocessa e molto probabilmente avrà un rendimento limitato nei risultati di ricerca
DISAPPROVED Il problema non approva la promozione.

Metodi

get

 Recupera la promozione dal tuo account Merchant Center.

insert

 Inserisce una promozione per il tuo account Merchant Center.

list

 Elenca le promozioni nel tuo account Merchant Center.