Feed APIs
You can use our custom APIs to upload your feed.
Three types of feed uploads we support:
- Full Feed Upload: Use this method to upload your entire product catalog or to overwrite any previous copy of your feed on our servers.
- Delta Feed Upload: Also known as Incremental Feed Upload, use this to update/add multiple records or to upload a catalog partially.
- Single Record Upload: Use this method to update/add a single attribute within a product in your existing feed file.
Full Feed Upload
Allows you to upload the complete version of your schema and catalog files.
API Query
Post: /{siteKey}/upload/catalog/full
Get: /api/{siteKey}/catalog/status
Description
You can use our Feed APIs to upload your complete feed file as a single JSON file.
Sample Request
curl -X POST \
https://feed.unbxd.io/api/{siteKey}/upload/catalog/full \
-H 'Authorization:{secretKey}'\
-F file=@{fileName}.json`
For US region:
http://feed.unbxd.io/api/demo-unbxd700181503576558/catalog/status
For ANZ region:
https://feed-anz.unbxd.io/api/demo-unbxd700181503576558/catalog/status
For SG region:
https://feed-apac.unbxd.io/api/demo-unbxd700181503576558/catalog/status
For UK region:
https://feed-uk.unbxd.io/api/demo-unbxd700181503576558/catalog/status?count=1
Response
{
"fileName": "{fileName}",
"uploadId": "{id}",
"timeStamp": 6581239201
}
Parameters
Parameters in the API query are:
- siteKey: A unique identifier provided when you create an Unbxd account. This key can also be retrieved from the Console. This is a required field.
- fileName: The name of feed file, in JSON format.
- variantID: The unique ID of variants within the feed file. When there are variants present, the API will have the variantID of the variants.
- uploadID: The unique identifier assigned to your upload session.
- Status: Indicates the upload situation or progress of your feed file.
Status can be:- Indexing
- Indexed
- Failed
- timeStamp: Indicates the time of the file in YYYY-MM-DD | HH:MM:SS format.
- message: Indicates if the upload succeeded or failed. This field will also indicate the error code.
Sample
Here's how a full feed upload with variants will appear:
{
"feed":
{
"catalog":
{
"add":
{
"items": [
{
"uniqueId": "ss10010",
"title": "Short Sleeve Shirt",
"description": "Start your summer right with the all new short sleeve shirt."
},
{
"uniqueId": "sj10011",
"title": "Stretch Jeans",
"description": "Fit perfectly even after wash.",
"variants": [
{
"variantId": "9890101",
"vSize": "s",
"vPrice": 90
},
{
"variantId": "9890102",
"vSize": "xxl",
"vPrice": 100,
"vImages": "http://example.com/images/2-2.jpg"
}
]
}
]
}
}
}
}
Click here to view a sample feed file without variants.
Errors
We use conventional HTTP response codes to indicate success or failure of an API request.
- 201 (Ok): Indicates the upload was successful.
- 401 (Authorization Error): Indicates you may have provided an invalid API key.
- 400 (Bad Request): Indicates you may have missed a required parameter.
- 500 (Internal Server Error): Though these are rare, this indicates we may have messed up.
Check Status
To check the status of your upload within your browser:
- In the address field, type in http://feed.unbxd.io/api/<siteKey>/catalog/status
- To check the status of the last 10 uploads, type in
http://feed.unbxd.io/api/<siteKey>/catalog/status?count=10 - To view the status of your upload using the Upload ID:
Use
Path/api/{siteKey}/catalog/{upload}/status.
Once you get the response using the Upload ID, replace {uploadID}.
Best Practices
To ensure your feed is uploaded and integrated seamlessly, we recommend the following:
- When uploading a full feed, use only the Add block.
- A full feed is recommended when uploading a catalog under 2GB or less than 1 million products. If your catalog is over 2GB or more than 1 million products, we recommend you split your catalog into smaller chunks and upload these smaller files in a phased manner.
Delta Feed Upload
A delta (also known as Incremental) feed upload is when you perform a partial feed upload. Changes are updated to the existing product feed file.
API Query
Post: /{siteKey}/upload/catalog/delta
Get: /api/{siteKey}/catalog/delta/status
Description
You can use our Feed APIs to upload updated portions of your feed file as a single JSON file.
Request
curl -X POST \
https://feed.unbxd.io/api/{siteKey}/upload/catalog/delta \
-H 'Authorization:{secretKey}' \
-F file=@{fileName}.json
Response
{
"fileName": "{fileName}",
"uploadId": "{id}",
"timeStamp": 6581239201
}
Parameters
Parameters in the API query are:
- siteKey: A unique identifier provided when you create an Unbxd account. This key can also be retrieved from the Console. This is a required field.
- fileName: The name of feed file, in JSON format.
- variantID: The unique ID of variants within the feed file. When there are variants present, the API will have the variantID of the variants.
- uploadID: The unique identifier assigned to your upload session.
- Status: Indicates the upload situation or progress of your feed file.
Status can be:- Indexing
- Indexed
- Failed
- timeStamp: Indicates the time of the file in YYYY-MM-DD | HH:MM:SS format. message: Indicates if the upload succeeded or failed. This field will also indicate the error code.
Sample
This is how a delta feed upload will appear if you want to update the variants and when the variantId is unique:
{
"feed": {
"catalog": {
"update": {
"items": [
{
"variants": [
{
"variantId": "00889705456424",
"v_qty": "0",
"vSize": "s",
"vPrice": 90
}
]
}
]
}
}
}
}
If you want to update other fields of a product that has a unique ID:
{
"feed": {
"catalog": {
"update": {
"uniqueId":”12345”,
"color":"blue",
"size":10
}
}
}
}
Errors
We use conventional HTTP response codes to indicate success or failure of an API request.
- 201 (Ok): Indicates the upload was successful.
- 401 (Authorization Error): Indicates you may have provided an invalid API key.
- 400 (Bad Request): Indicates you may have missed a required parameter.
- 500 (Internal Server Error): Though these are rare, this indicates we may have messed up.
Check Status
To check the status of your upload within your browser:
- In the address field, type in http://feed.unbxd.io/api/SITE_NAME/catalog/delta/status
- To check the status of the last 10 uploads, type in
http://feed.unbxd.io/api/<siteKey>/catalog/status?count=10 - To view the status of your upload using the Upload ID:
Use
Path/api/{siteKey}/catalog/{upload}/status.
Once you get the response using the Upload ID, replace {uploadID}.
Best Practices
To ensure your feed is uploaded and integrated seamlessly, we recommend the following:
- When uploading multiple files, schedule successive uploads to happen at 10-minute intervals.
- Don’t use a delta feed API to upload a full feed.
- Don’t use a delta upload to update inventory and price information.
Feed Actions
Add
Used when you want to add a new product or variant to an existing feed file.
Used when you want to:
- Add products: When new products are added to your catalog, you can use this action to add to your existing Feed by uploading the snapshot of only those products. Once uploaded, we will add these products to your existing product feed.
- Add variants: Variants are different combinations of options for a product with the same SKU. For instance, you can have a tee shirt with two options: size and color. The size option has three values: small, medium, and large. The color option has two values: blue and green. An example of a variant would be a blue tee-shirt in large.
Add Products
Use the Add block to add new products to your catalog.
For example, let's assume you want to add a product 'Acme Party Shirt' to your catalog. The JSON to add a new product when the uniqueId does not exist would appear like this:
{
"feed": {
"catalog": {
"add": {
"items": [{
"uniqueId": "GDR1234",
"title": "Acme Party Shirt"
}]
}
}
}
}
In the code below, the 'Add' block allows you to replace a product that has an existing uniqueId:
{
"feed": {
"catalog": {
"add": {
"items": [{
"uniqueId": "GDR1234",
"title": "Acme Party Shirt",
"description": "A cotton shirt that cloths the party animal in you",
"color": "Tangerine",
"size": "L"
}]
}
}
}
}
Note: You can use the 'Add' block to add a new product when the uniqueId is already in the catalog. However, if the catalog already has the uniqueId then it will replace the entire product with the fields within the Add block.
Add Variants
It is common for product feeds to have products with multiple variants.
To add a variant to a product that already has variants and an existing uniqueId:
{
"feed": {
"catalog": {
"add": {
"items": [{
"uniqueId": "ffff78ac",
"title": "Acme Jumper Suit",
"description": "The perfect casual wear for an evening out",
"color": "Orange",
"variants": [{
"var_description": "The jumper suit for the party animal in you",
"variantId": "GOR00302",
"var_price": 400,
"color": "Dark Red"
},
{
"var_description": "The jumper suit when you don't want to blend in",
"variantId": "GOR00302",
"var_price": 400,
"color": "Purple"
}
]
}]
}
}
}
}
As in the code above, the 'Add' block allows you to pass a new variant along with all other variants and other product fields.
There are two scenarios when syncing latest changes/additions to variants using the Add action.
Scenario 1
When performing a delta upload, you can use the ‘Add’ action to add new variants to existing products as well as updating the rest of the variants.
To do this, ensure that all variants are a part of ‘Add’ block within the base product.
For example, let's assume an existing product in your catalog 'Acme Party Shirt' has 2 different variants (colors) and you want to add 1 new variant (colors) to the catalog. You can use the 'Add' block to add the new variants to the base product along with the 2 existing variants. So as to achieve this, you would be required to perform an 'Add' action for all the 3 variants, as shown in the sample JSON below:
{
"feed": {
"catalog": {
"add": {
"items": [{
"uniqueId": "GDR1234",
"title": "Superman",
"variants": [{
"variantId": "child-1",
"vColor": [{
"id": "47587",
"value": "Red"
},{
"variantId": "child-2",
"vColor": [{
"id": "47587",
"value": "Blue"
}]
},
{
"variantId": "child-3",
"vColor": [{
"id": "49867",
"value": "Green"
}],
"vSize": "S",
"vPrice": 130
}
]
},
]
}
}
}
}
Scenario 2
When performing a delta upload, you can use the ‘Add’ action to add a new product with variants.
For instance,
{
"feed": {
"catalog": {
"add": {
"items": [{
"uniqueId": "GDR1234",
"title": "Superman",
"variants": [{
"variantId": "child-1",
"vColor": [{
"id": "47587",
"value": "Red"
}]
}]
}]
}
}
}
}
Delete
Used when you want to delete products from your existing feed file.
To delete, mention the uniqueID of the product you want to delete.
{
"feed": {
"catalog": {
"delete": {
"items": [{
"uniqueId": "GDR1234"
}]
}
}
}
}
Update
Used when you want to update the values of an existing field in your existing Product Feed synced with Unbxd.
To update, upload the snapshot of the uniqueIDs of only those products along with the fields whose values need to be changed.
Generally, this action is used for updating the quantity or availability of a product.
Scenario 1
When performing a delta upload, you can use the ‘Update’ action to update only a few variants of a product, you can update the changes in the update block of that variant.
For example, let's consider you have a Product 'Acme Party Shirt' with three variants [variantId1, variantId11, variantId12] and another Product 'Lucus Casual Shirts' with the three variants [variantId2, variantId21, variantId22]. If you want to update only variantId1, variantId11 & variantId2, you can include only these three variants as in the JSON below.
{
"feed": {
"catalog": {
"update": {
"items": [{
"variants": [{
"variantId": "variantId1",
"inventoryCount": 10
},
{
"variantId": "variantId11",
"inventoryCount": 15
},
{
"variantId": "variantId2",
"inventoryCount": 12
}
]
}]
}
}
}
}
Note: You don’t have to include the uniqueId when the variantId is unique.
Similarly, when the variantId is not unique, your JSON will appear like this:
{
"feed": {
"catalog": {
"update": {
"items": [{
"uniqueId": "uniqueId1",
"variants": [{
"variantId": "variantId1",
"inventoryCount": 10
},
{
"variantId": "variantId11",
"inventoryCount": 15
}
]
},
{
"uniqueId": "unqiueId2",
"variants": [{
"variantId": "variantId2 ",
"inventoryCount": 12
}]
}
]
}
}
}
}
Scenario 2
You can use the Update block if you want to update the price, add a new field, an attribute, edit the quantity, or update a variant.
Let’s assume your feed in this scenario looks like this:
{
"uniqueId": "GDR1234",
"title": "Superman",
"price": 100,
"quantity": 40
}
If you want to update the price to $50:
{
"feed": {
"catalog": {
"update": {
"items": [{
"uniqueId": "GDR1234",
"price": 50
}
]
}
}
}
}
To add a new field to an existing feed:
{
"feed": {
"catalog": {
"update": {
"items": [{
"uniqueId": "GDR1234",
"size": "S",
"price": 50
}
]
}
}
}
}
To add an attribute sleeve-length, and set the value to "full":
{
"feed": {
"catalog": {
"update": {
"items": [{
"uniqueId": "GDR1234",
"variants": [{
"variantId": "5678",
"sleeveLength": "Full"
}]
}]
}
}
}
}
To update the quantity to 100:
{
"feed": {
"catalog": {
"update": {
"items": [{
"uniqueId": "GDR1234",
"quantity": 100
}
]
}
}
}
}
Single Record Upload
When you want to add/update just a single attribute within an existing feed file.
Recommended when you want to upload only parts of an existing product within your feed. Using single record upload instead of delta upload to update single attributes can save you time.
Request
curl -X POST 'https://feed.unbxd.io/api/{siteKey}/upload/feed?operation={operationType}'
-H 'Authorization:{secretKey}'
-d '{
"uniqueId": "parent-id-1",
"title": "batman",
"variants":
[
{
"variantId": "child-1",
"vColor": "black",
"vSize": "m",
"vPrice": 19,
"vImages": "http://example.com/images/1-1.jpg"
},
{
"variantId": "child-2",
"vColor": "blue",
"vSize": "xl",
"vPrice": 10,
"vImages": "http://example.com/images/1-2.jpg"
}
]
}
Response
{
"fileName": "{fileName}",
"uploadId": "{id}",
"status": "INDEXED",
"timeStamp": 1497016711231
"message":"success
}
Parameters
Parameters in the API query are:
- siteKey: A unique identifier provided when you create an Unbxd account. This key can also be retrieved from the Console. This is a required field.
- fileName: The name of feed file, in JSON format.
- variantID: The unique ID of variants within the feed file. When there are variants present, the API will have the variantID of the variants.
- uploadID: The unique identifier assigned to your upload session.
- Status: Indicates the upload situation or progress of your feed file.
Status can be:- Indexing
- Indexed
- Failed
- timeStamp: Indicates the time of the file in YYYY-MM-DD | HH:MM:SS format.
- message: Indicates if the upload succeeded or failed. This field will also indicate the error code.
Sample
This is how a single record upload will appear:
curl -X POST 'https://feed.unbxd.io/api/{siteKey}/upload/feed?operation={operationType}'
-H 'Authorization:{secretKey}'
-d '{
"uniqueId": "parent-id-1",
"title": "batman",
"variants": [
{
"variantId": "child-1",
"vColor": "black",
"vSize": "m",
"vPrice": 19,
"vImages": "http://example.com/images/1-1.jpg"
},
{
"variantId": "child-2",
"vColor": "blue",
"vSize": "xl",
"vPrice": 10,
"vImages": "http://example.com/images/1-2.jpg"
}
]
}
Errors
We use conventional HTTP response codes to indicate success or failure of an API request.
- 201 (Ok): Indicates the upload was successful.
- 401 (Authorization Error): Indicates you may have provided an invalid API key.
- 400 (Bad Request): Indicates you may have missed a required parameter.
- 500 (Internal Server Error): Though these are rare, this indicates we may have messed up.
Check Status
To check the status of your upload within your browser:
- In the address field, type in http://feed.unbxd.io/api/<siteKey>/catalog/status
- To check the status of the last 10 uploads, type in
http://feed.unbxd.io/api/<siteKey>/catalog/status?count=10 - To view the status of your upload using the Upload ID:
Use
Path/api/{siteKey}/catalog/{upload}/status.
Once you get the response using the Upload ID, replace {uploadID}.
Best Practices
To ensure your feed is uploaded and integrated seamlessly, remember:
- When updating feed with variants, use the Add block at the product’s parent-level.
Check Product Count
Allows you to check the number of products you have in your feed.
Get: /api/{siteKey}/catalog/size
Request
curl -X GET https://feed.unbxd.io/api/{siteKey}/catalog/size
Response
The response will have the number of products in the feed file.
Parameters
Parameters in the API query are:
- siteKey: A unique identifier provided when you create an Unbxd account. This key can also be retrieved from the Console. This is a required field.
- size: Returns the number of products indexed.
Next Steps
- Integrate Analytics
- Integrate Autosuggest