Skip to main content

Operation Definitions

Endpoints

POST /order

Summary

Use the Create Order operation to create a new order. Users can create an empty order, or they can add products to the order at the same time as creating a new order. The Create Order method returns an Order Object.

Request Parameters

In

Field Name

Type

Required

Description

header

CONTENT-TYPE

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

body

body

CreateOrderRequestBody

Yes

Add the Create Order request body.

Sample Request Body

{
    "destination": {
        "id": "carry-out",
        "name": "Carry Out"
    },
    "order_source_id": "Kiosk",
    "owner": {
        "id": "1111111",
        "name": "John Smith",
        "title": "employee"
    },
    "customer": {
        "id": "123456",
        "first_name": "Jane",
        "last_name": "Smith",
        "phone_cell": "7045553333",
        "email": "jane.smith@somedomain.com"
    },
    "items": [
        {
            "product_id": "3030",
            "name": "Deluxe Cheeseburger",
            "quantity": 2,
            "child_items": [
                {
                    "product_id": "810070_extra",
                    "name": "Extra Pickles",
                    "quantity": 1
                }
            ]
        },
        {
            "product_id": "3010M",
            "name": "MD Coke",
            "quantity": 1
        },
        {
            "donation_id": "RC",
            "quantity": 1,
            "unit_price": 10.75
        },
        {
            "entity_id": "5f2da8ab2ad9d51e0abf7d7a",
            "quantity": 1
        }
    ],
    "terminal": {
        "id": "1",
        "title": "Kiosk 1",
        "terminal_number": "22"
    }
}

Responses

Code

Description

Schema

200

Order successfully created

OrderObject

400

Error creating order

GeneralErrorStructure

PUT /order/{_id}/item

Summary

An order must include items before it can be processed. Use the Add Items operation to add items to an order or update the items already associated with the order.

When items are added to an order, the associated prices are used to automatically calculate the subtotal, tax amount, and total amount to be paid for the order.

The Add Items method returns an Order Object that includes an array of item objects and the subtotals, taxes, and total order amount.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

itemObject

Yes

Adds items to the order request body (individual item structure).

Responses

Code

Description

Schema

200

Item successfully added

OrderObject

400

Error adding item to order

GeneralErrorStructure

PUT /order/{_id}/checkin

Summary

The Check In operation sends the order to the store to be prepared and delivered. Orders that have been checked in cannot be altered.

The Check In operation returns an Order Object with the state property set to checkedin.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

AddDestinationRequestBody

No

Add a destination to the request body

Responses

Code

Description

Schema

200

Order successfully checked in

OrderObject

400

Error checking in order

GeneralErrorStructure

PUT /order/{_id}/commit

Summary

Use the Commit operation to confirm that the order is complete and ready to be processed. Committed orders can still be amended. However, users must update payment details if they change a committed order.

The Commit operation returns an Order Object with the state property set to committed.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

AddDestinationRequestBody

No

Add a destination to the request body

Responses

Code

Description

Schema

200

Successfully committed the order

OrderObject

400

Error committing order

GeneralErrorStructure

PUT /order/{_id}/customer

Summary

An order must have a customer associated with it before it can be processed. The Add Customer operation adds a customer to an order or updates customer information already associated with the order. The customer object, attached to the order, is where users can set a pickup date and time for the order. The Add Customer operation returns an Order Object that includes the customer information.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

AddCustomerRequestBody

Yes

Add a customer to the order request body

Responses

Code

Description

Schema

200

Successfully added customer to order

OrderObject

400

Error adding customer to order

GeneralErrorStructure

PUT /order/{_id}/discount

Summary

Use the Create Order operation to create a new discount order.

Request Parameters

In

Field Name

Type

Required

Description

header

CONTENT-TYPE

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

AddOrderDiscountsRequestBody

Yes

Add the Add Order Discounts request body

Responses

Code

Description

Schema

200

Order successfully created

OrderObject

400

Error creating order

GeneralErrorStructure

PUT /order/{_id}/item/update

Summary

Update an order item.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

UpdateOrderItemRequestBody

Yes

Update the order item request body

Responses

Code

Description

Schema

200

Successfully updated order item

OrderObject

400

Error updating order item

GeneralErrorStructure

PUT /order/{_id}/item/{parent_item_id}/child

Summary

Add a child item.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

path

parent_item_id

string

Yes

The order_item_id of the parent item

body

body

AddChildItemsRequestBody

No

Add child items body

Responses

Code

Description

Schema

200

Child item successfully added

OrderObject

400

Error adding child item to order

GeneralErrorStructure

PUT /order/{_id}/payment

Summary

Use the Add Payment operation to define how a customer paid for an order.

It is possible to use multiple payment methods to pay for an order. When the total amount of the order has been allocated to payment methods, the value of the payment_status parameter switches from open to paid.

The Add Payment operation returns an Order Object with the payment methods included. The operation automatically calculates and updates the payment status and change due.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

AddPaymentRequestBody

Yes

Add the Payment request body

Responses

Code

Description

Schema

200

