Orders V3

The Orders V3 API provides enhanced order management with additional fulfillment capabilities and improved status tracking.

Overview

V3 introduces expanded order lifecycle management with new statuses for voids, refunds, and failures. Support for deferred orders, auto-fulfillment, and post-confirmation attribute updates.

API Endpoints

Create Order

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

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

Accepted Statuses:

• ANTICIPATED
• READY_FOR_CONFIRMATION

Request Body (required)

Content-Type: application/json

{
  "appRef": "string",
  "orderNumber": "string",
  "status": "string",
  "placedAt": "string",
  "expectedAt": "string",
  "autoFulfillAfter": "integer",
  "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>"
}

Responses:

• 200 - POS is online and order successfully created.

Response Body:

Content-Type: application/json

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

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

Retrieve Order

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

Retrieve an Online Order V3 details by order id.

Response: 200 - Returns an online order V3 object

{
  "id": "string",
  "appRef": "string",
  "orderNumber": "string",
  "status": "string",
  "placedAt": "string",
  "expectedAt": "string",
  "estimatedAt": "string",
  "autoFulfillAfter": "integer",
  "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

POST /online-ordering/v3/{locationId}/orders/{id}/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.

Request Body:

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

Response: 204 - Request was successfully accepted

Update Order Attributes

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

This endpoint is used to update an order attributes.

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

Request Body:

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

Response: 204 - Request was successfully accepted

Order Status Values

The V3 API supports 13 distinct order statuses:

Data Models

Core Order Fields

Fulfillment Types

DELIVERY

• Requires delivery address and contact information
• Supports delivery service integration
• Includes delivery-specific fields (estimated time, instructions)

PICKUP

• Includes special instructions and diner contact info
• Supports curbside-specific attributes (vehicle, pickup location)

DINE_IN

• Includes table information
• Supports special instructions

CURBSIDE

• Extension of PICKUP type
• Requires vehicle description and parking location
• Supports post-confirmation attribute updates

Order Attributes (Post-Confirmation)

Metadata

Custom key-value pairs for additional order data:

• STRING type - text values
• BOOLEAN type - true/false flags

Each metadata entry contains:

• name - Key identifier
• value - Data value

Differences from V2

Key Changes

1. Order ID in Response: V3 returns order ID in 200 response (V2 returned 204)
2. Status Endpoint: Separate POST endpoint for status updates
3. Attributes Endpoint: New PUT endpoint for post-confirmation customization
4. Additional Statuses: UNKNOWN, PLACEMENT_FAILED, FULFILLMENT_FAILED, VOIDED, REFUNDED
5. Deferred Orders: New isDeferred and deferredUntil fields
6. Auto-Fulfillment: New autoFulfillAfter field for automatic status transitions
7. Discount Tracking: New discountTotal field
8. Enhanced Delivery: More detailed delivery service integration
9. Metadata Support: Extensible custom data fields
10. Field Naming: Uses ref instead of guid for references

Validation Rules

• Timestamps: Only UTC format accepted
• Currency: All amounts in US cents (integers)
• Phone Numbers: E.164 format required for delivery services
• Attributes Update: Order must be confirmed before attribute updates
• Reason Requirement: Mandatory for REJECTED/CANCELLED status transitions
• Deferred Orders: deferredUntil required when isDeferred=true