Amazon SP-API integration

MarginLock reads from your Amazon Seller Central account through the Selling Partner API (SP-API). The connection is read-only on the surfaces that matter for our product, and the OAuth flow is the standard SP-API hybrid flow — you authorize MarginLock as a developer in Seller Central, and we exchange the refresh token for short-lived access tokens behind the scenes.

What we read

We pull data from a focused set of SP-API endpoints, just enough to power the warehouse, settlement, fee, and reimbursement pillars:

• Orders — the Orders API, for fulfilment and margin breakdown per order.
• FBA Inventory — getInventorySummaries and the related calls that drive the warehouse-inventory page and aging bands.
• Reports — settlement, removal, returns, and reimbursement reports. These are the primary source of truth for Settlement, FeeAdjustment, and Reimbursement rows.
• Catalog Items — for ASIN, dimensions, and category lookups.
• Shipments — the Inbound Shipments API, so we can read your FBA shipment plans.

What we don't touch

We never call any write endpoint on your account. Specifically, we do not:

• Create, edit, or cancel listings.
• Adjust prices.
• Submit, edit, or cancel shipments. (We help you build them; you submit them.)
• Open reimbursement cases. (Reimbursement filing stays a human-in-the-loop step in your seller account.)

If we ever add a write surface, it ships behind a per-merchant opt-in toggle with a clear scope description, never as part of a rolling feature release.

How often we sync

1. 1

   On connect

   A one-time backfill pulls the last 90 days of orders, settlements, and reimbursements so the dashboards are immediately useful.
2. 2

   Hourly

   Orders, inventory, and shipments refresh on a rate-limit-aware schedule — see our blog post on SP-API rate limits for the engineering detail.
3. 3

   Per settlement

   When Amazon closes a settlement, the report pulls within minutes of becoming available, and the fee engine runs immediately afterward.

Security and permissions

Your refresh token and access tokens are encrypted at rest with AES-256-GCM authenticated encryption; the encryption keys are held in AWS Secrets Manager, separate from the database. The SP-API LWA scope we request is the standard merchant scope — no developer- or vendor-only scopes.