Use the Amazon SP-API Listings Items API to create and update listings programmatically. PUT to /listings/2021-08-01/items/{sellerId}/{sku} with product attributes matching the Product Type Definitions schema. For bulk updates, use the JSON_LISTINGS_FEED via the Feeds API instead of individual calls. Authentication is LWA OAuth 2.0 only — AWS IAM/SigV4 is no longer required.
| Fact | Value |
|---|---|
| Platform | Amazon |
| Auth method | LWA OAuth 2.0 — access token in x-amz-access-token header |
| Rate limits | putListingsItem: 5 req/sec, burst 10 | createFeed: 1/min sustained |
| Difficulty | Advanced |
| Time required | 60–90 minutes |
| Last updated | May 2026 |
API Quick Reference
LWA OAuth 2.0 — access token in x-amz-access-token header
putListingsItem: 5 req/sec, burst 10 | createFeed: 1/min sustained
JSON
REST only
API overview
https://sellingpartnerapi-na.amazon.comAuthentication
SP-API uses Login with Amazon (LWA) OAuth 2.0. Access tokens are obtained from https://api.amazon.com/auth/o2/token and passed in the x-amz-access-token header. Tokens expire in 1 hour. AWS IAM/SigV4 signing is no longer required for SP-API as of October 2023 — only the LWA token is needed. LWA client credentials rotate every 180 days.
Key endpoints
/listings/2021-08-01/items/{sellerId}/{sku}Creates or fully replaces a listing for a given seller and SKU. Request body must contain productType and attributes matching the Product Type Definitions schema exactly. Returns a status of ACCEPTED or a list of validation issues.
| Parameter | Type | Required | Description |
|---|---|---|---|
| optional | ||
| optional | ||
| optional | ||
| optional | ||
| optional |
/listings/2021-08-01/items/{sellerId}/{sku}Updates specific attributes of an existing listing without replacing the entire record. Use for price, quantity, or description updates on live listings.
| Parameter | Type | Required | Description |
|---|---|---|---|
| optional | ||
| optional | ||
| optional | ||
| optional |
/listings/2021-08-01/items/{sellerId}/{sku}Retrieves the current attributes and status of a listing. Use to verify a listing was created correctly or to read attributes before a patch update.
| Parameter | Type | Required | Description |
|---|---|---|---|
| optional | ||
| optional | ||
| optional | ||
| optional |
/feeds/2021-06-30/feedsSubmits a bulk feed for processing. Use feedType=JSON_LISTINGS_FEED for listing creation/updates. The response includes a feedId to poll for completion status.
| Parameter | Type | Required | Description |
|---|---|---|---|
| optional | ||
| optional | ||
| optional |
Step-by-step automation
Authenticate with LWA OAuth 2.0
Exchange your LWA refresh token for an access token. Tokens expire in 1 hour. Implement auto-refresh before each API call. No AWS Signature V4 required.
1# Get LWA access token2curl -X POST https://api.amazon.com/auth/o2/token \3 -H "Content-Type: application/x-www-form-urlencoded" \4 -d "grant_type=refresh_token&client_id=$LWA_CLIENT_ID&client_secret=$LWA_CLIENT_SECRET&refresh_token=$LWA_REFRESH_TOKEN"56# Response: {"access_token": "Atza|...", "expires_in": 3600, "token_type": "bearer"}Look Up Product Type Definitions Before Creating a Listing
Amazon's listing model is attribute-based with strict product type schemas. Before creating a listing, query the Product Type Definitions API to get the required attributes for your product type (e.g., HOME_BED_AND_BATH, SHIRT, KITCHEN). Missing or incorrectly named attributes cause INVALID_ATTRIBUTE errors.
1# Search for product type definitions2curl -X GET "https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes?keywords=mug&marketplaceIds=ATVPDKIKX0DER" \3 -H "x-amz-access-token: $LWA_ACCESS_TOKEN"45# Get schema for a specific product type6curl -X GET "https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/KITCHEN?marketplaceIds=ATVPDKIKX0DER" \7 -H "x-amz-access-token: $LWA_ACCESS_TOKEN"Create or Update a Listing with putListingsItem
PUT the listing with all required attributes. The request must include productType and the attributes object with exact field names from the Product Type Definitions schema. Monitor the LISTINGS_ITEM_STATUS_CHANGE notification to confirm approval or see rejection reasons.
1curl -X PUT "https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/$SELLER_ID/MY-SKU-001?marketplaceIds=ATVPDKIKX0DER" \2 -H "x-amz-access-token: $LWA_ACCESS_TOKEN" \3 -H "Content-Type: application/json" \4 -d '{5 "productType": "KITCHEN",6 "attributes": {7 "item_name": [{"value": "Handmade Ceramic Coffee Mug 12oz", "language_tag": "en_US"}],8 "brand": [{"value": "MyBrand"}],9 "bullet_point": [10 {"value": "Handmade ceramic, food-safe glaze", "language_tag": "en_US"},11 {"value": "Dishwasher and microwave safe", "language_tag": "en_US"}12 ],13 "list_price": [{"value": 24.99, "currency": "USD"}],14 "fulfillment_availability": [{"fulfillment_channel_code": "DEFAULT", "quantity": 50}]15 }16 }'Bulk Create Listings with JSON_LISTINGS_FEED
For 100+ listings, use the Feeds API with feedType=JSON_LISTINGS_FEED. This bypasses the 5 req/sec rate limit and handles large catalogs. The flow is: create a feed document, upload the JSON feed, submit the feed job, then poll for completion and download the processing report.
1# Step 1: Create feed document2curl -X POST "https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/documents" \3 -H "x-amz-access-token: $LWA_ACCESS_TOKEN" \4 -H "Content-Type: application/json" \5 -d '{"contentType": "application/json; charset=UTF-8"}'6# Returns: {"feedDocumentId": "doc123", "url": "https://s3.amazonaws.com/..."}'78# Step 2: Upload feed to the presigned S3 URL9curl -X PUT "$PRESIGNED_S3_URL" \10 -H "Content-Type: application/json; charset=UTF-8" \11 --data-binary @listings-feed.json1213# Step 3: Submit feed14curl -X POST "https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds" \15 -H "x-amz-access-token: $LWA_ACCESS_TOKEN" \16 -H "Content-Type: application/json" \17 -d '{"feedType": "JSON_LISTINGS_FEED", "marketplaceIds": ["ATVPDKIKX0DER"], "inputFeedDocumentId": "doc123"}'Complete working code
Complete Amazon listing automation: reads from a product CSV/JSON, creates or updates listings via putListingsItem with rate-limit throttling, and logs results.
Error handling
The attribute name in your request doesn't exactly match the Product Type Definitions schema. For example, using 'name' instead of 'item_name', or 'price' instead of 'list_price'.
Query the Product Type Definitions API for your product type and download the JSON Schema. Check the exact attribute names — they are case-sensitive and underscore-separated. Use the schema's 'required' array to identify mandatory fields.
Your SP-API application doesn't have the required roles authorized, or the refresh token was issued before the necessary permissions were granted.
Check your SP-API application's required roles in Seller Central. For Listings Items, you need the 'Product Listing' role. Re-authorize the seller account after adding new roles — existing refresh tokens don't inherit new permissions.
Exceeded putListingsItem's 5 req/sec limit or the Feeds API's 1/min createFeed limit.
For individual updates: add 210ms minimum delay between requests. For bulk (100+ listings): switch to JSON_LISTINGS_FEED via the Feeds API. The Feeds API has no per-listing rate limit — submit all listings in one feed.
The listing was accepted but has issues preventing it from going live — missing required images, price below Amazon's minimum, or brand approval required.
Use getListingsItem with includedData=issues to see the specific blocking issues. Common causes: no product image, price=0, or brand not in Amazon Brand Registry. Check LISTINGS_ITEM_ISSUES_CHANGE notifications for ongoing issue alerts.
LWA client credentials rotate every 180 days. Using an expired access token returns 401.
Implement auto-refresh: compare current time to token_expiry - 60 before every request. For the 180-day credential rotation, set a calendar reminder and update the client_id/client_secret in your secrets manager before expiry.
Rate limits & throttling
Security checklist
- Store LWA client_id, client_secret, and refresh_token in environment variables or a secrets manager
- Rotate LWA credentials every 180 days before they expire — set a calendar reminder
- Never expose the access token in client-side code or API responses
- Use the minimum required SP-API roles for your application (Product Listing role for listings)
- Log all listing submissions with SKU, submission ID, and timestamp for audit trail
- Do not commit product feeds containing pricing or inventory data to version control
Automation use cases
New Product Launch Automation
When a new product is added to your ERP or PIM system, automatically trigger a listing creation on Amazon via putListingsItem, monitor for LISTINGS_ITEM_STATUS_CHANGE notifications, and alert your team when the listing goes live.
Catalog Migration from Flat Files
Replace legacy flat-file feed uploads (deprecated March 2025) with JSON_LISTINGS_FEED. Convert your existing spreadsheet-based workflow to the new JSON attribute format.
Price and Inventory Sync from ERP
Use patchListingsItem to push price and quantity updates from your ERP system to Amazon without replacing the full listing. Run every hour to keep listings current.
No-code alternatives
Don't want to write code? These platforms can automate the same workflows visually.
Zapier
No native Amazon SP-API integration. Requires HTTP action with custom LWA token headers. Complex for the attribute-based listing schema.
Make (Integromat)
HTTP modules can call SP-API endpoints. More practical than Zapier for the multi-step token refresh + listing creation flow. Still requires mapping product attributes manually.
n8n
HTTP Request nodes with JavaScript Code nodes to handle LWA token refresh and attribute mapping. Best no-code-adjacent option for Amazon SP-API automation.
Best practices
- Query the Product Type Definitions API first — attribute names are product-type-specific and differ between KITCHEN, SHIRT, and HOME_BED_AND_BATH
- Use patchListingsItem for incremental updates (price, quantity) to avoid accidentally overwriting title, description, or images
- For 100+ listings, always use JSON_LISTINGS_FEED — individual putListingsItem calls at scale will hit rate limits and take too long
- Subscribe to LISTINGS_ITEM_STATUS_CHANGE notifications via SQS to detect listing approval or issues asynchronously instead of polling
- Store your SKU-to-submissionId mapping to correlate status change notifications back to your submission
- Test with a single listing in sandbox or a low-risk SKU before running bulk operations
- Rotate LWA client credentials every 180 days — calendar reminder is essential
- Log all INVALID issue details: Amazon's error messages identify the exact attribute name and required format
Ask AI to help
Copy one of these prompts to get a personalized, working implementation.
Help me build a Node.js script to automate Amazon product listing creation using the SP-API Listings Items API. It should: (1) authenticate with LWA OAuth 2.0 (no AWS SigV4 needed — just POST to https://api.amazon.com/auth/o2/token and use the token in x-amz-access-token header, 1-hour expiry), (2) read product data from a JSON file, (3) PUT to /listings/2021-08-01/items/{sellerId}/{sku} with productType and attributes — the attributes must use exact field names from Amazon's Product Type Definitions schema, (4) handle INVALID status responses by logging the specific attribute issues, (5) add 210ms delays between requests to stay under the 5 req/sec limit.
Build me an Amazon listing management dashboard that: (1) authenticates with Amazon SP-API via LWA OAuth 2.0 (access token in x-amz-access-token header), (2) shows a table of all current listings fetched from GET /listings/2021-08-01/items/{sellerId}/{sku} with status (ACTIVE, INACTIVE, INVALID), (3) has a form to create new listings with fields for sku, title, price, quantity, and product type, (4) shows any listing ISSUES in a red warning panel, (5) uses Supabase to store the LWA tokens and a local cache of listing statuses. Include 210ms delays between API calls for rate limiting.
Frequently asked questions
Do I still need AWS IAM credentials and SigV4 signing to use the SP-API?
No. As of October 2023, SP-API authentication is LWA OAuth 2.0 only. You only need the x-amz-access-token header. AWS IAM roles and SigV4 request signing are no longer required. This significantly simplifies the integration compared to older tutorials that describe the IAM setup.
Why does Amazon return INVALID_ATTRIBUTE for my listing even though the field name looks right?
Attribute names in the SP-API are product-type-specific and must exactly match the Product Type Definitions schema. 'name' fails; 'item_name' is correct. 'price' fails; 'list_price' is correct. Download the JSON Schema for your specific productType from the Product Type Definitions API and use it as your reference for every attribute name.
What's the difference between putListingsItem and patchListingsItem?
putListingsItem is a full replacement — you must include all attributes. patchListingsItem applies partial updates using JSON Merge Patch (RFC 7396) — you only send the attributes you want to change. Use PUT for initial creation and PATCH for incremental updates like price and quantity changes to avoid accidentally overwriting your title or images.
Can I still use flat-file CSV uploads instead of the API?
XML/flat-file feeds were deprecated March 31, 2025. For bulk listing management you should now use JSON_LISTINGS_FEED via the Feeds API. It's the API equivalent of flat-file uploads but uses JSON attribute format that matches the Product Type Definitions schema.
How long does it take for a listing to become active after putListingsItem returns ACCEPTED?
ACCEPTED means Amazon received the submission, not that the listing is live. Listings typically go active within 15–60 minutes. For brand-new ASINs with no existing catalog entry, it can take several hours. Subscribe to the LISTINGS_ITEM_STATUS_CHANGE notification via SQS to receive an event when the listing status changes.
Can RapidDev help me migrate my Amazon catalog to the new SP-API format?
Yes. RapidDev can build a migration pipeline that reads your existing flat-file or spreadsheet catalog, maps attributes to the correct Product Type Definitions schema for each product type, and submits them via the SP-API Feeds API. We handle the attribute mapping, error monitoring, and re-submission logic.
What marketplace IDs should I use for different Amazon regions?
North America (US): ATVPDKIKX0DER. Canada: A2EUQ1WTGCTBG2. Mexico: A1AM78C64UM0Y8. UK: A1F83G8C2ARO7P. Germany: A1PA6795UKMFR9. France: A13V1IB3VIYZZH. Japan: A1VC38T7YXB528. Australia: A39IBJ37TRP1C6. Use the corresponding regional base URL for non-NA marketplaces (sellingpartnerapi-eu.amazon.com for Europe, sellingpartnerapi-fe.amazon.com for Far East).
Need this automated?
Our team has built 600+ apps with API automations. We can build this for you.
Book a free consultation