API Offers

L'API Offers fa parte di un programma beta chiuso e solo su invito. Se sei stato invitato al programma, rivolgiti al tuo rappresentante di Meta per ottenere l'accesso.

Usando questa API, puoi aggiungere informazioni sull'offerta al tuo catalogo prodotti per abilitare il merchandising delle tue offerte su Facebook e Instagram. Per i venditori che hanno abilitato la funzione di acquisto su Facebook o Instagram, gli acquirenti potranno riscattare le tue offerte direttamente all'interno della famiglia di app di Meta.

Creazione delle offerte

Puoi creare offerte tramite un elenco di offerte o manualmente tramite il Gestore delle vendite.

Elenco

Per creare un nuovo elenco di offerte, effettua una richiesta POST al segmento /{product_catalog_id}/product_feeds e imposta feed_type su OFFER. Quando pubblichi su questo segmento, viene creato un elenco prodotti di tipo Offerta per il catalogo specificato nel campo product_catalog_id.

Una volta creato l'elenco di offerte, puoi caricare i dati delle tue offerte tramite una richiesta POST al segmento /{product_feed_id}/uploads.

Colonne dell'elenco

Puoi impostare la maggior parte dei campi disponibili elencati sotto come colonne nel file elenco. Solo i campi contrassegnati di sola lettura non possono essere impostati durante la creazione.

Glossario

Insiemi di prodotti

Un insieme di prodotti è un gruppo di articoli correlati all'interno di un catalogo prodotti.

Articoli dell'offerta

Questi sono i prodotti per i quali è valida un'offerta.

Prerequisiti dell'offerta

Questi sono i presupposti che devono essere soddisfatti per la presentazione dell'offerta. Ad esempio, puoi determinare che l'offerta è valida solo quando le persone acquistano una specifica quantità minima di prodotti o raggiungono una quantità o un valore minimi dei singoli prodotti. Attualmente, i prodotti prerequisito derivano dai prodotti target. Ad esempio, un'offerta del 20% su tutte le scarpe significa che devono essere soddisfatti i requisiti di subtotale/quantità minimi per le scarpe nel carrello.

Tipo di applicazione dell'offerta

Il tipo di applicazione dell'offerta specifica in che modo un'offerta viene applicata al momento dell'acquisto sul tuo sito web o nell'ambito della procedura di acquisto su Facebook. Ad esempio, il tipo di applicazione può essere usato per determinare se un'offerta viene applicata automaticamente al momento dell'acquisto o se richiede un codice coupon per essere riscattata. Il tipo di applicazione definisce anche il comportamento della combinazione di un'offerta con altre offerte. Per maggiori dettagli consulta Combinazione di offerte.

Campi di base

I campi sottostanti possono essere usati per configurare tutti i tipi di offerte.

Campo Descrizione

