Feed API
You can use our Feed 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. We recommend full feed uploads occasionally to ensure that your Unbxd catalog is in sync with the production systems.
- Delta Feed Upload: Also known as Incremental Feed Upload, use this to update/add multiple records or to upload a catalog partially.
- Check Product Count: Use this to verify the total number of products in your catalog before or after an upload.
Feed Actions
These are 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.
NoteWe support only one type of feed action (operation) in a single delta upload request.
For eg: it can be either of Add, Update, or Delete for delta uploads. You cannot use multiple operations in the same delta uploads.
Add
Used when you want to add a new product, reset product fields within your existing feed, or add/update variants to an existing feed file. This is the default feed action when performing a full feed. You can use the Add block when you want to:
Add Product
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 T-shirt with size and color options. 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 T-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"
}]
}
}
}
}
NoteYou 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.
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 product fields.
There are two scenarios when syncing the 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 update the rest of the variants. To do this, ensure that all variants are a part of the ‘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 and the two existing variants. So as to achieve this, you would be required to perform an ‘Add’ action for all three 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 and the fields whose values need to be changed. Generally, this action is used to update the quantity or availability of a product.
Scenario 3
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 when the variantIds are unique as in the JSON below.
{
"feed": {
"catalog": {
"update": {
"items": [{
"uniqueId": "uniqueId1",
"variants": [{
"variantId": "variantId1",
"inventoryCount": 10
},
{
"variantId": "variantId11",
"inventoryCount": 15
}
]
},
{
"uniqueId": "unqiueId2",
"variants": [{
"variantId": "variantId2",
"inventoryCount": 12
}]
}
]
}
}
}
}
NoteYou don’t have to include the uniqueId when the variantId is unique.
Similarly, when the variantId is not unique, the uniqueId needs to be included. 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 to update the price, add a new field or 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
}
]
}
}
}
}
NoteEnsure 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
}
]
}
}
}
}Check Product Count
Allows you to check the number of products you have in your feed.
Method : GET
End Point : {feed end point}/api/{siteKey}/catalog/size
Description : This API will provide the size of the uploaded feed. 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 your feed has.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.Sample 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.Best Practices
- We should specify clearly whether the schema and catalog can be part of one document together or separately.
- We should document if there is a limit on file size, record count for schema, and catalog files
- We should document feed processing failures midway and their effect on indexing.
- Document the time taken to record the index file.
Updated 16 days ago