eBay Inventory API: from ERP catalog to listing (SKU → listing)

The eBay Inventory API is the part of the Sell API that manages products, prices and availability with a model close to ERP and warehouse systems: you think in terms of SKUs, not individual listings. Understanding this model is the step that makes an integration maintainable rather than fragile.

The four-level model

The Inventory API separates the concept of a product from the concept of a listing. The flow is:

1. SKU: the unique identifier coming from your back office;
2. Inventory item: the inventory product, with attributes, images and quantity;
3. Offer: the commercial offer (price, marketplace, category, policies);
4. Listing: the live listing created when you publish the offer.

The split between inventory item and offer is valuable: the same product can have different offers on different marketplaces, and a stock update touches the inventory item without rebuilding the offer.

The key calls

Operation	Call
Create/update product	createOrReplaceInventoryItem
Create the offer	createOffer
Publish the listing	publishOffer
Update stock only	createOrReplaceInventoryItem (availability field)
Bulk uploads	bulkCreateOrReplaceInventoryItem

Variants and groups

For products with sizes and colours you use the inventory item group: individual SKUs remain inventory products, while the group joins them into a single listing with variations. It is essential to map aspects (e.g. size, colour) correctly onto the attributes the category requires, otherwise publication fails.

Incremental updates

The advantage of the model is that a price or quantity change does not require republishing everything. So it pays to:

• distinguish events: new product, stock update, price update, withdrawal;
• send only deltas, not the whole catalog on every sync;
• use bulk operations for high volume, respecting size limits.

Mapping the ERP catalog

The critical part is not the call but the data transformation. The back office speaks its own language (internal codes, merchandise categories), eBay another (aspects, conditions, marketplace categories). A mapping layer converts and validates before publishing: product identifiers (GTIN/EAN), mandatory attributes, compliant images, descriptions.

Architecture on Azure

A reliable catalog sync on Microsoft Azure can include a component that captures changes in the ERP, a mapping step that prepares payloads, and workers that call the Inventory API with retries and rate-limit handling, recording the outcome and the diff for each SKU.

Payload example: item, offer and stock delta

The first submission creates or replaces the inventory item. I also store the normalized payload so a publication error can be reproduced without reading the ERP again.

PUT /sell/inventory/v1/inventory_item/TSHIRT-BLK-M
{
  "availability": {
    "shipToLocationAvailability": { "quantity": 15 }
  },
  "condition": "NEW",
  "product": {
    "title": "Black t-shirt size M",
    "description": "100% cotton, regular fit",
    "aspects": { "Size": ["M"], "Color": ["Black"] },
    "imageUrls": ["https://cdn.example.com/tshirt-black-m.jpg"]
  }
}

The commercial offer stays separate. Price changes more often than description, so I treat it as a different event.

POST /sell/inventory/v1/offer
{
  "sku": "TSHIRT-BLK-M",
  "marketplaceId": "EBAY_IT",
  "format": "FIXED_PRICE",
  "availableQuantity": 15,
  "pricingSummary": { "price": { "value": "24.90", "currency": "EUR" } },
  "listingPolicies": {
    "fulfillmentPolicyId": "123",
    "paymentPolicyId": "456",
    "returnPolicyId": "789"
  },
  "categoryId": "15687",
  "merchantLocationKey": "WAREHOUSE_IT"
}

For a later stock delta I do not recreate the offer: I update only availability.shipToLocationAvailability.quantity on the inventory item and log previous/new quantity for audit.

Common mistakes

• rebuilding the whole listing on every stock update;
• not handling variation groups and creating duplicate listings;
• forgetting product identifiers required by the category;
• sending the entire catalog instead of just deltas, saturating the API.

Conclusion

The Inventory API rewards those who adopt its SKU model: inventory products, offers and listings kept separate, incremental updates and upfront validation. It is the foundation for aligning the ERP catalog with eBay at scale. Official documentation: eBay Inventory API — Overview.