# Rewards & Cart

Retrieve loyalty rewards based on cart content, apply promocodes, void loyalty orders, and compute applicable deals for a given cart.

### `POST /v1/loyalty/restaurants/{restaurantId}/cart/loyalty-data` - Get Loyalty Data with Cart

Retrieve loyalty member information and available rewards based on the current cart contents. This is the main endpoint for getting rewards during the ordering flow. The channel is automatically determined from the caller role (Kiosk, Web, POS).

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| restaurantId | integer | Yes | The unique identifier of the restaurant. |

#### Request Body

```json
{
  "sessionId": "session_abc123",
  "memberId": "ext_789",
  "rewards": [
    {
      "id": "reward_1",
      "status": "available"
    }
  ],
  "cart": {
    "consumptionMode": "EatIn",
    "createdAt": "2024-01-15T12:30:00Z",
    "items": [
      {
        "productId": 101,
        "name": "Classic Burger",
        "categoryId": 5,
        "categoryName": "Burgers",
        "itemNetPrice": 800,
        "itemGrossPrice": 960,
        "quantity": 2,
        "tags": [
          "burger",
          "beef"
        ],
        "sku": "BRG-001"
      }
    ],
    "totalPrice": 1920
  },
  "menuId": 42,
  "channelId": null,
  "shouldSkipCleanAwaitingOrders": 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 |
| --- | --- | --- | --- |
| sessionId | string | "session\_abc123" | Identifier of the associated session. |
| memberId | string | "ext\_789" | Identifier of the associated member. |
| rewards | array | \[…\] | List of rewards entries. |
| rewards\[\] | object | {…} | Object containing rewards fields. |
| rewards\[\].id | string | "reward\_1" | The id value. |
| rewards\[\].status | string | "available" | HTTP status code returned by the API. |
| cart | object | {…} | Object containing cart fields. |
| cart.consumptionMode | string | "EatIn" | The consumption mode value. |
| cart.createdAt | string | "2024-01-15T12:30:00Z" | Timestamp when this resource was created. |
| cart.items | array | \[…\] | List of items entries. |
| cart.items\[\] | object | {…} | Object containing items fields. |
| cart.items\[\].productId | integer | 101 | Identifier of the product. |
| cart.items\[\].name | string | "Classic Burger" | The name value. |
| cart.items\[\].categoryId | integer | 5 | Identifier of the category. |
| cart.items\[\].categoryName | string | "Burgers" | The category name value. |
| cart.items\[\].itemNetPrice | integer | 800 | The item net price value. |
| cart.items\[\].itemGrossPrice | integer | 960 | The item gross price value. |
| cart.items\[\].quantity | integer | 2 | The quantity value. |
| cart.items\[\].tags | array | \[…\] | List of tags entries. |
| cart.items\[\].tags\[\] | string | "burger" | The tags value. |
| cart.items\[\].sku | string | "BRG-001" | The sku value. |
| cart.totalPrice | integer | 1920 | The total price value. |
| menuId | integer | 42 | Identifier of the menu. |
| channelId | null | null | Identifier of the associated channel. |
| shouldSkipCleanAwaitingOrders | boolean | false | The should skip clean awaiting orders value. |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_rewards_found",
  "message": "Loyalty rewards have been found.",
  "data": {
    "member": {
      "id": "ext_789",
      "email": "john.doe@example.com",
      "phoneNumber": null,
      "givenName": "John",
      "familyName": "Doe",
      "tierName": "Gold",
      "points": 1250
    },
    "rewards": [
      {
        "id": "reward_1",
        "name": "Free Dessert",
        "description": "Get a free dessert with your meal",
        "imageUrl": "https://cdn.example.com/rewards/dessert.png",
        "provider": "splio",
        "type": "value",
        "points": 500,
        "value": 350,
        "status": "available"
      }
    ]
  }
}
```

