GET/offer
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.
Note: At this time, the same SKU value can not be offered across multiple eBay marketplaces, so the marketplace_id query parameter currently does not have any practical use for this call.
Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers. Otherwise, only one offer will be returned.
The authorization
header is the only required HTTP header for this call. See the HTTP request headers section for more information.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com
root URI with api.sandbox.ebay.com
URI parameters
Parameter | Type | Description |
---|---|---|
sku | string | The seller-defined SKU value is passed in as a query parameter. All offers associated with this product are returned in the response. Note: The same SKU can be offered through an auction and a fixed-price listing concurrently. If this is the case, getOffers will return two offers. Otherwise, only one offer will be returned. Use the getInventoryItems method to retrieve SKU values. Max length: 50. Occurrence: Required |
marketplace_id | MarketplaceEnum | 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. Note: At this time, the same SKU value can not be offered across multiple eBay marketplaces, so the marketplace_id query parameter currently does not have any practical use for this call. Occurrence: Optional |
format | FormatTypeEnum | 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 FIXED_PRICE . Occurrence: Optional |
limit | string | 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. Occurrence: Optional |
offset | string | 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 0 . The first page of records has a value of 0 , the second page of records has a value of 1 , and so on. If this query parameter is not set, its value defaults to 0 , and the first page of records is returned. Occurrence: Optional |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization
HTTP header for authentication authorization.
All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/sell.inventory.readonly
https://api.ebay.com/oauth/api_scope/sell.inventory
See OAuth access tokens for more information.
Request payload
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
Output container/field | Type | Description |
---|---|---|
href | string | This is the URL to the current page of offers. Occurrence: Always |
limit | integer | This integer value is the number of offers that will be displayed on each results page. Occurrence: Always |
next | string | This is the URL to the next page of offers. This field will only be returned if there are additional offers to view. Occurrence: Conditional |
offers | array of EbayOfferDetailsWithAll | This container is an array of one or more of the seller's offers for the SKU value that is passed in through the required sku query parameter. Occurrence: Always |
offers.availableQuantity | integer | This integer value indicates the quantity of the inventory item (specified by the sku value) that will be available for purchase by buyers shopping on the eBay site specified in the marketplaceId field. Occurrence: Conditional |
offers.categoryId | string | The unique identifier of the primary eBay category that the inventory item is listed under. This field is always returned for published offers, but is only returned if set for unpublished offers. Occurrence: Conditional |
offers.charity | Charity | This container is returned if a charitable organization will receive a percentage of sale proceeds for each sale generated by the listing. This container consists of the charityId field to identify the charitable organization, and the donationPercentage field that indicates the percentage of the sales proceeds that will be donated to the charitable organization. Occurrence: Conditional |
offers.charity.charityId | string | The eBay-assigned unique identifier of the charitable organization that will receive a percentage of the sales proceeds. The charitable organization must be reqistered with the PayPal Giving Fund in order to receive sales proceeds through eBay listings. Occurrence: Conditional |
offers.charity.donationPercentage | string | This field is the percentage of the purchase price that the charitable organization (identified in the charityId field) will receive for each sale that the listing generates. This field is conditionally required if a seller is planning on donating a percentage of the sale proceeds to a charitable organization. This numeric value can range from 10 to 100, and in any 5 (percent) increments in between this range (e.g. Occurrence: Conditional |
offers.extendedProducerResponsibility | ExtendedProducerResponsibility | This container is used to provide the eco-participation fee for a product. Use the getExtendedProducerResponsibilityPolicies method of the Sell Metadata API to retrieve categories that support eco-participation fee for a specified marketplace. Occurrence: Conditional |
offers.extendedProducerResponsibility.ecoParticipationFee | Amount | This is the fee paid for new items to the eco-organization (for example, "eco-organisme" in France). It is a contribution to the financing of the elimination of the item responsibly. Occurrence: Conditional |
offers.extendedProducerResponsibility.ecoParticipationFee.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.extendedProducerResponsibility.ecoParticipationFee.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.extendedProducerResponsibility.producerProductId | string | Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on. Occurrence: Conditional |
offers.extendedProducerResponsibility.productDocumentationId | string | Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on. Occurrence: Conditional |
offers.extendedProducerResponsibility.productPackageId | string | Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on. Occurrence: Conditional |
offers.extendedProducerResponsibility.shipmentPackageId | string | Note: THIS FIELD IS DEPRECATED AND NO LONGER SUPPORTED. For sellers selling on the eBay France Marketplace, Extended Producer Responsibility ID fields are no longer set at the listing level. Instead, sellers must provide these IDs for each applicable category in their My eBay accounts. The URL will be based on the seller's home/registration site, and will use this pattern: https://accountsettings./epr-fr. Sellers based in the US will use https://accountsettings.ebay.com/epr-fr, sellers based in France will use https://accountsettings.ebay.fr/epr-fr, and so on. Occurrence: Conditional |
offers.format | FormatTypeEnum | This enumerated value indicates the listing format of the offer. Occurrence: Always |
offers.hideBuyerDetails | boolean | This field is returned as Occurrence: Always |
offers.includeCatalogProductDetails | boolean | This field indicates whether or not eBay product catalog details are applied to a listing. A value of Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to 'true' if omitted. Occurrence: Always |
offers.listing | ListingDetails | For published offers, this container is always returned in the getOffer and getOffers calls, and includes the eBay listing ID associated with the offer, the status of the listing, and the quantity sold through the listing. The listing container is not returned at all for unpublished offers. Occurrence: Conditional |
offers.listing.listingId | string | The unique identifier of the eBay listing that is associated with the published offer. Occurrence: Conditional |
offers.listing.listingOnHold | boolean | Indicates if a listing is on hold due to an eBay policy violation. If a listing is put on hold, users are unable to view the listing details, the listing is hidden from search, and all attempted purchases, offers, and bids for the listing are blocked. eBay, however, gives sellers the opportunity to address violations and get listings fully reinstated. A listing will be ended if a seller does not address a violation, or if the violation can not be rectified. If a listing is fixable, the seller should be able to view the listing details and this boolean will be returned as true. Once a listing is fixed, this boolean will no longer be returned. Occurrence: Conditional |
offers.listing.listingStatus | ListingStatusEnum | The enumeration value returned in this field indicates the status of the listing that is associated with the published offer. Occurrence: Conditional |
offers.listing.soldQuantity | integer | This integer value indicates the quantity of the product that has been sold for the published offer. Occurrence: Conditional |
offers.listingDescription | string | The description of the eBay listing that is part of the unpublished or published offer. This field is always returned for published offers, but is only returned if set for unpublished offers. Occurrence: Conditional |
offers.listingDuration | ListingDurationEnum | This field indicates the number of days that the listing will be active. Occurrence: Always |
offers.listingPolicies | ListingPolicies | This container indicates the listing policies that are applied to the offer. Listing policies include business policies, custom listing policies, and fields that override shipping costs, enable eBay Plus eligibility, or enable the Best Offer feature. Occurrence: Always |
offers.listingPolicies.bestOfferTerms | BestOffer | This container is used if the seller would like to support the Best Offer feature on their listing. To enable the Best Offer feature, the seller will have to set the bestOfferEnabled field to Occurrence: Conditional |
offers.listingPolicies.bestOfferTerms.autoAcceptPrice | Amount | This is the price at which Best Offers are automatically accepted. If a buyer submits a Best Offer that is equal to or above this value, the offer is automatically accepted on behalf of the seller. This field is only applicable if the bestOfferEnabled value is set to Occurrence: Conditional |
offers.listingPolicies.bestOfferTerms.autoAcceptPrice.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.bestOfferTerms.autoAcceptPrice.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.bestOfferTerms.autoDeclinePrice | Amount | This is the price at which Best Offers are automatically declined. If a buyer submits a Best Offer that is equal to or below this value, the offer is automatically declined on behalf of the seller. This field is only applicable if the bestOfferEnabled value is set to Occurrence: Conditional |
offers.listingPolicies.bestOfferTerms.autoDeclinePrice.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.bestOfferTerms.autoDeclinePrice.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.bestOfferTerms.bestOfferEnabled | boolean | This field indicates whether or not the Best Offer feature is enabled for the listing. A seller can enable the Best Offer feature for a listing as long as the category supports the Best Offer feature. Occurrence: Conditional |
offers.listingPolicies.eBayPlusIfEligible | boolean | This field is included in an offer and set to Occurrence: Conditional |
offers.listingPolicies.fulfillmentPolicyId | string | This unique identifier indicates the fulfillment business policy that will be used once an offer is published and converted to an eBay listing. This fulfillment business policy will set all fulfillment-related settings for the eBay listing. Important!Publish offer note: This field is required before an offer can be published to create an active listing. Occurrence: Conditional |
offers.listingPolicies.paymentPolicyId | string | This unique identifier indicates the payment business policy that will be used once an offer is published and converted to an eBay listing. This payment business policy will set all payment-related settings for the eBay listing. Important!Publish offer note: This field is required before an offer can be published to create an active listing. Occurrence: Conditional |
offers.listingPolicies.productCompliancePolicyIds | array of string | This field contains the array of unique identifiers indicating the seller-created global product compliance policies that will be used once an offer is published and converted to a listing. Occurrence: Conditional |
offers.listingPolicies.regionalProductCompliancePolicies | RegionalProductCompliancePolicies | A comma-delimited list of unique identifiers indicating the seller-created country-specific product compliance policies that that will be used once an offer is published and converted to a listing.
For example, if a seller offers products in the UK, Germany, and Italy, each of which requires custom product compliance information, up to 18 policies (i.e., 6 policies x 3 countries,) may be included with each offer.Note: Product compliance policies that apply to all countries to which a seller ships are specified using productCompliancePolicyIds. Occurrence: Conditional |
offers.listingPolicies.regionalProductCompliancePolicies.countryPolicies | array of CountryPolicy | The array of country-specific product compliance policies to be used by an offer when it is published and converted to a listing. Occurrence: Conditional |
offers.listingPolicies.regionalProductCompliancePolicies.countryPolicies.country | CountryCodeEnum | The two-letter ISO 3166-1 country code identifying the country to which the policy or policies specified in the corresponding policyIds array will apply. Occurrence: Conditional |
offers.listingPolicies.regionalProductCompliancePolicies.countryPolicies.policyIds | array of string | An array of custom policy identifiers that apply to the country specified by listingPolicies.regionalTakeBackPolicies.countryPolicies.country.
Occurrence: Conditional |
offers.listingPolicies.regionalTakeBackPolicies | RegionalTakeBackPolicies | The list of unique identifiers indicating the seller-created country-specific take-back policies that will be used once an offer is published and converted to a listing. The law in some countries may require sellers to take back a used product when the buyer buys a new product.
Note: Take-back policies that apply to all countries to which a seller ships are specified using takeBackPolicyId. Occurrence: Conditional |
offers.listingPolicies.regionalTakeBackPolicies.countryPolicies | array of CountryPolicy | The array of country-specific take-back policies to be used by an offer when it is published and converted to a listing. Occurrence: Conditional |
offers.listingPolicies.regionalTakeBackPolicies.countryPolicies.country | CountryCodeEnum | The two-letter ISO 3166-1 country code identifying the country to which the policy or policies specified in the corresponding policyIds array will apply. Occurrence: Conditional |
offers.listingPolicies.regionalTakeBackPolicies.countryPolicies.policyIds | array of string | An array of custom policy identifiers that apply to the country specified by listingPolicies.regionalTakeBackPolicies.countryPolicies.country.
Occurrence: Conditional |
offers.listingPolicies.returnPolicyId | string | This unique identifier indicates the return business policy that will be used once an offer is published and converted to an eBay listing. This return business policy will set all return policy settings for the eBay listing. Important!Publish offer note: This field is required before an offer can be published to create an active listing. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides | array of ShippingCostOverride | This container is used if the seller wishes to override the shipping costs or surcharge for one or more domestic or international shipping service options defined in the fulfillment listing policy. To override the costs of a specific domestic or international shipping service option, the seller must know the priority/order of that shipping service in the fulfillment listing policy. The name of a shipping service option can be found in the shippingOptions.shippingServices.shippingServiceCode field of the fulfillment policy, and the priority/order of that shipping service option is found in the shippingOptions.shippingServices.sortOrderId field. Both of these values can be retrieved by searching for that fulfillment policy with the getFulfillmentPolicies or getFulfillmentPolicyByName calls of the Account API. The shippingCostOverrides.priority value should match the shippingOptions.shippingServices.sortOrderId in order to override the shipping costs for that shipping service option. The seller must also ensure that the shippingServiceType value is set to Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.additionalShippingCost | Amount | The dollar value passed into this field will override the additional shipping cost that is currently set for the applicable shipping service option. The "Additional shipping cost" is the cost to ship each additional identical product to the buyer using the corresponding shipping service. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.additionalShippingCost.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.additionalShippingCost.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.priority | integer | The integer value input into this field, along with the shippingServiceType value, sets which domestic or international shipping service option in the fulfillment policy will be modified with updated shipping costs. Specifically, the shippingCostOverrides.shippingServiceType value in a createOffer or updateOffer call must match the shippingOptions.optionType value in a fulfillment listing policy, and the shippingCostOverrides.priority value in a createOffer or updateOffer call must match the shippingOptions.shippingServices.sortOrderId value in a fulfillment listing policy. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.shippingCost | Amount | The dollar value passed into this field will override the shipping cost that is currently set for the applicable shipping service option. This value will be the cost to ship one item to the buyer using the corresponding shipping service. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.shippingCost.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.shippingCost.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.shippingServiceType | ShippingServiceTypeEnum | This enumerated value indicates whether the shipping service specified in the priority field is a domestic or an international shipping service option. To override the shipping costs for a specific domestic shipping service in the fulfillment listing policy, this field should be set to Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.surcharge | Amount | Note: DO NOT USE THIS FIELD. Shipping surcharges for shipping service options can no longer be set with fulfillment business policies. To set a shipping surcharge for a shipping service option, only the Shipping rate tables tool in My eBay can be used. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.surcharge.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.shippingCostOverrides.surcharge.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.listingPolicies.takeBackPolicyId | string | This unique identifier indicates the seller-created global take-back policy that will be used once an offer is published and converted to a listing. Occurrence: Conditional |
offers.listingStartDate | string | This timestamp is the date/time (in UTC format) that the seller set for the scheduled listing. With the scheduled listing feature, the seller can set a time in the future that the listing will become active, instead of the listing becoming active immediately after a publishOffer call. Occurrence: Conditional |
offers.lotSize | integer | This field is only applicable and returned if the listing is a lot listing. A lot listing is a listing that has multiple quantity of the same product. An example would be a set of four identical car tires. The integer value in this field is the number of identical items being sold through the lot listing. Occurrence: Conditional |
offers.marketplaceId | MarketplaceEnum | This enumeration value is the unique identifier of the eBay site on which the offer is available, or will be made available. Occurrence: Always |
offers.merchantLocationKey | string | The unique identifier of the inventory location. This identifier is set up by the merchant when the inventory location is first created with the createInventoryLocation call. Once this value is set for an inventory location, it can not be modified. To get more information about this inventory location, the getInventoryLocation method can be used, passing in this value at the end of the call URI. Occurrence: Conditional |
offers.offerId | string | The unique identifier of the offer. This identifier is used in many offer-related calls, and it is also used in the bulkUpdatePriceQuantity call. Occurrence: Always |
offers.pricingSummary | PricingSummary | This container shows the listing price for the product offer, and if applicable, the settings for the Minimum Advertised Price and Strikethrough Pricing features. The Minimum Advertised Price feature is only available on the US site. Strikethrough Pricing is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites. Occurrence: Always |
offers.pricingSummary.auctionReservePrice | Amount | This field indicates the lowest price at which the seller is willing to sell an item through an auction listing. Note that setting a Reserve Price will incur a listing fee of $5 or 7.5% of the Reserve Price, whichever is greater. The minimum fee is $5. Occurrence: Conditional |
offers.pricingSummary.auctionReservePrice.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.auctionReservePrice.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.auctionStartPrice | Amount | This field indicates the minimum bidding price for the auction. The bidding starts at this price. Occurrence: Conditional |
offers.pricingSummary.auctionStartPrice.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.auctionStartPrice.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.minimumAdvertisedPrice | Amount | This container is needed if the Minimum Advertised Price (MAP) feature will be used in the offer. Minimum Advertised Price (MAP) is an agreement between suppliers (or manufacturers (OEM)) and the retailers (sellers) stipulating the lowest price an item is allowed to be advertised at. Sellers can only offer prices below this price through the use of other discounts. The MAP feature is only available to eligible US sellers. This field will be ignored if the seller and or the listing is not eligible for the MAP feature. Occurrence: Conditional |
offers.pricingSummary.minimumAdvertisedPrice.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.minimumAdvertisedPrice.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.originallySoldForRetailPriceOn | SoldOnEnum | This field is needed if the Strikethrough Pricing (STP) feature will be used in the offer. This field indicates that the product was sold for the price in the originalRetailPrice field on an eBay site, or sold for that price by a third-party retailer. When using the createOffer or updateOffer calls, the seller will pass in a value of Occurrence: Conditional |
offers.pricingSummary.originalRetailPrice | Amount | This container is needed if the Strikethrough Pricing (STP) feature will be used in the offer. The dollar value passed into this field indicates the original retail price set by the manufacturer (OEM). eBay does not maintain or validate the value supplied here by the seller. The dollar value in this field should always be more than the dollar value in the price container. This field and the originallySoldForRetailPriceOn field are only applicable if the seller and listing are eligible to use the Strikethrough Pricing feature, a feature which is limited to the US (core site and Motors), UK, Germany, Canada (English and French versions), France, Italy, and Spain sites. Compare the originalRetailPrice and the dollar value in the price field to determine the amount of savings to the buyer. This Original Retail Price will have a strikethrough line through for a marketing affect. Occurrence: Conditional |
offers.pricingSummary.originalRetailPrice.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.originalRetailPrice.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.price | Amount | This is the listing price of the product. A listing price must be specified before publishing an offer, but it is possible to create an offer without a price. Important!Publish offer note: This container and its two child fields (currency and value) are required before an offer can be published to create an active listing. Occurrence: Conditional |
offers.pricingSummary.price.currency | string | A three-digit string value representing the type of currency being used. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.price.value | string | A string representation of a dollar value expressed in the currency specified in the currency field. Both the value and currency fields are required/always returned when expressing prices. Occurrence: Conditional |
offers.pricingSummary.pricingVisibility | MinimumAdvertisedPriceHandlingEnum | This field is needed if the Minimum Advertised Price (MAP) feature will be used in the offer. This field is only applicable if an eligible US seller is using the Minimum Advertised Price (MAP) feature and a minimumAdvertisedPrice has been specified. The value set in this field will determine whether the MAP price is shown to a prospective buyer prior to checkout through a pop-up window accessed from the View Item page, or if the MAP price is not shown until the checkout flow after the buyer has already committed to buying the item. To show the MAP price prior to checkout, the seller will set this value to Occurrence: Conditional |
offers.quantityLimitPerBuyer | integer | This field is only applicable and set if the seller wishes to set a restriction on the purchase quantity of an inventory item per seller. If this field is set by the seller for the offer, then each distinct buyer may purchase up to, but not exceed the quantity in this field. So, if this field's value is Occurrence: Conditional |
offers.regulatory | Regulatory | This container is used by the seller to provide regulatory information. Occurrence: Conditional |
offers.regulatory.documents | array of Document | This container provides a collection of regulatory documents associated with the listing. Occurrence: Conditional |
offers.regulatory.documents.documentId | string | The unique identifier of a regulatory document associated with the listing. Occurrence: Conditional |
offers.regulatory.economicOperator | EconomicOperator | Important! Economic Operator is being decommissioned and being replaced by the manufacturer and responsiblePersons containers. Economic Operator related fields should no longer be used for the create or update methods. As it is currently still supported, Economic Operator-related fields will be returned if applicable for the getOffer method. Economic Operator and its related fields will be decommissioned on October 21, 2024. This container provides Economic Operator (EO) information about the manufacturer and/or supplier of the item. The EO is a corporate entity that is related to, has some responsibility for, the product being listed for sale. For additional information, see What is an economic operator? Occurrence: Conditional |
offers.regulatory.economicOperator.addressLine1 | string | The first line of the registered Economic Operator's street address. Occurrence: Conditional |
offers.regulatory.economicOperator.addressLine2 | string | The second line, if any, of the registered Economic Operator's street address. This field is not always used, but can be used for 'Suite Number' or 'Apt Number'. Occurrence: Conditional |
offers.regulatory.economicOperator.city | string | The city of the registered Economic Operator's street address. Occurrence: Conditional |
offers.regulatory.economicOperator.companyName | string | The company name of the registered Economic Operator. Occurrence: Conditional |
offers.regulatory.economicOperator.country | CountryCodeEnum | The two-letter ISO 3166-1 standard abbreviation of the country of the registered Economic Operator's address. Occurrence: Conditional |
offers.regulatory.economicOperator.email | string | The registered Economic Operator's business email address. Occurrence: Conditional |
offers.regulatory.economicOperator.phone | string | The registered Economic Operator's business phone number. Occurrence: Conditional |
offers.regulatory.economicOperator.postalCode | string | The postal code of the registered Economic Operator's street address. Occurrence: Conditional |
offers.regulatory.economicOperator.stateOrProvince | string | The state or province of the registered Economic Operator's street address. Occurrence: Conditional |
offers.regulatory.energyEfficiencyLabel | EnergyEfficiencyLabel | This container provides information about the energy efficiency for certain durable goods. Occurrence: Conditional |
offers.regulatory.energyEfficiencyLabel.imageDescription | string | A brief verbal summary of the information included on the Energy Efficiency Label for an item. Occurrence: Conditional |
offers.regulatory.energyEfficiencyLabel.imageURL | string | The URL to the Energy Efficiency Label image that is applicable to an item. Occurrence: Conditional |
offers.regulatory.energyEfficiencyLabel.productInformationSheet | string | The URL to the Product Information Sheet that provides complete manufacturer-provided efficiency information about an item. Occurrence: Conditional |
offers.regulatory.hazmat | Hazmat | This container is used by the seller to provide hazardous material information for the listing.
Note: Hazmat information is not required for all categories. Use the getRegulatoryPolicies method of the Metadata API to return metadata on the eBay categories that recommend or require Hazmat-related fields. Occurrence: Conditional |
offers.regulatory.hazmat.component | string | This field is used by the seller to provide component information for the listing. For example, component information can provide the specific material of Hazmat concern. Occurrence: Conditional |
offers.regulatory.hazmat.pictograms | array of string | An array of comma-separated string values listing applicable pictogram code(s) for Hazard Pictogram(s). Occurrence: Conditional |
offers.regulatory.hazmat.signalWord | string | This field sets the signal word for hazardous materials in the listing. Occurrence: Conditional |
offers.regulatory.hazmat.statements | array of string | An array of comma-separated string values specifying applicable statement code(s) for hazard statement(s) for the listing. Occurrence: Conditional |
offers.regulatory.manufacturer | Manufacturer | This container provides information about the manufacturer of the item. Occurrence: Conditional |
offers.regulatory.manufacturer.addressLine1 | string | The first line of the product manufacturer's street address. Occurrence: Conditional |
offers.regulatory.manufacturer.addressLine2 | string | The second line of the product manufacturer's street address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'. Occurrence: Conditional |
offers.regulatory.manufacturer.city | string | The city of the product manufacturer's street address. Occurrence: Conditional |
offers.regulatory.manufacturer.companyName | string | The company name of the the product manufacturer. Occurrence: Conditional |
offers.regulatory.manufacturer.country | CountryCodeEnum | This defines the list of valid country codes, adapted from http://www.iso.org/iso/country_codes, ISO 3166-1 country code. List elements take the following form to identify a two-letter code with a short name in English, a three-digit code, and a three-letter code: For example, the entry for Japan includes Japan, 392, JPN. Short codes provide uniform recognition, avoiding language-dependent country names. The number code is helpful where Latin script may be problematic. Not all listed codes are universally recognized as countries, for example: code AQ is Antarctica, 010, ATA Occurrence: Conditional |
offers.regulatory.manufacturer.email | string | The product manufacturer's business email address. Occurrence: Conditional |
offers.regulatory.manufacturer.phone | string | The product manufacturer's business phone number. Occurrence: Conditional |
offers.regulatory.manufacturer.postalCode | string | The postal code of the product manufacturer's street address. Occurrence: Conditional |
offers.regulatory.manufacturer.stateOrProvince | string | The state or province of the product manufacturer's street address. Occurrence: Conditional |
offers.regulatory.productSafety | ProductSafety | This container is used to provide product safety information for the listing. Two elements are required to complete the Product Safety section for a listing: pictograms and statements. The component element is optional. Occurrence: Conditional |
offers.regulatory.productSafety.component | string | This field is used by the seller to provide product safety component information for the listing. For example, component information can include specific warnings related to product safety, such as 'Tipping hazard'. Occurrence: Conditional |
offers.regulatory.productSafety.pictograms | array of string | An array of comma-separated string values used to provide product safety pictogram(s) for the listing. Occurrence: Conditional |
offers.regulatory.productSafety.statements | array of string | An array of comma-separated string values used to provide product safety statement(s) for the listing. Occurrence: Conditional |
offers.regulatory.repairScore | number | This field represents the repair index for the listing.
Note: Repair score is not applicable to all categories. Use the getExtendedProducerResponsibilityPolicies method of the Metadata API to see where repair score is applicable. Occurrence: Conditional |
offers.regulatory.responsiblePersons | array of ResponsiblePerson | This container provides information about the EU-based Responsible Persons or entities associated with the listing. Occurrence: Conditional |
offers.regulatory.responsiblePersons.addressLine1 | string | The first line of the Responsible Person's street address. Occurrence: Conditional |
offers.regulatory.responsiblePersons.addressLine2 | string | The second line of the Responsible Person's address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'. Occurrence: Conditional |
offers.regulatory.responsiblePersons.city | string | The city of the Responsible Person's street address. Occurrence: Conditional |
offers.regulatory.responsiblePersons.companyName | string | The name of the the Responsible Person or entity. Occurrence: Conditional |
offers.regulatory.responsiblePersons.country | CountryCodeEnum | This defines the list of valid country codes, adapted from http://www.iso.org/iso/country_codes, ISO 3166-1 country code. List elements take the following form to identify a two-letter code with a short name in English, a three-digit code, and a three-letter code: For example, the entry for Japan includes Japan, 392, JPN. Short codes provide uniform recognition, avoiding language-dependent country names. The number code is helpful where Latin script may be problematic. Not all listed codes are universally recognized as countries, for example: code AQ is Antarctica, 010, ATA Occurrence: Conditional |
offers.regulatory.responsiblePersons.email | string | The Responsible Person's email address. Occurrence: Conditional |
offers.regulatory.responsiblePersons.phone | string | The Responsible Person's business phone number. Occurrence: Conditional |
offers.regulatory.responsiblePersons.postalCode | string | The postal code of the Responsible Person's street address. Occurrence: Conditional |
offers.regulatory.responsiblePersons.stateOrProvince | string | The state of province of the Responsible Person's street address. Occurrence: Conditional |
offers.regulatory.responsiblePersons.types | array of ResponsiblePersonTypeEnum | The type(s) associated with the Responsible Person or entity. Occurrence: Conditional |
offers.secondaryCategoryId | string | The unique identifier for a secondary category. This field is applicable if the seller decides to list the item under two categories. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. A fee may be charged when adding a secondary category to a listing. Occurrence: Conditional |
offers.sku | string | This is the seller-defined SKU value of the product in the offer. Occurrence: Always |
offers.status | OfferStatusEnum | The enumeration value in this field specifies the status of the offer - either Occurrence: Always |
offers.storeCategoryNames | array of string | This container is returned if the seller chose to place the inventory item into one or two eBay store categories that the seller has set up for their eBay store. The string value(s) in this container will be the full path(s) to the eBay store categories, as shown below: Occurrence: Conditional |
offers.tax | Tax | This container is only returned if a sales tax table, a Value-Added Tax (VAT) rate, and/or a tax exception category code was applied to the offer. Only Business Sellers can apply VAT to their listings. It is possible that the applyTax field will be included with a value of Occurrence: Conditional |
offers.tax.applyTax | boolean | When set to Important! In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.
For complete information about using sales-tax tables, refer to Establishing sales-tax tables. Note that a seller can enable the use of a sales-tax table, but if a sales-tax rate is not specified for the buyer's tax jurisdiction, sales tax will not be applied to the order. When a thirdPartyTaxCategory value is used, applyTax must also be set to true .This field will be returned by getOffer and getOffers if set for the offer. For additional information, refer to Taxes and import charges. Occurrence: Conditional |
offers.tax.thirdPartyTaxCategory | string | The tax exception category code. If this field is used, sales tax will also apply to a service/fee, and not just the item price. This is to be used only by sellers who have opted into sales tax being calculated by a sales tax calculation vendor. If you are interested in becoming a tax calculation vendor partner with eBay, contact developer-relations@ebay.com. One supported value for this field is Occurrence: Conditional |
offers.tax.vatPercentage | number | This value is the Value Add Tax (VAT) rate for the item, if any. When a VAT percentage is specified, the item's VAT information appears on the listing's View Item page. In addition, the seller can choose to print an invoice that includes the item's net price, VAT percent, VAT amount, and total price. Since VAT rates vary depending on the item and on the user's country of residence, a seller is responsible for entering the correct VAT rate; it is not calculated by eBay. Occurrence: Conditional |
prev | string | This is the URL to the previous page of offers. This field will only be returned if there are previous offers to view. Occurrence: Conditional |
size | integer | This integer value indicates the number of offers being displayed on the current page of results. This number will generally be the same as the limit value if there are additional pages of results to view. Occurrence: Always |
total | integer | This integer value is the total number of offers that exist for the specified SKU value. Based on this number and on the limit value, the seller may have to toggle through multiple pages to view all offers. Occurrence: Always |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
Status | Meaning |
---|---|
200 | Success |
400 | Bad Request |
404 | Not Found |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
25001 | API_INVENTORY | APPLICATION | A system error has occurred. {additionalInfo} |
25706 | API_INVENTORY | REQUEST | You have provided invalid pagination values. {additionalInfo}. |
25709 | API_INVENTORY | REQUEST | Invalid value for {fieldName}. {additionalInfo} |
Warnings
This call has no warnings.
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Retrieves Offers for an Inventory Item
This call will retrieve offers for a specific inventory item associated with the seller's account.
Input
The seller is looking for offers for the inventory item specified in the sku query parameter. Offers associated with this inventory item will be retrieved.
GEThttps://api.ebay.com/sell/inventory/v1/offer?sku=3***********5
Output
One offer is retrieved for inventory item with a SKU value of 3***********5
.
The retrieved offer is in the published state, and there is an active eBay listing on the eBay US site associated with this offer. The item ID, status, and quantity sold for this listing is shown in the listing container. There is a quantity of 70 available for purchase.