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 credit to apply to this order. For a point of sale integration, typically only merchant-funded (pre-tax) credit is used as post-tax credit can just be applied via the tender amount.

To create a 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.

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 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",
    "discount_only": false,
    "exemption_amount": 0,
    "receipt_message_html": null,
    "register": "3",
    "tax_amount": 62,
    "tip_amount": 0,
    "identifier_from_merchant": "001001",
    "partial_authorization_allowed": true,
    "location_id": 19,
    "spend_amount": 1559,
    "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.
discount_only Boolean No Apply only merchant funded discount to order, no payment.
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.
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.
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).
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 fees, order taxes, and fee taxes (in cents). Do not include tip_amount if present.
tax_amount Integer Yes The amount of tax due to be tendered on this transaction, including order taxes and taxes incurred to fees charged.
tip_amount Integer No The amount to tip due to be tendered on this transaction.

cURL Example

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",
          "discount_only": false,
          "exemption_amount": 0,
          "receipt_message_html": null,
          "register": "3",
          "tax_amount": 62,
          "tip_amount": 0,
          "identifier_from_merchant": "001001",
          "partial_authorization_allowed": true,
          "location_id": 19,
          "spend_amount": 1559,
          "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

{
  "proposed_order": {
    "uuid": "1b3b3c4d5e6f7g8a9i9h8g7f6e5d4c3b2a1",
    "rewards": [
      {
        "reward": {
          "funding_source": "merchant",
          "id": "campaign-237",
          "redemptions": [
            {
              "redemption": {
                "applied_pre_tax": true,
                "applied_to_id": null,
                "applied_to_type": "check",
                "applied_amount": 400
              }
            }
          ]
        }
      },
      {
        "reward": {
          "funding_source": "third_party",
          "id": "campaign-49",
          "redemptions": [
            {
              "redemption": {
                "applied_pre_tax": false,
                "applied_to_id": null,
                "applied_to_type": "check",
                "applied_amount": 100
              }
            }
          ]
        }
      }
    ],
    "discount_amount": 400
  }
}

Response Parameters

Parameters Type Description
discount_amount Integer The amount (in cents) of merchant-funded credit to apply.
rewards[] JSON Array An array of rewards projected to be applied to the order upon order completion.
reward JSON Hash Object representing a reward.
reward[funding_source] String The entity that is funding the reward. Will be one of: grubhub, merchant, or third_party.
reward[id] String The id of the reward.
reward[redemptions] JSON Array An array of projected applications of a particular reward.
redemption JSON Hash Object representing a redemption.
redemption[applied_pre_tax] Boolean Apply the reward pre-tax.
redemption[applied_to_id] String The id of the entity the reward will apply to.
redemption[applied_to_type] String The entity the reward will apply to. Will be one of: check or fee.
redemption[applied_amount] Integer The amount (in cents) of 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.