Skip to main content

PUT/offer/{offerId}

This call updates an existing offer. An existing offer may be in published state (active eBay listing), or in an unpublished state and yet to be published with the publishOffer call. The unique identifier (offerId) for the offer to update is passed in at the end of the call URI.

The updateOffer call does a complete replacement of the existing offer object, so all fields that make up the current offer object are required, regardless of whether their values changed.

Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Offer fields for a list of fields required to publish an offer.


Other information that is required before an unpublished offer can be published or before a published offer can be revised include:
  • Inventory location
  • Offer price
  • Available quantity
  • eBay listing category
  • Referenced listing policy profiles to set payment, return, and fulfillment values/settings

Note: Though the includeCatalogProductDetails parameter is not required to be submitted in the request, the parameter defaults to true if omitted from both the updateOffer and the createOffer calls. If a value is specified in the updateOffer call, this value will be used.
Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.
Note: Each listing can be revised up to 250 times in one calendar day. If this revision threshold is reached, the seller will be blocked from revising the item until the next calendar day.

For published offers, the listingDescription field is also required to update the offer/eBay listing. For unpublished offers, this field is not necessarily required unless it is already set for the unpublished offer.

Input

Resource URI

PUT https://api.ebay.com/sell/inventory/v1/offer/{offerId}

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
offerIdstringThis path parameter specifies the unique identifier of the offer being updated.

Use the getOffers method to retrieve offer IDs.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

HeaderTypeDescription
Content-LanguagestringThis header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.

For more information on the Content-Language header, refer to HTTP request headers.

Occurrence: Required

Content-TypestringThis header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

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

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard
{ /* EbayOfferDetailsWithId */ }

Request fields

Input container/fieldTypeDescription
availableQuantityinteger

This integer value sets the quantity of the inventory item that will be available through the offer. Quantity must be set to 1 or more in order for the inventory item to be purchasable. This value should not be more than the quantity that is specified for the inventory item record. For auction listings, this value must be 1.

If this field exists for the current unpublished or published offer, it should be provided again in the updateOffer call, even if the value is not changing. If this particular field is omitted in an updateOffer call, the general available quantity set for the inventory item record may be used instead, and this may not be accurate if the inventory item is being sold across multiple marketplaces.

Occurrence: Conditional

categoryIdstring

The unique identifier of the eBay category that the inventory item is/will be listed under. This field is not immediately required for an unpublished offer, but will be required before publishing the offer. Sellers can use the getCategorySuggestions method of the Taxonomy API to retrieve suggested category ID values. The seller passes in a query string like "iPhone 6", and category ID values for suggested categories are returned in the response.

If this field exists for the current unpublished offer, it should be provided again in the updateOffer call, even if the eBay category is not changing. For a published offer (aka active eBay listing), this field must be provided or an error may occur. The eBay category of an active eBay listing cannot be changed once the listing has one or more sales, or if the listing is scheduled to end in less than 12 hours.

Important!Publish offer note: This field is required before an offer can be published to create an active listing.

Occurrence: Conditional

charityCharity

This container is used if the seller wishes to update a published or unpublished offer with a charitable organization that will receive a percentage of sale proceeds for each sale generated by the eBay 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 for each sale. Both fields in this container are conditionally required for charitable listings.

Occurrence: Optional

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

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

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: Optional

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.

Note: 0 should not be used as a default value.
Minimum: 0.0

Occurrence: Optional

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

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

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: Optional

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: Optional

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: Optional

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: Optional

hideBuyerDetailsboolean

This field is included and set to true if the seller wishes to update a published or unpublished offer with the private listing feature. Alternatively, the seller could also remove the private listing feature (if already set for a published or unpublished offer) by including this field and setting it to false.

Sellers may want to use this option when they believe that a listing's potential bidders/buyers would not want their obfuscated user IDs (and feedback scores) exposed to other users.

Occurrence: Optional

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: Optional

listingDescriptionstring

The text in this field is (published offers), or will become (unpublished offers) the description of the eBay listing. This field is not immediately required for an unpublished offer, but will be required before publishing the offer. Note that if the listingDescription field was omitted in the createOffer call for the offer, the offer entity should have picked up the text provided in the product.description field of the inventory item record, or if the inventory item is part of a group, the offer entity should have picked up the text provided in the description field of the inventory item group record.

