API Offers

L’API Offers est actuellement en phase bêta fermée, accessible uniquement sur invitation. Si vous avez été invité·e à participer au programme, veuillez contacter votre représentant Meta pour obtenir les droits d’accès.

Cette API permet d’intégrer des informations d’offres à votre catalogue produits, facilitant ainsi leur mise en avant sur Facebook et Instagram. Pour les vendeur·ses ayant activé le paiement sur Facebook ou Instagram, les acheteur·ses pourront bénéficier directement de ces offres au sein des applications de la famille Meta.

Créer des offres

Vous pouvez créer des offres soit via un flux d’offres, soit manuellement via le Gestionnaire des ventes.

Flux

Pour créer un flux d’offres, envoyez une requête POST à l’arête /{product_catalog_id}/product_feeds en définissant feed_type sur OFFER. Cette action génère un flux de produits de type Offre pour le catalogue spécifié dans le champ product_catalog_id.

Une fois le flux d’offres créé, vous pouvez télécharger vos données d’offres via une requête POST à l’arête /{product_feed_id}/uploads.

Colonnes du flux

La majorité des champs répertoriés ci-dessous peuvent être définis comme colonnes dans votre fichier de flux. Seuls les champs en lecture seule ne peuvent pas être définis lors de la création.

Glossaire

Ensembles de produits

Un ensemble de produits désigne un groupe d’articles connexes au sein d’un catalogue produits.

Articles cibles de l’offre

Produits éligibles à une offre spécifique.

Prérequis de l’offre

Conditions nécessaires à l’application de l’offre. Par exemple, vous pouvez spécifier que l’offre n’est valable que lorsque les acheteur·ses atteignent un certain seuil d’achat, en termes de quantité ou de valeur. Actuellement, les produits prérequis sont dérivés des produits cibles. Exemple : une offre de 20 % de réduction sur toutes les chaussures signifie que les exigences minimales de sous-total ou de quantité doivent être satisfaites avec des chaussures dans le panier.

Type d’application de l’offre

Détermine les modalités d’application d’une offre lors du paiement, que ce soit sur votre propre site Web ou via le processus de paiement de Facebook. Il peut, par exemple, définir si une offre est automatiquement appliquée ou nécessite un code promo. Le type d’application régit également la façon dont une offre peut être combinée avec d’autres. Pour plus de détails, consultez la section Combinaison des offres.

Champs de base

Les champs suivants permettent de configurer tous les types d’offres.

Champ Description

