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
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:
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 IDUrl
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
Response Document
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
Response Document
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 |
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
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 | Constraints |
---|---|---|---|
count | Integer | ||
expand | String | The list of expansions to retrieve product information.
The expand values available are:
|
|
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
Path Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
master_product_id | String | The id of the master product. | minLength=1 |
Query Parameters
Parameter | Type | Description | Constraints |
---|---|---|---|
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
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."
}
}