HTML tags and markup can be used in listing descriptions, but each character counts toward the max length limit.

Note: To ensure that their short listing description is optimized when viewed on mobile devices, sellers should strongly consider using eBay's View Item description summary feature when listing their items. Keep in mind that the 'short' listing description is what prospective buyers first see when they view the listing on a mobile device. The 'full' listing description is also available to mobile users when they click on the short listing description, but the full description is not automatically optimized for viewing in mobile devices, and many users won't even drill down to the full description.

Using HTML div and span tag attributes, this feature allows sellers to customize and fully control the short listing description that is displayed to prospective buyers when viewing the listing on a mobile device. The short listing description on mobile devices is limited to 800 characters, and whenever the full listing description (provided in this field, in UI, or seller tool) exceeds this limit, eBay uses a special algorithm to derive the best possible short listing description within the 800-character limit. However, due to some short listing description content being removed, it is definitely not ideal for the seller, and could lead to a bad buyer experience and possibly to a Significantly not as described (SNAD) case, since the buyer may not get complete details on the item when viewing the short listing description. See the eBay help page for more details on using the HTML div and span tags.


If this field exists for the current unpublished offer, it should be provided again in the updateOffer call, even if the text is not changing. For a published offer (aka active eBay listing), this field must be provided or an error may occur.

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

Occurrence: Conditional

listingDurationListingDurationEnum

This field indicates the number of days that the listing will be active. For fixed-price listings, this value must be set to GTC, but auction listings support different listing durations.

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 without a winning bidder, the listing then becomes available as a fixed-price offer and listing duration will be GTC.

Important!Publish offer note: This field is required before an offer can be published to create an active listing.


Occurrence: Conditional

listingPoliciesListingPolicies

This container sets listing policies that will be used to construct the listing. Listing policies include business policies, custom listing policies, and fields that override shipping costs, enable eBay Plus eligibility, or enable the Best Offer feature. This container is not initially required when creating an offer but will become required before the offer can be published. Busines policies (payment, return, fulfillment policies) will always be required before publishing an offer. Other policies, including the seller created compliance policies and seller created take-back policy, will be required as needed by the marketplace, category, or product.

This container is required for updating published offers, regardless of whether or not the business policies are being changed. For an unpublished offer, this field is not necessarily required, but will be required before an offer can be published.

It is required that the seller be opted in to 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. Similarly, payment, return, and fulfillment business policies may be created/managed in My eBay or by using the business policy calls of the Account API.

Important!Publish offer note: This container and a few of its child fields (as noted below) are required before an offer can be published to create an active listing.


Occurrence: Conditional

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: Optional

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: Optional

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

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

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: Optional

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

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

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: Optional

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: Optional

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.

Important!Publish offer note: This field is required before an offer can be published to create an active listing.

Occurrence: Conditional

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.

Important!Publish offer note: This field is required before an offer can be published to create an active listing.

Occurrence: Conditional

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: Optional

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: Optional

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

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

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

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: Optional

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

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

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

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.

Important!Publish offer note: This field is required before an offer can be published to create an active listing.

Occurrence: Conditional

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: Optional

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

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

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

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

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

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

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

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

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

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

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

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: Optional

listingStartDatestring

This field can be used with an unpublished offer if the seller wants to specify a time in the future that the listing will become active on eBay. The timestamp supplied in this field should be in UTC format, and it should be far enough in the future so that the seller will have enough time to publish the listing with the publishOffer method.

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

This field is optional, and it doesn't apply to offers where the corresponding listing is already active. If this field is not provided, the listing starts immediately after a successful publishOffer method.

Occurrence: Optional

lotSizeinteger

This field is only applicable if the listing is a lot listing. A lot listing is a listing that has multiple quantity of the same item, such as four identical tires being sold as a single offer, or it can be a mixed lot of similar items, such as used clothing items or an assortment of baseball cards. Whether the lot listing involved identical items or a mixed lot, the integer value passed into this field is the total number of items in the lot. Lots can be used for auction and fixed-price listings.

Occurrence: Conditional

merchantLocationKeystring

The unique identifier of a merchant's inventory location (where the inventory item in the offer is located).

To get more information about inventory locations, the getInventoryLocations method can be used.br>
Note: This field is not initially required upon first creating an offer, but will become required before an offer can be published.
Max length: 36

