Guides: Guest App Integration · Innovorder API Documentation

This guide outlines the comprehensive steps to integrate a third-party guest application (e.g., a corporate catering app) with the Innovorder API. By following this recipe, you can enable users to seamlessly view their balance, reload their account, and access their transaction history within your application.

1. Authentication

Each brand is assigned a distinct Service Account. You must first authenticate using these credentials to obtain an accessToken. This token is required to sign and authorize all subsequent API requests.

POST`/oauth/login`Get Access Token

Authenticate using the service account credentials provided for the specific brand. The access token is valid for 24 hours (14 days when rememberMe is true); when it expires the API responds with a 401 error (token_expired) and you must authenticate again.

Request Body

json

{
  "username": "service.account@brand.com",
  "password": "YOUR_SECURE_PASSWORD",
  "grant_type": "password"
}

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
username	string	"service.account@brand.com"	The username value.
password	string	"YOUR_SECURE_PASSWORD"	The password value.
grant_type	string	"password"	The grant type value.

Response

json

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "status": 201,
  "code": "token_created",
  "message": "You have successfully logged in.",
  "data": {
    "user": {
      "userId": 1,
      "email": "service.account@brand.com",
      "role": "brand",
      "brandId": 100
    }
  },
  "token_type": "Bearer"
}

Response Properties

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

Property	Type	Example	Description
access_token	string	"eyJhbGciOiJIUzI1..."	The access token value.
status	integer	201	HTTP status code returned by the API.
code	string	"token_created"	Machine-readable application code for the result.
message	string	"You have successfully logged in."	Human-readable result message. Do not use this value for program logic.
data	object	{…}	Endpoint-specific response payload.
data.user	object	{…}	Object containing user fields.
data.user.userId	integer	1	Identifier of the user.
data.user.email	string	"service.account@brand.com"	Email address.
data.user.role	string	"brand"	The role value.
data.user.brandId	integer	100	Identifier of the brand.
token_type	string	"Bearer"	The token type value.

Header Requirement:Authorization: Bearer <accessToken>

2. User Account Pairing

To link a guest account in your external app with an Innovorder account, use the Customer Search endpoint. This allows you to resolve the Innovorder customerId using an email, name, or badge number.

GET`/customers`Find Customer

Search for a customer to retrieve their internal ID.

Parameters

Name	Type	Required	Description
brandId	string	Yes	The ID of the Brand.
search	string	No	Partial match on name, email, phone, or badge number.
email	string	No	Exact email match.
badgeNumber	string	No	Exact badge number match.

Response

json

{
  "data": [
    {
      "customerId": 12345,
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "badgeNumber": "998877"
    }
  ]
}

Response Properties

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

Property	Type	Example	Description
data	array	[…]	Endpoint-specific response payload.
data[]	object	{…}	Endpoint-specific response payload.
data[].customerId	integer	12345	Identifier of the customer.
data[].firstName	string	"John"	The first name value.
data[].lastName	string	"Doe"	The last name value.
data[].email	string	"john@example.com"	Email address.
data[].badgeNumber	string	"998877"	The badge number value.

3. Display Badge Number

If the guest needs to identify themselves physically at a Kiosk or POS (for example, to pay with their account), you should display their Badge Number. This information is available in the customer details.

GET`/customers/{customerId}`Get Customer Details

Retrieve the profile details including the badge number.

Parameters

Name	Type	Required	Description
customerId	integer	Yes	The Innovorder Customer ID.
unscoped	boolean	No	Must be set to true when calling from a service account.

Response

json

{
  "status": 200,
  "data": {
    "customerId": 12345,
    "firstName": "John",
    "lastName": "Doe",
    "badgeNumber": "998877",
    "email": "john@example.com"
  }
}

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.
data	object	{…}	Endpoint-specific response payload.
data.customerId	integer	12345	Identifier of the customer.
data.firstName	string	"John"	The first name value.
data.lastName	string	"Doe"	The last name value.
data.badgeNumber	string	"998877"	The badge number value.
data.email	string	"john@example.com"	Email address.

4. View Balance

Once you have the customerId, you can retrieve the real-time E-Wallet balance. The balance is returned in cents.

GET`/customers/{customerId}/balance`Get Wallet Balance

Parameters

Name	Type	Required	Description
customerId	integer	Yes	Innovorder Customer ID.
unscoped	boolean	No	Must be set to true when calling from a service account.

Response

json

{
  "status": 200,
  "data": {
    "customerBalance": 2500
  }
}

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.
data	object	{…}	Endpoint-specific response payload.
data.customerBalance	integer	2500	The customer balance value.

5. Reload Balance

Allow the guest to top up their account directly from your app. This operation creates a CREDIT transaction on the user's ledger.

