Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Algolia Search Provider

Configure Algolia for production with the Indexing Service or test direct event forwarding with webhooks.

For production, use the Indexing Service integration for Algolia. Direct webhook processing is intended mainly for testing:

  • Indexing Service (recommended for production) – Configure Algolia as described in Indexing Service. See Indexing output by strategy for the SPLIT and MERGE document formats.

  • Webhook-based configuration (testing) – Forward index-item.updated and index-item.deleted events directly through Svix to Algolia endpoints, with transformations to match Algolia API requirements. See Webhook-based search configuration.

Indexing output by strategy

The following sections describe Algolia index document structure produced by Indexing Service for SPLIT and MERGE strategies.

The example below shows the document format stored in the Algolia index when the SPLIT strategy is active. BatteryIncluded does not support this strategy.

See an example document with SPLIT strategy
  {
  "name": [
    "Banana"
  ],
  "localizedName": {
    "en": "Banana"
  },
  "categories": [
    "Food"
  ],
  "popularity": 0,
  "prices": [
    {
      "id": "659bd4e09862ec2ec136a61b",
      "itemId": {
        "itemType": "PRODUCT",
        "id": "659bd4bfb9ce7a0b975c33eb",
        "name": {
          "en": "Banana"
        }
      },
      "currency": "EUR",
      "originalAmount": 1.99,
      "effectiveAmount": 1.99,
      "location": {
        "countryCode": "DE"
      },
      "priceModelId": "63402c86af907617bb4e1234",
      "priceModel": {
        "id": "63402c86af907617bb4e1234",
        "name": {
          "en": "Default price model"
        },
        "description": {
          "en": "Default price model"
        },
        "includesTax": false,
        "measurementUnit": {
          "quantity": 1,
          "unitCode": "pc"
        },
        "tierDefinition": {
          "tierType": "BASIC",
          "tiers": [
            {
              "minQuantity": {
                "quantity": 0,
                "unitCode": "pc"
              },
              "id": "63402c86af907617bb4e9826"
            }
          ]
        }
      },
      "restrictions": {
        "validity": null,
        "siteCodes": [
          "main"
        ]
      },
      "tierValues": [
        {
          "id": "63402c86af907617bb4e9826",
          "priceValue": 1.99
        }
      ],
      "siteCode": "main"
    }
  ],
  "description": [
    "Banana "
  ],
  "localizedDescription": {
    "en": "Banana "
  },
  "image": "http://res.cloudinary.com/saas-ag/image/upload/v1704711465/lspaymentstage/media/659bd5286bec48360e3b3a83",
  "code": "Banana",
  "categoriesMissing": false,
  "available": false,
  "distributionChannel": [
    "ASSORTMENT"
  ],
  "category_assignments": [
    {
      "id": "2918ddc4-0c1c-4977-bb91-a4c366c535a6",
      "name": "Food",
      "localizedName": {
        "en": "Food"
      },
      "code": "food",
      "localizedSlug": {
        "en": "food"
      },
      "parent": null
    }
  ],
  "category_levels": {
    "level0": [
      "Food"
    ]
  },
  "_tags": [
    "product",
    "published"
  ],
  "category_ids": [
    "2918ddc4-0c1c-4977-bb91-a4c366c535a6"
  ],
  "objectID": "urn:yaas:saasag:caasproduct:product:TENANT;659bd4bfb9ce7a0b975c33eb"
  }

The example below shows the document format stored in the Algolia index when the MERGE strategy is active.

