By default, resources' relationships are not included in responses and only the corresponding ID will be exposed - or a list of IDs in case of a list. Those relationships can be expanded if needed by using the expand request parameter. This parameter is available on all index requests.
You can expand recursively by specifying nested fields after a dot (.). For example, requesting fulfillment.order on a tracker will expose all the fields of the related fulfillment and will then also expose the order fields related to it.
You can expand multiple objects at once by identifying multiple items in the expand array.
Please note that the intermediary expand object will have all its attributes expanded automatically. So if you need fulfillment and order attributes you only need fulfilllment.order in the expand query. No need to add fulfillment to the expand array.
Another example would be having the fulfillment, its trackers, and all the items in the fulfillment and the trackers. In this situation you only need fulfilllment.line_items and fulfilllment.trackers.line_items in the expandarray.
Expansions have a maximum depth of 4 levels.
Please refer to the core resources schema for common relationships in Shipup data model. Other expandable resources will be specified in corresponding endpoint documentation.
Please keep in mind that many deep expansions on list requests can be slow
It is really recommended to expand the minimum amount of resources
curl https://api.shipup.co/v2/trackers \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ${PRIVATE_KEY}" \
-d "expand[]"="fulfillment"
{
"object": "tracker",
"id": 12345,
"created_at": 1570906800,
"custom_variables": null,
"delivered_at": null,
"delivery_status_code": "in_transit",
"displayable_expected_delivery_date": null,
"displayable_expected_delivery_datetime": null,
"first_delivery_attempted_at": null,
"mute_notifications": false,
"shipped_at": null,
"tracking_link": "http://www.laposte.fr/outils/suivre-vos-envois?code=AB12345678CD_1",
"tracking_number": "AB12345678CD_1",
"untracked_carrier_name": null,
"untracked_carrier_url": null,
"updated_at": null,
"uuid": "6ac199f1-e1f7-41c0-b26a-a409a31e51f2",
"carrier": {
"object": "carrier",
"code": "colissimo"
},
"events": {
"object": "list",
"data": [
{
"object": "event",
"id": 12346,
"event_type_code": null,
"happened_at": 1570906800,
"message": "Out for delivery",
"raw": "{:matcher=>\"Out for delivery\", :date=>Sat, 12 Oct 2019 19:00:00 +0000}",
"messages": {
"fr": "Out for delivery"
},
"address": null
},
{
"object": "event",
"id": 12345,
"event_type_code": "origin_scan",
"happened_at": 1570906800,
"message": "Package received",
"raw": "{:message=>\"Package received\", :date=>Sat, 12 Oct 2019 19:00:00 +0000}",
"messages": {
"fr": "Scan d'entrée"
},
"address": null
}
]
},
"fulfillment": {
"object": "fulfillment",
"id": 12345
},
"line_items": {
"object": "list",
"data": [
{
"object": "line_item",
"id": 12347
},
{
"object": "line_item",
"id": 12346
},
{
"object": "line_item",
"id": 12345
}
]
}
}