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
  status: 'new' | 'future' | 'rejected' | 'cancelled' | 'ready' | 'finished';
  deliveryStatus?: 'ASSIGNED' | 'EN_ROUTE_TO_STORE_LOCATION' | 'EN_ROUTE_TO_CUSTOMER' | 'COMPLETED' | 'CANCELED';
  createdAt: string;                       // ISO 8601 timestamp when order was created
  updatedAt: string;                       // ISO 8601 timestamp of last update
  cancellation?: {                         // Present when order is cancelled
    by: 'platform' | 'merchant' | 'system';
    reason: string;
    at: string;                            // ISO 8601 timestamp
  };
  store: Store;                            // Store information
  details: OrderDetails;                     // Detailed order information
};

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 received by Mealco
  estimatedPickupAt?: string;         // ISO timestamp for estimated pickup/ready

  // Order Type
  isPickup: boolean;                  // Pickup vs delivery

  // Customer Information
  consumer: Consumer;                 // Primary customer
  consumers: Array<Consumer>;         // All customers (group orders)
  isGroupOrder: boolean;              // Whether multiple customers are involved

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

  // Delivery
  isMerchantDelivery: boolean;        // Delivery handled by merchant
  deliveryAddress?: DeliveryAddress;  // Delivery address details
  courier?: Courier;                  // Courier details for platform deliveries

  // Financials (cents)
  // All monetary amounts are 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;                 // Include utensils

  // Items
  items: Array<OrderItem>;            // Line items

  // Promotions
  promotions?: Array<OrderPromotion>; // Applied promotions
};

type Consumer = {
  name: string;
  phone?: string;                      // Contact phone (may be masked)
  code?: string;                       // Code for masked phone numbers
};

type DeliveryAddress = {
  googlePlaceId?: string;
  lat?: number;
  lng?: number;
  label: string;
  raw: string;
};

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

type OrderItem = {
  id: string;
  sku?: string;                        // Optional SKU when available
  name: string;
  quantity: number;
  price: {
    total: number;
    unit: number;
    base: number;
    menu: number;
  };
  note?: string;
  modifiers: Array<OrderItemModifier>;
};

type OrderItemModifier = {
  id: string;
  sku?: string;                        // Optional SKU when available
  name: string;
  quantity: number;
  price: {
    total: number;
    unit: number;
    base: number;
    menu: number;
  };
  modifierGroup?: { id: string; name: string };
  modifiers?: Array<OrderItemModifier>;
};

type OrderPromotion = {
  name?: string;
  discountValue?: number;              // cents
  discountPercentage?: number;         // e.g. 40 for 40%
};

Store Information​

type Store = {
  id: string;                           // Unique store identifier
  externalId?: string;                  // Partner-facing store ID (e.g., POS ID)
  location?: string;                    // The store's location name
  brand?: string;                       // The brand name
  platform: string;                     // The name of the ordering platform (e.g., "doordash")
};

### Delivery Address Guidance

For highest accuracy, it is strongly recommended to **use the `deliveryAddress.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.

### Item Structure

```typescript
type OrderItem = {
  id: string;                         // Item identifier
  sku?: string;                       // SKU when available
  name: string;                       // Item name
  quantity: number;                   // Quantity ordered
  price: {
    total: number;                    // Total price (cents)
    unit: number;                     // Unit price including modifiers (cents)
    base: number;                     // Base price without modifiers (cents)
    menu: number;                     // Menu price (cents)
  };
  note?: string;                      // Item-specific notes
  modifiers: Array<OrderItemModifier>; // Item modifiers
};

type OrderItemModifier = {
  id: string;
  sku?: string;                       // SKU when available
  name: string;
  quantity: number;
  price: {
    total: number;                    // Total price (cents)
    unit: number;                     // Unit price (cents)
    base: number;                     // Base price (cents)
    menu: number;                     // Menu price (cents)
  };
  modifierGroup?: {                   // Modifier group (e.g., "Protein Choice")
    id: string;
    name: string;
  };
  modifiers?: Array<OrderItemModifier>; // Nested modifiers
};

Promotions​

The promotions array lists all discounts applied to the order. To calculate the total discount amount, sum the discountValue from each object in the array.

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