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: each product in the list has no variants
curl "https://api.arcuserp.com/v1/products" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

# With expand: each product carries its variants (paths on a list start with data.)
curl "https://api.arcuserp.com/v1/products?expand[]=data.variants" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

Response comparison

{
  "object": "list",
  "data": [
    {
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "title": "Riser Kit",
      "product_type": "variant_parent",
      "has_variants": true,
      "is_active": true
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/products"
}

{
  "object": "list",
  "data": [
    {
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "title": "Riser Kit",
      "product_type": "variant_parent",
      "has_variants": true,
      "is_active": true,
      "variants": {
        "object": "list",
        "data": [
          {
            "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
            "sku": "RISER-DOME",
            "variant_title": "Dome Riser Kit",
            "is_active": true
          },
          {
            "id": "9b2e1c4a-5d3f-4a7b-8e6c-1f0a2b3c4d5e",
            "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
            "sku": "RISER-FLAT",
            "variant_title": "Flat Riser Kit",
            "is_active": true
          }
        ],
        "has_more": false
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/products"
}

Where expand applies

expand[] is a read option, and at this release GET /v1/products and GET /v1/products/{id} are the endpoints where it runs: they apply expand[], require the data. prefix on the list, and check the 403 insufficient_scope scope for each path. The order endpoints do not act on expand[] and check no expand scope: GET /v1/orders never reads it, and GET /v1/orders/{id} always returns the line items, payments, tax lines and packages inline. PATCH and DELETE take no expand[] either. GET /v1/orders/{id} takes either the order’s UUID or its human-readable order number (for example SO-001234) as {id}. By default GET /v1/orders lists only quotes, sales orders, and invoices; pass document_type to include other order documents.

Multiple expansions

Pass several paths in one expand parameter, separated by commas, to hydrate multiple fields. Put the list in expand, not in expand[]: a comma inside an expand[] value returns 400 Bad Request with code: invalid_expand_param.

curl "https://api.arcuserp.com/v1/products?expand=data.variants,data.vendors" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

Nested expansion

Dot notation can nest expand paths up to 4 levels deep, but no nested path on the products endpoints returns related records at this release, so there is no nested example here; request each field as its own path.

List endpoints: the `data.` prefix

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

# Single-resource endpoint: no prefix
GET /v1/products/{id}?expand[]=variants

# List endpoint: data. prefix required on every path
GET /v1/products?expand=data.variants,data.vendors

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, in addition to the endpoint’s own read scope. A missing scope returns 403 Forbidden with code: insufficient_scope and a required field naming the scope. This check runs on the endpoints named under Where expand applies; the order endpoints check no expand scope because they do not act on expand[].

SDK usage

const products = await arcus.products.list({
  limit: 10,
  expand: ['data.variants', 'data.vendors'],
});

// each product now carries its variants as a list object
console.log(products.data[0].variants.data.length);

products = arcus.products.list(
    limit=10,
    expand=['data.variants', 'data.vendors'],
)
print(len(products.data[0].variants.data))

products, err := client.Products.List(ctx, &arcus.ProductListParams{
    Limit:  arcus.Int(10),
    Expand: []string{"data.variants", "data.vendors"},
})
fmt.Println(len(products.Data[0].Variants.Data))

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

Where expand applies

Multiple expansions

Nested expansion

List endpoints: the `data.` prefix

Limits

Scope requirements

SDK usage

Available expand paths per resource

​Overview

​Basic usage

​Response comparison

​Where expand applies

​Multiple expansions

​Nested expansion

​List endpoints: the data. prefix

​Limits

​Scope requirements

​SDK usage

​Available expand paths per resource

Overview

Basic usage

Response comparison

Where expand applies

Multiple expansions

Nested expansion

List endpoints: the `data.` prefix

Limits

Scope requirements

SDK usage

Available expand paths per resource