Campo	Descrizione
`id` tipo: `numeric string`	Sola lettura. Un identificatore unico (ID Facebook) per questo articolo.
`offer_id` tipo: `string`	Obbligatorio. Un identificatore per l'offerta fornito dal venditore. Questo campo è usato per identificare in modo unico un'offerta all'interno di un catalogo.
`title` tipo: `string`	Facoltativo. Un titolo per l'articolo in offerta. Al momento questo titolo è usato solo per consentire di identificare le offerte nel Gestore delle vendite e non viene mostrato agli acquirenti.
`description` tipo: `string`	Sola lettura. La descrizione generata automaticamente dell'offerta.
`application_type` tipo: `enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}`	Obbligatorio. Determina come e quando viene applicata un'offerta. Le opzioni disponibili sono: `SALE`: gli articoli vengono direttamente scontati, mostrati agli acquirenti come prezzi barrati. Queste offerte non richiedono prerequisiti da parte dell'acquirente e non sono correlate ad altri articoli al momento dell'acquisto. Viene sempre selezionata la promozione che produce il prezzo più basso di un articolo, dal momento che le promozioni non vengono mai combinate. Le promozioni possono essere cumulabili con altri tipi di offerte, ma vengono sempre applicate per prime. Se un prodotto ha già il campo `sale_price` impostato, il prezzo finale viene calcolato usando il `sale_price` come prezzo base. `AUTOMATIC_AT_CHECKOUT`: l'offerta viene applicata automaticamente al momento dell'acquisto, se l'acquirente soddisfa i criteri di riscatto necessari. La configurazione di questa offerta impedisce che sia classificata come promozione, pertanto può essere combinata solo con offerte promozionali. Possono essere attive fino a 25 di queste offerte alla volta. `BUYER_APPLIED`: questa offerta viene applicata al momento dell'acquisto in base a un'azione intrapresa dall'acquirente, come l'inserimento di un codice promozionale. Queste offerte al momento non possono essere cumulabili tra di loro o con offerte applicate automaticamente al momento dell'acquisto. Richiede che venga fornito uno tra [`public_coupon_code`, `coupon_codes`].
`coupon_codes` tipo: `Array<string>`	Lista dei codici coupon che non distinguono tra maiuscole e minuscole che i clienti usano al momento dell'acquisto per riscattare l'offerta. È consentito un massimo di 100 codici coupon. Ad esempio: `["10OFF", "HOLIDAY_SALE"]` I codici coupon possono essere specificati solo quando il parametro `application_type` è `BUYER_APPLIED`. Se questo campo è impostato, `public_coupon_code` deve essere nullo.
`public_coupon_code` tipo: `string`	Facoltativo. Un unico codice coupon che non distingue tra maiuscole e minuscole che sarà incluso nell'offerta e precompilato al momento dell'acquisto se l'acquirente soddisfa i prerequisiti dell'offerta. Per impostazione predefinita, le offerte con codici coupon non sono visibilmente promosse agli acquirenti su piattaforme di shopping di Facebook o Instagram come una pagina dei dettagli del prodotto, per evitare che codici privati o segreti trapelino vengano involontariamente mostrati agli acquirenti. Puoi cambiare questo comportamento specificando un codice coupon pubblico da usare per la promozione della tua offerta. Le offerte con codici pubblici saranno visualizzate nello stesso modo delle offerte con `application_typeAUTOMATIC_AT_CHECKOUT`, ma includeranno anche il testo del codice. Un codice coupon pubblico non può superare i 20 caratteri e il tuo catalogo può contenere al massimo 10 offerte attive con codici coupon pubblici alla volta. Un codice coupon pubblico può essere impostato solo quando il parametro `application_type` è `BUYER_APPLIED`. Se questo campo è impostato, `coupon_codes` deve essere nullo.
`start_date_time` tipo: `timestamp`	Obbligatorio. Indicazione temporale Unix, in secondi, dell'inizio dell'offerta. L'input può essere o un'indicazione temporale Unix, in secondi, o una stringa di data in formato ISO-8601 (ad es. 2021-09-25T12:34:56Z).
`end_date_time` tipo: `timestamp`	Facoltativo. L'impostazione predefinita è `null`. Indicazione temporale Unix, in secondi, della fine dell'offerta. Se lasciato vuoto o `null`, l'offerta non ha data di fine. L'input può essere o un'indicazione temporale Unix, in secondi, o una stringa di data in formato ISO-8601 (ad es. 2021-09-25T12:34:56Z).
`min_quantity` tipo: `int64`	Facoltativo. L'impostazione predefinita è 0. Usa questo campo se la tua offerta è valida solo quando il cliente acquista un numero minimo di prodotti. Questo campo rappresenta il numero di prodotti che il cliente deve acquistare affinché l'offerta sia valida. Ad esempio: "Acquista 5 camicie e ottieni il 20% di sconto". Può essere impostato solo uno tra i valori `min_quantity` e `min_subtotal`.
`min_subtotal` tipo: `string`	Facoltativo. L'impostazione predefinita è `null`. Usa questo campo se la tua offerta è valida solo quando l'ordine del cliente soddisfa un valore subtotale specifico. Il subtotale dei prodotti prerequisito deve essere uguale o superiore a questo valore per l'offerta. Se non vengono impostati prodotti prerequisito espliciti, i prodotti target vengono utilizzati come prodotti prerequisito. Questo campo deve essere formattato come l'importo, seguito dal codice valuta ISO a 3 cifre, con uno spazio tra importo e valuta. Ad esempio: la stringa "30,99 USD" rappresenta un subtotale prerequisito di $30,99 per l'applicazione dell'offerta. Può essere impostato solo uno tra i valori `min_quantity` e `min_subtotal`.
`redeem_limit_per_user` tipo: `int64`	Facoltativo. L'impostazione predefinita è 0 (illimitato). Il numero massimo di volte in cui l'offerta può essere utilizzata da un singolo utente. Imposta questo campo su 1 per creare un codice coupon monouso. Questo campo deve essere impostato solo se il parametro `application_type` è `BUYER_APPLIED`.
`value_type` tipo: `enum {FIXED_AMOUNT, PERCENTAGE}`	Obbligatorio. Il tipo di sconto previsto dall'offerta. Le opzioni disponibili sono: `FIXED_AMOUNT`: applica uno sconto del valore indicato in `fixed_amount_off`. `PERCENTAGE`: applica una percentuale di sconto del valore indicato in `percent_off`.
`fixed_amount_off` tipo: `string`	Obbligatorio, se `value_type` è impostato su `FIXED_AMOUNT`. L'importo dello sconto dell'offerta. Deve essere formattato come l'importo, seguito dal codice valuta ISO a 3 cifre, con uno spazio tra importo e valuta. Ad esempio, la stringa "30,99 USD" rappresenta uno sconto di $30,99. Questo campo deve essere impostato solo se il parametro `value_type` è `FIXED_AMOUNT`.
`percent_off` tipo: `int64`	Obbligatorio, se `value_type` è impostato su `PERCENTAGE`. La percentuale di sconto dell'offerta. Deve essere un numero intero compreso tra 0 e 100. Ad esempio, "30" rappresenta uno sconto del 30%. Il campo deve essere impostato solo se il parametro `value_type` è `PERCENTAGE`.
`target_granularity` tipo: `enum {ITEM_LEVEL, ORDER_LEVEL}`	Obbligatorio. La granularità alla quale si applica lo sconto dell'offerta. Le opzioni disponibili sono: `ITEM_LEVEL`: rappresenta uno sconto applicato a ciascuno degli articoli target nel carrello. `ORDER_LEVEL`: rappresenta uno sconto applicato al totale degli articoli target nel carrello. Ad esempio, se hai un'offerta "$30 di sconto sulle scarpe" con 3 paia di scarpe nel carrello, `ITEM_LEVEL` applicherà $30 di sconto su ogni paio di scarpe (per un valore di $90), mentre `ORDER_LEVEL` applicherà $30 di sconto sulla somma delle 3 paia di scarpe (per un valore massimo di $30). Tieni presente che le offerte con granularità `ORDER_LEVEL` possono comportare assegnazioni dello sconto all'acquisto che non si suddividono in maniera uniforme tra gli articoli di un ordine. Gestire queste assegnazioni dello sconto irregolari può comportare una maggiore complessità al momento dell'evasione o in caso di rimborsi.
`offer_terms` tipo: `string`	Facoltativo. Eventuali condizioni aggiuntive che determinino l'uso dell'offerta da parte di un acquirente. Max. 2500 caratteri. Facebook genererà automaticamente i termini che descrivono l'offerta in base alla sua configurazione. Oltre a queste condizioni, puoi usare `offer_terms` per aggiungere una descrizione delle tue condizioni per l'offerta. Queste condizioni saranno visualizzate sotto le condizioni dell'offerta di Facebook. Il contenuto deve seguire le nostre normative sui contenuti.

