Loyalty: Rewards & Cart · Innovorder API Documentation

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.