Salesforce B2C Commerce 24.7 > Open Commerce API 23.2 > Shop API resources 23.2

ProductLists resource (Shop API 23.2)

Summary

Http Method Resource Description
GET /product_lists Retrieves all public product lists as defined by the given search term (email, first name, last name).
GET /product_lists/{list_id} Retrieves a public product list by id.
GET /product_lists/{list_id}/items Retrieves the items of a public product list.
GET /product_lists/{list_id}/items/{item_id} Retrieves an item from a public product list.

Get list of product lists

Retrieves all public product lists as defined by the given search term (email, first name, last name).

Url

GET https://hostname:port/dw/shop/v23_2/product_lists?email={String}&firstname={String}&lastname={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT.
None No authentication.

Response Document

PublicProductListResult

Query Parameters

Parameter Type Description Constraints
email String The email address of the customer, the product lists belong to.  
firstname String The first name of the customer, the product lists belong to.  
lastname String The last name of the customer, the product lists belong to.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 ProductListSearchTermException   Indicates that the anonymous customer did not provide a proper search term.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.product_lists.beforeGET

beforeGET (email : String , firstName : String , lastName : String ) : Status

The function is called before the request will be processed.

Parameters:
email - The email address of the customer, the product lists belong to.
firstName - The first name of the customer, the product lists belong to.
lastName - The last name of the customer, the product lists belong to.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.product_lists.modifyGETResponse

modifyGETResponse (publicProductListResultResponse : PublicProductListResult ) : Status

Parameters:
publicProductListResultResponse - public product list result response object.
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/product_lists?firstname=john&lastname=doe HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 

RESPONSE:
Cache-Control:max-age=0,no-cache,no-store,must-revalidate
Keep-Alive:timeout=15, max=99
Connection:Keep-Alive
Content-Type:application/json;charset=UTF-8
Content-Length:483
{
   "_v" : "23.2",
   "count" : 2,
   "data" : 
   [
      
      {
         "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "href" : "https://example.com/dw/shop/v23_2/product_lists/cd2Id9aaabTQYaaadj9vRpVGwg",
         "name" : "WAPI-Wedding",
         "public" : false,
         "title" : "Wedding",
         "type" : "gift_registry"
      },
      
      {
         "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
         "href" : "https://example.com/dw/shop/v23_2/product_lists/ghjMV9aaab9d2aaafjycppVGwe",
         "public" : false,
         "title" : "Wish List",
         "type" : "wish_list"
      }
   ],
   "total" : 2
}

Get product list

Retrieves a public product list by id.

Url

GET https://hostname:port/dw/shop/v23_2/product_lists/{list_id}?expand={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT.
None No authentication.

Response Document

PublicProductList

Path Parameters

Parameter Type Description Constraints
list_id String The id of the list. mandatory=true, maxLength=28, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
expand String The possible expansions - items, product, images, availability. The product information is included in the product list items that is why the product expansion has to be done together with items expansion. For images and availability both product and items have to be expanded as well.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 ProductListNotFoundException

productListId (String)

 Indicates that this list doesn't exist.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.product_list.beforeGET

beforeGET (listId : String ) : Status

The function is called before the request will be processed.

Parameters:
listId - The id of the list.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.product_list.modifyGETResponse

modifyGETResponse (productList : ProductList , publicProductListResponse : PublicProductList ) : Status

Parameters:
productList - product list.
publicProductListResponse - public product list response object.
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/product_lists/cdmeh9aaabqtwaaadjcLADJaTY?expand=items,product,availability,images HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 