Champ	Description
`id` Type : `numeric string`	Lecture seule. Identifiant unique (ID Facebook) de cet élément.
`offer_id` Type : `string`	Obligatoire. Identifiant de l’offre fourni par le vendeur ou la vendeuse. Ce champ est utilisé pour identifier de manière unique une offre au sein d’un catalogue.
`title` Type : `string`	Facultatif. Titre de l’élément d’offre. Actuellement utilisé uniquement pour identifier les offres dans le Gestionnaire des ventes, non visible par les acheteurs et acheteuses.
`description` Type : `string`	Lecture seule. Description générée automatiquement de l’offre.
`application_type` Type : `enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}`	Obligatoire. Détermine comment et quand une offre est appliquée. Les options disponibles sont les suivantes : `SALE` : les articles sont directement soldés, affichés avec un prix barré pour les acheteur·ses. Ces offres ne nécessitent aucun prérequis de la part de l’acheteur ou de l’acheteuse et ne sont pas affectées par d’autres articles lors du paiement. La promotion offrant le prix le plus bas d’un article est toujours choisie, car les promotions ne sont jamais combinées. Les promotions peuvent être combinées avec d’autres types d’offres mais sont toujours appliquées en premier. Si un produit a déjà un champ `sale_price` défini, alors le prix final est calculé en utilisant `sale_price` comme prix de base. `AUTOMATIC_AT_CHECKOUT` : l’offre est automatiquement appliquée lors du paiement lorsque l’acheteur·se remplit les critères de remise nécessaires. Cette offre a une configuration qui l’empêche d’être qualifiée de promotion. Elle ne peut être combinée qu’avec des offres de type promotion. Jusqu’à 25 de ces offres peuvent être actives en même temps. `BUYER_APPLIED` : cette offre est appliquée lors du paiement sur la base d’une action effectuée par l’acheteur·se, comme la saisie d’un code promo. Ces offres ne peuvent actuellement pas être combinées entre elles ou avec des offres appliquées automatiquement lors du paiement. Nécessite que l’un des champs [`public_coupon_code`, `coupon_codes`] soit fourni.
`coupon_codes` Type : `Array<string>`	Liste des codes promo insensibles à la casse que les client·es utilisent lors du paiement pour bénéficier de l’offre. Maximum de 100 codes promo autorisés. Par exemple : `["10OFF", "HOLIDAY_SALE"]` Les codes promo ne peuvent être spécifiés que lorsque `application_type` est `BUYER_APPLIED`. Si ce champ est défini, `public_coupon_code` doit être null.
`public_coupon_code` Type : `string`	Facultatif. Un seul code promo insensible à la casse qui sera commercialisé avec l’offre et sera pré-rempli lors du paiement si l’acheteur·se remplit les conditions préalables de l’offre. Par défaut, les offres avec des codes promo ne sont pas visiblement diffusées aux acheteur·ses sur les plateformes d’achat Facebook ou Instagram telles qu’une page de détails de produit. Ceci pour éviter que des codes privés ou secrets ne soient divulgués involontairement aux acheteur·ses. Vous pouvez modifier ce comportement en spécifiant un code promo public à utiliser pour la diffusion de votre offre. Les offres avec des codes publics seront présentées de façon similaire aux offres avec un `application_typeAUTOMATIC_AT_CHECKOUT`, avec l’ajout du code promo visible. Un code promo public ne peut pas dépasser 20 caractères de longueur et votre catalogue peut contenir au maximum 10 offres actives avec des codes promo publics à la fois. Un code promo public ne peut être défini que lorsque `application_type` est `BUYER_APPLIED`. Si ce champ est défini, `coupon_codes` doit être null.
`start_date_time` Type : `timestamp`	Obligatoire. Horodatage Unix, en secondes, du début de l’offre. L’entrée peut être soit un horodatage Unix, en secondes, soit une chaîne de date formatée ISO-8601 (par exemple, 2021-09-25T12:34:56Z).
`end_date_time` Type : `timestamp`	Facultatif. Valeur par défaut : `null`. Horodatage Unix, en secondes, de la fin de l’offre. Si le champ n’est pas rempli ou s’il a la valeur `null`, l’offre n’a pas de date de fin. L’entrée peut être soit un horodatage Unix, en secondes, soit une chaîne de date formatée ISO-8601 (par exemple, 2021-09-25T12:34:56Z).
`min_quantity` Type : `int64`	Facultatif. Valeur par défaut : 0. Utilisez ce champ si votre offre n’est valable que lorsque le client ou la cliente achète un nombre minimum de produits. Ce champ représente le nombre de produits que le client ou la cliente doit acheter pour que l’offre soit valable. Par exemple : « Achetez 5 chemises, obtenez 20 % de réduction ». Un seul des champs `min_quantity` ou `min_subtotal` peut être défini.
`min_subtotal` Type : `string`	Facultatif. Valeur par défaut : `null`. Utilisez ce champ si votre offre n’est valable que lorsque la commande du client ou de la cliente atteint une valeur de sous-total spécifique. Le sous-total des produits prérequis doit être égal ou supérieur à cette valeur pour que l’offre s’applique. Si aucun produit prérequis explicite n’est défini, alors les produits cibles sont utilisés comme produits prérequis. Ce champ doit être formaté comme le montant, suivi du code de devise ISO à trois chiffres, avec un espace entre le montant et la devise. Par exemple, la chaîne « 30,99 EUR » représente un sous-total prérequis de 30,99 € pour que l’offre s’applique. Un seul des champs `min_quantity` ou `min_subtotal` peut être défini.
`redeem_limit_per_user` Type : `int64`	Facultatif. Valeur par défaut : 0 (illimité). Le nombre maximal de fois que l’offre peut être utilisée par un seul utilisateur ou une seule utilisatrice. Définissez ce champ sur 1 pour créer un code promo à usage unique. Ce champ ne doit être défini que si `application_type` est `BUYER_APPLIED`.
`value_type` Type : `enum {FIXED_AMOUNT, PERCENTAGE}`	Obligatoire. Le type de remise fourni par l’offre. Les options disponibles sont les suivantes : `FIXED_AMOUNT` : applique une remise d’un montant fixe dont la valeur est définie dans le champ `fixed_amount_off`. `PERCENTAGE` : applique une remise en pourcentage dont la valeur est définie dans le champ `percent_off`.
`fixed_amount_off` Type : `string`	Obligatoire si `value_type` est défini sur `FIXED_AMOUNT`. Le montant de la remise de l’offre. Ce champ doit être formaté comme le montant, suivi du code de devise ISO à trois chiffres, avec un espace entre le montant et la devise. Par exemple, la chaîne « 30,99 EUR » représente une remise de 30,99 €. Ce champ ne doit être défini que si `value_type` est `FIXED_AMOUNT`.
`percent_off` Type : `int64`	Obligatoire si `value_type` est défini sur `PERCENTAGE`. Le pourcentage de remise de l’offre. Doit être un entier compris entre 0 et 100. Par exemple, « 30 » correspond à une remise de 30 %. Ce champ ne doit être défini que si `value_type` est `PERCENTAGE`.
`target_granularity` Type : `enum {ITEM_LEVEL, ORDER_LEVEL}`	Obligatoire. Niveau d’application de la remise. Les options disponibles sont les suivantes : `ITEM_LEVEL` : la remise s’applique à chaque article éligible dans le panier. `ORDER_LEVEL` : la remise s’applique globalement à l’ensemble des articles éligibles dans le panier. Exemple : pour une offre de « 30 € de réduction sur les chaussures » avec trois paires de chaussures dans le panier, avec `ITEM_LEVEL`, la remise de 30 € s’applique à chaque paire (soit une réduction totale de 90 €), tandis qu’avec `ORDER_LEVEL`, une remise unique de 30 € s’applique sur le total des trois paires. Attention : les offres de type `ORDER_LEVEL` peuvent générer des répartitions de remise non uniformes entre les articles d’une commande. Cela peut compliquer la gestion lors de l’exécution de la commande ou en cas de remboursement.
`offer_terms` Type : `string`	Facultatif. Champ permettant d’ajouter des conditions générales supplémentaires relatives à l’utilisation de l’offre. Limite de 2 500 caractères. Facebook génère automatiquement des conditions basées sur la configuration de l’offre. Vous pouvez utiliser le champ `offer_terms` pour ajouter vos propres conditions spécifiques. Celles-ci seront affichées à la suite des conditions générées par Facebook. Le contenu doit être conforme à nos politiques de contenu.

