Expand

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.

Basic usage

# 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

{
  "id": "ord_01H...",
  "object": "order",
  "account_id": "acc_01H...",
  "document_type": "sales_order",
  "status": "confirmed"
}

{
  "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"
}

Multiple expansions

Pass expand[] multiple times to hydrate multiple fields:

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):

# 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:

# 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

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);

order = arcus.orders.retrieve(
    'ord_01H...',
    expand=['customer', 'line_items.product'],
)
print(order.customer.name)

order, err := client.Orders.Get(ctx, "ord_01H...", &arcus.OrderGetParams{
    Expand: []string{"customer", "line_items.product"},
})
fmt.Println(order.Customer.Name)

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.

Get Started

Concepts

Guides

SDKs

Collections

Overview

Basic usage

Response comparison

Multiple expansions

Nested expansion

List endpoints: the `data.` prefix

Limits

Scope requirements

SDK usage

Available expand paths per resource

​Overview

​Basic usage

​Response comparison

​Multiple expansions

​Nested expansion

​List endpoints: the data. prefix

​Limits

​Scope requirements

​SDK usage

​Available expand paths per resource

Overview

Basic usage

Response comparison

Multiple expansions

Nested expansion

List endpoints: the `data.` prefix

Limits

Scope requirements

SDK usage

Available expand paths per resource