- Platform Overview
- Resources and Guides
-
POS Integration
-
Getting Started
-
Core Concepts
-
Integration SDK
-
Certification
-
- Order Ahead
-
Provider Enablement
-
Provider Enablement
-
Endpoints
-
Developer Endpoints
-
-
API Reference
-
Getting Started
-
v15
-
- Access Tokens
- Campaigns
- Credit Cards
- Users
- Credit
- Locations
- Payment Methods
- QR Codes
- Progress Adjustments
-
Orders
- Create Proposed Order
- Complete Order
- Refund
- List by App
- Interstitials
- Get Merchant Details
- Get User Details
- Create Feedback
- Rewards
- Gift Cards
-
-
v14
-
- Credit
- Access Tokens
- Campaigns
- Categories
- Credit Cards
- Interstitials
- Locations
- Loyalty
- Orders
- Payment Tokens
- Support Tickets
- Users
-
-
Proposed Orders .: Create
API Reference / v15
Create a Proposed Order and Retrieve Order Discount Amount
This endpoint allows you to create a proposed order for a location and retrieve the amount of credit to apply to this order. For a point of sale integration, typically only merchant-funded (pre-tax) credit is used as post-tax credit can just be applied via the tender amount.
To create a proposed order, you must have a merchant access token with the manage_merchant_orders
permission included in the Authorization header and the user’s QR code included in the body of the request as the payment_token_data
field.
Before submitting this request, make sure you are using the proper values, as calculated by the proposed orders calculator: C# / Java.
Request Endpoint
Authorization Required – Merchant Token in Header and User QR Code Data in Body
Authorization: token merchant="982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73"
Request Body
{
"proposed_order": {
"payment_token_data": "LU0200018SECH4O89A4NBOT7030000LU",
"cashier": "Bob",
"discount_only": false,
"exemption_amount": 0,
"receipt_message_html": null,
"register": "3",
"tax_amount": 62,
"tip_amount": 0,
"identifier_from_merchant": "001001",
"partial_authorization_allowed": true,
"location_id": 19,
"spend_amount": 1559,
"items": [
{
"item": {
"charged_price_amount": 299,
"description": "Shredded potatoes griddled to perfection",
"name": "Hashbrowns",
"quantity": 1,
"sku": "01abc192",
"category": "Breakfast Sides",
"standard_price_amount": 299,
"children": [
{
"item": {
"charged_price_amount": 0,
"name": "Special Instructions",
"description": "Scattered"
}
},
{
"item": {
"charged_price_amount": 50,
"name": "Onions",
"description": "Smothered"
}
},
{
"item": {
"charged_price_amount": 100,
"name": "Cheese",
"quantity": 2,
"description": "Covered"
}
},
{
"item": {
"charged_price_amount": 50,
"name": "Ham",
"description": "Chunked"
}
}
]
}
},
{
"item": {
"charged_price_amount": 398,
"description": "12oz Can of Coca-Cola",
"name": "Can Coke",
"quantity": 2,
"sku": "291soo01",
"category": "Drinks",
"standard_price_amount": 398,
"upc": "04963406"
}
}
],
"fees": [
{
"fee": {
"name": "Delivery Fees",
"type": "delivery",
"charged_price_amount": 100,
"tax_amount": 10,
"collector": "merchant"
}
},
{
"fee": {
"name": "Custom Fees",
"type": "custom",
"charged_price_amount": 500,
"tax_amount": 10,
"collector": "merchant"
}
}
]
}
}
Request Parameters
Parameters | Type | Required | Description |
---|---|---|---|
cashier |
String | No | The cashier who is logged into the POS terminal. |
discount_only |
Boolean | No | Apply only merchant funded discount to order, no payment. |
exemption_amount |
Integer | No | Total amount in cents of exempted items on the check. The exempted amount is ignored when we apply loyalty credit and calculate how much loyalty credit a user earns. This can be useful for products like tobacco and gift cards, where laws prohibit discounted sale. |
fees[] |
JSON Array | No | An array of fees incurred to the order. |
fee |
JSON Hash | Yes | Object representing a fee. |
fee[name] |
String | No | The name of the fee. |
fee[type] |
String | Yes | Must be one of: delivery , custom , catering . |
fee[charged_price_ amount]
|
Integer | Yes | The fee amount to be tendered (in cents). |
fee[tax_amount] |
Integer | No | The amount of tax associated with the fee due to be tendered (in cents). |
fee[collector] |
String | Yes | Always merchant . |
identifier_from_ merchant
|
String | No | The order ID or number for the check. Should be usable to find the check on the POS. Max 10 characters. |
items[] |
JSON Array | No | An array of items in the order. |
item |
JSON Hash | Yes | Object representing an order item. |
item[children] |
JSON Array | No | Array of sub-items. Usually modifiers or add-on items. |
item[charged_price_ amount]
|
Integer | Yes | The price for the item(s) that was charged to the customer (in cents). (Unit price * quantity - non-LevelUp discounts) |
item[description] |
String | Yes | The description of the item. |
item[name] |
String | Yes | The name of the item. |
item[quantity] |
Integer | Yes | The number of this item sold. Not required for child items. |
item[sku] |
String | No | SKU (Stock Keeping Unit) code of this item. |
item[category] |
String | No | Category of the item. |
item[standard_price_ amount]
|
Integer | No | Standard price for the item(s). (Unit price * quantity) |
item[upc] |
String | No | UPC (Universal Product Code) of the item. |
location_id |
Integer | Yes | LevelUp Location ID that is creating the proposed order. |
partial_ authorization_allowed
|
Boolean | No | Allow or reject partial authorization of orders. |
payment_token_data |
String | Yes | Customer QR code data (input from the LevelUp Scanner). |
receipt_message_html |
String | No | Limited HTML (a, br, p, strong) to include on the user’s email receipt (1000 character limit). |
register |
String | No | The register that placed the order. |
spend_amount |
Integer | Yes | Total amount to tender with LevelUp including fees, order taxes, and fee taxes (in cents). Do not include tip_amount if present. |
tax_amount |
Integer | Yes | The amount of tax due to be tendered on this transaction, including order taxes and taxes incurred to fees charged. |
tip_amount |
Integer | No | The amount to tip due to be tendered on this transaction. |
cURL Example
curl -X POST https://sandbox.thelevelup.com/v15/proposed_orders \
-H Accept:application/json \
-H Content-Type:application/json \
-H 'Authorization: token merchant=982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73' \
-d '{
"proposed_order": {
"payment_token_data": "LU0200018SECH4O89A4NBOT7030000LU",
"cashier": "Bob",
"discount_only": false,
"exemption_amount": 0,
"receipt_message_html": null,
"register": "3",
"tax_amount": 62,
"tip_amount": 0,
"identifier_from_merchant": "001001",
"partial_authorization_allowed": true,
"location_id": 19,
"spend_amount": 1559,
"items": [{
"item": {
"charged_price_amount": 299,
"description": "Shredded potatoes griddled to perfection",
"name": "Hashbrowns",
"quantity": 1,
"sku": "01abc192",
"category": "Breakfast Sides",
"standard_price_amount": 299,
"children": [{
"item": {
"charged_price_amount": 0,
"name": "Special Instructions",
"description": "Scattered"
}
}, {
"item": {
"charged_price_amount": 50,
"name": "Onions",
"description": "Smothered"
}
}, {
"item": {
"charged_price_amount": 100,
"name": "Cheese",
"quantity": 2,
"description": "Covered"
}
}, {
"item": {
"charged_price_amount": 50,
"name": "Ham",
"description": "Chunked"
}
}]
}
}, {
"item": {
"charged_price_amount": 398,
"description": "12oz Can of Coca-Cola",
"name": "Can Coke",
"quantity": 2,
"sku": "291soo01",
"category": "Drinks",
"standard_price_amount": 398,
"upc": "04963406"
}
}],
"fees": [
{
"fee": {
"name": "Delivery Fees",
"type": "delivery",
"charged_price_amount": 100,
"tax_amount": 10,
"collector": "merchant"
}
},
{
"fee": {
"name": "Custom Fees",
"type": "custom",
"charged_price_amount": 500,
"tax_amount": 10,
"collector": "merchant"
}
}
]
}
}'
Example Response
{
"proposed_order": {
"uuid": "1b3b3c4d5e6f7g8a9i9h8g7f6e5d4c3b2a1",
"rewards": [
{
"reward": {
"funding_source": "merchant",
"id": "campaign-237",
"redemptions": [
{
"redemption": {
"applied_pre_tax": true,
"applied_to_id": null,
"applied_to_type": "check",
"applied_amount": 400
}
}
]
}
},
{
"reward": {
"funding_source": "third_party",
"id": "campaign-49",
"redemptions": [
{
"redemption": {
"applied_pre_tax": false,
"applied_to_id": null,
"applied_to_type": "check",
"applied_amount": 100
}
}
]
}
}
],
"discount_amount": 400
}
}
Response Parameters
Parameters | Type | Description |
---|---|---|
discount_amount |
Integer | The amount (in cents) of merchant-funded credit to apply. |
rewards[] |
JSON Array | An array of rewards projected to be applied to the order upon order completion. |
reward |
JSON Hash | Object representing a reward. |
reward[funding_source] |
String | The entity that is funding the reward. Will be one of: grubhub , merchant , or third_party . |
reward[id] |
String | The id of the reward. |
reward[redemptions] |
JSON Array | An array of projected applications of a particular reward. |
redemption |
JSON Hash | Object representing a redemption. |
redemption[applied_pre_tax] |
Boolean | Apply the reward pre-tax. |
redemption[applied_to_id] |
String | The id of the entity the reward will apply to. |
redemption[applied_to_type] |
String | The entity the reward will apply to. Will be one of: check or fee . |
redemption[applied_amount] |
Integer | The amount (in cents) of funded credit to apply. |
uuid |
String | The uuid of the created proposed order. To be used in the subsequent order completion. |
Errors
HTTP/1.1 error 404 Not Found
- QR Code is invalid
HTTP/1.1 401 Unauthorized
- Not authorized to create orders for this user or location.
Details available in WWW-Authenticate response header.