id

Type : numeric string

Lecture seule.

Identifiant unique (ID Facebook) de cet élément.

offer_id

Type : string

Obligatoire.

Identifiant de l’offre fourni par le vendeur ou la vendeuse.

Ce champ est utilisé pour identifier de manière unique une offre au sein d’un catalogue.

title

Type : string

Facultatif.

Titre de l’élément d’offre.

Actuellement utilisé uniquement pour identifier les offres dans le Gestionnaire des ventes, non visible par les acheteurs et acheteuses.

description

Type : string

Lecture seule.

Description générée automatiquement de l’offre.

application_type

Type : enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}

Obligatoire.

Détermine comment et quand une offre est appliquée. Les options disponibles sont les suivantes :

SALE : les articles sont directement soldés, affichés avec un prix barré pour les acheteur·ses. Ces offres ne nécessitent aucun prérequis de la part de l’acheteur ou de l’acheteuse et ne sont pas affectées par d’autres articles lors du paiement. La promotion offrant le prix le plus bas d’un article est toujours choisie, car les promotions ne sont jamais combinées. Les promotions peuvent être combinées avec d’autres types d’offres mais sont toujours appliquées en premier. Si un produit a déjà un champ sale_price défini, alors le prix final est calculé en utilisant sale_price comme prix de base.
AUTOMATIC_AT_CHECKOUT : l’offre est automatiquement appliquée lors du paiement lorsque l’acheteur·se remplit les critères de remise nécessaires. Cette offre a une configuration qui l’empêche d’être qualifiée de promotion. Elle ne peut être combinée qu’avec des offres de type promotion. Jusqu’à 25 de ces offres peuvent être actives en même temps.
BUYER_APPLIED : cette offre est appliquée lors du paiement sur la base d’une action effectuée par l’acheteur·se, comme la saisie d’un code promo. Ces offres ne peuvent actuellement pas être combinées entre elles ou avec des offres appliquées automatiquement lors du paiement. Nécessite que l’un des champs [public_coupon_code, coupon_codes] soit fourni.

coupon_codes

Type : Array<string>

Liste des codes promo insensibles à la casse que les client·es utilisent lors du paiement pour bénéficier de l’offre. Maximum de 100 codes promo autorisés. Par exemple : ["10OFF", "HOLIDAY_SALE"]

Les codes promo ne peuvent être spécifiés que lorsque application_type est BUYER_APPLIED.

Si ce champ est défini, public_coupon_code doit être null.

public_coupon_code

Type : string

Facultatif.

Un seul code promo insensible à la casse qui sera commercialisé avec l’offre et sera pré-rempli lors du paiement si l’acheteur·se remplit les conditions préalables de l’offre.

Par défaut, les offres avec des codes promo ne sont pas visiblement diffusées aux acheteur·ses sur les plateformes d’achat Facebook ou Instagram telles qu’une page de détails de produit. Ceci pour éviter que des codes privés ou secrets ne soient divulgués involontairement aux acheteur·ses. Vous pouvez modifier ce comportement en spécifiant un code promo public à utiliser pour la diffusion de votre offre. Les offres avec des codes publics seront présentées de façon similaire aux offres avec un application_typeAUTOMATIC_AT_CHECKOUT, avec l’ajout du code promo visible.