Occurrence: Conditional

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.

This container is required for updating published offers, regardless of whether or not the pricing information is being changed or not. For an unpublished offer, this container is not necessarily required, but an offer price will be required before an offer can be published, and if a pricingSummary container already exists for an unpublished offer, it must be provided again, even if the values are not changing.

Important!Publish offer note: This container and its child container, price, are required before an offer can be published to create an active listing.

Occurrence: Conditional

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: Optional

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

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

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: Optional

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

quantityLimitPerBuyerinteger

This field is only applicable and set if the seller wishes to set a restriction on the purchase quantity per seller. If this field is set by the seller for the offer, then each distinct buyer may purchase up to, but not exceeding the quantity specified for this field. So, if this field's value is 5, each buyer may purchase between one to five of these products, 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.

If this field currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if the value is not changing.

Occurrence: Conditional

regulatoryRegulatory

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

Occurrence: Optional

regulatory.documentsarray of Document

This container provides a collection of regulatory documents associated with the listing.

For information on removing one or more files from a listing using the updateOffer method, see Remove documents from listings. .

Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory document information in their eBay listings. For more information on GPSR, see General Product Safety Regulation (GPSR).

Occurrence: Optional

regulatory.documents.documentIdstring

The unique identifier of a regulatory document associated with the listing.

This value can be found in the response of the createDocument method of the Media API.

Occurrence: Conditional

regulatory.energyEfficiencyLabelEnergyEfficiencyLabel

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

Note: Energy efficiency 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 energy efficiency-related fields.

Occurrence: Optional

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

regulatory.energyEfficiencyLabel.imageURLstring

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

Occurrence: Conditional

regulatory.energyEfficiencyLabel.productInformationSheetstring

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

Occurrence: Conditional

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.

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: Optional

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: Optional

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

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

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

regulatory.manufacturerManufacturer

This container provides information about the manufacturer of the item.

Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory manufacturer information in their eBay listings. Manufacturer 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 manufacturer-related fields. For more information on GPSR, see General Product Safety Regulation (GPSR).

Occurrence: Optional

regulatory.manufacturer.addressLine1string

The first line of the product manufacturer's street address.

Max length: 180 characters

Occurrence: Conditional

regulatory.manufacturer.addressLine2string

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

Max length: 180 characters

Occurrence: Optional

regulatory.manufacturer.citystring

The city of the product manufacturer's street address.

Max length: 64 characters

Occurrence: Conditional

regulatory.manufacturer.companyNamestring

The company name of the the product manufacturer.

Max length: 100 characters

Occurrence: Conditional

regulatory.manufacturer.countryCountryCodeEnum

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

regulatory.manufacturer.emailstring

The product manufacturer's business email address.

Max length: 180 characters

Occurrence: Conditional

regulatory.manufacturer.phonestring

The product manufacturer's business phone number.

Max length: 64 characters

Occurrence: Conditional

regulatory.manufacturer.postalCodestring

The postal code of the product manufacturer's street address.

Max length: 9 characters

Occurrence: Conditional

regulatory.manufacturer.stateOrProvincestring

The state or province of the product manufacturer's street address.

Max length: 64 characters

Occurrence: Conditional

regulatory.productSafetyProductSafety

This container is used to provide product safety information for the listing. One of the following elements is required to complete the Product Safety section for a listing: pictograms or statements. The component element is optional.

Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory product safety information in their eBay listings. Product safety 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 product safety-related fields. For more information on GPSR, see General Product Safety Regulation (GPSR).

Occurrence: Optional

regulatory.productSafety.componentstring

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

Note: Component information can only be specified if used with the pictograms and/or statements field; if the component is provided without one or both of these fields, an error will occur.
Max length: 120 characters

Occurrence: Optional

regulatory.productSafety.pictogramsarray of string

An array of comma-separated string values used to provide product safety pictogram(s) for the listing.

If your product shows universal product safety or compliance symbols, please select the values corresponding to the product safety pictograms for display in the product safety section of the listing. The seller specifies the identifier of each pictogram in this field.

Note: For product safety pictograms, use the getProductSafetyLabels method of the Metadata API to find supported values for a specific marketplace/site.
A maximum of 2 pictograms are allowed for product safety.

Occurrence: Conditional

