Catalog validations
- Overview
- Operations
- Getting Set Up (Authentication & Connectivity)
- 1. Item Field Validation (JWO — Upload Catalog)
- 2. Barcode (external_product_id) Format
- 3. Store ID Authorization
- 4. SKU Uniqueness and Upsert Behavior
- 5. Price and Tax Code
- 6. Archive Catalog
- 7. Checking Upload Status (Get Catalog Upload Status)
- 8. Errors
- Quick Checklist
Overview
As you use Amazon's retail technology, you provide Amazon with a catalog of product information and keep it up to date. This guide describes the validation rules your requests must satisfy, the constraints published in the Amazon developer documentation, and the errors you may receive.
Operations
| # | Operation | HTTP | Store Type | Purpose |
|---|---|---|---|---|
| 1 | Upload Catalog | POST /v1/catalog/upload | JWO | Upload items for sale in your JWO store |
| 2 | Upload Cart Catalog | POST /v1/catalog/cart/upload | Dash Cart | Upload items sold in your Dash Cart store |
| 3 | Archive Catalog | POST /v1/catalog/archive | JWO | Archive items by SKU across all stores |
| 4 | Get Catalog Upload Status | POST /v1/catalog/getCatalogUploadStatus | JWO | Retrieve processing status by ingestionId |
Upload and archive operations are asynchronous: on success they return an ingestionId you use to poll status and to correlate the completion notification. Store the ingestionId from every response.
Rate and volume limits: 10 requests per second and a maximum of 10,000 items per upload (and per archive request). Split larger jobs across multiple calls.
Getting Set Up (Authentication & Connectivity)
- Access is granted per AWS account. During onboarding (Merchant Portal → Catalog → Catalog API Setup) you supply your AWS Account Id (to be allowlisted), an SQS ARN, and the list of stores you are authorized to call.
- Calls are signed with SigV4 using an IAM role. That role must have the Invoke API permission and be allowlisted in JWO — otherwise the API returns 403.
- Completion notifications are delivered asynchronously: Amazon publishes an SNS message (containing
ingestionIdand a reportdownloadLink) to a queue namedJWOCatalogIngestionStatusQueue. Do not rename or alter the queue or its policy. Confirm the SNS subscription within 48 hours or the request expires.
1. Item Field Validation (JWO — Upload Catalog)
Each catalog item (CatalogItem) supports the following fields:
| # | Field | Type | Required? | Rule |
|---|---|---|---|---|
| 1 | item_sku | String | Required | Max length 255. Unique identifier for the product, assigned by you. |
| 2 | external_product_id | String | Required | Max length 255. The scannable barcode value. Must match expected form for its type. |
| 3 | external_product_id_type | String/Enum | Optional | One of: UPC, ISBN, EAN, EAN8, GTIN, PLU. |
| 4 | additional_external_product_information | List | Optional | Up to 50 entries; associates additional barcodes with one SKU. |
| 5 | item_name | String | Required | Max length 255. A short product title. |
| 6 | store_id | String | Required | Max length 255. Unique identifier for your store, defined during onboarding. |
| 7 | standard_price | String | Optional | Max length 10. Price with or without tax, in local currency. |
| 8 | brand_name | String | Optional | Max length 255. |
| 9 | product_tax_code | String | Optional | Max length 255. Amazon Standard code identifying product tax properties. |
Batch size: An upload must contain between 1 and 10,000 items.
Minimum required fields: item_sku, external_product_id, item_name, and store_id. Omitting any results in a 400 validation error.
Additional fields: color_name (max 50), size_name (max 50), unit_of_measure (g, kg, lb, oz, ml, l, gal), main_image_url, other_image_url1…other_image_url8, and fallback_configuration (for Smart Device products).
2. Barcode (external_product_id) Format
Your external_product_id must be a valid, correctly-formed scannable barcode. The value must match the expected length and check digit for its type:
| # | Type | Expected Form |
|---|---|---|
| 1 | UPC | 12 or 8 digits |
| 2 | EAN | 13 digits |
| 3 | EAN8 | 8 digits |
| 4 | ISBN | 10 digits |
| 5 | GTIN | 14 digits |
| 6 | PLU | Integer PLU code |
- Barcodes with an incorrect check digit, wrong length for their type, or non-numeric characters (except PLU) are rejected.
- Provide
external_product_id_typewhen you can. If omitted, the type is inferred from the value. - Values in scientific notation (e.g., an Excel-corrupted value such as
[MAC_ADDRESS]) are rejected — export your barcodes as plain text.
3. Store ID Authorization
Requests are scoped to your account. Every store_id you send must belong to your account and must all be associated with the same retailer. If not, the request is rejected:
- Invalid store_id: "One or more StoreID's present in the request is incorrect"
- Cross-retailer stores: "List of store ID's present in the request are either incorrect / not associated with the same retailer"
If your account has not been configured for catalog uploads, you receive a 404 (MerchantResourceNotFoundException); a missing or non-allowlisted IAM role returns a 403.
4. SKU Uniqueness and Upsert Behavior
item_skuis your product's identifier and must be unique for each product you list.- Upsert by SKU: Amazon matches each incoming item by its SKU. If a match exists, the stored values are updated; if not, a new item is created.
- A barcode identifies a single active product. Submitting the same barcode under a different SKU is treated as a duplicate and is rejected.
- Archiving is not a permanent delete. If you archive a product and later upload an item with the same barcode/SKU, the previously archived product is reactivated. To retire a product permanently, do not re-submit its barcode.
- Up to 10,000 SKUs per upload (and per archive request).
5. Price and Tax Code
Price (standard_price)
- Published constraint: a string, max length 10, representing the price (with or without tax) in your local currency.
- Service validation (returned as a 400): must parse as a number greater than 0 (zero and negative are rejected), must not exceed the per-item maximum, and is stored to 2 decimal places. Non-numeric values are rejected. If omitted, a nominal default price is applied.
Tax Code (product_tax_code)
- A string (max length 255) — an Amazon Standard tax code identifying the product's tax properties.
- Where a store type requires it, the value must be a recognized Amazon Standard tax code; unrecognized codes may be rejected. May be left blank.
6. Archive Catalog
POST /v1/catalog/archive marks products inactive by SKU.
- itemSkus (required): SKUs to archive; each must match an existing active product. Up to 10,000 per request.
- allApplicableStores (required): must contain every store ID for your retailer — not just the stores where the SKU is sold. A partial list is rejected. Archiving is retailer-wide because barcodes/SKUs are merchant-level properties.
- Behavior: Items are deactivated but their data and transaction history are preserved. Reactivate an archived item by uploading it again via Upload Catalog.
- SKU-level errors (e.g., the SKU is still on a planogram, or is already archived) are reported asynchronously in the processing report, not in the API response.
Recommended workflow: Call the API → store the ingestionId → poll status → download the report → confirm every SKU shows SUCCESS → only then remove the SKU from your POS.
Archive-Specific Errors
- 400 — Partial store list: "All applicable stores for one retailer must be provided."
- 400 — Cross-retailer stores: "Store IDs are either incorrect or not associated with same retailer."
- 400 — All IDs invalid: "The entered store ID is invalid."
- 400 — Bad format or over 10,000 SKUs: "Invalid request body."
- 500 — Store config issue: "Error with store configuration. Please contact customer support."
7. Checking Upload Status (Get Catalog Upload Status)
POST /v1/catalog/getCatalogUploadStatus
- processingStatus values:
DONE(completed successfully),INQUEUE/INPROGRESS(still processing),CANCELLED/FATAL(failed). Poll until you reach a terminal state. - reportDownloadLink is the processing report. The download link is valid for 60 minutes before it expires.
- Results are also delivered proactively via the SNS notification (
ingestionId+downloadLink) to your configured queue.
Status Errors
- 400 — Invalid
ingestionId, or aningestionIdnot associated with your retailer. - 429 — Too Many Requests.
- 500 — Server error.
8. Errors
| HTTP | Error | Meaning | Detail | Retry? |
|---|---|---|---|---|
| 400 | BadRequestException | Invalid request body | Null sent instead of empty string, or list over threshold. | No |
| 400 | InvalidRequestException | Validation error | Incorrect/mismatched store IDs, or item fails field rule. | No |
| 403 | (IAM) | Permission denied | IAM role lacks Invoke API permission or not allowlisted. | No — fix perms |
| 404 | MerchantResourceNotFound | Not configured | AWS account not configured for the retailer. | No |
| 429 | TooManyRequests | Rate limit exceeded | Exceeds 10 req/s. | Yes — backoff |
| 500 | InternalServerException | Server error | Server-side error. | Conditional |
Error body format: { "errorMsg": "<message>" }
Quick Checklist
- Your IAM role is allowlisted in JWO and signs requests with SigV4; your SNS subscription is confirmed.
- All items include
item_sku,external_product_id,item_name, andstore_id. - Barcodes are valid for their type (correct length and check digit); no scientific notation.
- All
store_idsbelong to your account and the same retailer. - Each barcode maps to a single SKU; you are not reusing an archived barcode unless you intend to reactivate it.
- Prices are positive numbers, ≤ 2 decimals, within the per-item limit.
product_tax_codeis a valid Amazon Standard tax code (or blank).- For archive,
allApplicableStoreslists every store ID for your retailer. - Batches contain no more than 10,000 items; you send no more than 10 requests/second.
- You store the
ingestionId, poll status to a terminal state, and confirm SUCCESS in the report before deleting SKUs from your POS. - 429 responses are retried with progressive backoff; report download links are used within 60 minutes.
