Catalog API

This API allows you to manage your product catalog dynamically, bypassing the traditional CMS feed integration. The Catalog API acts as a separate integration type and is visible in the integrations settings like other integration methods.

The Catalog API cannot work alongside a standard catalog integration. You must choose to use either the Catalog API or a catalog Feed/CMS integration for your catalog management.

Catalog API authentication

To manage your catalog securely, the API uses a dedicated API key that is only authorized to manage the catalog. The standard recommendation API key does not have permission to edit the catalog.

To use the Catalog API endpoints, you must generate a Catalog API key and authenticate all your requests with it.

curl 'https://api-catalog.abtasty.com/ENDPOINT' \
-H 'authorization: Bearer CATALOG_API_KEY'

Catalog structure management

Catalog item fields requirements

Catalog items are represented as objects that must contain the following fields:

• Mandatory fields: Every catalog item must include the following fields:

  • id : the unique ID of the item. It should be a string of 40 characters maximum.
  • is_recommendable: a true/false boolean indicating if your product can be recommended.
  • name: the display name of the item. It should be a string or null.
  • absolute_link: the PDP url of the item. It should be a string or null.
  • img_link: the main image url of the item. It should be a string or null.
  • price: the price of the item. It should be a number or null.
  • categories_ids: the categories of the item. It should be a array of string or null.
• Required to connect with your analytics solution: These fields are the keys that will be used to link your analytics events to your catalog items. Learn more on analytics documentation

  • item_purchase_key: an identifier accessible in your purchase event properties that will be the link between the purchase event and the item. Product id or product key is often used here. It should be an array of string or null.
  • item_pageview_key: an identifier accessible in your pageview event properties that will be the link between the pageview event and the item. Product canonical url or product id is often used here. It should be an array of string or null.
• Custom fields: You can define as many custom fields as you need by adding them to the payload. Each field sent in the payload will be dynamically added to your catalog schema.

Example of a catalog item object:

{
    // Mandatory fields
    "id": "my-unique-id",
    "is_recommendable": true,
    "name": "My product name",
    "absolute_link": "https://e-commerce.com/p/my-product-url",
    "img_link": "https://cdn.e-commerce.com/p/my-product/main-image",,
    "price": 14.02,
    "categories_ids": ["category_A", "category_B"],
    // Required for analytics link
    "item_purchase_key": ["my-purchase-item-key"],
    "item_pageview_key": ["https://e-commerce.com/p/my-product-url"],
    // Custom fields
    "custom_field_1": "xyz",
    "color": "red",
    "availability_per_shop": ["001": true, "002": false, "003": true],
    ...
}

Dynamic catalog schema & typing constraints

Catalog API schema is dynamic. When sending product data through the API, catalog item fields are accepted and created dynamically based on your payload.

The API strictly enforces data types. A custom field's data type is determined by the first value sent through the API. For example: if you create a product with the field "color" and the value "red", a catalog field named "color" is automatically created and assigned the type "string". All future products with a field "color" should now have either an empty value or a string value.

Supported fields types

• String
• Number
• Boolean
• Array of string [String]
• Object of strings [String:String]
• Object of numbers [String:Number]
• Object of booleans [String:Boolean]

Catalog API Endpoints (v1)

Base domain is https://api-catalog.abtasty.com/

Add or replace a product

PUT /indexes/catalog/{itemID}

Description: Use this endpoint to add a new product or entirely replace an existing product in the catalog based on its itemID.

Payload example:

{
    "id": "my-unique-id",
    "is_recommendable": true,
    "name": "My product name",
    "absolute_link": "https://e-commerce.com/p/my-product-url",
    "img_link": "https://cdn.e-commerce.com/p/my-product/main-image",,
    "price": 14.02,
    "categories_ids": ["category_A", "category_B"],
    "item_purchase_key": ["my-purchase-item-key"],
    "item_pageview_key": ["https://e-commerce.com/p/my-product-url"],
    "custom_field_1": "xyz",
    ...
}

Delete a product

DELETE /indexes/catalog/{itemID}

Description: Deletes a single product from the catalog matching the specified itemID.

Payload example:

{
    "id": "my-unique-id",
}

Delete all products

DELETE /indexes/catalog

Description: Deletes all products from the catalog while keeping in memory the existing schema.

Payload: null

Delete a catalog field

DELETE /indexes/catalog/schema/{fieldID}

Description: Deletes a catalog field from the catalog schema matching the specified fieldID.

If a field was created with the wrong type, use this endpoint to remove it. Since field types cannot be changed after creation, you will need to recreate the field with the correct type.

Batch operations

POST /indexes/catalog/batch

Description: This endpoint allows you to add, replace, or delete multiple products in the catalog using a single API request.

Batch size limit: Payload size should be less than 50MB and maximum 10 000 operations per call.

Payload example:

[
  {
    "operation":"create-replace",
    "product": {
        "id": "my-unique-id",
        "is_recommendable": true,
        "name": "My product name",
        "absolute_link": "https://e-commerce.com/p/my-product-url",
        "img_link": "https://cdn.e-commerce.com/p/my-product/main-image",,
        "price": 14.02,
        "categories_ids": ["category_A", "category_B"],
        "item_purchase_key": ["my-purchase-item-key"],
        "item_pageview_key": ["https://e-commerce.com/p/my-product-url"],
        ...
    }
  },
  {
    "operation":"delete",
    "product":{ "id": "my-unique-id-2" }
  },
  ...
]

Catalog synchronization recurrence

When building your integration with Catalog API, be aware of the following technical limitations and synchronization behaviors:

• Catalog API operations are validated synchronously.
• The catalog visible in the platform and used for your strategy results is only updated after a synchronization job runs, not after each API call. By default, synchronization runs once per day. The update frequency can be increased according to your needs.