regulatory.productSafety.statementsarray of string

An array of comma-separated string values used to provide product safety statement(s) for the listing.

If your product shows universal product safety or compliance warnings, please select the values corresponding to the product safety statements for display in the product safety section of the listing. The seller specifies the identifier of each statement in this field.

Note: For product safety statements, use the getProductSafetyLabels method of the Metadata API to find supported values for a specific marketplace/site.
A maximum of 8 statements are allowed for product safety.

Occurrence: Conditional

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

Note: 0 should not be used as a default value, as it implies the product is not repairable.
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: Optional

regulatory.responsiblePersonsarray of ResponsiblePerson

This container provides information about the EU-based Responsible Persons or entities associated with the listing.

A maximum of 5 EU Responsible Persons are supported.

Note: As a part of General Product Safety Regulation (GPSR) requirements effective on December 13th, 2024, sellers operating in, or shipping to, EU-based countries or Northern Ireland are conditionally required to provide regulatory Responsible Persons information in their eBay listings. For more information on GPSR, see General Product Safety Regulation (GPSR).

Occurrence: Optional

regulatory.responsiblePersons.addressLine1string

The first line of the Responsible Person's street address.

Max length: 180 characters

Occurrence: Conditional

regulatory.responsiblePersons.addressLine2string

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

Max length: 180 characters

Occurrence: Optional

regulatory.responsiblePersons.citystring

The city of the Responsible Person's street address.

Max length: 64 characters

Occurrence: Conditional

regulatory.responsiblePersons.companyNamestring

The name of the the Responsible Person or entity.

Max length: 100 characters

Occurrence: Conditional

regulatory.responsiblePersons.countryCountryCodeEnum

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

regulatory.responsiblePersons.emailstring

The Responsible Person's email address.

Max length: 180 characters

Occurrence: Conditional

regulatory.responsiblePersons.phonestring

The Responsible Person's business phone number.

Max length: 64 characters

Occurrence: Conditional

regulatory.responsiblePersons.postalCodestring

The postal code of the Responsible Person's street address.

Max length: 9 characters

Occurrence: Conditional

regulatory.responsiblePersons.stateOrProvincestring

The state of province of the Responsible Person's street address.

Max length: 64 characters

Occurrence: Conditional

regulatory.responsiblePersons.typesarray of ResponsiblePersonTypeEnum

The type(s) associated with the Responsible Person or entity.

Note: Currently, the only supported value is EUResponsiblePerson.

Occurrence: Conditional

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: Optional

storeCategoryNamesarray of string

This container is used if the seller would like to place the inventory item into one or two store categories that the seller has set up for their eBay store. The string value(s) passed in to this container will be the full path(s) to the store categories, as shown below:

"storeCategoryNames": [
"/Fashion/Men/Shirts",
"/Fashion/Men/Accessories" ],
If this field currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if the eBay categories are not changing.

Occurrence: Conditional

taxTax

This container is only applicable and used if a sales tax table, a Value-Added Tax (VAT) rate, or a tax exception category code will be 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. Sales tax rates for different jurisdictions can be added/modified in the Payment Preferences section of My eBay, or the seller can use the sales tax calls of the Account API.

If tax information currently exists for an unpublished or published offer, it should be provided again in an updateOffer call, even if none of the tax settings are changing.

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

Occurrence: Conditional

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

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: Optional

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: Optional

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
Content-LanguageThis response header sets the natural language that will be provided in the field values of the response payload.

Response payload

Response fields

Output container/fieldTypeDescription
offerIdstring

The unique identifier of the offer that was just created with a createOffer call. It is not returned if the createOffer call fails to create an offer. This identifier will be needed for many offer-related calls.

Note: The offerId value is only returned with a successful createOffer call. This field will not be returned in the updateOffer response.

Occurrence: Conditional

warningsarray of ErrorDetailV3

This container will contain an array of errors and/or warnings when a call is made, and errors and/or warnings occur.

Occurrence: Conditional

warnings.categorystring

This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Conditional

warnings.domainstring

The name of the domain in which the error or warning occurred.

Occurrence: Conditional

warnings.errorIdinteger

A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of string

An array of one or more reference IDs which identify the specific request element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.longMessagestring

A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

warnings.messagestring

A description of the condition that caused the error or warning.

Occurrence: Conditional

