Product Catalog Workflow Interface Contracts
Changed on:
9 May 2025
Detailed Description
The below Interface Contracts document the interaction points with the . These allow you to ensure that any integration made into the will enable the to work correctly.
UPSERT_CATEGORY Event
This is used to create or update Category within the target .
Request Payload: Create Category
Use this payload when creating a new Category entry in the catalog.
Main Payload
Property | Description | Type | Required? | Length Limit |
| The unique reference identifier for the Category. Uppercase Alphanumeric. | String | Required | 100 |
| The name of the Category. | String | Required | 100 |
| Type of Category (Normally set to | String | Required | 50 |
| Status of the Category. | String | Optional | 50 |
| A short description of the Category. | String | Optional | 255 |
| 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 |
| The unique reference identifier for the Category. Uppercase Alphanumeric. | String | Required | 100 |
| The name of the Category | String | Required | 100 |
| Type of the Category (Normally set to | String | Required | 50 |
| Status of the Category | String | Optional | 50 |
| A short description of the Category | String | Optional | 255 |
| 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 is used to create or update Products within the target .
Request Payload
STANDARD PRODUCT
Main Payload
Property | Description | Type | Required? | Length Limit |
| The unique reference identifier for the Product | String | Required | 100 |
| The name of the Product | String | Required | 255 |
| Type of the Standard Product (Recommended to be set to | String | Required | 50 |
| Status of the Standard Product | String | Optional | 50 |
| The Global Trade Item Number (GTIN) for the Product | String | Required | 20 |
| A short description of the Product | String | Optional | 255 |
| Array of attributes for the Product | [] | Optional | |
| A list of references to the Categories to which the Product relates. Product Categories must be a part of the same . The Category must already exist. | [String] | Optional | 100 |
| Array of prices for the Product | [prices] | Optional | |
| Array of Tax types for the Product | [taxType] | Optional |
Attribute Type
Property | Description | Type | Required? | Length Limit |
| Name of Standard Product | String | Optional | |
| Type of Standard Product | String | Optional | |
| Value of Standard Product | String | Optional |
Prices Type
Property | Description | Type | Required? | Length Limit |
| Type of Product price | String | Optional | 100 |
| Currency of Product price | String | Optional | 255 |
| Value of Product price | Float | Optional | 255 |
TaxType Type
Property | Description | Type | Required? | Length Limit |
| Country of the Tax type | String | Optional | 100 |
| Group of the Tax type | String | Optional | 100 |
| 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 |
| The unique reference identifier for the Product | String | Required | 100 |
| The name of the Product | String | Required | 255 |
| Type of the Variant Product (Recommended to be set to | String | Required | 50 |
| Status of the Variant Product | String | Optional | 50 |
| The Global Trade Item Number (GTIN) for the Product | String | Required | 20 |
| A short description of the Product | String | Optional | 255 |
| Associated base Standard Product of this Variant Product | String | Optional | 100 |
| Array of attributes for the Product | [] | Optional | |
| A list of references to the Categories to which the Product relates. Product Categories must be a part of the same . The Category must already exist. | [String] | Optional | 100 |
| Array of prices for the Product | [prices] | Optional | |
| Array of Tax types for the Product | [taxType] | Optional |
Attribute Type
Property | Description | Type | Required? | Length Limit |
| Name of Variant Product | String | Optional | |
| Type of Variant Product | String | Optional | |
| Value of Variant Product | String | Optional |
Prices Type
Property | Description | Type | Required? | Length Limit |
| Type of Product price | String | Optional | 100 |
| Currency of Product price | String | Optional | 255 |
| Value of Product price | Float | Optional | 255 |
TaxType Type
Property | Description | Type | Required? | Length Limit |
| Country of the Tax type | String | Optional | 100 |
| Group of the Tax type | String | Optional | 100 |
| 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}