# Integration Guide: Guest App

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](https://developers.innovorder.io/docs/orders/orders-retrieve.md).

**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 | "&lt;!DOCTYPE html&gt;&lt;html&gt;...Receipt Content...&lt;/html&gt;" | The html ticket value. |