See an example document with MERGE strategy
{
"name": [
  "Banana"
],
"localizedName": {
  "en": "Banana"
},
"categories": [
  "Food"
],
"popularity": 0,
"prices": [
  {
    "id": "659bd4e09862ec2ec136a61b",
    "itemId": {
      "itemType": "PRODUCT",
      "id": "659bd4bfb9ce7a0b975c33eb",
      "name": {
        "en": "Banana"
      }
    },
    "currency": "EUR",
    "originalAmount": 1.99,
    "effectiveAmount": 1.99,
    "location": {
      "countryCode": "DE"
    },
    "priceModelId": "63402c86af907617bb4e1234",
    "priceModel": {
      "id": "63402c86af907617bb4e1234",
      "name": {
        "en": "Default price model"
      },
      "description": {
        "en": "Default price model"
      },
      "includesTax": false,
      "measurementUnit": {
        "quantity": 1,
        "unitCode": "pc"
      },
      "tierDefinition": {
        "tierType": "BASIC",
        "tiers": [
          {
            "minQuantity": {
              "quantity": 0,
              "unitCode": "pc"
            },
            "id": "63402c86af907617bb4e9826"
          }
        ]
      }
    },
    "restrictions": {
      "validity": null,
      "siteCodes": [
        "main"
      ]
    },
    "tierValues": [
      {
        "id": "63402c86af907617bb4e9826",
        "priceValue": 1.99
      }
    ],
    "siteCode": "main"
  }
],
"description": [
  "Banana"
],
"localizedDescription": {
  "en": "Banana"
},
"image": "http://res.cloudinary.com/saas-ag/image/upload/v1704711465/lspaymentstage/media/659bd5286bec48360e3b3a83.jpg",
"code": "Banana",
"categoriesMissing": false,
"available": false,
"distributionChannel": [
  "ASSORTMENT"
],
"sitePrices": {
  "DE": [
    {
      "id": "659bd4f29862ec2ec136a61c",
      "itemId": {
        "itemType": "PRODUCT",
        "id": "659bd4bfb9ce7a0b975c33eb",
        "name": {
          "en": "Banana"
        }
      },
      "currency": "EUR",
      "originalAmount": 2.49,
      "effectiveAmount": 2.49,
      "location": {
        "countryCode": "DE"
      },
      "priceModelId": "63402c86af907617bb4e1234",
      "priceModel": {
        "id": "63402c86af907617bb4e1234",
        "name": {
          "en": "Default price model"
        },
        "description": {
          "en": "Default price model"
        },
        "includesTax": false,
        "measurementUnit": {
          "quantity": 1,
          "unitCode": "pc"
        },
        "tierDefinition": {
          "tierType": "BASIC",
          "tiers": [
            {
              "minQuantity": {
                "quantity": 0,
                "unitCode": "pc"
              },
              "id": "63402c86af907617bb4e9826"
            }
          ]
        }
      },
      "restrictions": {
        "validity": null,
        "siteCodes": [
          "DE",
          "FR"
        ]
      },
      "tierValues": [
        {
          "id": "63402c86af907617bb4e9826",
          "priceValue": 2.49
        }
      ],
      "siteCode": "DE"
    }
  ],
  "main": [
    {
      "id": "659bd4e09862ec2ec136a61b",
      "itemId": {
        "itemType": "PRODUCT",
        "id": "659bd4bfb9ce7a0b975c33eb",
        "name": {
          "en": "Banana"
        }
      },
      "currency": "EUR",
      "originalAmount": 1.99,
      "effectiveAmount": 1.99,
      "location": {
        "countryCode": "DE"
      },
      "priceModelId": "63402c86af907617bb4e1234",
      "priceModel": {
        "id": "63402c86af907617bb4e1234",
        "name": {
          "en": "Default price model"
        },
        "description": {
          "en": "Default price model"
        },
        "includesTax": false,
        "measurementUnit": {
          "quantity": 1,
          "unitCode": "pc"
        },
        "tierDefinition": {
          "tierType": "BASIC",
          "tiers": [
            {
              "minQuantity": {
                "quantity": 0,
                "unitCode": "pc"
              },
              "id": "63402c86af907617bb4e9826"
            }
          ]
        }
      },
      "restrictions": {
        "validity": null,
        "siteCodes": [
          "main"
        ]
      },
      "tierValues": [
        {
          "id": "63402c86af907617bb4e9826",
          "priceValue": 1.99
        }
      ],
      "siteCode": "main"
    }
  ],
  "FR": [
    {
      "id": "659bd4f29862ec2ec136a61c",
      "itemId": {
        "itemType": "PRODUCT",
        "id": "659bd4bfb9ce7a0b975c33eb",
        "name": {
          "en": "Banana"
        }
      },
      "currency": "EUR",
      "originalAmount": 2.49,
      "effectiveAmount": 2.49,
      "location": {
        "countryCode": "DE"
      },
      "priceModelId": "63402c86af907617bb4e1234",
      "priceModel": {
        "id": "63402c86af907617bb4e1234",
        "name": {
          "en": "Default price model"
        },
        "description": {
          "en": "Default price model"
        },
        "includesTax": false,
        "measurementUnit": {
          "quantity": 1,
          "unitCode": "pc"
        },
        "tierDefinition": {
          "tierType": "BASIC",
          "tiers": [
            {
              "minQuantity": {
                "quantity": 0,
                "unitCode": "pc"
              },
              "id": "63402c86af907617bb4e9826"
            }
          ]
        }
      },
      "restrictions": {
        "validity": null,
        "siteCodes": [
          "DE",
          "FR"
        ]
      },
      "tierValues": [
        {
          "id": "63402c86af907617bb4e9826",
          "priceValue": 2.49
        }
      ],
      "siteCode": "FR"
    }
  ]
},
"siteAvailabilities": {
  "DE": {
    "id": "DE:659bd4bfb9ce7a0b975c33eb",
    "stockLevel": 700,
    "productId": "659bd4bfb9ce7a0b975c33eb",
    "site": "DE",
    "available": false,
    "popularity": 0,
    "distributionChannel": "ASSORTMENT"
  },
  "main": {
    "id": "main:659bd4bfb9ce7a0b975c33eb",
    "stockLevel": 999,
    "productId": "659bd4bfb9ce7a0b975c33eb",
    "site": "main",
    "available": false,
    "popularity": 0,
    "distributionChannel": "ASSORTMENT"
  },
  "FR": {
    "id": "FR:659bd4bfb9ce7a0b975c33eb",
    "stockLevel": 50,
    "productId": "659bd4bfb9ce7a0b975c33eb",
    "site": "FR",
    "available": false,
    "popularity": 0,
    "distributionChannel": "ASSORTMENT"
  }
},
"category_assignments": [
  {
    "id": "2918ddc4-0c1c-4977-bb91-a4c366c535a6",
    "name": "Food",
    "localizedName": {
      "en": "Food"
    },
    "code": "food",
    "localizedSlug": {
      "en": "food"
    },
    "parent": null
  }
],
"category_levels": {
  "level0": [
    "Food"
  ]
},
"_tags": [
  "product",
  "published"
],
"category_ids": [
  "2918ddc4-0c1c-4977-bb91-a4c366c535a6"
],
"objectID": "urn:yaas:saasag:caasproduct:product:lspaymentstage;659bd4bfb9ce7a0b975c33eb"
}