Un code promo public ne peut pas dépasser 20 caractères de longueur et votre catalogue peut contenir au maximum 10 offres actives avec des codes promo publics à la fois.

Un code promo public ne peut être défini que lorsque application_type est BUYER_APPLIED.

Si ce champ est défini, coupon_codes doit être null.

start_date_time

Type : timestamp

Obligatoire.

Horodatage Unix, en secondes, du début de l’offre.

L’entrée peut être soit un horodatage Unix, en secondes, soit une chaîne de date formatée ISO-8601 (par exemple, 2021-09-25T12:34:56Z).

end_date_time

Type : timestamp

Facultatif. Valeur par défaut : null.

Horodatage Unix, en secondes, de la fin de l’offre. Si le champ n’est pas rempli ou s’il a la valeur null, l’offre n’a pas de date de fin.

L’entrée peut être soit un horodatage Unix, en secondes, soit une chaîne de date formatée ISO-8601 (par exemple, 2021-09-25T12:34:56Z).

min_quantity

Type : int64

Facultatif. Valeur par défaut : 0.

Utilisez ce champ si votre offre n’est valable que lorsque le client ou la cliente achète un nombre minimum de produits.

Ce champ représente le nombre de produits que le client ou la cliente doit acheter pour que l’offre soit valable. Par exemple : « Achetez 5 chemises, obtenez 20 % de réduction ».

Un seul des champs min_quantity ou min_subtotal peut être défini.

min_subtotal

Type : string

Facultatif. Valeur par défaut : null.

Utilisez ce champ si votre offre n’est valable que lorsque la commande du client ou de la cliente atteint une valeur de sous-total spécifique.

Le sous-total des produits prérequis doit être égal ou supérieur à cette valeur pour que l’offre s’applique. Si aucun produit prérequis explicite n’est défini, alors les produits cibles sont utilisés comme produits prérequis.

Ce champ doit être formaté comme le montant, suivi du code de devise ISO à trois chiffres, avec un espace entre le montant et la devise. Par exemple, la chaîne « 30,99 EUR » représente un sous-total prérequis de 30,99 € pour que l’offre s’applique.

Un seul des champs min_quantity ou min_subtotal peut être défini.

redeem_limit_per_user

Type : int64

Facultatif. Valeur par défaut : 0 (illimité).

Le nombre maximal de fois que l’offre peut être utilisée par un seul utilisateur ou une seule utilisatrice.

Définissez ce champ sur 1 pour créer un code promo à usage unique.

Ce champ ne doit être défini que si application_type est BUYER_APPLIED.

value_type

Type : enum {FIXED_AMOUNT, PERCENTAGE}

Obligatoire.

Le type de remise fourni par l’offre.

Les options disponibles sont les suivantes :

FIXED_AMOUNT : applique une remise d’un montant fixe dont la valeur est définie dans le champ fixed_amount_off.
PERCENTAGE : applique une remise en pourcentage dont la valeur est définie dans le champ percent_off.

fixed_amount_off

Type : string

Obligatoire si value_type est défini sur FIXED_AMOUNT.

Le montant de la remise de l’offre. Ce champ doit être formaté comme le montant, suivi du code de devise ISO à trois chiffres, avec un espace entre le montant et la devise. Par exemple, la chaîne « 30,99 EUR » représente une remise de 30,99 €.

Ce champ ne doit être défini que si value_type est FIXED_AMOUNT.

percent_off

Type : int64

Obligatoire si value_type est défini sur PERCENTAGE.

Le pourcentage de remise de l’offre. Doit être un entier compris entre 0 et 100. Par exemple, « 30 » correspond à une remise de 30 %.

Ce champ ne doit être défini que si value_type est PERCENTAGE.

target_granularity

Type : enum {ITEM_LEVEL, ORDER_LEVEL}

Obligatoire.

Niveau d’application de la remise.

Les options disponibles sont les suivantes :

ITEM_LEVEL : la remise s’applique à chaque article éligible dans le panier.
ORDER_LEVEL : la remise s’applique globalement à l’ensemble des articles éligibles dans le panier. Exemple : pour une offre de « 30 € de réduction sur les chaussures » avec trois paires de chaussures dans le panier, avec ITEM_LEVEL, la remise de 30 € s’applique à chaque paire (soit une réduction totale de 90 €), tandis qu’avec ORDER_LEVEL, une remise unique de 30 € s’applique sur le total des trois paires.

Attention : les offres de type ORDER_LEVEL peuvent générer des répartitions de remise non uniformes entre les articles d’une commande. Cela peut compliquer la gestion lors de l’exécution de la commande ou en cas de remboursement.

