Operation Definitions

The Online Ordering API documentation includes operation definitions, which list the endpoints, data models, and error responses.

Endpoints

GET /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

POST /api/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.

Note

To create a refund order request, use the Create Refund Order request body.

To create an order with loyalty information, use the Create Order with loyalty information request body.

Beyond the standard Create Order request, which is documented below, it is possible to use the Create Order request to access additional features of Online Ordering:

Marketplace Facilitator Taxes - For integrators, such as delivery partners that are required to collect tax in some states but not in others, the Create Order operation provides a way to define the tax liability state of 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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
body	`body`	CreateOrderRequestBody	Yes	Add the Create Order request body. To create a refund order, replace with CreateRefundOrderRequestBody. To create an order with loyalty information, replace with CreateOrderLoyaltyRequestBody.

Responses

Code	Description	Schema
200	Order successfully created	OrderObject
400	Error creating order	GeneralErrorStructure

GET /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

DELETE /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
header	`X-Order-Target`	string	No	The order target
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

PUT /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
path	`_id`	string	Yes	The unique identifier (UID) relating to the order
body	`body`	array of order_item	Yes	Adds items to the order request body (individual item structure). To add loyalty discount information, use the `discount_info` field from the order_item.

Responses

Code	Description	Schema
200	Item successfully added	OrderObject
400	Error adding item to order	GeneralErrorStructure

DELETE /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

PUT /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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 /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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 /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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 /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

DELETE /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

PUT /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

DELETE /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

PUT /api/order/{_id}/discount

Summary

Use the Create Order operation to create a new discount order with loyalty 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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

DELETE /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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

PUT /api/order/{_id}/total

Summary

Manually total 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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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 /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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 /api/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 will have to 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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
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 /api/order/{_id}/touchlessPayment

Summary

Add a touchless payment option to 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
header	`X-COMPANY-ID`	string	Yes	The identifier of the company that owns the document
header	`X-SITE-IDs`	string	Yes	Comma separated list of the site identifiers
body	`BODY`	AddPaymentRequestBody	Yes	The JSON formatted request

Responses

Code	Description	Schema
200	Successfully added touchless payment	OrderObject
400	Error adding touchless payment	GeneralErrorStructure

PUT /api/order/{_id}/close

Summary

Close 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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
header	`x-order-target`	string	No	If it does not exist or is empty, then we send `xooApiNotification` and `xooOrder notifications` by default. Otherwise, we send `posOrder` notifications.
path	`_id`	string	Yes	The unique identifier (UID) relating to the order
body	`body`	CloseOrderRequestBody	Yes	The JSON formatted request

Responses

Code	Description	Schema
200	Successfully closed order	OrderObject
400	Validation Error	GeneralErrorStructure

GET /api/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
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of site identifiers
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

GET /api/info

Summary

Get the component information.

Request Parameters

No parameters

Responses

Code	Description	Schema
200	Returns component information	ComponentInfo

PUT /api/total

Summary

Create an order without saving it to the database.

Request Parameters

In	Field Name	Type	Required	Description
header	`Content-Type`	string	Yes	`application/json`
header	`Authorization`	string	Yes	The integrator token created previously
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
body	`body`	CreateOrderRequestBody	Yes	The JSON formatted request

Responses

Code	Description	Schema
200	Order successfully created	OrderObject
400	Error creating order	GeneralErrorStructure

PUT /api/cache-reset

Summary

Reset the cache.

Request Parameters

In	Field Name	Type	Required	Description
header	`Content-Type`	string	Yes	`application/json`
header	`Authorization`	string	Yes	The integrator token created previously
header	`X-Company-Id`	string	Yes	The identifier of the company that owns the document
header	`X-Site-Ids`	string	Yes	Comma separated list of the site identifiers
body	`body`	array [string]	Yes	Entities to be deleted from the cache

Responses

Code	Description	Schema
200	Default: Cache successfully cleared	string
400	Error clearing cache	GeneralErrorStructure

PUT /api/order/{refund_order_id}/payment

Summary

Use the Add Refund Order Payment operation to send a refund request for an order.

Request Parameters

