Manage discounts - Chataigne Docs

Discounts are managed at one of two scopes:

A location discount belongs to one restaurant.
An organization discount is a template assigned to one or more locations.

A location list returns both kinds so you can inspect the offers that are effective for that restaurant. Organization-managed entries are read-only on location mutation endpoints; update their template or location mapping through the organization routes.

Endpoints

Location discounts

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}

Organization templates

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}

Organization location mappings

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

Writes require discounts.write; reads require discounts.read. Organization API keys may act on child locations. A location-scoped key cannot act on organization routes.

Create a location discount

Use public product and bundle IDs from the location’s active Catalog API resource. Chataigne never accepts or returns private SKU or database IDs here.

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": "Welcome 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 }
  }'

Date boundaries are inclusive calendar dates evaluated in the location timezone. minimum_order.amount uses whole major currency units; fixed discount amounts support two decimals. PATCH uses merge semantics: omitted fields stay unchanged; explicit null clears nullable fields such as description, image_url, dates, and minimum_order. The benefit type is immutable. To change from a percentage to a free product, create a new discount and deactivate the old one with PATCH { "enabled": false }.

Benefit types

Type	Required fields
`percentage`	`percentage` from more than 0 through 100
`fixed_amount`	`amount` with the target location currency
`free_product`	exactly one product in `reward_items`
`buy_one_get_one`	one or more product or bundle `reward_items`
`buy_x_get_y`	positive `buy_quantity`, `free_quantity`, and product-only `reward_items`
`free_delivery`	no additional field

required_items are eligibility conditions; they do not limit a percentage or fixed amount to those line items.

Organization mappings

Product IDs may differ between restaurant catalogs. Product-based organization discounts therefore carry reward and eligibility item mappings on each location assignment.

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 replaces both mapping arrays for that location. The response reports mapping_status:

ready: every required binding resolves against the active catalog;
unresolved: at least one item is missing or belongs to another catalog;
ambiguous: a stable reference matches more than one catalog item.

Non-ready discounts remain visible to management clients but fail closed during ordering. Organization fixed amounts and minimum-order thresholds require all active target locations to use one currency. A mixed-currency target set returns discount_target_currency_mismatch; per-location monetary overrides are not part of V1.

Deactivation and history

Public API V1 does not expose destructive discount deletion. Deactivate a location discount or organization template with PATCH { "enabled": false }; it remains available for history and can be re-enabled with PATCH { "enabled": true } unless an internal lifecycle operation has already retired it after completed-order use. Existing retired location mappings remain readable with status=retired.

​Endpoints

​Create a location discount

​Benefit types

​Organization mappings

​Deactivation and history

Endpoints

Create a location discount

Benefit types

Organization mappings

Deactivation and history