# Catalog API - coming soon

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.

{% hint style="info" %}
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.
{% endhint %}

### Catalog API authentication

To securely manage your catalog, 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](https://docs.abtasty.com/recommendations-and-merchandising/how-tos/how-to-configure-your-analytics-integration)
  * **`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]
* Array of number \[Number]
* Object of strings \[String:String]
* Object of numbers \[String:Number]
* Object of booleans \[String:Boolean]

### Catalog API Endpoints (v1)

{% hint style="info" %}
Base domain is `https://api-catalog.abtasty.com/`
{% endhint %}

#### 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

#### 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.