Successfully added payment to order

OrderObject

400

Error adding payment to order

GeneralErrorStructure

PUT /order/{_id}/total

Summary

Use this endpoint to get calculated values from the API without creating the order. It allows the user to get tax or discount amounts when creating the entire order at once or requesting a price check.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

Responses

Code

Description

Schema

200

Successfully totaled order

OrderObject

400

Error totaling order

GeneralErrorStructure

PUT /order/{_id}/update

Summary

Update the order.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

UpdateOrderRequestBody

Yes

Optional fields to update in the order

Responses

Code

Description

Schema

200

Successfully updated the order

OrderObject

400

Error updating order

GeneralErrorStructure

PUT /order/{{_id}}/fee

Summary

Add fee to the order request body.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

FeeRequestBody

Yes

Add fee to the order request body

Responses

Code

Description

Schema

200

Successfully added fee to order

OrderObject

400

Error adding fee to order

GeneralErrorStructure

DELETE /order/{_id}/discount

Summary

Remove the discount from the order.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

DeleteDiscountRequestBody

Yes

Removes the Discount request body

Responses

Code

Description

Schema

200

Successfully removed discount from order

OrderObject

400

Error deleting discount from order

GeneralErrorStructure

DELETE /order/{_id}

Summary

Remove the order.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

X-Order-Target

string

No

The order target

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

Responses

Code

Description

Schema

200

Order successfully removed

OrderObject

400

Error removing order

GeneralErrorStructure

DELETE /order/{_id}/customer

Summary

Remove the customer from the order.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

Responses

Code

Description

Schema

200

Successfully removed customer from order

OrderObject

400

Error removing customer from order

GeneralErrorStructure

DELETE /order/{_id}/item

Summary

Remove the item.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

DeleteItemsRequestBody

Yes

Delete the child items body

Responses

Code

Description

Schema

200

Item successfully removed

OrderObject

400

Error removing item from order

GeneralErrorStructure

DELETE /order/{_id}/payment

Summary

Remove the payment from the order.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

body

body

DeletePaymentRequestBody

Yes

Add the Delete Payment request body

Responses

Code

Description

Schema

200

Successfully removed payment from order

OrderObject

400

Error removing payment from order

GeneralErrorStructure

GET /info

Summary

Get the component information.

Request Parameters

No parameters

Responses

Code

Description

Schema

200

Returns component information

ComponentInfo

GET /order

Summary

Get the orders.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

query

$filter

string

No

Odata filter parameter.

Example of usage: filtering by customer: customer/id eq 'customer_id',filtering by state: state eq 'committed',filtering by terminal.id: creator/terminal/id eq '9',filtering by date range: time/created gt '2017-06-22T12:15:34Z' and time/created lt '2017-06-28T12:15:35Z'combined filtering: creator/terminal/id eq '9' and time/created gt '2017-06-22T12:15:34Z' and time/created lt '2017-06-28T12:15:35Z'

query

$top

number

No

The number of items to be returned

query

$orderby

string

No

The Odata sorting parameter.

Example of sorting by time.created in descending order: time/created desc

query

$skip

number

No

The number of items to be skipped

query

$select

string

No

The fields to be returned

Responses

Code

Description

Schema

200

Returns a list of found orders

OrderObject

400

Error getting order

GeneralErrorStructure

GET /order/{_id}

Summary

Get the order by the identifier.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

path

_id

string

Yes

The unique identifier (UID) relating to the order

Responses

Code

Description

Schema

200

Order successfully returned

OrderObject

404

Error getting order

GeneralErrorStructure

GET /site/status

Summary

The Site Status operation allows users to retrieve the latest status updates for a company's sites, primarily to determine whether or not a site is online.

Request Parameters

In

Field Name

Type

Required

Description

header

Content-Type

string

Yes

application/json

header

Authorization

string

Yes

The integrator token created previously. For information on tokens, see Authentication.

header

X-Company-Id

string

Yes

The identifier (ID) of the company that owns the document

header

X-Site-Ids

string

Yes

The local site ID

header

sec-iv

string

Yes

The initialization vector

header

sec-fingerprint

string

Yes

The secret key ID

query

site_availability

boolean

No

If set to true, additional field - is_online is returned to determine if site is online

Responses

Code

Description

Schema

200

Successfully retrieved site status

SiteStatusResponse

Data Models

AddChildItemsRequestBody

Add child items body.

Field Name

Type

Required

Description

child_items

AddItemRequestBody

No

Individual item structure

AddCustomerRequestBody

Add a customer to the Order request body.

Field Name

Type

Required

Description

customer

CustomerRequestBody

No

Add a customer to the Order request body

AddDestinationRequestBody

Add a destination to the request body.

Field Name

Type

Required

Description

id

string

Yes

The unique identifier (UID) of a destination

name

string

No

The name of the destination

AddDiscountInfoRequestBody

Add discount information to the request body.

Field Name

Type

Required

Description

discounts

AddDiscountRequestBody

No

Adds discount information to the order

AddDiscountRequestBody

Field Name

Type