In	Field Name	Type	Required	Description
header	`Content-Type`	string	Yes	`application/json`
header	`Authorization`	string	Yes	The integrator token required to perform API calls for the company
header	`X-Company-Id`	string	Yes	The unique identifier (UID) for the company in which the menu will be created
header	`X-Site-Ids`	string	Yes	The UID for the site in which the menu will be created
body	`body`	AddRefundOrderPaymentRequestBody	Yes	Add the Add Refund Order Payment request body

Data Models

BaseCreateOrderRequestBody

The Create Order request body.

Field Name	Type	Required	Description
`store_number`	string	No	The store number of the specified site
`terminal`	TerminalRequestBody	No	These fields define the information for the terminal associated with a particular order or event
`items`	array of order_item	No	Adds items to the Order request body (individual item structure)
`customer`	CustomerRequestBody	No	Adds a customer to the request body
`destination`	AddDestinationRequestBody	No	Adds a destination to the request body
`discount_info`	AddDiscountInfoRequestBody	No	Adds discount information to the request body
`reference_id`	string	No	The reference to another order identifier
`owner`	EmployeeObject	No	The owner's information
`suite_info`	SuiteInfoRequestBody	No	Adds suite information to the Order Object. If only the suite_id is provided, then the other data is taken from the xcat API.
`table_info`	TableInfoRequestBody	No	Adds table information to the Order Object
`event`	EventRequestBody	No	Adds event information to the Order Object
`table_name`	string	No	If the table_name is missing, it will be taken from the suite_info.name
`add_event_info`	boolean	No	If is true, then the next event will be added
`fees`	FeeRequestBody	No	Minimum items: 1
`order_source`	string	No	The Order Source. Example: Mobile
`order_type`	string	No	The type of order. Enum: order, refund
`order_source_id`	string	No	The Order Source ID, if present order_source_entity_id is not allowed. Example: web
`order_source_entity_id`	string	No	The Order Source item
`is_tax_liable`	boolean	No	Specifies if the marketplace merchant is liable for taxes
`marketplace_remitted_tax`	number	No	Specified by the integrator
`collected_exclusive_tax`	number	No	Specified by the integrator

RefundRequest

If order_type = refund.

Field Name	Type	Required	Description
`reference_id`	string	No	The refund reference identifier
`items`	AddRefundItemsRequestBody	No	Add items to the Order request body

RegularOrderRequest

For regular order items.

Field Name	Type	Required	Description
`items`	array of order_item	No	Adds items to the Order request body (individual item structure)

CreateOrderRequestBody

Field Name	Type	Required	Description
`store_number`	string	No	The store number of the specified site
`terminal`	TerminalRequestBody	Yes	The terminal attributes
`items`	array of order_item	Yes	Add items to the Order request body
`customer`	CustomerRequestBody	Yes	Add customer to the order request body
`destination`	AddDestinationRequestBody	Yes	Add the Destination request body
`discount_info`	AddDiscountInfoRequestBody	Yes	Add the Discount Information request body
`reference_id`	string	No	The reference to another order identifier
`owner`	EmployeeObject	No	The owner's information
`suite_info`	SuiteInfoRequestBody	Yes	Adding suite information to the Order Object. If only the `suite_id` is provided, then the other data is taken from the xcat API.
`table_info`	TableInfoRequestBody	Yes	Adding table information to the Order Object
`event`	EventRequestBody	Yes	Adding event information to the Order Object
`table_name`	string	No	If the `table_name` is missing, it will be taken from the suite_info.name
`add_event_info`	boolean	No	If is true, then the next event will be added
`fees`	FeeRequestBody	Yes	The fee type item. One of [`fee_id`, `entity_id`] is required
`order_source`	string	No	The Order Source. Example: Mobile
`order_type`	string	No	The type of order. Enum: order, refund
`order_source_id`	string	No	The Order Source ID, if present, `order_source_entity_id` is not allowed. Example: web
`order_source_entity_id`	string	No	The Order Source item
`is_tax_liable`	boolean	No	Specifies if the marketplace merchant is liable for taxes
`marketplace_remitted_tax`	number	No	Specified by the integrator
`collected_exclusive_tax`	number	No	Specified by the integrator

CreateRefundOrderRequestBody

