eBay Adapter
NexusCommerce integration with the eBay REST APIs for global marketplace selling.
Overview
The eBay adapter connects NexusCommerce to eBay's REST API suite, covering eBay's global marketplace network. The adapter uses the eBay Sell APIs for listings, orders, fulfillment, and inventory management, and the eBay Buy APIs for market research and competitor data.
eBay operates marketplace sites across 190 countries. A single seller account (eBay Global Account) can list on multiple eBay sites; configure one NexusCommerce connection per eBay site you sell on.
Key Concepts
eBay Sell APIs — The suite of APIs used to manage a seller's presence on eBay. Key APIs used by this adapter:
Sell Inventory API— Manage inventory items and offersSell Fulfillment API— Retrieve and manage orders and shipmentsSell Listing API— Manage item listingsSell Account API— Retrieve seller-level settings (payment policies, return policies, shipping profiles)
Inventory Item vs. Offer — eBay separates the product definition (Inventory Item) from the marketplace listing (Offer). NexusCommerce maps its product schema to both: the Inventory Item holds product details (title, description, images, aspects), and the Offer holds the price, quantity, and listing-specific settings.
eBay Site ID — Each eBay marketplace has a numeric site ID. Common values: US (0), UK (3), Germany (77), Australia (15), France (71).
Condition IDs — eBay uses numeric condition IDs (1000 = New, 3000 = Used - Very Good, etc.). NexusCommerce maps its condition values to eBay condition IDs during listing creation.
Getting Started
Required Credentials
| Field | Description |
|---|---|
| App ID (Client ID) | From the eBay Developer Program |
| Cert ID (Client Secret) | From the eBay Developer Program |
| Dev ID | From the eBay Developer Program |
| User Access Token | OAuth user token obtained via eBay's consent flow |
| Refresh Token | Long-lived token for re-issuing access tokens |
| eBay Site ID | The eBay marketplace site to connect |
OAuth Flow
eBay uses OAuth 2.0 with a user consent (authorization code) flow:
- Register your application at developer.ebay.com
- Note the App ID (Client ID), Cert ID (Client Secret), and Dev ID
- In NexusCommerce, navigate to Connections > Add Connection > eBay
- Click Connect via eBay — NexusCommerce opens the eBay consent page
- Log in with your eBay seller account and grant the requested scopes
- NexusCommerce stores the access token and refresh token automatically
Required OAuth Scopes:
https://api.ebay.com/oauth/api_scope
https://api.ebay.com/oauth/api_scope/sell.inventory
https://api.ebay.com/oauth/api_scope/sell.fulfillment
https://api.ebay.com/oauth/api_scope/sell.account
https://api.ebay.com/oauth/api_scope/sell.marketingAccess tokens expire after 2 hours. Refresh tokens are valid for 18 months. NexusCommerce handles token refresh automatically using the stored refresh token.
Synced Data
| Data Type | Direction | eBay API | Notes |
|---|---|---|---|
| Products (Inventory Items) | Read / Write | Sell Inventory API | Title, description, aspects, images |
| Offers (Listings) | Read / Write | Sell Inventory API | Price, quantity, listing status |
| Orders | Read | Sell Fulfillment API | All statuses; paginates automatically |
| Shipment Tracking | Write | Sell Fulfillment API | Carrier and tracking number |
| Returns | Read / Write | Sell Fulfillment API | Accept/decline return requests |
| Account Policies | Read | Sell Account API | Payment, return, and shipping policies |
Configuration Options
| Key | Type | Default | Description |
|---|---|---|---|
site_id | integer | 0 (US) | eBay site to connect |
sync_interval_minutes | integer | 60 | Polling frequency |
order_lookback_days | integer | 30 | Historical order import window |
listing_duration | string | GTC | Default listing duration (GTC = Good Till Cancelled) |
auto_relist | boolean | true | Automatically relist ended fixed-price listings |
out_of_stock_control | boolean | true | Keep listings active when quantity reaches 0 |
eBay Site IDs Reference:
| Marketplace | Site ID |
|---|---|
| eBay US | 0 |
| eBay UK | 3 |
| eBay Germany | 77 |
| eBay Australia | 15 |
| eBay France | 71 |
| eBay Italy | 101 |
| eBay Spain | 186 |
| eBay Canada | 2 |
Supported Features
| Feature | Supported | Notes |
|---|---|---|
| Product listing sync | Yes | Inventory Item + Offer model |
| Inventory updates | Yes | Via Sell Inventory API |
| Order sync | Yes | Including partial refunds |
| Shipment confirmation | Yes | Required to release funds |
| Returns management | Yes | Accept or decline via API |
| Pricing updates | Yes | Fixed-price offers |
| Account policies sync | Yes | Payment, return, shipping profiles |
| Webhooks | Yes | Order and listing notifications |
| Promoted Listings data | No | Requires Sell Marketing API integration |
| Auction listings | No | Fixed-price only |
| Multi-quantity variations | Yes | SKU-level quantity per variation |
Webhooks
The eBay adapter registers for real-time notifications via the eBay Notification Platform. NexusCommerce subscribes to these topics on connection setup:
| Topic | Description |
|---|---|
MARKETPLACE_ACCOUNT_DELETION | Seller account deletion notice |
OFFER_LISTED | New listing goes live |
OFFER_ENDED | Listing ends or is removed |
ORDER_LINE_ITEM_SHIPPED | Buyer marks item received |
Webhook payloads are verified using the eBay notification signature (X-EBAY-SIGNATURE header).
Rate Limits & Quotas
eBay applies per-API rate limits. Default application limits:
| API | Daily Call Limit |
|---|---|
| Sell Inventory | 5,000 |
| Sell Fulfillment | 5,000 |
| Sell Account | 5,000 |
The adapter tracks call counts per day. When approaching 80% of the daily limit, it reduces polling frequency and defers non-critical reads. Limits reset at midnight UTC.
For high-volume accounts, contact eBay Developer Support to request increased call limits.
Troubleshooting
Invalid access token after connection setup
The access token has expired and the refresh token could not be used. Click Reconnect in NexusCommerce to re-run the eBay consent flow and obtain fresh tokens.
Listings not appearing on eBay
eBay requires category-specific item aspects (e.g., Brand, MPN for Electronics). Ensure your products have the required aspects filled in. Check the sync log for ItemAspects validation errors.
CATEGORY_REQUIRED error on product publish
eBay's category taxonomy is required for all listings. NexusCommerce auto-suggests a category based on the product title. Override using the ebay_category_id custom attribute on the product.
Orders missing from sync
Verify that the OAuth token was granted the sell.fulfillment scope. Re-connect if necessary. Check whether the order_lookback_days setting covers the period in question.
Return requests not updating
eBay return requests must be responded to within the seller's stated return window. If NexusCommerce fails to sync a return decision, check the sync log for API errors related to the Sell Fulfillment API returns endpoint.