# Grants

Grants define the monetary benefit (absolute amount or rate) applied when a pricing rule is triggered. They can be configured with per-restaurant overrides and shift-level schedules.

### Get Grant

### `GET /grants/{grantId}` - Get Grant by ID

Returns the grant identified by grantId with its full configuration.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| grantId | integer | Yes | ID of the grant. |

#### Response

```json
{
  "status": 200,
  "code": "grant_found",
  "message": "Grant found.",
  "data": {
    "grantId": 10,
    "brandId": 22,
    "code": "MEAL_SUBSIDY",
    "labelTicket": "Subvention repas",
    "amount": 700,
    "strategy": 1,
    "dailyLimit": 1,
    "type": "ABSOLUTE",
    "tag": null,
    "threshold": null,
    "ceiling": null,
    "restaurants": []
  }
}
```

##### 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 | "grant\_found" | Machine-readable application code for the result. |
| message | string | "Grant found." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.grantId | integer | 10 | Identifier of the associated grant. |
| data.brandId | integer | 22 | Identifier of the brand. |
| data.code | string | "MEAL\_SUBSIDY" | Machine-readable application code for the result. |
| data.labelTicket | string | "Subvention repas" | The label ticket value. |
| data.amount | integer | 700 | The amount value. |
| data.strategy | integer | 1 | The strategy value. |
| data.dailyLimit | integer | 1 | The daily limit value. |
| data.type | string | "ABSOLUTE" | The type value. |
| data.tag | null | null | The tag value. |
| data.threshold | null | null | The threshold value. |
| data.ceiling | null | null | The ceiling value. |
| data.restaurants | array | \[\] | List of restaurants entries. |

### Create Grant

Create a new grant (subsidy) for a brand. Grants can be configured with per-restaurant overrides and shift-level schedules.

### `POST /grants` - Create Grant

Creates a grant with optional restaurant-level overrides and shift schedules.

#### Request Body

```json
{
  "brandId": 22,
  "code": "MEAL_SUBSIDY",
  "labelTicket": "Subvention repas",
  "amount": 700,
  "strategy": 1,
  "dailyLimit": 1,
  "type": "ABSOLUTE",
  "tag": null,
  "threshold": null,
  "ceiling": null,
  "restaurants": [
    {
      "enabled": true,
      "restaurantId": 195,
      "restaurant_grant": {
        "amount": 700,
        "strategy": 1,
        "dailyLimit": 1,
        "threshold": null,
        "ceiling": null
      },
      "shiftGrants": [
        {
          "shiftId": "shift-uuid-1",
          "amount": 700,
          "ceiling": null,
          "threshold": null
        }
      ]
    }
  ]
}
```

##### 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 | "MEAL\_SUBSIDY" | Machine-readable application code for the result. |
| labelTicket | string | "Subvention repas" | The label ticket value. |
| amount | integer | 700 | The amount value. |
| strategy | integer | 1 | The strategy value. |
| dailyLimit | integer | 1 | The daily limit value. |
| type | string | "ABSOLUTE" | The type value. |
| tag | null | null | The tag value. |
| threshold | null | null | The threshold value. |
| ceiling | null | null | The ceiling value. |
| restaurants | array | \[…\] | List of restaurants entries. |
| restaurants\[\] | object | {…} | Object containing restaurants fields. |
| restaurants\[\].enabled | boolean | true | The enabled value. |
| restaurants\[\].restaurantId | integer | 195 | Identifier of the restaurant. |
| restaurants\[\].restaurant\_grant | object | {…} | Object containing restaurant grant fields. |
| restaurants\[\].restaurant\_grant.amount | integer | 700 | The amount value. |
| restaurants\[\].restaurant\_grant.strategy | integer | 1 | The strategy value. |
| restaurants\[\].restaurant\_grant.dailyLimit | integer | 1 | The daily limit value. |
| restaurants\[\].restaurant\_grant.threshold | null | null | The threshold value. |
| restaurants\[\].restaurant\_grant.ceiling | null | null | The ceiling value. |
| restaurants\[\].shiftGrants | array | \[…\] | List of shift grants entries. |
| restaurants\[\].shiftGrants\[\] | object | {…} | Object containing shift grants fields. |
| restaurants\[\].shiftGrants\[\].shiftId | string | "shift-uuid-1" | Identifier of the associated shift. |
| restaurants\[\].shiftGrants\[\].amount | integer | 700 | The amount value. |
| restaurants\[\].shiftGrants\[\].ceiling | null | null | The ceiling value. |
| restaurants\[\].shiftGrants\[\].threshold | null | null | The threshold value. |