Field Name	Type	Required	Description
`order_type`	string	Yes	The order type which defines when an order should be a refund: `"order_type": "refund"`
`reference_id`	string	Yes	The identification (ID) from the original order

CreateOrderLoyaltyRequestBody

Field Name	Type	Required	Description
`customer`	customer Object	Yes	Contains loyalty information from the customer

customer Object

Field Name	Type	Required	Description
`loyalty_info`	loyalty_info Object	Yes	The customer's loyalty information added to the order

Sample Request Body

{
    "customer": {
        "first_name": "Fname",
        "id": "1234567890123456789",
        "last_name": "Lname",
        "loyalty_card_number": "0987654321",
        "loyalty_info": {
            "customer": {
                "customer_id": "1234",
                "first_name": "Fname",
                "identification_method": "loyalty_card_number",
                "last_name": "Lname",
                "loyalty_card_number": "0122333444455555"
            }
        },
        "phone_cell": "999-999-9999"
    },
    "items": [
        {
            "product_id": "123",
            "quantity": 1,
            "unit_price": 3.50
        },
        {
            "product_id": "456",
            "quantity": 1,
            "unit_price": 2
        }
    ],
    "order_source": "APP",
    "store_number": "146",
    "terminal": {
        "id": "02"
    }
}

loyalty_info Object

Field Name

Type

Required

Description

balances

array

balance Object

The list of customer's loyalty balances. For example, points or visits.

cards

array

cards Object

The list of stored value accounts available for the customer

customer

inner customer Object

Yes

The loyalty customer personal information

balance Object

Field Name	Type	Required	Description
`balance`	number	No	The customer's loyalty balance
`expiration_dates`	array expiration_dates Object	No	The loyalty balance expiration dates
`name`	string	No	The loyalty balance's name. For example, `Points`.
`type`	string	No	The loyalty balance type

expiration_dates Object

Field Name	Type	Required	Description
`expiration_date`	string	No	The loyalty balance expiration date
`points_quantity`	number	No	The balance amount to expire

cards Object

Field Name	Type	Required	Description
`card_number`	string	No	The customer's stored value account or card number
`card_balance`	string	No	The customer's stored value account or card balance
`pin`	string	No	The customer's stored value account or card PIN

inner customer Object

Field Name	Type	Required	Description
`identification_method`	string (enum)	Yes	The method used to identify loyalty customer. The possible values are as follows: `code` `first_name` `last_name` `loyalty_card_number` `email` `phone_number` `coupon`
`first_name`	string	No	The customer's first name
`last_name`	string	No	The customer's last name
`loyalty_card_number`	string	Yes*	The customer's loyalty card or account number that can be used for customer identification. *One of the following is required for the request: `loyalty_card_number` `code` `email` `phone`
`code`	string	Yes*	The customer's loyalty code that can be used for customer identification. *One of the following is required for the request: `loyalty_card_number` `code` `email` `phone`
`email`	string	Yes*	The customer's email. *One of the following is required for the request: `loyalty_card_number` `code` `email` `phone`
`phone`	string	Yes*	The customer's phone number. *One of the following is required for the request: `loyalty_card_number` `code` `email` `phone`
`id`	string	No	The customer account identifier (ID) in the loyalty system

offers Object

Field Name	Type	Required	Description
`apply_automatically`	boolean	Yes*	The flag that identifies if the reward should be applied automatically. These rewards cannot be removed from the order. *This field is required if the offers Object is provided.
`calculated_by`	string	Yes*	Indicates the party responsible for the loyalty rewards. This should be set to `provider` when the loyalty rewards are calculated and validated by a loyalty provider. This should be set to `client` when the loyalty rewards are calculated and validated by our system. For this type of integration, the value should be set to `provider`. *This field is required if the offers Object is provided.
`points_required`	number	No	The amount of points associated with the reward
`expiration_date`	string	No	The reward expiration date
`id`	string	Yes*	The reward identification value. *This field is required if the offers Object is provided.
`name`	string	Yes*	The reward name. *This field is required if the offers Object is provided.
`program_id`	string	No	The reward program identifier (ID)
`reward_type`	string	No	The reward type
`status`	string	Yes*	The reward status: `validated` `redeemed` *This field is required if the offers Object is provided.

TerminalRequestBody

Terminal attributes.

