> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expand

> Hydrate related resources inline using the ?expand[] query parameter -- the same Stripe-style pattern you already know.

## Overview

By default, the Arcus API returns only references (UUIDs) for related resources. Use `?expand[]=<field>` to hydrate those references inline in a single request, eliminating N+1 API calls.

This is identical to [Stripe's expand behavior](https://docs.stripe.com/api/expanding_objects).

## Basic usage

```bash theme={null}
# Without expand: order.customer is just an account_id UUID
curl "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders/ord_01H..." \
  -H "Authorization: Bearer $ARCUS_API_KEY"

# With expand: order.customer is the full account object
curl "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders/ord_01H...?expand[]=customer" \
  -H "Authorization: Bearer $ARCUS_API_KEY"
```

## Response comparison

<CodeGroup>
  ```json Without expand theme={null}
  {
    "id": "ord_01H...",
    "object": "order",
    "account_id": "acc_01H...",
    "document_type": "sales_order",
    "status": "confirmed"
  }
  ```

  ```json With ?expand[]=customer theme={null}
  {
    "id": "ord_01H...",
    "object": "order",
    "account_id": "acc_01H...",
    "customer": {
      "id": "acc_01H...",
      "object": "account",
      "name": "Acme Corp",
      "account_type": "business",
      "email": "billing@acmecorp.example"
    },
    "document_type": "sales_order",
    "status": "confirmed"
  }
  ```
</CodeGroup>

## Multiple expansions

Pass `expand[]` multiple times to hydrate multiple fields:

```bash theme={null}
curl "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders/ord_01H...?expand[]=customer&expand[]=line_items.product" \
  -H "Authorization: Bearer $ARCUS_API_KEY"
```

## Nested expansion

Use dot notation to expand nested relations (up to 4 levels deep):

```bash theme={null}
# Expand the product inside each line item
?expand[]=line_items.product

# Expand the default vendor on each product inside each line item
?expand[]=line_items.product.default_vendor
```

## List endpoints: the `data.` prefix

On list endpoints, all expand paths require the `data.` prefix:

```bash theme={null}
# Single-resource endpoint: no prefix
GET /v1/entities/{entity_id}/orders/ord_01H...?expand[]=customer

# List endpoint: data. prefix required
GET /v1/entities/{entity_id}/orders?expand[]=data.customer&expand[]=data.line_items.product
```

Omitting the `data.` prefix on a list endpoint returns `400 Bad Request` with `code: invalid_expand_list_requires_data_prefix`.

## Limits

| Constraint                     | Value                                                   |
| ------------------------------ | ------------------------------------------------------- |
| Max expand paths per request   | 10                                                      |
| Max nesting depth              | 4                                                       |
| Max hydrated rows per relation | 100 (returns reference + `truncated: true` beyond that) |

## Scope requirements

Each expand path requires the corresponding read scope on your API key. For example, expanding `customer` on an order requires the `accounts:read` scope. Missing scope returns `403 Forbidden` with `code: insufficient_scope` and `required: accounts:read`.

## SDK usage

<CodeGroup>
  ```javascript Node theme={null}
  const order = await arcus.orders.retrieve('ord_01H...', {
    expand: ['customer', 'line_items.product'],
  });

  // order.customer is now the full account object
  console.log(order.customer.name);
  ```

  ```python Python theme={null}
  order = arcus.orders.retrieve(
      'ord_01H...',
      expand=['customer', 'line_items.product'],
  )
  print(order.customer.name)
  ```

  ```go Go theme={null}
  order, err := client.Orders.Get(ctx, "ord_01H...", &arcus.OrderGetParams{
      Expand: []string{"customer", "line_items.product"},
  })
  fmt.Println(order.Customer.Name)
  ```
</CodeGroup>

## Available expand paths per resource

Valid expand paths are documented on each endpoint's reference page under the **Expandable fields** section. Requesting an invalid path returns `400 Bad Request` with `code: invalid_expand_unknown_field` and a list of valid paths.