Webhook-based search configuration

Direct webhook forwarding is intended mainly for testing. For production environments, use the Indexing Service integration.

Before configuring Algolia endpoints, complete the shared webhook setup in Search Configuration with Webhooks.

Creating and updating products

1

Add an endpoint

In Endpoints, choose Add Endpoint and fill in the fields with the following values:

  • Endpoint URL - https://{ALGOLIA_APPLICATION_ID}.algolia.net/1/indexes - provide your Algolia application ID

  • Description - Algolia Create/Update

  • Message filtering - select only the index-item.updated event

Svix endpoint configuration for Algolia create and update
Svix endpoint configuration for Algolia create and update
2

Save the endpoint

Choose Create and check if your configuration was properly saved.

3

Add custom headers

Go to the Advanced tab, provide the required custom headers and enable the transformation feature:

  • Key: X-Algolia-API-Key Value: YOUR_ALGOLIA_ADMIN_API_KEY

  • Key: X-Algolia-Application-Id Value: YOUR_ALGOLIA_APPLICATION_ID

Find the right values for your keys in your application settings (API Keys) in your Algolia account.

4

Enable transformations

In the Transformations section, set the transformation feature to enabled.

Transformations enabled in Svix endpoint Advanced tab
Transformations enabled in Svix endpoint Advanced tab
5

Configure the transformation mapping

In Edit transformation, start working on the Algolia mapping.

Since there are differences between the default mapping in Svix and Algolia requirements, we need to adjust the mapping to make it work properly.

The default mapping available in Svix is as follows:

/**
 * @param webhook the webhook object
 * @param webhook.method destination method. Allowed values: "POST", "PUT"
 * @param webhook.url current destination address
 * @param webhook.eventType current webhook Event Type
 * @param webhook.payload JSON payload
 * @param webhook.cancel whether to cancel dispatch of the given webhook
 */
function handler(webhook) {
  // modify the webhook object...

  // and return it
  return webhook
}

