Expandable Attributes

---

All attributes that are tagged with "Expandable attribute" can be expanded.

Expanding an attribute returns the referenced object opposed to just the ID.

To expand an attribute, append the expand query parameter to the URL.

GET /v1/marketplace/vouchers

[
  {
    ...
    "amount": 3990,
    "id": "tJzkMy8OVe4FCGcUg",
    "user": "62458fa81fefab001e1ca18f"
    ...
  }
]

GET /v1/marketplace/vouchers?expand=user

[
  {
    ...
    "amount": 3990,
    "id": "tJzkMy8OVe4FCGcUg",
    "user": {
      "id": "62458fa81fefab001e1ca18f",
      "name": "John The Voucher Buyer"
      ...
    }
    ...
  }
]

Nested expanding is also supported.

Let's say we have a list of transactions, and we want to get the titles of all customer groups with ties to that transaction.

• A transaction is a part of a sale
• A sale is possibly tied to a customer
• A customer might belong to 0-N groups

This relationship can be conceptualized as a graph, where a transaction is a node, and the edges represent the connections to sales, customers, and groups.

---

---

By issuing a single API call with nested expanding, it is possible to retrieve the required data, eliminating the need for multiple back-and-forth requests.

tip

The expand functionality can also be combined with the select feature, which allows for the selective retrieval of data, reducing the response payload to only the Customer Group titles.

GET /v1/hq/companies/4bF8BQmKtowFKdguf/transactions?expand=sale.customer.groups&select=sale.customer.groups.title

[
  {
    "sale": {
      "customer": {
        "groups": [
          {
            "title": "Family"
          },
          {
            "title": "Regulars"
          }
        ]
      }
    }
  },
  {
    "sale": {
      "customer": {
        "groups": []
      }
    }
  }
]

It is also possible expand multiple fields at any depth. The usage is the same as with select, an array of keys to expand is sent as a query parameter:

?expand=sale.customer.groups&expand=sale.company&expand=employees