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

POST /v14/orders

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