Product Catalog Workflow Interface Contracts
Interface Contract
Changed on:
9 May 2025
Detailed Description
The below Interface Contracts document the interaction points with the Product Catalog Workflow. These allow you to ensure that any integration made into the Workflow will enable the Workflow to work correctly.
Attribute Type
Prices Type
TaxType Type
Attribute Type
Prices Type
TaxType Type
UPSERT_CATEGORY Event
This event is used to create or update Category within the target Product Catalog.Request Payload: Create Category
Use this payload when creating a new Category entry in the catalog.Main Payload| Property | Description | Type | Required? | Length Limit |
`ref` | The unique reference identifier for the Category. Uppercase Alphanumeric. | String | Required | 100 |
`name` | The name of the Category. | String | Required | 100 |
`type` | Type of Category (Normally set to `STANDARD`). | String | Required | 50 |
`status` | Status of the Category. | String | Optional | 50 |
`summary` | A short description of the Category. | String | Optional | 255 |
`parentCategory` | Identifies the parent Category to which the item belongs. Use it to group related Categories under a shared parent. | String | Optional | 255 |
Event Request Example
1{
2 "name": "UPSERT_CATEGORY",
3 "retailerId": "1",
4 "entityRef": "DEFAULT:1",
5 "entityType": "PRODUCT_CATALOGUE",
6 "entitySubtype": "DEFAULT",
7 "rootEntityRef": "DEFAULT:1",
8 "rootEntityType": "PRODUCT_CATALOGUE",
9 "attributes": {
10 "ref": "GAMING_CHAIR",
11 "type": "STANDARD",
12 "status": "ACTIVE",
13 "name": "GAMING CHAIR",
14 "summary": "BEST GAMING CHAIR IN THE WORLD",
15 "parentCategory": "CHAIR"
16 }
17}Request Payload: Update Category with Children
Use this version of the payload when assigning one or more child categories to an existing parent category.Main Payload| Property | Description | Type | Required? | Length Limit |
`ref` | The unique reference identifier for the Category. Uppercase Alphanumeric. | String | Required | 100 |
`name` | The name of the Category | String | Required | 100 |
`type` | Type of the Category (Normally set to `STANDARD`) | String | Required | 50 |
`status` | Status of the Category | String | Optional | 50 |
`summary` | A short description of the Category | String | Optional | 255 |
`childCategories` | Categories that fall under the Category in the hierarchy. Used to organize nested structures. | String | Optional | 255 |
Event Request Example
1{
2 "name": "UPSERT_CATEGORY",
3 "retailerId": "1",
4 "entityRef": "DEFAULT:1",
5 "entityType": "PRODUCT_CATALOGUE",
6 "entitySubtype": "DEFAULT",
7 "rootEntityRef": "DEFAULT:1",
8 "rootEntityType": "PRODUCT_CATALOGUE",
9 "attributes": {
10 "ref": "CHAIR",
11 "type": "STANDARD",
12 "status": "ACTIVE",
13 "name": "GAMING CHAIR",
14 "summary": "BEST GAMING CHAIR IN THE WORLD",
15 "childCategories": "GAMING_CHAIR"
16 }
17}UPSERT_PRODUCT Event
This event is used to create or update Products within the target Product Catalog.Request Payload
STANDARD PRODUCT
Main Payload| Property | Description | Type | Required? | Length Limit |
`ref` | The unique reference identifier for the Product | String | Required | 100 |
`name` | The name of the Product | String | Required | 255 |
`type` | Type of the Standard Product (Recommended to be set to `STANDARD` to ensure the proper functioning of the `SetState` Rule) | String | Required | 50 |
`status` | Status of the Standard Product | String | Optional | 50 |
`gtin` | The Global Trade Item Number (GTIN) for the Product | String | Required | 20 |
`summary` | A short description of the Product | String | Optional | 255 |
`attributes` | Array of attributes for the Product | [Attribute] | Optional | |
`categoryRefs` | A list of references to the Categories to which the Product relates. Product Categories must be a part of the same Product Catalog. The Category must already exist. | [String] | Optional | 100 |
`prices` | Array of prices for the Product | [prices] | Optional | |
`taxType` | Array of Tax types for the Product | [taxType] | Optional |
| Property | Description | Type | Required? | Length Limit |
`attributes.name` | Name of Standard Product attribute | String | Optional | |
`attributes.type` | Type of Standard Product attribute | String | Optional | |
`attributes.value` | Value of Standard Product attribute | String | Optional |
| Property | Description | Type | Required? | Length Limit |
`prices.type` | Type of Product price | String | Optional | 100 |
`prices.currency` | Currency of Product price | String | Optional | 255 |
`prices.value` | Value of Product price | Float | Optional | 255 |
| Property | Description | Type | Required? | Length Limit |
`taxType.country` | Country of the Tax type | String | Optional | 100 |
`taxType.group` | Group of the Tax type | String | Optional | 100 |
`taxType.tariff` | Tariff of the Tax type | String | Optional | 100 |
Event Request Example
1{
2 "name": "UPSERT_PRODUCT",
3 "retailerId": "1",
4 "entityRef": "DEFAULT:1",
5 "entityType": "PRODUCT_CATALOGUE",
6 "entitySubtype": "DEFAULT",
7 "rootEntityRef": "DEFAULT:1",
8 "rootEntityType": "PRODUCT_CATALOGUE",
9 "attributes": {
10 "ref": "STANDARD_PRODUCT_1",
11 "status": "ACTIVE",
12 "type": "STANDARD",
13 "gtin": "SP",
14 "name": "Standard Product 1",
15 "summary": "Summary",
16 "attributes": [
17 {
18 "name": "imageUrl",
19 "type": "STRING",
20 "value": "ImageUrl"
21 }
22 ],
23 "categoryRefs": [
24 "CATEGORY_1"
25 ],
26 "prices": [
27 {
28 "type": "DEFAULT",
29 "currency": "AUD",
30 "value": 100
31 }
32 ],
33 "taxType": {
34 "country": "AU",
35 "group": "Tax Group",
36 "tariff": "Tax Tariff"
37 }
38 }
39}VARIANT PRODUCT
Main Payload| Property | Description | Type | Required? | Length Limit |
`ref` | The unique reference identifier for the Product | String | Required | 100 |
`name` | The name of the Product | String | Required | 255 |
`type` | Type of the Variant Product (Recommended to be set to `VARIANT` to ensure the proper functioning of the `SetState` Rule) | String | Required | 50 |
`status` | Status of the Variant Product | String | Optional | 50 |
`gtin` | The Global Trade Item Number (GTIN) for the Product | String | Required | 20 |
`summary` | A short description of the Product | String | Optional | 255 |
`standardProductRef` | Associated base Standard Product of this Variant Product | String | Optional | 100 |
`attributes` | Array of attributes for the Product | [Attribute] | Optional | |
`categoryRefs` | A list of references to the Categories to which the Product relates. Product Categories must be a part of the same Product Catalog. The Category must already exist. | [String] | Optional | 100 |
`prices` | Array of prices for the Product | [prices] | Optional | |
`taxType` | Array of Tax types for the Product | [taxType] | Optional |
| Property | Description | Type | Required? | Length Limit |
`attributes.name` | Name of Variant Product attribute | String | Optional | |
`attributes.type` | Type of Variant Product attribute | String | Optional | |
`attributes.value` | Value of Variant Product attribute | String | Optional |
| Property | Description | Type | Required? | Length Limit |
`prices.type` | Type of Product price | String | Optional | 100 |
`prices.currency` | Currency of Product price | String | Optional | 255 |
`prices.value` | Value of Product price | Float | Optional | 255 |
| Property | Description | Type | Required? | Length Limit |
`taxType.country` | Country of the Tax type | String | Optional | 100 |
`taxType.group` | Group of the Tax type | String | Optional | 100 |
`taxType.tariff` | Tariff of the Tax type | String | Optional | 100 |
Event Request Example
1{
2 "name": "UPSERT_PRODUCT",
3 "retailerId": "1",
4 "entityRef": "DEFAULT:1",
5 "entityType": "PRODUCT_CATALOGUE",
6 "entitySubtype": "DEFAULT",
7 "rootEntityRef": "DEFAULT:1",
8 "rootEntityType": "PRODUCT_CATALOGUE",
9 "attributes": {
10 "ref": "VARIANT_PRODUCT_1",
11 "status": "ACTIVE",
12 "type": "VARIANT",
13 "gtin": "VP",
14 "name": "Variant Product",
15 "summary": "Summary",
16 "standardProductRef": "STANDARD_PRODUCT_1",
17 "attributes": [
18 {
19 "name": "imageUrl",
20 "type": "STRING",
21 "value": "ImageUrl"
22 }
23 ],
24 "categoryRefs": [
25 "CATEGORY_1"
26 ],
27 "prices": [
28 {
29 "type": "DEFAULT",
30 "currency": "AUD",
31 "value": 100
32 }
33 ],
34 "taxType": {
35 "country": "AU",
36 "group": "Tax Group",
37 "tariff": "Tax Tariff"
38 }
39 }
40}