# Setup

Manage loyalty provider configuration for restaurants and brands. Each restaurant can be connected to one loyalty provider (Splio, Como, or Pongo).

### `GET /v1/loyalty/restaurants/{restaurantId}/config` - Get Restaurant Loyalty Config

Retrieve the loyalty configuration for a specific restaurant. The restaurantId can be either a numeric ID or a UUID. Returns the provider configuration, authentication methods, register methods, and feature flags. The API key is omitted from the response.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| restaurantId | integer \| string (UUID) | Yes | The restaurant ID (numeric) or UUID. |

#### Response

```json
{
  "status": 200,
  "code": "module_loyalty_succeed",
  "message": "A module loyalty has been retrieved.",
  "data": {
    "moduleLoyaltyProviderId": 42,
    "restaurantId": 1001,
    "brandId": 10,
    "provider": "splio",
    "programId": "program_abc123",
    "memberIdentifier": "email",
    "loginMethod": "email",
    "formLink": "https://example.com/loyalty-form",
    "useCasualTone": true,
    "authModes": [
      "email"
    ],
    "authenticationMethods": {
      "email": true,
      "phone": false,
      "externalId": false
    },
    "registerMethods": {
      "email": true,
      "phone": false
    },
    "features": [
      {
        "id": 1,
        "name": "smart_pass",
        "isEnabled": true
      },
      {
        "id": 2,
        "name": "order_details_v2",
        "isEnabled": false
      }
    ]
  }
}
```

##### 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 | "module\_loyalty\_succeed" | Machine-readable application code for the result. |
| message | string | "A module loyalty has been retrieved." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.moduleLoyaltyProviderId | integer | 42 | Identifier of the associated module loyalty provider. |
| data.restaurantId | integer | 1001 | Identifier of the restaurant. |
| data.brandId | integer | 10 | Identifier of the brand. |
| data.provider | string | "splio" | The provider value. |
| data.programId | string | "program\_abc123" | Identifier of the associated program. |
| data.memberIdentifier | string | "email" | The member identifier value. |
| data.loginMethod | string | "email" | The login method value. |
| data.formLink | string | "https://example.com/loyalty-form" | The form link value. |
| data.useCasualTone | boolean | true | The use casual tone value. |
| data.authModes | array | \[…\] | List of auth modes entries. |
| data.authModes\[\] | string | "email" | The auth modes value. |
| data.authenticationMethods | object | {…} | Object containing authentication methods fields. |
| data.authenticationMethods.email | boolean | true | Email address. |
| data.authenticationMethods.phone | boolean | false | Phone number. |
| data.authenticationMethods.externalId | boolean | false | Identifier in the connected external system. |
| data.registerMethods | object | {…} | Object containing register methods fields. |
| data.registerMethods.email | boolean | true | Email address. |
| data.registerMethods.phone | boolean | false | Phone number. |
| data.features | array | \[…\] | List of features entries. |
| data.features\[\] | object | {…} | Object containing features fields. |
| data.features\[\].id | integer | 1 | The id value. |
| data.features\[\].name | string | "smart\_pass" | The name value. |
| data.features\[\].isEnabled | boolean | true | Whether this feature is enabled. |

### `GET /v1/loyalty/restaurants/{restaurantId}/eligibility` - Get External Loyalty Eligibility

Checks whether an external loyalty provider can be enabled for the restaurant. External loyalty is unavailable only when Innovorder Royalty is enabled at both the brand and restaurant levels.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| restaurantId | integer | Yes | Restaurant whose loyalty eligibility is checked. |

#### Response