Field Name

Type

Required

Description

id

string

The terminal number (previously known as the register number)

title

string

The terminal title.

Examples: front counter, drive thru

terminal_number

string

The terminal number

AddRefundItemsRequestBody

Add items to the Order request body.

Field Name

Type

Required

Description

quantity

number

The number of item quantity to refund.

Minimum: 1

order_item_id

string

The unique order item identifier

AddChildItemsRequestBody

Add child items body.

Field Name	Type	Required	Description
`child_items`	AddItemRequestBody	No	Individual item structure

AddItemRequestBody

Individual item structure.

Field Name	Type	Required	Description
`product_id`	string	No	The unique product identifier. Either `product_id` or `entity_id` is required.
`entity_id`	string	No	The unique identifier (GUID) 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 identifier. 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

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

PaymentMethodRequestBody

Field Name	Type	Required	Description
`payment_method_type`	string	No	The payment method type
`card_reference_id`	string	No	The card reference identifier
`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 identifier
`is_primary`	boolean	No
`is_assigned`	boolean	No

AccountFeeRequestBody

Field Name	Type	Required
`entity_id`	string	No
`id`	string	No
`calc`	object	No
`type`	string	No
`value`	number	No
`max_value`	number	No

AccountRequestBody

Field Name	Type	Required	Description
`account_id`	string	No	The account identifier
`payment_methods`	PaymentMethodRequestBody	No	Add the Payment Method request body
`fees`	AccountFeeRequestBody	No	Add the Account Fee request body

AddRefundItemsRequestBody

Add items to the Order request body.

Field Name

Type

Required

Description

quantity

number

The number of item quantity to refund.

Minimum: 1

order_item_id

string

The unique order item identifier

CustomerRequestBody

Add a customer to the Order request body.

Field Name	Type	Required	Description
`id`	string	No	The user defined unique identifier 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
`zip_code`	string	No	The zip code of residence of the customer
`pickup_date_time`	string	No	The pickup date and time
`delivery_date_time`	string	No	The delivery date and time
`accounts`	AccountRequestBody	No	Add the Account request body

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 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
`loyalty_info`	loyalty_info Object	Yes	The loyalty information of a customer added to the order

loyalty_info Object

Field Name	Type	Required	Description
`apply_automatically`	boolean	Yes	The flag that indicates if the discount should be applied to the order automatically
`quantity_redeemed`	number	Yes	The loyalty discount quantity
`reward_id`	string	Yes	The loyalty discount identifier (ID)
`reward_type`	string	Yes	The loyalty Object discount type
`status`	string	Yes	The loyalty discount status, which should be validated when the order is `unpaid`, `redeemed`, and `fully paid`
`code`	string	No	The loyalty Object discount code
`program_id`	string	No	The loyalty discount program ID
`amount`	number	Yes	The loyalty discount amount
`offers`	array offers Object	No	The list of loyalty offers added to the order. This parameter is added for order-level loyalty information only.

DeleteDiscountRequestBody

Remove the Discount request body.

Field Name	Type	Required	Description
`discount_ids`	string	No	The list of discount identifiers to remove

AddDestinationRequestBody

Add a destination to the request body.

Field Name	Type	Required	Description
`id`	string	No	The unique identifier of a destination
`name`	string	No	The name of the destination
`default_taxable_destination`	boolean	No
`checkin_on_commit`	boolean	No	If this flag is enabled and set to `True`, the order is sent with a `checked_in` order status

DeleteItemsRequestBody

Field Name	Type	Required	Description
`order_item_ids`	string	No	The list of order item identifiers (`order_item_id`)

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
`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 identifier

CloseOrderRequestBody

Field Name	Type	Required	Description
`payments`	object	No	The Payment Object
`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
`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 identifier
`owner`	EmployeeObject	No	The owner's information
`suite_info`	SuiteInfoRequestBody	No	Adds suite information to the Order Object. If only the `suite_id` is provided, then the other data is taken from the xcat API.
`table_info`	TableInfoRequestBody	No	Adds table information to the Order Object
`table_name`	string	No	If the `table_name` is missing, it will be taken from the `suite_info.name`

DeletePaymentRequestBody

