Payload Structure

  "operation": "upsert" | "update" | "delete",
  "item_groups"?: Product[],
  "item_group_ids"?: string[]

At the moment 3 operations are supported:

  • upsert - update provided item groups, or create them if they don't exist
  • update - update some fields of the provided item groups
  • delete - remove item groups from index

For reference of example values of required and optional fields please refer to JSON Feed Specification.

interface Product {
    item_group_id: string,
    fields: {
        // required fields
        title: string,
        url : string,
        description: string,
        price: number, // no float or double, additional validation
        image_url: string,
        product_url: string,
        category: string,
        thumbnail_url: string,
        availability: "in stock" | "out of stock", 
        created_at: string, //ISO 8601 date
        updated_at: string, //ISO 8601 date

        // optional fields
        sku?: string,
        brand?: string,
        seller?: string,
        sale_price?: number, // no float or double
        cost?: number, // no float or double
        size?: string,
        quantity?: number,
        reviews.average_score?: number,
        reviews.count?: number,
        // any custom field using this syntax
        [field name]: string | number | boolean | string[] | number[]
    // Optional variant list
    variants?: [
            id: string,
            // Same structure as product
            fields: {
                [field name]: string | number | boolean | string[] | number[]


At the moment we don't support objects or nested objects as allowed types of item group

Upsert operation

Using the upsert batch operation you can both create and update existing item groups. If the item group is not present on Findify's end, it will be created, otherwise the item group's fields will be updated by Findify. We use the item_group_id field that is provided to link the item group in the request to our internal product database, so you must provide the same item_group_id used when creating an item group if you need to update it. You must provide all required fields in the payload and any number of optional fields that your item group might have.

For upsert batch operation you need to provide all the required fields from the model and any number of optional fields if they are relevant to the product you are sending.

Update operation

Unlike upsert, update operation allows only to update item groups that are already present in Findify - you cannot create add new item groups with update operation. However, the benefit of update is that all the fields of the payload, except for item_group_id (and variant id if variants array is present in the payload) are optional, so you can use this route to send partial item group updates to Findify. This can be useful when you just need to update the price, availability, or quantity of the item group and don't want to pass the whole object to Findify.


Combine multiple item group updates into one request

If you need to update several fields of one item group, we recommend to send one update that includes all the fields that need to be updated for optimal performance and fast item group updates.


Removing a fields is not supported for update operation

If you want to remove a field from a product, rather than updating it - you need to use the upsert operation.

Delete operation

Findify will remove all item groups with the specified item group IDs if they are present in our system. For this operation you must provide the item_group_ids parameter in your request.


Removing variants is not supported by delete operation

If you need to remove one or more variants, you need to use the upsert operation.

Click Try It! to start a request and see the response here!