comecerodocs
Concepts

Expanding objects

Use the expand query parameter to get related Comecero objects, such as an order's customer and payments, in the same API response instead of as URLs.

Many fields in a response are links to other objects. With expand you get those objects in full in the same response, so one call can replace several.

By default a related object comes back as its URL:

Request
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
Response
{
  "object": "order",
  "order_id": "6622-NXKHE-858",
  "customer": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4",
  "payments": "https://api.comecero.com/api/v1/orders/6622-NXKHE-858/payments"
}

Name the fields to expand, separated by commas, and they come back as objects:

Request
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858?expand=customer,payments" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
Response
{
  "object": "order",
  "order_id": "6622-NXKHE-858",
  "customer": {
    "object": "customer",
    "customer_id": "0142130616328Cu6Vsk6M4",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "payments": {
    "total_items": 1,
    "data": [
      { "object": "payment", "payment_id": "0142130709984PyZwyr0YD", "status": "completed" }
    ]
  }
}

Each object's page in the API reference says which of its fields can be expanded.

Nested objects

Use dot notation to expand an object inside an expanded object. The objects along the path are expanded too, so expand=payments.payment_method also expands payments.

# The payment method of each payment on the order
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858?expand=payments.payment_method" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"

# The product of each item in a cart
curl "https://api.comecero.com/api/v1/carts/0091307952465CafhFSTa1?expand=items.product" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"

For an array such as items, the path applies to every element. For an expanded list such as payments, you name the field of each item directly (payments.payment_method), without data.

Expanding in lists

expand works on lists too. It applies to every item on the page:

Request
curl "https://api.comecero.com/api/v1/orders?expand=customer" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"

A list cannot be expanded inside another list. In a list of orders, payments stays a URL even if you ask to expand it. Get one order to expand its payments.

Limits

LimitValue
Paths on a single object12
Paths on a list2
Depth4 levels (payments.payment_method is 2)

The API does not answer with an error when you go past a limit or misspell a field:

  • Paths past the maximum are dropped, keeping the first ones you sent.
  • Paths more than 4 levels deep are dropped.
  • A field that does not exist or cannot be expanded is ignored.

So if a field still comes back as a URL, check its spelling and the limits.

Next steps

On this page