Online Ordering Order

Methods

Create Order

This endpoint is used to place an order and be sure that the POS is Online.

This endpoint accepts these statuses: "ANTICIPATED", "READY_FOR_CONFIRMATION"

POST /online-ordering/v3/{locationId}/orders

Request Body (required)

Content-Type: application/json

{
  "appRef": "string",
  "orderNumber": "string",
  "status": "string",
  "placedAt": "string",
  "expectedAt": "string",
  "fulfillmentType": "string",
  "deliveryInfo": "<OrderDeliveryInfo>",
  "pickupInfo": "<OrderPickupInfo>",
  "dineInInfo": "<OrderDineInInfo>",
  "payments": ["<OrderPayment>"],
  "paymentTotal": "integer",
  "surcharges": ["<OrderSurcharge>"],
  "surchargeTotal": "integer",
  "taxes": ["<OrderTax>"],
  "taxTotal": "integer",
  "tipTotal": "integer",
  "grandTotal": "integer",
  "lineItems": ["<OrderLineItem>"],
  "metadata": ["<OrderMetadata>"],
  "attributes": "<OrderAttributes>",
}

Response 200 - POS is online and order successfully created.

Response Body

Content-Type: application/json

{
  "id": "<Created order identifier>"
}

Response 504 - POS is offline and 3rd-party should do a retry action or contact a Restaurant to know the "offline" reason.

Retrieve Order

Retrieve an Online Order V3 details by order id

GET /online-ordering/v3/{locationId}/orders/{id}

Response 200 - Returns an online order V3 object

{
  "id": "string",
  "appRef": "string",
  "orderNumber": "string",
  "status": "string",
  "placedAt": "string",
  "expectedAt": "string",
  "estimatedAt": "string",
  "fulfillmentType": "string",
  "deliveryInfo": "<OrderDeliveryInfo>",
  "pickupInfo": "<OrderPickupInfo>",
  "dineInInfo": "<OrderDineInInfo>",
  "payments": ["<OrderPayment>"],
  "paymentTotal": "integer",
  "surcharges": ["<OrderSurcharge>"],
  "surchargeTotal": "integer",
  "statusHistory": ["<OrderStatusHistoryEntry>"],
  "taxes": ["<OrderTax>"],
  "taxTotal": "integer",
  "tipTotal": "integer",
  "grandTotal": "integer",
  "lineItems": ["<OrderLineItem>"],
  "metadata": ["<OrderMetadata>"],
  "attributes": "<OrderAttributes>",
}

Update Order Status

This endpoint is used to update an order status.

The endpoint accepts only these statuses: "READY_FOR_CONFIRMATION", "CANCELLED", "REJECTED". Reason required with "REJECTED" or "CANCELLED" status.

POST /online-ordering/v3/{locationId}/orders/{id}/status

Response 204 - Request was successfully accepted

{
  "status": "string",
  "reason": {
    "code": "string",
    "explanation": "string"
  }
}

Update Order Attributes

This endpoint is used to update an order attributes.

Endpoint accepts attributes payload with at least one of the following properties: "vechicle", "pickupLocation", "table".

PUT /online-ordering/v3/{locationId}/orders/{id}/attributes

Response 204 - Request was successfully accepted

{
  "vechicle": "string",
  "pickupLocation": "string",
  "table": "string"
}

Definitions

Online Order V3

The order model is the basis for all POS orders. This contains all necessary information for fulfilling and processing orders.

Name Type Description
appRef* string The 3rd-party globally unique identity of the order. This is the primary and only guaranteed unique identity.
orderNumber* string A more human-readable order number to show to the customer, restaurant and drivers. This is not guaranteed to be unique forever and is thus not used as a true identifier from an API perspective.
status* string The current state of the order:
  • UNKNOWN
  • ANTICIPATED
  • READY_FOR_CONFIRMATION
  • CONFIRMED
  • REJECTED
  • CANCELLED
  • READY_FOR_PICKUP
  • OUT_FOR_DELIVERY
  • FULFILLED
  • FULFILLMENT_FAILED
  • VOIDED
  • REFUNDED
