Skip to content
SummerbaseDocs

Expanding responses

A field that holds another object, such as a subscription’s customer, is left out of a response unless the request asks for it with expand[]. Each object’s page marks those fields as expandable, and each endpoint lists the values it takes.

A dotted path reaches into what an expanded object holds in turn: items.price expands a subscription’s items and each item’s price, and items.price.plan the plan of each of those prices too. A path expands everything along it, so items.price needs no items beside it.

Terminal window
curl "https://api.summerbase.com/v1/subscriptions/backend:sub_7731?expand[]=customer&expand[]=items.price" \
  -H "Authorization: Bearer $SUMMERBASE_API_KEY"
{
  "id": "0199a7c2-5b3e-7a14-8c6d-2f9e4b7a1c05",
  "object": "subscription",
  "customer_id": "0199a7c2-4e1b-7f38-b9d2-5a6c8e0f1d73",
  "customer": {
    "id": "0199a7c2-4e1b-7f38-b9d2-5a6c8e0f1d73",
    "object": "customer",
    "name": "Northwind Labs"
  },
  "items": [
    {
      "id": "0199a7c2-5b41-7c62-9d3e-6a1f8b2c4d97",
      "object": "subscription_item",
      "quantity": "25",
      "price_id": "0199a7c2-3c8d-7b51-a4e2-7d9f1b3c5e28",
      "price": {
        "id": "0199a7c2-3c8d-7b51-a4e2-7d9f1b3c5e28",
        "object": "price",
        "name": "Growth monthly"
      }
    }
  ]
}
  • Not expanded, the field is absent. A field that points at one object has its id beside it either way, as customer_id is here; one that holds several, such as items, has nothing until it is expanded.
  • Expanded, a field that points at nothing is null, and one that holds several is a list.
  • On a list endpoint, expand[] expands that field on every record in data. A search takes the same values as expand in its body.
  • Each step of a path can expand what that object’s own endpoints offer, and each endpoint lists every path it takes. A path is at most four steps, a request takes at most ten, and no path may come back to an object already on it — items.subscription on a subscription is the subscription you asked for. Anything else is refused with 400 and the code invalid_expand, which names what was wrong.
© 2026 SummerbaseHomePricingAboutTermsPrivacySecurity