> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gérer les remises

> Créez des remises d’établissement, des modèles d’organisation et leurs mappings produits.

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

```text Remises d’établissement theme={null}
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}
```

```text Modèles d’organisation theme={null}
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}
```

```text Affectations aux établissements theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`.