Overview

When the product catalog is extensive, uploading it as a single JSON file can be slow or even fail.

To solve this, Unbxd provides the Multipart Feed Upload API, which allows you to split your catalog into smaller chunks, such as multiple JSON files, upload them, and combine them into a single feed. This ensures faster, more reliable, and scalable uploads.

Steps to Perform Multipart Feed Upload

1. Identify Your Feed Region

Why: You must upload data to the correct endpoint based on your site’s region. Each site is assigned a region (US, APAC, UK, etc.). To find the region, use the Status API: curl -v "http://feed.unbxd.io/api/<sitekey>/catalog/status?count=1"

In the response headers, look for: Unx-Route-Dest: ap-southeast-1 This will tell you the site’s region. Use the correct endpoint from the table below:

2. Start the Feed Upload

This step creates an uploadId that uniquely identifies your upload session. Use the following API to initiate the upload process:

curl -X POST 'http://feed-anz.unbxd.io/api/<sitekey>/upload/catalog/full/start' \
--header 'Authorization: <Secret Key>'

Sample Success Response Example:

{
  "uploadId": "9057d09b-0ef6-4dfa-8fd8-2eeee0f31609",
  "status": "ACCEPTED",
  "message": "File queued."
}

📘

Note

Save this uploadId, as it will be used in all subsequent steps.

3. Upload Multiple JSON Files

Upload your large catalog in manageable chunks for better performance. Use the uploadId from Step 2 in each request:

curl --request POST 'https://feed-anz.unbxd.io/api/<sitekey>/upload/catalog/full/write?feedId=<uploadId>' \
-H 'Authorization: <Secret Key>' \
-F 'file=@<filename.json>'

📘

Note

Each file you send gets appended to the feed until you finish uploading all parts.

4. End the Upload Session

It would tell the system when the uploading files is done so that the processing can begin.

curl -X POST 'https://feed-anz.unbxd.io/api/<sitekey>/upload/catalog/full/end?feedId=<uploadId>' \
-H 'Authorization: <Secret Key>'

Sample Success Response Example

{
  "uploadId": "9057d09b-0ef6-4dfa-8fd8-2eeee0f31609",
  "status": "ACCEPTED",
  "message": "File queued."
}

5. Check Feed Status

The last step is to confirm whether the feed was successfully processed and indexed.

https://feed-{{region}}.unbxd.io/api/<sitekey>/catalog/status

Common Error and Fix

• Error: Error: Length Required POST requests require a Content-Length header.
• Solution: Add this to your request: --header 'Content-Length: 0'

Takeaways

• Multipart feed upload is designed for large catalogs.
• Always check your region before starting the upload.
• Use the same uploadId for all files in one session.
• Don’t forget to end the session after uploading all parts.
• Monitor indexing using the Status API.