Skip to main content
The responses returned by a GET operation can be large: they may include payloads such as Order objects or Product objects that contain over a hundred properties each. Depending on the specific data you want to retrieve, you may not always need the API to return every property for a given resource. Similarly, you may not always want to update every property on a resource when you execute a PUT operation. Furthermore, retrieving or updating only the data you need allows your operations to maintain optimal performance. The responseFields argument allows you to filter which properties are returned or updated by the API, providing you with a more manageable payload to work with and reducing network latency and client SDK parse times. Use the responseFields argument carefully when retrieving and then modifying a resource, as you can inadvertently delete data. For example, if you use the responseFields argument to retrieve a subset of a resource, make changes to that subset, and then update the resource with the new subset without using the same responseFields argument again, the entire resource may be overwritten with only the subset of data. In general, the responseFields argument is recommended for retrieving select data to display or modify on the storefront, and for selectively updating data. It is not generally recommended for retrieving API resources you intend to modify or process before updating the original object with the changes.

​
HTTP Request Syntax

To use the responseFields argument, include it in the GET or PUT HTTP request. For example, the following line shows the placement of the argument for the GetProduct operation request: GET api/commerce/catalog/admin/products/{productCode}?responseFields={responseFields} The responseFields argument is optional, and if no value is provided, then the entire resource is retrieved or updated. Not every PUT operation supports the responseFields argument. Consult the API reference documentation for details on a specific operation.

​
Basic Example: Include Single Property

The simplest use of the responseFields argument is to retrieve one specific property.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=a1 API Object 
{
    "a1": "value",
    "a2": "value",
    "a3": "value"
}
Payload Response 
{
    "a1": "value",
}

​
Include Multiple Properties

Similar to the single property example, you can retrieve or update multiple properties at a time by separating them with a comma.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=a1,a3 API Object 
{
    "a1": "value",
    "a2": "value",
    "a3": "value"
}
Payload Response 
{
    "a1": "value",
    "a3": "value"
}

​
Exclude Properties

You can exclude one or more properties to retrieve or update by using the negative sign operator.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=-a2 API Object 
{
    "a1": "value",
    "a2": "value",
    "a3": "value"
}
Payload Response 
{
    "a1": "value",
    "a3": "value"
}

​
Include and Exclude Properties

You can specify properties to include and exclude within the same argument by combining commas and negative sign operators.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=a1,-a3,a4 API Object 
{
    "a1": "value",
    "a2": "value",
    "a3": "value",
    "a4": "value"
}
Payload Response 
{
    "a1": "value",
    "a4": "value"
}

​
Include Wildcards

You can use an asterisk to include properties that are otherwise not explicitly included or excluded in the argument.

​
Example

Argument To Use The following three arguments all return the same payload. GET api/_endpointPath_/?responseFields=a1,-a2,* GET api/_endpointPath_/?responseFields=-a2,a3,* GET api/_endpointPath_/?responseFields=*,-a2 API Object 
{
    "a1": "value",
    "a2": "value",
    "a3": "value"
}
Payload Response 
{
    "a1": "value",
    "a3": "value"
}

​
Arrays

The responseField argument works the same for arrays as it does for simple structures. You can include and exclude arrays, as well as use the asterisk symbol to denote wildcards.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=a1,-a3,* API Object 
{
    "a1": [ "value1", "value2" ],
    "a2": [ "value1", "value2" ],
    "a3": [ "value1", "value2" ]
}
Payload Response 
{
    "a1": [ "value1", "value2" ],
    "a2": [ "value1", "value2" ]
}

​
Include Specific Subresources

The majority of API objects are composed of nested subresources. You can use a forward slash character in the responseFields argument to include only certain subresources.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=a1/b2 API Object 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}
Payload Response 
{
    "a1": {
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}

​
Include Subresources at any Depth

You can limit inclusion of subresources down to any depth necessary by stringing forward slashes together.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=a1/b2/c1 API Object 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}
Payload Response 
{
    "a1": {
        "b2": {
            "c1": "value1"
        }
    }
}

​
Exclude Subresources

You can exclude subresources at any depth using the negative sign operator.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=a1/b2/-c1 API Object 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}
Payload Response 
{
    "a1": {
        "b2": {
            "c2": "value2",
            "c3": "value3"
        }
    }
}

​
Include a Subset of Subresources

You can use parentheses to include a subset of subresources. Only the fields between the parentheses are retrieved or updated. Using parentheses instead of forward slashes may be more convenient depending on your use case.

​
Example

Argument To Use GET api/_endpointPath_/?responseFields=a1(b1,b2(c2)) API Object 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}
Payload Response 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c2": "value2"
        }
    }
}

​
Syntax Combinations

The responseFields argument lets you combine the syntax operators in the aforementioned sections to achieve powerful and flexible inclusions and exclusions. The following examples in this section demonstrate several example scenarios to give you an idea of how flexible the responseFields argument is:

​
Combination: Asterisks and Parentheses

Argument To Use GET api/_endpointPath_/?responseFields=a1(*,b2(c1)) API Object 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}
Payload Response 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1"
        }
    }
}

​
Combination: Forward Slashes, and Parentheses

Argument To Use GET api/_endpointPath_/?responseFields=a1/b2(c1,c2) API Object 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}
Payload Response 
{
    "a1": {
        "b2": {
            "c1": "value1",
            "c2": "value2"
        }
    }
}

​
Combination: Asterisks, Forward Slashes, and Parentheses

Argument To Use GET api/_endpointPath_/?responseFields=a1(*,b2/c1) API Object 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}
Payload Response 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1"
        }
    }
}

​
Combination: Negation, Asterisks, Forward Slashes, and Parentheses

Argument To Use GET api/_endpointPath_/?responseFields=a1(*,b2(-c2,-c3)) API Object 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1",
            "c2": "value2",
            "c3": "value3"
        }
    }
}
Payload Response 
{
    "a1": {
        "b1": "value",
        "b2": {
            "c1": "value1"
        }
    }
}

​
Combination: Arrays

Argument To Use GET api/_endpointPath_/?responseFields=a1(b1/c1,*) API Object 
{
    "a1" : [
        { 
            "b1" : {
                "c1" : "value",
                "c2" : "value",
                "c3" : "value"
            },
            "b2" : "value"
        },
        { 
            "b1" : {
                "c1" : "value1",
                "c2" : "value2",
                "c3" : "value3"
            },
            "b2" : "value"
        }
    ]
}
Payload Response 
{
    "a1" : [
        { 
            "b1" : {
                "c1" : "value"
            },
            "b2" : "value"
        },
        { 
            "b1" : {
                "c1" : "value1"
            },
            "b2" : "value"
        }
    ]
}