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.

Request Endpoint

POST /v15/proposed_orders

Authorization Required – Merchant and User Token in Header

Authorization: token merchant="982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73", user="1123-15d2aeedc9f4e0e7094a9d283868f8fbe873cb85ceaa0c511727245aec8c9e"

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": "LU02000008ZS9OJFUBNEL6ZM030000LU",
    "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": "LU02000008ZS9OJFUBNEL6ZM030000LU",
          "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=1123-15d2aeedc9f4e0e7094a9d283868f8fbe873cb85ceaa0c511727245aec8c9e' \
  -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.