Release NotesAnnouncementsBlogFAQSupport
Guides

Use expandable fields for API responses

North America
Europe
Latin America

Use the expand query parameter

You 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

curl -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 about 1 month ago