eBay API Setup Guide

Last updated June 2026 · eBay Sell Fulfillment API v1 · Sell Inventory API v1

What You Need

• An eBay seller account (any level)
• An eBay Developer Account at developer.ebay.com
• A registered application in the eBay Developer Program
• A user OAuth token granted by the seller (authorization-code grant)

Step-by-Step Setup

1. Create an eBay Developer Account Register at developer.ebay.com/signin. Use the same email as your eBay seller account, or a separate developer email. The Developer Program is free to join.
2. Create an Application In the Developer Portal, go to My Account → Application Keys and click Create Application. Give it a name (e.g. EcomCentral). You will see two sets of keys:
   • Production — for your live eBay account
   • Sandbox — for testing (use a sandbox seller account)
   Note the App ID (Client ID), Dev ID, and Cert ID (Client Secret). These are needed for the OAuth token exchange.
3. Add OAuth redirect URI (RuName) In Application Keys → your app → User Tokens → click Get a Token from eBay via Your Application. Add your redirect URI (e.g. https://your-ecomcentral-domain/oauth/ebay/callback). eBay calls this a RuName. Note it for the authorization URL.
4. Request the required OAuth scopes When building the authorization URL, request these scopes:

   Scope	Purpose	Required?
   https://api.ebay.com/oauth/api_scope/sell.fulfillment	Read & write orders, create shipping fulfillments	Required
   https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly	Read orders only (if write not needed)	Alternative
   https://api.ebay.com/oauth/api_scope/sell.inventory	Read & update inventory items and stock	Required
   https://api.ebay.com/oauth/api_scope/sell.inventory.readonly	Read inventory only	Alternative

5. Authorize and get the access token Direct the seller to the eBay authorization URL:

   https://auth.ebay.com/oauth2/authorize
     ?client_id=YOUR_APP_ID
     &redirect_uri=YOUR_RUNAME
     &response_type=code
     &scope=https://api.ebay.com/oauth/api_scope/sell.fulfillment
            https://api.ebay.com/oauth/api_scope/sell.inventory

   After the seller authorizes, eBay redirects with a code parameter. Exchange it for tokens:

   POST https://api.ebay.com/identity/v1/oauth2/token
   Content-Type: application/x-www-form-urlencoded
   Authorization: Basic base64(client_id:client_secret)
   
   grant_type=authorization_code
   &code=YOUR_CODE
   &redirect_uri=YOUR_RUNAME

   The response includes an access_token (valid ~2 hours) and a refresh_token (valid ~18 months).
   
   
   ℹ️ Store the access token in EcomCentral as the access_token credential. You will need to refresh it periodically using the refresh token — access tokens expire after ~2 hours.
6. Add the connection in EcomCentral Go to Connections → Add Connection → eBay and enter:

   Field	Value
   access_token	OAuth2 user access token (without the "Bearer " prefix)
   marketplace_id (optional)	eBay marketplace (default: EBAY_US). See table below.
   content_language (optional)	Content-Language header (default: en-US). Match your marketplace locale.

   Set Environment to sandbox if using sandbox credentials.

eBay Marketplace IDs

Order Fulfillment Status Reference

How Shipping Fulfillment Works

When you click Create Fulfillment in EcomCentral:

1. EcomCentral fetches the full order to collect all lineItemId values
2. All line items are included in the createShippingFulfillment request (required by the eBay Sell Fulfillment API)
3. The carrier code, tracking number, and shipped date are sent to eBay
4. eBay notifies the buyer and updates the order's fulfillment status

Inventory Updates

eBay's Inventory API uses a full-record PUT (createOrReplaceInventoryItem) — there is no partial update endpoint for quantity alone.

EcomCentral handles this safely by:

1. Fetching the current inventory item record (product title, condition, aspects, etc.)
2. Merging the new quantity into it
3. Sending the complete updated record back to eBay

Token Expiry & Refresh

eBay access tokens expire after approximately 2 hours. When an API call fails with a 401, the token has expired. To refresh:

POST https://api.ebay.com/identity/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&scope=https://api.ebay.com/oauth/api_scope/sell.fulfillment
       https://api.ebay.com/oauth/api_scope/sell.inventory

Update the access_token value in the EcomCentral connection with the new token. Refresh tokens last ~18 months but must also be renewed before expiry.

Troubleshooting

✕ "API not configured (access_token missing)"

No access_token credential is set. Edit the connection and add the OAuth token.

✕ HTTP 401 — Invalid access token

The access token has expired (~2 hours). Refresh it using the refresh_token and update the connection.

✕ HTTP 403 — Insufficient permissions

The OAuth token was not granted the required scopes. Re-authorize the app and request sell.fulfillment and sell.inventory scopes.

✕ HTTP 400 on createShippingFulfillment

Most commonly caused by an unrecognized shippingCarrierCode. Check eBay's list of accepted carrier codes for your marketplace, or use Other as a fallback.

Inventory items not showing

The Sell Inventory API only shows items created or migrated to the Inventory API. Older listings created via the Trading API or Seller Hub may not appear here. Use eBay's Inventory Item Migration tool to move them.

EcomCentral · eBay Sell Fulfillment API v1 & Inventory API v1 · Official eBay Sell API Docs