Edit in GitHubLog an issue

Retrieve filtered responses for REST endpoints

Some REST calls return dozens or even hundreds of parameters, and parsing through all this data can be unwieldy. In addition, mobile app developers might find the bandwidth needed to process a request to be excessive. To resolve these problems, Adobe Commerce provides a query parameter-based syntax for REST requests that return partial responses.

You can append ?fields=<field_or_object1>,<field_or_object2>,... to any GET, POST, or PUT operation to filter unimportant information from the response. <field_or_object> can be any of the following:

  • Simple top-level field
  • Top-level object that includes all fields
  • Top-level object with selected fields
  • Nested objects

Separate each field or object with a comma.

On POST and PUT requests, Commerce ignores the fields parameter as input, but the response includes only the requested fields and objects.

Examples#

All examples use Luma sample data.

Simple fields#

The following example returns only the sku, price, and name for the specified product:

GET <host>/rest/<store_code>/V1/products/24-MB01?fields=sku,price,name

Copied to your clipboard
1{
2 "sku": "24-MB01"
3 "name": "Joust Duffle Bag"
4 "price": 24.99
5}

Simple fields and top-level objects with all fields#

The following example returns only the customer first name, last name, and the entire billing_address object from a specified order. Do not include brackets [] after an object name when you want to return all of the object's contents.

GET <host>/rest/<store_code>/V1/orders/2?fields=billing_address,customer_firstname,customer_lastname

Copied to your clipboard
1{
2"customer_firstname": "Veronica"
3"customer_lastname": "Costello"
4"billing_address": {
5 "address_type": "billing"
6 "city": "Calder"
7 "country_id": "US"
8 "customer_address_id": 1
9 "email": "roni_cost@example.com"
10 "entity_id": 4
11 "firstname": "Veronica"
12 "lastname": "Costello"
13 "parent_id": 2
14 "postcode": "49628-7978"
15 "region": "Michigan"
16 "region_code": "MI"
17 "region_id": 33
18 "street": "6146 Honey Bluff Parkway"
19 "telephone": "(555) 229-3326"
20 }
21}

Top-level object with selected fields#

The following example returns only the name, qty, and sku fields defined in an items object from a specified shipment:

GET <host>/rest/<store_code>/V1/shipment/2?fields=items[name,qty,sku]

Copied to your clipboard
1"items": [
2 {
3 "name": "Minerva LumaTech&trade; V-Tee-XS-Blue",
4 "qty": 1,
5 "sku": "WS08-XS-Blue",
6 }
7]

Nested objects#

This example returns only the following:

  • The product's sku and name
  • The entire category_links object, which is defined in extension_attributes
  • The item_id and qty fields of the stock_item object, which is also defined in extension_attributes

GET <host>/rest/<store_code>/V1/products/MT12?fields=name,sku,extension_attributes[category_links,stock_item[item_id,qty]]

Copied to your clipboard
1{
2 "sku": "MT12"
3 "name": "Cassius Sparring Tank"
4 "extension_attributes": {
5 "category_links": {
6 "position": 1
7 "category_id": "18"
8 }
9 "stock_item": {
10 "item_id": 732
11 "qty": 0
12 }
13 }
14}

POST operation#

The following POST operation and payload creates a catalog category named New Category. Commerce returns only the id, parent_id, and name attributes

POST <host>/rest/<store_code>/V1/categories?fields=id,parent_id,name

Payload:

Copied to your clipboard
1{
2 "category": {
3 "name": "New Category",
4 "is_active": true
5 }
6}

Response:

Copied to your clipboard
1{
2"id": 43
3"parent_id": 2
4"name": "New Category"
5}

Using with searchCriteria#

The searchCriteria query parameter allows you to search across multiple objects in a collection. You can use the fields query parameter in conjunction with searchCriteria to limit the output. The question mark (?) that precedes fields in all the other examples in this document is replaced with an ampersand (&).

The following query returns only the sku and name parameters for product items whose category_gear attribute includes the value 86.

GET <host>/rest/<store_code>/V1/products/?searchCriteria[filter_groups][0][filters][0][field]=category_gear&searchCriteria[filter_groups][0][filters][0][value]=86&searchCriteria[filter_groups][0][filters][0][condition_type]=finset&fields=items[sku,name]

Copied to your clipboard
1{
2"items":
3 {
4 "sku": "24-MG04"
5 "name": "Aim Analog Watch"
6 }
7 {
8 "sku": "24-MG01"
9 "name": "Endurance Watch"
10 }
11 {
12 "sku": "24-MG03"
13 "name": "Summit Watch"
14 }
15 {
16 "sku": "24-MG05"
17 "name": "Cruise Dual Analog Watch"
18 }
19 {
20 "sku": "24-MG02"
21 "name": "Dash Digital Watch"
22 }
23 {
24 "sku": "24-WG09"
25 "name": "Luma Analog Watch"
26 }
27 {
28 "sku": "24-WG01"
29 "name": "Bolo Sport Watch"
30 }
31 {
32 "sku": "24-WG03"
33 "name": "Clamber Watch"
34 }
35 {
36 "sku": "24-WG02"
37 "name": "Didi Sport Watch"
38 }
39}

Related topics#

  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.