offer_terms

Type : string

Facultatif.

Champ permettant d’ajouter des conditions générales supplémentaires relatives à l’utilisation de l’offre. Limite de 2 500 caractères.

Facebook génère automatiquement des conditions basées sur la configuration de l’offre. Vous pouvez utiliser le champ offer_terms pour ajouter vos propres conditions spécifiques. Celles-ci seront affichées à la suite des conditions générées par Facebook.

Le contenu doit être conforme à nos politiques de contenu.

Définition des produits éligibles

Les articles cibles auxquels une offre s’applique et les articles prérequis qu’un acheteur ou une acheteuse doit acquérir pour bénéficier de l’offre sont définis par des ensembles de produits. L’API Offers propose plusieurs méthodes pour spécifier ces ensembles, mais une seule méthode peut être utilisée par type d’ensemble et par offre.

Champ Description

Champ	Description
`target_selection` Type : `enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}`	Obligatoire. Différencie les offres applicables à l’ensemble du catalogue produits de celles limitées à un sous-ensemble spécifique. Les options disponibles sont les suivantes : `ALL_CATALOG_PRODUCTS` : l’offre s’applique à tout le catalogue. `SPECIFIC_PRODUCTS` : l’offre ne s’applique qu’aux produits spécifiés via `target_filter`, `target_product_retailer_ids`, `target_product_group_retailer_ids` ou `target_product_set_retailer_ids`. Si `target_selection` est `SPECIFIC_PRODUCTS`, l’un des champs suivants doit être renseigné : `target_filter`, `target_product_retailer_ids`, `target_product_group_retailer_ids` ou `target_product_set_retailer_ids`.
`target_filter` Type : `JSON-encoded string`	Facultatif. Règle de filtrage des produits éligibles à l’offre. Utilise la même logique que pour l’ajout de produits à un ensemble de produits. Si la règle de filtrage spécifiée correspond à un ensemble de produits existant, l’offre ciblera cet ensemble. Sinon, un nouvel ensemble sera créé. Ce champ ne doit être utilisé que si `target_selection` est défini sur `SPECIFIC_PRODUCTS`.
`target_product_retailer_ids` Type : `Array<product_retailer_id>`	Facultatif. Liste des ID de détaillant des produits éligibles à l’offre. Ce champ ne doit être utilisé que si `target_selection` est défini sur `SPECIFIC_PRODUCTS`.
`target_product_group_retailer_ids` Type : `Array<product_group_retailer_id>`	Facultatif. Liste des ID de détaillant des groupes de produits éligibles à l’offre. Toutes les variantes de produits du groupe seront éligibles. Ce champ ne doit être utilisé que si `target_selection` est défini sur `SPECIFIC_PRODUCTS`.
`target_product_set_retailer_ids` Type : `Array<product_set_retailer_id>`	Facultatif. Liste des ID de détaillant des ensembles de produits éligibles à l’offre. L’offre s’appliquera à l’ensemble des produits inclus dans tous ces ensembles de produits spécifiés.
`prerequisite_filter` Type : `JSON-encoded string`	Facultatif. Règle de filtrage des produits prérequis à l’achat pour bénéficier de l’offre. Utilise la même logique que pour l’ajout de produits à un ensemble de produits. Typiquement utilisé pour les offres « Achetez X, obtenez Y ». Si la règle de filtrage spécifiée correspond à un ensemble de produits existant, cet ensemble définira les produits prérequis. Sinon, un nouvel ensemble sera créé. Si ce champ est défini, `prerequisite_product_retailer_ids`, `prerequisite_product_group_retailer_ids` et `prerequisite_product_set_retailer_ids` doivent avoir la valeur `null`.
`prerequisite_product_retailer_ids` Type : `Array<product_retailer_id>`	Facultatif. ID de détaillant des produits prérequis à l’achat pour bénéficier de l’offre. Tout article de la liste peut servir de prérequis. Typiquement utilisé pour les offres « Achetez X, obtenez Y ». Si ce champ est défini, `prerequisite_filter`, `prerequisite_product_group_retailer_ids` et `prerequisite_product_set_retailer_ids` doivent avoir la valeur `null`.
`prerequisite_product_group_retailer_ids` Type : `Array<product_group_retailer_id>`	Facultatif. ID de détaillant des groupes de produits prérequis à l’achat pour bénéficier de l’offre. Toutes les variantes de produits de chaque groupe peuvent servir de prérequis. Typiquement utilisé pour les offres « Achetez X, obtenez Y ». Si ce champ est défini, `prerequisite_filter`, `prerequisite_product_retailer_ids` et `prerequisite_product_set_retailer_ids` doivent avoir la valeur `null`.
`prerequisite_product_set_retailer_ids` Type : `Array<product_set_retailer_id>`	Facultatif. ID de détaillant des ensembles de produits contenant les articles prérequis à l’achat pour bénéficier de l’offre. Tout produit appartenant à l’un de ces ensembles peut être considéré comme prérequis pour l’offre. Typiquement utilisé pour les offres « Achetez X, obtenez Y ». Si ce champ est défini, `prerequisite_filter`, `prerequisite_product_retailer_ids` et `prerequisite_product_group_retailer_ids` doivent avoir la valeur `null`.
`exclude_sale_priced_products` Type : `bool enum {YES, NO}`	Facultatif. Détermine si l’offre s’applique aux produits déjà en promotion dans le catalogue (définis par le champ `sale_price` d’un article). `YES` : exclut ces produits pour éviter une double réduction. `NO` ou non renseigné : inclut les produits ayant un `sale_price` inférieur dans votre catalogue. Lorsqu’il est défini, ce champ s’applique à la fois aux produits cibles et aux produits prérequis de l’offre.