id

tipo: numeric string

Sola lettura.

Un identificatore unico (ID Facebook) per questo articolo.

offer_id

tipo: string

Obbligatorio.

Un identificatore per l'offerta fornito dal venditore.

Questo campo è usato per identificare in modo unico un'offerta all'interno di un catalogo.

title

tipo: string

Facoltativo.

Un titolo per l'articolo in offerta.

Al momento questo titolo è usato solo per consentire di identificare le offerte nel Gestore delle vendite e non viene mostrato agli acquirenti.

description

tipo: string

Sola lettura.

La descrizione generata automaticamente dell'offerta.

application_type

tipo: enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}

Obbligatorio.

Determina come e quando viene applicata un'offerta. Le opzioni disponibili sono:

SALE: gli articoli vengono direttamente scontati, mostrati agli acquirenti come prezzi barrati. Queste offerte non richiedono prerequisiti da parte dell'acquirente e non sono correlate ad altri articoli al momento dell'acquisto. Viene sempre selezionata la promozione che produce il prezzo più basso di un articolo, dal momento che le promozioni non vengono mai combinate. Le promozioni possono essere cumulabili con altri tipi di offerte, ma vengono sempre applicate per prime. Se un prodotto ha già il campo sale_price impostato, il prezzo finale viene calcolato usando il sale_price come prezzo base.
AUTOMATIC_AT_CHECKOUT: l'offerta viene applicata automaticamente al momento dell'acquisto, se l'acquirente soddisfa i criteri di riscatto necessari. La configurazione di questa offerta impedisce che sia classificata come promozione, pertanto può essere combinata solo con offerte promozionali. Possono essere attive fino a 25 di queste offerte alla volta.
BUYER_APPLIED: questa offerta viene applicata al momento dell'acquisto in base a un'azione intrapresa dall'acquirente, come l'inserimento di un codice promozionale. Queste offerte al momento non possono essere cumulabili tra di loro o con offerte applicate automaticamente al momento dell'acquisto. Richiede che venga fornito uno tra [public_coupon_code, coupon_codes].

coupon_codes

tipo: Array<string>

Lista dei codici coupon che non distinguono tra maiuscole e minuscole che i clienti usano al momento dell'acquisto per riscattare l'offerta. È consentito un massimo di 100 codici coupon. Ad esempio: ["10OFF", "HOLIDAY_SALE"]

I codici coupon possono essere specificati solo quando il parametro application_type è BUYER_APPLIED.

Se questo campo è impostato, public_coupon_code deve essere nullo.

public_coupon_code

tipo: string

Facoltativo.

Un unico codice coupon che non distingue tra maiuscole e minuscole che sarà incluso nell'offerta e precompilato al momento dell'acquisto se l'acquirente soddisfa i prerequisiti dell'offerta.

Per impostazione predefinita, le offerte con codici coupon non sono visibilmente promosse agli acquirenti su piattaforme di shopping di Facebook o Instagram come una pagina dei dettagli del prodotto, per evitare che codici privati o segreti trapelino vengano involontariamente mostrati agli acquirenti. Puoi cambiare questo comportamento specificando un codice coupon pubblico da usare per la promozione della tua offerta. Le offerte con codici pubblici saranno visualizzate nello stesso modo delle offerte con application_typeAUTOMATIC_AT_CHECKOUT, ma includeranno anche il testo del codice.

Un codice coupon pubblico non può superare i 20 caratteri e il tuo catalogo può contenere al massimo 10 offerte attive con codici coupon pubblici alla volta.

Un codice coupon pubblico può essere impostato solo quando il parametro application_type è BUYER_APPLIED.

Se questo campo è impostato, coupon_codes deve essere nullo.

start_date_time

