External Discounts
For brands that use loyalty providers that are not integrated with PAR Ordering, our APIs allow for their discounts to be applied to a cart via secure machine-to-machine communication.
Authentication
In order to ensure that externally calculated discounts are valid and have not been tampered with on the frontend, we require a machine-to-machine authentication token using a client_id and client_secret credentials, which are then used to generate access tokens.
Generate Access Token
To establish a secure connection, client applications will generate access tokens, using the client_id and client_secret credentials. These access tokens serve as the authentication mechanism, guaranteeing that only authorized client applications can interact with the API.
By calling the /api/oauth/tokens the access token can be generated and later be used as the Bearer token for setting up external discounts to PAR Ordering.
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Application |
Header Application Key | "f3a90488ffee32c3acb6fcd0ca417cf6" | Specific Management Center application key provided by PAR Ordering |
Authorization |
Header | "Basic 32c3acb6fcd0ca417cf6f3a90488ffee" | Basic Authorization header is based on the previously received client_id and client_secret and is generated as follows : base_64_encode(client_id:client_secret) |
scope |
string | "order" |
Token access scope |
{
"method": "post",
"url": "https://api-public-playground.menu.app/api/oauth/tokens",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Authorization": "Basic 32c3acb6fcd0ca417cf6f3a90488ffee",
"Content-Type": "application/x-www-form-urlencoded",
"Api-Version": 4.44.0,
"X-Role-ID": ""
},
"body":{
"grant_type": "client_credentials",
"scope": "order"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"oauth_token": {
"access_token": "d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291",
"token_type": "bearer",
"scope": "order",
"expires_in": 86399
}
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
oauth_token.access_token |
string | "f3a90488ffee32c3acb6fcd0ca417cf6" |
Access token for the future creation and editing of the webhooks configurations. This token should be used as Bearer token in the next calls. |
oauth_token.expires_in |
int | "86399" | Token expiration time in seconds |
oauth_token.scope |
string | "order" |
Token access scope |
External Discounts - Calculate method
The amount of money that will be discounted from the order subtotal is sent in the order /api/orders/calculate method specifying that the discount origin is external:
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
X-API-Authorization |
Header | "Bearer 0ca417cf6f3a90488ffee32c3acb6fcd" |
Bearer token, should be the access_token received in the /api/oauth/tokens call |
singular_point_id |
string | "db2f3288-63f4-4939-81f6-d0351bce9c7"0 |
Singular Point ID from /venues/{venue_uuid} call |
order_type.id |
id | 6 |
Type ID of order type for which order should be placed - see Order Types reference |
menu_items |
array[MenuItem] | Array of Menu Items that are included in the cart | |
menu_items.id |
string | "833c2e35-5066-4b1c-a813-fe5cb349a6aa"", |
Menu Item UUID |
menu_items.quantity |
int | 1 |
Number of the same Menu Items with same price level and modifiers that are in cart |
menu_items.price_level_id |
string | "76efaa5d-b849-4549-9468-72b8131b904a"", |
UUID of Price Level of Menu Item that customer chose |
discounts.discount_amount |
int | 500 |
The amount of money to be deducted from the subtotal in cents. |
discounts.origin |
string | "non-integrated" |
The origin of the discount - non integrated loyalty provider |
calculate_accurate_tax |
bool | false |
Defines whether external tax engine (such as POS system) should be used to calculate accurate taxes, or whether a prediction should be returned - should be set to true when proceeding to checkout and be false while the customer is still composing their cart. |
{
"method": "post",
"url": "https://api-public-playground.menu.app/api/orders/calculate",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": 4.38.0,
"Content-Type": "application/json",
"X-API-Authorization": "Bearer 32c3acb6fcd0ca417cf6f3a90488ffee"
},
"body": {
"singular_point_id": "db2f3288-63f4-4939-81f6-d0351bce9c70",
"order_type": {
"id": 6
},
"menu_items": [
{
"id": "833c2e35-5066-4b1c-a813-fe5cb349a6aa",
"quantity": 1,
"price_level_id": "76efaa5d-b849-4549-9468-72b8131b904a"
}
],
"discounts": [
{
"discount_amount": 500,
"origin_type": "non_integrated"
}
],
"calculate_accurate_tax": false
}
}
See the Placing order article for more details on the Calculate API.
Creating Order
Once payment initialization is called with the updated total cost, you can proceed with posting the order to /orders:
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
X-API-Authorization |
Header | "32c3acb6fcd0ca417cf6f3a90488ffee" | "Bearer 0ca417cf6f3a90488ffee32c3acb6fcd" |
discounts.discount_amount |
int | 500 |
The amount of money to be deducted from the subtotal in cents. |
discounts.origin |
string | "non-integrated" |
The origin of the discount - non integrated loyalty provider |
{
"method": "post",
"url": "https://api-public-playground.menu.app/api/orders",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": 4.38.0,
"Content-Type": "application/json",
"X-API-Authorization": "Bearer 32c3acb6fcd0ca417cf6f3a90488ffee"
},
"body": {
"singular_point_id": "db2f3288-63f4-4939-81f6-d0351bce9c70",
"order_type": {
"id": 6,
"pickup_asap": true,
"pickup_at": "2023-08-06 23:20:00"
},
"menu_items": [
{
"id": "833c2e35-5066-4b1c-a813-fe5cb349a6aa",
"quantity": 2,
"price_level_id": "76efaa5d-b849-4549-9468-72b8131b904a"
}
],
"discounts": [
{
"discount_amount": 500,
"origin_type": "non_integrated"
}
],
"customer_info": {
"email": "jane.doe@partech.com",
"first_name": "Jane",
"last_name": "Doe",
"phone_number": "+112345566"
},
"payment_info": {
"payment_init_hash": "6d930b1593304c87f1092001ceb29ae2"
}
}
}
See the Placing order article for more details on the Create Order API.
The taxes are calculated on the PAR Ordering and POS side. When the discount is applied, the discount amount is discounted proportionally from all the menu items and combos, as the taxes are different for different product types.