Required

Description

discount_definition_id

string

No

The unique identifier (UID) specific to a discount

discount_code

string

No

The unique code specific to a discount

discount_variable_value

number

No

The value specified when calculating variable discounts

order_item_ids

string

No

The list of order item IDs to add to a discount.

Note

This can be used only if the items exist.

ignore

boolean

No

If set to true, the discount is ignored in the calculation

discount_link_id

string

No

The unique value specified for linking discounts

AddItemRequestBody

Individual item structure.

Field Name

Type

Required

Description

product_id

string

No

The unique product identifier (ID). Either product_id or entity_id is required.

entity_id

string

No

The unique identifier (UID) relating to the product_id. Either product_id or entity_id is required.

item_type

string

No

The type of the item.

Examples: product, modifier

quantity

integer

No

The quantity of the items ordered.

Default: 1

name

string

No

The name of the item

unit_price

number

No

The unit price of the item

discount_info

AddDiscountInfoRequestBody

No

Add the Discount Information request body

comment

string

No

The user comments about the item

child_items

object

No

The child items are of a type item object

donation_id

string

No

The unique donation ID.

Minimum length: 1

apply_as

string

No

How the amount value should be applied to the order.

fixed: The amount is added as a fixed currency value.

percentage: The amount is calculated as a percentage of the total of the order.

Enum: round-up, fixed

fee_config

FeeConfigRequestBody

No

Add the Fee Configuration request body

build_type

string

No

Examples: plain, replace, augment

AddOrderDiscountsRequestBody

To add discounts at the order_level use the following structure:

Field Name

Type

Required

Description

discounts

array

DiscountObject

Yes

The list of discounts to be applied to the order

AddPaymentRequestBody

Field Name

Type

Required

Description

payments

object

No

The list of payments to add

amount

number

No

The payment amount rounded to "n" decimal digits based on the currency settings

pay_type_id

string

No

The payment type identifier (ID)

name_on_card

string

No

The name as shown on the card

card_brand_name

string

No

The card company brand.

Examples: Visa, Mastercard, American Express

payment_type

string

No

The payment type.

Examples: Cash, Credit, Debit, Gift Card, EBT

e_signature

string

No

Electronic signature

terminal_id

string

No

The terminal where the payment was processed

transaction_id

string

No

The Host reference transaction ID

CreateOrderRequestBody

The order fields and values for the create order request. Custom values may be included in the request and returned in the OrderObject under the additional_properties field.

Field Name

Type

Required

Description

terminal

TerminalRequestBody

Yes

The terminal attributes

items

itemObject

No

Add items to the Order request body

customer

CustomerRequestBody

No

Add a customer object to the order request body

destination

AddDestinationRequestBody

No

Add the Destination request body

owner

EmployeeObject

No

The owner's information

table_info

TableInfoRequestBody

No

Adding table information to the Order Object

event

EventRequestBody

No

Adding event information to the Order Object

table_name

string

No

The table name

add_event_info

boolean

No

If is true, then the next event will be added

order_type

string

No

The type of order

order_source_id

string

No

The Order Source ID.

Example: Kiosk

CustomerRequestBody

Add a customer object to the Order request body.

Field Name

Type

Required

Description

id

string

No

The user defined unique identifier (UID) for the customer record

first_name

string

No

The first name of the customer

last_name

string

No

The last name of the customer

phone_home

string

No

The home phone number of the customer

phone_work

string

No

The work phone number of the customer

phone_cell

string

No

The cell phone number of the customer

email

string

No

The email of the customer

address1

string

No

The address of the customer

address2

string

No

The secondary address of the customer

city

string

No

The city of the customer

state

string

No

The state of residence of the customer. The format is the proper name of the state. For example, Oregon.

zip_code

string

No

The zip code of residence of the customer

pickup_date_time

string

No

The pickup date and time. The format is in ISO 8601 Coordinated Universal Time (UTC) with millisecond precision strings. For example, 2026-05-19T13:15:00.000Z.

delivery_date_time

string

No

The delivery date and time. The format is in ISO 8601 UTC with millisecond precision strings. For example, 2026-05-19T13:15:00.000Z.

Sample Request Body

{
    "customer": {
        "id": "123456",
        "first_name": "Joe",
        "last_name": "Smith",
        "phone_home": "5555551111",
        "phone_work": "5555552222",
        "phone_cell": "5555553333",
        "email": "joe.smith@somedomain.com"
    }
}

DeleteDiscountRequestBody

Remove the Discount request body.

Field Name

Type

Required

Description

discount_ids

string

No

The list of discount identifiers (IDs) to remove

DeleteItemsRequestBody

Field Name

Type

Required

Description

order_item_ids

string

No

The list of order item identifiers (IDs) (order_item_id)

DeletePaymentRequestBody

Field Name

Type

Required

Description

payment_ids

string

No

The list of payment identifiers (IDs) to delete

EventRequestBody

Adding event information to the Order Object.

Field Name

Type

Required

Description

id

string

No

The unique identifier (UID) for the event

FeeConfigRequestBody

