Gérer les remises - Chataigne Docs

Les remises sont gérées dans l’un des deux périmètres suivants :

Une remise d’établissement appartient à un seul restaurant.
Une remise d’organisation est un modèle affecté à un ou plusieurs établissements.

La liste d’un établissement renvoie les deux types afin d’afficher toutes les offres effectives pour ce restaurant. Les remises provenant de l’organisation sont en lecture seule sur les routes de mutation d’un établissement ; modifiez leur modèle ou leur affectation via les routes de l’organisation.

Endpoints

Remises d’établissement

GET    /v1/locations/{location_id}/discounts
POST   /v1/locations/{location_id}/discounts
GET    /v1/locations/{location_id}/discounts/{discount_id}
PATCH  /v1/locations/{location_id}/discounts/{discount_id}

Modèles d’organisation

GET    /v1/organizations/{organization_id}/discounts
POST   /v1/organizations/{organization_id}/discounts
GET    /v1/organizations/{organization_id}/discounts/{discount_id}
PATCH  /v1/organizations/{organization_id}/discounts/{discount_id}

Affectations aux établissements

GET    /v1/organizations/{organization_id}/discounts/{discount_id}/locations
PUT    /v1/organizations/{organization_id}/discounts/{discount_id}/locations/{location_id}

Les écritures exigent discounts.write et les lectures discounts.read. Une clé d’organisation peut agir sur ses établissements enfants. Une clé limitée à un établissement ne peut pas agir sur les routes de l’organisation.

Créer une remise d’établissement

Utilisez les identifiants publics des produits et bundles du catalogue actif. Chataigne n’accepte et ne renvoie jamais ici les identifiants privés des SKU ou de la base de données.

curl https://server.chataigne.ai/v1/locations/loc_123/discounts \
  -X POST \
  -H 'x-api-key: ck_live_...' \
  -H 'content-type: application/json' \
  -H 'idempotency-key: 86fa9212-87e5-4de8-951a-c119b26bb9b8' \
  -d '{
    "name": "Bienvenue -10 %",
    "code": "WELCOME10",
    "visibility": "public",
    "once_per_customer": true,
    "combinable": true,
    "starts_on": "2026-09-01",
    "ends_on": "2026-09-30",
    "minimum_order": { "amount": 20, "currency": "EUR" },
    "required_items": [{ "type": "product", "id": "burger-classic" }],
    "benefit": { "type": "percentage", "percentage": 10 }
  }'

Les bornes de date sont des dates calendaires inclusives évaluées dans le fuseau horaire de l’établissement. minimum_order.amount utilise des unités monétaires majeures entières ; les montants de remise fixe acceptent deux décimales. PATCH suit une sémantique de fusion : un champ omis reste inchangé ; null efface les champs nullable comme description, image_url, les dates et minimum_order. Le type d’avantage est immuable. Pour remplacer un pourcentage par un produit offert, créez une nouvelle remise puis désactivez l’ancienne avec PATCH { "enabled": false }.

Types d’avantage

Type	Champs requis
`percentage`	`percentage` strictement supérieur à 0 et inférieur ou égal à 100
`fixed_amount`	`amount` dans la devise de l’établissement cible
`free_product`	exactement un produit dans `reward_items`
`buy_one_get_one`	un ou plusieurs produits ou bundles dans `reward_items`
`buy_x_get_y`	`buy_quantity`, `free_quantity` positifs et produits uniquement dans `reward_items`
`free_delivery`	aucun champ supplémentaire

required_items représente une condition d’éligibilité ; ce champ ne limite pas le pourcentage ou le montant fixe à ces lignes de commande.

Mappings d’organisation

Les identifiants produits peuvent différer entre les catalogues des restaurants. Les remises d’organisation liées à des produits portent donc leurs mappings de récompense et d’éligibilité sur chaque affectation d’établissement.

curl https://server.chataigne.ai/v1/organizations/org_123/discounts/disc_456/locations/loc_123 \
  -X PUT \
  -H 'x-api-key: ck_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "required_items": [{ "type": "product", "id": "burger-classic" }],
    "reward_items": [{ "type": "product", "id": "drink-cola" }]
  }'

PUT remplace les deux tableaux de mapping pour cet établissement. La réponse expose mapping_status :

ready : chaque mapping requis est résolu dans le catalogue actif ;
unresolved : au moins un article est absent ou appartient à un autre catalogue ;
ambiguous : une référence stable correspond à plusieurs articles.

Une remise dont le mapping n’est pas prêt reste visible dans l’API de gestion, mais son application à une commande échoue de manière sûre. Les montants fixes et seuils minimum d’une organisation exigent une devise unique sur tous les établissements actifs ciblés. Un ensemble multidevise renvoie discount_target_currency_mismatch ; les montants spécifiques à chaque établissement ne font pas partie de la V1.

Désactivation et historique

L’API publique V1 n’expose aucune suppression destructive de remise. Désactivez une remise d’établissement ou un modèle d’organisation avec PATCH { "enabled": false } ; la ressource reste disponible dans l’historique et peut être réactivée avec PATCH { "enabled": true }, sauf si une opération interne l’a déjà retirée après une utilisation dans une commande terminée. Les affectations déjà retirées restent consultables avec status=retired.

​Endpoints

​Créer une remise d’établissement

​Types d’avantage

​Mappings d’organisation

​Désactivation et historique

Endpoints

Créer une remise d’établissement

Types d’avantage

Mappings d’organisation

Désactivation et historique