Listings & Offers

In eBay, an Offer is what makes a product publicly visible on the marketplace. It connects an inventory item (SKU) to a marketplace, category, price, and policies. A product can exist in the Inventory API without being listed — it only becomes a public listing when an offer is created and published.

API endpoints

Method	Path	Description	API Reference
POST	`/api/v1/products/listings`	Create and publish a single offer	ref
POST	`/api/v1/products/listings/batch`	Create multiple offers in batch	ref
POST	`/api/v2/products/listings/publish`	Publish an existing unpublished offer	ref
POST	`/api/v2/products/listings/migrate`	Migrate legacy listings to Inventory API	ref
GET	`/api/v1/products/listings`	Get all listings (Trading API)	ref
GET	`/api/v1/products/listings/{id}`	Get a single listing with offers	ref
PUT	`/api/v1/listings/{offerId}`	Update an existing offer	ref

Creating and publishing a single offer (v1)

POST /api/v1/products/listings

This endpoint creates the offer and immediately attempts to publish it in a single call. The product (SKU) must already exist in the Inventory API before you can create an offer for it — see Products & Variants.

Before using this endpoint, ensure your account meets all Getting Started prerequisites (Payoneer, seller program enrollment, policies, and at least one location).

Full request payload:

POST /api/v1/products/listings
{
  "listing": {
    "sku": "MY-PRODUCT-001",
    "marketplaceId": "EBAY_US",
    "format": "FIXED_PRICE",
    "availableQuantity": 10,
    "categoryId": "9355",
    "listingDescription": "Full HTML or plain-text description of the product.",
    "listingDuration": "GTC",
    "listingPolicies": {
      "fulfillmentPolicyId": "6196932000",
      "paymentPolicyId": "6196934000",
      "returnPolicyId": "6196936000"
    },
    "merchantLocationKey": "WAREHOUSE-US-01",
    "pricingSummary": {
      "price": {
        "currency": "USD",
        "value": "29.99"
      }
    }
  }
}

Field	Required	Notes
`sku`	Yes	Must match a product in the Inventory API
`marketplaceId`	Yes	e.g. `EBAY_US` — use underscore format
`format`	Yes	Use `"FIXED_PRICE"`
`categoryId`	Yes	eBay category ID for your marketplace. Use `GET /api/v2/categories` to find the right one → ref
`listingDescription`	Yes	Accepts HTML. Shown on the eBay listing page
`listingDuration`	Yes	Use `"GTC"` (Good Till Cancelled) for fixed-price listings
`listingPolicies.fulfillmentPolicyId`	Yes	Must belong to the same `marketplaceId`
`listingPolicies.paymentPolicyId`	Yes	Must belong to the same `marketplaceId`
`listingPolicies.returnPolicyId`	Yes	Must belong to the same `marketplaceId`
`merchantLocationKey`	Yes	Location created via `POST /api/v2/locations`
`pricingSummary.price`	Yes	`currency` and `value` as string
`availableQuantity`	No	Defaults to inventory quantity on the product if omitted

A successful response returns an offerId. Save this ID — you will need it to update the offer later.

→ API Reference

Publishing an existing offer (v2)

POST /api/v2/products/listings/publish

Publishes an offer that was already created but not yet published — for example, after using POST /api/v1/products/listings/batch to bulk-create offers. Requires the offerId and marketplaceId.

POST /api/v2/products/listings/publish
{
  "listing": {
    "offerId": "OFFER_ID_HERE",
    "marketplaceId": "EBAY_US"
  }
}

→ API Reference

Updating an offer (v1)

PUT /api/v1/listings/{offerId}

The offerId is returned when you create an offer. You can also retrieve it by calling GET /api/v1/products/listings/{listingId} — the offerId appears inside the Offers array in the response.

Use case	How
Update price	Send `pricingSummary.price` in the offer payload
Update quantity	Include `inventory: true` in the payload
Update description, policies, duration	Send the full offer object with the updated fields

Price lives on the Offer, not on the product. Sending a price update to PUT /api/v2/products/{sku} will return 200 OK but will not change the price on eBay. Always update price via PUT /api/v1/listings/{offerId}.

Example — update price:

PUT /api/v1/listings/{offerId}
{
  "listing": {
    "marketplaceId": "EBAY_US",
    "pricingSummary": {
      "price": {
        "currency": "USD",
        "value": "24.99"
      }
    }
  }
}

→ API Reference

Getting listings (v1)

GET /api/v1/products/listings

Uses eBay's Trading API (GetSellerList) internally. Returns listings from the last 30 days by default.

Limits:

Max time range: 120 days
Max 300 requests per 15-second window

→ API Reference

Getting a single listing (v1)

GET /api/v1/products/listings/{listingId}

Returns full item details via Trading API (GetItem) plus the associated offers fetched from the Inventory API. For variant products, returns one offer per variant SKU in the Offers array.

→ API Reference

Creating offers in batch (v1)

POST /api/v1/products/listings/batch

Creates multiple offers in a single request using eBay's bulk_create_offer. This is the required third step when publishing a variant product group — see Products & Variants → Complete flow: create and publish a variant group.

→ API Reference