Products Resource (Data API 17.2)

Summary

Http Method	Resource	Description
GET	/Products/{Id}	Action to get product information.
DELETE	/Products/{Id}	Deletes the product by ID
PUT	/Products/{Id}	Creates a product using the information provided. If a product with the same unique identifier, it will be cleaned and overwritten unless the header x-dw-validate-existing=true is passed in with the request.
PATCH	/Products/{Id}	Update a product using the information provided. Fields that can be updated: name, page_description, long_descripton, page_title, page_keywords, brand, ean,upc, manufacture_sku, manufacture_name, searchable, unit, searchable, online_flag, default_variant_id.
GET	/Products/{Id}/Variations	Reads variations(variants) within a product of type variation master or variation group.
GET	/Products/{Master_product_id}/Variation_groups	Reads variation groups for a product master.
GET	/Products/{Product_id}/Variation_attributes	Reads variation attributes of a product of type variant or variation master or variation group.

Get Product

Action to get product information.

Url

GET https://hostname:port/dw/data/v17_2/products/{id}?site_id={String}&expand={String}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Response Document

Product

Path Parameters

Parameter	Type	Description	Constraints
id	String	The product ID.	minLength=1

Query Parameters

Parameter	Type	Description	Constraints
expand	String	The list of expansions that can be applied to the product. They are: 'all' will retrieve all the product properties. 'availability' will retrieve the following properties: ats in_stock online 'images' will retrieve the following properties: image image_groups 'all_images' used with images will retrieve the following properties, including the images specified for its variants and variation groups: image image_groups 'prices' will retrieve the following properties: price price_currency 'variations' will retrieve the following properties: master variation_attributes variation_groups variation_values variants Note that only variants with variation values are retrieved for a product of type variation master.
site_id	String	The site context.

Parameter

Type

Description

Constraints

expand

String

The list of expansions that can be applied to the product. They are:

'all' will retrieve all the product properties.
'availability' will retrieve the following properties:
- ats
- in_stock
- online
'images' will retrieve the following properties:
- image
- image_groups
'all_images' used with images will retrieve the following properties, including the images specified for its variants and variation groups:
- image
- image_groups
'prices' will retrieve the following properties:
- price
- price_currency
'variations' will retrieve the following properties:
- master
- variation_attributes
- variation_groups
- variation_values
- variants

Note that only variants with variation values are retrieved for a product of type variation master.

site_id

String

The site context.

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`ProductNotFoundException`	productId (String)	Indicates the product is not found.

Sample

REQUEST:
GET  /s/-/dw/data/v17.2/products/my-product?expand=availability&site_id=SiteGenesis HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Aug-2014 00:00:00 GMT
{
    "_v" : "17.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "product",
   "ats" : 500,
   "brand" : "Brand",
   "ean" : "EAN",
   "id" : "my-product",
   "in_stock" : true,
   "link" : "https://example.com/s/-/dw/data/v17.2/products/my-product",
   "long_description" : 
   {
      "default" : "Long Description"
   },
   "manufacturer_name" : "Manufacturer",
   "manufacturer_sku" : "Manufacturer ID",
   "name" : 
   {
      "default" : "My Product"
   },
   "online" : true,
   "online_flag" : 
   {
      "default" : true
   },
   "owning_catalog_id" : "my-catalog",
   "owning_catalog_name" : 
   {
      "default" : "My Catalog"
   },
   "page_description" : 
   {
      "default" : "Page description"
   },
   "page_keywords" : 
   {
      "default" : "Page Keyword"
   },
   "page_title" : 
   {
      "default" : "Page title"
   },
   "searchable" : 
   {
      "default" : true
   },
   "short_description" : 
   {
      "default" : "Short Description"
   },
   "type" : 
   {
      "_type" : "product_type",
      "bundle" : true,
      "bundled" : true,
      "part_of_product_set" : true
   },
   "unit" : "bnd",
   "upc" : "UPC"
}

# in case of failure:
 
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":"17.2",
  "fault":{
    "type":"ProductNotFoundException",
    "message":"No product with id 'my-product' found."
  }
}

Delete Product

Deletes the product by ID

