Including associations
How to include a resource and its associations in the same request
When you fetch a resource or a collection, you can include its associations in the same request, using the
include
query parameter. This reduces the number of roundtrips, optimizing the performances.The value of the
include
parameter must be a comma-separated list of relationship paths (see example) — make sure to avoid whitespaces before or after each comma. A relationship path is a dot-separated list of relationship names (see example). For each included resource you'll find in the relationships
object of the response an additional data
array containing their type and ID.Included resources cannot be sorted or filtered. Sort rules and filters apply to the parent resource (e.g.
skus
in the examples below) or to related resources (see examples).
Request
Response
The following request fetches the SKU identified by the ID "xYZkjABcde" and the related prices and stock items:
curl -g -X GET \
'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde?include=prices,stock_items' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: your-access-token'
On success, the API responds with a
200 OK
status code, returning the resource object and the included associations:{
"data": {
"id": "xYZkjABcde",
"type": "skus",
"links": { ... },
"attributes": { ... },
"relationships": {
"shipping_category": { ... },
"prices": {
"links": { .. },
"data": [
{
"type": "prices",
"id": "pxEWUBWXLA"
}
]
},
"stock_items": {
"links": { ... },
"data": [
{
"type": "stock_items",
"id": "jAdEfdlvBK"
},
{
"type": "stock_items",
"id": "jpQRfJlrwN"
}
]
},
"stock_reservations": { ... },
"delivery_lead_times": { ... },
"sku_options": { ... },
"attachments": { ... },
"events": { ... },
"tags": { ... }
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
},
"included": [
{
"id": "pxEWUBWXLA",
"type": "prices",
"links": { ... },
"attributes": {
"currency_code": "USD",
"sku_code": "TSHIRTMM000000FFFFFFMXXX",
"amount_cents": 3480,
"amount_float": 34.8,
"formatted_amount": "$34.80",
"compare_at_amount_cents": 4524,
"compare_at_amount_float": 45.24,
"formatted_compare_at_amount": "$45.24",
"created_at": "2019-05-14T10:36:53.987Z",
"updated_at": "2019-05-14T10:36:53.987Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"price_list": { ... },
"sku": { ... },
"price_tiers": { ... },
"price_volume_tiers": { ... },
"price_frequency_tiers": { ... },
"attachments": { ... }
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
},
{
"id": "jAdEfdlvBK",
"type": "stock_items",
"links": { ... },
"attributes": {
"sku_code": "TSHIRTMM000000FFFFFFMXXX",
"quantity": 76,
"created_at": "2019-05-14T10:36:53.980Z",
"updated_at": "2019-05-14T10:36:53.980Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"stock_location": { ... },
"sku": { ... },
"reserved_stock": { ... },
"stock_reservations": { ... },
"attachments": { ... }
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
},
{
"id": "jpQRfJlrwN",
"type": "stock_items",
"links": { ... },
"attributes": {
"sku_code": "TSHIRTMM000000FFFFFFMXXX",
"quantity": 28,
"created_at": "2019-05-14T10:36:53.993Z",
"updated_at": "2019-05-14T10:36:53.993Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"stock_location": { ... },
"sku": { ... },
"reserved_stock": { ... },
"stock_reservations": { ... },
"attachments": { ... }
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
}
]
}
Request
Response
The following request features the relationship path
stock_items.reserved_stock
as the value of the include parameter, where stock_items
is a relationship listed under the SKU resource object, and reserved_stock
is a relationship listed under the stock item resource object:curl -g -X GET \
'http://yourdomain.commercelayer.io/api/skus/xYZkjABcde?include=stock_items.reserved_stock' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token'
On success, the API responds with a
200 OK
status code, returning the resource object and the included associations:{
"data": {
"id": "xYZkjABcde",
"type": "skus",
"links": { ... },
"attributes": { ... },
"relationships": {
"shipping_category": { ... },
"prices": { ... },
"stock_items": {
"links": { ... },
"data": [
{
"type": "stock_items",
"id": "jAdEfdlvBK"
},
{
"type": "stock_items",
"id": "jpQRfJlrwN"
}
]
},
"stock_reservations": { ... },
"delivery_lead_times": { ... },
"sku_options": { ... },
"attachments": { ... },
"events": { ... },
"tags": { ... }
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
},
"included": [
{
"id": "jAdEfdlvBK",
"type": "stock_items",
"links": { ... },
"attributes": {
"sku_code": "TSHIRTMM000000FFFFFFMXXX",
"quantity": 76,
"created_at": "2019-05-14T10:36:53.980Z",
"updated_at": "2019-05-14T10:36:53.980Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"stock_location": { ... },
"sku": { ... },
"reserved_stock": {
"links": { ... },
"data": null
},
"stock_reservations": { ... },
"attachments": { ... }
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
},
{
"id": "jpQRfJlrwN",
"type": "stock_items",
"links": { ... },
"attributes": {
"sku_code": "TSHIRTMM000000FFFFFFMXXX",
"quantity": 28,
"created_at": "2019-05-14T10:36:53.993Z",
"updated_at": "2019-05-14T10:36:53.993Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"stock_location": { ... },
"sku": { ... },
"reserved_stock": {
"links": { ... },
"data": {
"type": "reserved_stocks",
"id": "noJnMSBLXo"
}
},
"stock_reservations": { ... },
"attachments": { ... }
},
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
},
{
"id": "noJnMSBLXo",
"type": "reserved_stocks",
"links": { ... },
"attributes": {
"quantity": 5,
"created_at": "2023-07-17T10:29:13.433Z",
"updated_at": "2023-07-17T10:29:13.441Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": {
"stock_item": { ... },
"sku": { ... },
"stock_reservations": { ... },
"meta": {
"mode": "test",
"organization_id": "EnAvaFOrRe"
}
}
]
}
Last modified 2mo ago