eBay Integration
Connect your eBay seller account with OAuth 2.0, sync inventory and orders across the Fulfillment, Inventory, and Account REST APIs, and ask the AI Assistant questions about stock levels, order volume, and revenue.
Overview
The eBay Integration screen (Ecommerce → Marketplace Hub → eBay) is the connection hub between TotalApp and your eBay seller account. It manages your OAuth 2.0 credentials, exchanges your refresh token for short-lived user access tokens, fetches inventory and recent orders, lists the exact REST endpoints in use, tracks your daily call limits, and provides an embedded AI Assistant with direct context of your marketplace data.
How eBay OAuth & Signatures Work
eBay's API ecosystem is built from: App ID (Client ID), Cert ID (Client Secret) and Dev ID that authenticate your application; a RuName (eBay Redirect URL Name) used on the consent screen; a per-seller Refresh Token (valid ~18 months, stored AES-256 encrypted per tenant) that mints a fresh User Access Token (~2 hours) on demand; and Digital Signatures (Ed25519 / RSA-SHA256) sent in the x-ebay-signature-key header for the Fulfillment and Finance endpoints that require them.
Server-Side API Calls Only
All requests to the OAuth token endpoint and the REST endpoint (api.ebay.com, or api.sandbox.ebay.com) are made from the TotalApp server, never directly from your browser. Your Cert ID, Refresh Token, and signing key are never exposed to the browser, and CORS restrictions are avoided.
eBay Developer Setup & Onboarding Guide
Follow these four stages in order to obtain everything TotalApp needs. This is the practical checklist your developer team can work through end to end.
1eBay Developer Account & Keysets
- Join the eBay Developers Program (developer.ebay.com) and create an application.
- Under Application Keysets, obtain a Sandbox keyset for testing and a Production keyset for live traffic. Each keyset contains an App ID (Client ID), a Dev ID, and a Cert ID (Client Secret).
- Keep Sandbox and Production keys separate — they authenticate against entirely different hosts.
- Tip: the Cert ID is shown only once at generation. Store it securely; you must regenerate the keyset if it is lost.
2RuName (eBay Redirect URL Name) Setup
- In User Tokens → Get a Token from eBay via Your Application, configure your OAuth Redirect URL (the endpoint that receives the authorization code).
- eBay generates a RuName — a special alias standing in for your redirect URL on the consent screen (a plain URL is not used).
- Set your Auth Accepted / Declined URLs and privacy policy link.
- Record the RuName — enter it into TotalApp.
3OAuth 2.0 Authorization Flows
User Access Token (Authorization Code Grant) — for seller-scoped operations:
- Redirect the seller to eBay's consent screen using your RuName and scopes.
- eBay redirects back with an Authorization Code.
- Exchange the code at
POST /identity/v1/oauth2/token(grant_type=authorization_code) for an Access Token (~2h) and a Refresh Token (~18 months). Store the refresh token AES-256 encrypted, keyed per tenant. - At call time, exchange the refresh token for a fresh access token (
grant_type=refresh_token). TotalApp caches this per tenant until ~1 minute before expiry.
Application Access Token (Client Credentials Grant) — for public data (Catalog, Taxonomy) that needs no seller consent: call POST /identity/v1/oauth2/token with grant_type=client_credentials.
4Digital Signatures (Payload Signing)
- Certain Fulfillment and Finance endpoints mandate a Digital Signature over the request payload to guarantee integrity.
- Generate an Ed25519 (or RSA) key pair and register the public key with eBay to receive a signing key id.
- For each signed request, TotalApp signs the payload with your private key and sends the signature alongside the key id in the
x-ebay-signature-keyheader. - Enter the Signing Key ID and Signing Private Key (PEM) in TotalApp to enable signing; without them, signed endpoints are called unsigned (sandbox-safe).
Setting Up the Connection in TotalApp
Open Settings → Integrations → Ecommerce → eBay and enter:
| Field | Where to find it | Example |
|---|---|---|
| App ID (Client ID) | Developer Program → Application Keys | YourApp-XXXX-PRD-... |
| Cert ID (Client Secret) | Developer Program → Application Keys | PRD-xxxxxxxxxxxx-... |
| Dev ID (optional) | Developer Program → Application Keys | xxxxxxxx-xxxx-... |
| RuName | Developer Program → User Tokens | Your_Company-YourApp-PRD-... |
| Refresh Token | From the OAuth authorization-code flow | v^1.1#i^1#... |
| Marketplace | eBay marketplace you sell in | EBAY_US |
| Environment | Production or Sandbox | production |
| Signing Key ID / Private Key (optional) | For digital signatures | -----BEGIN PRIVATE KEY----- |
Back on the eBay Integration screen, open the Seller Connection panel and click Test Connection. TotalApp performs an OAuth token exchange (proving your credentials) and fetches a page of inventory to confirm scope.
Connect eBay Account button
The Connect eBay Account button opens the eBay consent screen (via your configured RuName) to begin the authorization-code flow. In production, the redirect callback exchanges the authorization code for the refresh token that is then saved (encrypted) for your tenant.
API Endpoints & Backend Modules
The screen exposes an API Endpoints reference panel. Path parameters such as {orderId} and {sku} are filled at call time. Endpoints that require a digital signature are flagged SIG.
Authentication — api.ebay.com
| Method | Path | Purpose |
|---|---|---|
POST | /identity/v1/oauth2/token (refresh_token) | User access token exchange (~2h) |
POST | /identity/v1/oauth2/token (client_credentials) | Application access token (public data) |
REST APIs — api.ebay.com / api.sandbox.ebay.com
| Method | Path | Module |
|---|---|---|
GET | /sell/fulfillment/v1/order | getOrders |
POST | /sell/fulfillment/v1/order/{orderId}/shipping_fulfillment (SIG) | createShippingFulfillment |
GET | /sell/inventory/v1/inventory_item | getInventoryItems |
POST | /sell/inventory/v1/bulk_update_price_quantity | bulkUpdatePriceQuantity |
PUT | /sell/inventory/v1/inventory_item/{sku} | createOrReplaceInventoryItem |
GET | /sell/account/v1/fulfillment_policy | Account API (Fulfillment & Return policies) |
Rate Limits & Retry
eBay enforces per-application daily call limits and returns HTTP 429 when a limit is exceeded. TotalApp sends the X-EBAY-C-MARKETPLACE-ID header on every request, tracks usage in the Daily Call Limits gauge, and retries with jittered exponential back-off (up to 3 attempts) so transient throttling does not fail a sync.
Sync Settings & Logs
The Sync Settings panel exposes toggles for Auto Order Pull and Inventory & Price Sync, plus a Default Marketplace selector (US, GB, DE, and more) that becomes the X-EBAY-C-MARKETPLACE-ID on every request. The Sync Logs panel records each connection test, inventory sync, and order sync with a timestamp, scope, and success/failure detail so you can audit recent activity at a glance.
AI Assistant
The AI Assistant panel gives you a conversational interface into your eBay data. When credentials are configured, TotalApp fetches your live inventory and last-30-days orders server-side and provides them as context.
What You Can Ask
- Stock questions: “Which SKUs are out of stock or low on available inventory?”
- Order questions: “Summarize my orders from the last 30 days by fulfillment status.”
- Revenue questions: “What is my total revenue and which products are top sellers?”
Writer Engine Support
The assistant respects your Settings → Agentic → Writer Engine choice. In Local CLI or Hosted API mode, live eBay data is fetched server-side and included as context. In Ollama, Local LLM, or Web LLM mode the request runs entirely client-side and live marketplace data is not available — switch to Local CLI or Hosted API for data-driven reports.
Saving as a Report
After the AI responds, a Save as Report button appears under the reply. Clicking it saves the response as a named report in Ecommerce Reports, automatically titled with your question and the current month.
Frequently Asked Questions
x-ebay-signature-key header) on specific Fulfillment and Finance endpoints — for example createShippingFulfillment. TotalApp signs the payload with your Ed25519/RSA private key when a signing key is configured; endpoints flagged SIG in the reference panel require it.sandbox, and a Production keyset must use production; they authenticate against different hosts.