##### 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 | "loyalty\_rewards\_found" | Machine-readable application code for the result. |
| message | string | "Loyalty rewards have been found." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.member | object | {…} | Object containing member fields. |
| data.member.id | string | "ext\_789" | The id value. |
| data.member.email | string | "john.doe@example.com" | Email address. |
| data.member.phoneNumber | null | null | The phone number value. |
| data.member.givenName | string | "John" | The given name value. |
| data.member.familyName | string | "Doe" | The family name value. |
| data.member.tierName | string | "Gold" | The tier name value. |
| data.member.points | integer | 1250 | The points value. |
| data.rewards | array | \[…\] | List of rewards entries. |
| data.rewards\[\] | object | {…} | Object containing rewards fields. |
| data.rewards\[\].id | string | "reward\_1" | The id value. |
| data.rewards\[\].name | string | "Free Dessert" | The name value. |
| data.rewards\[\].description | string | "Get a free dessert with your meal" | The description value. |
| data.rewards\[\].imageUrl | string | "https://cdn.example.com/rewards/dessert.png" | The image url value. |
| data.rewards\[\].provider | string | "splio" | The provider value. |
| data.rewards\[\].type | string | "value" | The type value. |
| data.rewards\[\].points | integer | 500 | The points value. |
| data.rewards\[\].value | integer | 350 | The value value. |
| data.rewards\[\].status | string | "available" | HTTP status code returned by the API. |

### `POST /v1/loyalty/restaurants/{restaurantId}/cart/void` - Void Loyalty Order

Void (cancel) a loyalty order session. This reverses any points or rewards that were consumed during the order. Used when an order is cancelled after loyalty processing.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| restaurantId | integer | Yes | The unique identifier of the restaurant. |

#### Request Body

```json
{
  "memberId": "ext_789",
  "sessionId": "session_abc123",
  "cart": {
    "createdAt": "2024-01-15T12:30:00Z",
    "totalPrice": 1920
  }
}
```

##### 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 |
| --- | --- | --- | --- |
| memberId | string | "ext\_789" | Identifier of the associated member. |
| sessionId | string | "session\_abc123" | Identifier of the associated session. |
| cart | object | {…} | Object containing cart fields. |
| cart.createdAt | string | "2024-01-15T12:30:00Z" | Timestamp when this resource was created. |
| cart.totalPrice | integer | 1920 | The total price value. |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_order_void",
  "message": "Loyalty order has been voided."
}
```

##### 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 | "loyalty\_order\_void" | Machine-readable application code for the result. |
| message | string | "Loyalty order has been voided." | Human-readable result message. Do not use this value for program logic. |

### `POST /v1/loyalty/restaurants/{restaurantId}/promocode` - Apply Promocode

Validate and retrieve the reward associated with a promotion code for a given cart. Returns the discount details if the code is valid and applicable to the current cart.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| restaurantId | integer | Yes | The unique identifier of the restaurant. |

#### Request Body

```json
{
  "sessionId": "session_abc123",
  "memberId": "ext_789",
  "cart": {
    "consumptionMode": "EatIn",
    "createdAt": "2024-01-15T12:30:00Z",
    "items": [
      {
        "productId": 101,
        "name": "Classic Burger",
        "categoryId": 5,
        "categoryName": "Burgers",
        "itemNetPrice": 800,
        "itemGrossPrice": 960,
        "quantity": 1,
        "tags": [
          "burger"
        ]
      }
    ],
    "totalPrice": 960
  },
  "code": "SUMMER2024"
}
```

##### 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 |
| --- | --- | --- | --- |
| sessionId | string | "session\_abc123" | Identifier of the associated session. |
| memberId | string | "ext\_789" | Identifier of the associated member. |
| cart | object | {…} | Object containing cart fields. |
| cart.consumptionMode | string | "EatIn" | The consumption mode value. |
| cart.createdAt | string | "2024-01-15T12:30:00Z" | Timestamp when this resource was created. |
| cart.items | array | \[…\] | List of items entries. |
| cart.items\[\] | object | {…} | Object containing items fields. |
| cart.items\[\].productId | integer | 101 | Identifier of the product. |
| cart.items\[\].name | string | "Classic Burger" | The name value. |
| cart.items\[\].categoryId | integer | 5 | Identifier of the category. |
| cart.items\[\].categoryName | string | "Burgers" | The category name value. |
| cart.items\[\].itemNetPrice | integer | 800 | The item net price value. |
| cart.items\[\].itemGrossPrice | integer | 960 | The item gross price value. |
| cart.items\[\].quantity | integer | 1 | The quantity value. |
| cart.items\[\].tags | array | \[…\] | List of tags entries. |
| cart.items\[\].tags\[\] | string | "burger" | The tags value. |
| cart.totalPrice | integer | 960 | The total price value. |
| code | string | "SUMMER2024" | Machine-readable application code for the result. |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_rewards_found",
  "message": "Loyalty rewards have been found.",
  "data": {
    "id": "promo_reward_1",
    "name": "Summer Promotion",
    "description": "10% off your order",
    "provider": "splio",
    "type": "percentage",
    "points": 0,
    "value": 10,
    "status": "available"
  }
}
```

