Expanding Objects

It is possible to expand the nested objects within a main object. For example, an Order might have an associated User ID. If you want to expand the actual user information, you can use the expand query parameter.

GET https://api.builton.dev/payment_methods/<payment_method_id>?expand=user HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

HTTP/1.1 200 OK
Content-Type: application/json
​
{
   "masked_card_number":"XXXXXXXXXXXX1234",
   "user": {
        "first_name": "John",
        "last_name": "Doe"
    }
}

You can also nest expand requests with the dot property. For example, requesting payments.payment_method on an order will expand the payments property into a list of Payment objects, and will then expand the payment_method property for each Payment object into a full Payment Method object.

You can expand multiple objects at once. Just separate items in the query with commas.

GET /orders/<order-id>?expand=user,items.product

This will expand the user, the items and the product in each item.