target_selection

Type : enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}

Obligatoire.

Différencie les offres applicables à l’ensemble du catalogue produits de celles limitées à un sous-ensemble spécifique.

Les options disponibles sont les suivantes :

ALL_CATALOG_PRODUCTS : l’offre s’applique à tout le catalogue.
SPECIFIC_PRODUCTS : l’offre ne s’applique qu’aux produits spécifiés via target_filter, target_product_retailer_ids, target_product_group_retailer_ids ou target_product_set_retailer_ids.

Si target_selection est SPECIFIC_PRODUCTS, l’un des champs suivants doit être renseigné : target_filter, target_product_retailer_ids, target_product_group_retailer_ids ou target_product_set_retailer_ids.

target_filter

Type : JSON-encoded string

Facultatif.

Règle de filtrage des produits éligibles à l’offre. Utilise la même logique que pour l’ajout de produits à un ensemble de produits.

Si la règle de filtrage spécifiée correspond à un ensemble de produits existant, l’offre ciblera cet ensemble. Sinon, un nouvel ensemble sera créé.

Ce champ ne doit être utilisé que si target_selection est défini sur SPECIFIC_PRODUCTS.

target_product_retailer_ids

Type : Array<product_retailer_id>

Facultatif.

Liste des ID de détaillant des produits éligibles à l’offre.

Ce champ ne doit être utilisé que si target_selection est défini sur SPECIFIC_PRODUCTS.

target_product_group_retailer_ids

Type : Array<product_group_retailer_id>

Facultatif.

Liste des ID de détaillant des groupes de produits éligibles à l’offre.

Toutes les variantes de produits du groupe seront éligibles.

Ce champ ne doit être utilisé que si target_selection est défini sur SPECIFIC_PRODUCTS.

target_product_set_retailer_ids

Type : Array<product_set_retailer_id>

Facultatif.

Liste des ID de détaillant des ensembles de produits éligibles à l’offre. L’offre s’appliquera à l’ensemble des produits inclus dans tous ces ensembles de produits spécifiés.

prerequisite_filter

Type : JSON-encoded string

Facultatif.

Règle de filtrage des produits prérequis à l’achat pour bénéficier de l’offre. Utilise la même logique que pour l’ajout de produits à un ensemble de produits. Typiquement utilisé pour les offres « Achetez X, obtenez Y ».

Si la règle de filtrage spécifiée correspond à un ensemble de produits existant, cet ensemble définira les produits prérequis. Sinon, un nouvel ensemble sera créé.

Si ce champ est défini, prerequisite_product_retailer_ids, prerequisite_product_group_retailer_ids et prerequisite_product_set_retailer_ids doivent avoir la valeur null.

prerequisite_product_retailer_ids

Type : Array<product_retailer_id>

Facultatif.

ID de détaillant des produits prérequis à l’achat pour bénéficier de l’offre. Tout article de la liste peut servir de prérequis. Typiquement utilisé pour les offres « Achetez X, obtenez Y ».

Si ce champ est défini, prerequisite_filter, prerequisite_product_group_retailer_ids et prerequisite_product_set_retailer_ids doivent avoir la valeur null.

prerequisite_product_group_retailer_ids

Type : Array<product_group_retailer_id>

Facultatif.

ID de détaillant des groupes de produits prérequis à l’achat pour bénéficier de l’offre. Toutes les variantes de produits de chaque groupe peuvent servir de prérequis. Typiquement utilisé pour les offres « Achetez X, obtenez Y ».

Si ce champ est défini, prerequisite_filter, prerequisite_product_retailer_ids et prerequisite_product_set_retailer_ids doivent avoir la valeur null.

