Fields and Expand Query Parameters

Most of the Shopper APIs support query parameters. When you add parameters to a request, you modify the results in ways such as changing the resource representation, refining your query, and paginating the results. Some query parameters modify the resource by changing the locale or pricing information. The API returns a default set of fields for each resource you request. You can override the default fields returned by using the fields and expand query parameters when the default fields does not meet your specific needs.

Fields Query Parameter

Use the fields query parameter to filter the fields that appear in a response to just the fields you specifically request. Filtering the fields returned in a response can conserve bandwidth and accelerate response time.

The following example gets an authenticated shopper to see what fields are available by default. Line numbers 8 to 11 display links that are only available for an authenticated shopper.

URI: GET /v1/shoppers/me

1   <?xml version="1.0" encoding="UTF-8"?>
2.  <shopper uri="">
3.     <id>161784673509</id>
4.     <username>jsmith</username>
5.     <firstname>John</firstname>
6.     <lastname>Smith</lastname>
7.     <emailaddress></emailaddress>
8.     <paymentoptions uri="https:// v1/shoppers/me/payment-options"/>
9.     <addresses uri=""/>
10.    <orders uri=""/>
11.    <subscriptions uri=""/>
12. </shopper>

The next example gets the same shopper's first and last name only. Notice that the response only includes the fields you specified.

URI: GET /v1/shoppers/me?fields=firstName,lastName

<?xml version="1.0" encoding="UTF-8"?>
<shopper uri="">

Expand Query Parameter

Use the expand query parameter when you need additional information. The expand query parameter increases the set of fields that appear in the response in addition to the default fields. Expanding resources reduces the number of API calls required to accomplish a task.

The following example gets the same shopper and requests specific resource fields: locale and currency. Line numbers 8 and 9 show the locale and currency for the shopper in the response.

URI: GET /v1/shoppers/me?expand=locale,currency

1.  <?xml version="1.0" encoding="UTF-8"?>
2.  <shopper uri="">
3.    <id>161784673509</id>
4.    <username>jsmith</username>
5.    <firstname>John</firstname>
6.    <lastname>Smith</lastname>
7.    <emailaddress></emailaddress>
8.    <locale>en_US</locale>
9.    <currency>USD</currency>
10.   <paymentoptions uri="https:// v1/shoppers/me/payment-options"/>
11.   <addresses uri=""/>
12.   <orders uri=""/>
13.   <subscriptions uri=""/>    
14. </shopper>

The next example gets the same shopper and requests all the fields with expand=all

Best Practices: Avoid using the expand=all parameter if you want to reduce the information returned and ensure optimal performance.

As you can see in this example, there are more fields available with full expansion of a resource. Notice that an authenticated shopper session also provides links (non-expandable) to orders and subscriptions. You can expand addresses and payment options; however, for orders and subscriptions, you must make follow-up calls.

URI: GET /v1/shoppers/me?expand=all

1.  <?xml version="1.0" encoding="UTF-8"?>
2.  <shopper uri="">
3.     <id>161784673509</id>
4.     <username>jsmith</username>
5.     <externalreferenceid>123456</externalreferenceid>
6.     <firstname>John</firstname>
7.     <lastname>Smith</lastname>
8.     <emailaddress></emailaddress>
9.     <locale>en_US</locale>
10.    <currency>USD</currency>
11.    <sendmail>false</sendmail>
12.    <sendemail>true</sendemail>
13.    <paymentoptions uri="">
14.       <paymentoption uri="">
15.          <id>1695808409</id>
16.          <nickname>Default</nickname>
17.          <isdefault>true</isdefault>
18.          <creditcard>
19.             <expirationmonth>5</expirationmonth>
20.             <expirationyear>2017</expirationyear>
21.             <issuecode>
22.             <startmonth>
23.             <startyear>
24.             <displayablenumber>************1111</displayablenumber>
25.             <type>Visa</type>
26.          </startyear></startmonth></issuecode></creditcard>
27.       </paymentoption>
28,    </paymentoptions>
29.    <addresses uri=""><address uri="">
30.            <id>2268768209</id>
31.            <nickname>Office address</nickname>
32.            <isdefault>true</isdefault>
33.            <firstname>John</firstname>
34.            <lastname>Smith</lastname>
35.            <companyname>Acme Inc.</companyname>
36.            <line1>1234 Main Street</line1>
37.            <line2>Suite 1</line2>
38.            <line3>Building D</line3>
39.            <city>Eden Prairie</city>
40.            <countrysubdivision>MN</countrysubdivision>
41.            <postalcode>55344-3765</postalcode>
42.            <country>US</country>
43.            <countryname>United States</countryname>
44.            <phonenumber>952-123-1234</phonenumber>
45.            <countyname>
46.          </countyname></address>
47.    </addresses>
48.   <orders uri=""/>
49.   <subscriptions uri=""/>
50. </shopper>

Parameter Precedence

The expand parameter with a value of all overrides the fields parameter when both are specified within a URL. For example, the results for GET v1/shoppers/me?fields=firstName&expand=all returns all fields for a shopper.