```json
{
  "status": 200,
  "code": "loyalty_eligibility_succeed",
  "message": "External loyalty eligibility has been retrieved.",
  "data": {
    "isRoyaltyEnabledOnBrand": true,
    "isRoyaltyEnabledOnRestaurant": false,
    "canEnableExternalLoyalty": 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\_eligibility\_succeed" | Machine-readable application code for the result. |
| message | string | "External loyalty eligibility has been retrieved." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.isRoyaltyEnabledOnBrand | boolean | true | Whether royalty enabled on brand is enabled or applies. |
| data.isRoyaltyEnabledOnRestaurant | boolean | false | Whether royalty enabled on restaurant is enabled or applies. |
| data.canEnableExternalLoyalty | boolean | true | Whether enable external loyalty is enabled or applies. |

### `GET /v1/loyalty/brands/{brandId}/config` - Get Brand Loyalty Configs

Retrieve loyalty configurations for all restaurants within a brand. Returns an array of configurations, one per restaurant. The API key is omitted from each configuration.

#### Parameters

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

#### Response

```json
{
  "status": 200,
  "code": "module_loyalty_succeed",
  "message": "A module loyalty has been retrieved.",
  "data": [
    {
      "moduleLoyaltyProviderId": 42,
      "restaurantId": 1001,
      "brandId": 10,
      "provider": "splio",
      "programId": "program_abc123",
      "memberIdentifier": "email",
      "loginMethod": "email"
    },
    {
      "moduleLoyaltyProviderId": 43,
      "restaurantId": 1002,
      "brandId": 10,
      "provider": "como",
      "programId": "program_def456",
      "memberIdentifier": "phone",
      "loginMethod": "phone"
    }
  ]
}
```

##### 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 | "module\_loyalty\_succeed" | Machine-readable application code for the result. |
| message | string | "A module loyalty has been retrieved." | 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\[\].moduleLoyaltyProviderId | integer | 42 | Identifier of the associated module loyalty provider. |
| data\[\].restaurantId | integer | 1001 | Identifier of the restaurant. |
| data\[\].brandId | integer | 10 | Identifier of the brand. |
| data\[\].provider | string | "splio" | The provider value. |
| data\[\].programId | string | "program\_abc123" | Identifier of the associated program. |
| data\[\].memberIdentifier | string | "email" | The member identifier value. |
| data\[\].loginMethod | string | "email" | The login method value. |

### `PUT /v1/loyalty/restaurants/{restaurantId}/config` - Upsert Restaurant Loyalty Config

Create or update the loyalty provider configuration for a restaurant. If a restaurant-level and brand-level loyalty module both exist, a conflict error is returned. Requires Brand or Restaurant role.

#### Parameters

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

#### Request Body

```json
{
  "provider": "splio",
  "apiKey": "sk_live_abc123def456",
  "programId": "program_abc123",
  "memberIdentifier": "email",
  "programTermsUrl": "https://example.com/terms",
  "optInLists": {
    "LOYALTY": 1,
    "MARKETING": 2
  },
  "splio": {
    "syncMenu": true,
    "smartPass": {
      "urlPrefix": "https://smartpass.example.com",
      "organizationId": "org_123",
      "projectId": "proj_456",
      "organizationSecret": "secret_789"
    }
  },
  "formLink": "https://example.com/loyalty-form",
  "useCasualTone": true,
  "allowCustomerRewardUsage": true,
  "authenticationMethods": {
    "email": true,
    "phone": false,
    "externalId": false
  },
  "registerMethods": {
    "email": true,
    "phone": false
  },
  "features": [
    {
      "id": 1,
      "isEnabled": true
    },
    {
      "id": 2,
      "isEnabled": 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 |
| --- | --- | --- | --- |
| provider | string | "splio" | The provider value. |
| apiKey | string | "sk\_live\_abc123def456" | The api key value. |
| programId | string | "program\_abc123" | Identifier of the associated program. |
| memberIdentifier | string | "email" | The member identifier value. |
| programTermsUrl | string | "https://example.com/terms" | The program terms url value. |
| optInLists | object | {…} | Object containing opt in lists fields. |
| optInLists.LOYALTY | integer | 1 | The loyalty value. |
| optInLists.MARKETING | integer | 2 | The marketing value. |
| splio | object | {…} | Object containing splio fields. |
| splio.syncMenu | boolean | true | The sync menu value. |
| splio.smartPass | object | {…} | Object containing smart pass fields. |
| splio.smartPass.urlPrefix | string | "https://smartpass.example.com" | The url prefix value. |
| splio.smartPass.organizationId | string | "org\_123" | Identifier of the associated organization. |
| splio.smartPass.projectId | string | "proj\_456" | Identifier of the associated project. |
| splio.smartPass.organizationSecret | string | "secret\_789" | The organization secret value. |
| formLink | string | "https://example.com/loyalty-form" | The form link value. |
| useCasualTone | boolean | true | The use casual tone value. |
| allowCustomerRewardUsage | boolean | true | The allow customer reward usage value. |
| authenticationMethods | object | {…} | Object containing authentication methods fields. |
| authenticationMethods.email | boolean | true | Email address. |
| authenticationMethods.phone | boolean | false | Phone number. |
| authenticationMethods.externalId | boolean | false | Identifier in the connected external system. |
| registerMethods | object | {…} | Object containing register methods fields. |
| registerMethods.email | boolean | true | Email address. |
| registerMethods.phone | boolean | false | Phone number. |
| features | array | \[…\] | List of features entries. |
| features\[\] | object | {…} | Object containing features fields. |
| features\[\].id | integer | 1 | The id value. |
| features\[\].isEnabled | boolean | true | Whether this feature is enabled. |

#### Response

```json
{
  "status": 200,
  "code": "module_loyalty_updated",
  "message": "A module loyalty has been updated.",
  "data": {
    "moduleLoyaltyProviderId": 42,
    "restaurantId": 1001,
    "provider": "splio",
    "apiKey": "sk_live_abc123def456",
    "programId": "program_abc123"
  }
}
```

##### 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 | "module\_loyalty\_updated" | Machine-readable application code for the result. |
| message | string | "A module loyalty has been updated." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.moduleLoyaltyProviderId | integer | 42 | Identifier of the associated module loyalty provider. |
| data.restaurantId | integer | 1001 | Identifier of the restaurant. |
| data.provider | string | "splio" | The provider value. |
| data.apiKey | string | "sk\_live\_abc123def456" | The api key value. |
| data.programId | string | "program\_abc123" | Identifier of the associated program. |

### `DELETE /v1/loyalty/restaurants/{restaurantId}/config` - Delete Restaurant Loyalty Config

Remove the loyalty provider configuration for a restaurant. This disconnects the restaurant from its loyalty provider. Requires Brand or Restaurant role.

#### Parameters

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

#### Response

```json
{
  "status": 200,
  "code": "module_loyalty_updated",
  "message": "A module loyalty has been updated."
}
```

##### 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 | "module\_loyalty\_updated" | Machine-readable application code for the result. |
| message | string | "A module loyalty has been updated." | Human-readable result message. Do not use this value for program logic. |

### `GET /v1/loyalty/restaurants/{restaurantId}/programs` - Get Loyalty Programs

Retrieve available loyalty programs for a restaurant from its configured provider. Requires Brand or Restaurant role.

#### Parameters

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

#### Response

```json
{
  "status": 200,
  "code": "module_loyalty_succeed",
  "message": "A module loyalty has been retrieved.",
  "data": [
    {
      "id": "program_abc123",
      "name": "Gold Rewards",
      "description": "Earn points on every purchase"
    },
    {
      "id": "program_def456",
      "name": "VIP Club",
      "description": "Exclusive member discounts"
    }
  ]
}
```

##### 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 | "module\_loyalty\_succeed" | Machine-readable application code for the result. |
| message | string | "A module loyalty has been retrieved." | 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 | "program\_abc123" | The id value. |
| data\[\].name | string | "Gold Rewards" | The name value. |
| data\[\].description | string | "Earn points on every purchase" | The description value. |

### OAuth Integration

OAuth-based authentication flow for connecting loyalty providers that require OAuth (e.g., Pongo). The flow involves redirecting the user to the provider, and handling the callback.

### `GET /v1/loyalty/brands/{brandId}/restaurants/{restaurantId}/oauth` - Get OAuth Redirect URL

Initiate the OAuth flow for a loyalty provider. Returns a 302 response with the redirect URL where the user should be sent to authorize the connection. Currently only supports the Pongo provider.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | The unique identifier of the brand. |
| restaurantId | integer | Yes | The unique identifier of the restaurant. |
| provider | string | Yes | The loyalty provider name. Currently only "pongo" is supported. |

#### Response

```json
{
  "redirectUrl": "https://pongo.io/oauth/authorize?client_id=abc&redirect_uri=..."
}
```

##### Response Properties

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

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| redirectUrl | string | "https://pongo.io/oauth/authorize?client\_id=abc&redirect\_uri=..." | The redirect url value. |

### `GET /v1/loyalty/providers/{provider}/oauth/redirect` - OAuth Callback

Callback endpoint for the OAuth flow. This is called by the loyalty provider after the user has authorized the connection. The state parameter is encrypted and contains the brand/restaurant context. Returns a 302 redirect to the backoffice.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| provider | string | Yes | The loyalty provider name (e.g., "pongo"). |
| code | string | Yes | The authorization code from the OAuth provider. |
| state | string | Yes | Encrypted state parameter containing the brand and restaurant context. |

#### Response

```json
HTTP 302 Found. The API returns a Location header that redirects the user agent to the backoffice URL supplied by the loyalty provider integration. There is no JSON response body.
```