prerequisite_product_set_retailer_ids

Type : Array<product_set_retailer_id>

Facultatif.

ID de détaillant des ensembles de produits contenant les articles prérequis à l’achat pour bénéficier de l’offre. Tout produit appartenant à l’un de ces ensembles peut être considéré comme prérequis pour l’offre. Typiquement utilisé pour les offres « Achetez X, obtenez Y ».

Si ce champ est défini, prerequisite_filter, prerequisite_product_retailer_ids et prerequisite_product_group_retailer_ids doivent avoir la valeur null.

exclude_sale_priced_products

Type : bool enum {YES, NO}

Facultatif.

Détermine si l’offre s’applique aux produits déjà en promotion dans le catalogue (définis par le champ sale_price d’un article).

YES : exclut ces produits pour éviter une double réduction. NO ou non renseigné : inclut les produits ayant un sale_price inférieur dans votre catalogue.

Lorsqu’il est défini, ce champ s’applique à la fois aux produits cibles et aux produits prérequis de l’offre.

Offres de livraison

L’API Offers prend en charge deux types de réductions : celles sur le prix des produits dans le panier de l’acheteur·se et celles sur les frais de livraison associés. À l’instar des offres sur les produits, les offres de livraison peuvent être appliquées via un code promo ou automatiquement, avec ou sans conditions préalables supplémentaires pour l’acheteur·se.

Pour créer une offre de livraison, le champ target_type doit être défini sur SHIPPING. Actuellement, seules les offres de livraison gratuite sont prises en charge. Ainsi, value_type doit toujours être PERCENTAGE avec percent_off défini sur 100.

Champ Description

Champ	Description
`target_type` Type : `enum{LINE_ITEM, SHIPPING}`	Obligatoire. Détermine l’objet de l’offre : `LINE_ITEM` : l’offre s’applique directement aux articles. `SHIPPING` : l’offre s’applique aux frais de livraison. Cette option n’est valide que lorsque `target_granularity` est défini sur `ITEM_LEVEL`.
`target_shipping_option_types` Type : `Array<shipping_service_tier>`	Obligatoire si `target_type` est `SHIPPING`. Liste des types de service de livraison (par exemple, `STANDARD`, `RUSH`, `EXPEDITED`) auxquels l’offre s’applique. Exemple : pour une offre de livraison applicable aux modes standard et express, mais pas à la livraison le lendemain, utilisez : `target_type` = `SHIPPING` `target_shipping_option_types` = `["STANDARD", "RUSH"]` Les vendeur·ses ayant activé le paiement sur Facebook ou Instagram peuvent utiliser l’API Shipping Profiles pour gérer leurs profils de livraison sur leur compte marchand.

target_type

Type : enum{LINE_ITEM, SHIPPING}

Obligatoire.

Détermine l’objet de l’offre :

LINE_ITEM : l’offre s’applique directement aux articles.
SHIPPING : l’offre s’applique aux frais de livraison. Cette option n’est valide que lorsque target_granularity est défini sur ITEM_LEVEL.

target_shipping_option_types

Type : Array<shipping_service_tier>

Obligatoire si target_type est SHIPPING.

Liste des types de service de livraison (par exemple, STANDARD, RUSH, EXPEDITED) auxquels l’offre s’applique.

Exemple : pour une offre de livraison applicable aux modes standard et express, mais pas à la livraison le lendemain, utilisez :

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

Les vendeur·ses ayant activé le paiement sur Facebook ou Instagram peuvent utiliser l’API Shipping Profiles pour gérer leurs profils de livraison sur leur compte marchand.

Offres « Achetez X, obtenez Y »

Les offres de type « Achetez X, obtenez Y » permettent aux client·es d’acheter une quantité spécifique de produits « X » pour bénéficier d’un ou de plusieurs produits « Y » à prix réduit ou gratuitement. Sont également prises en charge les offres basées sur un seuil de dépense, où la clientèle doit atteindre un montant minimum d’achat pour un ensemble de produits X afin d’obtenir une réduction. Pour créer une offre « Achetez X, obtenez Y » configurez le champ target_quantity, ainsi que les champs min_quantity ou min_subtotal.

Dans certains cas, comme l’offre classique « un acheté, un offert », X et Y peuvent désigner le même ensemble de produits. Toutefois, vous pouvez utiliser les champs prerequisite_filter, prerequisite_product_retailer_ids, prerequisite_product_group_retailer_ids et prerequisite_product_set_retailer_ids pour spécifier un ensemble de produits X distinct des produits Y ciblés. Consultez la section Définition des produits éligibles pour la configuration de ces champs.

Champ Description

