Get started

eBay channel

@mercentia/ebay-channel integrates Mercentia with the eBay Sell API. Once connected, a merchant can publish products to eBay listings, sync inventory levels both ways, and reconcile eBay-paid orders into the Mercentia order timeline.

Connecting

  1. Sign in to your eBay developer account.
  2. Create a production “keyset” — copy the App ID, Cert ID, and Dev ID.
  3. In Mercentia, open Channels → eBay and click Connect with eBay. Approve the OAuth consent screen on eBay; the gateway exchanges the auth code for a user token and refresh token, persisted under the calling store.
  4. Pick a marketplace (EBAY_GB, EBAY_US, etc.) and a default merchant location key. These determine the legal entity that ships the order.

Publishing a product

From the product page, open the Channels panel and toggle eBay. Mercentia:

  • Creates an InventoryItem for each variant SKU.
  • Creates an Offer for each variant against the chosen marketplace.
  • Publishes the offer (POST /sell/inventory/v1/offer/{offerId}/publish).
  • Persists the resulting listingId against the variant so follow-up syncs target the correct listing.

Pricing, title, and description default to the Mercentia values. Override per-channel from the panel if you need eBay-only copy.

Inventory sync

Both directions are supported:

  • Mercentia → eBay: Every order that decrements stock fires a job that updates availability.shipToLocationAvailability.quantity on the matching InventoryItem.
  • eBay → Mercentia: A scheduled poll calls GET /sell/inventory/v1/inventory_item/{sku} and reconciles the remote quantity into Mercentia’s stock ledger. Mismatches raise a channel_drift_detected event on the variant.

Orders

eBay orders arrive via the marketplace-account-deleted and marketplace-order-fulfillment webhooks. The gateway upserts an order with source = 'ebay' and the eBay buyer’s contact info, mapping each line to the matching Mercentia variant by SKU. Payment is recorded as paid_externally since eBay captures funds.

Disconnect

Channels → eBay → Disconnect revokes the OAuth token and hides all eBay-listed offers. Existing listings on eBay remain until you end them on eBay’s side.

Troubleshooting

Symptom Cause
Publish fails with Item.policy.payment.missing The marketplace requires a business policy — set one in eBay Seller Hub and re-publish.
Inventory drift alerts Another tool (or a manual edit on eBay) changed the quantity. Reconcile from the channel panel.
OAuth refresh fails The user token expired and the refresh token was also revoked. Click Reconnect.