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 is encrypted at rest with envelope encryption (AWS KMS), and access tokens are never written to disk. The SP-API LWA scope we request is the standard merchant scope — no developer- or vendor-only scopes.