Help us improve
Share bugs, ideas, or general feedback.
From lumitec-amazon
Operate a user's Amazon Seller Central business through the Lumitec SP-API MCP — orders, FBA inventory, listings, pricing, reports, financial events, feeds, and notifications. Use this skill whenever the user asks anything about their Amazon seller account: checking orders or sales, sales velocity, looking up ASINs or SKUs, adjusting prices or stock, running reports, investigating suspended listings, analysing margins, pan-EU / multi-marketplace work, inventory coverage, settlement reconciliation, "my products", "my listings", "how many sold", "days of stock", "buy box", or anything in Seller Central. Also applies to casual phrasing like "check Amazon", "my amzn sales", "fba numbers" — if it's about their seller business, this skill applies even when they don't name SP-API explicitly. NOT for Amazon advertising / PPC (that's the amazon-ads skill) and NOT for Amazon-as-a-shopper (Claude handles that directly).
npx claudepluginhub lumitecai/lumitec-cowork-plugin --plugin lumitec-amazonHow this skill is triggered — by the user, by Claude, or both
Slash command
/lumitec-amazon:amazon-seller [orders|inventory|catalog|pricing|listings|reports|fba|finance] [query][orders|inventory|catalog|pricing|listings|reports|fba|finance] [query]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Manages Amazon seller operations through the hosted `amazon-sp-api` MCP at
Guides using Bun as JavaScript runtime, package manager, bundler, and test runner. Covers choosing Bun vs Node, Node migration, and Vercel deployment support.
Share bugs, ideas, or general feedback.
Manages Amazon seller operations through the hosted amazon-sp-api MCP at
https://lumitec-sp-api-mcp.fly.dev/mcp. All data access goes through MCP
tools — never call SP-API directly.
Before any workflow, verify the MCP is connected:
checkCredentials. Possible outcomes:
Missing or invalid X-Lumitec-Key → the user's Lumitec access key
is wrong or missing. Ask them to re-run the setup-amazon skill, or
email a.walters@lumitec.ai if they need a fresh key.Failed to authenticate with Amazon SP-API → their Amazon
credentials (client ID / secret / refresh token) are wrong, expired,
or for the wrong region. Re-run setup-amazon.setup-amazon skill.marketplaceId
explicitly. The MCP has a default marketplace set at install time, but
that's only used when no marketplaceId is passed. EU sellers often
default to Germany — UK queries silently return nothing without an
explicit UK marketplace ID (A1F83G8C2ARO7P).sellerId is configured at install time and auto-filled by the MCP
for listings tools. Only pass it explicitly if operating across
multiple seller accounts (rare — one seller ID per region: NA/EU/FE).How the MCP is wired: the user's Claude client talks to
https://lumitec-sp-api-mcp.fly.dev/mcp over HTTPS. Their Amazon
credentials travel as request headers on every call; the server holds
nothing at rest (only an in-memory LWA token cache keyed by a hash of
client ID + refresh token, which isolates tenants from each other). If
the user hasn't set up the MCP yet, invoke the setup-amazon skill
before continuing.
Never execute a write operation without explicit per-item confirmation from the user. Read operations are fine to run directly; write operations change the user's Amazon account, and a mistake can cost real money or break real customer orders.
Every mutating SP-API tool requires confirmation:
| Tool | What it changes |
|---|---|
patchListingsItem | A live listing's attributes (price, quantity, bullets, etc.) |
putListingsItem | Overwrites an entire listing |
deleteListingsItem | Removes a listing |
createFeed | Submits a bulk feed — can change hundreds of listings or inventory records in one shot |
createReport | Creates an async report (low-stakes but costs an API call) |
cancelReport / cancelReportSchedule | Cancels a running or scheduled report |
createSubscription / deleteSubscription | Changes notification wiring |
createDestination / deleteDestination | Changes where SQS/EventBridge events are delivered — destructive if the user has an existing pipeline |
updateInventory | Adjusts FBA inventory records |
The confirmation rule:
For read-only operations (searchOrders, getCatalogItem,
getInventorySummaries, listFinancialEvents, etc.) — run them directly
without asking; that's the point of the skill.
Mental model: caches first, API as fallback, refresh at session start.
SP-API has strict rate limits and starts charging per call from April 30, 2026. Pull a bulk report once, store it on the user's own disk, and query it locally rather than looping the API per SKU / order.
Why client-side caching (not Lumitec-side): the cache contains order data with buyer PII. Amazon's SP-API Data Protection Policy places strict obligations on anyone storing that data at rest. Keeping the cache on the user's own machine — where they're the registered Amazon developer holding their own data — keeps Lumitec out of the DPP compliance scope. Lumitec never sees the cached rows.
| Work type | Cache file | Report type |
|---|---|---|
| Sales / orders analysis | orders-{region}-{country}.tsv | GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL |
| Product / pricing / listing work | listings-{region}-{country}.tsv | GET_MERCHANT_LISTINGS_ALL_DATA |
| Inventory / stock planning | fba-{region}-{country}.tsv | GET_FBA_MYI_ALL_INVENTORY_DATA |
Staleness: orders 6 h, listings 24 h, inventory 24 h, financial events 7 d.
Full table in references/caching-strategy.md.
| Client | Cache directory | Persistence | Setup |
|---|---|---|---|
| Claude Code (mac/linux/win) | cache/ in the cwd (project-relative) | Persists as long as the project folder exists | No setup — Bash/Write tools run directly on the host FS |
| Cowork | /sessions/<name>/mnt/lumitec-amazon-cache/ inside the VM (mapped to a host directory like ~/lumitec-amazon-cache/) | Persists on the host, survives session deletion | One-time per conversation: ask the user to approve a request_cowork_directory for a folder like ~/lumitec-amazon-cache/. Then writes go through to their Mac disk. |
| Claude Desktop | Not supported for bulk caching | — | Use targeted API batches instead (getInventorySummaries with sellerSkus, getPricing batch of 20). Recommend the user switch to Claude Code or Cowork for bulk work. |
Cowork gotcha — bug #30364:
multiple separate writes to a single mount can silently drop all but the
first. Workaround: write each cache to a separately named file in one
write operation (don't do three sequential curl -o into the same
mount — bundle them, or use three distinct filenames with distinct
downloads spaced apart).
grep it directly. Stale or missing → refresh.createReport with the report type + marketplaceIds.getReport until processingStatus: DONE.getReportDocument → returns a pre-signed S3 URL (expires in 5 min —
download immediately).Bash curl -o <cache-path> "$URL" (Code) or
mcp__workspace__bash curl -o <mount-path>/... "$URL" (Cowork).| Question | Action | Never do |
|---|---|---|
| "How many units of [SKU] sold?" | Grep orders cache, sum quantity column | Loop getOrderItems (~0.5 req/s → 10 min for 300 orders) |
| "Find all [keyword] products" | Grep listings cache | searchListingsItems has no keyword filter |
| "Current price of [SKU]?" | Grep listings cache, read price column | getListingsItem per SKU |
| "Did [SKU] sell in [country]?" | Grep orders cache, filter ship-country | searchOrders per country |
| "Pan-EU sales breakdown" | Grep orders cache (includes cross-border translated names) | Multiple API calls per marketplace |
getInventorySummaries after receiving confirmation.patchListingsItem, putListingsItem, etc. always hit API.getListingsItem after patching.getInventorySummaries({sellerSkus:[...]}) up to 50
SKUs; getPricing / getCompetitivePricing / getItemOffersBatch up
to 20 ASINs. Never loop getOrderItems — use a report and recommend
the user switch to Claude Code or Cowork for bulk work.| User says... | Workflow | Read first |
|---|---|---|
| "check my orders", "recent orders", "order status" | Order Management | — |
| "how many sold", "sales this month", "sales velocity" | Order Management (grep cache) | — |
| "FBA inventory", "stock levels", "inbound shipments" | FBA & Inventory | — |
| "days of stock", "inventory coverage" | Inventory Coverage (compound) | — |
| "look up ASIN", "search products", "catalog" | Product Research | — |
| "find my products", "search my listings" | Grep listings cache (no API keyword search) | — |
| "pricing", "competitor prices", "buy box" | Pricing Intelligence | references/rate-limits.md |
| "create listing", "update listing", "patch listing" | Listing Management | references/listings-pitfalls.md |
| "sales report", "generate report", "listings report" | Reports & Analytics | references/report-types.md |
| "financial events", "settlements" | Finance | — |
| "notifications", "subscriptions", "destinations" | Notifications | — |
If ambiguous, default to Order Management for sales queries or Product Research for ASIN/product queries.
Read first (for bulk work): references/caching-strategy.md,
references/rate-limits.md.
Choose the right approach by volume:
GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL (max 30-day window per request, see references/caching-strategy.md)API path (small volume):
searchOrders with date/status filters. Always pass marketplaceIds. Rate: ~1 req/min — don't loop aggressively.getOrder with orderIdgetOrderItems with orderIdReport path (bulk):
createReport with type GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL, date range, marketplaceIdsgetReport until DONEgetReportDocument → download TSV (URL expires in 5 min!)Choose the right inventory tool:
getInventorySummaries — use for targeted SKU lookups. Supports sellerSkus filter param to fetch specific SKUs in one call. Returns both FBA and MFN inventory.getFbaInventorySummaries — use for broad FBA overview. Does NOT support SKU filtering — returns all FBA inventory paginated at 50 results. You may need multiple pages to find specific SKUs.getInventorySummaries with sellerSkus. Only use getFbaInventorySummaries for full FBA catalogue scans.getInboundEligibility to check FBA program eligibilitylistInboundPlans for inbound shipment tracking (v2024-03-20)getInboundPlan for details on a specific inbound planCombines cached orders + live inventory in one pass:
getInventorySummaries API call with sellerSkus filter → current FBA stock for those exact SKUscurrentStock / dailyVelocity = days of stock remainingThis uses 1 API call total instead of hundreds.
searchCatalogItems with keywordsgetCatalogItem with ASIN for full detailsgetCompetitivePricing for price contextRead first: references/rate-limits.md (batch rules)
getPricing — batch up to 20 ASINs/SKUs per call (always batch, never loop)getCompetitivePricing — batch up to 20 for competitor datagetListingOffers — lowest offers for a single SKURead first: references/listings-pitfalls.md (critical traps)
Confirmation required for every write — see the top-of-skill
"Confirmation Policy" section. Listing writes in particular (patchListingsItem,
putListingsItem, deleteListingsItem) are high-impact: wrong price,
wrong quantity, wrong SKU targeted — all show up on Seller Central
immediately.
grep -i "product name" cache/{region}-{country}-listings.tsvgrep "B0XXXXXXXX" cache/{region}-{country}-listings.tsv — also reveals if ASIN has multiple SKUs (FBA + MFN)getListingsItem to inspect full current state (sellerId auto-fills from install-time config).patchListingsItem with JSON Patch operations.
putListingsItem overwrites ALL data — only use for full create/replace.deleteListingsItem to remove.When a user reports suspended or inactive listings in EU marketplaces:
getMarketplaceParticipations — check which marketplaces show hasSuspendedListings: truegetListingsItem with that marketplace's ID to see the listing status and issuesRead first: references/report-types.md + references/caching-strategy.md
Reports are async:
createReport with reportType + marketplaceIdsgetReport until status = DONEgetReportDocument to get download URL (expires in 5 minutes!)listFinancialEventGroups for settlement periods (requires financialEventGroupStartedAfter date)listFinancialEvents for transaction detailslistFinancialEventsByOrderId for per-order fees/charges/refunds (profitability analysis)getFinancialEventGroup for events in a specific groupRaw financial events are verbose — always aggregate before presenting:
listFinancialEventsByOrderId for each order (or listFinancialEvents for a date range)
ShipmentEventList.ShipmentEventList[].ShipmentItemList[].ItemFeeList[]:
Principal) — the sale price you receiveCommission) — Amazon's referral feeFBAPerUnitFulfillmentFee, FBAPerOrderFulfillmentFee) — pick/pack/shipDigitalServicesFee) — UK/EU digital services taxNote: Finance API v0 — sunset August 28, 2026.
getDestinations to list existing SQS/EventBridge destinationscreateDestination to set up a new onecreateSubscription for a notification type (ORDER_CHANGE, REPORT_PROCESSING_FINISHED, etc.)getSubscription to check status| Code | Meaning | Action |
|---|---|---|
| 400 | Bad request — surface errors[].message | Fix params |
| 401 | Token expired | Retry — getAccessToken auto-refreshes |
| 403 | Missing role/scope on LWA app | Check app registration (not credentials) |
| 404 | Invalid ASIN/SKU/orderId | Verify identifier, try search |
| 429 | Rate limit — read x-amzn-RateLimit-Limit | Backoff with jitter |
| 500/503 | Amazon transient error | Retry with backoff |
Full guide: references/error-codes.md
Read: references/api-gaps.md before suggesting workarounds.
No: Buy Box analytics, A+ Content, PPC/Advertising, reviews, Brand Analytics, keyword ranking. Use: agent-browser for Seller Central UI tasks, Amazon Ads API for PPC.