orderTypeRef string The order type reference. This corresponds to the order type guid in the POS.
placedAt* string The time that the diner placed the order. Only UTC is accepted.
expectedAt* string The time that the food should be delivered or in the case of a pickup order, ready for pickup. Only UTC is accepted.
estimatedAt string Nullable, available only after successful order confirmation and depends on FulfillmentType:

DELIVERY - The time that the delivery is estimated by the restaurant to occur. Only UTC is accepted.
PICKUP - The time that the diner was told that their food would be available for pickup. Only UTC is accepted.
DINE_IN - The time that the diner was told that their food would be available for dine-in. Only UTC is accepted.
fulfillmentType* string
  • DELIVERY
  • PICKUP
  • DINE_IN - Supported only by a specific POS version.
  • CURBSIDE
deliveryInfo object Information on how to deliver the order to the diner.
pickupInfo object Information about the pickup of the order including basic diner information.
dineInInfo object Information about the pickup of the dine in order including basic diner information.
curbsideInfo object Information about the curbside of the order.
payments* array Individual payments for the order, this will also include adjustments.
paymentTotal* integer Initial total for an order in US Cents.
surcharges* array Individual charges in US Cents.
surchargeTotal* integer Total surcharges of all line items in US Cents.
taxes* array Any taxes applied to the order.
taxTotal* integer Total tax paid.
tipTotal* integer The sum total of all the tips on the order.
grandTotal* integer The total fees for the order in US Cents.
lineItems* array List of line items ordered by the diner.
metadata array List of additional information related to Order.
isDeferred boolean Indicates whether the order is deferred or not.
deferredUntil string The time until which the order is deferred. Only UTC is accepted and the value is required if isDeferred is true.
inclusiveTaxCalculation string The party expected to calculate inclusive tax. Defaults to PROVIDER.
attributes object A set of fields that can be added by 3rd party after order has been confirmed.
discounts array List of discounts applied to the order.
discountTotal integer The total discount amount in US Cents.

Order Delivery Info

Information on how to deliver the order to the diner.

Name Type Description
address* object The address to deliver to.
instructions string Special instructions for delivery.
contactInfo* object Contact information for the diner.
deliveryType string Delivery Type
hasAgeRestrictedItems boolean True/False based on the content of the order. The purpose of this field in the payload is to support alcohol/tobacco that have an ID requirement in a manner that supports confidence and growth. Default value false will be sent always.
isContactless boolean Determines the preferred way of how this order should be delivered. Defaults to false value.
deliveryServiceData object Required if "deliveryType" is a "DELIVERY_SERVICE", provides the information that is needed for DSP.

Order Delivery Address

The address to deliver to.

Name Type Description
line1* string First address line.
line2 string Optional second address line.
city* string The city.
state* string The state as a two letter abbreviation.
country string The country as a two letter abbreviation.
crossStreet string -
postalCode* string The zip code. This is a string because it may in certain cases contain a +4 zip.
latitude number The geolocated addresses latitude.
longitude number The geolocated addresses longitude.
instructions string Any special instructions having to do with the delivery address. This might include the closest major cross streets as entered by the diner, etc.

Order Contact Info

Contact information for the diner.

Name Type Description
name* string Name of the diner.
phone* string Phone number of the diner.
Note: For DELIVERY_SERVICE orders the phone number should follow the E.164 format rule, example: +442071838750.
email string Email of the diner.

Order Delivery Service Data

Required if "deliveryType" is a "DELIVERY_SERVICE", provides the information that is needed for DSP.

Name Type Description
deliveryId string Delivery service order reference ID.
preferredQuoteId string Specifies the preferred DSP quote to be used for this delivery order. If not specified or preferred quote was rejected, the system will determine the best available DSP for this delivery. In the case there are no available DSPs at the order confirmation process, this order will be rejected within a proper reason.
expectedPickupAt* string The time that is expected to be prepared by the kitchen.

Order Pickup Info

