# Expanding objects (/docs/basic-concepts/expanding-objects)

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 [#links-and-expanded-objects]

By default a related object comes back as its URL:

```bash title="Request"
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

```json title="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:

```bash title="Request"
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858?expand=customer,payments" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

```json title="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](/api) says which of its fields can be expanded.

## Nested objects [#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`.

```bash
# 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 [#expanding-in-lists]

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

```bash title="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 [#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 [#next-steps]

<Cards>
  <Card title="Customizing output" href="/docs/basic-concepts/customizing-output" />
  <Card title="Lists and pagination" href="/docs/basic-concepts/lists-and-pagination" />
</Cards>
