eBay

eBay's API is friendlier than Amazon's but the listing model has its own model — items live in fixed-price or auction listings, conditions matter, and category-specific required fields (item specifics) vary by what you sell.

OAuth and environments

eBay has two environments: Production and Sandbox. The connect flow defaults to Production; pass environment: "sandbox" in the enable config to point at the sandbox API.

{
  "environment": "production",
  "marketplaceId": "EBAY_US",
  "fulfillmentPolicyId": "...",
  "paymentPolicyId": "...",
  "returnPolicyId": "..."
}

marketplaceId selects the eBay site (EBAY_US, EBAY_GB, EBAY_DE, etc.). The three policy IDs come from the seller's eBay account — eBay requires a fulfillment policy, payment policy, and return policy attached to every listing.

Item conditions

Every listing requires a condition. eBay's condition IDs are integers — the channel mapping translates your internal condition strings to eBay IDs:

eBay ID	Description
1000	New
1500	New other (open box)
2000	Manufacturer refurbished
2500	Seller refurbished
3000	Used
4000	Very Good
5000	Good
6000	Acceptable
7000	For parts or not working

Some categories restrict allowed conditions (e.g. categories under Books only allow 1000, 2750, 3000, 4000, 5000, 6000). Pushing an unsupported condition returns 1083: Item condition is invalid.

Listing duration

Fixed-price listings on eBay have a duration: 1, 3, 5, 7, 10, 30 days, or GTC (Good 'Til Cancelled). The provider defaults new listings to GTC, which auto-renews monthly. Auction listings (rare on eBay these days) cap at 10 days.

{
  "format": "FixedPriceItem",
  "duration": "GTC"
}

Item specifics

Each eBay category has required and recommended item specifics — structured attributes like Brand, Model, Color, Size. The API enforces required ones; missing them returns 21916233: Required item specifics are missing.

Discover required specifics per category:

curl -X POST https://appengine.appmint.io/sales-channel/channels/ebay/execute \
  -H "Authorization: Bearer $JWT" -H "orgid: $ORG" \
  -d '{"operation": "get_required_aspects", "data": {"categoryId": "11450"}}'

Map your internal attributes to eBay specifics via POST /sales-channel/mappings/attributes.

eBay Stores

Sellers with an eBay Store subscription get extra capabilities — store categories, custom URL, lower per-listing fees. The channel surfaces the store's custom categories as a separate taxonomy. Map your category tree to store categories via POST /sales-channel/mappings/categories with targetType: "ebay_store".

Rate limits

eBay's REST APIs allow up to 5,000 calls/min and ~1M/day per app. The Trading API (legacy XML) has separate limits. The provider hits both — most operations use REST; bulk listing revisions still call Trading because the REST equivalent doesn't cover all fields. Hitting limits returns 21919189: Rate limit exceeded.

Order pull

Orders flow in via REST getOrders (poll) and via webhook notifications (eBay Notifications API). Configure the notification subscriptions during channel enable; the provider auto-subscribes to AuctionCheckoutComplete, FixedPriceTransaction, ItemSold, OrderCancelled.

Quirks worth a callout

• Variations — eBay supports variations (size/color combos) only in select categories. The provider rejects variation pushes outside those categories.
• Best Offer — set per-listing via bestOfferEnabled: true. Auto-accept and auto-decline thresholds go on the listing, not the channel config.
• GTIN gate — many categories require a GTIN (UPC/EAN/ISBN). For brand-new products without a GTIN, request a GTIN exemption from eBay first.
• Tax tables — eBay applies sales tax based on a per-state table maintained on the seller's account. Don't push line-level tax; let eBay compute it.