Orders .: Complete

API Reference / v15

Complete a Proposed Order

This endpoint allows you to complete a previously proposed order.

To complete a previously 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.

You must also have previously created an order in the proposed state and utilize the returned UUID from the proposed order. Before submitting the completed order, make sure you have taken the discount returned from the proposed order into account.

The only differences between the proposed order and the completed order should be:

  • Adjusted tax_amount (adjusted because of the discount)
  • Adjusted spend_amount (adjusted for the tax adjustment)
  • Included applied_discount_amount (the amount of discount applied to the check)
  • Included proposed_order_uuid (returned from the proposed order endpoint)

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/completed_orders

Authorization Required – Merchant Token in Header and User QR Code Data in Body

Authorization: token merchant="982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73"

Request Body

{
  "completed_order": {
    "applied_discount_amount": 0,
    "cashier": "Bob",
    "discount_only": false,
    "exemption_amount": 0,
    "identifier_from_merchant": "001001",
    "location_id": 19,
    "partial_authorization_allowed": true,
    "payment_token_data": "LU0200018SECH4O89A4NBOT7030000LU",
    "proposed_order_uuid": "53bffba02f5b013523b42adce3309561",
    "receipt_message_html": "Pick up your order at <strong>counter #4</strong>",
    "register": "3",
    "spend_amount": 1559,
    "tax_amount": 62,
    "tip_amount": 0,
    "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.
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 to tender with LevelUp including applied LevelUp discounts, fees, order taxes, and fee taxes (in cents). Do not include tip_amount if present.
applied_discount_
amount
Integer Yes LevelUp merchant-funded credit applied (returned from proposed orders endpoint).
discount_only Boolean No Apply only merchant funded discount to order, no payment. See details below.
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).
proposed_order_uuid String Yes The uuid returned from the proposed order call.
receipt_message_html String No Limited HTML (a, br, p, strong) to include on the user’s email receipt (1000 character limit).
tax_amount Integer Yes The amount of tax due on this transaction, including order taxes and taxes from fees. This value should reflect any applied merchant-funded discounts.
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.
tip_amount Integer No The amount to tip due to be tendered on this transaction.
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.

cURL Example

curl https://sandbox.thelevelup.com/v15/completed_orders \
  -H Accept:application/json \
  -H Content-Type:application/json \
  -H 'Authorization: token merchant=982-9a4218e4b6714b7b6b47890d0bf2f46544c99ff7a5957f72ef5637eaafdc73' \
  -d '{
        "completed_order": {
          "applied_discount_amount": 0,
          "cashier": "Bob",
          "discount_only": false,
          "exemption_amount": 0,
          "identifier_from_merchant": "001001",
          "location_id": 19,
          "partial_authorization_allowed": true,
          "payment_token_data": "LU0200018SECH4O89A4NBOT7030000LU",
          "proposed_order_uuid": "53bffba02f5b013523b42adce3309561",
          "receipt_message_html": "Pick up your order at <strong>counter #4</strong>",
          "register": "3",
          "spend_amount": 1559,
          "tax_amount": 62,
          "tip_amount": 0,
          "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

{
  "order": {
    "gift_card_total_amount": 0,
    "gift_card_tip_amount": 0,
    "spend_amount": 1559,
    "tip_amount": 0,
    "total_amount": 1559,
    "uuid": "5a1z9x2h31ah7g8a9i9h8g7f6e5d4c4a21o"
  }
}

Response Parameters

Parameters Type Description
gift_card_total_amount Integer Amount (in cents) to be applied to the check as merchant-funded gift card credit (including gift card tip).
gift_card_tip_amount Integer Amount (in cents) to be applied to the check as merchant-funded gift card tip.
spend_amount Integer Total amount (in cents) of non-tip approved (including LevelUp discount, tender and gift card).
tip_amount Integer Tip amount (in cents) to be applied to the check (including both gift card and non-gift card tip). This amount is in addition to the spend amount.
total_amount Integer Total amount tendered including discount, gift card, LevelUp tender and all gratuities.
uuid String UUID for the completed order. Note that this is not the same as the one for the proposed order.

Spend Amount and Partial Authorization

When creating an completed 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 but excluding any tip_amount (if present). 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 requests will always receive a 200 OK response but their approved spend_amount will be equal to any discount applied. Otherwise will return 0.

This endpoint also allows for a discount_only flag. When used in conjuction with the partial_authorization_allowed flag, this will only allow a user to apply available merchant funded discount credit to an order. The remainder of the check (if any) must be collected through alternative forms of payment. No merchant funded gift cards or third party credit will be applied, but progress will be accrued normally.

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