- 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
- Rewards
- Gift Cards
-
-
v14
-
- Credit
- Access Tokens
- Campaigns
- Categories
- Credit Cards
- Interstitials
- Locations
- Loyalty
- Orders
- Payment Tokens
- Support Tickets
- Users
-
-
Orders .: Create
API Reference / v14
Create an Order
This endpoint creates a new order.
NOTE: Tip information is included as part of the customer’s QR code so the full payment amount will not be known until the response from LevelUp is received.
Request Endpoint
Authorization Required – Merchant Token in Header
Authorization: token 123456-75489120749...
Request Body
{
"order": {
"identifier_from_merchant": "001001",
"location_id": 1234,
"payment_token_data": "LU02111222333444555666777888999LU",
"spend_amount": 997,
"cashier": "Andrew Jones",
"register": "03",
"applied_discount_amount": null,
"available_gift_card_amount": null,
"exemption_amount": null,
"partial_authorization_allowed": false,
"receipt_message_html": "Pick up your order at <strong>counter #4</strong>",
"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"
}
}
]
}
}
Request Parameters
Parameters | Type | Required | Description |
---|---|---|---|
token |
String | Yes | Authorization token (access_token ) for the merchant. |
identifier_from_ merchant
|
String | No | The POS-specific order ID or number for the check. Should be usable to find the check on the POS. Max 10 characters. |
location_id |
Integer | Yes | LevelUp Location ID that is placing the order. |
payment_token_data |
String | Yes | Customer QR code data (input from the LevelUp Scanner). |
spend_amount |
Integer | Yes | Total amount of the order, including applied LevelUp discounts and tax (in cents - ie $1.00 = 100). |
cashier |
String | No | Cashier name or identifier. |
register |
String | No | Register name or identifier. |
applied_discount_ amount
|
Integer | No | LevelUp merchant-funded credit applied (calculated from value retrieved from merchant funded credit endpoint). Should be null if merchant-funded credit endpoint is not being used. If set to 0, will override any available discounts. |
available_gift_card_ amount
|
Integer | No | LevelUp gift card credit available (calculated from value retrieved from merchant funded credit endpoint). Should be null if merchant-funded credit endpoint is not being used. |
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. |
partial_ authorization_allowed
|
Boolean | No | Allow or reject partial authorization of orders. See details below. |
receipt_message_html |
String | No | Limited HTML (a, br, p, strong) to include on the user’s email receipt (1000 character limit). |
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. |
cURL Example
curl -X POST -H Accept: application/json -H Content-Type: application/json -H 'Authorization: token 123456-75489120749...' -d '{"order": {"identifier_from_merchant": "001001", "location_id": 1234, "payment_token_data": "LU02111222333444555666777888999LU", "spend_amount": 997, "cashier": "Andrew Jones", "register": "03", "exemption_amount": null, "receipt_message_html": "Pick up your order at <strong>counter #4</strong>", "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"}}]}}' https://api.thelevelup.com/v14/orders
Example Response Body
{
"order": {
"uuid": "1a2b3c4d5e6f7g8h9i9h8g7f6e5d4c3b2a1",
"spend_amount": 997,
"tip_amount": 0,
"total_amount": 997
}
}
Response Parameters
Parameters | Type | Description |
---|---|---|
order |
JSON Hash | Successfully created order object. |
uuid |
String | UUID for the order. |
spend_amount |
Integer | Amount approved for payment (in cents). |
tip_amount |
Integer | Tip amount (in cents). |
total_amount |
Integer | Total amount approved including tip (in cents) |
Spend Amount and Partial Authorization
When creating an order request, the spend_amount
param should include the entire amount the
customer is attempting to tender to LevelUp, inclusive of all discounts and taxes. For example,
if a customer’s check is $10 and the customer has a $2 LevelUp discount, the requested
spend_amount
would be 1000 ($10 in cents). If the customer has a $2 LevelUp discount and a $5
merchant coupon (non-LevelUp), the spend_amount
requested would be 500 ($3 due after application
of $5 merchant coupon + $2 LevelUp discount applied = $5 paid through LevelUp -> 500 cents =
spend_amount
).
If tax is included in the example:
$10 Subtotal $1 Tax $11 Grand Total
(apply $5 LevelUp discount (forgives tax))
$10 Subtotal $5 LevelUp Discount $.5 Adjusted Tax $5.50 Amount Due
The spend_amount
sent to LevelUp for the above example would be 1050. This is equated by taking
the amount (in cents) Due (550) and adding the discount amount (500) for a total of 1050.
This endpoint allows for a partial_authorization_allowed
flag. This flag will allow a user to
transact for exactly the amount of their available credit (in the case of gift card) or their
preloaded account balance even if they request authorization for an amount greater than their
available credit. If partial authorization is disabled (set to false or omitted), orders exceeding
available balance will be rejected with an error. For example, if a user only has $5 in gift card
credit (and no backup funding source) and attempts to pay for $10 worth of goods (requested
spend_amount
= 1000), the LevelUp API will respond with a 200 OK and a spend_amount
of 500. The
customer should then be prompted to settle the remainder with another tender type.
The partial_authorization_allowed
flag also enables merchants to offer “2 touch loyalty” to their
customers. Essentially customers are allowed to use LevelUp for loyalty only, and are not required
to link a payment method. These customer’s order reqests will always receive a 200 OK response and
their approved spend_amount
will be equal to any discount applied. Otherwise will return 0.
Errors
HTTP/1.1 error 422 Unprocessable Entity
- QR code was not recognized
[
{
"error": {
"message": "We couldn't recognize that as a valid LevelUp Code. Perhaps scan again?",
"object": "order",
"property": "base"
}
}
]
HTTP/1.1 error 422 Unprocessable Entity
- The customer’s card could not be charged
[
{
"error": {
"message": "Sorry. We cannot charge the credit card at this time.",
"object": "order",
"property": "base"
}
}
]
HTTP/1.1 error 422 Unprocessable Entity
- Invalid payment token
[
{
"error": {
"object": "order",
"property": "payment_token_data",
"code": "invalid",
"message": "Payment token is invalid."
}
}
]
HTTP/1.1 error 422 Unprocessable Entity
- Location not found or not configured correctly
[
{
"error": {
"object": "order",
"property": "location_id",
"code": "not_found",
"message": "Location can't be blank"
}
}
]