REST Resource: accounts.promotions

Risorsa: promozione

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

Gli attributi di input della promozione obbligatori per superare i controlli di convalida dei dati sono definiti principalmente di seguito:

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. Segui i requisiti minimi per evitare che le promozioni non vengano approvate.

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 per la 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 nella sua 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 calcolate in modo asincrono.

versionNumber

string (int64 format)

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

Se impostato, l'inserimento viene impedito quando il numero di versione è inferiore a quello corrente della promozione esistente. Il reinserimento (ad esempio, l'aggiornamento della promozione dopo 30 giorni) può essere eseguito 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 è in negozio. È lo stesso canale di 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. Il tipo di promozione. Utilizza questo attributo per indicare se i clienti hanno bisogno o meno di un codice coupon per utilizzare la promozione.

genericRedemptionCode

string

(Facoltativo) Codice promozionale generico per la promozione. Da utilizzare con il campo offerType e deve soddisfare i requisiti minimi.

longTitle

string

Obbligatorio. Titolo lungo per la promozione.

couponValueType

enum (CouponValueType)

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

promotionDestinations[]

enum (DestinationEnum)

Obbligatorio. L'elenco di destinazioni a cui si applica la promozione. Se non specifichi una destinazione includendo un valore supportato nell'origine dati, per impostazione predefinita la tua 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, Piattaforme Google, Piattaforme Google locali. Per rappresentare questi valori, utilizza FREE_LISTINGS, FREE_LOCAL_LISTINGS, LOCAL_INVENTORY_ADS. Per ulteriori dettagli, consulta Destinazione della promozione

itemIdInclusion[]

string

(Facoltativo) Filtra prodotto in base all'ID articolo 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.

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 all'applicabilità del prodotto in promozione productApplicability è impostato su specific_products.

itemGroupIdInclusion[]

string

(Facoltativo) Filtra prodotti in base all'ID gruppo di articoli 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.

productTypeInclusion[]

string

(Facoltativo) Filtro prodotto per 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.

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 all'applicabilità del prodotto in promozione productApplicability è impostato su specific_products.

brandExclusion[]

string

(Facoltativo) Filtra i prodotti in base all'esclusione dei brand 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.

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 in promozione productApplicability è impostato su specific_products. per la promozione.

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. Rappresentazione TimePeriod 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) Rappresentazione TimePeriod 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 tempo di visualizzazione per la promozione promotionDisplayTimePeriod non viene specificato, il periodo di tempo di validità della promozione promotionEffectiveTimePeriod determina la data e l'intervallo di tempo in cui la promozione verrà pubblicata su Google.com e negli annunci Shopping.

storeApplicability

enum (StoreApplicability)

(Facoltativo) Indica se la promozione si applica a tutti i negozi o solo a quelli specificati. Le promozioni per gli annunci di inventario locale generano un errore se non viene inclusa alcuna applicabilità del 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 nella promozione. Gli attributi del filtro del negozio 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 saperne di più, consulta la specifica dei dati dell'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 alla 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 confermare che la promozione è valida e può essere utilizzata.

ProductApplicability

A quale prodotto o elenco di prodotti si applica la promozione.

Enum
PRODUCT_APPLICABILITY_UNSPECIFIED I prodotti a cui si applica la promozione non sono noti.
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. È necessario un codice promozionale generico per la promozione 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 di sconto.
PERCENT_OFF Tipo di valore del coupon con percentuale di sconto.
BUY_M_GET_N_MONEY_OFF Acquista una quantità di M e ottieni uno sconto in denaro di N tipo di valore del coupon. 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 solo con descrizione.
FREE_GIFT_WITH_VALUE Un regalo con un valore monetario.
FREE_GIFT_WITH_ITEM_ID Regalo con ID articolo.
FREE_SHIPPING_STANDARD Tipo di valore del coupon di 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 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.

StoreApplicability

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

Enum
STORE_APPLICABILITY_UNSPECIFIED I codici negozio a cui si applica la promozione non sono noti.
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 è approvata.
LIVE La promozione è approvata ed è attiva.
STOPPED La promozione è stata interrotta dal commerciante.
EXPIRED La promozione non è più attiva.
PENDING La promozione non viene interrotta e tutte le revisioni sono state approvate, ma la data attiva è una data 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. 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 per facilitare la risoluzione del problema.

applicableCountries[]

string

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

Gravità

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.