Upload Feed

POST /v1/feeds
Content-Type: multipart/form-data

Upload a product catalog feed file for processing. The file is validated, stored, and processed asynchronously through a workflow pipeline. The response is returned immediately with a 202 Accepted status while processing continues in the background.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer msk_{merchant_id}{uuid}
Content-Type	Yes	multipart/form-data

Form Parts

Part	Type	Required	Description
file	binary	Yes	The feed file. Max size: 2 GB. Accepted formats: Google Product Feed XML (application/xml or text/xml).
feedName	string	Yes	A human-readable name for this feed. Example: "Summer 2024 Product Catalog"
feedType	string	Yes	Must be CATALOG or INVENTORY.
parentFeedId	string	Only for INVENTORY	The feed_id of the parent catalog feed. Required when feedType is INVENTORY. Example: "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Feed Types

Type	Description
CATALOG	A full product catalog containing product information, pricing, and availability. Generates a feed ID prefixed with cat_.
INVENTORY	An inventory update for an existing catalog feed. Must reference a parent catalog feed via parentFeedId. Generates a feed ID prefixed with inv_.

Example Requests

Catalog Feed

curl -X POST https://api.violet.io/v1/feeds \
  -H 'Authorization: Bearer msk_12345abc11094a44800d84017c593e22' \
  -F 'file=@products.xml' \
  -F 'feedName=Summer 2024 Product Catalog' \
  -F 'feedType=CATALOG'

Inventory Feed

Inventory feeds update stock levels for products in an existing catalog feed. The XML uses the same Google Product Feed format, but only <g:id>, <g:availability>, and inventory fields are required per item — the service matches items to existing products by their <g:id>.

curl -X POST https://api.violet.io/v1/feeds \
  -H 'Authorization: Bearer msk_12345abc11094a44800d84017c593e22' \
  -F 'file=@inventory-update.xml' \
  -F 'feedName=Daily Inventory Update' \
  -F 'feedType=INVENTORY' \
  -F 'parentFeedId=cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890'

Example inventory-update.xml:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0">
  <channel>
    <title>Daily Inventory Update</title>
    <link>https://www.example.com</link>
    <description>Inventory feed</description>

    <item>
      <g:id>TSHIRT-WHT-S</g:id>
      <g:availability>in stock</g:availability>
      <g:inventory>48</g:inventory>
    </item>

    <item>
      <g:id>TSHIRT-WHT-M</g:id>
      <g:availability>in stock</g:availability>
      <g:inventory>12</g:inventory>
    </item>

    <item>
      <g:id>TSHIRT-BLK-S</g:id>
      <g:availability>out of stock</g:availability>
      <g:inventory>0</g:inventory>
    </item>

  </channel>
</rss>

Response

202 Accepted — Feed uploaded successfully. Processing has started asynchronously.

{
  "feed_id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING",
  "message": "Feed uploaded successfully and processing initiated",
  "timestamp": "2024-03-15T10:30:00Z",
  "merchant_id": 12345,
  "workflow_id": "feed-upload-cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "uploaded_at": "2024-03-15T10:30:00Z"
}

Response Fields

Field	Type	Description
feed_id	string	Unique identifier for the feed. Prefixed with cat_ for catalog feeds or inv_ for inventory feeds.
status	string	Processing status. Will be PENDING immediately after upload.
message	string	Human-readable description of the operation result.
timestamp	string (ISO 8601)	When the upload completed.
merchant_id	integer	Your merchant ID.
workflow_id	string	ID of the processing workflow. Can be used to track async processing.
uploaded_at	string (ISO 8601)	When the file was uploaded to storage.

Error Responses

400 Bad Request — Validation failed.

{
  "code": "INVALID_FEED_TYPE",
  "message": "feedType must be CATALOG or INVENTORY",
  "timestamp": "2024-03-15T10:30:00Z"
}

Common error codes:

Code	Description
INVALID_FEED_TYPE	feedType must be CATALOG or INVENTORY.
MISSING_PARENT_FEED	parentFeedId is required for INVENTORY feeds.
INVALID_FILE	The uploaded file is empty.
MISSING_AUTHENTICATION	No Authorization header provided.

413 Payload Too Large — File exceeds the 2 GB limit.

{
  "code": "FILE_TOO_LARGE",
  "message": "File size exceeds 2GB limit",
  "timestamp": "2024-03-15T10:30:00Z"
}