#### Response

```json
{
  "status": 200,
  "code": "grant_created",
  "message": "Grant created.",
  "data": {
    "grantId": 10,
    "brandId": 22,
    "code": "MEAL_SUBSIDY",
    "labelTicket": "Subvention repas",
    "amount": 700,
    "strategy": 1,
    "dailyLimit": 1,
    "type": "ABSOLUTE"
  }
}
```

##### 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 | "grant\_created" | Machine-readable application code for the result. |
| message | string | "Grant created." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.grantId | integer | 10 | Identifier of the associated grant. |
| data.brandId | integer | 22 | Identifier of the brand. |
| data.code | string | "MEAL\_SUBSIDY" | Machine-readable application code for the result. |
| data.labelTicket | string | "Subvention repas" | The label ticket value. |
| data.amount | integer | 700 | The amount value. |
| data.strategy | integer | 1 | The strategy value. |
| data.dailyLimit | integer | 1 | The daily limit value. |
| data.type | string | "ABSOLUTE" | The type value. |

#### Field Reference

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | Integer | Yes | The brand this grant belongs to. |
| code | String | Yes | Unique code identifying this grant. |
| labelTicket | String | Yes | Label printed on the receipt/ticket. |
| amount | Integer | Yes | Subsidy amount in cents (e.g. 700 = 7.00 EUR) or rate in basis points depending on `type`. |
| strategy | Integer | Yes | Application strategy identifier that determines how the grant is computed. |
| dailyLimit | Integer | Yes | Maximum number of times a customer can use this grant per day. |
| type | Enum | No | `ABSOLUTE` for a fixed amount, `RATE` for a percentage-based subsidy. |
| tag | String \| null | No | Optional tag for categorization. |
| threshold | Integer \| null | No | Minimum cart amount (in cents) required to trigger the grant. |
| ceiling | Integer \| null | No | Maximum discount amount (in cents) that can be applied. |
| restaurants | Array<Object> | No | Per-restaurant overrides. Each entry contains `restaurantId`, `enabled`, `restaurant_grant` (amount, strategy, dailyLimit, threshold, ceiling), and optional `shiftGrants` array. |

### Update Grant

Update an existing grant. The full configuration including restaurant-level overrides must be provided.

### `PUT /grants/{grantId}` - Update Grant

Replaces the grant configuration identified by grantId.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| grantId | integer | Yes | ID of the grant to update. |

#### Request Body