Field Name

Type

Required

Description

apply_as

string

No

fee_type

string

No

A fee type item.

Example: donation

FeeRequestBody

The fee type item. One of [fee_id, entity_id] is required.

Field Name

Type

Required

Description

fee_id

string

No

The unique identifier (UID) of the fee.

Minimum length: 1

Maximum length: 255

entity_id

string

No

The unique entity_id generated by Data Management for the fee.

Minimum length: 1

Maximum length: 255

fee_variable_value

number

No

The fixed percentage/fixed amount value.

Minimum: 0

Default: 0

PaymentMethodRequestBody

Field Name

Type

Required

Description

payment_method_type

string

No

The payment method type

card_reference_id

string

No

The card reference identifier (ID)

card_brand_name

string

No

The card company brand.

Examples: Visa, Mastercard, American Express

card_nickname

string

No

A customer chosen name for the card

account

string

No

The account ID

is_primary

boolean

No

A flag that indicates whether the payment method is primary

is_assigned

boolean

No

A flag that indicates whether the payment method is assigned

TableInfoRequestBody

Field Name

Type

Required

Description

table_id

string

No

The table identifier (ID)

table_name

string

No

The table name

TerminalRequestBody

Field Name

Type

Required

Description

id

string

Yes

The terminal number (previously known as the register number)

title

string

No

The terminal title.

Examples: front counter, drive thru

terminal_number

string

No

The terminal number

UpdateOrderItemRequestBody

Update the Order Item request body.

Field Name

Type

Required

Description

order_item_id

string

No

The unique identifier (UID) of the order item

name

string

No

The order item name

quantity

integer

No

Minimum: 1

fractional_quantity

FractionalQuantityObject

No

The Fractional Quantity Object information

units

integer

No

Minimum: 1

unit_price

number

No

Minimum: 0

serial_number

string

No

The order item's serial number

destination

DestinationObject

No

The Destination Object information

UpdateOrderRequestBody

Optional fields to update on the order.

Field Name

Type

Required

Description

point

string

No

The order point.

Examples: Kiosk1, Register1, Terminal1

external_order_id

string

No

The integrator specific identifier (ID) to link to their system

origin

string

No

The origin of the order.

Default: Mobile

customer

CustomerRequestBody

No

Adds a customer to the Order request body

reference_id

string

No

The reference to an existing order

OrderObject

These fields comprise the Order Object itself.

Field Name

Type

Required

Description

_id

string

No

The unique Order Object identifier (ID)

origin

string

No

This value is set to pos-api automatically

company_id

string

No

The unique identifier (UID) of the company

site_info

SiteInfoObject

No

The site details.

Examples: name, phone, address, website, and email

store_number

string

No

The store number defined by the company

creator

ContributorObject

No

Additional employees or terminals involved in this order

owner

EmployeeObject

No

The owner's information

contributors

ContributorObject

No

Additional employees or terminals involved in this order

order_number

string

No

The unique number for a particular company and particular site

version

string

No

The Order Object version

business_date

string

No

An ISO-8601 formatted current business date

state

string

No

The Order Object state: Open, Saved, Deleted, Voided, Overringed, Parked, Split, Suspended, Voided-post-payment, Committed, Checkedin, Bumped, and Purged

payment_status

string

No

Default: Open

The transaction type: Open, Paid, Partial, and Post-adjusted

notification_status

string

No

The Order Object status: Open, Committed, Committed-ack, Checkedin, Checkedin-ack, Voided, Voided-ack, and Bumped

destination

DestinationObject

No

The order destination. Available options are: dine-in, carry-out, drive thru, and delivery.

time

TimeObject

No

The order dates and times in ISO8601 format

customer

CustomerObject

No

The customer details information

items

ItemObject

No

An array of the order items

subtotal

number

No

The subtotal (total before taxes) of the order

tax_inclusive_subtotal

number

No

The order tax inclusive price

total

number

No

The total of the order

discount_info

DiscountInfoObject

No

The order level discount information

discount_total

number

No

The total of all order and item level discounts

tax_info

TaxInfoObject

No

The order level tax information

tax_exempt_info

TaxExemptInfoObject

No

The tax exempt information

tax_inclusive_info

TaxInclusiveInfoObject

No

The tax inclusive information

payment_info

PaymentInfoObject

No

The payment information

print_info

PrintInfoArray

No

The list of print records

order_type

string

No

The order type. The available options include: Order or Waste.

reference_id

string

No

The unique order ID of the order

comment

string

No

The comments about the order

table_info

TableInfoObject

No

The table information

table_name

string

No

The table name

additional_properties

object

No

An object which allows additional key-value pairs to be stored on an order.

Example: OrderedMap { "string_key": "string_value", "some_tokens": OrderedMap { "web_token": "token", "secret_token": 15284 } }

deleted_items

ItemObject

No

The deleted items

guest_count

number

No

The guest count

lifecycle

string

No

The life cycle of the order from total, tender, and save

order_point

string

No

The name or other ID of the specific device that created the order.

Example: kiosk1

