Includables
Eager-load related data with the includes[] query parameter and each resource's supported includes.
By default, a resource returns its own fields. Use the includes parameter to
eager-load related data in the same response — so you fetch a product and its
category in one round trip instead of two.
Syntax
includes is an array. Repeat the bracketed key once per relation:
GET https://api.flavours.sa/dev/api/v2/products?includes[]=category&includes[]=prices.paymentMethodAPI-TOKEN: <your-key>X-API-Version: 2.0.0- Each relation is a separate
includes[]=…entry. - Nested relations use dot notation:
prices.paymentMethodloads each price and its payment method. Including a nested path implies its parents, soincludes[]=prices.paymentMethodalso loadsprices.
Supported includes are a fixed whitelist
Each resource defines exactly which relations may be included. This is the key difference from a free-form query: you cannot load an arbitrary relation.
An unsupported include returns 422, not data
If you request an include a resource does not support, the request is rejected
with a 422 validation error — it does not silently ignore the value, and it
does not return a 500. Stick to the supported names below (and on each
endpoint's reference page).
{
"meta": {
"code": 422,
"status": "error",
"message": "The selected includes is invalid."
},
"data": [
{
"code": 0,
"message": "The selected includes is invalid.",
"field": "includes"
}
]
}Products — supported includes
| Include | Loads |
|---|---|
category | The product's category. |
market | The owning market. |
branch | The owning branch. |
prices.paymentMethod | Per-payment-method prices, each with its method. |
ingredients.ingredient | The product's ingredients. |
recipes.recipe | The product's recipes. |
exclusions, exclusions.type | Order-type exclusions for the product. |
addonGroups, addonGroups.options | Attached add-on groups and their options. |
The full, authoritative list for any endpoint is on its reference page. Naming a
relation not in that list yields the 422 above.
Limiting a to-many include
Some to-many relations accept a per-relation cap, written relation:N, to bound
how many child rows are loaded per parent:
?includes[]=products:5This loads at most 5 child rows for that relation. The cap is clamped to a maximum of 100. This suffix is only accepted on relations that opt into it — on others it is rejected as invalid.
Include only what you need
Every include adds queries and payload. Request the specific relations your integration uses rather than a broad set, and page your list requests so each response stays small.