Fluent Commerce Logo
Docs
Sign In

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.

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}

Language: json

Name: UPSERT_CATEGORY: Create a New Category

Description:

This request will create a new category

`GAMING_CHAIR`
nested under the existing category
`CHAIR`
.

Endpoint: POST {{fluentApiHost}}/api/v4.1/event/async

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}

Language: json

Name: UPSERT_CATEGORY: Update a Category with a Child

Description:

This request will associate

`GAMING_CHAIR`
as a child of the
`CHAIR`
category, creating a hierarchical structure.

Endpoint: POST {{fluentApiHost}}/api/v4.1/event/async


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


Attribute Type

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


Prices Type

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

TaxType Type

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}

Language: json

Name: UPSERT_PRODUCT

Description:

Update or Insert Standard Product

Endpoint: POST {{fluentApiHost}}/api/v4.1/event/async

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


Attribute Type

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


Prices Type

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

TaxType Type

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}

Language: json

Name: UPSERT_PRODUCT

Description:

Update or Insert Variant Product

Endpoint: POST {{fluentApiHost}}/api/v4.1/event/async