warnings.outputRefIdsarray of string

An array of one or more reference IDs which identify the specific response element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3

Various warning and error messages return one or more variables that contain contextual information about the error or waring. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

warnings.parameters.namestring

This type contains the name and value of an input parameter that contributed to a specific error or warning condition.

Occurrence: Conditional

warnings.parameters.valuestring

This is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstring

The name of the subdomain in which the error or warning occurred.

Occurrence: Conditional

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
204No Content
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}
25002API_INVENTORYREQUESTA user error has occurred. {additionalInfo}
25003API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}
25004API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}
25005API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}
25006API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}
25007API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}
25008API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}
25009API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}
25011API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}
25012API_INVENTORYREQUESTInvalid inventory location. {additionalInfo}
25013API_INVENTORYREQUESTInvalid data in the Inventory Item Group. {additionalInfo}
25014API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}
25015API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}
25016API_INVENTORYREQUESTThe {fieldName} value is invalid. {additionalInfo}
25017API_INVENTORYREQUEST{fieldName} is missing. {additionalInfo}
25018API_INVENTORYREQUESTIncomplete account information. {additionalInfo}
25019API_INVENTORYREQUESTCannot revise listing. {additionalInfo}
25020API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}
25021API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}
25022API_INVENTORYREQUESTInvalid attribute. {fieldName}
25023API_INVENTORYREQUESTInvalid compatibility information. {additionalInfo}
25025API_INVENTORYAPPLICATIONConcurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later.
25026API_INVENTORYREQUESTSelling limit exceeded. {additionalInfo}
25029API_INVENTORYREQUEST{field} is required for this category.
25031API_INVENTORYREQUEST{field} is not valid and needs to be a number between {min} and {max}
25032API_INVENTORYREQUEST{field} is not valid
25034API_INVENTORYREQUESTOnly {max value} policies can be specified
25035API_INVENTORYREQUESTThe specified policy is not found for the market place
25036API_INVENTORYREQUESTThe policy(ies) {PolicyId} is not of type {PolicyEnum}
25038API_INVENTORYREQUEST{ItemId} cannot be revised if the item has a bid or a best offer or is ending within 12 hours
25039API_INVENTORYREQUEST{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours
25040API_INVENTORYREQUEST{ItemId} cannot be revised if the item has a bid or a best offer and is ending within 12 hours
25076API_INVENTORYREQUEST{replaceable_value} ID(s) {replaceable_value} not found. Please use valid ID(s).
25077API_INVENTORYREQUESTDuplicate Regulatory ID(s) {replaceable_value} sent in the request. Duplicate ID(s) have been ignored.
25078API_INVENTORYREQUESTHazmat structure incorrect for {replaceable_value}.
25079API_INVENTORYREQUESTRepair score invalid. Repair score must be in the range from {replaceable_value} to {replaceable_value} with one decimal place.
25080API_INVENTORYREQUESTThe value of the {0} field is invalid. Field must not exceed {replaceable_value} characters.
25081API_INVENTORYREQUESTHazardous material information incomplete. Your listing must include pictograms, hazardous statements and a signal word.
25083API_INVENTORYREQUESTEnergy efficiency image is missing. Image is required with image description.
25084API_INVENTORYREQUESTThe listing must have both an energy efficiency label and a product information sheet.
25086API_INVENTORYREQUESTThe URL provided must be an eBay Picture Service URL.
25088API_INVENTORYREQUESTThe email address provided is formatted incorrectly.
25089API_INVENTORYREQUESTNo more than {replaceable_value} global compliance policies allowed. Excess policies ignored.
25090API_INVENTORYREQUESTNo more than {replaceable_value} compliance policies per region allowed. Excess policies ignored.
25091API_INVENTORYREQUESTNo more than a total of {replaceable_value} compliance policies allowed. Excess policies ignored.
25092API_INVENTORYREQUESTNo more than {replaceable_value} global takeback policy allowed.
25093API_INVENTORYREQUESTNo more than {replaceable_value} takeback policy per region allowed. Excess policies ignored.
25094API_INVENTORYREQUESTNo more than a total of {replaceable_value} takeback policies allowed.
25095API_INVENTORYREQUESTRegion invalid for regional custom policy. Regions allowed are {replaceable_value}.
25104API_INVENTORYREQUESTRegulatory document ID(s) {replaceable_value} not found. Please use valid ID(s).
25106API_INVENTORYREQUESTRegulatory document structure incorrect. Max allowed number of entries is {replaceable_value}.
25107API_INVENTORYREQUESTInvalid document state for ID(s) {replaceable_value}. Documents must be in the SUBMITTED or ACCEPTED state.
25108API_INVENTORYREQUESTProduct Safety structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}.
25109API_INVENTORYREQUESTProduct Safety information incomplete. Your listing must include product safety pictograms & statements.
25110API_INVENTORYREQUESTManufacturer address information is incomplete. When providing the address, please provide the street, city, postal code and country
25111API_INVENTORYREQUESTManufacturer information is incomplete. Please provide the company name.
25112API_INVENTORYREQUESTResponsible Person structure incorrect for {replaceable_value}. Max allowed number of entries is {replaceable_value}.
25113API_INVENTORYREQUESTResponsible Person address information is incomplete. When providing the address, please provide the street, city, postal code and country
25114API_INVENTORYREQUESTResponsible Person information is incomplete. Please provide the company name.
25115API_INVENTORYREQUESTEither the Manufacturer or at least one of the Responsible Persons must be located in the EU.
25116API_INVENTORYREQUESTPlease provide a minimum of {replaceable_value} and a maximum of {replaceable_value} types for a Responsible Person.
25118API_INVENTORYREQUESTSeller must provide at least one form of contact info for Manufacturer - either phone, email or address.
25119API_INVENTORYREQUESTSeller must provide at least one form of contact info for Responsible Person - either phone, email or address.
25601API_INVENTORYREQUESTInvalid attribute. {fieldName}
25604API_INVENTORYREQUESTInput error. {additionalInfo}
25710API_INVENTORYREQUESTWe didn't find the resource/entity you are requesting. Please verify the request
25713API_INVENTORYREQUESTThis Offer is not available : {additionalInfo}.
25752API_INVENTORYREQUESTlistingStartDate provided is invalid.
25756API_INVENTORYREQUESTAuction format is not permitted with a SKU that is part of an InventoryItemGroup.
25757API_INVENTORYREQUESTauctionStartPrice is required for auction offer.
25758API_INVENTORYREQUESTauctionStartPrice and auctionReservePrice are not supported for fixed price offer.
25761API_INVENTORYREQUESTDiscount pricing is not applicable for auction offer.
25762API_INVENTORYREQUESTavailableQuantity is not applicable for auction offer.
25763API_INVENTORYREQUESTquantityLimitPerBuyer is not applicable for auction offer.
25764API_INVENTORYREQUESTeBayPlusIfEligible is not applicable for auction offer.
25766API_INVENTORYREQUESTThe takeBackPolicyId field must be a long value type. Please correct the error.
25767API_INVENTORYREQUESTThe productCompliancePolicyId field must be a long value type. Please correct the error.

