Overview

The SpotOn Order API allows the injection of fully paid orders into the POS. There are two valid flows for injecting orders:

• Propose then Submit
• Submit without Propose

If your application is caching its own menu and performing its own cart calculation, you can Submit Order without making a Propose Order request. If you want to use SpotOn to calculate your cart taxes and discounts, and validate item availability and pricing against a menu, you can Propose then Submit.

Order Explainers

Line items

Line item price is base price of the line item – (not multiplied by quantity, not including modifier and subitem pricing)

Order State

• DRAFT^ – An unpaid order that is not visible in the POS. The order can be updated.
• OPEN^ – An unpaid order that is visible in the POS. The order can be updated.
• CLOSED – An order with a full payment. This order is in a terminal state and cannot be updated except to be Canceled
• CANCELED – An order that was canceled.

^ Currently only fully paid CLOSED orders can be handled by the /submit endpoint. Trying to /submit orders with a state of DRAFT or OPEN will result in an error.

Source

The Order Source Name string will appear on receipts, KDS, and as a filter attribute in sales reporting. It is important to use this field consistently and minimize changes for reporting continuity.

Customer

When a first_name, last_name, email, and phone are ALL provided, a new customer will be created in the merchant’s customer database. Alternatively you can provide an id for an existing customer. Providing an ID for an existing customer will use their currently stored name, email, and phone.

Fulfillment

Type

An Order must be one of three fulfillment types: Dine-in, Pickup, or Delivery. This affects its printer/KDS routing and lead time estimation.

Schedule and Lead Times

An order has one of two schedule types: ASAP or SCHEDULED.

When placing an ASAP order, the estimated_ready_at time will be populated in the response to let you know when the order should be ready. If it is a DELIVERY order, additional the estimated_delivery_at will be populated in the response as well.

When placing a SCHEDULED order, you must provide the estimated_ready_at time in the request, OR in the case of DELIVERY orders, provide an estimated_delivery_at time. If the restaurant's prep and lead times allow for the scheduled order, the response will accept your requested times. However, if you try and request a scheduled order sooner than it can be fulfilled, the order will not fail. Instead, the order will be converted to an ASAP order and the estimated_ready_at (and if applicable the estimated_delivery_at) time will be overridden and provided in the response. If the new times do not suit the customer it is up to the API consumer to CANCEL the order.

Status

Currently when orders are submitted to the API, if they are valid the fulfillment will automatically move to ACCEPTED. An ACCEPTED order can then be CANCELED either by the merchant on the POS, or by the API consumer who submitted the order. These are currently the only two statuses for an order, but SpotOn is working on features that will make use of the other statuses via POS, KDS, and Courier triggered updates.

Payment

Currently the Orders API only accepts fully paid orders. It is required that you attach a payment to the order that matches the total.

If a payment is being processed outside of SpotOn, you can use the EXTERNAL payment type. When using this type you can provide a provider_name which will be used for the name of the custom tender and in a merchants reporting.

If you are processing credit cards on SpotOn payment rails, you can use the PAYMENT_CARD payment type. This type requires that you submit a card transaction id received from our payments API (currently private).

Menu_id

Currently it is required that you provide a source menu_id for all orders for reporting purposes.

Propose Orders

Order Proposal serves two purposes: to calculate taxes and discounts, and to validate an order against a menu. Order proposal is currently a strict validation, which means that it will validate pricing, availability, and taxes against the menu_id provided. Order proposal will return a signature for partners that require signed carts to submit an order.^

^Most partners will not require signed carts.

Submit Orders

Submit order will accept any item price overrides and tax total. One important note is that while SpotOn accepts any externally provided tax_total to allow for rounding differences and third party marketplace discrepancies, we will still perform internal tax calculations to allocate taxes for reporting purposes. In other words SpotOn accepts externally provided totals but not externally provided calculation and allocation.