How to: sync products catalog, categories

Intro

This guide will walk you through syncing Merchant's store's product catalog via Products API, which enables powerful features such as:

Product Recommender: Leverage the Omnisend's product recommender to suggest relevant products to your merchant's customers based on their browsing and purchase history.
Automated Product Inclusion: Easily include product information in merchant's marketing campaigns, such as email templates and dynamic content, without manual data entry.

See the detailed API reference for products and categories

Create a product

In order to create product one by one use the POST /products endpoint. Here's an example using the curl command to create a new product:

curl --location 'https://api.omnisend.com/v5/products' \
--header 'X-Forwarded-For: 127.0.0.0.1' \
--header 'Content-Type: application/json' \
--header  'X-API-KEY: BRAND_API_KEY' \
--data '{
    "id": "product-id-123",
    "url": "http://www.example.com/products/prod-666",
    "defaultImageUrl": "http://www.example.com/images/products/default.png",
    "title": "Product title",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin ut volutpat neque. Etiam vel vulputate neque. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis fringilla ex ex, eget tincidunt metus ornare eu.",
    "vendor": "Pear",
    "type": "Plastic",
    "status": "inStock",
    "currency": "UZS",
    "createdAt": "2022-06-18T00:00:01Z",
    "updatedAt": "2022-07-11T00:00:01Z",
    "variants": [
        {
            "id": "product-variant-id-123",
            "title": "Product variant title",
            "sku": "123",
            "price": 28.99,
            "strikeThroughPrice": 30.99,
            "status": "inStock",
            "defaultImageUrl": "http://www.example.com/images/variant/default.png",
            "url": "http://www.example.com/variant/prod-11",
            "images": [
                "http://www.example.com/images/variant/1.png",
                "http://www.example.com/images/variant/2.png",
                "http://www.example.com/images/variant/3.png"
            ],
            "description": "variant description"
        }
    ],
    "images": [
        "http://www.example.com/images/products/1.png",
        "http://www.example.com/images/products/2.png",
        "http://www.example.com/images/products/3.png"
    ],
    "tags": [
        "tag1",
        "tag2",
        "tag3"
    ],
    "categoryIDs": [
        "category-1",
        "category-2"
    ]
}'
'

Update product

Use the PUT /products/{productID} endpoint to replace an existing product.

Here's an example using the curl command:

curl --location --request PUT 'https://api.omnisend.com/v5/products/product-id-123' \
--header 'X-API-KEY: X-API-KEY: BRAND_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \

--data '
{
  "id":"product-id-123",
  "title": "Container for mojo",
  "status": "inStock",
  "url": "http://www.example.com/products/prod-666",
  "currency": "USD",
   "variants": [
        {
            "id": "product-variant-id-123",
            "title": "Product variant title",
            "sku": "123",
            "price": 28.99,
            "strikeThroughPrice": 30.99,
            "status": "inStock",
            "defaultImageUrl": "http://www.example.com/images/variant/default.png",
            "url": "http://www.example.com/variant/prod-11",
            "images": [
                "http://www.example.com/images/variant/1.png",
                "http://www.example.com/images/variant/2.png",
                "http://www.example.com/images/variant/3.png"
            ],
            "description": "variant description"
        }
    ]
  }
'

Create/update products in batch

Using the batch endpoint to create/update products saves time, minimises API calls, reduces rate limit risks, and improves scalability.

We recommend keeping the payload size limited to a maximum of 1MB to ensure optimal performance and efficient data transmission.

Use POST /batches endpoint to create/update multiple products. Here is an example for creating products:

curl --request POST \
     --url https://api.omnisend.com/v5/batches \
     --header 'X-API-KEY: MERCHANT_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "method": "POST",
    "endpoint": "products",
    "items": [
        {
            "categoryIDs": [
                "cat123"
            ],
            "id": "abc123",
            "title": "Shirts",
            "status": "inStock",
            "currency": "USD",
            "productUrl": "http://www.example.com/products/prod-666"
        }
    ]
}
'

Change method to PUT if you need to update multiple products.

Create products category

In order to create products category use the POST /product-categories endpoint. Here's an example using the curl command:

curl --request POST \
     --url https://api.omnisend.com/v5/product-categories \
     --header 'X-API-KEY: BRAND_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "categoryID": "cat667",
  "title": "Containers"
}
'

Update products category

You can update/replace products category using the PATCH /product-categories/{categoryID} endpoint. Here's an example using curl command:

curl --request PATCH \
     --url https://api.omnisend.com/v5/product-categories/cat123 \
     --header 'X-API-KEY: BRAND_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "title": "New title2"
}
'