Skip to main content

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.

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

​
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

ConstraintValue
Max expand paths per request10
Max nesting depth4
Max hydrated rows per relation100 (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);

​
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.