Release NotesAnnouncementsVideosBlog
Guides

Use expandable fields

United States
Canada
Europe
Latin America

Use the expand query parameter

You 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

$ 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 about 1 year ago