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.
Links and expanded objects
By default a related object comes back as its URL:
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858" \
-H "Authorization: Bearer $COMECERO_TEST_TOKEN"{
"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:
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858?expand=customer,payments" \
-H "Authorization: Bearer $COMECERO_TEST_TOKEN"{
"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:
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
| Limit | Value |
|---|---|
| Paths on a single object | 12 |
| Paths on a list | 2 |
| Depth | 4 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
Lists and pagination
How Comecero API lists return pages of up to 100 items, the difference between offset and cursor lists, and how to sort them and filter them by date.
Customizing output
Use the show and hide query parameters to return only the fields you need from the Comecero API, which keeps responses small, especially for long lists.