tipo: timestamp

Obbligatorio.

Indicazione temporale Unix, in secondi, dell'inizio dell'offerta.

L'input può essere o un'indicazione temporale Unix, in secondi, o una stringa di data in formato ISO-8601 (ad es. 2021-09-25T12:34:56Z).

end_date_time

tipo: timestamp

Facoltativo. L'impostazione predefinita è null.

Indicazione temporale Unix, in secondi, della fine dell'offerta. Se lasciato vuoto o null, l'offerta non ha data di fine.

L'input può essere o un'indicazione temporale Unix, in secondi, o una stringa di data in formato ISO-8601 (ad es. 2021-09-25T12:34:56Z).

min_quantity

tipo: int64

Facoltativo. L'impostazione predefinita è 0.

Usa questo campo se la tua offerta è valida solo quando il cliente acquista un numero minimo di prodotti.

Questo campo rappresenta il numero di prodotti che il cliente deve acquistare affinché l'offerta sia valida. Ad esempio: "Acquista 5 camicie e ottieni il 20% di sconto".

Può essere impostato solo uno tra i valori min_quantity e min_subtotal.

min_subtotal

tipo: string

Facoltativo. L'impostazione predefinita è null.

Usa questo campo se la tua offerta è valida solo quando l'ordine del cliente soddisfa un valore subtotale specifico.

Il subtotale dei prodotti prerequisito deve essere uguale o superiore a questo valore per l'offerta. Se non vengono impostati prodotti prerequisito espliciti, i prodotti target vengono utilizzati come prodotti prerequisito.

Questo campo deve essere formattato come l'importo, seguito dal codice valuta ISO a 3 cifre, con uno spazio tra importo e valuta. Ad esempio: la stringa "30,99 USD" rappresenta un subtotale prerequisito di $30,99 per l'applicazione dell'offerta.

Può essere impostato solo uno tra i valori min_quantity e min_subtotal.

redeem_limit_per_user

tipo: int64

Facoltativo. L'impostazione predefinita è 0 (illimitato).

Il numero massimo di volte in cui l'offerta può essere utilizzata da un singolo utente.

Imposta questo campo su 1 per creare un codice coupon monouso.

Questo campo deve essere impostato solo se il parametro application_type è BUYER_APPLIED.

value_type

tipo: enum {FIXED_AMOUNT, PERCENTAGE}

Obbligatorio.

Il tipo di sconto previsto dall'offerta.

Le opzioni disponibili sono:

FIXED_AMOUNT: applica uno sconto del valore indicato in fixed_amount_off.
PERCENTAGE: applica una percentuale di sconto del valore indicato in percent_off.

fixed_amount_off

tipo: string

Obbligatorio, se value_type è impostato su FIXED_AMOUNT.

L'importo dello sconto dell'offerta. Deve essere formattato come l'importo, seguito dal codice valuta ISO a 3 cifre, con uno spazio tra importo e valuta. Ad esempio, la stringa "30,99 USD" rappresenta uno sconto di $30,99.

Questo campo deve essere impostato solo se il parametro value_type è FIXED_AMOUNT.

percent_off

tipo: int64

Obbligatorio, se value_type è impostato su PERCENTAGE.

La percentuale di sconto dell'offerta. Deve essere un numero intero compreso tra 0 e 100. Ad esempio, "30" rappresenta uno sconto del 30%.

Il campo deve essere impostato solo se il parametro value_type è PERCENTAGE.

target_granularity

tipo: enum {ITEM_LEVEL, ORDER_LEVEL}

Obbligatorio.

La granularità alla quale si applica lo sconto dell'offerta.

Le opzioni disponibili sono:

ITEM_LEVEL: rappresenta uno sconto applicato a ciascuno degli articoli target nel carrello.
ORDER_LEVEL: rappresenta uno sconto applicato al totale degli articoli target nel carrello. Ad esempio, se hai un'offerta "$30 di sconto sulle scarpe" con 3 paia di scarpe nel carrello, ITEM_LEVEL applicherà $30 di sconto su ogni paio di scarpe (per un valore di $90), mentre ORDER_LEVEL applicherà $30 di sconto sulla somma delle 3 paia di scarpe (per un valore massimo di $30).

Tieni presente che le offerte con granularità ORDER_LEVEL possono comportare assegnazioni dello sconto all'acquisto che non si suddividono in maniera uniforme tra gli articoli di un ordine. Gestire queste assegnazioni dello sconto irregolari può comportare una maggiore complessità al momento dell'evasione o in caso di rimborsi.

offer_terms

tipo: string

Facoltativo.

Eventuali condizioni aggiuntive che determinino l'uso dell'offerta da parte di un acquirente. Max. 2500 caratteri.

Facebook genererà automaticamente i termini che descrivono l'offerta in base alla sua configurazione. Oltre a queste condizioni, puoi usare offer_terms per aggiungere una descrizione delle tue condizioni per l'offerta. Queste condizioni saranno visualizzate sotto le condizioni dell'offerta di Facebook.

Il contenuto deve seguire le nostre normative sui contenuti.

Definizione dei prodotti idonei

