- 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 .: Complete
API Reference / v15
Complete a Proposed Order
This endpoint allows you to complete a previously proposed order.
To complete a previously 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.
You must also have previously created an order in the proposed state and utilize the returned UUID from the proposed order. Before submitting the completed order, make sure you have taken the discount returned from the proposed order into account.
The only differences between the proposed order and the completed order should be:
- Adjusted
tax_amount
(adjusted because of the discount) - Adjusted
spend_amount
(adjusted for the tax adjustment) - Included
applied_discount_amount
(the amount of discount applied to the check) - Included
proposed_order_uuid
(returned from the proposed order endpoint)
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
{
"completed_order": {
"applied_discount_amount": 0,
"cashier": "Bob",
"discount_only": false,
"exemption_amount": 0,
"identifier_from_merchant": "001001",
"location_id": 19,
"partial_authorization_allowed": true,
"payment_token_data": "LU0200018SECH4O89A4NBOT7030000LU",
"proposed_order_uuid": "53bffba02f5b013523b42adce3309561",
"receipt_message_html": "Pick up your order at <strong>counter #4</strong>",
"register": "3",
"spend_amount": 1559,
"tax_amount": 62,
"tip_amount": 0,
"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. |
register |
String | No | The register that placed the order. |
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. |
location_id |
Integer | Yes | LevelUp Location ID that is placing the order. |
spend_amount |
Integer | Yes | Total amount to tender with LevelUp including applied LevelUp discounts, fees, order taxes, and fee taxes (in cents). Do not include tip_amount if present. |
applied_discount_ amount
|
Integer | Yes | LevelUp merchant-funded credit applied (returned from proposed orders endpoint). |
discount_only |
Boolean | No | Apply only merchant funded discount to order, no payment. See details below. |
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. |
payment_token_data |
String | Yes | Customer QR code data (input from the LevelUp scanner). |
proposed_order_uuid |
String | Yes | The uuid returned from the proposed order call. |
receipt_message_html |
String | No | Limited HTML (a, br, p, strong) to include on the user’s email receipt (1000 character limit). |
tax_amount |
Integer | Yes | The amount of tax due on this transaction, including order taxes and taxes from fees. This value should reflect any applied merchant-funded discounts. |
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. |
tip_amount |
Integer | No | The amount to tip due to be tendered on this transaction. |
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 . |
cURL Example
curl https://sandbox.thelevelup.com/v15/completed_orders \
-H Accept:application/json \
-H Content-Type:application/json \
-H 'Authorization: token merchant=982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73' \
-d '{
"completed_order": {
"applied_discount_amount": 0,
"cashier": "Bob",
"discount_only": false,
"exemption_amount": 0,
"identifier_from_merchant": "001001",
"location_id": 19,
"partial_authorization_allowed": true,
"payment_token_data": "LU0200018SECH4O89A4NBOT7030000LU",
"proposed_order_uuid": "53bffba02f5b013523b42adce3309561",
"receipt_message_html": "Pick up your order at <strong>counter #4</strong>",
"register": "3",
"spend_amount": 1559,
"tax_amount": 62,
"tip_amount": 0,
"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
{
"order": {
"gift_card_total_amount": 0,
"gift_card_tip_amount": 0,
"spend_amount": 1559,
"tip_amount": 0,
"total_amount": 1559,
"uuid": "5a1z9x2h31ah7g8a9i9h8g7f6e5d4c4a21o"
}
}
Response Parameters
Parameters | Type | Description |
---|---|---|
gift_card_total_amount |
Integer | Amount (in cents) to be applied to the check as merchant-funded gift card credit (including gift card tip). |
gift_card_tip_amount |
Integer | Amount (in cents) to be applied to the check as merchant-funded gift card tip. |
spend_amount |
Integer | Total amount (in cents) of non-tip approved (including LevelUp discount, tender and gift card). |
tip_amount |
Integer | Tip amount (in cents) to be applied to the check (including both gift card and non-gift card tip). This amount is in addition to the spend amount. |
total_amount |
Integer | Total amount tendered including discount, gift card, LevelUp tender and all gratuities. |
uuid |
String | UUID for the completed order. Note that this is not the same as the one for the proposed order. |
Spend Amount and Partial Authorization
When creating an completed 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 but excluding
any tip_amount
(if present). 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 (in cents) 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 requests will always receive a 200 OK response but
their approved spend_amount
will be equal to any discount applied. Otherwise will return 0.
This endpoint also allows for a discount_only
flag. When used in conjuction with the
partial_authorization_allowed
flag, this will only allow a user to apply available merchant funded
discount credit to an order. The remainder of the check (if any) must be collected through
alternative forms of payment. No merchant funded gift cards or third party credit will be applied,
but progress will be accrued normally.
Errors
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
- Location not found or not configured correctly
[
{
"error": {
"object": "order",
"property": "location_id",
"code": "not_found",
"message": "Location can't be blank"
}
}
]
HTTP/1.1 401 Unauthorized
- Not authorized to create orders for this user.
[
{
"error": {
"object": "order",
"property": "user_token",
"code": "not_authorized",
"message": "Not authorized to create orders for this user."
}
}
]
HTTP/1.1 401 Unauthorized
- Not authorized to create orders for this merchant.
[
{
"error": {
"object": "order",
"property": "merchant_token",
"code": "not_authorized",
"message": "Not authorized to create orders for this merchant."
}
}
]