Field Name	Type	Required	Description
`payment_ids`	string	No	The list of payment identifiers to delete

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

TableInfoRequestBody

Add table information to the Order Object.

Field Name	Type	Required	Description
`table_id`	string	No	The table identifier
`table_name`	string	No	The table name

EventRequestBody

Adding event information to the Order Object.

Field Name	Type	Required	Description
`id`	string	No	The unique identifier (UID) for the event

FeeRequestBody

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

Field Name

Type

Required

Description

fee_id

string

The unique identifier (UID) of the fee.

Minimum length: 1

Maximum length: 255

entity_id

string

The unique entity_id generated by Data Management for the fee.

Minimum length: 1

Maximum length: 255

fee_variable_value

number

The fixed percentage/fixed amount value.

Minimum: 0

Default: 0

SuiteInfoRequestBody

Add suite information to the Order Object. If only the suite_id is provided, then the other data is taken from the xcat API.

Field Name	Type	Required	Description
`suite_id`	string	No	The unique identifier (UID) for the suite
`entity_id`	string	No	The entity identifier
`name`	string	No	The suite name
`short_name`	string	No	The suite short name

SiteInfoObject

These fields contain details for an order site or location. Typically, Online Ordering orders only populate the bare minimum of SiteInfo in order to identify to which site the order should be sent.

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
`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

EmployeeObject

This object contains employee information, populated in-store.

Field Name

Type

Required

Description

id

string

The employee identifier

name

string

The employee's first and last name

title

string

The employee's job title.

Examples: cashier, manager

TerminalObject

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

Field Name

Type

Required

Description

id

string

The terminal identifier (previously knows as register ID)

title

string

The terminal title.

Examples: front counter, drive thru

terminal_number

string

The terminal number

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

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

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

CustomerObject

These fields comprise all customer-related information, which is either provided by the customers in-store or 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 Online Ordering API.

Field Name	Type	Required	Description
`id`	string	No	The user defined unique identifier 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
`loyalty_customer`	boolean	No

FeeConfigRequestBody

Field Name

Type

Required

Description

apply_as

string

fee_type

string

A fee type item.

Example: donation

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
`entity_id`	string	No	The unique identifier (GUID) relating to the `product_id`
`order_item_id`	string	No	The unique item instance identifier
`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
`item_type`	string	No	The type of the item. Examples: product, modifier
`state`	string	No	The state of the item. Examples: Saved, Voided, Deleted
`payment_status`	string	No	The payment status. Examples: Paid, Refunded
`tags`	array	No	An array of strings
`price`	number	No	The calculated price of the item
`unit_price`	number	No	The unit price of the item
`quantity`	integer	No	The quantity of the items ordered
`fractional_quantity`	FractionalQuality	No	The fractional quantity of the item ordered
`discount_info`	DiscountInfoObject	No	The item discount information
`tax_info`	TaxInfoObject	No	The item tax information
`tax_inclusive_info`	TaxInclusiveInfoObject	No	The item tax inclusive information
`tax_group`	TaxGroupObject	No	The item tax group
`child_items`	object	No	A nested item object
`master`	string	No	The identifier of the base item (used for modifiers)
`comment`	string	No	The user comments about the item
`tax_inclusive_price`	number	No	The item tax inclusive price
`fee_config`	FeeConfigObject	No	Defines the configuration for a "fee" type order item
`hash_code`	string	No	A hash code order
`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"
`reporting_category`	object	No	The order item reporting category
`tax_inclusive`	boolean	No	The item tax inclusive information
`time`	TimeObject	No	The item time information

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

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

DiscountObject

This information describes a specific discount that applies to the order. Our system offers many type of discount configurations, including order level and Item level discounts, manual and automatic, percentage and fixed amount, and quantity-based.

Field Name	Type	Required	Description
`discount_definition_id`	string	No	The unique discount identifier
`order_discount_id`	string	No	The unique discount instance identifier
`discount_variable_value`	number	No	The variable discount amount value
`apply_type`	string	No	How the discount is applied. Examples: Manual, Automatic
`quantity`	integer	No	The quantity of the specified discount applied
`amount_unrounded`	number	No	The amount of discount applied unrounded (5-digit decimal precision)
`amount`	number	No	The amount of discount applied rounded to "n" number of decimal digits based on the currency settings
`distributed`	boolean	No	True: Distributed discount amount False: Actual full discount amount
`ignore`	boolean	No	True: Ignore the discount in all calculations False (default): Discounts are applied (not ignored)

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

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

TaxGroupObject

These fields describe a specific tax group.

Field Name	Type	Required	Description
`entity_id`	string	No	The entity identifier of the tax group
`tax_code`	string	No	Tax Code/Tax Group identifier
`name`	string	No	The name of the tax group

TaxExemptInfoObject

These fields provide information about tax exemptions.

Field Name	Type	Required	Description
`id`	string	No	The tax exempt identifier
`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