Sia gli articoli target per i quali è valida un'offerta sia gli articoli prerequisito, che un acquirente deve acquistare per riscattare l'offerta, sono definiti da insiemi di prodotti. L'API Offers supporta diversi modi per specificare questi insiemi di prodotti, ma può essere usato un solo metodo per tipo di insieme di prodotti per offerta.

Campo Descrizione

Campo	Descrizione
`target_selection` tipo: `enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}`	Obbligatorio. Questo campo è usato per distinguere tra offerte che si applicano a un intero catalogo prodotti e offerte limitate a uno specifico sottoinsieme di articoli all'interno di un catalogo. Le opzioni disponibili sono: `ALL_CATALOG_PRODUCTS`: l'offerta può essere applicata a qualsiasi prodotto del catalogo. `SPECIFIC_PRODUCTS`: l'offerta può essere applicata solo ai prodotti target specificati da `target_filter`, `target_product_retailer_ids`, `target_product_group_retailer_ids` o `target_product_set_retailer_ids`. Se il parametro `target_selection` è `SPECIFIC_PRODUCTS`, è richiesto uno solo dei seguenti parametri: `target_filter`, `target_product_retailer_ids`, `target_product_group_retailer_ids` o `target_product_set_retailer_ids`.
`target_filter` tipo: `JSON-encoded string`	Facoltativo. Regola di filtro per identificare i prodotti a cui può essere applicata l'offerta. Usa la stessa logica della regola di filtro usata per aggiungere prodotti a un insieme di prodotti. Se la regola di filtro specificata corrisponde al filtro di un insieme di prodotti esistente, questa offerta sarà destinata a quell'insieme di prodotti, altrimenti verrà creato un nuovo insieme di prodotti. Questo campo deve essere impostato solo se il parametro `target_selection` è impostato su `SPECIFIC_PRODUCTS`.
`target_product_retailer_ids` tipo: `Array<product_retailer_id>`	Facoltativo. Lista degli ID rivenditore dei prodotti a cui è applicabile l'offerta. Questo campo deve essere impostato solo se il parametro `target_selection` è impostato su `SPECIFIC_PRODUCTS`.
`target_product_group_retailer_ids` tipo: `Array<product_group_retailer_id>`	Facoltativo. Lista degli ID rivenditore dei gruppi di prodotti contenenti i prodotti a cui è applicabile l'offerta. Tutte le varianti di prodotto incluse nel gruppo di prodotti saranno ritenute idonee per l'offerta. Questo campo deve essere impostato solo se il parametro `target_selection` è impostato su `SPECIFIC_PRODUCTS`.
`target_product_set_retailer_ids` tipo: `Array<product_set_retailer_id>`	Facoltativo. Lista degli ID rivenditore degli insiemi di prodotti contenenti i prodotti a cui è applicabile l'offerta. L'offerta si applicherà all'unione di tutti i prodotti ottenuti valutando gli insiemi di prodotti specificati.
`prerequisite_filter` tipo: `JSON-encoded string`	Facoltativo. Regola di filtro per identificare i prodotti che devono essere acquistati perché l'acquirente possa riscattare l'offerta. Usa la stessa logica della regola di filtro usata per aggiungere prodotti a un insieme di prodotti. Normalmente utilizzata nelle offerte di tipo "Acquista X e ottieni Y". Se la regola di filtro specificata corrisponde al filtro di un insieme di prodotti esistente, questa offerta userà quell'insieme di prodotti per definire i prodotti prerequisito, altrimenti verrà creato un nuovo insieme di prodotti. Se questo campo è impostato, `prerequisite_product_retailer_ids`, `prerequisite_product_group_retailer_ids` e `prerequisite_product_set_retailer_ids` devono essere `null`.
`prerequisite_product_retailer_ids` tipo: `Array<product_retailer_id>`	Facoltativo. ID rivenditore per i prodotti che l'acquirente deve acquistare per poter riscattare l'offerta. Tutti gli articoli inclusi nella lista possono essere utilizzati dall'acquirente come prerequisito per riscattare l'offerta. Normalmente utilizzata nelle offerte di tipo "Acquista X e ottieni Y". Se questo campo è impostato, `prerequisite_filter`, `prerequisite_product_group_retailer_ids` e `prerequisite_product_set_retailer_ids` devono essere `null`.
`prerequisite_product_group_retailer_ids` tipo: `Array<product_group_retailer_id>`	Facoltativo. ID rivenditore per i gruppi di prodotti che l'acquirente deve acquistare per poter riscattare l'offerta. Tutte le varianti di prodotto incluse in ciascun gruppo possono essere utilizzate dall'acquirente come prerequisito per riscattare l'offerta. Normalmente utilizzata nelle offerte di tipo "Acquista X e ottieni Y". Se questo campo è impostato, `prerequisite_filter`, `prerequisite_product_group_retailer_ids` e `prerequisite_product_set_retailer_ids` devono essere `null`.
`prerequisite_product_set_retailer_ids` tipo: `Array<product_set_retailer_id>`	Facoltativo. ID rivenditore per gli insiemi di prodotti che l'acquirente deve acquistare per poter riscattare l'offerta. Tutti gli articoli ottenuti dall'unione di valutazione degli insiemi di prodotti possono essere utilizzati dall'acquirente come prerequisito per riscattare l'offerta. Normalmente utilizzata nelle offerte di tipo "Acquista X e ottieni Y". Se questo campo è impostato, `prerequisite_filter`, `prerequisite_product_group_retailer_ids` e `prerequisite_product_set_retailer_ids` devono essere `null`.
`exclude_sale_priced_products` tipo: `bool enum {YES, NO}`	Facoltativo. Indica se l'offerta si applica ai prodotti che hanno già un prezzo ridotto impostato nel catalogo, come specificato dal campo `sale_price` del prodotto. Imposta questo campo su `YES` per evitare il rischio di prodotti doppiamente scontati. Omettilo o impostalo su `NO` per includere i prodotti con un `sale_price` inferiore impostato nel catalogo. Quando impostato, questo campo si applica sia ai prodotti target sia ai prodotti prerequisito di un'offerta.

