Product Catalog sync through API

This page will describe how you can use our GraphQL API to synchronize product catalog AI Knowledge with your systems, with the aim to use this knowledge in your generative AI bots.

Introduction

This feature allows to keep knowledge about products up to date, by allowing you to send updates, creations and deletion operations about the product information your system holds. Upon receiving these events, we'll index the new knowledge such that your bot can use the very latest information to answer your visitors' questions.

To do so, we'll look into how you can create a knowledge source (your product catalog), and insert, update and delete knowledge items (your products information).

Step 1: Recommended: Configure a product id custom data

Although this step is optional, we highly recommend you take the time to properly configure the custom data that holds the product id. This will enable the generative AI bots to automatically fetch the relevant product information based on the visitor's current page.

You'll find an article describing how to set up a custom data here. Take note of the custom data variable name, it will be useful during step 2.

Step 2: Create a new KnowledgeSource

This operation will only need to be done once, therefore there is no need to write any code for it.

It consists in using GraphQL to create a new KnowledgeSource, and taking note of the identifier that was attributed to it. This identifier will be used during step 3.

Using Apollo

You can open the GraphQL mutation by clicking on this link. You'll need to:

• Be logged in as an administrator.

• Replace the variables in the bottom panel with the identifier of your project, the name of the knowledge you're about to create ("API sync product catalog" for instance), and put the name of the custom data variable.

• Execute the query by clicking the KnowledgeSourceCreate blue button

• Write down the identifier of the KnowledgeSource that will appear in the right panel

Manually

Graphql Mutation

mutation KnowledgeSourceCreate(
  $knowledgeSourceCreateInput: KnowledgeSourceCreateInput!
) {
  knowledgeSourceCreate(knowledgeSourceCreateInput: $knowledgeSourceCreateInput) {
    knowledgeSource {
      id
      name
    }
  }
}

Variables

{
  "knowledgeSourceCreateInput": {
    "details": {
      "productApiSync": {
        "customDataName": "<custom data name>"
      }
    },
    "name": "<name>",
    "projectId": <project id>
  }
}

If you are requesting our GraphQL API directly, do not forget to get your GraphQL token first

Step3: Synchronize your products with us

Now you have a KnowledgeSource, you can add, update or delete items within that source. In order to do this, you'll need to react to events within your system and call our GraphQL API.

Create or update a product

You can use this mutation, bearing in mind you can submit up to 20 products in a single mutation.

If you are upserting a lot of products or a whole catalog, please comply with the 50 request per second rate limit.

Mutation

mutation KnowledgeProductUpsert($input: KnowledgeProductsUpsertInput!) {
  knowledgeProductsUpsert(input: $input) {
    knowledgeSource {
      name
    }
    upsertedProducts {
      productId
      status
    }
  }
}

Variables

{
  "input": {
    "knowledgeSourceId": "<id from step 2>",
    "products": [
      {
        "id": "<product id in your system>",
        "availability": "IN_STOCK",
        "availabilityDate": "2024-01-09",
        "brand": "my brand",
        "color": "blue",
        "condition": "NEW",
        "description": "this is my product description",
        "gender": "UNISEX",
        "imageLink": "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
        "additionalImageLink": "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
        "itemGroupId": "my group id",
        "link": "https://www.google.com",
        "material": "cotton",
        "price": {
          "currency": "EUR",
          "value": "120.00"
        },
        "productTypes": [
          "t-shirt",
          "polo"
        ],
        "size": "XL",
        "title": "my product title",
        "productDetails": [
          {
            "attributeName": "my detail name",
            "attributeValue": "my detail value"
          }
        ],
        "salePrice": {
          "currency": "EUR",
          "value": "2.0"
        }
      }
    ]
  }
}

Expected values

Some fields require defined values. Here's what's required:

• availability : IN_STOCK, OUT_OF_STOCK, PREORDER, BACKORDER

• condition : NEW, REFURBISHED, USED

• gender : MALE, FEMALE, UNISEX

You'll find more information about the definition of each fields in our static graphql documentation.

Delete a product

Mutation

mutation ($input: KnowledgeProductsDeleteInput!) {
  knowledgeProductsDelete(input: $input) {
    knowledgeSource {
      name
    }
    deletedProducts {
      productId
      status
    }
  }
}

Variables

{
  "input": {
    "knowledgeSourceId": "<id from step 2>",
    "productIds": ["<product id in your system>"]
  }
}