> For the complete documentation index, see [llms.txt](https://merchant-help.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://merchant-help.violet.io/feeds/feeds-overview/upload-feed.md). # 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 ```bash 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 ``, ``, and inventory fields are required per item — the service matches items to existing products by their ``. ```bash 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 Daily Inventory Update https://www.example.com Inventory feed TSHIRT-WHT-S in stock 48 TSHIRT-WHT-M in stock 12 TSHIRT-BLK-S out of stock 0 ``` ## Response **`202 Accepted`** — Feed uploaded successfully. Processing has started asynchronously. ```json { "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. ```json { "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. ```json { "code": "FILE_TOO_LARGE", "message": "File size exceeds 2GB limit", "timestamp": "2024-03-15T10:30:00Z" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://merchant-help.violet.io/feeds/feeds-overview/upload-feed.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.