Expanding fields

Fields can be expanded using the expand query parameter. You can see which fields are expandable for a given resource in the API Reference.

🚧
IMPORTANT
Please limit expansions to a maximum of three fields per API call. This will allow us to continually provide quick API response times and reduce undue load.

In this example, the 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": "Bangers and Mash",
    "alternateName": "",
    "code": "024463061095",
    "price": 150,
    "priceType": "FIXED",
    "defaultTaxRates": true,
    "unitName": "",
    "isRevenue": true,
    "categories": {
        "elements": [
            {
                "id": "MHH9XR2YXZ4T4",
                "name": "Food",
                "sortOrder": "0"
            }
        ]
    }
}

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
            }
        ]
    }
}

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"
}
...

🚧IMPORTANT

🚧
IMPORTANT