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 merchant funded credit to apply to this order as discount.

To create a proposed 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 in the body of the request.

Before submitting this request, make sure you are using the proper values, as calculated by the proposed orders calculator: C# / Java.

Request Endpoint

POST /v15/proposed_orders

Authorization Required – Merchant and User Token in Header

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

OR

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",
    "exemption_amount": 0,
    "receipt_message_html": null,
    "register": "3",
    "tax_amount": 89,
    "identifier_from_merchant": "001001",
    "partial_authorization_allowed": true,
    "location_id": 19,
    "spend_amount": 986,
    "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.
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.
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). 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).
register String No The register that placed the order.
spend_amount Integer Yes Total amount to tender with LevelUp including tax. Typically the order balance due unless this is a split tender.
tax_amount Integer Yes The amount of tax due to be tendered on this transaction.

cURL Example using QR Code

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",
          "exemption_amount": 0,
          "receipt_message_html": null,
          "register": "3",
          "tax_amount": 89,
          "identifier_from_merchant": "001001",
          "partial_authorization_allowed": true,
          "location_id": 19,
          "spend_amount": 986,
          "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 User Token

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,user=123897-99SCvr3kSe3TqqQid3DyPXfo2Kq98MyhF6CaNPqoDeMhJ18Uopq19uddcznu6R' \
  -d '{
        "proposed_order": {
          "cashier": "Bob",
          "exemption_amount": 0,
          "receipt_message_html": null,
          "register": "3",
          "tax_amount": 89,
          "identifier_from_merchant": "001001",
          "partial_authorization_allowed": true,
          "location_id": 19,
          "spend_amount": 986,
          "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

{
  "proposed_order": {
    "discount_amount": 400,
    "uuid": "1b3b3c4d5e6f7g8a9i9h8g7f6e5d4c3b2a1"
  }
}

Response Parameters

Parameters Type Description
discount_amount Integer The amount (in cents) of merchant-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.