TaxObject

These fields provide information for an individual tax.

Field Name	Type	Required	Description
`tax_definition_id`	string	No	The unique tax identifier
`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

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
`aid_number`	string	No	An authorization identifier. 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 identifier
`pay_type_id`	string	No	The payment type identifier
`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 identifier in batch
`transaction_id`	string	No	The transaction identifier
`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
`time`	string	No	An ISO-8601 formatted timestamp of when the receipt was printed

OrderObject

These fields comprise the Order Object itself.

Field Name	Type	Required	Description
`_id`	string	No	The unique Order Object identifier
`origin`	string	No	The system that the order or notification originated from. This is set to `mobile` for orders that originate from the cloud. For orders and notifications that originate from the store, this is set to the store number. This is used internally by our system's processes to manage synchronization of orders and notifications between the cloud and the store.
`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, Post-adjusted, and Refunded
`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 and discounts) 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`	PrinterInfoArray	No	The list of print records
`order_type`	string	No	The order type. The available options include: Order, Refund, or Waste.
`reference_id`	string	No	The unique order identifier of the order being refunded
`comment`	string	No	The comments about the order
`suite_info`	SuiteInfoObject	No	The suite information
`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 identifier 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.
`order_source_ext`	object	No	The point from which the order originated
`order_source_id`	string	No	The identifier of the device from which the order originated
`name`	string	No	The order name
`is_marketplace`	boolean	No
`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
`refunds`	object	No	The refunds information. A separate object is created for each refunded item with the reference to the refunded order.
`order_item_id`	string	No	The order item identifier
`quantity`	number	No	The order quantity
`refund_order_reference_id`	string	No	The refund reference identifier
`day_part_info`	DayPartObject	No	Describes the Day Part during which the order was sent
`event`	EventObject	No	The Event Object information
`external_order_id`	string	No	The external order identifier
`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

SuiteInfoObject

Field Name	Type	Required	Description
`suite_id`	string	No	The unique suite identifier
`name`	string	No	The suite name
`short_name`	string	No	The suite short name

TableInfoObject

Field Name	Type	Required	Description
`table_id`	string	No	The unique table identifier
`table_number`	string	No	The table number
`table_name`	string	No	The table name

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

DayPartObject

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

Field Name

Type

Required

Description

day_part_type_id

string

The unique identifier (UID) of the Day Part Type. This field matches the entity_id of the Day Part Type stored in Data Management.

day_part_type_name

string

The name of the Day Part Type.

Examples: Morning, Afternoon, Evening

external_id

string

The external identifier used to reference the Day Part Type

EventObject

Field Name	Type	Required	Description
`id`	string	No	The unique event identifier
`name`	string	No	The event name
`event_type`	object	No	The event type
`entity_id`	string	No	The event type entity identifier
`external_id`	string	No	The external identifier used to reference the event type
`name`	string	No	The event type name

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 of the specified site
`company_id`	string	No	The unique identifier of the company at which the site resides

SiteStatusObject

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	The ISO-8601 formatted date-time stamp of last time the cloud made contact with the specified site
`business_date`	string	No	The business date of the specified site
`pos_type`	string	No	The type of point of sale (POS) at the site
`pos_version`	string	No	The version of the POS at the site
`server_timestamp`	string	No	The 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 of the request
`site_id`	string	No	The site identifier 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 identifier in question	string	No	This field can be one of the following: `entity_ids`, `order_discount_ids`,or `order_item_ids`. It signifies the identifier that is in question when trying to perform the specified operation. Example: `key:value pair: entity_ids: ['123456789','987654321']`

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

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`	FractionalQuantity	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