##### 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 | "loyalty\_rewards\_found" | Machine-readable application code for the result. |
| message | string | "Loyalty rewards have been found." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.id | string | "promo\_reward\_1" | The id value. |
| data.name | string | "Summer Promotion" | The name value. |
| data.description | string | "10% off your order" | The description value. |
| data.provider | string | "splio" | The provider value. |
| data.type | string | "percentage" | The type value. |
| data.points | integer | 0 | The points value. |
| data.value | integer | 10 | The value value. |
| data.status | string | "available" | HTTP status code returned by the API. |

### `POST /v1/loyalty/promotions/applicable` - Get Applicable Promotions

Canonical web and kiosk endpoint for computing cart-wide loyalty promotion discounts. Customer and Kiosk authentication are supported; POS integrations use the restaurant-scoped promotions surface.

#### Request Body

```json
{
  "restaurantId": 1001,
  "memberId": null,
  "cart": {
    "consumptionMode": "EatIn",
    "createdAt": "2026-08-11T12:30:00.000Z",
    "items": [
      {
        "productId": 101,
        "name": "Classic Burger",
        "itemNetPrice": 1500,
        "itemGrossPrice": 1500,
        "quantity": 1,
        "tags": [],
        "sku": "SKU-BURGER"
      }
    ],
    "totalPrice": 1500
  }
}
```

##### 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 |
| --- | --- | --- | --- |
| restaurantId | integer | 1001 | Identifier of the restaurant. |
| memberId | null | null | Identifier of the associated member. |
| cart | object | {…} | Object containing cart fields. |
| cart.consumptionMode | string | "EatIn" | The consumption mode value. |
| cart.createdAt | string | "2026-08-11T12:30:00.000Z" | Timestamp when this resource was created. |
| cart.items | array | \[…\] | List of items entries. |
| cart.items\[\] | object | {…} | Object containing items fields. |
| cart.items\[\].productId | integer | 101 | Identifier of the product. |
| cart.items\[\].name | string | "Classic Burger" | The name value. |
| cart.items\[\].itemNetPrice | integer | 1500 | The item net price value. |
| cart.items\[\].itemGrossPrice | integer | 1500 | The item gross price value. |
| cart.items\[\].quantity | integer | 1 | The quantity value. |
| cart.items\[\].tags | array | \[\] | List of tags entries. |
| cart.items\[\].sku | string | "SKU-BURGER" | The sku value. |
| cart.totalPrice | integer | 1500 | The total price value. |

#### Response

```json
{
  "status": 200,
  "code": "success",
  "message": "Success",
  "data": [
    {
      "id": "prom_1234567803",
      "label": "10% off",
      "value": 150
    }
  ]
}
```

##### 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 | "success" | Machine-readable application code for the result. |
| message | string | "Success" | 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\[\].id | string | "prom\_1234567803" | The id value. |
| data\[\].label | string | "10% off" | The label value. |
| data\[\].value | integer | 150 | The value value. |

### `POST /v1/loyalty/deals/applicable` - Get Applicable Deals (Deprecated Alias)

Deprecated alias of POST /v1/loyalty/promotions/applicable. It keeps the same response contract while existing kiosk, web ordering, and POS clients migrate to their canonical promotion surfaces.

#### Request Body

```json
{
  "restaurantId": 1001,
  "memberId": "ext_789",
  "cart": {
    "consumptionMode": "EatIn",
    "createdAt": "2024-01-15T12:30:00Z",
    "items": [
      {
        "productId": 101,
        "name": "Classic Burger",
        "categoryId": 5,
        "categoryName": "Burgers",
        "itemNetPrice": 800,
        "itemGrossPrice": 960,
        "quantity": 2,
        "tags": [
          "burger"
        ]
      }
    ],
    "totalPrice": 1920
  }
}
```

