For more than two decades, e-commerce developers and multi-channel resellers have relied on eBay’s XML-based Trading API (AddItem, ReviseItem, GetItem, GetOrders), the Post-Order API v2, and Platform Notifications to list inventory, synchronize stock, and process orders.
With the publication of eBay’s official Modern APIs Migration Guide, eBay is executing the largest architectural overhaul in its developer history: retiring monolithic XML calls in favor of the GraphQL Listing API, domain-focused REST Sell & Buy APIs, and consolidated Notification API webhook topics.
Whether you maintain custom eBay software or use a local-first cross-listing workstation like Pivotal Reseller, understanding these changes—and the 2026 hard decommissioning deadlines—is critical to keeping your listings live and your inventory synchronized.
---
Executive Summary: What Is Changing in eBay’s Modern API Stack?
eBay’s migration consolidates three legacy technology stacks into modern JSON/REST and GraphQL services:
1. Traditional SOA/XML Trading API → GraphQL Listing API & REST Microservices:
Listing creation, revision, ending, and seller inventory search move to the typed GraphQL Listing API (createListing, updateListing, bulkUpdateInventory, endListing, sellerListings, sellerListingSearch).
2. Order & Checkout Splitting → Order API, Item Commitment API & Purchase Quote API:
eBay now strictly separates paid orders (Order API v1) from unpaid buyer commitments (Item Commitment API v1) and pre-payment combined shipping invoices (Purchase Quote API v1).
3. Post-Order API v2 Retirement → Unified Order & Commitment Sub-Resources:
Cancellations, returns, and Item Not Received (INR) inquiries move out of the standalone /post-order/v2/ namespace directly into the REST Order API and Item Commitment API, while standalone Case calls are retired.
4. Platform Notifications → Notification API Topics:
Dozens of granular XML notification events (ItemListed, ItemRevised, ItemClosed, BestOffer, FixedPriceTransaction) are grouped into structured JSON webhook topics (LISTING, ORDER_CONFIRMATION, OFFER_ACTIVITY, NEW_MESSAGE) with explicit reason and activityType payloads.
---
Hard 2026 Decommissioning Deadlines You Must Hit First
While several next-generation endpoints (including the GraphQL Listing API, Order API v1, and Message API v1) are currently in Limited Release, eBay has announced mandatory 2026 decommissioning dates for core catalog and taxonomy XML calls:
| Legacy XML / SOA API Call | Hard Decommission Date | Modern REST API Replacement | Action Required |
|---|---|---|---|
GetCategories | April 15, 2026 | Commerce Taxonomy API (getCategoryTree, getCategorySubtree, getCategorySuggestions) | Migrate category trees & use the open-source eBay Taxonomy SDK |
GetCategory2CS | April 15, 2026 | Commerce Taxonomy API (getItemAspectsForCategory, fetchItemAspects) | Replace legacy characteristics sets with category item aspects |
GetCategoryFeatures | June 4, 2026 | Sell Metadata API (getItemConditionPolicies, getListingStructurePolicies, getNegotiatedPricePolicies) | Query per-policy REST endpoints instead of monolithic XML feature dumps |
findProducts / getProductDetails | August 17, 2026 | Commerce Catalog API (product_summary/search, getProduct) | Switch product catalog lookups to eBay’s REST Catalog API |
---
1. Listing Management: Migrating from XML Trading API to the GraphQL Listing API
For seller tools, the centerpiece of the Modern APIs Migration Guide is the shift from AddItem, ReviseItem, RelistItem, EndItem, and GetItem to the GraphQL Listing API.
Architectural Comparison: Trading API vs. GraphQL Listing API
| Topic | Legacy XML Trading API | Modern GraphQL Listing API | Developer Migration Action |
|---|---|---|---|
| Data Model | Organized around a monolithic Item XML container | Explicit GraphQL schema types for listings, items, and variations | Map existing listing fields to typed GraphQL input objects |
| Request Format | Operation-specific XML bodies (AddFixedPriceItemRequest, etc.) | Single GraphQL endpoint using typed operations and JSON variables | Replace XML string builders with GraphQL queries/mutations and schema validation |
| Listing-Level SKU | Optional; only tracked when InventoryTrackingMethod = SKU | Optional, but defaults to inventoryTrackingBySku = true, enforcing seller-wide uniqueness across all eBay marketplaces | Audit reused SKUs across listings and international sites; assign unique eBay SKUs per listing |
| Variation-Child SKU | Conditional on InventoryTrackingMethod | Mandatory for every variation and must be unique within the listing | Generate and validate a distinct child SKU for every size/color variation |
| Idempotency Key | Not required by AddItem | Required by createListing | Generate deterministic UUID/hash idempotency keys for safe network retries |
| Quantity on Creation | Often defaulted to 1 if omitted | Must be supplied explicitly (quantity never defaults) | Always pass explicit integer quantities on every item and variation |
| Mutation Response | Fixed XML response payload per call | Caller defines a GraphQL selection set choosing which fields to return | Request only the fields (listingId, status, warnings) your app needs |
| Read Coverage | GetItem returned almost every buyer and seller attribute | sellerListings and sellerListingSearch return listing-creation fields | Audit GetItem consumers; use Browse API for public buyer-facing views |
The New SKU Uniqueness Rule (inventoryTrackingBySku = true)
One of the most common pitfalls when migrating to the GraphQL Listing API is global SKU uniqueness. When you provide a listing-level SKU on createListing, inventoryTrackingBySku defaults to true. That establishes a strict 1:1 mapping between your SKU and an eBay listingId across all eBay marketplaces.
Crucially, listing on a different country site (such as EBAY_US vs. EBAY_UK) does not create a separate SKU namespace. If your warehouse or reselling database uses one internal SKU for multiple active eBay listings (for example, multi-lot listings or regional listings), you must maintain an internal-to-eBay SKU mapping table:
| Internal Master SKU | eBay Listing-Level SKU | eBay Marketplace | eBay Listing ID |
|---|---|---|---|
VTG-BROOCH-042 | VTG-BROOCH-042-US-1 | EBAY_US | 186492019481 |
VTG-BROOCH-042 | VTG-BROOCH-042-US-2 | EBAY_US | 186492019912 |
VTG-BROOCH-042 | VTG-BROOCH-042-UK-1 | EBAY_GB | 186492020504 |
(Note: While eBay provides a temporary migration flag inventoryTrackingBySku: false for legacy integrations with duplicate SKUs, eBay has announced that inventoryTrackingBySku is slated for future deprecation—so building 1:1 SKU mapping now is essential.)
Legacy Trading Calls to GraphQL Listing Operations
| Legacy Trading XML Call | Modern GraphQL / REST Replacement | Implementation Notes |
|---|---|---|
AddItem / AddFixedPriceItem / AddItems | createListing (GraphQL Listing API) | Supports single-item and multi-variation listings (FIXED_PRICE or AUCTION). |
VerifyAddItem / VerifyAddFixedPriceItem | Retired (No 1:1 replacement) | Validate payloads against the GraphQL schema and test in the eBay Sandbox environment before production cutover. |
ReviseItem / ReviseFixedPriceItem | updateListing (GraphQL Listing API) | Performs full or partial updates on an active listing using listingId or unique SKU. |
ReviseInventoryStatus | bulkUpdateInventory or updateListing (GraphQL Listing API) | Use bulkUpdateInventory to rapidly sync price and quantity across up to 4 SKUs/listings per call. |
RelistItem / RelistFixedPriceItem | createListing (GraphQL Listing API) | Retrieve the ended listing via sellerListings, then submit a fresh createListing mutation. |
EndItem / EndFixedPriceItem / EndItems | endListing (GraphQL Listing API) | Ends an active listing by listingId or unique listing-level SKU. |
GetItem (Seller view) / GetSellerList / GetMyeBaySelling | sellerListings & sellerListingSearch (GraphQL Listing API) | Use sellerListings when you know the listingId or SKU; use sellerListingSearch for filtered pagination. |
UploadSiteHostedPictures | createImageFromFile / createImageFromUrl (Commerce Media API) | Upload high-resolution listing photos and Video (createVideo / uploadVideo) via REST before calling createListing. |
---
2. Order Management: Separating Paid Orders, Unpaid Item Commitments & Purchase Quotes
In the legacy XML GetOrders and GetOrderTransactions workflow, eBay returned both paid orders (ready to ship) and unpaid checkouts (such as an auction winner or an accepted Best Offer where the buyer hasn't paid yet) in the same XML structure.
eBay’s modern REST architecture splits the post-commit lifecycle into three dedicated APIs:
| Lifecycle Stage | Modern eBay REST API | Key Methods | What It Represents |
|---|---|---|---|
| 1. Unpaid Commitment | Item Commitment API v1 | getItemCommitments, getItemCommitment | Buyer won an auction or committed to buy (FIXED_PRICE without immediate pay), but payment has not cleared. |
| 2. Pre-Payment Invoice / Quote | Purchase Quote API v1 | initiatePurchaseQuote, getPurchaseQuote | Replaces legacy SendInvoice. Buyer requests a combined shipping total (BUYER_REQUESTED_PURCHASE_QUOTE) across one or more item commitments. |
| 3. Paid Order & Fulfillment | Order API v1 | getOrders, getOrder, createShippingFulfillment, issueOrderRefund | Buyer has completed checkout and payment has cleared. Ready for label creation, tracking upload (CompleteSale replacement), or partial/full refunds. |
Why This Matters for Multi-Channel Auto-Delisting and Accounting
In Pivotal Reseller v0.1.9, separating inventory reservation from realized revenue prevents two classic reseller headaches:
1. Preventing Double-Sales Without Corrupting Schedule C Accounting: When a buyer commits to an item (Item Commitment), your cross-listed inventory on Mercari, Poshmark, Depop, and Vinted should be paused or delisted so you never double-sell—but your Profit & Loss Statement and Fee Calculator (try our live 2026 Fee Calculator here) should only book gross sales and shipping label costs once the paid Order is confirmed.
2. Automated Shipping Policy Tiers: When creating listings or calculating combined quotes, Pivotal Reseller v0.1.9 automatically assigns weight-based shipping policies (Flat Rate 1 under 8 oz through Flat Rate 4 over 32 oz) and flags any guessed package weights with a red-glow To-Do alert before an order ever ships.
---
3. Retiring Post-Order API v2: Cancellations, Inquiries & Returns
Historically, developers had to authenticate differently and call /post-order/v2/cancellation/, /post-order/v2/return/, /post-order/v2/inquiry/, and /post-order/v2/casemanagement/ using non-standard IAF tokens.
In the Modern APIs Migration, the entire Post-Order API v2 is replaced by standard OAuth 2.0 REST resources directly inside the Order API v1 and Item Commitment API v1:
| Post-Order Workflow | Legacy Post-Order v2 Calls | Modern REST API Replacement |
|---|---|---|
| Paid Order Cancellations | POST /post-order/v2/cancellation / approve / reject / search | Order API v1: initiateOrderCancellation, respondToOrderCancellation, getOrderCancellations, getOrderCancellation |
| Unpaid Commitment Cancellations | Handled via unpaid item settings or Post-Order cancellation | Item Commitment API v1: initiateItemCommitmentCancellation, getItemCommitmentCancellations |
| Item Not Received (INR) Inquiries | POST /post-order/v2/inquiry/ (provide_shipment_info, provide_refund, escalate) | Order API v1: respondToOrderInquiry (supports refund, shipment tracking, or message), escalateOrderInquiry, getOrderInquiries |
| Order Returns & RMAs | POST /post-order/v2/return/ (decide, issue_refund, send_shipping_label, file) | Order API v1: respondToOrderReturn, escalateOrderReturn, uploadOrderReturnAttachment, submitOrderReturnAttachment, getOrderReturns |
| Legacy Case Management | /post-order/v2/casemanagement/* & Trading GetUserDisputes | Retired: Once an Inquiry or Return is escalated (escalateOrderInquiry / escalateOrderReturn), eBay Customer Support handles resolution directly on-platform. |
---
4. Account Management, Combined Shipping Rules & Communication APIs
Account API v1 & v2: Business Policies and Combined Shipping Rules
- Business Policies (
ReturnPolicy,PaymentPolicy,FulfillmentPolicy): Managed via the Sell Account API v1 and required for all listings created through the GraphQL Listing API. - Combined Shipping Discounts (
SetShippingDiscountProfilesReplacement): Migrates to Sell Account API v2 viagetCombinedShippingRules,updateCombinedShippingRules, andupdateShippingRuleAdjustment. - Store Categories (
GetStore/SetStoreCategoriesReplacement): Migrates to the Sell Stores API (getStore,getStoreCategories,addStoreCategory,renameStoreCategory,moveStoreCategory,deleteStoreCategory). - User Identity (
GetUserReplacement): Migrates to the Commerce Identity API (getUser).
Conversation-Based Message API & Photo-Capable Feedback API
- Message API v1 (Replaces
GetMyMessages,GetMemberMessages,AddMemberMessageAAQToPartner): Organizes all buyer-seller and eBay-to-member messages into threaded Conversations (getConversations,getMessages,sendMessage,updateConversations,bulkUpdateConversation). - Feedback API v1 (Replaces
GetFeedback,LeaveFeedback,RespondToFeedback): AddsgetFeedback,getFeedbackRatingSummary,leaveFeedback,respondToFeedback,deleteFeedbackResponse, anduploadFeedbackImage(supporting up to 5 photos on buyer feedback). - Offer API v1 & Negotiation API (Replaces
GetBestOffers&RespondToBestOffer): Separates buyer-initiated Best Offers (getBuyerOffers,respondToBuyerOfferin the Offer API) from seller-initiated discount offers to interested watchers (findEligibleItems,sendOfferToInterestedBuyersin the Negotiation API).
---
5. Platform Notifications to Modern Notification API Topics
Legacy XML Platform Notifications required maintaining SOAP/XML listener endpoints for dozens of separate event names. The modern Commerce Notification API consolidates events into pub/sub Notification Topics:
| Legacy Platform Notification Event | Modern Notification API Topic | Key Payload Discriminator |
|---|---|---|
ItemListed | LISTING | reason = CREATED |
ItemRevised | LISTING | reason = UPDATED |
ItemClosed | LISTING | reason = ENDED |
FixedPriceTransaction / ItemSold | ORDER_CONFIRMATION + LISTING | Fires ORDER_CONFIRMATION when checkout payment clears |
BestOffer / BestOfferPlaced / CounterOfferReceived | OFFER_ACTIVITY | OfferType (BUYER_OFFER, BUYER_COUNTER_OFFER, SELLER_COUNTER_OFFER) + OfferStatus |
BidReceived / OutBid | AUCTION_ACTIVITY | AuctionActivity = BID_RECEIVED or OUTBID |
EndOfAuction / AuctionCheckoutComplete | AUCTION_ENDED | Sent to seller and bidders immediately when auction closes |
CheckoutBuyerRequestsTotal | BUYER_REQUESTED_PURCHASE_QUOTE | Buyer requested combined shipping total on item commitments |
BuyerCancelRequested | ORDER_CANCELLATION_ACTIVITY / ITEM_COMMITMENT_CANCELLATION_ACTIVITY / PURCHASE_QUOTE_CANCELLATION_ACTIVITY | activityType = CANCELLATION_REQUESTED |
OrderInquiryReminderForEscalation | ORDER_INQUIRY_ACTIVITY | activityType = SELLER_RESPONSE_REMINDER |
ReturnRefundOverdue / ReturnSellerInfoOverdue | ORDER_RETURN_ACTIVITY | activityType = SELLER_RESPONSE_REMINDER + sellerAvailableActions |
AskSellerQuestion / MyMessagesM2MMessage | NEW_MESSAGE | Covers buyer-to-seller, seller-to-buyer, and eBay system messages |
FeedbackLeft / FeedbackReceived | FEEDBACK_LEFT / FEEDBACK_RECEIVED | Triggered when line-item feedback is recorded |
---
Developer Migration Checklist for 2026
If you are migrating an existing eBay integration or auditing your reselling software stack, work through these five steps in order:
1. Eliminate April–August 2026 Decommissioned Calls Immediately:
Replace GetCategories and GetCategory2CS with the Commerce Taxonomy API (decommissions April 15, 2026), GetCategoryFeatures with the Sell Metadata API (decommissions June 4, 2026), and findProducts with the Commerce Catalog API (decommissions August 17, 2026).
2. Audit Your SKU Namespace Before Enabling GraphQL createListing:
Ensure every variation child has a SKU, and ensure every listing-level SKU is globally unique across all eBay marketplaces (inventoryTrackingBySku = true).
3. Add Deterministic Idempotency Keys & Explicit Quantities:
Never rely on default quantities (Quantity = 1 is gone) and generate a persistent idempotency key per listing creation attempt.
4. Decouple Item Commitments from Paid Orders:
Update your order ingestion pipeline so unpaid auction wins and offers are tracked via getItemCommitments, while shipping labels, accounting ledgers, and tax reports consume paid orders from getOrders.
5. Consolidate Webhook Listeners onto Notification API Topics:
Replace XML SOAP listeners with HTTPS JSON webhook destinations subscribed to LISTING, ORDER_CONFIRMATION, OFFER_ACTIVITY, and NEW_MESSAGE.
---
Built for the Modern Multi-Channel Era: Try Pivotal Reseller v0.1.9
We engineered Pivotal Reseller from day one around a local-first SQLite inventory vault that separates your internal master SKU from marketplace-specific listing IDs, automates 4-tier weight-based shipping policy assignment (Flat Rate 1–4), and alerts you with red-glow To-Do checks whenever cross-listing data needs human verification.