order_source

string

No

The device from which the order originated. This value is set by the client ordering application and is specific to customer requirements. It is not used for system-level management of orders.

Note

order_source_ext is the new field that should be used instead. Any new code that reads an Order Object should use order_source only if order_source_ext is not provided.

If not provided, this value defaults to Kiosk unless another value is set in Site Preferences → General → Order Rules → Order Source Configuration for the Local Order API.

order_source_ext

object

No

The point from which the order originated

order_source_id

string

No

The ID of the device from which the order originated

name

string

No

The order name

is_tax_liable

boolean

No

order_status

object

No

The order status

status

string

No

Enum: Pending, Suspended, Closed, Saved, Deleted, Voided

reason_code

object

No

The reason code for a declined order

order_item_id

string

No

The order item ID

quantity

number

No

The order quantity

day_part_info

DayPartObject

No

Describes the daypart during which the order was sent

event

EventObject

No

The Event Object information

external_order_id

string

No

The external order ID

fulfillment_date

string

No

The fulfillment date of the order

segments

SegmentObject

No

The Segment Object information

sequential_order_number

string

No

The unformatted order number.

Example: 1004

ContributorObject

Additional employees or terminals involved in this order. This information designates the origin of the order.

Field Name

Type

Required

Description

employee

EmployeeObject

No

An object containing the information of the employee who created or modified the order

terminal

TerminalObject

No

An object containing the information of the terminal at which the order was created or modified

time

string

No

The time at which the order was created or modified in an ISO8601 format

CustomerObject

These fields comprise all customer-related information, which is either provided by the customers in-store, on third-party client user interfaces (UIs), or delivery service applications. Users can update some of these fields after an order has already been committed to In-Store POS API.

Field Name

Type

Required

Description

id

string

No

The user defined unique identifier (UID) for the customer record

first_name

string

No

The first name of the customer

last_name

string

No

The last name of the customer

phone_work

string

No

The work phone number of the customer

phone_cell

string

No

The cell phone number of the customer

phone_home

string

No

The home phone number of the customer

email

string

No

The email of the customer

address1

string

No

The address of the customer

address2

string

No

The secondary address of the customer

city

string

No

The city of the customer

state

string

No

The state of residence of the customer

zip_code

string

No

The zip code of residence of the customer

table_tent

string

No

The tent number

pickup_date_time

string

No

The pickup date and time

delivery_date_time

string

No

The delivery date and time

DayPartObject

These fields describe the daypart during which the order was sent. Dayparts are time periods during the day, each belonging to a particular daypart type and assigned to a specific day of the week. Dayparts allow users to track orders or restrict menus by time of day.

Field Name

Type

Required

Description

day_part_type_id

string

No

The unique identifier (UID) of the daypart type. This field matches the entity_id of the daypart type stored in Data Management.

day_part_type_name

string

No

The name of the daypart type.

Examples: Morning, Afternoon, Evening

external_id

string

No

The external ID used to reference the daypart type

DestinationObject

This information describes the Order Destination, which is the point of issue of the order. For example, Drive-thru, Dine-in, To Go. The Order Destination can alter what menu content is available and what pricing rules apply to the order.

Field Name

Type

Required

Description

id

string

No

The unique identifier (UID) of a destination

name

string

No

The name of the destination

consumption_type

string

No

The consumption type of the destination for the tax calculation

DiscountObject

Field Name

Type

Required

Description

name

string

No

The name of the discount

discount_code

string

Yes

The reference code for the discount

discount_definition_id

string

No

The definition identifier (ID) of the discount

discount_variable_value

string

Yes

The value specified when calculating variable discounts

order_items_ids

array (string)

No

The list of order item IDs to add a discount to. It should be provided only if items exist.

DiscountInfoObject

This object contains information for all discounts applied to the order.

Field Name

Type

Required

Description

discounts

DiscountObject

No

The list of discounts applied to the item or order

total_unrounded

number

No

The total discount amount applied to the item or order

total

number

No

The total discount amount rounded to "n" number of decimal digits based on currency settings

EmployeeObject

This object contains employee information, populated in-store.

Field Name

Type

Required

Description

id

string

No

The employee identifier (ID)

name

string

No

The employee's first and last name

title

string

No

The employee's job title.

Examples: cashier, manager

EventObject

Field Name

Type

Required

Description

id

string

Yes

The unique event identifier (ID)

name

string

No

The event name

event_type

object

No

The event type

entity_id

string

No

The event type entity ID

external_id

string

No

The external ID used to reference the event type

name

string

No

The event type name

FeeConfigObject

This information defines the configuration of a fee applied to the order.

Field Name

Type

Required

Description

amount

number

No

The amount of the fee. For percentage fees, this is the percentage to use when calculating the fee, written as a decimal number.

Example: 0.20 for 20%

apply_pre_tax

boolean

No

When set to true, the fee will be calculated on the subtotal, without discounts, before taxes are added. When false, the fee is calculated on the full total (subtotal + taxes - discounts).

apply_as

string

No

