eBay as a Channel
June 26, 2026
Summary
eBay is Flxpoint's current-generation marketplace integration, connecting over OAuth2 and eBay's Inventory API to publish listings, sync price and quantity, import orders, and send tracking back to eBay. It runs separately from eBay Legacy (Auth Token + Trading API): listings created through one cannot be managed by the other, so create a new eBay channel and run it in parallel while you migrate.
What this integration does
Publish Listings
Publishes mapped Flxpoint product data as new eBay listings via the Inventory API
Sync & Link Listings
Pushes price and quantity and links existing eBay listings to Flxpoint products by SKU, UPC or MPN
Get Orders
Imports new eBay orders into Flxpoint for processing and fulfillment
Sync Orders
Sends shipment confirmations, carrier and tracking numbers back to eBay
Filter listings by source
You can now use the Source Name quick filter within the Listings grid UI to isolate products by their inventory origin. This allows you to quickly view and manage eBay listings based on which specific source is supplying the inventory, providing better visibility into your multi-source fulfillment strategy.
How to connect: credentials you need
Add a new channel, choose eBay (not eBay Legacy), name it, then click Get Started to launch the setup wizard and authenticate. Business Policy IDs and the Merchant Location Key are entered later in the wizard's publishing step.
| Field | What to enter |
|---|---|
eBay Account Connection (OAuth2)Required | The wizard authenticates over OAuth2: click Get Started and sign in to your eBay account to authorize Flxpoint. There is no manual token or key to paste in.
Have your eBay account credentials ready before starting. If auth later fails or returns 401/403, open the operation, click Edit, go to Connect an Integration, open the connection and click Click here to generate a new refresh token to regenerate the OAuth token: tokens expire and need periodic renewal. |
Return Policy IDSetting | Your eBay return handling business policy ID. Required before any listing can be published. Click View Policies to pull your available policies from eBay.
Open eBay Seller Hub |
Fulfillment Policy IDSetting | Your eBay shipping options and timeframes business policy ID. Required for publishing.
Created and managed in your eBay Seller Hub. |
Payment Policy IDSetting | Your eBay payment business policy ID. Required for publishing.
Created and managed in your eBay Seller Hub. |
Merchant Location KeySetting | Identifies where you ship from. Click View Merchant Locations to see options pulled from eBay. If it is missing, Flxpoint attempts to auto-create it. eBay Motors sellers also need at least Country + Postal Code (or Country + State/Province).
A misconfigured Merchant Location Key can make publish fail with a 500 or null-pointer error. |
Policy fields empty? Confirm the policies exist in your eBay Seller Hub, then regenerate your Refresh Token to fetch the latest data. Connection test failing or 401/403 errors? Open the operation, click Edit, go to Connect an Integration, open the connection and click "Click here to generate a new refresh token" to regenerate the OAuth token; if you suspect rate limiting, wait 15 to 30 minutes and reduce scheduled job frequency.
Important: read before configuring
The new eBay integration can only manage Inventory API listings
eBay uses the Inventory API exclusively. Listings created manually in Seller Hub or via the Trading API (Legacy) cannot be linked or synced through the new channel: they must be re-published through Flxpoint's new eBay channel to be managed going forward. Import Listings is not supported on the new eBay channel; use Sync & Link Listings instead.
Do not replace eBay Legacy before you fully migrate
Run the new eBay channel in parallel with Legacy while you test, and keep Legacy active until every open order has its tracking synced back to eBay. Removing it earlier loses the tracking history for those orders. See Migrating from eBay Legacy for the order to move each job in.
Category ID must be a leaf (terminal) category
eBay requires the Category ID to be the most specific subcategory with no children: a parent category ID causes publish failures. Download the category file for your eBay site to validate IDs before publishing: eBay US, eBay Motors US or eBay Australia. Each lists every leaf category ID with the aspects that category requires. For another eBay site, ask Flxpoint support. Re-download the file if you hit unexpected category errors, since eBay updates categories periodically.
Business policies and a Merchant Location are required to Publish
The new eBay integration requires valid Return, Fulfillment and Payment policy IDs plus a Merchant Location Key before any listing can be published. If the Merchant Location Key is missing, Flxpoint tries to auto-create it, but if it is misconfigured, publish fails with a 500 or null-pointer error.
Syncing listings automatically unpauses items
When you click Start Syncing Listings, Flxpoint now automatically unpauses all listings before the sync job begins. This ensures that your updates are pushed to eBay without requiring manual status changes first.
Inventory audit completion notifications
You will receive an email notification once an inventory audit job completes. This email includes a direct link to the onboarding guide to help you navigate next steps in your channel setup.
Use country-specific category files
eBay requires a numeric Category ID for every listing. Because these IDs vary by region, you must use the reference file matching your selling location: eBay US, eBay Motors US, or eBay Australia. For other regions, contact support.
Migrating from eBay Legacy
The two integrations talk to different eBay APIs, so moving between them is a cutover, not a settings change: your Legacy listings are not converted, and nothing you configured on the Legacy channel carries across. You relink or republish your listings on the new channel, then retire Legacy one job at a time. Work through the steps in order, keep Legacy connected until the last one, and at every point know which channel owns your listings, your orders and your shipments.
| What changes | eBay Legacy | New eBay channel |
|---|---|---|
| eBay API | Trading API | Inventory API, exclusively |
| Authentication | An Auth Token you generate in your eBay Developer account and paste in | OAuth2 sign-in, with no token to paste. Tokens expire, so open the operation, click Edit, go to Connect an Integration, open the connection and click Click here to generate a new refresh token when authentication starts failing |
| Bringing your listings across | Import Listings | Sync & Link Listings. Import Listings is not supported |
| Which listings it can manage | Listings created through the Trading API | Only listings created through the Inventory API flow. Anything created in Seller Hub, or on Legacy, has to be republished through Flxpoint |
01
Set upCreate the new channel alongside LegacyAdd a new channel, choose eBay (not eBay Legacy), and name it so you can tell the two apart at a glance. Leave Legacy connected and running. Complete the setup wizard in one sitting: if you close or minimize it before finishing, you may not be able to relaunch it for that channel, and support has to remove the half-created channel before you can start over.
02
Set upAuthenticate, then fill in the publishing requirementsSign in to eBay to authorize Flxpoint, then set the Return, Fulfillment and Payment policy IDs and the Merchant Location Key in the wizard's publishing step. Use View Policies and View Merchant Locations to pull the current values straight from eBay rather than typing them. Nothing publishes until all four are set.
03
Set upRebuild your channel rules, then check the numbers they producePricing and Quantity Rules, Maximum Quantity, listing mapping templates and category mapping are configured per channel, so the new channel starts empty and you rebuild them there. Then check what they produce before anything syncs: open a handful of variants and compare the price the new channel calculates against what is live on eBay today. This is the cheapest moment to catch a pricing mistake, and worth extra care if account-level pricing rules and channel tier pricing both apply to the same variant.
04
LinkMap the SKU field the new channel actually usesIn the Sync & Link Listings template, map SKU to eBay V2 Variant Link SKU, not eBay Product SKU. This is the single most common reason a migration appears to do nothing. Map Price and Quantity explicitly as well: unmapped fields are skipped without raising an error.
05
LinkRun Link Listings before Sync ListingsLink Listings matches your live eBay listings to Flxpoint products, and sync cannot update a listing that is not linked yet, so running Sync first looks like a job that succeeds and changes nothing. Set the sync direction to Flxpoint → eBay. Expect some listings not to link. If one you expect to link will not, Advanced Linking and Syncing Listings and Channel SKU Not Linked go deeper than this section does.
06
LinkRepublish whatever would not linkAnything Link Listings cannot match has to be published through the new eBay channel to be managed going forward, which creates a new eBay listing. Before you run it, confirm the Category ID is a leaf category and that every aspect that category requires is mapped. Required aspects are set per category by eBay, so a template that publishes cleanly for one category can fail for the next.
07
VerifyProve it on a small batch before switching anything offTake a handful of SKUs and confirm price, quantity and status on eBay are what you expect, and that the listings report Synced rather than an error. Legacy is still doing the real work at this point, which is exactly why this is the cheapest moment to find a mistake.
08
Cut overMove listing sync across, then switch Legacy offTurn Sync Listings on for the new channel, let a full run finish clean, then turn Sync Listings off on Legacy. Do not leave both channels syncing the same listings for longer than that check: two channels pushing price and quantity to the same eBay listings produce conflicting updates and job failures on both.
09
Cut overMove orders across, Get Orders firstTurn Get Orders off on Legacy, schedule Get Orders on the new channel, and manually import any order that landed in the gap between the two. At least one Fulfillment Status must be selected or the job will not run at all. Then test Sync Orders on a real shipment before disabling it on Legacy: eBay needs both Carrier Name and Tracking Number, with the carrier code matching eBay exactly (
FedEx, not FedEx Ground).10
RetireRemove Legacy only when nothing is still waiting on itKeep Legacy connected until every open Legacy order has its tracking synced back to eBay: removing it earlier loses the tracking history for those orders. Once it is clear, delete the Legacy listings, then ask support to remove the Legacy channel itself.
Mapping: fields to know
Publishes mapped Flxpoint product data as new eBay listings via the Inventory API
| Field | Maps To: Notes |
|---|---|
| Title | Map using Field. Product name displayed on eBay. |
| Description | Map using Field. Product details on the listing page. If it is left empty, the product title is used. |
| Subtitle | Set to Don't Map to avoid the per-listing subtitle fee. |
| UPC | Map using Field. Required for many eBay categories. |
| VAT Percentage | Set using a static Value (e.g., 20) for regions that require tax compliance. |
| eBay Plus If Eligible | Optional eBay Plus enrollment (boolean): map or leave as Don't Map. |
Up to 10 Category Aspects (sub-aspects per category) can also be mapped in the template. Publishing requires valid leaf numeric Category IDs, all three business policy IDs, and a Merchant Location Key. Publish Listings can be scheduled or run manually.
Pushes price and quantity and links existing eBay listings to Flxpoint products by SKU, UPC or MPN
| Field | Maps To: Notes |
|---|---|
| SKU | → eBay Product SKU (Legacy) / eBay V2 Variant Link SKU (new eBay). Required: primary linking identifier. Using the Legacy field on a new eBay channel makes linking fail silently. |
| Price | → eBay Listing Price. Required. Sets the listing price on eBay. |
| Quantity | → eBay Available Quantity. Required. Subject to the Maximum Quantity display cap. |
| UPC | No mapping available on Sync & Link Listings. |
| MPN | No mapping available on Sync & Link Listings. |
Always run Link Listings before Sync Listings on first setup, and set the sync direction to Flxpoint → eBay. Only listings originally created through the Inventory API flow can be linked on the new eBay channel.
Imports new eBay orders into Flxpoint for processing and fulfillment
| Field | Maps To: Notes |
|---|---|
| Order ID | → Order: External Order ID. Required. Uniquely identifies the eBay order. |
| Full Name | → Shipping Address: Full Name. Required. |
| Address Line 1 | → Shipping Address: Street Address 1. Required. |
| Address Line 2 | → Shipping Address: Street Address 2. Optional. |
| City | → Shipping Address: City. Required. |
| State or Province | → Shipping Address: State Code. Required. |
| Postal Code | → Shipping Address: Post Code. Required. |
| Country Code | → Shipping Address: Country. Required. |
| Phone | → Shipping Address: Phone. Optional. |
| → Billing Address: Email. Optional. | |
| Total | → Order: Total. Required. Order total amount. |
| Tax Total | → Order: Tax Total. Optional. Summed from each line item's tax. |
| Shipping Total | → Order: Shipping Total. Optional. |
| Status | → Order: Status. Required. Tracks the order fulfillment status. |
| Order Item SKU | → Order Item: SKU. Required. |
| Order Item Quantity | → Order Item: Quantity. Required. |
| Order Item Price | → Order Item: Price. Required. Price per line item. |
| Payment Method | No mapping available on Get Orders. |
At least one Fulfillment Status must be selected or the job will not run. Confirm the Fetch Last X Days window covers the order dates you expect.
Sends shipment confirmations, carrier and tracking numbers back to eBay
| Field | Maps To: Notes |
|---|---|
| Carrier Name | → eBay: Carrier. Required. Must match eBay's accepted carrier codes exactly (e.g., FedEx, not FedEx Ground). |
| Tracking Number | → eBay: Tracking Number. Required. |
| Shipping Method | → eBay: Method. Optional (e.g., Ground). |
| Shipped At | → eBay: Shipped At. Recommended. Records the shipment date. |
| Note | → eBay: Note. Optional custom text sent with the tracking info: a single field; Note Header and Note Footer are not separately mappable. |
| Tracking URL | → eBay: Tracking URL. Optional link to the tracking page. |
eBay requires both Carrier Name and Tracking Number to display tracking. For partial shipments, also map Shipment Item SKU and Quantity.
Common issues
Products stuck in "Pending Publish": job finishes but shows no products to list
Usually a mapping-template issue. Verify the Category ID is a valid leaf numeric ID for your target eBay site, that all required fields (Title and UPC) are mapped, and that all three business policy IDs plus a Merchant Location Key are configured. Test with a single SKU first to isolate the cause before re-running the full job.
"Could not find any products eligible to be linked" when running Link Listings on new eBay
Three common causes: the mapping uses eBay Product SKU (Legacy) instead of eBay V2 Variant Link SKU; the listing is still linked to the Legacy channel and must be unlinked first; or the listing was not created through the Inventory API flow and must be re-published through Flxpoint before it can be managed.
Price and quantity not updating on eBay despite the sync job completing successfully
Run Link Listings before Sync Listings on first setup: sync cannot update listings that are not yet linked. Confirm the Price and Quantity fields are explicitly mapped in the Sync Listings template (unmapped fields are skipped silently), and that sync direction is Flxpoint → eBay, not the reverse.
Tracking not updating on eBay from dropship sources
Confirm the Sync Orders template maps both Carrier Name and Tracking Number: eBay requires both. Ensure the carrier name matches eBay's accepted carrier codes exactly (use
FedEx, not FedEx Ground). For partial shipments also map Shipment Item SKU and Quantity, and check the Sync Orders logs for carrier-mismatch errors."Exceeding 255 variants" error on a product with fewer than 255 actual variants
eBay counts variation combinations across all option dimensions, not just active SKUs. With multiple option types (e.g., size and color) the total permutations can exceed 255. Reduce the number of option values or split the listing into multiple separate products.
Connection test failing or integration returning 401/403 authentication errors
For the new eBay channel, open the operation, click Edit, go to Connect an Integration, open the connection and click Click here to generate a new refresh token to regenerate the OAuth token: tokens expire and need periodic renewal. For eBay Legacy, generate a new Auth Token in your eBay Developer account and update it in the connection settings. If you suspect rate limiting, wait 15–30 minutes and reduce scheduled job frequency.
Publish fails or shows incorrect categories despite mapping?
Verify your category data for hidden or invisible characters (like trailing spaces or non-printing characters) which can cause mapping failures. You can also use Mapping Sets to explicitly assign eBay Category IDs to Category 1 and Category 2 fields. If a publish fails, check the logs for the specific mapped category ID to ensure it matches a valid leaf category from the eBay category reference document, then retry the publish after cleaning the data.
Error: Invalid data in the Inventory Item Group. Missing name in the variation specifics or variation specifics set.
This error occurs when the product variation structure or option names (like Size or Color) are modified after an initial attempt to publish to eBay. Flxpoint may attempt to reuse existing option sets that no longer match the new structure. To resolve this, unpublish or delist the product from the eBay channel, ensure the outdated Inventory Item Groups are cleared in Flxpoint, and then republish the listing with the updated option names.
Sync Shipment fails with "External Listing ID is missing"
Flxpoint has no eBay listing ID recorded for the item being shipped, so it has nothing to attach the tracking to. This turns up during a Legacy to new eBay cutover when the order was imported on one channel while the listing is linked on the other. Confirm the listing is linked on the channel the order came from, run Link Listings on the new channel if it is not, then retry the shipment sync.
Publish fails: "Configured Category ID X requires aspect fields [...] but the following required aspects are missing"
The eBay category you mapped requires an aspect you have not mapped yet. Add it under the Category Aspects in the Publish Listings mapping template, where up to 10 can be mapped. Required aspects are set per category by eBay, so a template that publishes cleanly for one category can fail for another: check the failing category's requirements rather than the template as a whole. The category file for your site (eBay US, eBay Motors US or eBay Australia) lists the required aspects of every category.
Jobs failing on both eBay Legacy and the new eBay channel at the same time
Two channels syncing the same eBay listings both push their own price and quantity to it. During a migration, move one job type at a time and disable it on Legacy as soon as the new channel's equivalent runs clean, rather than leaving both scheduled.
Publish fails with category validation or missing item specifics?
eBay only allows listings under end (leaf) categories. If you are using a parent category ID like 'Gun Parts,' you must instead select a specific child category such as 'Rifle Parts' to avoid validation errors. Once a valid leaf category is selected, ensure all required item specifics for that category (such as Brand, Type, or For Gun Type) are mapped in your template, as these are mandatory for a successful publish.
Error: 'Invalid shipment tracking number or carrier' when syncing orders?
eBay rejected the carrier name or tracking number. Check that the Sync Orders template maps both Carrier Name and Tracking Number, and that the carrier matches eBay's accepted names exactly (for example FedEx, not FedEx Ground).
FAQs
Should I migrate from eBay Legacy to the new eBay integration?
Yes: the new eBay integration is the recommended path going forward because it uses eBay's latest APIs. Create the new channel alongside Legacy rather than replacing it, verify on a small batch, then retire Legacy one job at a time. Migrating from eBay Legacy above sets out the order to do it in.
Do I have to create new listings for the new eBay channel?
Only for the listings that cannot be linked. Start with Sync & Link Listings: it connects your existing live eBay listings to Flxpoint products, and those keep their eBay listing, history and item number. Anything the link job cannot match, typically listings created manually in Seller Hub or created through eBay Legacy on the Trading API, has to be republished through the new channel, which does create a new eBay listing. Run Link Listings first so you only republish what is genuinely left over.
Can I run eBay Legacy and the new eBay channel at the same time?
Yes, and you should while you migrate: that is what lets you verify the new channel without risking live listings and orders. What you should not do is leave both channels running the same job against the same listings. Move one job type at a time (Sync Listings, then Get Orders, then Sync Orders) and disable it on Legacy once the new channel's equivalent has run clean, otherwise the two push conflicting price and quantity updates and both start failing.
Do my Legacy pricing rules and mapping templates move over automatically?
No. The new eBay channel is a separate channel, so Pricing and Quantity Rules, Maximum Quantity, listing mapping templates, category mapping and job schedules all start empty and you rebuild them there. Rebuild them while Legacy is still live so you can compare the two side by side, and check the price the new channel calculates on a few variants before you turn on Sync Listings.
Why is Import Listings not available on my new eBay channel?
Import Listings is only supported on the eBay Legacy connection type. The new eBay integration does not support Import Listings, instead, use Sync & Link Listings to associate your existing eBay listings to products in Flxpoint. Note that linking only works for listings originally created through the Inventory API flow.
What is the difference between the SKU mapping for Legacy vs. new eBay?
For eBay Legacy, map Listing Variant SKU to eBay Product SKU. For the new eBay integration, map Listing Variant SKU to eBay V2 Variant Link SKU. Using the wrong field is one of the most common reasons linking fails silently when migrating to v2.
I closed the eBay setup wizard before finishing. How do I get back in?
The wizard runs as part of initial channel setup and may not be relaunchable once it has been closed or minimized. If you cannot get back into it, contact support to remove the partially configured channel, then add the channel again and complete the wizard in one sitting.
How do I remove the eBay Legacy channel once I am done?
First confirm nothing still depends on it: every open Legacy order should have its tracking synced back to eBay, because removing the channel loses that tracking history. Then delete the Legacy listings and ask support to remove the channel itself.
What does "existing quantity value is identical" mean during a sync?
It means the quantity Flxpoint sent already matches what is live on eBay, so eBay made no change. Flxpoint now marks those listings as Synced rather than raising an error, so no action is needed: your listings are already up to date.
How does Maximum Quantity work on eBay?
Maximum Quantity caps the quantity displayed on eBay regardless of actual stock. For example, if your inventory is 50 but Maximum Quantity is set to 5, buyers see 5 available. This is useful for high-velocity SKUs where stock fluctuates rapidly and reduces the risk of overselling during demand spikes. Configure it under Pricing and Quantity Rules in the channel settings.
Get Orders is not importing orders: what should I check?
At least one Fulfillment Status must be selected in Get Orders settings: if none is selected, the job will not run. Confirm the Fetch Last X Days window covers the order dates you expect, and verify the mapping template is saved with all required fields (Order ID, SKU, Quantity, Ship To Address) mapped.
Why does my eBay publish fail with 'Category is not mapped'?
Map Category ID as its own field in the eBay Publish Listings mapping template, with a valid eBay category ID, and map the category's required aspects separately as aspect fields. The publish fails with 'Category is not mapped' when Category ID is empty or not a valid eBay category.
What does the 'element cannot be mapped to a null key' error on eBay mean?
It means Link Listings found an eBay offer with no parent SKU and could not group it with the others. Make sure the eBay listing has a parent SKU, then link the listings again.