/product

Payload Structure

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

At the moment 3 operations are supported:

• upsert - create new item groups, or replace existing ones with new data (all fields are updated)
• 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, // can be provided in variants array
		description: string,
		price?: number, // no float or double, additional validation, can be provided in variants array
		image_url?: string, // can be provided in variants array
		product_url?: string, // can be provided in variants array
		category: string,
		thumbnail_url?: string, // can be provided in variants array
		availability?: "in stock" | "out of stock", // can be provided in variants array
		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

Item Group and Variant

We treat each product as a collection of variants that are joined using the item_group_id property. This means that each variant can have it's own full set of fields, including product_url, image_url, color, price etc.

After the grouping phase is performed, all the variants with the same item_group_id will be joined together and their properties will be propagated in the grouped product. So when querying the Search API, you will receive a color field as an array of strings if there are multiple variants with different colors.

All this means, that if you have variants that own specific properties, like color or price, you don't need to provide the values of such properties in the fields of the grouped item API request if they are present in the variants array.

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.