eBay Integration — Overview

This section covers everything you need to integrate eBay through EcartAPI: products, variants, offers, policies, orders, fulfillments, locations, categories, and webhooks.

---

v1 vs v2

EcartAPI's eBay integration is split across two API versions that complement each other:

Both versions share the same OAuth token. v1 and v2 are EcartAPI's own versioning — they do not map directly to eBay API versions. Both internally call eBay's current REST and Trading APIs as needed.

---

Critical: Inventory API vs. legacy listings

EcartAPI works exclusively with eBay's Inventory API. This is the most important concept to understand before working with any product endpoint:

• Products, SKUs, and offers created through EcartAPI live in eBay's Inventory API.
• Listings created outside of the Inventory API (directly on eBay's site or via the old listing flow) are not accessible by SKU through EcartAPI's product endpoints.
• If GET /api/v2/products/{sku} returns 404, it means the product does not exist in the Inventory API — not that the SKU is wrong or that the product doesn't exist on eBay.

To make legacy listings accessible via EcartAPI, they must be migrated first. See Products & Variants → Migrating Existing Listings.

---

Multiple marketplaces

eBay US and eBay UK are completely separate integrations. Each marketplace requires its own:

• OAuth connection — a separate access token per marketplace
• Policies — fulfillment, payment, and return policies are per marketplace (EBAY_US policies do not apply to EBAY_GB)
• Locations — inventory locations are per marketplace

If you try to publish an offer in EBAY_GB using policy IDs or locations created for EBAY_US, eBay will return an error ("Inventory Item Group not found" or similar). Connect each marketplace separately via OAuth, then create the full set of policies and at least one location for each marketplace before publishing any offer.

---

Complete selling flows

Flow 1 — First-time seller setup

Before publishing any offer, your account must have policies and a location in place:

1. GET  /api/v1/policies/sellerPrograms               — verify SELLING_POLICY_MANAGEMENT enrollment
2. POST /api/v1/policies/sellerPrograms               — enroll (if not already enrolled)
3. POST /api/v1/policies/fulfillments/{marketplaceId} — create fulfillment policy
4. POST /api/v1/policies/payments/{marketplaceId}     — create payment policy
5. POST /api/v1/policies/returns/{marketplaceId}      — create returns policy
6. POST /api/v2/locations                             — create inventory location

→ Full details: Getting Started

---

Flow 2 — Publish a single product

After the first-time setup is complete:

1. GET  /api/v2/categories?marketplaceId=EBAY_US      — find the correct category ID
2. POST /api/v1/products                              — create the product (inventory item)
3. POST /api/v1/products/listings                     — create offer and publish it in one call
4. PUT  /api/v2/products/{sku}  (inventory: true)     — update stock and/or price later

→ Full details: Products & Variants, Listings & Offers

---

Flow 3 — Publish a variant group

Variants require a 4-step process:

1. POST /api/v1/products/batch                                  — create all variant products in one call
2. POST /api/v1/products/{inventoryItemGroupKey}/variants       — create the product group linking all SKUs
3. POST /api/v1/products/listings/batch                         — create one offer per variant SKU
4. POST /api/v1/products/{inventoryItemGroupKey}/variants/publish — publish the entire group at once

→ Full details: Products & Variants → Complete flow: create and publish a variant group

---

Flow 4 — Update inventory and price

1. PUT /api/v2/products/{sku}     with { "product": { "quantity": "10" } }          — update stock quantity
2. PUT /api/v1/listings/{offerId} with pricingSummary.price                          — update price at the offer level

Or to update stock and price in one call:

PUT /api/v2/products/{sku}  with { "product": { "offers": [{ "id": "OFFER_ID", "quantity": "10", "price": {...} }] } }

Note: Price cannot be updated by sending price alone to the product endpoint — it returns 200 OK but has no effect. Use the offer endpoint or include the offers array. See Listings & Offers → Updating an offer.

---

Flow 5 — Fulfill an order

1. GET  /api/v2/orders/{orderId}                     — fetch order to get lineItemIds
2. GET  /api/v2/services/carriers?ecommerce=true     — get valid carrier codes for your marketplace
3. POST /api/v2/orders/{orderId}/fulfillments        — create fulfillment with items, tracking.number, tracking.companyId

→ Full details: Orders & Fulfillments

---

Flow 6 — Migrate a legacy listing

1. GET  /api/v1/products/listings                         — get listing IDs from the Trading API
2. POST /api/v2/products/listings/migrate                 — send { "listings": { "ids": ["LISTING_ID"] } }
3. PUT  /api/v2/products/{sku}  with { "product": { "quantity": "10" } }  — update inventory after migration

Before migrating a variant listing, ensure every variant has at least 1 unit in stock. Zero-stock variants are silently excluded and cannot be re-added via migration. See Products & Variants → Migrating existing listings.

---

Guide sections