How the "amount" value should be applied to the order. The valid values are as follows:

  • fixed: The amount is added as a fixed currency value

  • percentage: The amount is calculated as a percentage of the total of the order

fee_type

string

No

Specifies what type of fee the object represents. The valid values are as follows:

  • gratuity: The fee is a gratuity calculation. It could be automatic or manual

  • service: The fee is an arbitrary service fee

FractionalQuantityObject

Field Name

Type

Required

Description

numerator

number

Yes*

The increment numerator of the modifier build.

*This field is required if the fractional quantity condition is met.

denominator

number

Yes*

The increment denominator of the modifier build.

*This field is required if the fractional quantity condition is met.

ItemObject

This object contains information for an individual item within the order.

Field Name

Type

Required

Description

product_id

string

No

The unique product identifier (ID)

entity_id

string

No

The unique identifier (UID) relating to the product_id

timestamp

string

No

An ISO-8601 formatted date-time of the product when the item is added to the order

name

string

No

The name of the item

state

string

No

The state of the item.

Examples: Saved, Voided, Deleted

payment_status

string

No

The payment status.

Example: Paid

tags

array

No

An array of strings

unit_price

number

No

The unit price of the item

quantity

integer

No

The quantity of the items ordered

fractional_quantity

FractionalQualityObject

No

The fractional quantity of the item ordered

child_items

object

No

A nested item object

master

string

No

The base item ID (used for modifiers)

comment

string

No

The user comments about the item

fee_config

FeeConfigObject

No

Defines the configuration for a fee type order item

kitchen_routing_categories

string

No

A list of strings that tells us which kitchen printer an item should be sent to on "send to kitchen"

time

TimeObject

No

The item time information

discount_info

DiscountInfoObject

No

The information for an item-leve discount

PaymentInfoObject

These fields provide information for all payments on an order.

Field Name

Type

Required

Description

payments

PaymentObject

No

The list of payments used to pay the order

PaymentObject

These fields store information for an individual payment on an order. Online orders can contain payment information already, or they can be committed as an unpaid order, allowing point of sale (POS) employees to populate payment information in-store. An order can also might be updated in-store if the order content changes.

Field Name

Type

Required

Description

account

string

No

The account identifier (ID)

aid_number

string

No

An authorization ID. For Europay, Mastercard, and Visa (EMV) transactions, this is the application identifier (AID) field.

amount

number

No

The payment amount rounded to "n" decimal digits based on the currency settings

application_name

string

No

The name of card processing application.

Examples: MasterCardCredit, AMEX

For EMV transactions, this is the APL field.

auth

string

No

The authentication code

balance

number

No

The balance on the card

card_acquisition

string

No

The type of acquisition.

Examples: MANUAL, SWIPE, CONTACTLESS, SCANNER, CHIP, or CHIP_FALL_BACK_SWIPE.

For EMV transactions, this is the CEM field.

name_on_card

string

No

The name as shown on the card

id

string

No

The unique payment ID

pay_type_id

string

No

The payment type ID

card_brand_name

string

No

The card company brand.

Examples: Visa, Mastercard, American Express

point_balance

string

No

The number of points left in a customer's house account. For example, a customer could have 30 points left for rewards after the order transaction.

trace_number

string

No

The transaction ID in the batch

transaction_id

string

No

The transaction ID

arqc

string

No

A cryptogram field

tc

string

No

A cryptogram field

emv

string

No

The EMV format for Portico

e_signature

string

No

The electronic signature

terminal_id

string

No

The terminal where the payment was processed

payment_type

string

No

Examples: Cash, Credit, Debit, Gift Card, EBT

signature

boolean

No

If true, the printer prints the signature line

verification_method

string

No

The specified verification method.

Examples: SIGNATURE VERIFIED, PIN VERIFIED, NO SIGNATURE REQUIRED

pin

string

No

If the PIN is supplied, the signature is not required

agreement

string

No

The Portico requirement added for certification

refund_policy

string

No

The Portico requirement added for certification

PrintInfoArray

Field Name

Type

Required

Description

PrintInfoArray

PrintRecordObject

No

The list of print records

PrintRecordObject

These fields provide information for an individual print record.

Field Name

Type

Required

Description

printed_by

string

No

The first and last name of who printed the receipt

user_id

string

No

The employee identifier (ID)

time

string

No

An ISO-8601 formatted timestamp of when the receipt was printed

SegmentObject

Users can divide orders into segments, defined in these fields. Data Management provides settings for configuring segment names.

Field Name

Type

Required

Description

title

string

No

The name of the segment (Tray1, Tray2 or Seat1, Seat2). This name depends on how it was created as Tray or Seat, which is set on Data Management.

num

number

No

The number of the corresponding segment that will be included in the OrderItem to determine to which segment the item belongs

id

string

No

The unique segment identifier (ID)

SiteInfoObject

These fields contain details for an order site or location.

Field Name

Type

Required

Description

address

string

No

The first address line for the site

address2

string

No

The second address line for the site

city

string

No

The site city

email

string

No

The email for a site

id

string

No

