| Code | Description |
|---|---|
| 401 | Unauthorized. Include a WWW-Authenticate header field containing a challenge applicable to the requested resource. |
| 403 | Forbidden. The request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource. |
| 404 | Not Found. The requested resource could not be found. |
| 422 | Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors. |
| 500 | Internal Server Error. An unexpected condition was encountered. |
request:
{
"product": {
"code": "product_1",
"name": "Product 1",
"attribute_set": "Automotive",
"product_type": "product",
"status": "active",
"brand": {
"id": 1
},
"product_attributes": {
"description": "Product 1 description",
"npc_association_1": {
"associated_id": 1
},
"npc_association_1": {
"associated_code": "npc_entity_1"
}
},
"categories": [
{
"path": "Engine Oil",
"is_primary": true,
"category_set": "default"
}
],
"entity_identifiers": [
{
"key": "10000000001",
"name": "Channel Name"
},
{
"key": "20000000002",
"name": "Channel Name"
}
],
"shipping_zones": [
"AU_FREE"
]
}
}
Sample: create a product in a one level attribute set with minimal data required
{
"product": {
"code": "code-001",
"name": "Name 001",
"attribute_set": "Automotive",
"product_type": "product",
"status": "active"
}
}
Sample: update some fields of an existing product
{
"product": {
"code": "code-001",
"product_attributes": {
"description": "content test here",
"gender": "Male"
}
}
}
Sample: update product code of an existing product
{
"product": {
"code": "code-001",
"_new_code": "code-0001-new"
}
}
or
{
"product": {
"id": 1,
"_new_code": "code-0001-new"
}
}
Sample: full sample of multi-level products. All data associated with a product can be sent together
{
"product": {
"code": "code-001",
"name": "Name 001",
"attribute_set": "Apparel",
"product_type": "product",
"status": "inactive",
"brand": {
"id": 23
},
"categories": [
{
"id": 5
}
],
"price_items": [
{
"price_book_name": "Default",
"amount": 100
}
],
"product_attributes": {
"description": "content test here",
"gender": "Male"
},
"variants": {
"code-001-blue": {
"code": "code-001-blue1",
"name": "001 blue",
"status": "inactive",
"media_items": [
{
"media_item_type": "ImageMediaItem",
"url": "https://robohash.org/my-own-slug.png?size=50x50",
"tag_list": ["thumbnail"]
}
],
"price_items": [
{
"price_book_name": "Default",
"amount": 100
}
],
"product_attributes": {
"colour": "Blue"
},
"variants": {
"code-001-blue-large": {
"code": "code-001-blue-large",
"name": "001 blue large",
"status": "inactive",
"product_attributes": {
"size": "Large"
},
"inventories": [
{
"inventory_source": "DC1",
"qty": 1,
"available_qty": 2,
"stock_availability": "in_stock",
"dispatch_time": 3,
"dispatch_time_unit": "day",
"style": "dynamic"
}
]
}
}
}
}
}
}
Sample: update some fields of an existing variant. Note product code of each level must be supplied
{
"product": {
"code": "code-001",
"variants": {
"code-001-blue": {
"code": "code-001-blue1",
"variants": {
"code-001-blue-large": {
"code": "code-001-blue-large",
"product_attributes": {
"description": "Fancy"
},
"inventories": [
{
"inventory_source": "DC1",
"qty": 20,
}
]
}
}
}
}
}
}
Sample: Use product identifier (instead of code) to update product
{
"product": {
"identifier_name": "MPN",
"entity_key": "m-001",
"product_attributes": {
"description": "Product 2 description"
}
}
}
Class product
Differences for class product:
- product_class_name is used instead of attribute set.
- json type custom attribute needs to be serialised string.
- Single option and multi-option type custom attribute needs to be option value ID instead of label. See samples below.
- variants element is not supported. See below for new element to link products.
Sample for product creation
{
"product": {
"code": "sku-12",
"name": "Product ABC",
"status": "inactive",
"product_class_name": "Class ABC"
}
}
Add three level products (Style-Colour-Size) or more along with associations
{
"product": {
"name":"jacket",
"code":"jacket",
"status":"active",
"product_type":"product",
"product_class_name":"Style",
"variants": {
"jacket-red": {
"name":"jacket-red",
"code":"jacket-red",
"status":"active",
"product_type":"product",
"product_class_name":"Colour",
"parent_variations": [
{"product_code": "jacket"}
],
"variants": {
"jacket-red-sm": {
"name":"jacket-red-sm",
"code":"jacket-red-sm",
"status":"active",
"product_type":"product",
"product_class_name":"Size",
"parent_variations": [
{"product_code": "jacket-red"}
]
}
}
},
"jacket-blue": {
"name":"jacket-blue",
"code":"jacket-blue",
"status":"active",
"product_type":"product",
"product_class_name":"Colour",
"parent_variations": [
{"product_code": "jacket"}
],
"variants": {
"jacket-blue-sm": {
"name":"jacket-blue-sm",
"code":"jacket-blue-sm",
"status":"active",
"product_type":"product",
"product_class_name":"Size",
"parent_variations": [
{"product_code": "jacket-blue"}
]
}
}
}
}
}
}
Add Variations to Parent from Parent Product
{
"product": {
"code": "ABC",
"product_variations": [
{
"child_id": 235
},
{
"child_product_code": "ABC-Black"
}
]
}
}
Add Variations to Parent from Child Product
{
"product": {
"code": "ABC-Black",
"parent_variations": [
{
"parent_id": 25
},
{
"product_code": "ABC"
}
]
}
}
Add Product to Grouped products from Child product:
{
"product": {
"code": "sku-12",
"groups": [
{
"group_id": 259
},
{
"product_code": "group-3"
}
]
}
}
Add Product to Grouped products from Grouped Product:
{
"product": {
"code": "sku-12",
"group_members": [
{
"member_id": 2583
},
{
"sku_code": "sku-6",
"sort_order": 100
}
]
}
}
Add Child Related Products to Product
{
"product": {
"code": "sku-12",
"child_related_products": [
{
"relationship_id": 1,
"child_product_id": 12,
"sort_order": 1,
"status": "active"
},
{
"relationship_code": "relationship_1",
"child_product_code": "child_product_code_1",
"sort_order": 2,
"status": "inactive"
}
]
}
}
Add Product to Parent Related Products
{
"product": {
"code": "sku-12",
"parent_related_products": [
{
"relationship_id": 1,
"parent_product_id": 12,
"sort_order": 1,
"status": "active"
},
{
"relationship_code": "relationship_1",
"parent_product_code": "child_product_code_1",
"sort_order": 2,
"status": "inactive"
}
]
}
}
Add Product to Kit Products from Child product:
{
"product": {
"code": "sku-12",
"parent_kits": [
{
"parent_id": 260,
"qty": 2
},
{
"parent_product_code": "kit-3",
"qty": 1
}
]
}
}
Add Product to Kit products from Parent Product:
{
"product": {
"code": "kit-3",
"kit_members": [
{
"child_id": 2583,
"qty": 2
},
{
"child_product_code": "sku-6",
"qty": 1
}
]
}
}
Single option, multi option values:
{
"product": {
"code": "sku-12"
"product_attributes": {
"option1": 2,
"option2": [ { "code": "blue" } ],
"option3": [4, 5],
"option4": [ { "code": "A" }, { "code": "B" } ]
}
}
}
Multi association values:
Supported Mode:
- upsert: default
- reset: Delete all existing association for this attribute, and replace with the current one. Send empty array to remove all existing values.
{
"product": {
"code": "sku-12"
"product_attributes": {
"npc_association_1": {
"associated_id": [1],
"mode": "upsert"
},
"npc_association_2": {
"associated_code": ["npc_entity_1"],
"mode": "reset"
}
}
}
}
Create Single option, multi option values if not exists and assign to product:
{
"product": {
"code": "sku-12"
"product_attributes": {
"option2": [ { "code": "blue", "name": "Blue" } ],
"option4": [ { "code": "A", "name": "A" }, { "code": "B", "name": "B" } ]
}
}
}
Response (teannt version 1):
{
"en": {
"id": 2,
"product_type": "product",
"code": "product_1",
"status": "active",
"product_attributes": {
"description": {
"base_type": "html",
"value": "Product 1 description"
},
"short_description": {
"base_type": "html",
"value": ""
}
},
"name": "Product 1",
"is_complete": false,
"incomplete_fields": {
"missing_image": true,
"missing_category": false,
"missing_price": true,
"missing_attributes": null
},
"discontinued": false,
"shipping_options": [],
"attribute_set": {
"id": 1,
"name": "Automotive"
},
"product_level": {
"id": 1,
"name": "Products"
},
"brand": {
"id": 1,
"name": "MOTUL",
"description": null,
"logo_link": ""
},
"product_categories": [
{
"is_primary": true,
"category_id": 1,
"name": "Engine Oil",
"path": "Engine Oil",
"category_set": {
"id": 1,
"name": "default"
}
}
],
"catalogs": [],
"shipping_zones": [
{
"id": 1,
"name": "AU_FREE"
}
],
"media_items": []
},
"created_at": "2016-05-11T14:45:58.210+10:00",
"updated_at": "2016-05-11T14:45:58.817+10:00"
}
Response (teannt version 2):
{
"id": 1,
"product_type": "product",
"code": "shirt-a",
"status": "active",
"product_attributes": {
"description": {
"value": "test5",
"base_type": "html"
},
"short_description": {
"value": "test1",
"base_type": "html"
}
},
"name": "Shirt A updated",
"discontinued": false,
"children": [
{
"id": 7,
"product_type": "product",
"code": "shirt-a-white",
"status": "active",
"product_attributes": {
"colour": {
"value": "White",
"base_type": "string"
}
},
"name": "shirt-a-white",
"discontinued": false,
"children": [
{
"id": 10,
"product_type": "product",
"code": "shirt-a-white-xlarge",
"status": "active",
"product_attributes": {
"ean": {
"value": "",
"base_type": "string"
},
"gtin": {
"value": "",
"base_type": "string"
},
"hero": {
"value": false,
"base_type": "boolean"
},
"isbn": {
"value": "",
"base_type": "string"
},
"size": {
"value": "",
"base_type": "string"
},
"upca": {
"value": "",
"base_type": "string"
}
},
"name": "shirt-a-white-xlarge",
"discontinued": false,
"children": []
},
{
"id": 8,
"product_type": "product",
"code": "shirt-a-white-small",
"status": "active",
"product_attributes": {
"ean": {
"value": "",
"base_type": "string"
},
"gtin": {
"value": "",
"base_type": "string"
},
"hero": {
"value": false,
"base_type": "boolean"
},
"isbn": {
"value": "",
"base_type": "string"
},
"size": {
"value": "",
"base_type": "string"
},
"upca": {
"value": "",
"base_type": "string"
}
},
"name": "shirt-a-white-small",
"discontinued": false,
"children": []
},
{
"id": 9,
"product_type": "product",
"code": "shirt-a-white-large",
"status": "active",
"product_attributes": {
"ean": {
"value": "",
"base_type": "string"
},
"gtin": {
"value": "",
"base_type": "string"
},
"hero": {
"value": false,
"base_type": "boolean"
},
"isbn": {
"value": "",
"base_type": "string"
},
"size": {
"value": "",
"base_type": "string"
},
"upca": {
"value": "",
"base_type": "string"
}
},
"name": "shirt-a-white-large",
"discontinued": false,
"children": []
}
]
},
{
"id": 2,
"product_type": "product",
"code": "shirt-a-black",
"status": "active",
"product_attributes": {
"colour": {
"value": "black",
"base_type": "string"
}
},
"name": "Shirt A Black updated 2",
"discontinued": false,
"children": [
{
"id": 11,
"product_type": "product",
"code": "shirt-a-black-xlarge",
"status": "active",
"product_attributes": {
"ean": {
"value": "",
"base_type": "string"
},
"gtin": {
"value": "",
"base_type": "string"
},
"hero": {
"value": false,
"base_type": "boolean"
},
"isbn": {
"value": "",
"base_type": "string"
},
"size": {
"value": "",
"base_type": "string"
},
"upca": {
"value": "",
"base_type": "string"
}
},
"name": "shirt-a-black-xlarge",
"discontinued": false,
"children": []
},
{
"id": 3,
"product_type": "product",
"code": "shirt-a-black-small",
"status": "active",
"product_attributes": {
"ean": {
"value": "",
"base_type": "string"
},
"gtin": {
"value": "",
"base_type": "string"
},
"hero": {
"value": false,
"base_type": "boolean"
},
"isbn": {
"value": "",
"base_type": "string"
},
"size": {
"value": "Small",
"base_type": "string"
},
"upca": {
"value": "",
"base_type": "string"
}
},
"name": "Shirt A Black Small updated 1",
"discontinued": false,
"children": []
},
{
"id": 6,
"product_type": "product",
"code": "shirt-a-black-large",
"status": "inactive",
"product_attributes": {
"ean": {
"value": "",
"base_type": "string"
},
"gtin": {
"value": "",
"base_type": "string"
},
"hero": {
"value": false,
"base_type": "boolean"
},
"isbn": {
"value": "",
"base_type": "string"
},
"size": {
"value": "Large",
"base_type": "string"
},
"upca": {
"value": "",
"base_type": "string"
}
},
"name": "shirt-a-black-large",
"discontinued": false,
"children": []
}
]
},
{
"id": 12,
"product_type": "product",
"code": "shirt-a-orange",
"status": "active",
"product_attributes": {
"colour": {
"value": "Orange",
"base_type": "string"
}
},
"name": "shirt-a-orange",
"discontinued": false,
"children": []
}
]
}
Response for Class product:
attribute_values is returned instead of product_attributes.
{
"id": 2712,
"product_type": null,
"code": "csv-group-1",
"status": "active",
"product_attributes": null,
"name": "csv-group-1",
"class_type": "grouped",
"discontinued": false,
"children": [],
"attribute_values": [
{
"attribute_definition_id": 25,
"attribute_definition_code": "multi_option_attributes",
"data": []
},
{
"attribute_definition_id": 2,
"attribute_definition_code": "short_description",
"data": ""
}
]
}
| Param name | Description |
|---|---|
|
product required |
Validations:
|
|
product[locale] optional , nil allowed |
Locale for this product. Should be one of the language codes defined on CommerceConnect. Defaults to the default language. Validations:
|
|
product[name] optional , nil allowed |
Product or sku name Validations:
|
|
product[code] optional , nil allowed |
Unique identifier for product and sku Validations:
|
|
product[_new_code] optional , nil allowed |
Update the code of existing product Validations:
|
|
product[attribute_set] optional , nil allowed |
Attribute set name that this product is assigned to. This must be created beforehand Validations:
|
|
product[product_class_name] optional , nil allowed |
Class name that this product is assigned to. This must be created beforehand Validations:
|
|
product[product_family_code] optional , nil allowed |
Product family code Validations:
|
|
product[product_type] optional , nil allowed |
Validations:
|
|
product[status] optional , nil allowed |
Validations:
|
|
product[kit_create_mode] optional , nil allowed |
Provide this only for creating new kit. Empty kit - create empty kit in the provided attribute set. Clone from existing SKU - create a kit by copying all data from the product with code in base_sku_code_for_clone field Validations:
|
|
product[base_sku_code_for_clone] optional , nil allowed |
The product code (must be SKU/bottom level product) to clone for new kit. kit_create_mode must be Clone from existing SKU. Provide this only for creating new kit Validations:
|
|
product[brand] optional , nil allowed |
Validations:
|
|
product[brand][id] optional , nil allowed |
Brand ID Validations:
|
|
product[product_attributes] optional , nil allowed |
Validations:
|
|
product[product_attributes][_any_attribute_code_] optional , nil allowed |
The key of attribute is attribute code and value is a valid json type that matches the base type of the attribute Validations:
|
|
product[dimension] optional , nil allowed |
Validations:
|
|
product[dimension][length] optional , nil allowed |
Validations:
|
|
product[dimension][width] optional , nil allowed |
Validations:
|
|
product[dimension][height] optional , nil allowed |
Validations:
|
|
product[dimension][weight] optional , nil allowed |
Validations:
|
|
product[packed_dimension] optional , nil allowed |
Validations:
|
|
product[packed_dimension][length] optional , nil allowed |
Validations:
|
|
product[packed_dimension][width] optional , nil allowed |
Validations:
|
|
product[packed_dimension][height] optional , nil allowed |
Validations:
|
|
product[packed_dimension][weight] optional , nil allowed |
Validations:
|
|
product[shipping_zones] optional , nil allowed |
Replace existing shipping zones with these new shipping zones Validations:
|
|
product[price_items] optional , nil allowed |
Add new prices or update existing prices if they exist. Validations:
|
|
product[price_items][price_book_name] optional , nil allowed |
Name of an existing price book to which this price item is linked Validations:
|
|
product[price_items][from] optional , nil allowed |
Valid from Validations:
|
|
product[price_items][to] optional , nil allowed |
Valid to Validations:
|
|
product[price_items][amount] optional , nil allowed |
Validations:
|
|
product[categories] optional , nil allowed |
Set the product’s categories to these categories (existing categories will be removed) Validations:
|
|
product[categories][id] optional , nil allowed |
Category ID Validations:
|
|
product[catalogs] optional , nil allowed |
Link these catalogs with the product. Validations:
|
|
product[catalogs][id] optional , nil allowed |
Catalog ID Validations:
|
|
product[catalogs][name] optional , nil allowed |
Catalog name Validations:
|
|
product[media_items] optional , nil allowed |
Set the product’s media items to these (existing media items will be removed). Validations:
|
|
product[media_items][media_item_type] optional , nil allowed |
Validations:
|
|
product[media_items][url] optional , nil allowed |
URL that stores the corresponding media item Validations:
|
|
product[media_items][description] optional , nil allowed |
Description for the media item Validations:
|
|
product[media_items][sort_order_position] optional , nil allowed |
The position of the media item. Non negative integer is supported Validations:
|
|
product[media_items][is_primary] optional , nil allowed |
Make this media item as primary Validations:
|
|
product[media_items][tag_list] optional , nil allowed |
Tags for this media item Validations:
|
|
product[media_items][processing_options] optional , nil allowed |
Options to perform extra image processing on the media item. This is applicable only when media_item_type is ‘ImageMediaItem’ Validations:
|
|
product[media_items][processing_options][apply_background] optional , nil allowed |
Setting this to true would result in a new media item created against the product with background applied. Removes transparency. Validations:
|
|
product[media_items][processing_options][background_colour] optional , nil allowed |
The colour name or a hex colour code for the background colour for the created media item. Defaults to white. Validations:
|
|
product[media_items][processing_options][processed_tags] optional , nil allowed |
The tags for the created media item. Validations:
|
|
product[inventories] optional , nil allowed |
Add new inventory or update existing inventory data Validations:
|
|
product[inventories][inventory_source] optional , nil allowed |
Inventory source name to which this inventory is applied Validations:
|
|
product[inventories][sku] optional , nil allowed |
Inventory source related SKU Validations:
|
|
product[inventories][qty] optional , nil allowed |
Quantity in the inventory source specified Validations:
|
|
product[inventories][available_qty] optional , nil allowed |
Available quantity in the inventory source specified Validations:
|
|
product[inventories][stock_availability] optional , nil allowed |
Flag to indicate the stock level Validations:
|
|
product[inventories][out_of_stock_threshold] optional , nil allowed |
Out of stock threshold Validations:
|
|
product[inventories][dispatch_time] optional , nil allowed |
Dispatch time Validations:
|
|
product[inventories][dispatch_time_unit] optional , nil allowed |
Dispatch time unit Validations:
|
|
product[inventories][unit_cost] optional , nil allowed |
Unit cost of the product for this inventory source Validations:
|
|
product[inventories][style] optional , nil allowed |
Dynamic means Qty changes and Static means Qty stays the same. This is related to inventory decrement for order download Validations:
|
|
product[variants] optional , nil allowed |
Validations:
|
|
product[variants][_product_code_] optional , nil allowed |
Child product. It accepts the params of a product Validations:
|
|
product[virtual_products] optional , nil allowed |
Validations:
|
|
product[virtual_products][_virtual_product_code_] optional , nil allowed |
Validations:
|
|
product[virtual_products][_virtual_product_code_][code] optional , nil allowed |
Unique identifier for virtual product Validations:
|
|
product[virtual_products][_virtual_product_code_][name] optional , nil allowed |
Virtual product name. Required for creating new virtual Validations:
|
|
product[virtual_products][_virtual_product_code_][status] optional , nil allowed |
Required for creating new virtual product Validations:
|
|
product[virtual_products][_virtual_product_code_][attributes] optional , nil allowed |
Validations:
|
|
product[virtual_products][_virtual_product_code_][attributes][_any_attribute_code_] optional , nil allowed |
The key of attribute is attribute code and value is a valid json type that matches the base type of the attribute Validations:
|
|
product[kit_skus] optional , nil allowed |
Validations:
|
|
product[kit_skus][product_code] required |
Product code. It must be at bottom level (SKU) and cannot be a Kit Validations:
|
|
product[kit_skus][qty] required |
The qty of the bundled SKU Validations:
|