Amazon SP-API integration

MarginLock reads from your Amazon Seller Central account through the Selling Partner API (SP-API). It reads your data and computes on it — it does not create, change, or cancel anything in your seller account. 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 settlement, fee, margin, and reimbursement pillars:

• Orders — the Orders API (getOrders, getOrderItems), for fulfilment and margin breakdown per order.
• Finances — financial events and financial event groups, the basis of settlement reconciliation.
• Reports — settlement, customer returns, storage fees, aged inventory, inventory planning (IPI), stranded inventory, and merchant listings reports. These are the primary source of truth for Settlement, FeeAdjustment, and Reimbursement rows, and for the inventory-health pages.
• Catalog Items — for ASIN, dimensions, and category lookups.
• Listings — listing issues, for the listing-health page.
• Product Fees — a per-ASIN FBA fee estimate, so we can compare Amazon's own figure against what you were actually charged.
• Fulfilment Inbound — we list the inbound plans that already exist in your account and keep our own copy of those records current. We read them; we do not create or change them.

What we don't touch

Nothing MarginLock calls changes the state of your seller account. Specifically, we do not:

• Create, edit, or cancel listings.
• Adjust prices.
• Create, submit, edit, or cancel inbound shipments or inbound plans.
• Create or submit removal orders, or move or dispose of inventory.
• Open reimbursement cases. (Reimbursement filing stays a human-in-the-loop step in your seller account.)

Two of the calls above are HTTP POSTs, because that is how Amazon defines them: POST /reports/2021-06-30/reports asks Amazon to generate a report, and POST /products/fees/v0/items/{asin}/feesEstimate asks for a fee estimate. Both are read paths — they are how you obtain that data — and neither writes anything to your account.

If we ever add a surface that does change your account, we will disclose it and it will require your authorization first — 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

   Every six hours

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

   Daily

   Financial event groups sync at 08:00 UTC, customer returns at 06:00 UTC, and the inventory planning (IPI) report and the inbound-plan sweep each run on their own 24-hour timer.
4. 4

   Per settlement

   Once Amazon closes a financial event group, the settlement report is requested on the next daily financial sync; the fee and revenue totals are computed as soon as Amazon finishes generating it.
5. 5

   Monthly

   Storage fees and aged inventory sync on the 16th of each month, after Amazon posts the previous month's storage-fee report.
6. 6

   On request

   Stranded inventory and listing health are not on a schedule — you trigger the sync, and we ingest the data when Amazon finishes processing the report.

Security and permissions

Your refresh token and access tokens are encrypted with AES-256-GCM authenticated encryption before they are written to the database; 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.