target_selection

tipo: enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}

Obbligatorio.

Questo campo è usato per distinguere tra offerte che si applicano a un intero catalogo prodotti e offerte limitate a uno specifico sottoinsieme di articoli all'interno di un catalogo.

Le opzioni disponibili sono:

ALL_CATALOG_PRODUCTS: l'offerta può essere applicata a qualsiasi prodotto del catalogo.
SPECIFIC_PRODUCTS: l'offerta può essere applicata solo ai prodotti target specificati da target_filter, target_product_retailer_ids, target_product_group_retailer_ids o target_product_set_retailer_ids.

Se il parametro target_selection è SPECIFIC_PRODUCTS, è richiesto uno solo dei seguenti parametri: target_filter, target_product_retailer_ids, target_product_group_retailer_ids o target_product_set_retailer_ids.

target_filter

tipo: JSON-encoded string

Facoltativo.

Regola di filtro per identificare i prodotti a cui può essere applicata l'offerta. Usa la stessa logica della regola di filtro usata per aggiungere prodotti a un insieme di prodotti.

Se la regola di filtro specificata corrisponde al filtro di un insieme di prodotti esistente, questa offerta sarà destinata a quell'insieme di prodotti, altrimenti verrà creato un nuovo insieme di prodotti.

Questo campo deve essere impostato solo se il parametro target_selection è impostato su SPECIFIC_PRODUCTS.

target_product_retailer_ids

tipo: Array<product_retailer_id>

Facoltativo.

Lista degli ID rivenditore dei prodotti a cui è applicabile l'offerta.

Questo campo deve essere impostato solo se il parametro target_selection è impostato su SPECIFIC_PRODUCTS.

target_product_group_retailer_ids

tipo: Array<product_group_retailer_id>

Facoltativo.

Lista degli ID rivenditore dei gruppi di prodotti contenenti i prodotti a cui è applicabile l'offerta.

Tutte le varianti di prodotto incluse nel gruppo di prodotti saranno ritenute idonee per l'offerta.

Questo campo deve essere impostato solo se il parametro target_selection è impostato su SPECIFIC_PRODUCTS.

target_product_set_retailer_ids

tipo: Array<product_set_retailer_id>

Facoltativo.

Lista degli ID rivenditore degli insiemi di prodotti contenenti i prodotti a cui è applicabile l'offerta. L'offerta si applicherà all'unione di tutti i prodotti ottenuti valutando gli insiemi di prodotti specificati.

prerequisite_filter

tipo: JSON-encoded string

Facoltativo.

Regola di filtro per identificare i prodotti che devono essere acquistati perché l'acquirente possa riscattare l'offerta. Usa la stessa logica della regola di filtro usata per aggiungere prodotti a un insieme di prodotti. Normalmente utilizzata nelle offerte di tipo "Acquista X e ottieni Y".

Se la regola di filtro specificata corrisponde al filtro di un insieme di prodotti esistente, questa offerta userà quell'insieme di prodotti per definire i prodotti prerequisito, altrimenti verrà creato un nuovo insieme di prodotti.

Se questo campo è impostato, prerequisite_product_retailer_ids, prerequisite_product_group_retailer_ids e prerequisite_product_set_retailer_ids devono essere null.

prerequisite_product_retailer_ids

tipo: Array<product_retailer_id>

Facoltativo.

ID rivenditore per i prodotti che l'acquirente deve acquistare per poter riscattare l'offerta. Tutti gli articoli inclusi nella lista possono essere utilizzati dall'acquirente come prerequisito per riscattare l'offerta. Normalmente utilizzata nelle offerte di tipo "Acquista X e ottieni Y".

Se questo campo è impostato, prerequisite_filter, prerequisite_product_group_retailer_ids e prerequisite_product_set_retailer_ids devono essere null.

prerequisite_product_group_retailer_ids

tipo: Array<product_group_retailer_id>

Facoltativo.

ID rivenditore per i gruppi di prodotti che l'acquirente deve acquistare per poter riscattare l'offerta. Tutte le varianti di prodotto incluse in ciascun gruppo possono essere utilizzate dall'acquirente come prerequisito per riscattare l'offerta. Normalmente utilizzata nelle offerte di tipo "Acquista X e ottieni Y".