##### 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 |
| --- | --- | --- | --- |
| restaurantId | integer | 1001 | Identifier of the restaurant. |
| memberId | string | "ext\_789" | Identifier of the associated member. |
| cart | object | {…} | Object containing cart fields. |
| cart.consumptionMode | string | "EatIn" | The consumption mode value. |
| cart.createdAt | string | "2024-01-15T12:30:00Z" | Timestamp when this resource was created. |
| cart.items | array | \[…\] | List of items entries. |
| cart.items\[\] | object | {…} | Object containing items fields. |
| cart.items\[\].productId | integer | 101 | Identifier of the product. |
| cart.items\[\].name | string | "Classic Burger" | The name value. |
| cart.items\[\].categoryId | integer | 5 | Identifier of the category. |
| cart.items\[\].categoryName | string | "Burgers" | The category name value. |
| cart.items\[\].itemNetPrice | integer | 800 | The item net price value. |
| cart.items\[\].itemGrossPrice | integer | 960 | The item gross price value. |
| cart.items\[\].quantity | integer | 2 | The quantity value. |
| cart.items\[\].tags | array | \[…\] | List of tags entries. |
| cart.items\[\].tags\[\] | string | "burger" | The tags value. |
| cart.totalPrice | integer | 1920 | The total price value. |

#### Response

```json
{
  "status": 200,
  "code": "success",
  "message": "Success",
  "data": [
    {
      "name": "Buy 2 Get 10% Off",
      "type": "percentage",
      "value": 10,
      "scope": "order"
    }
  ]
}
```

##### 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 | "success" | Machine-readable application code for the result. |
| message | string | "Success" | 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\[\].name | string | "Buy 2 Get 10% Off" | The name value. |
| data\[\].type | string | "percentage" | The type value. |
| data\[\].value | integer | 10 | The value value. |
| data\[\].scope | string | "order" | The scope value. |

### Loyalty Cards (Internal)

Manage Innovorder internal loyalty system cards. These endpoints handle card lookup, validation, royalty management, and card lifecycle operations. This is separate from the external provider-based loyalty system.

### `GET /loyalty_cards` - List Loyalty Cards

Retrieve a paginated list of loyalty cards for a brand. Supports filtering by customer, batch number, search term, and currency unit preference.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brand\_id | integer | Yes | The unique identifier of the brand. |
| limit | integer | No | Maximum number of results to return. |
| offset | integer | No | Number of results to skip for pagination. |
| order | string | No | Sort order for results. |
| customer\_id | integer | No | Filter by customer ID. |
| batch\_number | string | No | Filter by card batch number. |
| search | string | No | Search term to filter cards. |
| unit\_currency | boolean | No | Whether to display amounts in currency units (default: false). |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_card_success",
  "message": "You can access this loyalty card.",
  "data": [
    {
      "loyaltyCardId": 1001,
      "cardNumber": "CARD-001234",
      "customerId": 5001,
      "brandId": 10,
      "batchNumber": "BATCH-2024-01",
      "balance": 1500,
      "status": "active",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}
```

##### 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 | "loyalty\_card\_success" | Machine-readable application code for the result. |
| message | string | "You can access this loyalty card." | 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\[\].loyaltyCardId | integer | 1001 | Identifier of the associated loyalty card. |
| data\[\].cardNumber | string | "CARD-001234" | The card number value. |
| data\[\].customerId | integer | 5001 | Identifier of the customer. |
| data\[\].brandId | integer | 10 | Identifier of the brand. |
| data\[\].batchNumber | string | "BATCH-2024-01" | The batch number value. |
| data\[\].balance | integer | 1500 | The balance value. |
| data\[\].status | string | "active" | HTTP status code returned by the API. |
| data\[\].createdAt | string | "2024-01-15T10:00:00Z" | Timestamp when this resource was created. |

### `GET /loyalty_cards/count` - Count Loyalty Cards

Count the total number of loyalty cards matching the given filters. Uses the same filter parameters as the list endpoint.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brand\_id | integer | Yes | The unique identifier of the brand. |
| customer\_id | integer | No | Filter by customer ID. |
| batch\_number | string | No | Filter by card batch number. |
| search | string | No | Search term to filter cards. |
| unit\_currency | boolean | No | Whether to display amounts in currency units (default: false). |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_card_success",
  "message": "You can access this loyalty card.",
  "data": {
    "count": 42
  }
}
```

##### 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 | "loyalty\_card\_success" | Machine-readable application code for the result. |
| message | string | "You can access this loyalty card." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.count | integer | 42 | Total number of matching records. |

### `GET /loyalty_cards/validate` - Validate Loyalty Card

Validate a loyalty card number for a brand. This is a public endpoint protected by reCAPTCHA. Used to verify that a card number exists and is valid before associating it with a customer.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brand\_id | integer | Yes | The unique identifier of the brand. |
| card\_number | string | Yes | The loyalty card number to validate. |
| g-recaptcha-response | string | Yes | Google reCAPTCHA verification token. |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_card_success",
  "message": "You can access this loyalty card.",
  "data": {
    "loyaltyCardId": 1001,
    "cardNumber": "CARD-001234",
    "brandId": 10,
    "balance": 1500,
    "status": "active",
    "isValid": true
  }
}
```

##### 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 | "loyalty\_card\_success" | Machine-readable application code for the result. |
| message | string | "You can access this loyalty card." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.loyaltyCardId | integer | 1001 | Identifier of the associated loyalty card. |
| data.cardNumber | string | "CARD-001234" | The card number value. |
| data.brandId | integer | 10 | Identifier of the brand. |
| data.balance | integer | 1500 | The balance value. |
| data.status | string | "active" | HTTP status code returned by the API. |
| data.isValid | boolean | true | Whether valid is enabled or applies. |

### `GET /loyalty_cards/{loyaltyCardId}` - Get Loyalty Card by ID

Retrieve a specific loyalty card by its unique identifier. Returns the full card details including balance and associated customer information.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| loyaltyCardId | integer | Yes | The unique identifier of the loyalty card. |
| unit\_currency | boolean | No | Whether to display amounts in currency units (default: false). |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_card_success",
  "message": "You can access this loyalty card.",
  "data": {
    "loyaltyCardId": 1001,
    "cardNumber": "CARD-001234",
    "customerId": 5001,
    "brandId": 10,
    "batchNumber": "BATCH-2024-01",
    "balance": 1500,
    "status": "active",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}
```