# in case of success (own list):
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "co_registrant" : 
   {
      "email" : "[email protected]",
      "first_name" : "Jane",
      "last_name" : "Doe",
      "role" : "Bride"
   },
   "current_shipping_address_link" : 
   {
      "link" : "https://example.com/dw/shop/v23_2/customers/f93jdf93jdfd/addresses/me",
      "title" : "me, John Doe, Woburn"
   },
   "event" : 
   {
      "city" : "Washington",
      "country" : "US",
      "date" : "2015-07-30T00:00Z",
      "state" : "DC",
      "type" : "Wedding"
   },
   "id" : "bcqg6iWbw4XEYaaadjixFLTWP0",
   "items_link" : 
   {
      "link" : "https://example.com/dw/shop/v23_2/product_lists/bcqg6iWbw4XEYaaadjixFLTWP0/items",
      "title" : "2 items"
   },
   "name" : "DC-Doe-Wedding",
   "post_event_shipping_address_link" : 
   {
      "link" : "https://example.com/dw/shop/v23_2/customers/f93jdf93jdfd/addresses/jane",
      "title" : "jane, Jane Doe, Springfield"
   },"product_list_items" : 
   [
      
      {
         "_type" : "public_product_list_item",
         "id" : "50f50f608aa9ff2fbf9272ed7e",
         "priority" : 2,
         "product" : 
         {
            "_type" : "product",
            "id" : "BlueJeans1",
            "inventories" : 
            [
               
               {
                  "_type" : "inventory",
                  "ats" : 100,
                  "backorderable" : false,
                  "id" : "BlueJeans1Inventory",
                  "orderable" : true,
                  "preorderable" : false,
                  "stock_level" : 100
               }
            ],
            "min_order_quantity" : 1,
            "step_quantity" : 1
         },
         "product_details_link" : 
         {
            "_type" : "product_details_link",
            "link" : "https://example.com/dw/shop/v23_2/products/BlueJeans1?expand=items%2Cproduct%2Cavailability%2Cimages",
            "product_id" : "BlueJeans1",
            "product_name" : "Product w/- Local Option",
            "title" : "Product w/- Local Option"
         },
         "type" : "product"
      },
      
      {
         "_type" : "public_product_list_item",
         "id" : "2ab5aa2a2e050f1b7fd9463af1",
         "priority" : 3,
         "product" : 
         {
            "_type" : "product",
            "id" : "BlackJeans1",
            "inventories" : 
            [
               
               {
                  "_type" : "inventory",
                  "ats" : 999999,
                  "backorderable" : false,
                  "id" : "BlackJeans1Inventory",
                  "orderable" : true,
                  "preorderable" : false,
                  "stock_level" : 999999
               }
            ],
            "min_order_quantity" : 1,
            "step_quantity" : 1
         },
         "product_details_link" : 
         {
            "_type" : "product_details_link",
            "link" : "https://example.com/dw/shop/v23_2/products/BlackJeans1?expand=items%2Cproduct%2Cavailability%2Cimages",
            "product_id" : "BlackJeans1",
            "product_name" : "Simple Web API Product",
            "title" : "Black Jeans"
         },
         "type" : "product"
      },
      
      {
         "_type" : "public_product_list_item",
         "id" : "09c9df175e247c0d75d76f443e",
         "priority" : 6,
         "product" : 
         {
            "_type" : "product",
            "id" : "RedDress1",
            "image_groups" : 
            [
               
               {
                  "_type" : "image_group",
                  "images" : 
                  [
                     
                     {
                        "_type" : "image",
                        "alt" : "ALT master detail",
                        "link" : "https://example.com/foo/bar/master_detail.jpg",
                        "title" : "TITLE master detail"
                     }
                  ],
                  "view_type" : "detail"
               },
               
               {
                  "_type" : "image_group",
                  "images" : 
                  [
                     
                     {
                        "_type" : "image",
                        "alt" : "ALT main swatch",
                        "link" : "https://example.com/foo/bar/main_swatch.jpg",
                        "title" : "TITLE main swatch"
                     }
                  ],
                  "view_type" : "swatch"
               },
               
               {
                  "_type" : "image_group",
                  "images" : 
                  [
                     
                     {
                        "_type" : "image",
                        "alt" : "ALT master thumbnail",
                        "link" : "https://example.com/foo/bar/master_thumbnail.jpg",
                        "title" : "TITLE master thumbnail"
                     }
                  ],
                  "view_type" : "thumbnail"
               }
            ],
            "inventories" : 
            [
               
               {
                  "_type" : "inventory",
                  "ats" : 0,
                  "backorderable" : false,
                  "id" : "RedDress1Inventory",
                  "orderable" : false,
                  "preorderable" : false,
                  "stock_level" : 0
               }
            ],
            "min_order_quantity" : 1,
            "step_quantity" : 1
         },
         "product_details_link" : 
         {
            "_type" : "product_details_link",
            "link" : "https://example.com/dw/shop/v23_2/products/RedDress2?expand=items%2Cproduct%2Cavailability%2Cimages",
            "product_id" : "RedDress2",
            "product_name" : "Red Dress 2",
            "title" : "Red Dress"
         },
         "type" : "product"
      }
   ],
   "public": true, 
   "registrant" : 
   {
      "email" : "[email protected]",
      "first_name" : "John",
      "last_name" : "Doe",
      "role" : "Groom"
   },
   "shipping_address_link" : 
   {
      "link" : "https://example.com/dw/shop/v23_2/customers/f93jdf93jdfd/addresses/me",
      "title" : "me, John Doe, Woburn"
   },
   "type" : "gift_registry"
}

