Search…
Fields and expand query parameters
Learn how to use field and expand query parameters.
Most of the Shoppers resources 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 do 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 the response can conserve bandwidth and accelerate response time.
The following example gets the fields are available by default to an authenticated customer. Line numbers 8 to 21 display links that are only available for an authenticated customer.
URI
JSON
1
GET /v1/shoppers/me
Copied!
1
{
2
"shopper": {
3
"id": "161784673509",
4
"username": "jsmith",
5
"firstname": "John",
6
"lastname": "Smith",
7
"emailaddress": "[email protected]",
8
"paymentoptions": {
9
"_uri": "https:// api.digitalriver.com v1/shoppers/me/payment-options"
10
},
11
"addresses": {
12
"_uri": "https://api.digitalriver.com/v1/shoppers/me/addresses"
13
},
14
"orders": {
15
"_uri": "https://api.digitalriver.com/v1/shoppers/me/orders"
16
},
17
"subscriptions": {
18
"_uri": "https://api.digitalriver.com/v1/shoppers/me/subscriptions"
19
},
20
"_uri": "https://api.digitalriver.com/v1/shoppers/me"
21
}
22
}
Copied!
The next example gets the same customer's first and last name only. Notice that the response only includes the fields you specified.
URI
JSON
1
GET /v1/shoppers/me?fields=firstName,lastName
Copied!
1
{
2
"shopper": {
3
"firstname": "John",
4
"lastname": "Smith",
5
"_uri": "https://api.digitalriver.com/v1/shoppers/me"
6
}
7
}
Copied!

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 customer and requests specific resource fields: locale and currency. Line numbers 8 and 9 show the locale and currency for the customer in the response.
Plain Text
Untitled
1
GET /v1/shoppers/me?expand=locale,currency
Copied!
1
1. {
2
2. "shopper": {
3
3. "id": "161784673509",
4
4. "username": "jsmith",
5
5. "firstname": "John",
6
6. "lastname": "Smith",
7
7. "emailaddress": "[email protected]",
8
8. "locale": "en_US",
9
9. "currency": "USD",
10
10. "paymentoptions": {
11
11. "_uri": "https:// api.digitalriver.com v1/shoppers/me/payment-options"
12
12. },
13
13. "addresses": {
14
14. "_uri": "https://api.digitalriver.com/v1/shoppers/me/addresses"
15
15. },
16
16. "orders": {
17
17. "_uri": "https://api.digitalriver.com/v1/shoppers/me/orders"
18
18. },
19
19. "subscriptions": {
20
20. "_uri": "https://api.digitalriver.com/v1/shoppers/me/subscriptions"
21
21. },
22
22. "_uri": "https://api.digitalriver.com/v1/shoppers/me"
23
23. }
24
24. }
Copied!
The next example gets the same customer and requests all the fields with expand=all.
Tip: 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 customer 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
JSON
1
GET /v1/shoppers/me?expand=all
Copied!
1
1. {
2
2. "shopper": {
3
3. "id": "161784673509",
4
4. "username": "jsmith",
5
5. "externalreferenceid": "123456",
6
6. "firstname": "John",
7
7. "lastname": "Smith",
8
8. "emailaddress": "[email protected]",
9
9. "locale": "en_US",
10
10. "currency": "USD",
11
11. "sendmail": "false",
12
12. "sendemail": "true",
13
13. "paymentoptions": {
14
14. "paymentoption": {
15
15. "id": "1695808409",
16
16. "nickname": "Default",
17
17. "isdefault": "true",
18
18. "creditcard": {
19
19. "expirationmonth": "5",
20
20. "expirationyear": "2017",
21
21. "issuecode": {
22
22. "startmonth": {
23
23. "startyear": {
24
24. "displayablenumber": "************1111",
25
25. "type": "Visa"
26
26. }
27
27. }
28
28. }
29
29. },
30
30. "_uri": "https://api.digitalriver.com/v1/shoppers/me/payment-option/1695808409"
31
32. },
32
32. "_uri": "https://api.digitalriver.com/v1/shoppers/me/payment-options"
33
33. },
34
34. "addresses": {
35
35. "address": {
36
36. "id": "2268768209",
37
37. "nickname": "Office address",
38
38. "isdefault": "true",
39
39. "firstname": "John",
40
40. "lastname": "Smith",
41
41. "companyname": "Acme Inc.",
42
42. "line1": "1234 Main Street",
43
43. "line2": "Suite 1",
44
44. "line3": "Building D",
45
45. "city": "Eden Prairie",
46
46. "countrysubdivision": "MN",
47
47. "postalcode": "55344-3765",
48
48. "country": "US",
49
49. "countryname": "United States",
50
50. "phonenumber": "952-123-1234",
51
51. "countyname": "",
52
52. "_uri": "https://api.digitalriver.com/v1/shoppers/me/address/2268768209"
53
53. },
54
54. "_uri": "https://api.digitalriver.com/v1/shoppers/me/addresses"
55
55. },
56
56. "orders": {
57
57. "_uri": "https://api.digitalriver.com/v1/shoppers/me/orders"
58
58. },
59
59. "subscriptions": {
60
60. "_uri": "https://api.digitalriver.com/v1/shoppers/me/subscriptions"
61
61. },
62
62. "_uri": "https://api.digitalriver.com/v1/shoppers/me"
63
63. }
64
64. }
Copied!

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 customer.
Last modified 1yr ago