Url

DELETE https://hostname:port/dw/data/v17_2/products/{id}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Path Parameters

Parameter	Type	Description	Constraints
id	String	The product ID.	maxLength=100, minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`ProductNotFoundException`	productId (String)	Indicates the product is not found.

Sample

REQUEST:
DELETE /s/-/dw/data/v17_2/products/product1 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

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":"17.2",
  "fault":{
    "type":"ProductNotFoundException",
    "message":"No product with id 'my-product' found."
  }
}

Create Product

Creates a product using the information provided. If a product with the same unique identifier, it will be cleaned and overwritten unless the header x-dw-validate-existing=true is passed in with the request.

Url

PUT https://hostname:port/dw/data/v17_2/products/{id}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Request Document

Product

Response Document

Product

Path Parameters

Parameter	Type	Description	Constraints
id	String	The product ID.	maxLength=100, minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`ProductInvalidException`	productId (String) field (String) detail (String)	Indicates the catalog is not provided in the request.
400	`ProductDuplicateException`	productId (String)	Indicate the product is already existed.
400	`IdConflictException`	bodyID (String) urlID (String)	Indicates the ID in request URL does not match the ID in the product document.
404	`CatalogNotFoundException`	catalogId (String)	Indicates the catalog is not found.

Sample

REQUEST:
PUT /s/-/dw/data/v17_2/products/product1 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "owning_catalog_id" : "WapiCatalog", 
    "id" : "product1"
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
    "_v" : "17.2",
    "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
    "_type": "product",
    "id" : "product1",
    "link": "https://example.com/s/-/dw/data/v17_2/products/product1",
    "online": false,
    "owning_catalog_id" : "WapiCatalog",
    "searchable": false
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
    "_v":"17.2",
    "fault":{
        "type":"CatalogNotFoundException",
        "message":"No catalog with id 'my-catalog' found."
    }
}

Update Product

Update a product using the information provided. Fields that can be updated: name, page_description, long_descripton, page_title, page_keywords, brand, ean,upc, manufacture_sku, manufacture_name, searchable, unit, searchable, online_flag, default_variant_id.

Url

PATCH https://hostname:port/dw/data/v17_2/products/{id}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Request Document

Product

Response Document

Product

Path Parameters

Parameter	Type	Description	Constraints
id	String	The product ID.	maxLength=100, minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description

400

Status	Type	Arguments	Description
400	`ProductDefaultVariantException`	masterId (String) variantId (String)	Indicates there is a problem to set default variant for a product.
400	`IdConflictException`	bodyID (String) urlID (String)	Indicates the ID in request URL does not match the ID in the product document.
404	`ProductNotFoundException`	productId (String)	Indicates the product to be updated is not found.

ProductDefaultVariantException

masterId (String)

variantId (String)

Indicates there is a problem to set default variant for a product.

400

IdConflictException

bodyID (String)

urlID (String)

Indicates the ID in request URL does not match the ID in the product document.

404

ProductNotFoundException

productId (String)

Indicates the product to be updated is not found.

Sample

REQUEST:
PATCH /s/-/dw/data/v17_2/products/product1 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
	"id" : "product1",
        "name" : 
        {
               "default" : "Product 1",
               "zh-CN" : "产品 1"
        }
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
Content-Length: 67
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
   "_v" : "17.2",
   "_type" : "product",
   "_resource_state" : "cb8ba8f6173b517d36f8ccaa705a8072ed3369919b79c10c5b6afbfa4e1673ce",
   "id" : "product1”,
   "link" : "https://example.com/s/-/dw/data/v17_2/products/product1",
   "name" : 
        {
               "default" : "Product 1",
               "zh-CN" : "产品 1"
        }
   "online_flag" : 
   {
      "default" : false
   },
   "owning_catalog_id" : “testCatalog",
   "owning_catalog_name" : 
   {
      "default" : “Test Catalog"
   },
   "searchable" : 
   {
      "default" : false
   },
   "type" : 
   {
      "_type" : "product_type",
      "item" : true
   }
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-attribute,must-revalidate
{
    "_v":"17.2",
    "fault":{
        "type”:”ProductNotFoundException",
        "message":"No product with id ‘product1’ found."
    }
}