# in case of failure (list not found):
 
RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "The product list with ID 'cdmeh9aaabqtwaaadjcLADJaTZ' was not found."
   }
}

Get product list items

Retrieves the items of a public product list.

Url

GET https://hostname:port/dw/shop/v23_2/product_lists/{list_id}/items?expand={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT.
None No authentication.

Response Document

PublicProductListItemResult

Path Parameters

Parameter Type Description Constraints
list_id String The id of the list. mandatory=true, maxLength=28, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
expand String The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 ProductListNotFoundException

productListId (String)

 Indicates that this list doesn't exist.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.product_list.items.beforeGET

beforeGET (listId : String ) : Status

The function is called before the request will be processed.

Parameters:
listId - The id of the list.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.product_list.items.modifyGETResponse

modifyGETResponse_v2 (productList : ProductList , publicProductListItemResultResponse : PublicProductListItemResult ) : Status

Parameters:
productList - the product list the items are retrieved for.
publicProductListItemResultResponse - public product list item result response object.
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/product_lists/cdmeh9aaabqtwaaadjcLADJaTY/items?expand=items,product,availability,images HTTP/1.1
Host: example.com
Content-Type: application/json; charset=UTF-8
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 

# in case of success
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "count" : 2,
   "data" : 
   [
      
      {
         "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "id" : "cdPIB9aaabYFEaaadjOdBoMrMt",
         "position" : -1,
         "priority" : 2,
         "product_details_link" : 
         {
            "link" : "https://example.com/dw/shop/v23_2/products/008884303989?locale=en-US",
            "product_id" : "008884303989",
            "product_name" : "Platinum Blue Stripes Easy Care Fitted Shirt",
            "title" : "Platinum Blue Stripes Easy Care Fitted Shirt"
         },
         "public" : true,
         "purchased_quantity" : 0,
         "quantity" : 10,
         "type" : "product"
      },
      
      {
         "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
         "id" : "cdH9N9aaabYFIaaadjOdBoMrMt",
         "position" : -1,
         "priority" : 2,"product" : 
         {
            "_type" : "product",
            "id" : "BlueShirt",
            "image_groups" : 
            [
               
               {
                  "_type" : "image_group",
                  "images" : 
                  [
                     
                     {
                        "_type" : "image",
                        "alt" : "ALT master detail",
                        "link" : "https://example.com/foo/bar/master_detail.jpg",
                        "title" : "TITLE master detail"
                     }
                  ],
                  "view_type" : "detail"
               },
               
               {
                  "_type" : "image_group",
                  "images" : 
                  [
                     
                     {
                        "_type" : "image",
                        "alt" : "ALT main swatch",
                        "link" : "https://example.com/foo/bar/main_swatch.jpg",
                        "title" : "TITLE main swatch"
                     }
                  ],
                  "view_type" : "swatch"
               },
               
               {
                  "_type" : "image_group",
                  "images" : 
                  [
                     
                     {
                        "_type" : "image",
                        "alt" : "ALT master thumbnail",
                        "link" : "https://example.com/foo/bar/master_thumbnail.jpg",
                        "title" : "TITLE master thumbnail"
                     }
                  ],
                  "view_type" : "thumbnail"
               }
            ],
            "inventories" : 
            [
               
               {
                  "_type" : "inventory",
                  "ats" : 0,
                  "backorderable" : false,
                  "id" : "BlueShirtInventory",
                  "orderable" : false,
                  "preorderable" : false,
                  "stock_level" : 0
               }
            ],
         "product_details_link" : 
         {
            "link" : "https://example.com/dw/shop/v23_2/products/008885535488?locale=en-US",
            "product_id" : "008885535488",
            "product_name" : "Must Have Washable No-Iron Georgette Blouse",
            "title" : "Must Have Washable No-Iron Georgette Blouse"
         },
         "public" : false,
         "purchased_quantity" : 0,
         "quantity" : 1,
         "type" : "product"
      }
   ],
   "total" : 2
}