FractionalQuantity

These fields define a factional modifier quantity.

Field Name

Type

Required

Description

numerator

integer

The numerator of the fractional quantity.

Minimum: 1

denominator

integer

The denominator of the fractional quantity.

Minimum: 1

CompanyInfo

Our Portal provides this basic company information.

Field Name	Type	Required	Description
`id`	string	No	The company identifier stored in Portal API
`name`	string	No	The company name stored in Portal API

OrderItemReportingCategory

These fields describe the reporting categories of an order item.

Field Name	Type	Required	Description
`major_reporting_category`	ReportingCategory Object	No	The major reporting category information
`minor_reporting_category`	ReportingCategory Object	No	The minor reporting category information

OrderSourceInfo

The Order Source fields define the specific source where this order has been created. For example, "Delivery." Order sources differ from the Origin field, which is system definable, as opposed to Order Sources which are defined by integrators. For an example of the usage of the two entities, "Origin: In store" could be applicable for several order sources like "drive thru" and "dine in." Order Source is used in the our ecosystem heavily to filter and restrict certain items, menus, prices, and time periods for different ordering platforms.

Field Name

Type

Required

Description

name

string

The given name of the order source.

Examples: web, Terminal 47

order_source_ext

object

The object for order_source

order_source_id

string

The unique identifier (UID) for a particular order source

RefundReference

These fields provide reference information for a refund.

Field Name	Type	Required	Description
`order_item_id`	string	No	The refunded order item identifier
`quantity`	number	No	The refunded item quantity
`refund_order_reference_id`	string	No	The refunded order identifier (reference to created refund order)

ReportingCategory

These fields describe a reporting category.

Field Name	Type	Required	Description
`name`	string	No	The reporting category name
`entity_id`	string	No	The entity identifier of the reporting category

TaxJurisdiction

These fields identify the jurisdiction that imposes a particular tax.

Field Name	Type	Required	Description
`entity_id`	string	No	The jurisdiction identifier
`name`	string	No	The jurisdiction name
`jurisdiction_type`	string	No	The level of the jurisdiction
`external_id`	string	No	The unique external identifier of the TaxJurisdiction Object to which the tax is associated

TimeInfo

These fields record the time at which a particular event occurred.

Field Name	Type	Required	Description
`added`	string	No	The time for last addition of an item/reason to the collection
`created`	string	No	The created date-time in ISO8601 format
`checkedin`	string	No	The time that the customer of a mobile order has checked in at the restaurant or that the order was sent to kitchen to be prepared
`closed`	string	No	The closed time for the item or reason
`first_saved`	string	No	The first saved (totaled, sent to kitchen) time for order
`first_item_added`	string	No	The time that an item of any type was first added to order
`first_split`	string	No	The time when the first item from some other order was added during a split operation
`kitchen_sent`	string	No	The sent date-time to kitchen in ISO8601 format
`kitchen_bump`	string	No	The time that the order was completed by the kitchen (bumped)
`last_modified`	string	No	The last modified date-time in ISO8601 format

AddRefundOrderPaymentRequestBody

Field Name	Type	Required	Description
`payments`	payments Array	Yes	The list of the payment information for the refund

payments Array

Field Name	Type	Required	Description
`account`	string	No	The payment account identifier (ID)
`amount`	number	Yes	The payment amount
`card_brand_name`	string	No	The card brand name
`code`	string	No	The payment code
`notes`	string	No	A free text field to include notes about the payment
`pay_type_id`	string	Yes	The payment type ID
`pay_type_name`	string	No	The payment type name
`refund_reference_id`	string	Yes	The original order ID
`terminal_id`	string	No	The ID of the terminal where the payment was processed
`tip_amount`	number	No	The amount of the tip included in the payment
`transaction_id`	string	No	The host reference transaction ID

Sample Request Body

{
    "payments": [
        {
            "account": "**************4817",
            "amount": 33,
            "tip_amount": 0,
            "payment_id": "8c891f9c-5841-4b2b-9e30-c606f228d0d8",
            "pay_type_id": "02",
            "pay_type_name": "Credit Card",
            "code": "CREDIT",
            "card_brand_name": "Discover",
            "transaction_id": "4839847396",
            "refund_reference_id": "{{order_id1}}",
            "notes": "test"
        }
    ]
}