##### 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 | "loyalty\_card\_success" | Machine-readable application code for the result. |
| message | string | "You can access this loyalty card." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.loyaltyCardId | integer | 1001 | Identifier of the associated loyalty card. |
| data.cardNumber | string | "CARD-001234" | The card number value. |
| data.customerId | integer | 5001 | Identifier of the customer. |
| data.brandId | integer | 10 | Identifier of the brand. |
| data.batchNumber | string | "BATCH-2024-01" | The batch number value. |
| data.balance | integer | 1500 | The balance value. |
| data.status | string | "active" | HTTP status code returned by the API. |
| data.createdAt | string | "2024-01-15T10:00:00Z" | Timestamp when this resource was created. |

### `DELETE /loyalty_cards/{loyaltyCardId}/royalties` - Cancel Royalty by Card ID

Cancel a royalty transaction associated with a loyalty card. This reverses a previously credited royalty, typically used when an order is voided or refunded.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| loyaltyCardId | integer | Yes | The unique identifier of the loyalty card. |

#### Request Body

```json
{
  "externalOrderReference": "order_12345",
  "source": "pos"
}
```

##### 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 |
| --- | --- | --- | --- |
| externalOrderReference | string | "order\_12345" | The external order reference value. |
| source | string | "pos" | The source value. |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_card_royalty_cancel_success",
  "message": "You have done the royalty transactions cancel.",
  "data": {
    "loyaltyCardId": 1001,
    "balance": 1000,
    "cancelledAmount": 500
  }
}
```

##### 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 | "loyalty\_card\_royalty\_cancel\_success" | Machine-readable application code for the result. |
| message | string | "You have done the royalty transactions cancel." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.loyaltyCardId | integer | 1001 | Identifier of the associated loyalty card. |
| data.balance | integer | 1000 | The balance value. |
| data.cancelledAmount | integer | 500 | The cancelled amount value. |

### `DELETE /loyalty_cards/{loyaltyCardId}` - Delete Loyalty Card

Permanently delete a loyalty card. Requires Brand or Restaurant role. The brand\_id query parameter is used for access control validation.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| loyaltyCardId | integer | Yes | The unique identifier of the loyalty card to delete. |
| brand\_id | integer | Yes | The brand ID for access control validation. |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_card_delete_success",
  "message": "This card has been successfully deleted.",
  "data": {
    "loyaltyCardId": 1001,
    "cardNumber": "CARD-001234",
    "customerId": 5001,
    "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 | "loyalty\_card\_delete\_success" | Machine-readable application code for the result. |
| message | string | "This card has been successfully deleted." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.loyaltyCardId | integer | 1001 | Identifier of the associated loyalty card. |
| data.cardNumber | string | "CARD-001234" | The card number value. |
| data.customerId | integer | 5001 | Identifier of the customer. |
| data.brandId | integer | 100 | Identifier of the brand. |