# Coupons

 ⚠️ 

#### Platform Limitation

Couponing features currently only function on **Web Ordering** channels and via the **Create Order API**. Coupons configured here will not be applicable or recognized on POS or Kiosk devices at this time.

Manage promotional codes for your brand. Coupons can be configured with specific validity dates, usage limits, consumption mode restrictions, and discount types.

### List Coupons

Retrieve all promotional codes configured for your brand or specific restaurants.

### `GET /promocodes` - List All Coupons

Returns a list of all active and inactive coupons.

#### Response

```json
{
  "status": 200,
  "code": "promocode_succeed",
  "message": "Le promocode a été récupéré.",
  "data": [
    {
      "promocodeId": 29,
      "code": "SALUT",
      "reductionType": "absolute",
      "restaurantName": "Sushi shop courcelle",
      "reductionValue": 500,
      "isActive": true,
      "startDate": "2017-07-01T16:46:11.000Z",
      "endDate": "2017-08-03T22:00:00.000Z",
      "isActivatedOnDelivery": true,
      "isActivatedOnSitIn": false,
      "isActivatedOnTakeAway": false,
      "consumptionFlags": 1,
      "nonCumulative": false,
      "used": 0
    },
    {
      "promocodeId": 32,
      "code": "FIDELITE2017",
      "reductionType": "percentage",
      "restaurantName": "Sushi shop courcelle",
      "reductionValue": 1500,
      "isActive": true,
      "startDate": "2017-07-02T17:08:28.000Z",
      "endDate": "2017-07-30T22:00:00.000Z",
      "isActivatedOnDelivery": true,
      "isActivatedOnSitIn": false,
      "isActivatedOnTakeAway": false,
      "consumptionFlags": 1,
      "nonCumulative": false,
      "used": 0
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "promocode\_succeed" | Machine-readable application code for the result. |
| message | string | "Le promocode a été récupéré." | Human-readable result message. Do not use this value for program logic. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].promocodeId | integer | 29 | Identifier of the associated promocode. |
| data\[\].code | string | "SALUT" | Machine-readable application code for the result. |
| data\[\].reductionType | string | "absolute" | The reduction type value. |
| data\[\].restaurantName | string | "Sushi shop courcelle" | The restaurant name value. |
| data\[\].reductionValue | integer | 500 | The reduction value value. |
| data\[\].isActive | boolean | true | Whether this resource is active. |
| data\[\].startDate | string | "2017-07-01T16:46:11.000Z" | Date or timestamp for start. |
| data\[\].endDate | string | "2017-08-03T22:00:00.000Z" | Date or timestamp for end. |
| data\[\].isActivatedOnDelivery | boolean | true | Whether activated on delivery is enabled or applies. |
| data\[\].isActivatedOnSitIn | boolean | false | Whether activated on sit in is enabled or applies. |
| data\[\].isActivatedOnTakeAway | boolean | false | Whether activated on take away is enabled or applies. |
| data\[\].consumptionFlags | integer | 1 | The consumption flags value. |
| data\[\].nonCumulative | boolean | false | The non cumulative value. |
| data\[\].used | integer | 0 | The used value. |

### Create Coupon

Create a new promotional campaign.

### `POST /promocodes` - Create Coupon

#### Request Body

```json
{
  "brandId": 22,
  "code": "TEST",
  "reductionType": "absolute",
  "reductionValue": "200",
  "quantity": 100,
  "minimumAmount": "200",
  "startDate": "2025-12-07T23:00:00.000Z",
  "endDate": "2025-12-08T22:59:59.059Z",
  "consumptionFlags": 15,
  "restaurantIds": [
    195
  ],
  "noLimit": true,
  "isUnique": true,
  "nonCumulative": true
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| brandId | integer | 22 | Identifier of the brand. |
| code | string | "TEST" | Machine-readable application code for the result. |
| reductionType | string | "absolute" | The reduction type value. |
| reductionValue | string | "200" | The reduction value value. |
| quantity | integer | 100 | The quantity value. |
| minimumAmount | string | "200" | The minimum amount value. |
| startDate | string | "2025-12-07T23:00:00.000Z" | Date or timestamp for start. |
| endDate | string | "2025-12-08T22:59:59.059Z" | Date or timestamp for end. |
| consumptionFlags | integer | 15 | The consumption flags value. |
| restaurantIds | array | \[…\] | List of restaurant ids entries. |
| restaurantIds\[\] | integer | 195 | The restaurant ids value. |
| noLimit | boolean | true | The no limit value. |
| isUnique | boolean | true | Whether unique is enabled or applies. |
| nonCumulative | boolean | true | The non cumulative value. |

#### Response

```json
{
  "status": 201,
  "code": "promocode_created_succeed",
  "message": "Le promocode a été créé.",
  "data": [
    {
      "promocodeId": 351693,
      "code": "TEST",
      "isActive": true,
      "reductionType": "absolute",
      "reductionValue": 200,
      "minimumAmount": 200,
      "startDate": "2025-12-07T23:00:00.000Z",
      "endDate": null,
      "consumptionFlags": 15,
      "isUnique": true,
      "nonCumulative": true,
      "created_at": "2025-12-08T17:23:45.000Z"
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 201 | HTTP status code returned by the API. |
| code | string | "promocode\_created\_succeed" | Machine-readable application code for the result. |
| message | string | "Le promocode a été créé." | Human-readable result message. Do not use this value for program logic. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].promocodeId | integer | 351693 | Identifier of the associated promocode. |
| data\[\].code | string | "TEST" | Machine-readable application code for the result. |
| data\[\].isActive | boolean | true | Whether this resource is active. |
| data\[\].reductionType | string | "absolute" | The reduction type value. |
| data\[\].reductionValue | integer | 200 | The reduction value value. |
| data\[\].minimumAmount | integer | 200 | The minimum amount value. |
| data\[\].startDate | string | "2025-12-07T23:00:00.000Z" | Date or timestamp for start. |
| data\[\].endDate | null | null | Date or timestamp for end. |
| data\[\].consumptionFlags | integer | 15 | The consumption flags value. |
| data\[\].isUnique | boolean | true | Whether unique is enabled or applies. |
| data\[\].nonCumulative | boolean | true | The non cumulative value. |
| data\[\].created\_at | string | "2025-12-08T17:23:45.000Z" | Timestamp when this resource was created. |

#### Field Reference

| Field | Type | Description |
| --- | --- | --- |
| brandId | Integer | The unique identifier of the brand owning the coupon. |
| code | String | The alphanumeric code entered by the user (e.g., "SUMMER2025"). |
| reductionType | Enum | `absolute` for fixed amount discount, `percentage` for relative discount. |
| reductionValue | Integer | Value of the discount. If absolute: value in cents (e.g., 500 = 5.00). If percentage: basis points (e.g., 1500 = 15%). |
| minimumAmount | Integer | Minimum cart total (in cents) required to apply the coupon. |
| quantity | Integer | Global limit of usages for this campaign. |
| noLimit | Boolean | If true, ignores the quantity limit. |
| startDate / endDate | ISO Date | Validity window for the coupon. |
| consumptionFlags | Integer (Bitmask) | 1 = Delivery, 2 = Takeaway, 4 = Sit-in. Sum to combine (e.g., 15 = all). |
| isUnique | Boolean | If true, the code is a single-issue identifier. |
| nonCumulative | Boolean | If true, cannot be combined with other discounts. |
| restaurantIds | Array<Integer> | List of restaurant IDs where this coupon is valid. |

### Update Coupon

Modify an existing coupon's properties, such as extending the end date or changing the quantity.

### `PUT /promocodes/{promocodeId}` - Update Coupon

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| promocodeId | integer | Yes | ID of the coupon to update. |

#### Request Body

```json
{
  "promocodeId": 29,
  "code": "SALUT",
  "reductionValue": 500,
  "isActive": true,
  "startDate": "2017-06-30T22:00:00.000Z",
  "endDate": "2017-08-04T21:59:59.059Z",
  "quantity": 100,
  "minimumAmount": 1000,
  "consumptionFlags": 1,
  "noLimit": false
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| promocodeId | integer | 29 | Identifier of the associated promocode. |
| code | string | "SALUT" | Machine-readable application code for the result. |
| reductionValue | integer | 500 | The reduction value value. |
| isActive | boolean | true | Whether this resource is active. |
| startDate | string | "2017-06-30T22:00:00.000Z" | Date or timestamp for start. |
| endDate | string | "2017-08-04T21:59:59.059Z" | Date or timestamp for end. |
| quantity | integer | 100 | The quantity value. |
| minimumAmount | integer | 1000 | The minimum amount value. |
| consumptionFlags | integer | 1 | The consumption flags value. |
| noLimit | boolean | false | The no limit value. |

#### Response

```json
{
  "status": 200,
  "code": "promocode_updated_succeed",
  "message": "Le promocode a été mis à jour.",
  "data": {
    "promocodeId": 29,
    "code": "SALUT",
    "isActive": true,
    "updated_at": "..."
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "promocode\_updated\_succeed" | Machine-readable application code for the result. |
| message | string | "Le promocode a été mis à jour." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.promocodeId | integer | 29 | Identifier of the associated promocode. |
| data.code | string | "SALUT" | Machine-readable application code for the result. |
| data.isActive | boolean | true | Whether this resource is active. |
| data.updated\_at | string | "..." | Timestamp when this resource was last updated. |

### Delete Coupon

Permanently remove a coupon. This action cannot be undone.

### `DELETE /promocodes/{promocodeId}` - Delete Coupon

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| promocodeId | integer | Yes | ID of the coupon to delete. |

#### Response

```json
{
  "status": 200,
  "code": "promocode_deleted_succeed",
  "message": "Le promocode a été détruit."
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "promocode\_deleted\_succeed" | Machine-readable application code for the result. |
| message | string | "Le promocode a été détruit." | Human-readable result message. Do not use this value for program logic. |