This guide walks you through how to send product updates using the Push API for a single market.
Base URL
POST https://pushapi.findify.io/v3/product
Swagger Documentation: API Reference
Ensure you have your PRIVATE ACCESS KEY. For instructions, see the Authentication guide.
Supported Operations
- upsert - Create or replace products and variants with new data.
- update - Modify specific fields of existing item groups.
- delete - Remove item groups by ID.
Product Push API Payload Schema
{
"operation": "TYPE_OF_THE_OPERATION",
"item_groups": [
{
"item_group_id": "Some Product ID",
"variants": [
{
"id": "Some Variant ID",
"field_groups": [
{
"groupType": "product",
"fields": [
{
"name": "title",
"value": "Some Product/Variant Title",
"type": "string"
},
{
"name": "size",
"value": [
"Small",
"Medium",
"Large"
],
"type": "stringArray"
},
{
"name": "rating",
"value": 4.5,
"type": "double"
},
{
"name": "ratings",
"value": [4, 4.2, 4.8],
"type": "doubleArray"
},
{
"name": "isNewProduct",
"value": true,
"type": "boolean"
},
{
"name": "price",
"value": 6,
"type": "double"
},
...
]
}
]
},
...
]
}
]
}
Field | Type | Options | Description |
|---|
operation | String | upsert, update, delete
| Type of the operation you want to execute. More on the types below. |
item_groups.item_group_id | String | Product ID | Product ID in your system |
variants | Object[] | | Array of variant objects, more on Variants fields see below |
Variants fields:
Field | Type | Options | Description |
|---|
id | String | Variant ID | Variant ID in your system |
field_groups | Object[] | | Array of fields sent on the variant level |
groupType | String | product
| For Product insert you need to use: product groupType |
fields | Object[] | | Array of fields to be pushed |
fields[].name | String | | Product/variant field name |
fields[].value | String, String[], Double, Double[], Bool, Object[]
| | Field Value |
fields[].type | String | string, stringArray, double, doubleArray, boolean
| Type of the field |
Upsert Operation
Request: POST
Using the upsert batch operation you can both create and update existing item groups/variants. If the item group/variant is not present on our end, it will be created, otherwise the item group’s/variant’s fields will be updated by our system. 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.
Required Fields
Field | Type | Value Sample | Description |
|---|
title | string | High Heels | Product/variant Title |
product_url | string | https://some_store.com/product_url | Product/variant URL |
price | double | doubleArray | 150 | Product/variant Price |
availability | string | in stock | in stock OR out of stock
|
description | string | Great High Heels! | Product Description |
category | string | Women > Shoes ### Women > Shoes > Heels | Product Category: the only field that can be nested. The format is the following: category1 > category2 > category3 ### category4 > category5 > category6 ### ..., where `>` - is a subcategory indicator, ### is a delimiter in case you want to send multiple categories for a product |
image_url | string | https://image.com/women-heels-url-full.jpg | Product/variant image |
thumbnail_url | string | https://image.com/women-heels-url-thumb.jpg | Product/variant image, smaller version. Usually used for Autocomplete Product Matches |
created_at | string | 2025-06-18T06:00:00Z | Product/variant creation date, must follow: ISO 8601 date standard |
updated_at | string | 2025-06-18T06:00:00Z | Product/variant updated_at date, must follow: ISO 8601 date standard |
Optional Fields
Field | Type | Value Sample | Description |
|---|
quantity | double | 10 | Product/variant quantity |
color | string | stringArray | Black | Product/variant colors |
size | string | stringArray | double | doubleArray | XL | Product/variant size |
brand | string | MC | Product brand/vendor |
sale_price | currency | 100 | Product/variant current sale price (discounted product/variant) |
⚠️ Choose the correct type: Once a field type is set, it cannot be changed unless all products are re-upserted. If you expect a field to have multiple string values, please choose stringArray instead of string when you send the initial product/variant data.
Payload Sample
{
"operation": "upsert",
"item_groups": [
{
"item_group_id": "Some Product ID",
"variants": [
{
"id": "Some Variant ID",
"field_groups": [
{
"groupType": "product",
"fields": [
{
"name": "title",
"value": "Some Product/Variant Title",
"type": "string"
},
{
"name": "size",
"value": [
"Small",
"Medium",
"Large"
],
"type": "stringArray"
},
{
"name": "rating",
"value": 4.5,
"type": "double"
},
{
"name": "ratings",
"value": [
4,
4.2,
4.8
],
"type": "doubleArray"
},
{
"name": "isNewProduct",
"value": true,
"type": "boolean"
},
{
"name": "price",
"value": 6,
"type": "double"
},
...
]
}
]
},
...
]
}
]
}
Update Operation
Request: POST
Unlike upsert, update operation allows only to update item groups that are already present in Merchandising Cloud - 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/variant updates to our system. 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 Merchandising Cloud.
🚧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.
In the sample below, only the title of the variant: Some Variant ID of product: Some Product ID will be updated.
Payload Sample
{
"operation": "update",
"item_groups": [
{
"item_group_id": "Some Product ID",
"variants": [
{
"id": "Some Variant ID",
"field_groups": [
{
"groupType": "product",
"fields": [
{
"name": "title",
"value": "Some Product/Variant Title",
"type": "string"
},
...
]
}
]
},
...
]
}
]
}
Delete Operation
Request: POST
Merchandising Cloud 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.
Payload Sample
{
"operation": "delete",
"item_group_ids": [
"Product ID 1", "Product ID 2", ... //string
]
}
FAQ
How can I change a field’s type?
Re-upsert all products with the correct type.
How can I confirm all data was received?
If the API returned 201 OK, it accepted your payload. If data appears missing (e.g., translations), reach out to support to investigate further. Note: full sync is not currently supported for Multimarket.