Orders .: Create

API Reference / v15

*** THIS ENDPOINT HAS BEEN DEPRECATED - USE CREATE PROPOSED ORDER INSTEAD ***

Place an Order

This endpoint allows you to create orders. Once you have permission to charge orders, you’ll receive the appropriate access token you can use to charge the customer’s account.

To create an order, you must have a user access token with the create_orders permission and a merchant access token with the manage_merchant_orders permission.

As an alternative to using a user access token to authorize the user, you can include the user’s QR code as the user token in the request header.

Request Endpoint

POST /v15/orders

Authorization Required – Merchant and User Token in Header

Authorization: token merchant="982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73", user="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"

OR

Authorization Required – Merchant and User QR Code Data in Body

Authorization: token merchant="982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73"

Request Body

{
  "order": {
    "identifier_from_merchant": "001001",
    "location_id": 19,
    "spend_amount": 997,
    "cashier": "Andrew Jones",
    "register": "03",
    "applied_discount_amount": null,
    "available_gift_card_amount": null,
    "exemption_amount": null,
    "partial_authorization_allowed": false,
    "payment_token_data": "LU0200018SECH4O89A4NBOT7030000LU",
    "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
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 of the order, including applied LevelUp discounts and tax (in cents - ie $1.00 = 100).
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.
payment_token_data String Yes Customer QR code data (input from the LevelUp Scanner). Only required if user token is not passed in the Authorization header.
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 using User Permissions Token

curl https://sandbox.thelevelup.com/v15/orders \
  -H Accept:application/json \
  -H Content-Type:application/json \
  -H 'Authorization: token merchant="982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73",  user="123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R"' \
  -d '{
        "order": {
            "identifier_from_merchant": "001001",
            "location_id": 19,
            "spend_amount": 997,
            "applied_discount_amount": null,
            "available_gift_card_amount": null,
            "exemption_amount": null,
            "cashier": "Andrew Jones",
            "register": "03",
            "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"
                }
            }]
        }
      }'

cURL Example using QR Code as User Token

curl https://sandbox.thelevelup.com/v15/orders \
  -H Accept:application/json \
  -H Content-Type:application/json \
  -H 'Authorization: token merchant="982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73"' \
  -d '{
        "order": {
            "identifier_from_merchant": "001001",
            "location_id": 19,
            "spend_amount": 997,
            "applied_discount_amount": null,
            "available_gift_card_amount": null,
            "exemption_amount": null,
            "cashier": "Andrew Jones",
            "register": "03",
            "payment_token_data": "LU0200018SECH4O89A4NBOT7030000LU",
            "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"
                }
            }]
        }
      }'

Example Response

{
  "order": {
    "uuid": "1a2b3c4d5e6f7g8h9i9h8g7f6e5d4c3b2a1",
    "spend_amount": 10,
    "tip_amount": 0,
    "total_amount": 10
  }
}

Response Parameters

Parameters Type Description
order JSON Array Successfully created order object.
uuid String UUID for the order.
spend_amount Integer Amount requested for payment (in cents).
tip_amount Integer Tip amount (in cents).
total_amount Integer Total amount 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 (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 reqests will always receieve a 200 OK response but their approved spend_amount will always be 0.

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."
    }
  }
]