Get Variations

Reads variations(variants) within a product of type variation master or variation group.

Url

GET https://hostname:port/dw/data/v17_2/products/{id}/variations?site_id={String}&start={Integer}&count={Integer}&select={String}&expand={String}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Response Document

Variants

Path Parameters

Parameter	Type	Description	Constraints
id	String	The product ID of a variation master or a variation group.	minLength=1, nullable=false

Query Parameters

Parameter	Type	Description
count	Integer
expand	String	The list of expansions to retrieve product information. The expand values available are: _base - Basic product information is retrieved. This expand is included by default. all - All product information including the following properties are retrieved: ats - site_id has to be provided to see this property image in_stock- site_id has to be provided to see this property online - site_id has to be provided to see this property price- site_id has to be provided to see this property price_currency- site_id has to be provided to see this property searchable variations - Information related to product variation is retrieved. This expand is included by default.
select	String
site_id	String	The site context.
start	Integer

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`ProductNotMasterGroupException`	productId (String)	Indicates that the given product is neither a variation master nor a variation group.
404	`ProductNotFoundException`	productId (String)	Indicates the product is not found.

Sample

REQUEST:
GET  /s/-/dw/data/v17_2/products/my-product/variations?count=20 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Aug-2014 00:00:00 GMT
{
   "_v" : "17.2",
   "_type" : "variants",
   "count" : 9,
   "data" : 
   [
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-1",
         "product_id" : "my-product-1",
         "variation_values" : 
         {
            "color" : "red",
            "size" : "S"
         }
      },
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-2",
         "product_id" : "my-product-2",
         "variation_values" : 
         {
            "color" : "red",
            "size" : "M"
         }
      },
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-3",
         "product_id" : "my-product-3",
         "variation_values" : 
         {
            "color" : "red",
            "size" : "L"
         }
      },
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-4",
         "product_id" : "my-product-4",
         "variation_values" : 
         {
            "color" : "blue",
            "size" : "S"
         }
      },
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-5",
         "product_id" : "my-product-5",
         "variation_values" : 
         {
            "color" : "blue",
            "size" : "M"
         }
      },
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-6",
         "product_id" : "my-product-6",
         "variation_values" : 
         {
            "color" : "blue",
            "size" : "L"
         }
      },
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-7",
         "product_id" : "my-product-7",
         "variation_values" : 
         {
            "color" : "black",
            "size" : "S"
         }
      },
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-8",
         "product_id" : "my-product-8",
         "variation_values" : 
         {
            "color" : "black",
            "size" : "M"
         }
      },
      
      {
         "_type" : "variant",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-9",
         "product_id" : "my-product-9",
         "variation_values" : 
         {
            "color" : "black",
            "size" : "L"
         }
      }
   ],
   "start" : 0,
   "total" : 9
}

# in case of failure:
 
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":"17.2",
  "fault":{
    "type":"ProductNotMasterGroupException",
    "message":"Product 'my-product' is neither a variation master product nor a variation group product."
  }
}

Get Variation Groups

Reads variation groups for a product master.

Url

GET https://hostname:port/dw/data/v17_2/products/{master_product_id}/variation_groups?site_id={String}&start={Integer}&count={Integer}&select={String}&expand={String}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Response Document

VariationGroups

Path Parameters

Parameter	Type	Description	Constraints
master_product_id	String	The id of the master product.	minLength=1

Query Parameters

Parameter	Type	Description
count	Integer	The maximum number of variation groups to return (defaults to 25).
expand	String	The valid expands are {price,availability}
select	String	A selector that specifies the fields to return in the variation groups document.
site_id	String	The site context.
start	Integer	The start index of the variation groups to return (defaults to 0).

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`ProductNotMasterException`	productId (String)	Indicates that the given product is not a variation master.
404	`ProductNotFoundException`	productId (String)	Indicates the master product is not found.

Sample