AddOrderDiscountsRequestBody

To add discounts at the order_level use the following structure:

Field Name

Type

Required

Description

discounts

array

discount Object

Yes

The list of discounts to be applied to the order

discount Object

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
`loyalty_info`	loyalty_info Object	Yes	The loyalty information of a customer added to the order
`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.

Sample Request Body

{
    
    "discounts": [
        {
            "discount_code": "defaultLoyaltyItemLevelDiscount",
            "discount_variable_value": 4.2,
            "loyalty_info": {
                "amount": 2,
                "apply_automatically": false,
                "quantity_redeemed": 1,
                "reward_id": "B67543",
                "reward_type": "reward",
                "status": "validated"
            },
            "name": "Dname",
            "order_item_ids": [
                "dbdc0ece-12ab-34cd-56ef-2009023f6342"
            ],
            "quantity": 3
        }
    ],
}

loyalty_info Object for Discounts

Field Name	Type	Required	Description
`apply_automatically`	boolean	Yes	The flag that indicates if the discount should be applied to the order automatically
`quantity_redeemed`	number	Yes	The loyalty discount quantity
`reward_id`	string	Yes	The loyalty discount identifier (ID)
`reward_type`	string	Yes	The loyalty Object discount type
`status`	string	Yes	The loyalty discount status, which should be validated when the order is unpaid, redeemed, and fully paid
`code`	string	No	The loyalty Object discount code
`program_id`	string	No	The loyalty discount program ID
`amount`	number	Yes	The loyalty discount amount

order_item Object

Field Name	Type	Required	Description
`entity_id`	string	Yes*	The entity identifier (ID) of the item. *One of the following is required for the request: `entity_id` `item_type` `product_id` `donation_id`
`item_type`	string	Yes*	The reference code for the discount. *One of the following is required for the request: `entity_id` `item_type` `product_id` `donation_id` If this field is included the request should also include `mix_type`.
`name`	string	No	The name of the item
`product_id`	string	Yes*	The product ID related to the item. *One of the following is required for the request: `entity_id` `item_type` `product_id` `donation_id`
`donation_id`	string	Yes*	The donation ID of the order. *One of the following is required for the request: `entity_id` `item_type` `product_id` `donation_id`
`order_items_ids`	array	No	The list of order item IDs to add a discount to. It should be provided only if items exist.
`quantity`	integer	No	The quantity of the item included
`fractional_quantity`	fractional_quantity Object	No	The increment values for the quantity of the item
`unit_price`	number	No	The unit price of the item
`child_items`	array (order_item)	No	The list of the child items of the parent item
`discount_info`	discount Object	No	The discount applied to the specified product. To add discounts at the `item_level`, include this field.
`comment`	string	No	The comment added for the item
`apply_as`	string	No	How the `price` value should be applied to the order: `fixed` - The amount is added as a fixed currency. `round-up` - The amount is calculated as a percentage of the total amount of the order.
`fee_config`	FeeConfigRequestBody	No	The fee configuration for the item
`build_type`	string	No	Examples: plain, replace, augment

Sample Request Body

{
    "items": [
        {
            "discount_info": {
                "discounts": [
                    {
                        "discount_code": "123456",
                        "discount_variable_value": 3
                    }
                ]
            },
            "product_id": "234567",
            "quantity": 1
        },
        {
            "child_items": [
                {
                    "product_id": "456789",
                    "quantity": 1
                },
                {
                    "product_id": "124578",
                    "quantity": 1
                }
            ],
            "discount_info": {
                "discounts": [
                    {
                        "discount_code": "986532",
                        "discount_variable_value": 3.29
                    }
                ]
            },
            "product_id": "258963",
            "quantity": 1
        }
    ],
    "reference_id": "1111",
    "store_number": "258",
    "terminal": {
        "id": "9"
    }
}

fractional_quantity Object

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.

Error Responses

The following table defines the error responses returned by Online Ordering:

Code	Details
-1	Message Failed to get Order Destinations Description Online Ordering 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_NAME`should 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 Online Ordering 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 Online Ordering 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" } }