The site identifier (ID)

name

string

No

The site name

phone

string

No

The site phone

state

string

No

The United States (US) state or country province for the site

store_number

string

No

The store number defined by the company

website

string

No

The website for the site

zip

string

No

The site zip code

type

string

No

The site type

TableInfoObject

Field Name

Type

Required

Description

table_id

string

No

The unique table identifier (ID)

table_number

string

No

The table number

table_name

string

No

The table name

TaxExemptInfoObject

These fields provide information about tax exemptions.

Field Name

Type

Required

Description

id

string

No

The tax exempt identifier (ID)

reason

string

No

The reason text for tax exemption

taxes

TaxObject

No

The list of taxes exempted

total

number

No

The total tax exempted rounded to "n" digits based on the currency settings

TaxGroupObject

These fields describe a specific tax group.

Field Name

Type

Required

Description

entity_id

string

No

The tax group entity identifier (ID)

tax_code

string

No

Tax Code/Tax Group ID

name

string

No

The tax group name

TaxInclusiveInfoObject

These fields define the inclusive taxes applied to an order, item, or tax.

Field Name

Type

Required

Description

taxes

TaxObject

No

The list of taxes applied to the item, order, or tax

total_unrounded

number

No

The total tax amount included in the item's price

total

number

No

The total tax amount included in the item's price rounded to "n" digits based on the currency settings

TaxInfoObject

These fields contain information for all taxes applied to an order, item, or tax.

Field Name

Type

Required

Description

taxes

TaxObject

No

The list of taxes applied to the item or order

total_unrounded

number

No

The total unrounded tax amount applied to the item or order

total

number

No

The total tax applied to the item/order rounded to "n" digits based on the currency settings

TaxObject

These fields provide information for an individual tax.

Field Name

Type

Required

Description

tax_definition_id

string

No

The unique tax identifier (ID)

name

string

No

The name of the tax

amount_unrounded

number

No

The amount of the tax applied to the order/item

amount

number

No

The amount of the tax applied to the order/item rounded to "n" decimal digits based on the currency settings

tax_info

object

No

The Tax Info Object (Nested tax on tax)

visible

boolean

No

Determines if the discount is visible

TerminalObject

These fields define the information for the terminal associated with a particular order or event.

Field Name

Type

Required

Description

id

string

No

The terminal identifier (previously known as register ID)

title

string

No

The terminal title.

Examples: front counter, drive thru

terminal_number

string

No

The terminal number

TimeObject

Field Name

Type

Required

Description

created

string

No

ISO-8601 Formatted

closed

string

No

ISO-8601 Formatted

last_modified

string

No

ISO-8601 Formatted

notification_checkedin

string

No

ISO-8601 Formatted

notification_committed

string

No

ISO-8601 Formatted

notification_open

string

No

ISO-8601 Formatted

notification_voided

string

No

ISO-8601 Formatted

ComponentInfo

Field Name

Type

Required

appdateUTC

string

No

statuscode

number

No

statusmessage

string

No

info

string

No

servertimestamp

string

No

servertimestampUTC

string

No

appname

string

No

appcode

string

No

appversion

string

No

url

string

No

SiteStatusResponse

The list of statuses for each requested site.

Field Name

Type

Required

Description

store_number

string

No

The enterprise specific store number

store_name

string

No

The enterprise specific store name

last_contact_time

string

No

An ISO-8601 formatted date-time stamp of the last time the cloud made contact with the specified site

business_date

string

No

The business date of the specified site status

pos_type

string

No

The type of point of sale (POS) device at the site

pos_version

string

No

The version of the POS at the site

server_timestamp

string

No

An ISO-8601 formatted date-time stamp of when the site status was pushed from the store

site_id

string

No

The unique identifier (UID) of the specified site

company_id

string

No

The UID of the company at which the site resides

GeneralErrorStructure

The General Error Object structure.

Field Name

Type

Required

Description

error

object

No

The object of the error properties

detail

string

No

The detail description of the operational error

code

number

No

See: Error Responses for potential error codes

company_id

string

No

The company identifier (ID) of the request

site_id

string

No

The site ID of the request

context

array

No

The list of objects that give more details about the specified error

detail

string

No

The detail description of the error context

code

number

No

See: Error Responses for potential error codes

Integrator specified ID in question

string

No

This field can be one of the following: entity_ids, order_discount_ids,or order_item_ids. It signifies the ID that is in question when trying to perform the specified operation. Example: key:value pair: entity_ids: ['123456789','987654321']

Error Responses

The following table defines the error responses returned by In-Store POS API:

Code

Details

-1

Message

Failed to get Order Destinations

Description

In-Store POS API cannot identify the location that will prepare the order for one of the following reasons:

  • The site_id in the header is incorrect.

Sample Response Message

{
    "error": {
        "code": -1,
        "message": "Failed to get Order Destinations",
        "company_id": "9999999999999999",
        "site_id": "999999"
    }
}

1

Message

