Expansions

Inline related resources with ?expand=

Resources reference each other by ID (orders link to tables, menu items, customers). Use expand to inline the referenced object in the same response, saving a round-trip.

Basic expansion

Without expansion, a referenced object is just an ID:

GET /v1/orders/ord_abc

{
  "id": "ord_abc",
  "object": "order",
  "table": "tbl_07",
  "items": [
    { "menu_item": "mi_burger", "quantity": 1 }
  ]
}

Ask for it inline with ?expand=table:

GET /v1/orders/ord_abc?expand=table

{
  "id": "ord_abc",
  "object": "order",
  "table": {
    "id": "tbl_07",
    "object": "table",
    "number": 7,
    "capacity": 4,
    "status": "occupied"
  },
  "items": [
    { "menu_item": "mi_burger", "quantity": 1 }
  ]
}

Nested paths

Drill into nested fields with dots — up to 4 levels deep. For example ?expand=items.menu_item inlines the menu item on every line of every order:

GET /v1/orders/ord_abc?expand=items.menu_item

{
  "id": "ord_abc",
  "items": [
    {
      "menu_item": {
        "id": "mi_burger",
        "object": "menu_item",
        "name": "Classic burger",
        "price": 1200
      },
      "quantity": 1
    }
  ]
}

Multiple paths

Pass expand repeatedly or comma-separate:

GET /v1/orders?expand[]=table&expand[]=server&expand[]=items.menu_item

GET /v1/orders?expand=table,server,items.menu_item

A note on cost

Expansions are convenient but they fan out queries. Expand only what you'll actually use in the response — if you need 5+ deep nestings, the right call is usually a follow-up GET on the referenced resource.