# in case of failure (list not found):
 
RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "The product list with ID 'cdmeh9aaabqtwaaadjcLADJaTZ' not found."
   }
}

Get product list item

Retrieves an item from a public product list.

Url

GET https://hostname:port/dw/shop/v23_2/product_lists/{list_id}/items/{item_id}?expand={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT.
None No authentication.

Response Document

PublicProductListItem

Path Parameters

Parameter Type Description Constraints
item_id String The id of the item. mandatory=true, minLength=1, nullable=false
list_id String The id of the list. mandatory=true, maxLength=28, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
expand String The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 ProductListNotFoundException

productListId (String)

 Indicates that this list doesn't exist.
404 ProductListItemNotFoundException

itemId (String)

 Indicates that this product list item doesn't exist.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.product_list.item.beforeGET

beforeGET (listId : String , itemId : String ) : Status

The function is called before the request will be processed.

Parameters:
listId - The id of the list.
itemId - The id of the item.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.product_list.item.modifyGETResponse

modifyGETResponse (productList : ProductList , productListItem : ProductListItem , publicProductListItemResponse : PublicProductListItem ) : Status

Parameters:
productList - product list.
productListItem - product list item.
publicProductListItemResponse - public product list item response object.
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/product_lists/cdmeh9aaabqtwaaadjcLADJaTY/items/50f50f608aa9ff2fbf9272ed7e&expand=product,availability,images HTTP/1.1
Host: example.com
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "_type" : "public_product_list_item",
   "id" : "50f50f608aa9ff2fbf9272ed7e",
   "priority" : 2,
   "product" : 
   {
      "_type" : "product",
      "id" : "BlueJeans",
      "image_groups" : 
      [
         
         {
            "_type" : "image_group",
            "images" : 
            [
               
               {
                  "_type" : "image",
                  "alt" : "ALT master detail",
                  "link" : "https://example.com/foo/bar/master_detail.jpg",
                  "title" : "TITLE master detail"
               }
            ],
            "view_type" : "detail"
         },
         
         {
            "_type" : "image_group",
            "images" : 
            [
               
               {
                  "_type" : "image",
                  "alt" : "ALT main swatch",
                  "link" : "https://example.com/foo/bar/main_swatch.jpg",
                  "title" : "TITLE main swatch"
               }
            ],
            "view_type" : "swatch"
         },
         
         {
            "_type" : "image_group",
            "images" : 
            [
               
               {
                  "_type" : "image",
                  "alt" : "ALT master thumbnail",
                  "link" : "https://example.com/foo/bar/master_thumbnail.jpg",
                  "title" : "TITLE master thumbnail"
               }
            ],
            "view_type" : "thumbnail"
         }
      ],
      "inventories" : 
      [
         
         {
            "_type" : "inventory",
            "ats" : 0,
            "backorderable" : false,
            "id" : "BlueJeansInventory",
            "orderable" : false,
            "preorderable" : false,
            "stock_level" : 0
         }
      ],
      "min_order_quantity" : 1,
      "step_quantity" : 1
   },
   "product_details_link" : 
   {
      "_type" : "product_details_link",
      "link" : "https://example.com/dw/shop/v23_2/products/BlueJeansType1",
      "product_id" : "BlueJeansType1",
      "product_name" : "Product w/- Local Option",
      "title" : "Product w/- Local Option"
   },
   "quantity" : 99.0,
   "type" : "product"
}

Infocenter Retirement: On June 30, 2023, the Infocenter was retired, and documentation currently hosted on the Infocenter will be published to Salesforce Help, Commerce Cloud Developer Center, and Salesforce B2C Commerce Developer Documentation Resources. For more information, see the release note.

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.