```json
{
  "code": "MEAL_SUBSIDY_V2",
  "labelTicket": "Subvention repas v2",
  "amount": 800,
  "strategy": 1,
  "dailyLimit": 2,
  "type": "ABSOLUTE",
  "tag": null,
  "threshold": 500,
  "ceiling": 1000,
  "restaurants": [
    {
      "restaurantId": 195,
      "restaurant_grant": {
        "amount": 800,
        "strategy": 1,
        "dailyLimit": 2,
        "threshold": 500,
        "ceiling": 1000
      },
      "shiftGrants": []
    }
  ],
  "shouldUpdateShifts": 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 |
| --- | --- | --- | --- |
| code | string | "MEAL\_SUBSIDY\_V2" | Machine-readable application code for the result. |
| labelTicket | string | "Subvention repas v2" | The label ticket value. |
| amount | integer | 800 | The amount value. |
| strategy | integer | 1 | The strategy value. |
| dailyLimit | integer | 2 | The daily limit value. |
| type | string | "ABSOLUTE" | The type value. |
| tag | null | null | The tag value. |
| threshold | integer | 500 | The threshold value. |
| ceiling | integer | 1000 | The ceiling value. |
| restaurants | array | \[…\] | List of restaurants entries. |
| restaurants\[\] | object | {…} | Object containing restaurants fields. |
| restaurants\[\].restaurantId | integer | 195 | Identifier of the restaurant. |
| restaurants\[\].restaurant\_grant | object | {…} | Object containing restaurant grant fields. |
| restaurants\[\].restaurant\_grant.amount | integer | 800 | The amount value. |
| restaurants\[\].restaurant\_grant.strategy | integer | 1 | The strategy value. |
| restaurants\[\].restaurant\_grant.dailyLimit | integer | 2 | The daily limit value. |
| restaurants\[\].restaurant\_grant.threshold | integer | 500 | The threshold value. |
| restaurants\[\].restaurant\_grant.ceiling | integer | 1000 | The ceiling value. |
| restaurants\[\].shiftGrants | array | \[\] | List of shift grants entries. |
| shouldUpdateShifts | boolean | true | The should update shifts value. |

#### Response

```json
{
  "status": 200,
  "code": "grant_updated",
  "message": "Grant updated.",
  "data": {
    "grantId": 10,
    "code": "MEAL_SUBSIDY_V2",
    "labelTicket": "Subvention repas v2",
    "amount": 800
  }
}
```

##### 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 | "grant\_updated" | Machine-readable application code for the result. |
| message | string | "Grant updated." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.grantId | integer | 10 | Identifier of the associated grant. |
| data.code | string | "MEAL\_SUBSIDY\_V2" | Machine-readable application code for the result. |
| data.labelTicket | string | "Subvention repas v2" | The label ticket value. |
| data.amount | integer | 800 | The amount value. |

### Delete Grant

Permanently delete a grant. This will also remove it from any associated pricing rules.

### `DELETE /grants/{grantId}` - Delete Grant

Deletes the grant identified by grantId.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| grantId | integer | Yes | ID of the grant to delete. |

#### Response

```json
{
  "status": 200,
  "code": "grant_deleted",
  "message": "Grant deleted."
}
```

##### 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 | "grant\_deleted" | Machine-readable application code for the result. |
| message | string | "Grant deleted." | Human-readable result message. Do not use this value for program logic. |

### Brand Grants

Retrieve grants (subsidies/allowances) configured at the brand level. Grants define daily spending allowances that can be applied to customer accounts, typically in collective catering contexts.

### `GET /brands/{brandId}/grants` - Get Grants by Brand

Retrieve all grants associated with a brand.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | The unique identifier of the brand. |

#### Response

```json
{
  "status": 200,
  "code": "grants_found",
  "message": "The grants have been found.",
  "data": [
    {
      "grantId": 301,
      "name": "Employee Lunch Grant",
      "code": "EMP_LUNCH",
      "amount": 700,
      "brandId": 100
    }
  ]
}
```

##### 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 | "grants\_found" | Machine-readable application code for the result. |
| message | string | "The grants have been found." | 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\[\].grantId | integer | 301 | Identifier of the associated grant. |
| data\[\].name | string | "Employee Lunch Grant" | The name value. |
| data\[\].code | string | "EMP\_LUNCH" | Machine-readable application code for the result. |
| data\[\].amount | integer | 700 | The amount value. |
| data\[\].brandId | integer | 100 | Identifier of the brand. |

### `GET /brands/{brandId}/grants/list` - Get Grants List

Retrieve a simplified list of grants for a brand, optimized for dropdown or selection lists.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | The unique identifier of the brand. |

#### Response

```json
{
  "status": 200,
  "code": "grants_found",
  "message": "The grants have been found.",
  "data": [
    {
      "grantId": 301,
      "name": "Employee Lunch Grant",
      "code": "EMP_LUNCH"
    },
    {
      "grantId": 302,
      "name": "Student Grant",
      "code": "STU_GRANT"
    }
  ]
}
```

##### 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 | "grants\_found" | Machine-readable application code for the result. |
| message | string | "The grants have been found." | 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\[\].grantId | integer | 301 | Identifier of the associated grant. |
| data\[\].name | string | "Employee Lunch Grant" | The name value. |
| data\[\].code | string | "EMP\_LUNCH" | Machine-readable application code for the result. |