Se questo campo è impostato, prerequisite_filter, prerequisite_product_group_retailer_ids e prerequisite_product_set_retailer_ids devono essere null.

prerequisite_product_set_retailer_ids

tipo: Array<product_set_retailer_id>

Facoltativo.

ID rivenditore per gli insiemi di prodotti che l'acquirente deve acquistare per poter riscattare l'offerta. Tutti gli articoli ottenuti dall'unione di valutazione degli insiemi di prodotti possono essere utilizzati dall'acquirente come prerequisito per riscattare l'offerta. Normalmente utilizzata nelle offerte di tipo "Acquista X e ottieni Y".

Se questo campo è impostato, prerequisite_filter, prerequisite_product_group_retailer_ids e prerequisite_product_set_retailer_ids devono essere null.

exclude_sale_priced_products

tipo: bool enum {YES, NO}

Facoltativo.

Indica se l'offerta si applica ai prodotti che hanno già un prezzo ridotto impostato nel catalogo, come specificato dal campo sale_price del prodotto.

Imposta questo campo su YES per evitare il rischio di prodotti doppiamente scontati. Omettilo o impostalo su NO per includere i prodotti con un sale_price inferiore impostato nel catalogo.

Quando impostato, questo campo si applica sia ai prodotti target sia ai prodotti prerequisito di un'offerta.

Offerte di spedizione

L'API Offers supporta sia le offerte che scontano il prezzo dei prodotti nell'acquisto di un acquirente, sia le offerte che scontano le spese di spedizione di tali prodotti. Proprio come le offerte per i prodotti, le offerte di spedizione possono essere applicate con un codice coupon o automaticamente con o senza ulteriori prerequisiti per l'acquirente.

Per creare un'offerta di spedizione, il target_type deve essere impostato su SHIPPING. Al momento, sono supportate solo le offerte di spedizione gratuita e quindi value_type deve essere sempre PERCENTUGE con percent_off impostato su 100.

Campo Descrizione

Campo	Descrizione
`target_type` tipo: `enum{LINE_ITEM, SHIPPING}`	Obbligatorio. Il tipo di oggetto a cui si applica l'offerta: `LINE_ITEM`: l'offerta si applica ai prodotti stessi. `SHIPPING`: l'offerta si applica alle spese di spedizione. Questa opzione è valida solo quando `target_granularity` è `ITEM_LEVEL`.
`target_shipping_option_types` tipo: `Array<shipping_service_tier>`	Obbligatorio, se il parametro `target_type` è `SHIPPING`. Una lista di livelli di servizi (ad es. `STANDARD`, `RUSH`, `EXPEDITED`) per cui è valida l'offerta. Ad esempio, per specificare un'offerta di spedizione che si applica ai tempi di spedizione standard e rapida ma non alla spedizione notturna, usa: `target_type` di `SHIPPING` `target_shipping_option_types` di `["STANDARD", "RUSH"]` Per i venditori che hanno abilitato la funzione di acquisto su Facebook o Instagram, puoi usare l'API Shipping Profiles per gestire i profili di spedizione sul tuo account per le vendite.

target_type

tipo: enum{LINE_ITEM, SHIPPING}

Obbligatorio.

Il tipo di oggetto a cui si applica l'offerta:

LINE_ITEM: l'offerta si applica ai prodotti stessi.
SHIPPING: l'offerta si applica alle spese di spedizione. Questa opzione è valida solo quando target_granularity è ITEM_LEVEL.

target_shipping_option_types

tipo: Array<shipping_service_tier>

Obbligatorio, se il parametro target_type è SHIPPING.

Una lista di livelli di servizi (ad es. STANDARD, RUSH, EXPEDITED) per cui è valida l'offerta.

Ad esempio, per specificare un'offerta di spedizione che si applica ai tempi di spedizione standard e rapida ma non alla spedizione notturna, usa:

target_type di SHIPPING
target_shipping_option_types di ["STANDARD", "RUSH"]

Per i venditori che hanno abilitato la funzione di acquisto su Facebook o Instagram, puoi usare l'API Shipping Profiles per gestire i profili di spedizione sul tuo account per le vendite.

Offerte Acquista X e ottieni Y

Le offerte di tipo "Acquista X e ottieni Y" consentono agli acquirenti di acquistare una quantità specifica di prodotti "X" selezionati per ottenere 1 o più prodotti "Y" a prezzo ridotto o gratis. Sono supportate anche le offerte Spendi X e ottieni Y in cui l'acquirente deve raggiungere una soglia di spesa minima per un insieme di prodotti X per ricevere uno sconto. Puoi creare un'offerta Acquista X e ottieni Y impostando il campo target_quantity e uno tra i campi min_quantity e min_subtotal.

In alcuni casi come la diffusissima offerta "acquistane uno e il secondo è gratis", X e Y possono riferirsi allo stesso insieme di prodotti. Tuttavia, puoi anche usare i parametri prerequisite_filter, prerequisite_product_retailer_ids, prerequisite_product_group_retailer_ids e prerequisite_product_set_retailer_ids per specificare un insieme di prodotti X diversi dai prodotti target Y. Consulta Definizione dei prodotti idonei per scoprire come configurare questi campi.

