Use expandable fields for API responses
Use the expand
query parameter
expand
query parameterYou can use the expand
query parameter to retrieve additional information about specific fields in the API Reference. When you specify fields to expand, the server includes related objects nested within the parent object in the response. This allows you to access detailed information about these related objects without making separate API calls.
For example, if you expand the categories
field, the response will include detailed information about each category associated with the item.
IMPORTANT
Limit expansions to a maximum of three fields per API call. This allows us to continually provide quick API response times and reduce undue load.
Example 1—categories
for an inventory item are expanded
categories
for an inventory item are expandedcurl -s "https://apisandbox.dev.clover.com/v3/merchants/{mId}/items/{Item_ID}?expand=categories"
--header "Authorization: Bearer {API_Token}"
{
"id": "Z0EPYQ2R5TQ5Y",
"hidden": false,
"name": "My Food Truck",
"alternateName": "",
"code": "024463061095",
"price": 150,
"priceType": "FIXED",
"defaultTaxRates": true,
"unitName": "",
"isRevenue": true,
"categories": {
"elements": [
{
"id": "MHH9XR2YXZ4T4",
"name": "Food",
"sortOrder": "0"
}
]
}
}
Example 2—Multiple fields are expanded
To expand multiple fields in a request, separate the fields with a percent-encoded comma (%2C
). In the following example, the response expands both the tags
and categories
fields.
$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/{mId}/items/{Item_ID}?expand=tags%2Ccategories"
--header "Authorization: Bearer {API_Token}"
{
"cost": 0,
"defaultTaxRates": true,
"hidden": false,
"id": "AK5ESN5YR8YWY",
"isRevenue": true,
"modifiedTime": 1432671908000,
"name": "Pizza",
"price": 1499,
"priceType": "FIXED",
"tags": {
"elements": [
{
"id": "HYQ5Z74KS9E6W",
"name": "Hot"
}
]
},
"categories": {
"elements": [
{
"id": "1JZPWY014VPEP",
"name": "Italian",
"sortOrder": 1
},
{
"id": "0AJNZP04JXB4G",
"name": "From the Oven",
"sortOrder": 0
}
]
}
}
Example 3—Two levels of fields are expanded
Two levels of fields can be expanded by specifying a dotted field path. For example, when querying an order, you can expand the lineItems
in the order and the taxRates
of each item.
$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{Order_ID}?expand=lineItems.taxRates"
--header "Authorization: Bearer {API_Token}"
{
"clientCreatedTime": "1389389735000",
"createdTime": "1389389736000",
"employee": "id",
"groupLineItems": "true",
"id": "QGSS9P64219CM",
"lineItems": {
"elements": [
{
"createdTime": "1389389734000",
"id": "VGQRH14DBR7JC",
"name": "Bangers and Mash",
"price": "1000",
"printed": "true",
"taxRates": {
"elements": [
{
"id": "VSA19B84VG1GT",
"isDefault": "true",
"name": "VAT",
"rate": "1500000"
},
{
"id": "BTHZCAXV6Z5R8",
"isDefault": "true",
"name": "Zero Tax",
"rate": "0"
}
]
}
}
]
},
"manualTransaction": "false",
"payType": "FULL",
"state": "locked",
"taxRemoved": "false",
"total": "1000"
}
Updated 16 days ago