Skip to main content

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

GET https://api.ebay.com/sell/inventory/v1/offer?

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

ParameterTypeDescription
skustringThe 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_idMarketplaceEnumThe 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

formatFormatTypeEnumThis 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

limitstringThe 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

offsetstringThe 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

{ /* Offers */
"href" : "string",
"limit" : "integer",
"next" : "string",
"offers" : [
{ /* EbayOfferDetailsWithAll */
"sku" : "string",
}
],
"prev" : "string",
"size" : "integer",
}

Response fields

Output container/fieldTypeDescription
hrefstring

This is the URL to the current page of offers.

Occurrence: Always

limitinteger

This integer value is the number of offers that will be displayed on each results page.

Occurrence: Always

nextstring

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

offersarray 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.

Note: Currently, the Inventory API does not support the same SKU across multiple eBay marketplaces.
Max Occurs: 25

Occurrence: Always

offers.availableQuantityinteger

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.categoryIdstring

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.charityCharity

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.charityIdstring

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.

This field is conditionally required if a seller is planning on donating a percentage of the sale proceeds to a charitable organization.

The eBay-assigned unique identifier of a charitable organization can be found using the getCharityOrgs method of the Charity API. In the getCharityOrgs response, this unique identifier is shown in the charityOrgId field.

Occurrence: Conditional

offers.charity.donationPercentagestring

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. 10, 15, 20...95,... 100). The seller would pass in 10 for 10 percent, 15 for 15 percent, 20 for 20 percent, and so on, all the way to 100 for 100 percent.

Occurrence: Conditional

offers.extendedProducerResponsibilityExtendedProducerResponsibility

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.ecoParticipationFeeAmount

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.

Minimum: 0.0

Occurrence: Conditional

offers.extendedProducerResponsibility.ecoParticipationFee.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.extendedProducerResponsibility.ecoParticipationFee.valuestring

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.producerProductIdstring

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.productDocumentationIdstring

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.productPackageIdstring

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.shipmentPackageIdstring

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.formatFormatTypeEnum

This enumerated value indicates the listing format of the offer.

Occurrence: Always

offers.hideBuyerDetailsboolean

This field is returned as true if the private listing feature has been enabled for the offer. Sellers may want to use this feature when they believe that a listing's potential bidders/buyers would not want their obfuscated user IDs (and feedback scores) exposed to other users.

This field is always returned even if not explicitly set in the offer. It defaults to false, so will get returned as false if seller does not set this feature with a 'Create' or 'Update' offer method.

Occurrence: Always

offers.includeCatalogProductDetailsboolean

This field indicates whether or not eBay product catalog details are applied to a listing. A value of true indicates the listing corresponds to the eBay product associated with the provided product identifier. The product identifier is provided in createOrReplaceInventoryItem.

Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to 'true' if omitted.

Occurrence: Always

offers.listingListingDetails

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.listingIdstring

The unique identifier of the eBay listing that is associated with the published offer.

Occurrence: Conditional

offers.listing.listingOnHoldboolean

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.listingStatusListingStatusEnum

The enumeration value returned in this field indicates the status of the listing that is associated with the published offer.

Occurrence: Conditional

offers.listing.soldQuantityinteger

This integer value indicates the quantity of the product that has been sold for the published offer.

Occurrence: Conditional

offers.listingDescriptionstring

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.

Max Length: 500000 (which includes HTML markup/tags)

Occurrence: Conditional

offers.listingDurationListingDurationEnum

This field indicates the number of days that the listing will be active.