Error code 1 will include a message with one of the following formats:

  • data should have required property PROPERTY_NAME

  • data.PARENT_PROPERTY_NAME should have required property PROPERTY_NAME

  • data.PARENT_PROPERTY_NAME.INDEX_OF_CHILD_ITEM should have required property PROPERTY_NAME

  • data.PROPERTY_NAME[INDEX_OF_CHILD_ITEM].PROPERTY_NAMEshould match pattern \"^[a-fA-F0-9]{24}$\

  • data.PROPERTY_NAME should be equal to one of the allowed values

Description

Error code 1 indicates a missing or invalid required value in the request body.

The error response message indicates which property is missing and any parent element of the missing property.

If the missing property belongs to a child of a parent attribute, the response will include the index of the child item that caused the error.

If more than one error results in error code 1, the error messages are separated by a comma.

If the property is invalid, the error message indicates the correct format.

Sample Response Message

{
    "error": {
        "code": 1,
        "message": "data should have required property 'store_number',
        ... data.terminal should have required property 'id'",
        "company_id": "9999999999999999",
        "site_id": "9999999999999999"
    }
}

4

Message

Invalid Request - Order must have items

Description

The request did not include the required Order Object with an items array.

Sample Response Message

{
    "error": {
        "detail": "Failed to commit order",
        "code": 61,
        "context": [
            {
                "detail": "Invalid Request - Order must have items",
                "code": 4
            }
        ],
        "company_id": "9999999999999999",
        "site_id": "9999999999999999",
        "_id": "9999999999999999",
        "order_number": "999999",
        "store_number": "9999"
    }
}

14

Message

Order Already Tendered

Description

The order had already been paid in full.

Sample Response Message

{
    "error": {
        "detail": "Failed to add payment",
        "code": 58,
        "context": [
            {
                "detail": "Order Already Tendered",
                "code": 14
            }
        ],
        "company_id": "9999999999999999",
        "site_id": "9999999999999999",
        "_id": "9999999999999999",
        "order_number": "999999",
        "store_number": "9999"
    }
}

16

Message

Missed or Invalid Auth Token

Description

Request header does not include a valid auth token.

Sample Response Message

{
    "error": {
        "code": 16,
        "message": "Missed or Invalid Auth Token"
    }
}

22

Message

Customer not found

Description

In-Store POS API cannot find a customer with the customer_id value sent with the Add Items request, or the customer_id value is missing from the request.

Sample Response Message

{
    "error": {
        "detail": "Failed to add payment",
        "code": 58,
        "context": [
            {
                "detail": "Customer not found",
                "code": 22
            }
        ],
        "company_id": "9999999999999999",
        "site_id": "9999999999999999",
        "_id": "9999999999999999",
        "order_number": "999999",
        "store_number": "9999"
    }
}

37

Message

Missing Company or Site ID in Header

Description

Request header does not include a value for the required X-SITE-IDs or X-COMPANY-ID property.

Sample Response Message

{
    "error": {
        "code": 37,
        "message": "Missing Company or Site ID in Header"
    }
}

43

Message

Failed to add item

Description

The Add Item request failed. This error response includes child errors that state why the request failed.

Sample Response Message

{
    "error": {
        "detail": "Failed to add item",
        "code": 43,
        "context": [
            {
                "detail": "Failed to get products",
                "code": 76,
                "entity_ids": [],
                "product_ids": [
                    "asdf"
                ]
            }
        ],
        "company_id": "9999999999999999",
        "site_id": "9999999999999999",
        "_id": "9999999999999999",
        "order_number": "999999",
        "store_number": "9999"
    }
}

58

Message

Failed to add payment

Description

The Add Payment request failed. This error response includes child errors that state why the request failed. 

Sample Response Message

{
    "error": {
        "detail": "Failed to add payment",
        "code": 58,
        "context": [
            {
                "detail": "Customer not found",
                "code": 22
            }
        ],
        "company_id": "9999999999999999",
        "site_id": "9999999999999999",
        "_id": "9999999999999999",
        "order_number": "999999",
        "store_number": "9999"
    }
}

61

Message

Failed to commit order

Description

The Commit Order request failed. This error response includes child errors that state why the request failed. 

Sample Response Message

{
    "error": {
        "detail": "Failed to commit order",
        "code": 61,
        "context": [
            {
                "detail": "Invalid Request - Order must have items",
                "code": 4
            }
        ],
        "company_id": "9999999999999999",
        "site_id": "9999999999999999",
        "_id": "9999999999999999",
        "order_number": "999999",
        "store_number": "9999"
    }
}

76

Message

Failed to get products.

Description

In-Store POS API cannot find a product with the entity_id value sent with the Add Items request.

Sample Response Message

{
    "error": {
        "detail": "Failed to add item",
        "code": 43,
        "context": [
            {
                "detail": "Failed to get products",
                "code": 76,
                "entity_ids": [],
                "product_ids": [
                    "asdf"
                ]
            }
        ],
        "company_id": "9999999999999999",
        "site_id": "9999999999999999",
        "_id": "9999999999999999",
        "order_number": "999999",
        "store_number": "9999"
    }
}