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.
HTTP
Core SDK
Node SDK
Python SDK
1
GET https://api.builton.dev/orders/<order_id>?expand=user HTTP/1.1
2
Content-Type: application/json
3
Authorization: Bearer <jwt -or- service-account-key>
4
X-Builton-Api-Key: <builton-api-key>
5
Host: api.builton.dev
6
​
7
---------------
8
​
9
HTTP/1.1 200 OK
10
Content-Type: application/json
11
​
12
{
13
   [...],
14
   "items": [...],
15
   "payments": [...],
16
   "total_amount": 1337.42,
17
   "user": {
18
        "first_name": "John",
19
        "last_name": "Doe",
20
        [...]
21
    }
22
}
Copied!
1
const BuiltOn = require('@builton/core-sdk');
2
​
3
const builton = new BuiltOn({
4
    bearerToken: '<jwt>',
5
    apiKey: '<builton-api-key>',
6
});
7
​
8
builton.orders.get(
9
    '<order-id>',
10
    { urlParams: { expand: 'user' } }
11
).then((order) => {
12
  console.log(order);
13
  /*
14
    Order {
15
        [...],
16
        "items": [...],
17
        "payments": [...],
18
        "total_amount": 1337.42,
19
        "user": {
20
            "first_name": "John",
21
            "last_name": "Doe",
22
            [...]
23
        }
24
    }
25
  */
26
});
Copied!
1
const BuiltOn = require('@builton/node-sdk');
2
​
3
const builton = new BuiltOn({
4
    bearerToken: '<jwt -or- service-account-key>',
5
    apiKey: '<builton-api-key>',
6
});
7
​
8
builton.orders.get(
9
    '<order-id>',
10
    { urlParams: { expand: 'user' } }
11
).then((order) => {
12
  console.log(order);
13
  /*
14
    Order {
15
        [...],
16
        "items": [...],
17
        "payments": [...],
18
        "total_amount": 1337.42,
19
        "user": {
20
            "first_name": "John",
21
            "last_name": "Doe",
22
            [...]
23
        }
24
    }
25
  */
26
});
Copied!
1
from builton_sdk import Builton
2
​
3
builton = Builton(api_key=<builton-api-key>, bearer_token=<jwt -or- service-account-key>)
4
​
5
order = builton.order().get('<order-id>', expand='user')
6
print(order.user)
7
""
8
{
9
  "first_name": "John",
10
  "last_name": "Doe",
11
  [...]
12
}
13
""
Copied!
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.
HTTP
Core SDK
Node SDK
Python SDK
1
GET /orders/<order-id>?expand=user,items.product HTTP/1.1
2
Content-Type: application/json
3
Authorization: Bearer <jwt -or- service-account-key>
4
X-Builton-Api-Key: <builton-api-key>
5
Host: api.builton.dev
Copied!
1
builton.orders.get(
2
    '<order-id>',
3
    { urlParams: { expand: 'user, items.product' } }
4
).then(console.log);
Copied!
1
builton.orders.get(
2
    '<order-id>',
3
    { urlParams: { expand: 'user, items.product' } }
4
).then(console.log);
Copied!
1
builton.order().get('<order-id>', expand='user, items.product')
Copied!
This will expand the user, the items and the product in each item.
By using the expanded parameters, you are getting more information. This increases the payload, which may increase the API response time some.

Nuts & Bolts - Previous

Retrieve Items

Next - Nuts & Bolts

Pagination

Last modified 1yr ago

Copy link