Skip to main content

Order Schema

This document describes the Order object structure used throughout the API.

Order Object​

type Order = {
  id: string;                              // Unique order identifier (UUID)
  status: OrderStatus;                     // Current order status
  deliveryStatus?: DeliveryStatus;         // Delivery progress (delivery orders only)
  createdAt: string;                       // ISO 8601 timestamp when order was created
  updatedAt: string;                       // ISO 8601 timestamp of last update
  cancellation?: Cancellation;             // Present when order is cancelled
  store: Store;                            // Store information
  details: OrderDetails;                   // Detailed order information
  rawPlatformFinancials?: RawPlatformFinancials; // Raw financial data from ordering platform
};

type OrderStatus = 'new' | 'future' | 'rejected' | 'cancelled' | 'ready' | 'finished';

type DeliveryStatus =
  | 'ASSIGNED'                    // Courier assigned to order
  | 'EN_ROUTE_TO_STORE_LOCATION'  // Courier traveling to restaurant
  | 'EN_ROUTE_TO_CUSTOMER'        // Courier traveling to customer
  | 'COMPLETED'                   // Delivery completed
  | 'CANCELED';                   // Delivery cancelled

Order Details​

The details field contains comprehensive information about the order:

type OrderDetails = {
  // Identification
  externalId: string;                 // External platform order ID
  externalReadableOrderNum?: string;  // Human readable order number (platform-specific)
  source?: string;                    // Integration identifier (e.g. "doordash@1.13.1")

  // Timing
  placedAt: string;                   // ISO timestamp when order was placed
  estimatedPickupAt?: string;         // ISO timestamp for estimated pickup/ready time

  // Order Type
  isPickup: boolean;                  // true = pickup, false = delivery

  // Customer Information
  consumer: Consumer;                 // Primary customer
  consumers: Consumer[];              // All customers (for group orders)
  isGroupOrder: boolean;              // Whether multiple customers are involved

  // Notes
  note: string;                       // General order notes/special instructions
  deliveryNote: string;               // Delivery-specific instructions

  // Delivery
  isMerchantDelivery: boolean;        // true = restaurant handles delivery
  deliveryAddress?: DeliveryAddress;  // Delivery location (delivery orders only)
  courier?: Courier;                  // Courier details (third-party delivery)

  // Financials (all amounts in cents)
  total: number;                      // Final order total
  subtotal: number;                   // Items total before tax/fees
  tax: number;                        // Tax amount
  tip: number;                        // Tip amount
  deliveryFee: number;                // Delivery fee
  utensils?: boolean;                 // Whether utensils were requested

  // Items
  items: OrderItem[];                 // Line items

  // Promotions
  promotions?: OrderPromotion[];      // Applied promotions/discounts
};

Consumer​

type Consumer = {
  id?: string;                   // Consumer ID (if available)
  name: string;                  // Customer name
  email?: string;                // Customer email
  phone?: string;                // Contact phone (may be masked)
  code?: string;                 // Code for masked phone numbers
};

Delivery Address​

type DeliveryAddress = {
  googlePlaceId?: string;        // Google Maps place ID
  lat?: number;                  // Latitude coordinate
  lng?: number;                  // Longitude coordinate
  label: string;                 // Address label/name
  raw: string;                   // Full address string
};
Delivery Address Guidance

For highest accuracy, use the raw field as the source of truth and perform your own geocoding. The lat and lng fields are provided for convenience but may not always be present or reliable across all ordering platforms.

Courier​

type Courier = {
  name?: string;                 // Courier's name
  phone?: string;                // Courier's contact phone (may be masked)
  code?: string;                 // Code for masked phone numbers
};

Store​

type Store = {
  id: string;                    // Internal store identifier
  externalId?: string;           // Platform's store identifier
  location?: string;             // Store location name
  brand?: string;                // Brand name
  platform: string;              // Ordering platform (e.g., "doordash", "ubereats")
};

Order Item​

type OrderItem = {
  id: string;                    // Item identifier
  sku?: string;                  // SKU when available
  name: string;                  // Item name
  quantity: number;              // Quantity ordered
  price: ItemPrice;              // Price breakdown
  note?: string;                 // Item-specific notes
  modifiers: OrderItemModifier[]; // Item modifiers/add-ons
};

type ItemPrice = {
  total: number;                 // Total price (qty * unit) in cents
  unit: number;                  // Unit price including modifiers in cents
  base: number;                  // Base price without modifiers in cents
  menu: number;                  // Menu price in cents
};

Order Item Modifier​

type OrderItemModifier = {
  id: string;                    // Modifier identifier
  sku?: string;                  // SKU when available
  name: string;                  // Modifier name
  quantity: number;              // Quantity
  price: ItemPrice;              // Price breakdown
  modifierGroup?: {              // Parent modifier group
    id: string;
    name: string;
  };
  modifiers?: OrderItemModifier[]; // Nested modifiers (recursive)
};

Order Promotion​

type OrderPromotion = {
  name?: string;                 // Promotion name
  discountValue?: number;        // Discount amount in cents
  discountPercentage?: number;   // Discount as percentage (e.g., 40 for 40%)
};

To calculate the total discount amount, sum the discountValue from each promotion in the array.

Cancellation​

