openapi: 3.0.0
info:
title: eBay Account Advertising_eligibility Offer API
description: The <b>Account API</b> gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information. <br><br>For details on the availability of the methods in this API, see <a href="/api-docs/sell/account/overview.html#requirements">Account API requirements and restrictions</a>.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.9.2
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/account/v1
tags:
- name: Offer
paths:
/bulk_create_offer:
post:
tags:
- Offer
description: 'This call creates multiple offers (up to 25) for specific inventory items on a specific eBay marketplace. Although it is not a requirement for the seller to create complete offers (with all necessary details) right from the start, eBay recommends that the seller provide all necessary details with this call since there is currently no bulk operation available to update multiple offers with one call. The following fields are always required in the request payload: <strong>sku</strong>, <strong>marketplaceId</strong>, and (listing) <strong>format</strong>. <br><br>Other information that will be required before a offer can be published are highlighted below: <ul><li>Inventory location</li> <li>Offer price</li> <li>Available quantity</li> <li>eBay listing category</li> <li>Referenced listing policy profiles to set payment, return, and fulfillment values/settings</li> </ul><p><span class="tablenote"><strong>Note:</strong> Though the <strong>includeCatalogProductDetails</strong> parameter is not required to be submitted in the request, the parameter defaults to <code>true</code> if omitted.</span><br><span class="tablenote"><b>Note:</b> In addition to the <code>authorization</code> header, which is required for all Inventory API calls, this call also requires the <code>Content-Type</code> and <code>Content-Language</code> headers. See the <a href="/api-docs/sell/inventory/resources/offer/methods/bulkCreateOffer#h3-request-headers">HTTP request headers</a> for more information.</span></p> <p>If the call is successful, unique <strong>offerId</strong> values are returned in the response for each successfully created offer. The <strong>offerId</strong> value will be required for many other offer-related calls. Note that this call only stages an offer for publishing. The seller must run either the <strong>publishOffer</strong>, <strong>bulkPublishOffer</strong>, or <strong>publishOfferByInventoryItemGroup</strong> call to convert offer(s) into an active single- or multiple-variation listing.</p><p>For those who prefer to create a single offer per call, the <strong>createOffer</strong> method can be used instead.</p>'
operationId: bulkCreateOffer
parameters:
- name: Content-Language
in: header
description: This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be <code>en-US</code> for English or <code>de-DE</code> for German.<br><br>For more information on the Content-Language header, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: Details of the offer for the channel
content:
application/json:
schema:
description: Details of the offer for the channel
$ref: '#/components/schemas/BulkEbayOfferDetailsWithKeys'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOfferResponse'
'207':
description: Multi-Status
'400':
description: Bad Request
x-response-codes:
errors:
'25702':
domain: API_INVENTORY
category: REQUEST
description: SKU {additionalInfo} is not available in the system
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid request. Invalid value for field {additionalInfo}
'25729':
domain: API_INVENTORY
category: REQUEST
description: The combination of SKU, marketplaceId and format should be unique.
'25730':
domain: API_INVENTORY
category: REQUEST
description: The number of offers in the request cannot exceed {additionalInfo}
'25735':
domain: API_INVENTORY
category: REQUEST
description: Invalid SKU, marketplaceId or format.
'25752':
domain: API_INVENTORY
category: REQUEST
description: listingStartDate provided is invalid.
'25755':
domain: API_INVENTORY
category: REQUEST
description: listingDuration is required for auction offer.
'25756':
domain: API_INVENTORY
category: REQUEST
description: Auction format is not permitted with a SKU that is part of an InventoryItemGroup.
'25757':
domain: API_INVENTORY
category: REQUEST
description: auctionStartPrice is required for auction offer.
'25758':
domain: API_INVENTORY
category: REQUEST
description: auctionStartPrice and auctionReservePrice are not supported for fixed price offer.
'25761':
domain: API_INVENTORY
category: REQUEST
description: Discount pricing is not applicable for auction offer.
'25762':
domain: API_INVENTORY
category: REQUEST
description: availableQuantity is not applicable for auction offer.
'25763':
domain: API_INVENTORY
category: REQUEST
description: quantityLimitPerBuyer is not applicable for auction offer.
'25764':
domain: API_INVENTORY
category: REQUEST
description: eBayPlusIfEligible is not applicable for auction offer.
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: Any System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
/bulk_publish_offer:
post:
tags:
- Offer
description: <span class="tablenote"><strong>Note:</strong> Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.</span><br>This call is used to convert unpublished offers (up to 25) into published offers, or live eBay listings. The unique identifier (<strong>offerId</strong>) of each offer to publish is passed into the request payload. It is possible that some unpublished offers will be successfully created into eBay listings, but others may fail. The response payload will show the results for each <strong>offerId</strong> value that is passed into the request payload. The <strong>errors</strong> and <strong>warnings</strong> containers will be returned for an offer that had one or more issues being published. <br><br>For those who prefer to publish one offer per call, the <strong>publishOffer</strong> method can be used instead. In the case of a multiple-variation listing, the <strong>publishOfferByInventoryItemGroup</strong> call should be used instead, as this call will convert all unpublished offers associated with an inventory item group into a multiple-variation listing.
operationId: bulkPublishOffer
parameters:
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: The base request of the <strong>bulkPublishOffer</strong> method.
content:
application/json:
schema:
description: The base request of the <strong>bulkPublishOffer</strong> method.
$ref: '#/components/schemas/BulkOffer'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BulkPublishResponse'
x-response-codes:
errors:
'25028':
domain: API_INVENTORY
category: REQUEST
description: '{field} is not applicable and has been dropped'
'25030':
domain: API_INVENTORY
category: REQUEST
description: '{field} is not applicable for the condition and has been dropped'
'25033':
domain: API_INVENTORY
category: REQUEST
description: Duplicate policy IDs found
'25037':
domain: API_INVENTORY
category: REQUEST
description: Item level Eco Participation Fee will be ignored
'25401':
domain: API_INVENTORY
category: APPLICATION
description: Invalid listing options removed. {additionalInfo}
'25402':
domain: API_INVENTORY
category: APPLICATION
description: System warning. {additionalInfo}
'25753':
domain: API_INVENTORY
category: REQUEST
description: listingStartDate is in the past or the offer is live. Value is not updated on the listing.
'207':
description: Multi-Status
'400':
description: Bad Request
x-response-codes:
errors:
'25002':
domain: API_INVENTORY
category: REQUEST
description: Any User error. {additionalInfo}
'25003':
domain: API_INVENTORY
category: REQUEST
description: Invalid price. {additionalInfo}
'25004':
domain: API_INVENTORY
category: REQUEST
description: Invalid quantity. {additionalInfo}
'25005':
domain: API_INVENTORY
category: REQUEST
description: Invalid category. {additionalInfo}
'25006':
domain: API_INVENTORY
category: REQUEST
description: Invalid listing option. {additionalInfo}
'25007':
domain: API_INVENTORY
category: REQUEST
description: Invalid Shipping policy information. {additionalInfo}
'25008':
domain: API_INVENTORY
category: REQUEST
description: Invalid Payment policy information. {additionalInfo}
'25009':
domain: API_INVENTORY
category: REQUEST
description: Invalid Return policy information. {additionalInfo}
'25011':
domain: API_INVENTORY
category: REQUEST
description: Invalid tax information. {additionalInfo}
'25012':
domain: API_INVENTORY
category: REQUEST
description: Invalid location. {additionalInfo}
'25013':
domain: API_INVENTORY
category: REQUEST
description: Invalid InventoryItemGroup information. {additionalInfo}
'25014':
domain: API_INVENTORY
category: REQUEST
description: Invalid pictures. {additionalInfo}
'25015':
domain: API_INVENTORY
category: REQUEST
description: Invalid picture URL. {additionalInfo}
'25016':
domain: API_INVENTORY
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'25017':
domain: API_INVENTORY
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'25018':
domain: API_INVENTORY
category: REQUEST
description: Incomplete account information. {additionalInfo}
'25019':
domain: API_INVENTORY
category: REQUEST
description: Cannot revise listing. {additionalInfo}
'25020':
domain: API_INVENTORY
category: REQUEST
description: Invalid package details. {additionalInfo}
'25021':
domain: API_INVENTORY
category: REQUEST
description: Invalid condition information. {additionalInfo}
'25022':
domain: API_INVENTORY
category: REQUEST
description: Invalid attribute. {fieldName}
'25023':
domain: API_INVENTORY
category: REQUEST
description: Invalid compatibility information. {additionalInfo}
'25026':
domain: API_INVENTORY
category: REQUEST
description: Selling limits exceeded. {additionalInfo}
'25029':
domain: API_INVENTORY
category: REQUEST
description: '{field} is required for this category.'
'25031':
domain: API_INVENTORY
category: REQUEST
description: '{field} is not valid and needs to be a number between {min} and {max}'
'25032':
domain: API_INVENTORY
category: REQUEST
description: '{field} is not valid'
'25034':
domain: API_INVENTORY
category: REQUEST
description: Only {max value} policies can be specified
'25035':
domain: API_INVENTORY
category: REQUEST
description: The specified policy is not found for the market place
'25036':
domain: API_INVENTORY
category: REQUEST
description: The policy(ies) {PolicyId} is not of type {PolicyEnum}
'25038':
domain: API_INVENTORY
category: REQUEST
description: '{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours'
'25039':
domain: API_INVENTORY
category: REQUEST
description: '{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours'
'25040':
domain: API_INVENTORY
category: REQUEST
description: '{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours'
'25041':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, maximum handling time must be {replaceable_value} business day(s).
'25042':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, free shipping must be provided.
'25043':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, returns must be accepted.
'25044':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, refund must be provided as Money Back.
'25045':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, the minimum time you'll accept returns must be {replaceable_value} days.
'25046':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, seller must pay the cost for return shipping.
'25047':
domain: API_INVENTORY
category: REQUEST
description: Seller is not eligible to use Refurbished Item Condition
'25048':
domain: API_INVENTORY
category: REQUEST
description: Seller is not eligible to use Refurbished Item Condition in this Category
'25049':
domain: API_INVENTORY
category: REQUEST
description: Seller is not eligible to use Refurbished Item Condition for the selected Brand
'25050':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Title.
'25051':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, {replaceable_value} cannot be used in the Subtitle
'25052':
domain: API_INVENTORY
category: REQUEST
description: When listing an item with Refurbished condition, at least {replaceable_value} images must be provided
'25076':
domain: API_INVENTORY
category: REQUEST
description: '{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s).'
'25077':
domain: API_INVENTORY
category: REQUEST
description: Duplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored.
'25078':
domain: API_INVENTORY
category: REQUEST
description: Hazmat structure incorrect for {replaceable_value}.
'25079':
domain: API_INVENTORY
category: REQUEST
description: Repair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place.
'25080':
domain: API_INVENTORY
category: REQUEST
description: The value of the {0} field is invalid. Field must not exceed {replaceable_value} characters.
'25081':
domain: API_INVENTORY
category: REQUEST
description: Hazardous material information incomplete. Your listing must include pictograms, hazardous statements and a signal word.
'25083':
domain: API_INVENTORY
category: REQUEST
description: Energy efficiency image is missing. Image is required with image description.
'25084':
domain: API_INVENTORY
category: REQUEST
description: The listing must have both an energy efficiency label and a product information sheet.
'25085':
domain: API_INVENTORY
category: REQUEST
description: Economic Operator address information is incomplete. When providing the address, please provide the company name, street, city, state, postal code and country.
'25086':
domain: API_INVENTORY
category: REQUEST
description: The URL provided must be an eBay Picture Service URL.
'25087':
domain: API_INVENTORY
category: REQUEST
description: Economic Operator information is incomplete. Please provide the company name.
'25088':
domain: API_INVENTORY
category: REQUEST
description: The email address provided is formatted incorrectly.
'25601':
domain: API_INVENTORY
category: REQUEST
description: Invalid attribute. {fieldName}
'25604':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid offerId
'25713':
domain: API_INVENTORY
category: REQUEST
description: 'This Offer is not available : {additionalInfo}.'
'25730':
domain: API_INVENTORY
category: REQUEST
description: The number of offers in the request cannot exceed {additionalInfo}.
'25731':
domain: API_INVENTORY
category: REQUEST
description: OfferId should be unique in the request.
'25732':
domain: API_INVENTORY
category: REQUEST
description: Offers associated with SKUs that are part of a variation group cannot be published using this endpoint.
'25752':
domain: API_INVENTORY
category: REQUEST
description: listingStartDate provided is invalid.
'25760':
domain: API_INVENTORY
category: REQUEST
description: shipToLocationAvailability quantity insufficient to create auction listings.
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: Any System error. {additionalInfo}
'25025':
domain: API_INVENTORY
category: APPLICATION
description: Concurrent access of Inventory or InventoryItemGroup. Please try again later
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
/offer:
get:
tags:
- Offer
description: This call retrieves all existing offers for the specified SKU value. The seller has the option of limiting the offers that are retrieved to a specific eBay marketplace, or to a listing format.<br><br><span class="tablenote"><strong>Note:</strong> At this time, the same SKU value can not be offered across multiple eBay marketplaces, so the <strong>marketplace_id</strong> query parameter currently does not have any practical use for this call.</span><br><span class="tablenote"><strong>Note:</strong> The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, <b>getOffers</b> will return two offers. Otherwise, only one offer will be returned.</span><br>The <code>authorization</code> header is the only required HTTP header for this call. See the <strong>HTTP request headers</strong> section for more information.
operationId: getOffers
parameters:
- name: format
in: query
description: This enumeration value sets the listing format for the offers being retrieved. This query parameter will be passed in if the seller only wants to see offers in a specified listing format, such as <code>FIXED_PRICE</code>.
required: false
schema:
type: string
- name: limit
in: query
description: The value passed in this query parameter sets the maximum number of records to return per page of data. Although this field is a string, the value passed in this field should be a positive integer value. If this query parameter is not set, up to 100 records will be returned on each page of results.
required: false
schema:
type: string
- name: marketplace_id
in: query
description: The unique identifier of the eBay marketplace. This query parameter will be passed in if the seller only wants to see the product's offers on a specific eBay marketplace.<br><br><span class="tablenote"><strong>Note:</strong> At this time, the same SKU value can not be offered across multiple eBay marketplaces, so the <strong>marketplace_id</strong> query parameter currently does not have any practical use for this call.</span>
required: false
schema:
type: string
- name: offset
in: query
description: The value passed in this query parameter sets the page number to retrieve. Although this field is a string, the value passed in this field should be a integer value equal to or greater than <code>0</code>. The first page of records has a value of <code>0</code>, the second page of records has a value of <code>1</code>, and so on. If this query parameter is not set, its value defaults to <code>0</code>, and the first page of records is returned.
required: false
schema:
type: string
- name: sku
in: query
description: 'The seller-defined SKU value is passed in as a query parameter. All offers associated with this product are returned in the response. <br><br><span class="tablenote"><strong>Note:</strong> The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, <b>getOffers</b> will return two offers. Otherwise, only one offer will be returned.</span><br>Use the <a href="/api-docs/sell/inventory/resources/inventory_item/methods/getInventoryItems">getInventoryItems</a> method to retrieve SKU values.<br><br><strong>Max length</strong>: 50.'
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Offers'
'400':
description: Bad Request
x-response-codes:
errors:
'25706':
domain: API_INVENTORY
category: REQUEST
description: You have provided invalid pagination values. {additionalInfo}.
'25709':
domain: API_INVENTORY
category: REQUEST
description: Invalid value for {fieldName}. {additionalInfo}
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: A system error has occurred. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory.readonly
- https://api.ebay.com/oauth/api_scope/sell.inventory
post:
tags:
- Offer
description: 'This call creates an offer for a specific inventory item on a specific eBay marketplace. It is up to the sellers whether they want to create a complete offer (with all necessary details) right from the start, or sellers can provide only some information with the initial <strong>createOffer</strong> call, and then make one or more subsequent <strong>updateOffer</strong> calls to complete the offer and prepare to publish the offer. Upon first creating an offer, the following fields are required in the request payload: <strong>sku</strong>, <strong>marketplaceId</strong>, and (listing) <strong>format</strong>. <br><br>Other information that will be required before an offer can be published are highlighted below. These settings are either set with <strong>createOffer</strong>, or they can be set with a subsequent <strong>updateOffer</strong> call: <ul><li>Inventory location</li> <li>Offer price</li> <li>Available quantity</li> <li>eBay listing category</li> <li>Referenced listing policy profiles to set payment, return, and fulfillment values/settings</li> </ul> <p><span class="tablenote"><strong>Note:</strong> Though the <strong>includeCatalogProductDetails</strong> parameter is not required to be submitted in the request, the parameter defaults to <code>true</code> if omitted.</span></p><span class="tablenote"><b>Note:</b> In addition to the <code>authorization</code> header, which is required for all Inventory API calls, this call also requires the <code>Content-Type</code> and <code>Content-Language</code> headers. See the <a href="/api-docs/sell/inventory/resources/offer/methods/createOffer#h3-request-headers">HTTP request headers</a> for more information.</span><p>If the call is successful, a unique <strong>offerId</strong> value is returned in the response. This value will be required for many other offer-related calls. Note that this call only stages an offer for publishing. The seller must run the <strong>publishOffer</strong> call to convert the offer to an active eBay listing.</p><p>For those who prefer to create multiple offers (up to 25 at a time) with one call, the <strong>bulkCreateOffer</strong> method can be used.</p>'
operationId: createOffer
parameters:
- name: Content-Language
in: header
description: This header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be <code>en-US</code> for English or <code>de-DE</code> for German.<br><br>For more information on the Content-Language header, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: Details of the offer for the channel
content:
application/json:
schema:
description: Details of the offer for the channel
$ref: '#/components/schemas/EbayOfferDetailsWithKeys'
required: true
responses:
'201':
description: Created
headers:
Content-Language:
schema:
type: string
description: This response header sets the natural language that will be provided in the field values of the response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/OfferResponse'
'400':
description: Bad Request
x-response-codes:
errors:
# --- truncated at 32 KB (212 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-offer-api-openapi.yml