Champ	Description
`target_quantity` Type : `int64`	Facultatif. Valeur par défaut : 0 (illimité). Nombre de produits bénéficiant de la réduction à chaque utilisation de l’offre. Si vous définissez le champ `target_quantity` sur une valeur supérieure à 0, une offre de type « Achetez X, obtenez Y » est activée. Ce champ permet de définir le nombre de produits bénéficiant de la réduction lorsqu’un client ou une cliente remplit les conditions préalables. Exemples : pour une offre « Achetez-en 2, obtenez-en un à 50 % de réduction », la quantité cible est 1, tandis que pour une offre « Achetez-en 5, obtenez-en 2 gratuits », la quantité cible est 2.
`redemption_limit_per_order` Type : `int64`	Facultatif. Valeur par défaut : 0 (illimité). Nombre maximal d’applications de cette offre par commande. Ce champ permet de limiter le nombre de fois où une offre peut s’appliquer aux produits d’un achat. Exemple : pour une offre « un tee-shirt acheté, un t-shirt offert », par défaut, un client ou une cliente achetant six tee-shirts en recevrait trois au prix normal et trois gratuits. Si `redemption_limit_per_order` est fixé à 2, le client ou la cliente recevrait deux t-shirts gratuits et quatre au prix normal. Si ce champ est défini, la valeur du champ `target_quantity` doit être supérieure à 0.

target_quantity

Type : int64

Facultatif. Valeur par défaut : 0 (illimité).

Nombre de produits bénéficiant de la réduction à chaque utilisation de l’offre. Si vous définissez le champ target_quantity sur une valeur supérieure à 0, une offre de type « Achetez X, obtenez Y » est activée.

Ce champ permet de définir le nombre de produits bénéficiant de la réduction lorsqu’un client ou une cliente remplit les conditions préalables. Exemples : pour une offre « Achetez-en 2, obtenez-en un à 50 % de réduction », la quantité cible est 1, tandis que pour une offre « Achetez-en 5, obtenez-en 2 gratuits », la quantité cible est 2.

redemption_limit_per_order

Type : int64

Facultatif. Valeur par défaut : 0 (illimité).

Nombre maximal d’applications de cette offre par commande.

Ce champ permet de limiter le nombre de fois où une offre peut s’appliquer aux produits d’un achat. Exemple : pour une offre « un tee-shirt acheté, un t-shirt offert », par défaut, un client ou une cliente achetant six tee-shirts en recevrait trois au prix normal et trois gratuits. Si redemption_limit_per_order est fixé à 2, le client ou la cliente recevrait deux t-shirts gratuits et quatre au prix normal.

Si ce champ est défini, la valeur du champ target_quantity doit être supérieure à 0.

Combinaison d’offres

Les vendeur·ses utilisant le paiement intégré sur Facebook ou Instagram bénéficient d’une option limitée pour combiner plusieurs offres lors d’une transaction. La possibilité de cumuler une offre avec d’autres dépend essentiellement de son type d’application et de sa cible. À l’heure actuelle, les vendeur·ses ne peuvent pas configurer ce comportement. Voici les principes régissant le cumul des offres :

Pour chaque produit, si plusieurs offres entraînent un prix barré (application_type = SALE), l’offre proposant le prix le plus bas s’applique. Ce processus est répété pour tous les articles du panier. Le nouveau prix réduit sert ensuite de base pour les calculs des conditions des offres suivantes.
Sur une commande, le client ou la cliente peut utiliser soit une offre BUYER_APPLIED, soit une offre AUTOMATIC_AT_CHECKOUT par target_type (LINE_ITEM ou SHIPPING). Par exemple, il est possible de cumuler un code de livraison gratuite avec une offre « un acheté, un offert », mais pas deux offres réduisant le prix des produits.
Meta peut occasionnellement financer des offres pour attirer ou fidéliser la clientèle, sans frais pour les vendeur·ses. Ces offres financées par Meta sont toujours cumulables avec celles des vendeur·ses.

Ciblage des offres

Actuellement, les offres créées via l’API Offers ne peuvent pas être ciblées vers des groupes spécifiques d’utilisateurs et d’utilisatrices. En revanche, les offres créées dans le Gestionnaire des ventes peuvent inclure des critères d’éligibilité. Une offre publiée via l’API Offers sera visible par tous les acheteur·ses, et toute personne répondant aux critères de l’offre (y compris la saisie d’un code promo) pourra en bénéficier lors du paiement sur Facebook ou Instagram.

À l’avenir, l’API Offers pourrait permettre de restreindre les offres à certains pays pour la vente à l’international, ou de les limiter à des groupes spécifiques comme les nouvel·les clients et clientes ou les abonné·es à la Page Facebook du vendeur ou de la vendeuse.