type Cancellation = {
  by: 'platform' | 'merchant' | 'system';  // Who initiated cancellation
  reason: string;                           // Cancellation reason
  at: string;                               // ISO 8601 timestamp
};

Raw Platform Financials​

The rawPlatformFinancials field provides detailed financial data extracted directly from the ordering platform. This is useful for reconciliation, accounting, and understanding platform-specific charges.

type RawPlatformFinancials = {
  totals: {
    subtotal: number;                    // Pre-tax line items total (cents)
    total: number | null;                // Order total including tax
    grandTotal: number | null;           // Platform grand total
    merchantTotal: number | null;        // Amount merchant receives
    dinerGrandTotal: number | null;      // Customer total (GrubHub)
    adjustedGrandTotal: number | null;   // After modifications
    subtotalBeforeCoupons: number | null; // Before discounts
  };

  taxes: {
    total: number;                       // Total tax amount (cents)
    sales: number | null;                // Sales tax portion
    delivery: number | null;             // Delivery fee tax
    restaurant: number | null;           // Restaurant tax portion
    merchantTotal: number | null;        // Merchant total tax
    merchantSalesTotal: number | null;   // Merchant sales tax
    taxSource: string | null;            // Tax calculation source
  };

  taxRemittance: {
    isTaxRemittedByPlatform: boolean;    // Whether platform remits tax
    taxRemittedByPlatform: number | null; // Amount remitted by platform
    platformTaxRemittance: MoneyBreakdown[] | null;
    restaurantTaxRemittance: MoneyBreakdown[] | null;
    courierTaxRemittance: MoneyBreakdown[] | null;
    eaterTaxRemittance: MoneyBreakdown[] | null;
  } | null;

  tip: {
    amount: number | null;               // Tip amount (cents)
    type: string | null;                 // CASH, INCLUDE_IN_BILL, PREPAID
  } | null;

  fees: {
    total: number | null;                // Total fees
    delivery: number | null;             // Delivery fee (cents)
    deliveryTax: number | null;          // Tax on delivery fee
    smallOrder: number | null;           // Small order fee
    smallOrderTax: number | null;        // Tax on small order fee
    totalFeeTax: number | null;          // Tax on total fees
    bagFee: number | null;               // Bag/packaging fee
    pickAndPackFee: number | null;       // Pick and pack fee
  } | null;

  payments: {
    total: number | null;                // Total payment amount
    adjustedTotal: number | null;        // Adjusted after modifications
    paymentMethods: PaymentMethod[] | null;
  } | null;

  promotions: {
    appliedDiscounts: AppliedDiscount[] | null;
    loyaltyRewards: LoyaltyRewards | null;
    coupons: Coupon[] | null;
    platformPromotions: PlatformPromotion[] | null;
    totalPromoApplied: number | null;
    subtotalPromoApplied: number | null;
    taxPromoApplied: number | null;
  } | null;

  platformMetadata: {
    commissionType: string | null;       // "regular" or "dashpass"
    isDemandGen: boolean | null;         // Demand generation order
    subtotalForTax: number | null;       // Taxable subtotal
    subtotalDiscountFundingSource: string | null;
    storeOrderCartId: string | null;     // Platform cart ID
    taxWithheld: boolean | null;         // Tax remitted by platform
    restaurantSubtotal: number | null;   // Restaurant subtotal
    currencyCode: string | null;         // Currency code (e.g., "USD")
  } | null;
};

type MoneyBreakdown = {
  amount: number;                        // Amount in cents
  currencyCode: string;                  // Currency code
};

type PaymentMethod = {
  paymentType: string;                   // CREDIT_CARD, CASH, SUBSCRIPTION, etc.
  amount: number;                        // Amount in cents
  taxApplication: string | null;         // POST_TAX or PRE_TAX
  paymentSource: string | null;          // DINER, MERCHANT, platform name
};

type AppliedDiscount = {
  discountAmount: number;                // Discount amount (cents)
  promoId: string | null;                // Platform promo ID
  promoCode: string | null;              // Promo code used
  externalCampaignId: string | null;     // External campaign ID
};

type LoyaltyRewards = {
  rewards: unknown[];                    // Reward details
  rewardsTotal: number;                  // Total rewards value (cents)
};

type Coupon = {
  text: string;                          // Coupon description
  amount: number;                        // Coupon value (cents)
};

type PlatformPromotion = {
  promoType: string;                     // BOGO, FLATOFF, PERCENTOFF, etc.
  promotionUuid: string | null;          // Platform promotion UUID
  externalPromotionId: string | null;    // External promotion ID
  promoDiscountValue: number;            // Discount value (cents)
  promoDiscountPercentage: number | null; // Discount percentage
  promoDeliveryFeeValue: number | null;  // Delivery fee discount
  discountItems: DiscountItem[] | null;
  fundingSplits: FundingSplit[] | null;
};

type DiscountItem = {
  externalId: string;                    // Item external ID
  discountedQuantity: number;            // Quantity discounted
};

type FundingSplit = {
  fundingSource: string;                 // Who funds the discount
  amountPaid: number;                    // Amount paid (cents)
};
Platform-Specific Data

The rawPlatformFinancials field contains data normalized from the original platform (DoorDash, Uber Eats, GrubHub, etc.). Some fields may be null depending on what the source platform provides.