Docs

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.
To avoid accidental rejections, we convert your catalog to JSON after you’ve uploaded your feed file.

Full Feed Upload

Allows you to upload the complete version of your schema and catalog files.

We recommend you use the Full Feed Upload API to upload your catalog when you are uploading for the first time or if you want to overwrite untracked changes to your product categories.

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:

To locate your site key, navigate to Manage > Configure Site > Keys > Site Keys within the Console.

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.

Recommended when a previous feed is uploaded and indexed. Products not part of the delta file will remain unchanged.

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:

To locate your site key, navigate to Manage > Configure Site > Keys > Site Keys within the Console.

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

Useful when there are frequent product-based changes, like when you want to add a new product, delete an existing product, or update multiple fields within an existing product.

Add

Used when you want to add a new product or variant to an existing feed file.

This is the default feed action when performing a full feed.

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.

To prevent errors when adding fields using the 'Add' block, ensure the fields are defined within the schemas.

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.

You cannot update the field names or add/delete fields.

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
                    }

                ]
            }
        }
    }
}
Ensure the field already exists within the Schema.

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:

To locate your site key, navigate to Manage > Configure Site > Keys > Site Keys within the Console.

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