Step by Step guide

Example

Here we'll show an example of a parent item and a variant being sent. Once the items have been sent, we will promote the catalog as active. We then send a patch on the variant.

The sample of items:

Item parent

{
    "id": "A0001",
    "attributes": {
        "title": "My item",
        "description": "This is my item."
    }
}

Item variant

{
    "id": "B0001",
    "attributes": {
        "price": 2000,
        "color": "red"
    },
    "parentId": "A0001"
}

Create the item schema

The first step is to create an item schema. It must contain the attributes of the item and its variant.

Request

POST /item-schemas?tenant=mycompany&environment=production

{
    "name": "product",
    "attributes": [
        {
            "name": "title",
            "type": "TEXT"
        },
        {
            "name": "description",
            "type": "TEXT"
        }
    ],
    "nestedItemSchemas": [
        {
            "name": "variant",
            "attributes": [
                {
                    "name": "price",
                    "type": "INTEGER"
                },
                {
                    "name": "color",
                    "type": "TEXT"
                }
            ]
        }
    ]
}

Response

{
    "version": 1
}

Create the catalog

Next, create a catalog version. As this is the first catalog the version is 1, but you can list your catalogs.

Remember! Catalog API can handle only 2 catalogs at the same time. If this limit is reached, one inactive catalog must be deleted by using the API before creating a new one. Determining the inactive catalog is done by listing all catalogs API.

Request

POST /catalogs?tenant=mycompany&environment=production

{
    "catalogItemSchemas": [
        {
            "name": "product",
            "version": 1
        }
    ]
}

Response

{
    "version": 1
}

Sending the items

Request

POST /items?tenant=mycompany&environment=production

[
    {
        "id": "A0001",
        "catalogVersion": 1,
        "type": "product",
        "attributes": {
            "title": "My item",
            "description": "This is my item."
        }
    },
    {
        "id": "B0001",
        "catalogVersion": 1,
        "type": "variant",
        "attributes": {
            "price": 2000,
            "color": "red"
        },
        "parentId": "A0001"
    }
]

Response

{
    "requestIds": [
        {
            "itemId": {
                "id": "A0001",
                "catalogVersion": 1,
                "context": "",
                "type": "product",
                "tenant": "mycompany",
                "environment": "production"
            },
            "requestId": "1888742087434729"
        },
        {
            "itemId": {
                "id": "B0001",
                "catalogVersion": 1,
                "context": "",
                "type": "variant",
                "tenant": "mycompany",
                "environment": "production"
            },
            "requestId": "1888742087434730"
        }
    ]
}

Then, promote your catalog version.

POST /catalogs/promote/1?tenant=mycompany&environment=production

After a short period of time, the catalog will be active and usable.

Patch method

To quickly change the attribute of an item, use the patch method.

Here is an example of changing the price of the variant:

Request

PATCH /items?tenant=mycompany&environment=production

[
    {
        "id": "B0001",
        "catalogVersion": 1,
        "type": "variant",
        "attributes": {
            "price": 1500,
        },
        "parentId": "A0001"
    }
]