Use expandable fields
Use the expand
query parameter
expand
query parameterYou can use the expand
query parameter to expand specific fields in the API Reference. When you specify the fields to expand, the server retrieves the related fields and provides additional information as an expanded response, for example, related object nested within the parent.
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 expanded$ curl -s "https://apisandbox.dev.clover.com/v3/merchants/{mId}/items/{Item_ID}?expand=categories" --header "Authorization: Bearer {API_Token}" | python -mjson.tool
{
"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}" | python -mjson.tool
{
"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}" | python -mjson.tool
...
{
"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 12 months ago