SP-API Integration
How this console reaches Amazon: one self-authorised Selling Partner API application, three marketplaces, 10 roles (7 granted), 18 scheduled report pulls and 10 push subscriptions. Connection state as of Aug 28, 2026. Credentials shown masked, and none of them are real.
Connected accounts
4
1 Seller Central, 3 vendor groups
Marketplaces
3
NA region, one endpoint
Granted roles
7 of 10
3 PII roles left ungranted
Scheduled pulls
18
Reports, Vendor API, Data Kiosk
Pulls healthy
16 of 18
1 failed, 1 late
Subscriptions active
8 of 10
1 in error
Events ingested 24h
76K
EventBridge + SQS
Throttled calls 24h
167
4 operations affected
2 feeds degraded, with downstream screens already drifting. GET_VENDOR_TRAFFIC_REPORT (Vendor traffic (glance views)) last succeeded Aug 27, 10:50 AM, so glance views on Sales & Traffic go stale for every vendor-channel brand: conversion and unit-session rates there are computed on a frozen denominator and will read high until the pull recovers. GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT is past its window (Weekly Tue 10:00); search-term share on Brand Breakouts is one cycle behind. BRANDED_ITEM_CONTENT_CHANGE is in ERROR, so unauthorised copy and image edits on branded detail pages stop being detected: a third-party contribution can overwrite a title or bullet set and nothing raises a catalog alert until the next full listings pull. Both are re-grant or re-subscribe operations, not code changes, and neither is self-healing.
ConnectionDeveloper Central application profile · Login with Amazon
- Application type
- SP-API private application, self-authorised
- LWA client id
- amzn1.application-oa2-client.••••4c7e
- Authorisation model
- Login with Amazon refresh token per selling partner, rotated quarterly
- Region
- North America (us-east-1)
- Endpoint
- https://sellingpartnerapi-na.amazon.com
- Request signing
- LWA access token only (AWS SigV4 signing was retired for SP-API)
- Restricted Data Token
- Not requested: no PII roles are granted, so no RDT is required
- Token cache
- Access token valid 1 hour, refreshed at 55 minutes
- Seller id
- A2••••••••9QK7
- Vendor group codes
- RVLYS, RVOUT, RVRGT
- Brands mapped
- 14 across 3 segments
- ASINs in scope
- 1,448
MarketplacesgetMarketplaceParticipations
| Country | Marketplace ID | Channels | ASINs | Status |
|---|---|---|---|---|
| United States | ATVPDKIKX0DER | Vendor Central + Seller Central | 1,448 | ACTIVE |
| Canada | A2EUQ1WTGCTBG2 | Vendor Central + Seller Central | 898 | ACTIVE |
| Mexico | A1AM78C64UM0Y8 | Seller Central only | 405 | LIMITED |
Roles and scopesDeveloper Central role grants · 7 of 10 granted
| Role | Granted | Data class | Used by |
|---|---|---|---|
| Inventory and Order Tracking | Granted | No PII | Inventory Health, Replenishment, Alerts |
| Amazon Fulfillment | Granted | No PII | Fulfillment Centers, Shipments, Reimbursements |
| Product Listing | Granted | No PII | Catalog Health |
| Pricing | Granted | No PII | Pricing & Buy Box |
| Finance and Accounting | Granted | No PII | Fees & Profitability, Reimbursements |
| Selling Partner Insights | Granted | No PII | Sales & Traffic, Overview |
| Brand Analytics | Granted | No PII | Sales & Traffic |
| Buyer Communication | Not granted | PII | - |
| Direct-to-Consumer Shipping | Not granted | PII | - |
| Tax Invoicing | Not granted | PII | - |
The 3 ungranted roles are ungranted on purpose. Requesting a PII scope (Buyer Communication, Direct-to-Consumer Shipping, Tax Invoicing) puts the application into Amazon's Data Protection Policy audit track: annual security questionnaire, encryption and retention attestations, and penetration-test evidence. No screen in this console needs a buyer name, address or email, so the application stays outside that scope and every response it handles is aggregate or ASIN-level.
Ingestion pipeline18 feeds defined in code · 13 wired · ingestion disabled in this environment
| Feed | Source | API | Account | Role required | Cadence | Window | Tier | Restated | What breaks when stale |
|---|---|---|---|---|---|---|---|---|---|
FBA inventory position fba-inventory | GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA | REPORT | SELLER | Amazon Fulfilment | 6h | full | CORE | upsert | Stockout and restock alerts go blind. Days-of-supply figures freeze at the last good pull. |
FBA inventory by fulfilment centre fba-inventory-by-node | GET_AFN_INVENTORY_DATA_BY_COUNTRY | REPORT | SELLER | Amazon Fulfilment | daily | full | CORE | upsert | Node-level capacity and overfill projection stop updating, which is the feed the never-overfill-a-warehouse rule runs on. |
Inventory ledger, summary view ledger-summary | GET_LEDGER_SUMMARY_VIEW_DATA | REPORT | SELLER | Amazon Fulfilment | daily | 45d | RECOVERY | rewrites window | Reimbursement detection stops. This is the evidence feed: without it a claim is an assertion Amazon will deny. |
Sales and traffic by ASIN sales-traffic | analytics_salesAndTraffic_2024_04_24 | DATA KIOSK | SELLER | Brand Analytics | daily | 30d | CORE | rewrites window | Every revenue figure and the whole executive summary go stale. |
Vendor sales and traffic vendor-sales | analytics_vendorAnalytics_2024_09_30 | DATA KIOSK | VENDOR | Selling Partner Insights | daily | 30d | CORE | rewrites window | Vendor-side revenue, shipped COGS and replenishment out-of-stock all freeze. |
FBA customer returns customer-returns | GET_FBA_FULFILLMENT_CUSTOMER_RETURNS_DATA | REPORT | SELLER | Amazon Fulfilment | daily | 60d | RECOVERY | rewrites window | Refunds-without-a-returned-unit stop being detected, and each of those is a claim with a 60 day clock. |
FBA reimbursements reimbursements | GET_FBA_REIMBURSEMENTS_DATA | REPORT | SELLER | Amazon Fulfilment | daily | 180d | RECOVERY | rewrites window | Recovered dollars and the capture-rate metric stop moving, and the filing queue re-surfaces claims Amazon has already paid. |
Removal shipment detail removal-shipments | GET_FBA_REMOVAL_SHIPMENT_DETAIL_DATA | REPORT | SELLER | Amazon Fulfilment | weekly | 180d | RECOVERY | rewrites window | Removals that Amazon lost in transit stop being detected. These are reimbursable and routinely missed. |
Financial events and settlements finances | finances.listFinancialEvents | SP API | SELLER | Finance and Accounting | daily | 60d | RECOVERY | upsert | The cash bridge stops closing, so nobody can tie ordered revenue to money in the bank. |
Estimated FBA fees per unit estimated-fees | GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA | REPORT | SELLER | Amazon Fulfilment | weekly | full | COMMERCIAL | upsert | Size-tier errors stop being detected. Fee-correction claims have a 90 day window and are the most reliably paid category there is. |
Monthly storage fees storage-fees | GET_FBA_STORAGE_FEE_CHARGES_DATA | REPORT | SELLER | Amazon Fulfilment | monthly | full | COMMERCIAL | upsert | Aged-inventory surcharge forecasting stops, and the surcharge compounds monthly. |
Buy box and competitive pricing competitive-pricing | pricing.getItemOffersBatch | SP API | SELLER | Pricing | 6h | full | COMMERCIAL | upsert | Buy box share and MAP violation detection fall back to the notification stream alone, so a silent loss goes unnoticed. |
Listing quality and suppression listings-issues | GET_MERCHANT_LISTINGS_ALL_DATA | REPORT | SELLER | Product Listing | daily | full | COMMERCIAL | upsert | Suppressed listings stop being detected. A suppressed ASIN has no offer at all, so this is revenue already being lost. |
Advertising campaigns and budgets ads-campaigns | ads.listCampaigns | ADS API | SELLER | Ads API (separate application) | daily | full | ADVERTISING | upsert | Out-of-budget campaigns stop being flagged. |
Advertising performance by campaign and ASIN ads-performance | ads.reporting.v3 | ADS API | SELLER | Ads API (separate application) | daily | 60d | ADVERTISING | rewrites window | The spend-on-unbuyable-inventory join goes dark, which is usually the largest single avoidable number in the account. |
Vendor purchase orders vendor-purchase-orders | vendorOrders.getPurchaseOrders | VENDOR API | VENDOR | Vendor Direct Fulfilment / Vendor Orders | hourly | 30d | COMPLIANCE | upsert | The 24 hour acknowledgement clock stops being tracked. A missed acknowledgement earns a chargeback and drops the PO out of the fill-rate numerator: two penalties for one silence. |
Vendor chargebacks vendor-chargebacks | GET_VENDOR_CHARGEBACK_REPORT | REPORT | VENDOR | Vendor Payments | daily | 120d | COMPLIANCE | rewrites window | The dispute deadline clock stops. Amazon does not reopen a chargeback window. |
Vendor demand forecast vendor-forecast | analytics_vendorAnalytics_2024_09_30 vendorForecasting | DATA KIOSK | VENDOR | Selling Partner Insights | weekly | full | COMPLIANCE | rewrites window | Forecast-versus-plan comparison stops updating, which is the input to the buy plan. |
Three properties of this pipeline are worth naming, because they are the difference between a script and something that can be left running. Restated windows are rewritten, not upserted: Amazon moves sales figures for up to 72 hours and can reopen a settlement, so the 9 feeds marked above delete their window before writing it, which is the only way a total keeps matching Amazon's own console. Auth failures are separated from throttling: a 403 from a lapsed role grant and a 429 from rate limiting look alike in a log and need opposite responses, so the client classifies them and a feed waiting on a human is held back rather than retried every fifteen minutes all weekend. Nothing here writes to Amazon. There is no code path in the ingestion layer that POSTs to a selling partner resource. Acknowledging a PO and filing a claim are separate operations, each behind an explicit human approval.
Scheduled data pullsReports API createReport / Vendor Retail Analytics / Data Kiosk
| Report type | What it feeds | API | Cadence | Last run | Next run | Rows | Status |
|---|---|---|---|---|---|---|---|
| GET_VENDOR_TRAFFIC_REPORT | Vendor traffic (glance views) | VENDOR API | Daily 10:30 UTC | Aug 27, 10:50 AM | Aug 28, 10:04 AM | 2,216 | FAILED |
| GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT | Brand analytics: search terms | SP API | Weekly Tue 10:00 | Aug 26, 10:36 AM | Sep 2, 10:56 AM | 100,000 | LATE |
| GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA | FBA inventory: unsuppressed | SP API | Every 4 hours | Aug 27, 12:14 PM | Aug 27, 4:32 PM | 4,187 | HEALTHY |
| GET_FBA_INVENTORY_PLANNING_DATA | Inventory planning (age, DOS, IPI) | SP API | Daily 06:00 UTC | Aug 27, 6:30 AM | Aug 28, 6:40 AM | 3,962 | HEALTHY |
| GET_RESTOCK_INVENTORY_RECOMMENDATIONS_REPORT | Restock recommendations | SP API | Daily 07:00 UTC | Aug 27, 7:03 AM | Aug 28, 7:22 AM | 2,411 | HEALTHY |
| GET_AFN_INVENTORY_DATA_BY_COUNTRY | AFN inventory by country | SP API | Daily 06:30 UTC | Aug 27, 6:04 AM | Aug 28, 6:15 AM | 5,104 | HEALTHY |
| GET_STRANDED_INVENTORY_UI_DATA | Stranded inventory | SP API | Daily 15:00 UTC | Aug 27, 3:14 PM | Aug 28, 3:42 PM | 118 | HEALTHY |
| GET_LEDGER_DETAIL_VIEW_DATA | Inventory ledger: detail view | SP API | Daily 05:00 UTC | Aug 27, 5:17 AM | Aug 28, 5:39 AM | 26,840 | HEALTHY |
| GET_FBA_FULFILLMENT_CUSTOMER_RETURNS_DATA | FBA customer returns | SP API | Daily 08:00 UTC | Aug 27, 8:43 AM | Aug 28, 8:28 AM | 942 | HEALTHY |
| GET_FBA_REIMBURSEMENTS_DATA | FBA reimbursements | SP API | Daily 08:30 UTC | Aug 27, 8:00 AM | Aug 28, 8:26 AM | 407 | HEALTHY |
| GET_FBA_FULFILLMENT_LONGTERM_STORAGE_FEE_CHARGES_DATA | Aged inventory surcharge | SP API | Weekly Mon 09:00 | Aug 25, 9:04 AM | Sep 1, 9:55 AM | 1,633 | HEALTHY |
| GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE | Settlement: flat file v2 | SP API | On Amazon close | Aug 23, 3:32 AM | Sep 6, 3:05 AM | 88,214 | HEALTHY |
| GET_SALES_AND_TRAFFIC_REPORT | Sales & traffic by ASIN | SP API | Daily 09:00 UTC | Aug 27, 9:53 AM | Aug 28, 9:55 AM | 1,348 | HEALTHY |
| GET_VENDOR_SALES_REPORT | Vendor sales (Retail Analytics) | VENDOR API | Daily 10:00 UTC | Aug 27, 10:08 AM | Aug 28, 10:11 AM | 2,216 | HEALTHY |
| GET_VENDOR_INVENTORY_REPORT | Vendor inventory (sourceable, on-hand) | VENDOR API | Daily 10:15 UTC | Aug 27, 10:07 AM | Aug 28, 10:38 AM | 2,216 | HEALTHY |
| GET_VENDOR_FORECASTING_REPORT | Vendor demand forecast | VENDOR API | Weekly Mon 11:00 | Aug 25, 11:10 AM | Sep 1, 11:41 AM | 1,904 | HEALTHY |
| GET_VENDOR_REAL_TIME_INVENTORY_REPORT | Vendor real-time inventory | VENDOR API | Hourly | Aug 27, 3:45 PM | Aug 27, 4:42 PM | 2,216 | HEALTHY |
| salesAndTrafficByAsin | Data Kiosk: sales & traffic GraphQL | DATA KIOSK | Daily 09:30 UTC | Aug 27, 9:15 AM | Aug 28, 9:24 AM | 1,348 | HEALTHY |
Push notificationsNotifications API createSubscription · destination per type
| Notification type | Destination | Status | Events 24h | Purpose |
|---|---|---|---|---|
| BRANDED_ITEM_CONTENT_CHANGE | EventBridge | ERROR | - | Unauthorised copy edits: SQS policy needs re-grant |
| FEE_PROMOTION | EventBridge | PENDING | - | Fee change early warning |
| ANY_OFFER_CHANGED | EventBridge | ACTIVE | 41,822 | Buy box and competitive price monitoring |
| LISTINGS_ITEM_STATUS_CHANGE | EventBridge | ACTIVE | 316 | Suppression detection inside 2 minutes |
| LISTINGS_ITEM_ISSUES_CHANGE | EventBridge | ACTIVE | 204 | Catalog health queue |
| FBA_INVENTORY_AVAILABILITY_CHANGES | SQS | ACTIVE | 12,904 | Live days-of-supply recompute |
| FBA_OUTBOUND_SHIPMENT_STATUS | SQS | ACTIVE | 2,211 | Fulfilment exception tracking |
| ORDER_CHANGE | EventBridge | ACTIVE | 18,740 | Order-level velocity signal |
| REPORT_PROCESSING_FINISHED | SQS | ACTIVE | 96 | Report ingestion pipeline trigger |
| PRODUCT_TYPE_DEFINITION_CHANGE | EventBridge | ACTIVE | 7 | Attribute schema drift |
Why two latencies exist in this app. Notifications land on an EventBridge bus or an SQS queue, a small consumer normalises the payload and writes it to Supabase, and the alert rules evaluate on write rather than on a poll. That is why buy-box loss and suppression alerts appear within minutes of the event, while anything sourced from a report (fees, settlement, aged inventory, vendor traffic) can only move on the report cadence shown above. When a number on another page looks behind, the row that explains it is in one of these two tables.
Rate limits and throttlingx-amzn-RateLimit-Limit headers, trailing 24h
| Operation | Rate / sec | Burst | Usage of quota | Throttles 24h |
|---|---|---|---|---|
| getPricing (competitive) | 0.5000 | 1 | 92% | 118 |
| getInventorySummaries | 2.0 | 2 | 78% | 41 |
| searchCatalogItems | 2.0 | 2 | 61% | 6 |
| getReportDocument | 0.0167 | 15 | 51% | - |
| createReport | 0.0167 | 15 | 44% | 2 |
| getCatalogItem | 5.0 | 5 | 34% | - |
| getPurchaseOrders (Vendor) | 10.0 | 10 | 22% | - |
| submitShipmentConfirmations | 10.0 | 10 | 14% | - |
| submitAcknowledgement (Vendor) | 10.0 | 10 | 8% | - |
| createFulfillmentOrder | 2.0 | 30 | 3% | - |
The client holds a per-operation token bucket and retries a 429 with jittered exponential backoff, so a throttle costs latency rather than a dropped record. The binding constraint is getPricing competitive pricing at 0.5 requests per second: at 1,448 ASINs a full polled sweep of buy-box state takes over an hour, which is why it currently runs at 92% of quota with 118 throttles in the last 24 hours. Buy-box and offer changes are therefore taken from the ANY_OFFER_CHANGED notification, which carries the same signal push-side at no quota cost, and getPricing is reserved for on-demand checks when an operator opens a single ASIN.
Data flowAuthorise, pull, normalise, evaluate, render
- 1Authorise. The selling partner authorises the application in Seller Central or Vendor Central once, the app stores the returned refresh token per partner, and every call exchanges that token for a one-hour LWA access token.
- 2Request. A cron worker calls createReport for each schedule above and createSubscription once per notification type, so the same domain is covered by a slow authoritative feed and a fast event feed.
- 3Collect. The worker polls getReport until the processing status is DONE, then getReportDocument returns a pre-signed URL to a gzipped tab-delimited (or JSON, for Data Kiosk) document it streams and parses.
- 4Normalise. Rows are mapped onto the app's camelCase model, keyed on ASIN, FC code, PO number or claim id, and upserted into the Supabase tables listed on Data Admin.
- 5Evaluate. Alert rules run on write for event-sourced tables and on cron for report-sourced tables, comparing each record against its threshold and writing an alert plus an email or Slack notification when it crosses.
- 6Render. Every page in this app is an async server component that reads through one accessor, so nothing in the UI knows or cares whether the row came from Amazon an hour ago or from the demo generator.