POST`/customers/transactions`Credit E-Wallet

Add funds to a customer wallet.

Request Body

json

{
  "customerId": 12345,
  "brandId": 100,
  "type": "1",
  "amount": "2000",
  "source": "7",
  "paymentOrigin": "4",
  "paymentOriginMetaData": "App Reload Ref#9988"
}

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
customerId	integer	12345	Identifier of the customer.
brandId	integer	100	Identifier of the brand.
type	string	"1"	The type value.
amount	string	"2000"	The amount value.
source	string	"7"	The source value.
paymentOrigin	string	"4"	The payment origin value.
paymentOriginMetaData	string	"App Reload Ref#9988"	The payment origin meta data value.

Response

json

{
  "status": 200,
  "code": "transaction_succeed"
}

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	"transaction_succeed"	Machine-readable application code for the result.

6. View History

E-Wallet Transaction History

Retrieves credits, debits, and adjustments.

GET`/customers/{customerId}/balance_history`Get Wallet Transactions

Parameters

Name	Type	Required	Description
customerId	integer	Yes	Customer ID
limit	integer	No	Pagination limit (default 10)
offset	integer	No	Pagination offset
order	string	No	Sort expression accepted by the pagination middleware.
include	string	No	Comma-separated optional expansions: order, omnichannelOrder, and/or beforeAndAfterBalance.
unscoped	string	No	Use only when your integration is authorized to retrieve soft-deleted customer data.
applyDate	object	No	Optional Unix-timestamp range with gte and lte properties.

Response

json

{
  "status": 200,
  "code": "balance_succeed",
  "message": "You have access to this balance.",
  "data": [
    {
      "transactionId": 94001,
      "customerId": 12345,
      "amount": 2500,
      "type": "CREDIT",
      "status": "OK",
      "applyDate": "2026-07-10T12:00:00.000Z",
      "createdAt": "2026-07-10T12:00:00.000Z",
      "externalOrderReference": null,
      "orderId": null
    }
  ]
}

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	"balance_succeed"	Machine-readable application code for the result.
message	string	"You have access to this balance."	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[].transactionId	integer	94001	Identifier of the transaction.
data[].customerId	integer	12345	Identifier of the customer.
data[].amount	integer	2500	The amount value.
data[].type	string	"CREDIT"	The type value.
data[].status	string	"OK"	HTTP status code returned by the API.
data[].applyDate	string	"2026-07-10T12:00:00.000Z"	Date or timestamp for apply.
data[].createdAt	string	"2026-07-10T12:00:00.000Z"	Timestamp when this resource was created.
data[].externalOrderReference	null	null	The external order reference value.
data[].orderId	null	null	Identifier of the order.

Order History

Retrieves past food orders from POS, Kiosk, or Web. For a complete list of parameters and response fields, refer to the Order History Reference.

Feature: The response includes an htmlTicket field. You can inject this HTML string directly into a WebView to display a perfectly formatted receipt (just like the paper version) without needing to implement complex tax or discount logic on the client side.

GET`/v1/orders`Get Orders

Retrieve a paginated list of orders for the customer.

Parameters

Name	Type	Required	Description
customerId	string	Yes	Customer ID
brandId	string	Yes	Brand ID
limit	integer	No	Max results (default 10)
offset	integer	No	Pagination offset
startDate	string	No	Filter by date (ISO 8601)
status	string	No	Filter by status (e.g. PAID)

Response

json

{
  "status": 200,
  "code": "omnichannel_orders_succeed",
  "message": "Omnichannel orders successfully retrieved.",
  "data": {
    "omnichannelOrders": [
      {
        "omnichannelOrderId": "uuid-1234",
        "status": "PAID",
        "totalPriceDiscountedWithTaxIncluded": 1250,
        "htmlTicket": "<!DOCTYPE html><html>...Receipt Content...</html>"
      }
    ]
  }
}

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	"omnichannel_orders_succeed"	Machine-readable application code for the result.
message	string	"Omnichannel orders successfully retrieved."	Human-readable result message. Do not use this value for program logic.
data	object	{…}	Endpoint-specific response payload.
data.omnichannelOrders	array	[…]	List of omnichannel orders entries.
data.omnichannelOrders[]	object	{…}	Object containing omnichannel orders fields.
data.omnichannelOrders[].omnichannelOrderId	string	"uuid-1234"	Identifier of the associated omnichannel order.
data.omnichannelOrders[].status	string	"PAID"	HTTP status code returned by the API.
data.omnichannelOrders[].totalPriceDiscountedWithTaxIncluded	integer	1250	The total price discounted with tax included value.
data.omnichannelOrders[].htmlTicket	string	"<!DOCTYPE html><html>...Receipt Content...</html>"	The html ticket value.