Information about the pickup of the order including basic diner information.

Name Type Description
instructions string Special instructions for pickup.
contactInfo* object Contact information for the diner.

Order Dine In Info

Information about the pickup of the dine in order including basic diner information.

Name Type Description
instructions string Special guest instructions for "dine-in".
Expected format: (important POSi is parsing this format to extract the ${TableNotes} information
Table: ${TableNotes}, Special Instructions: ${Instructions}
contactInfo* object Contact information for the diner.

Order Curbside Info

Information about the curbside of the order.

Name Type Description
location string Vehicle’s location in parking lot
description* string Description of car (color, model, license plate and etc)
contactInfo* object Contact information for the diner.

Order Payment

Payments on the order.

Name Type Description
type* string The payment type. Note all non-CASH payment types should be treated as pre-paid tender or house account in the POS. Values:
  • NON_CASH - Non cash payment
  • GATEWAY - Gateway payment
amount* integer The payment amount in US Cents. Tips are included in this amount.
tipAmount* integer The tip amount in US Cents. Those tips are included in the payment amount.
gatewayData object Gateway payment data.

Gateway Payment Data

Gateway payment data.

Name Type Description
card* object -
transaction* object -
universalToken string An identifier for a card or payment account across all Shift4 Payments merchants.

Gateway Payment Card Details

Name Type Description
type* string An abbreviation used to specify the type of card that was used when processing a transaction.
last4Digits* string Last 4 digits of a card number.
expirationDate string Card expiration date.
holderName string Name on the card.
token* string This field is used to specify a card token.

Gateway Payment Transaction Details

Name Type Description
authorizationCode string The transaction authorization code provided by the consumer's issuing bank. It is provided in a response if an online authorization or sale request is approved.
invoice* string An invoice number serves as a unique key that identifies a transaction within a batch in Shift4 Payments' Gateway.

Order Surcharge

Base fees paid by the diner for the line items and delivery charges.

Name Type Description
name* string Surcharge Name like: Delivery, etc.
amount* integer The surcharge amount in US Cents.

Order Tax

Taxes paid by the diner.

Name Type Description
name* string Tax Name, like: Sales, Delivery, Restaurant
amount* integer The tax amount in US Cents.
isRemitted boolean Indicates whether the tax has been remitted.

Order Line Item

The order lines items for this portion of the order.

Name Type Description
itemRef* string The Online Menu Item reference.
name* string The name of the line item.
description string A description of the line item.
instructions string Free form text special instructions added by the diner.
price* integer The unit base price in US Cents of an item without adding in the price of any modifiers.
total* integer The unit total cost in US Cents of this item base price and modifiers.
quantity* integer The quantity ordered of this item.
lineModifierSets* array List of line items ordered by the diner.

Order Line Modifier Set

A grouping of items that can be selected as part of the purchase of a parent item/modifier, allowing the user to customize the item by making choices or bundling extras with their order.

Name Type Description
modifierSetRef* string The reference of the Online Menu Modifier Set.
name* string The name of this modifier set.
lineModifiers* array The options selected.

Order Line Modifier

The options selected for the specific item.

Name Type Description
modifierRef* string The Online Menu Modifier reference.
price* integer The unit price of this line modifier in US Cents without adding in the price of any sub-modifiers.
name* string The name of this option.
total* integer The unit price of this line option including modifier sub-modifiers.
quantity* integer The quantity ordered of this option.
lineModifierSets* array Any modifier sets for this item.

Order Metadata

Name Type Description
name* string A name of the specific Metadata item.
type* string ENUM of supported types:
  • STRING
  • BOOLEAN
value* string A value of the specific Metadata item.

Order attributes

A set of fields that can be added by 3rd party after order has been confirmed.

Name Type Description
vehicle string Type of vehicle.
pickupLocation string Pickup location.
table string Table identifier.

Online Order V3 Discount

Discount applied to an online order V3.

Name Type Description
name* string Discount name.
amount* integer Discount amount in US Cents.

results matching ""

    No results matching ""