Order Schema

This document describes the order data structure used when submitting orders to OneTablet.

Order Object

The complete order structure when calling the Submit Order API:

interface Order {
  // Identification
  id: string;                              // Your unique order ID
  store_order_cart_id: string;             // Cart reference ID
  delivery_short_code: string;             // Human-readable order reference (e.g., "ABC123")

  // Store Information
  store: {
    merchant_supplied_id: string;          // Store ID
    provider_type: string;                 // Your platform identifier
    timezone: string;                      // Store timezone (e.g., "America/New_York")
    store_business: {
      auto_release_enabled: boolean;       // Whether to auto-release to courier
    };
  };

  // Order Source
  experience: Experience;                  // Platform source identifier
  commission_type: CommissionType;         // Commission structure
  is_demand_gen?: boolean;                 // Demand generation order flag

  // Customer Information
  consumer: Consumer;

  // Order Items
  categories: OrderMenuCategory[];         // Items grouped by menu category

  // Special Instructions
  order_special_instructions: string;      // General order notes from customer

  // Pricing (all amounts in cents)
  subtotal: number;                        // Items total before tax
  tax: number;                             // Tax amount
  merchant_tip_amount: number;             // Tip amount for merchant

  // Fulfillment
  is_pickup: boolean;                      // true = pickup, false = delivery
  estimated_pickup_time: string;           // ISO 8601 timestamp for when order should be ready
  fulfillment_type: FulfillmentType;       // How the order will be fulfilled
  delivery_address?: DeliveryAddress;      // Required for delivery orders
  delivery_fee?: number;                   // Delivery fee in cents (if applicable)

  // Tax Remittance
  is_tax_remitted_by_platform: boolean;    // Whether platform remits tax on behalf of merchant
  tax_amount_remitted_by_platform: number; // Tax amount remitted by platform (cents)
  tax_transaction_id: string;              // Tax transaction reference ID

  // Tax Calculation Details (optional)
  subtotal_for_tax?: number;               // Taxable subtotal factoring in discounts and funding source
  subtotal_discount_funding_source?: string; // Who funds the discount: "platform" or "merchant"

  // Promotions
  applied_discounts?: AppliedDiscount[];   // Applied promotional discounts
}

Enums

Experience

Identifies the ordering platform source:

enum Experience {
  DOORDASH = "DOORDASH",
  CAVIAR = "CAVIAR",
  STOREFRONT = "STOREFRONT",
  WHITE_LABELED = "WHITE_LABELED",
  // Additional values may be assigned during integration
}

FulfillmentType

enum FulfillmentType {
  pickup = "pickup",              // Customer picks up at restaurant
  dx_delivery = "dx_delivery",    // Platform-managed delivery
  mx_fleet_delivery = "mx_fleet_delivery"  // Merchant-managed delivery
}

CommissionType

enum CommissionType {
  regular = "regular",     // Standard commission rate
  dashpass = "dashpass"    // Subscription-based reduced commission
}

Consumer

interface Consumer {
  id: number;              // Customer ID from your platform
  email: string;           // Customer email
  first_name: string;      // Customer first name
  last_name: string;       // Customer last name
  phone: string;           // Customer phone number
}

Items are grouped by their menu category:

interface OrderMenuCategory {
  name: string;                    // Category name
  merchant_supplied_id: string;    // Category ID from menu
  items: OrderItem[];              // Items ordered from this category
}

Order Item

interface OrderItem {
  name: string;                    // Item name
  merchant_supplied_id: string;    // Item ID from menu
  price: number;                   // Total price including modifiers (cents)
  quantity: number;                // Quantity ordered
  consumer_name: string;           // Customer name (used for group orders)
  special_instructions: string;    // Item-specific notes from customer
  extras: OrderItemExtra[];        // Selected modifier groups
}

Order Item Extra (Modifier Group)

interface OrderItemExtra {
  name: string;                    // Modifier group name
  merchant_supplied_id: string;    // Modifier group ID from menu
  options: OrderItemExtraOption[]; // Selected options within this group
}

Order Item Extra Option (Modifier)

interface OrderItemExtraOption {
  name: string;                    // Modifier option name
  merchant_supplied_id: string;    // Modifier option ID from menu
  price: number;                   // Modifier price (cents)
  quantity: number;                // Quantity selected
  extras: OrderItemExtra[];        // Nested modifier groups (for multi-level modifiers)
}