This field is returned for both auction and fixed-price listings; however, the value returned for fixed-price listings will always be GTC. The GTC (Good 'Til Cancelled) listings are automatically renewed each calendar month until the seller decides to end the listing.

Note: If the listing duration expires for an auction offer, the listing then becomes available as a fixed-price offer and will be GTC.

Occurrence: Always

offers.listingPoliciesListingPolicies

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.

It is required that the seller be opted into Business Policies before being able to create live eBay listings through the Inventory API. Sellers can opt-in to Business Policies through My eBay or by using the Account API's optInToProgram call. Payment, return, and fulfillment listing policies may be created/managed in My eBay or by using the listing policy calls of the sell Account API. The sell Account API can also be used to create and manage custom policies. For more information, see the sell Account API.

For unpublished offers where business policies have yet to be specified, this container will be returned as empty.

Occurrence: Always

offers.listingPolicies.bestOfferTermsBestOffer

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 true, and the seller also has the option of setting 'auto-accept' and 'auto-decline' price thresholds.

Note: Best Offer is unavailable for multi-variation listings.
This container is only returned if Best Offer is enabled on listing.

Occurrence: Conditional

offers.listingPolicies.bestOfferTerms.autoAcceptPriceAmount

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 true.

The price set here must be lower than the current 'Buy it Now' price. This field is only returned by getOffer and getOffers if set.

Occurrence: Conditional

offers.listingPolicies.bestOfferTerms.autoAcceptPrice.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.listingPolicies.bestOfferTerms.autoAcceptPrice.valuestring

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.autoDeclinePriceAmount

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 true.

The price set here must be lower than the current 'Buy it Now' price and the price set in the autoAcceptPrice field (if used). This field is only returned by getOffer and getOffers if set.

Occurrence: Conditional

offers.listingPolicies.bestOfferTerms.autoDeclinePrice.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.listingPolicies.bestOfferTerms.autoDeclinePrice.valuestring

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.bestOfferEnabledboolean

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.

The seller includes this field and sets its value to true to enable Best Offer feature.

Note: Best Offer is not available for multi-variation listings.

Occurrence: Conditional

offers.listingPolicies.eBayPlusIfEligibleboolean

This field is included in an offer and set to true if a Top-Rated seller is opted in to the eBay Plus program. With the eBay Plus program, qualified sellers must commit to next-day delivery of the item, and the buyers must have an eBay Plus subscription to be eligible to receive the benefits of this program, which are free, next-day delivery, as well as free returns.

Note: Currently, this program is only available on the Germany and Australian sites.
This field will be returned in the getOffer and getOffers methods if set for the offer.

Occurrence: Conditional

offers.listingPolicies.fulfillmentPolicyIdstring

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.

Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the fulfillment business policy before assigning it to the offer to make sure it is compatible with the inventory item and the offer settings. The seller may also want to review the shipping service costs in the fulfillment policy, and that seller might decide to override the shipping costs for one or more shipping service options by using the shippingCostOverrides container.

Business policies can be created and managed in My eBay or with the Account API. To get a list of all return policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getFulfillmentPolicies method. There are also calls in the Account API to retrieve a fulfillment policy by policy ID or policy name.

This field will be returned in the getOffer and getOffers methods if set for the offer.

Occurrence: Conditional

offers.listingPolicies.paymentPolicyIdstring

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.

Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the payment business policy to make sure that it is compatible with the marketplace and listing category before assigning it to the offer.

Business policies can be created and managed in My eBay or with the Account API. To get a list of all payment policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getPaymentPolicies method. There are also calls in the Account API to retrieve a payment policy by policy ID or policy name.

This field will be returned in the getOffer and getOffers methods if set for the offer.

Occurrence: Conditional

offers.listingPolicies.productCompliancePolicyIdsarray 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.

Product compliance policies provide buyers with important information and disclosures about products. For example, if you sell batteries and specific disclosures are required to be shared with all potential buyers, your global product compliance policy could contain the required disclosures.

A maximum of six (6) global product compliance policies may apply to each offer.Note: For countries that support country-specific policies, use regionalProductCompliancePolicies to apply them to an offer.

Occurrence: Conditional

offers.listingPolicies.regionalProductCompliancePoliciesRegionalProductCompliancePolicies

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.

Product compliance policies provide buyers with important information and disclosures about products. For example, if you sell batteries in a country requiring disclosures that apply only to that country, a country-specific product compliance policy could contain this information.

Each offer may include up to six (6) product compliance policies for each of the following countries:

  • United Kingdom [GB]
  • Germany [DE]
  • France [FR]
  • Italy [IT]
  • Spain [ES]

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.countryPoliciesarray 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.countryCountryCodeEnum

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.policyIdsarray of string

An array of custom policy identifiers that apply to the country specified by listingPolicies.regionalTakeBackPolicies.countryPolicies.country.

Product compliance and take-back policy information may be returned using the following methods:

  • getCustomPolicies

    Set policy_types to:
    • PRODUCT_COMPLIANCE for product compliance policies
    • TAKE_BACK for takeback policies

    This returns the list of specified policies and corresponding customPolicyId values a seller has created.
  • getCustomPolicy with custom_policy_id = customPolicyId

    Returns the details of the the policy specified by customPolicyId
For information about creating and managing custom policies, refer to the custom_policy resource in the Sell Account API.

Occurrence: Conditional

offers.listingPolicies.regionalTakeBackPoliciesRegionalTakeBackPolicies

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.

Each offer may include one (1) country-specific take-back policy for each of the following countries:

  • United Kingdom [GB]
  • Germany [DE]
  • France [FR]
  • Italy [IT]
  • Spain [ES]

Note: Take-back policies that apply to all countries to which a seller ships are specified using takeBackPolicyId.

Occurrence: Conditional

offers.listingPolicies.regionalTakeBackPolicies.countryPoliciesarray 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.countryCountryCodeEnum

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.policyIdsarray of string

An array of custom policy identifiers that apply to the country specified by listingPolicies.regionalTakeBackPolicies.countryPolicies.country.

Product compliance and take-back policy information may be returned using the following methods:

  • getCustomPolicies

    Set policy_types to:
    • PRODUCT_COMPLIANCE for product compliance policies
    • TAKE_BACK for takeback policies

    This returns the list of specified policies and corresponding customPolicyId values a seller has created.
  • getCustomPolicy with custom_policy_id = customPolicyId

    Returns the details of the the policy specified by customPolicyId
For information about creating and managing custom policies, refer to the custom_policy resource in the Sell Account API.

Occurrence: Conditional

offers.listingPolicies.returnPolicyIdstring

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.

Note: As a part of Digital Services Act (DSA) requirements, as of April 3, 2023, buyers in the EU must be allowed to return an item within 14 days or more, unless the item is exempt. Where applicable, sellers should update their return policies to reflect this requirement of accepting returns from EU buyers.
Business policies are not immediately required for offers, but are required before an offer can be published. The seller should review the return business policy before assigning it to the offer to make sure it is compatible with the inventory item and the offer settings.

Business policies can be created and managed in My eBay or with the Account API. To get a list of all return policies associated with a seller's account on a specific eBay Marketplace, use the Account API's getReturnPolicies call. There are also calls in the Account API to retrieve a return policy by policy ID or policy name.

This field will be returned in the getOffer and getOffers methods if set for the offer.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverridesarray 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 DOMESTIC to override a domestic shipping service option, or to INTERNATIONAL to override an international shipping service option.

A separate ShippingCostOverrides node is needed for each shipping service option whose costs are being overridden. All defined fields of the shippingCostOverrides container should be included, even if the shipping costs and surcharge values are not changing.

The shippingCostOverrides container is returned in the getOffer and getOffers calls if one or more shipping cost overrides are being applied to the fulfillment policy.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.additionalShippingCostAmount

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.

If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.

This field is returned in the getOffer and getOffers calls if defined.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.additionalShippingCost.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.additionalShippingCost.valuestring

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.priorityinteger

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.

This field is always required when overriding the shipping costs of a shipping service option, and will be always be returned for each shipping service option whose costs are being overridden.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.shippingCostAmount

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.

If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.

This field is returned in the getOffer and getOffers calls if defined.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.shippingCost.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.shippingCost.valuestring

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.shippingServiceTypeShippingServiceTypeEnum

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 DOMESTIC, and to override the shipping costs for each international shipping service, this field should be set to INTERNATIONAL. This value, along with priority value, sets which domestic or international shipping service option in the fulfillment policy that 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.

This field is always required when overriding the shipping costs of a shipping service option, and will be always be returned for each shipping service option whose costs are being overridden.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.surchargeAmount

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.

The dollar value passed into this field will override the shipping surcharge that is currently set for the applicable shipping service option. The shipping service option in the fulfillment policy to override is controlled by the shippingServiceType and priority values.

If using an updateOffer call, and this field is defined for the offer being updated, this field must be supplied again, even if its value is not changing.

This field is returned in the getOffer and getOffers calls if defined.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.surcharge.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.listingPolicies.shippingCostOverrides.surcharge.valuestring

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.takeBackPolicyIdstring

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.

One (1) global take-back policy may be specified per offer.
Note: For countries that support country-specific policies, use regionalTakeBackPolicies to apply them to an offer.

Occurrence: Conditional

offers.listingStartDatestring

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.

For example: 2023-05-30T19:08:00Z.

Scheduled listings do not always start at the exact date/time specified by the seller, but the date/time of the timestamp returned in getOffer/getOffers will be the same as the timestamp passed into a 'Create' or 'Update' offer call.

This field is returned if set for an offer.

Occurrence: Conditional

offers.lotSizeinteger

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.marketplaceIdMarketplaceEnum

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.merchantLocationKeystring

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.

This field is always returned for published offers, but is only returned if set for unpublished offers.

Max length: 36

Occurrence: Conditional

offers.offerIdstring

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.pricingSummaryPricingSummary

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.

For unpublished offers where pricing information has yet to be specified, this container will be returned as empty.

Occurrence: Always

offers.pricingSummary.auctionReservePriceAmount

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.

Important: This fee is charged regardless of whether or not the item is sold.

Occurrence: Conditional

offers.pricingSummary.auctionReservePrice.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.pricingSummary.auctionReservePrice.valuestring

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.auctionStartPriceAmount

This field indicates the minimum bidding price for the auction. The bidding starts at this price.

Note: If the auctionReservePrice is also specified, the value of auctionStartPrice must be lower than the value of auctionReservePrice.

Occurrence: Conditional

offers.pricingSummary.auctionStartPrice.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.pricingSummary.auctionStartPrice.valuestring

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.minimumAdvertisedPriceAmount

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.

This container will be returned by getOffer and getOffers if set for the offer.

Occurrence: Conditional

offers.pricingSummary.minimumAdvertisedPrice.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.pricingSummary.minimumAdvertisedPrice.valuestring

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.originallySoldForRetailPriceOnSoldOnEnum

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 ON_EBAY to indicate that the product was sold for the originalRetailPrice on an eBay site, or the seller will pass in a value of OFF_EBAY to indicate that the product was sold for the originalRetailPrice through a third-party retailer. This field and the originalRetailPrice 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.

This field will be returned by getOffer and getOffers if set for the offer.

Occurrence: Conditional

offers.pricingSummary.originalRetailPriceAmount

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.

This container will be returned by getOffer and getOffers if set for the offer.

Occurrence: Conditional

offers.pricingSummary.originalRetailPrice.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.pricingSummary.originalRetailPrice.valuestring

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.priceAmount

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.

For published offers, this container will always be returned, but for unpublished offers, this container will only be returned if set for the offer.

Occurrence: Conditional

offers.pricingSummary.price.currencystring

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.

See the CurrencyCodeEnum type for the full list of currencies and their corresponding three-digit string values.

Occurrence: Conditional

offers.pricingSummary.price.valuestring

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.pricingVisibilityMinimumAdvertisedPriceHandlingEnum

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 PRE_CHECKOUT. To show the MAP price after the buyer already commits to buy the item, the seller will set this value to DURING_CHECKOUT. This field will be ignored if the seller and/or the listing is not eligible for the MAP feature.

This field will be returned by getOffer and getOffers if set for the offer.

Occurrence: Conditional

offers.quantityLimitPerBuyerinteger

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 5, each buyer may purchase a quantity of the inventory item between one and five, and the purchases can occur in one multiple-quantity purchase, or over multiple transactions. If a buyer attempts to purchase one or more of these products, and the cumulative quantity will take the buyer beyond the quantity limit, that buyer will be blocked from that purchase.

Occurrence: Conditional

offers.regulatoryRegulatory

This container is used by the seller to provide regulatory information.

Occurrence: Conditional

offers.regulatory.economicOperatorEconomicOperator

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.addressLine1string

The first line of the registered Economic Operator's street address.

Occurrence: Conditional

offers.regulatory.economicOperator.addressLine2string

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.citystring

The city of the registered Economic Operator's street address.

Occurrence: Conditional

offers.regulatory.economicOperator.companyNamestring

The company name of the registered Economic Operator.

Occurrence: Conditional

offers.regulatory.economicOperator.countryCountryCodeEnum

The two-letter ISO 3166-1 standard abbreviation of the country of the registered Economic Operator's address.

Occurrence: Conditional

offers.regulatory.economicOperator.emailstring

The registered Economic Operator's business email address.

Occurrence: Conditional

offers.regulatory.economicOperator.phonestring

The registered Economic Operator's business phone number.

Occurrence: Conditional

offers.regulatory.economicOperator.postalCodestring

The postal code of the registered Economic Operator's street address.

Occurrence: Conditional

offers.regulatory.economicOperator.stateOrProvincestring

The state or province of the registered Economic Operator's street address.

Occurrence: Conditional

offers.regulatory.energyEfficiencyLabelEnergyEfficiencyLabel

This container provides information about the energy efficiency for certain durable goods.

Occurrence: Conditional

offers.regulatory.energyEfficiencyLabel.imageDescriptionstring

A brief verbal summary of the information included on the Energy Efficiency Label for an item.

For example, On a scale of A to G the rating is E.

Occurrence: Conditional

offers.regulatory.energyEfficiencyLabel.imageURLstring

The URL to the Energy Efficiency Label image that is applicable to an item.

Occurrence: Conditional

offers.regulatory.energyEfficiencyLabel.productInformationSheetstring

The URL to the Product Information Sheet that provides complete manufacturer-provided efficiency information about an item.

Occurrence: Conditional

offers.regulatory.hazmatHazmat

This container is used by the seller to provide hazardous material information for the listing.

Three elements are required to complete the Hazmat section of a listing:

  • Pictograms
  • SignalWord
  • Statements
The fourth element, Component, is optional.

Occurrence: Conditional

offers.regulatory.hazmat.componentstring

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.

Max length: 120

Occurrence: Conditional

offers.regulatory.hazmat.pictogramsarray of string

An array of comma-separated string values listing applicable pictogram code(s) for Hazard Pictogram(s).

If your product contains hazardous substances or mixtures, please select the values corresponding to the hazard pictograms that are stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.

Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Pictogram sample values for additional information.

Occurrence: Conditional

offers.regulatory.hazmat.signalWordstring

This field sets the signal word for hazardous materials in the listing.

If your product contains hazardous substances or mixtures, please select a value corresponding to the signal word that is stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.

Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Signal word information for additional information.

Occurrence: Conditional

offers.regulatory.hazmat.statementsarray of string

An array of comma-separated string values specifying applicable statement code(s) for hazard statement(s) for the listing.

If your product contains hazardous substances or mixtures, please select the values corresponding to the hazard statements that are stated on your product's Safety Data Sheet. The selected hazard information will be displayed on your listing.

Note: Use the getHazardousMaterialsLabels method in the Metadata API to find supported values for a specific marketplace/site. Refer to Hazard statement sample values for additional information.

Occurrence: Conditional

offers.regulatory.repairScorenumber

This field represents the repair index for the listing.

The repair index identifies the manufacturer's repair score for a product (i.e., how easy is it to repair the product.) This field is a floating point value between 0.0 (i.e., difficult to repair,) and 10.0 (i.e., easily repaired.)

The format for repairScore is limited to one decimal place. For example:

  • 7.9 and 0.0 are both valid scores
  • 5.645 and 2.10 are both invalid scores

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.secondaryCategoryIdstring

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.

Note: You cannot list US eBay Motors vehicles in two categories. However, you can list Parts & Accessories in two categories.

Occurrence: Conditional

offers.skustring

This is the seller-defined SKU value of the product in the offer.

Max Length: 50

Occurrence: Always

offers.statusOfferStatusEnum

The enumeration value in this field specifies the status of the offer - either PUBLISHED or UNPUBLISHED.

Occurrence: Always

offers.storeCategoryNamesarray 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:

"storeCategoryNames": [
"/Fashion/Men/Shirts",
"/Fashion/Men/Accessories" ],

Occurrence: Conditional

offers.taxTax

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 true, but a buyer's purchase will not involve sales tax. A sales tax rate must be set up in the seller's sales tax table for the buyer's state/tax jurisdiction in order for that buyer to be subject to sales tax.

See the Using a tax table help page for more information on setting up and using a sales tax table.

Occurrence: Conditional

offers.tax.applyTaxboolean

When set to true, the seller's account-level sales-tax table will be used to calculate sales tax for an order.

Note: Sales-tax tables are available only for the US and Canada marketplaces.

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.

However, sellers may continue to use a sales-tax table to set rates for the following US territories:

  • American Samoa (AS)
  • Guam (GU)
  • Northern Mariana Islands (MP)
  • Palau (PW)
  • US Virgin Islands (VI)


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.thirdPartyTaxCategorystring

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 WASTE_RECYCLING_FEE. If this field is used, the applyTax field must also be used and set to true

This field will be returned by getOffer and getOffers if set for the offer.

Occurrence: Conditional

offers.tax.vatPercentagenumber

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.

To use VAT, a seller must be a business seller with a VAT-ID registered with eBay, and must be listing the item on a VAT-enabled site. Max applicable length is 6 characters, including the decimal (e.g., 12.345). The scale is 3 decimal places. (If you pass in 12.3456, eBay may round up the value to 12.346).

This field will be returned by getOffer and getOffers if set for the offer.

Occurrence: Conditional

prevstring

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

sizeinteger

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.

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 and this value will be 2. Otherwise, only one offer will be returned and this value will be 1.

Occurrence: Always

totalinteger

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.

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, so this value would be 2. Otherwise, only one offer will be returned and this value will be 1.

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.

StatusMeaning
200Success
400Bad Request
404Not Found
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
25001API_INVENTORYAPPLICATIONA system error has occurred. {additionalInfo}
25706API_INVENTORYREQUESTYou have provided invalid pagination values. {additionalInfo}.
25709API_INVENTORYREQUESTInvalid 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.