REQUEST:
GET  /s/-/dw/data/v17_2/products/my-product/variation_groups?count=20 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Aug-2014 00:00:00 GMT
{
   "_v" : "17.2",
   "_type" : "variation_groups",
   "count" : 2,
   "data" : 
   [
      
      {
         "_type" : "variation_group",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-5",
         "product_id" : "my-product-5",
         "variation_values" : 
         {
            "color" : "red"
         }
      },
      
      {
         "_type" : "variation_group",
         "link" : "https://example.com/s/-/dw/data/v17_2/products/my-product-6",
         "product_id" : "my-product-6",
         "variation_values" : 
         {
            "color" : "black"
         }
      }
   ],
   "start" : 0,
   "total" : 2
}

# in case of failure:
 
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":"17.2",
  "fault":{
    "type":"ProductNotFoundException",
    "message":"No product with id 'my-product' 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":"17.2",
  "fault":{
    "type":"ProductNotMasterException",
    "message":"Product 'my-product' is not a variation master product."
  }
}

Get Variation Attributes

Reads variation attributes of a product of type variant or variation master or variation group.

Url

GET https://hostname:port/dw/data/v17_2/products/{product_id}/variation_attributes?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Response Document

VariationAttributes

Path Parameters

Parameter	Type	Description	Constraints
product_id	String	The product ID of a variant or a variation master or a variation group.	minLength=1

Query Parameters

Parameter	Type	Description	Constraints
count	Integer
select	String
start	Integer

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`ProductNotFoundException`	productId (String)	Indicates the product is not found.

Sample

REQUEST:
GET  /s/-/dw/data/v17_2/products/my-product/variation_attributes?count=20 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Aug-2014 00:00:00 GMT
{
   "_v" : "17.2",
   "_type" : "variation_attributes",
   "count" : 3,
   "data" : 
   [
      
      {
         "_type" : "variation_attribute",
         "id" : "fabric",
         "name" : 
         {
            "default" : "Fabric"
         },
         "values" : 
         [
            
            {
               "_type" : "variation_attribute_value",
               "name" : 
               {
                  "default" : "Leather"
               },
               "value" : "leather"
            },
            
            {
               "_type" : "variation_attribute_value",
               "name" : 
               {
                  "default" : "Linen"
               },
               "value" : "linen"
            },
            
            {
               "_type" : "variation_attribute_value",
               "name" : 
               {
                  "default" : "Plastic"
               },
               "value" : "plastic"
            },
            
            {
               "_type" : "variation_attribute_value",
               "name" : 
               {
                  "default" : "Metal"
               },
               "value" : "metal"
            }
         ]
      },
      
      {
         "_type" : "variation_attribute",
         "id" : "color",
         "name" : 
         {
            "default" : "Color"
         },
         "values" : 
         [
            
            {
               "_type" : "variation_attribute_value",
               "name" : 
               {
                  "default" : "Red"
               },
               "value" : "red"
            },
            
            {
               "_type" : "variation_attribute_value",
               "name" : 
               {
                  "default" : "Blue"
               },
               "value" : "blue"
            },
            
            {
               "_type" : "variation_attribute_value",
               "name" : 
               {
                  "default" : "Black"
               },
               "value" : "black"
            }
         ]
      },
      
      {
         "_type" : "variation_attribute",
         "id" : "size",
         "name" : 
         {
            "default" : "Size"
         },
         "values" : 
         [
            
            {
               "_type" : "variation_attribute_value",
               "description" : 
               {
                  "default" : "Small"
               },
               "name" : 
               {
                  "default" : "Small"
               },
               "value" : "S"
            },
            
            {
               "_type" : "variation_attribute_value",
               "description" : 
               {
                  "default" : "Medium"
               },
               "name" : 
               {
                  "default" : "Medium"
               },
               "value" : "M"
            },
            
            {
               "_type" : "variation_attribute_value",
               "description" : 
               {
                  "default" : "Large"
               },
               "name" : 
               {
                  "default" : "Large"
               },
               "value" : "L"
            }
         ]
      }
   ],
   "start" : 0,
   "total" : 3
}

# in case of failure:
 
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":"17.2",
  "fault":{
    "type":"ProductNotFoundException",
    "message":"No product with id 'my-product' found."
  }
}

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.