eBay API

Setting up OAuth tokens for eBay sellers in 2026

May 31, 2026 · 8 min read

Key takeaways

eBay uses standard OAuth 2.0 with three credentials people loosely call the token: the one-time authorization code, the short-lived access token, and the long-lived refresh token.
The access token expires in about two hours, so anything long-running must mint a fresh one from the refresh token rather than depend on a raw access token.
The finances scope is separate from the order scope, and without it you can only read gross order prices instead of true net earnings.
Validate the full flow in sandbox first, and handle a revoked refresh token with a clean re-auth path instead of a crash.
Fetch Order Tracking manages the whole OAuth lifecycle per store, refreshing tokens before each batch so a sync never dies mid-run.

OAuth is the gate between you and every useful thing eBay's API can do — and it is also where most sellers get stuck, get logged out mid-sync, or accidentally request the wrong permissions and wonder why their earnings come back empty.

This is the no-nonsense version. The scopes you actually need, the refresh-token trap that catches almost everyone, and how to set things up so your sync never silently dies at 2am. No theory you will not use.

The three tokens you will deal with

eBay's modern auth is standard OAuth 2.0, but three different credentials get casually called "the token", and conflating them is where confusion starts:

Authorization code — a one-time code returned to your redirect URL after the seller grants consent. Short-lived; you exchange it immediately.
Access token — the working credential you send on every API call. It expires in roughly two hours.
Refresh token — the long-lived credential you use to mint new access tokens without making the seller log in again. This is the one that matters for unattended syncing.

The scopes you actually need

Scopes are the single most common setup mistake. eBay does not give you everything by default — you request specific scopes, and if you forget one, the relevant calls just fail or return nothing. For an eBay × AliExpress tracking and profit workflow, the two that matter most are:

The fulfilment / order scope — to read orders, line items, and shipping info, and to upload tracking back to eBay.
The finances scope — a separate scope required to read the Finances API. Without it you cannot pull true net earnings, only gross order prices.

That second one trips up everyone who wants accurate profit. If you authorise only the order scope, you are stuck with the Order API's gross figures — which, as we explain in why eBay's Order API gives you the wrong earnings number, are not your real earnings at all.

If your profit column looks empty or wrong, check your scopes before you check your code. Nine times out of ten the finances scope was never granted.

The refresh-token trap

Here is the failure that gets people: they build everything around the access token, it works beautifully for two hours, and then the sync dies. The fix is to never depend on a raw access token for anything long-running. Instead:

Store the refresh token securely the moment you receive it.
Mint a fresh access token from it right before each batch, or whenever the current one is near expiry.
Handle the case where the refresh token itself is revoked — if the seller changes their password or pulls app consent, you need a clean re-auth path, not a stack trace.

Refresh tokens are long-lived but not eternal, and they can be invalidated by actions on the seller's side. Build for that and you will never get logged out mid-sync.

Sandbox first, production second

eBay gives you separate sandbox and production environments, each with their own credentials and redirect URLs. Validate the whole flow — consent, code exchange, refresh, a real API call — in sandbox before you touch live data. It is the same discipline we recommend for the supplier side in how to test your AliExpress sandbox credentials before going live: prove the auth dance works where mistakes are free.

Multi-store reality

If you run eBay UK, US, and AU stores, you are not managing one token set — you are managing one per store, each with its own refresh token and expiry clock. Doing that by hand across three regions is a part-time job nobody wants. Each store needs its tokens refreshed, its scopes kept current, and its re-auth handled when something lapses.

Where Fetch Order Tracking saves you the headache

Fetch Order Tracking handles the entire eBay OAuth lifecycle for you. You connect your store once; it requests the right scopes — including the finances scope so it can read true net earnings from the Finances API — stores your refresh token securely, and quietly mints fresh access tokens before every batch so a sync never dies halfway through.

Because it manages tokens per store, running multiple regions from one workspace does not multiply your auth chores. And because the auth is solid, the data downstream — tracking IDs, carriers, refund states, real profit — flows into your Google Sheet without you ever thinking about a token again. Skip the OAuth maze and get straight to the data that runs your business. Try Fetch Order Tracking.

Frequently asked questions

Which eBay OAuth scopes do I need for a tracking and profit workflow?

Two matter most. The fulfilment or order scope lets you read orders, line items, and shipping info and upload tracking back to eBay. The finances scope is a separate scope required to read the Finances API, and without it you cannot pull true net earnings, only gross order prices. If your profit column looks empty or wrong, check whether the finances scope was actually granted before you debug your code.

How do I stop my eBay sync from getting logged out mid-batch?

Do not build around the access token, which expires in roughly two hours. Store the refresh token securely the moment you receive it and mint a fresh access token from it right before each batch or whenever the current one is near expiry. Also handle the case where the refresh token itself is revoked, because a password change or withdrawn consent on the seller's side needs a clean re-auth path rather than a stack trace.

Does Fetch Order Tracking handle eBay OAuth and refresh tokens for me?

Yes. You connect your store once and Fetch Order Tracking requests the right scopes, including the finances scope, stores your refresh token securely, and quietly mints fresh access tokens before every batch so a sync never dies halfway through. Because it manages tokens per store, running eBay UK, US, and AU from one workspace does not multiply your auth chores.

Related guides

Try Fetch Order Tracking → More guides