Delivery Address

Required for delivery orders (is_pickup: false):

interface DeliveryAddress {
  street?: string;                 // Street address
  city?: string;                   // City
  state?: string;                  // State/Province
  zip_code?: string;               // Postal code
  country_code?: string;           // Country code
  subpremise?: string;             // Apartment/Suite number
  lat?: string;                    // Latitude (string format)
  lng?: string;                    // Longitude (string format)
  address_instructions?: string;   // Delivery instructions
}

Applied Discount

Details about promotional discounts applied to the order:

interface AppliedDiscount {
  discount_amount: number;         // Discount value in cents
  promo_id: string;                // Platform promotional campaign ID
  promo_code?: string;             // Promo code entered by customer (if any)
  external_campaign_id: string;    // Campaign reference ID as defined by merchant
}

Example Order

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "store_order_cart_id": "cart-abc123",
  "delivery_short_code": "ABC123",
  "store": {
    "merchant_supplied_id": "store-123",
    "provider_type": "your_platform",
    "timezone": "America/New_York",
    "store_business": {
      "auto_release_enabled": true
    }
  },
  "experience": "DOORDASH",
  "commission_type": "regular",
  "consumer": {
    "id": 12345,
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+15551234567"
  },
  "categories": [
    {
      "merchant_supplied_id": "cat-appetizers",
      "name": "Appetizers",
      "items": [
        {
          "merchant_supplied_id": "item-wings-001",
          "name": "Buffalo Wings",
          "quantity": 1,
          "price": 1299,
          "consumer_name": "John Doe",
          "special_instructions": "Extra crispy please",
          "extras": [
            {
              "merchant_supplied_id": "mod-sauce",
              "name": "Choose Sauce",
              "options": [
                {
                  "merchant_supplied_id": "opt-buffalo",
                  "name": "Buffalo",
                  "price": 0,
                  "quantity": 1,
                  "extras": []
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "order_special_instructions": "Ring doorbell, do not knock",
  "subtotal": 1299,
  "tax": 117,
  "merchant_tip_amount": 300,
  "is_pickup": false,
  "estimated_pickup_time": "2024-01-15T18:30:00Z",
  "fulfillment_type": "dx_delivery",
  "delivery_address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip_code": "10001",
    "lat": "40.7128",
    "lng": "-74.0060",
    "address_instructions": "Apt 4B, buzz 42"
  },
  "delivery_fee": 299,
  "is_tax_remitted_by_platform": false,
  "tax_amount_remitted_by_platform": 0,
  "tax_transaction_id": "tax-txn-abc123",
  "applied_discounts": []
}

Field Notes

Pricing

All monetary values are in cents (e.g., 1299 = $12.99).

Item Price

The price field on OrderItem represents the total price for one unit of that item including all selected modifiers. To calculate the base item price, subtract the sum of modifier prices.

Group Orders

For group orders where multiple people are ordering together, each item's consumer_name field identifies which person ordered that item. When there's only one consumer, this field typically contains the primary customer's name.

Tax Remittance

is_tax_remitted_by_platform: When true, the platform collects and remits sales tax on behalf of the merchant (common in Marketplace Facilitator states)
tax_amount_remitted_by_platform: The portion of tax that the platform remits (in cents)
The merchant is responsible for: tax - tax_amount_remitted_by_platform

Fulfillment Types

Type	Description
`pickup`	Customer picks up order at the restaurant
`dx_delivery`	Platform-managed delivery (e.g., DoorDash drivers)
`mx_fleet_delivery`	Merchant manages their own delivery fleet

Nested Modifiers

Modifiers can be nested to support complex customization. For example, a pizza might have a "Toppings" modifier group, where each topping option has its own "Half/Whole" modifier group.

Order Object​

Enums​

Experience​

FulfillmentType​

CommissionType​

Consumer​

Order Menu Category​

Order Item​

Order Item Extra (Modifier Group)​

Order Item Extra Option (Modifier)​

Delivery Address​

Applied Discount​

Example Order​

Field Notes​

Pricing​

Item Price​

Group Orders​

Tax Remittance​

Fulfillment Types​

Nested Modifiers​