Warnings

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

CodeDomainCategoryMeaning
25028API_INVENTORYREQUEST{field} is not applicable and has been dropped
25030API_INVENTORYREQUEST{field} is not applicable for the condition and has been dropped
25033API_INVENTORYREQUESTDuplicate policy IDs found
25037API_INVENTORYREQUESTItem level Eco Participation Fee will be ignored
25401API_INVENTORYAPPLICATIONInvalid listing options removed. {additionalInfo}
25402API_INVENTORYAPPLICATIONSystem warning. {additionalInfo}
25753API_INVENTORYREQUESTlistingStartDate is in the past or the offer is live. Value is not updated on the listing.

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: Update an Existing Offer for an Inventory Item

This call will update an existing offer for an inventory item associated with the seller's acount.

Input

The offerId path parameter is required in order to specify the existing order that is being updated.

The existing offer will be updated with the values passed into the request payload. With the exception of the sku, marketplaceId, and format fields, all the fields used for the existing offer are also required for an updateOffer call, even when their values have not changed.

For this particular updateOffer call, the seller decreased the total quantity available to 60, reduced the price to $260.00, and increased the quantity of the item that a specific buyer can purchase to 3.

The fulfillment, payment, and return listing policies used remained the same.

POSThttps://api.ebay.com/sell/inventory/v1/offer/1*********1

Output

A successful call returns an http status code of 204 No Content and no payload.