Campo Descrizione

Campo	Descrizione
`target_quantity` tipo: `int64`	Facoltativo. L'impostazione predefinita è 0 (illimitato). Il numero di prodotti scontati per ogni volta che l'offerta viene riscattata. Impostando `target_quantity` > 0 si definisce un'offerta di tipo Acquista X e ottieni Y. Usa questo campo per controllare quanti prodotti vengono scontati quando un acquirente soddisfa i prerequisiti di riscatto. Ad esempio, in un'offerta "acquistane 2 e il secondo è scontato del 50%" la quantità target è 1, mentre in un'offerta "acquistane 5 e ne ottieni 2 gratis" la quantità target è 2.
`redemption_limit_per_order` tipo: `int64`	Facoltativo. L'impostazione predefinita è 0 (illimitato). Il numero di volte in cui questa offerta può essere riscattata per singolo ordine. Usa questo campo per limitare il numero di volte in cui un'offerta può essere applicata ai prodotti nell'acquisto di un acquirente. Ad esempio, in un'offerta "acquista una camicia e la seconda è gratis" per impostazione predefinita un acquirente che acquista 6 camicie ne riceverebbe 3 a prezzo pieno e 3 in omaggio. Tuttavia, nello stesso esempio, se `redemption_limit_per_order` è impostato su 2 allora l'acquirente riceverebbe 2 camicie in omaggio e 4 a prezzo pieno. Se questo campo è impostato, `target_quantity` deve essere maggiore di 0.

target_quantity

tipo: int64

Facoltativo. L'impostazione predefinita è 0 (illimitato).

Il numero di prodotti scontati per ogni volta che l'offerta viene riscattata. Impostando target_quantity > 0 si definisce un'offerta di tipo Acquista X e ottieni Y.

Usa questo campo per controllare quanti prodotti vengono scontati quando un acquirente soddisfa i prerequisiti di riscatto. Ad esempio, in un'offerta "acquistane 2 e il secondo è scontato del 50%" la quantità target è 1, mentre in un'offerta "acquistane 5 e ne ottieni 2 gratis" la quantità target è 2.

redemption_limit_per_order

tipo: int64

Facoltativo. L'impostazione predefinita è 0 (illimitato).

Il numero di volte in cui questa offerta può essere riscattata per singolo ordine.

Usa questo campo per limitare il numero di volte in cui un'offerta può essere applicata ai prodotti nell'acquisto di un acquirente. Ad esempio, in un'offerta "acquista una camicia e la seconda è gratis" per impostazione predefinita un acquirente che acquista 6 camicie ne riceverebbe 3 a prezzo pieno e 3 in omaggio. Tuttavia, nello stesso esempio, se redemption_limit_per_order è impostato su 2 allora l'acquirente riceverebbe 2 camicie in omaggio e 4 a prezzo pieno.

Se questo campo è impostato, target_quantity deve essere maggiore di 0.

Combinazione di offerte

Per i venditori che hanno abilitato la funzione di acquisto su Facebook o Instagram, il supporto è limitato per la combinazione di più offerte in una singola transazione. La possibilità di combinare un'offerta con altre offerte dipende principalmente dal tipo di applicazione e dal tipo di target. Al momento questo comportamento non è configurabile dai venditori. Le regole di seguito riassumono il comportamento di combinazione delle offerte:

Per un dato prodotto, se ci sono offerte che comporterebbero prezzi barrati (application_type = VENDITA) viene applicata l'offerta con il prezzo del prodotto finale più basso. Questo si ripete per tutti gli articoli presenti nel carrello di un acquirente. Il nuovo prezzo scontato dell'articolo è usato in tutti i futuri calcoli dei prerequisiti dell'offerta.
In un singolo ordine, l'acquirente può riscattare 1 offerta BUYER_APPLIED o 1 offerta AUTOMATIC_AT_CHECKOUT per target_type (LINE_ITEM o SHIPPING). Ad esempio, un acquirente può applicare un coupon di spedizione gratuita e un coupon acquistane uno e il secondo è gratis, ma non può riscattare 2 offerte di sconto sul prezzo del prodotto.
Meta a volte può finanziare offerte per attirare clienti nuovi e ricorrenti senza alcun costo per i venditori. Le offerte finanziate da Meta possono sempre essere combinate con offerte finanziate dai venditori.

Limitazione dell'idoneità degli utenti per le offerte

Al momento, le offerte create tramite l'API Offers non possono essere proposte selettivamente a coorti specifiche di utenti. Le offerte create nel Gestore delle vendite possono essere configurate con limitazioni di idoneità degli utenti. Le offerte proposte che sono state create tramite l'API Offers saranno mostrate a tutti gli acquirenti, e qualsiasi acquirente che soddisfi i prerequisiti di un'offerta (compreso l'inserimento di eventuali codici coupon) nella procedura di acquisto su Facebook o Instagram potrà riscattarla.

In futuro, l'API Offers potrebbe supportare la limitazione delle offerte a determinati Paesi per venditori multinazionali e limitare l'idoneità delle offerte a specifici gruppi di utenti, come acquirenti per la prima volta o follower della Pagina Facebook di un venditore.