According to Algolia API Reference, the request that should be sent is as follows:

curl "https://${APPLICATION_ID}.algolia.net/1/indexes/contacts/myID" \
     -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     -d '{
            "name": "Betty Jane Mccamey",
            "company": "Vita Foods Inc.",
            "email": "betty@mccamey.com"
         }'

To learn more about Algolia API, see Algolia API Reference.

In the Edit transformation section, change the code to create the right mapping: a. Change the http method:

/**
 * @param webhook the webhook object
 * @param webhook.method destination method. Allowed values: "POST", "PUT"
 * @param webhook.url current destination address
 * @param webhook.eventType current webhook Event Type
 * @param webhook.payload JSON payload
 * @param webhook.cancel whether to cancel dispatch of the given webhook
 */
function handler(webhook) {

  webhook.method = "PUT";
  return webhook
}

b. Modify the target URL:

/**
 * @param webhook the webhook object
 * @param webhook.method destination method. Allowed values: "POST", "PUT"
 * @param webhook.url current destination address
 * @param webhook.eventType current webhook Event Type
 * @param webhook.payload JSON payload
 * @param webhook.cancel whether to cancel dispatch of the given webhook
 */
function handler(webhook) {

  var indexName = "emporix_" + webhook.payload.siteCode;
  webhook.url = webhook.url + "/" + indexName + "/" + webhook.payload.id;
  webhook.method = "PUT";
  return webhook
}

c. Optional: Modify the message body. For example, you can add additional field like image based on media field:


/**
 * @param webhook the webhook object
 * @param webhook.method destination method. Allowed values: "POST", "PUT"
 * @param webhook.url current destination address
 * @param webhook.eventType current webhook Event Type
 * @param webhook.payload JSON payload
 * @param webhook.cancel whether to cancel dispatch of the given webhook
 */
function handler(webhook) {

  if(webhook.payload.medias && webhook.payload.medias.length > 0) {
    webhook.payload.image = webhook.payload.medias[0].url;
  }

  var indexName = "emporix_" + webhook.payload.siteCode;
  webhook.url = webhook.url + "/" + indexName + "/" + webhook.payload.id;
  webhook.method = "PUT";
  return webhook
}
6

Run the transformation test

Choose Run test for the index-item.updated payload. As a result, you can see your transformed output.

7

Save your changes

If the output is correct, save your changes.

8

Test the configuration

Create a product in Management Dashboard and after a few minutes check if it appears in your index in the Algolia account. With this configuration, every time when a product is created or updated, the appropriate event is propagated to Svix, transformed and sent to Algolia.

Deleting products

1

Add an endpoint

In Endpoints, choose the Add Endpoint. Fill in the fields with the following values:

  • Endpoint URL - https://{ALGOLIA_APPLICATION_ID}.algolia.net/1/indexes - provide your Algolia application ID

  • Description - Algolia Delete

  • Message filtering - select only the index-item.deleted event

Svix endpoint configuration for Algolia delete
Svix endpoint configuration for Algolia delete
2

Save the endpoint

Choose Create and check if your configuration was properly saved.

3

Add custom headers

Go to the Advanced tab, provide the required custom headers and enable the transformation feature:

  • Key: X-Algolia-API-Key Value: YOUR_ALGOLIA_ADMIN_API_KEY

  • Key: X-Algolia-Application-Id Value: YOUR_ALGOLIA_APPLICATION_ID

Find the right values for your keys in your application settings (API Keys) in your Algolia account.

4

Enable transformations

In the Transformations section, set the transformation feature to enabled.

Transformations enabled in Svix endpoint Advanced tab
Transformations enabled in Svix endpoint Advanced tab
5

Configure the transformation mapping

According to Algolia API Reference, the request that should be sent is as follows:

To learn more about Algolia API, see Algolia API Reference.

In the Edit transformation section, change the code to create the right mapping: a. Change the http method:

b. Change the target URL:

6

Save your changes

If the output is correct, save your changes.

7

Test the configuration

Delete a product in Management Dashboard and after a few minutes check if it was deleted in your index in the Algolia account. With this configuration, every time when a product gets deleted, the appropriate event is propagated to Svix, transformed and then sent to Algolia.

PreviousIndexing Service
NextBatteryIncluded Search Provider

Last updated

Was this helpful?