Seller account connection (deep-dive)
The quick onboarding version of this is at Connect your Amazon Seller account. This page goes deeper for users who need to know exactly what Hilal reads, how the token is managed, and why a connection sometimes drifts.
In this guide:
- What the SP-API connection grants
- Token lifecycle
- What Hilal reads vs what it doesn’t
- Multi-marketplace coverage
- Re-authorization
What the SP-API connection grants
The SP-API connection is a single OAuth grant from your Amazon Seller account to Hilal. The scopes Hilal requests are read-only across:
- Inventory — listings, stock levels, attributes.
- Orders — order details, status, fulfillment, line items.
- Reports — settlement reports (fees, payments), inventory reports, returns reports.
- Catalog — product details for ASINs your account sells.
- Reimbursements — Amazon’s record of reimbursements.
- Sales — sales metrics, gross/net sales.
Hilal does not request write scopes for the Seller account itself (no listing edits, no inventory changes pushed back to Amazon). The Ads API is a separate connection with its own (read + write) scopes.
Token lifecycle
The grant produces:
- A refresh token stored encrypted in Hilal’s database.
- An access token generated on-demand from the refresh token; valid 1 hour.
Hilal automatically refreshes access tokens before they expire. The refresh token itself doesn’t expire — but Amazon may invalidate it if:
- You revoke the grant in Seller Central → Apps & Services → Manage Your Apps.
- You change your Amazon password (sometimes; depends on Amazon’s risk model).
- Hilal hasn’t used the grant in over a year (rare).
When the refresh token is invalid, every Hilal request fails with Unauthorized. The Amazon → Connection page surfaces a Reconnect button.
What Hilal reads vs what it doesn’t
| Hilal reads | Hilal doesn’t read |
|---|---|
| Listings, ASINs, attributes | Your bank account / payout details |
| Order line items, ship-to addresses | Buyer-personally-identifiable info beyond what Amazon exposes |
| Settlement reports (fees, payouts) | Other sellers’ data |
| Inventory levels and movements | Internal Amazon notes / case logs |
| Returns and refund records | Buyer messages (those go through the separate Buyer-Seller Messaging API) |
Multi-marketplace coverage
A single SP-API grant covers your whole Seller account, including every marketplace it’s authorized in. Connecting once is enough — you don’t need to redo the grant per region.
That said, only marketplaces you’ve ticked under Settings → Marketplaces are actively scoped in the UI. SP-API technically returns data for all authorized marketplaces; Hilal filters to what you’ve selected.
Re-authorization
Reasons to re-authorize:
- The connection expired or was revoked.
- You’ve added a new marketplace in Seller Central and want Hilal to see it.
- You changed Amazon Seller account ownership (the grant is bound to the old owner’s identity).
To re-authorize, go to Amazon → Connection → Reconnect. Hilal walks through the SP-API consent flow exactly as the first time.
Security
- Refresh tokens are encrypted at rest with a key never accessible to Hilal application code (KMS-managed).
- Every API call from Hilal uses HTTPS and an SP-API request signature.
- Hilal logs API calls for diagnostics; logs never contain access tokens or buyer PII.