eBay Trading API
|
Use this call to test the definition of a new fixed-price item without actually posting the listing.
Note: Seller-level call rate limits were introduced in Version 793 for Add and Revise Listing calls. Each user is allowed 1200 Add Listing calls and 1200 Revise Listing calls per 30 seconds, which equates to about 3.5 million calls per 24-hour period. Add Listing calls include AddItem, AddFixedPriceItem, AddItems, AddSellingManagerTemplate, VerifyAddItem, and VerifyAddFixedPriceItem. Revise Listing calls include ReviseItem, ReviseFixedPriceItem, and ReviseSellingManagerTemplate.A fixed-price listing can include multiple, identical items for sale by setting the Quantity to a value greater than 1. For more details on creating fixed-price items, see AddFixedPriceItem.
This call enables the seller to test the item definition and get listing fees before actually listing the item. Note that due to certain promotions and timing differences, the listing fees returned by VerifyAddFixedPriceItem can be different from those returned by AddFixedPriceItem for the same item definition.
VerifyAddFixedPriceItem is nearly identical to VerifyAddItem, and you should refer to that call for details on verifying item definitions. However, VerifyAddFixedPriceItem does have the following differences from VerifyAddItem:
| Note to Large Merchant Services users: Starting with release 637, when you use VerifyAddFixedPriceItem within a Merchant Data file, your request must be enclosed within BulkDataExchangeRequest tags. In addition, this call returns a namespace in BulkDataExchangeResponse, a top-level container in the response. This container is not shown in the standard Input/Output sections for this call. However, you can see examples of this container in both the request and response in the Samples section for AddFixedPriceItem. |
You can test this call in the Sandbox environment.
See:
Listing an Item
Introduction to Pictures in Item Listings
See also the reference documentation for these calls:
| Output Detail Controls Samples Change History Top Errors for VerifyAddFixedPriceItem User Notes |
The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).
See also Samples.
See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.
The XML prototype does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).
<?xml version="1.0" encoding="utf-8"?>
<VerifyAddFixedPriceItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
<!-- Call-specific Input Fields -->
<Item> ItemType
<ConditionDescription> string </ConditionDescription>
<ConditionID> int </ConditionID>
<DiscountPriceInfo> DiscountPriceInfoType
<MadeForOutletComparisonPrice> AmountType (double) </MadeForOutletComparisonPrice>
<MinimumAdvertisedPrice> AmountType (double) </MinimumAdvertisedPrice>
<MinimumAdvertisedPriceExposure> MinimumAdvertisedPriceExposureCodeType </MinimumAdvertisedPriceExposure>
<OriginalRetailPrice> AmountType (double) </OriginalRetailPrice>
<SoldOffeBay> boolean </SoldOffeBay>
<SoldOneBay> boolean </SoldOneBay>
</DiscountPriceInfo>
<IncludeRecommendations> boolean </IncludeRecommendations>
<ProductListingDetails> ProductListingDetailsType
<IncludePrefilledItemInformation> boolean </IncludePrefilledItemInformation>
<IncludeStockPhotoURL> boolean </IncludeStockPhotoURL>
<ProductID> string </ProductID>
<UseStockPhotoURLAsGallery> boolean </UseStockPhotoURLAsGallery>
</ProductListingDetails>
<QuantityInfo> QuantityInfoType
<MinimumRemnantSet> int </MinimumRemnantSet>
</QuantityInfo>
<QuantityRestrictionPerBuyer> QuantityRestrictionPerBuyerInfoType
<MaximumQuantity> int </MaximumQuantity>
</QuantityRestrictionPerBuyer>
<ReturnPolicy> ReturnPolicyType
<Description> string </Description>
<EAN> string </EAN>
<RefundOption> token </RefundOption>
<RestockingFeeValueOption> token </RestockingFeeValueOption>
<ReturnsAcceptedOption> token </ReturnsAcceptedOption>
<ReturnsWithinOption> token </ReturnsWithinOption>
<ShippingCostPaidByOption> token </ShippingCostPaidByOption>
<WarrantyDurationOption> token </WarrantyDurationOption>
<WarrantyOfferedOption> token </WarrantyOfferedOption>
<WarrantyTypeOption> token </WarrantyTypeOption>
</ReturnPolicy>
<ScheduleTime> dateTime </ScheduleTime>
<ShippingPackageDetails> ShipPackageDetailsType
<MeasurementUnit> MeasurementSystemCodeType </MeasurementUnit>
<PackageDepth> MeasureType (decimal) </PackageDepth>
<PackageLength> MeasureType (decimal) </PackageLength>
<PackageWidth> MeasureType (decimal) </PackageWidth>
<ShippingIrregular> boolean </ShippingIrregular>
<ShippingPackage> ShippingPackageCodeType </ShippingPackage>
<WeightMajor> MeasureType (decimal) </WeightMajor>
<WeightMinor> MeasureType (decimal) </WeightMinor>
</ShippingPackageDetails>
<SubTitle> string </SubTitle>
<TaxCategory> string </TaxCategory>
<Variations> VariationsType
<Pictures> PicturesType
<VariationSpecificName> string </VariationSpecificName>
<VariationSpecificPictureSet> VariationSpecificPictureSetType
<PictureURL> anyURI </PictureURL>
<!-- ... more PictureURL values allowed here ... -->
<VariationSpecificValue> string </VariationSpecificValue>
</VariationSpecificPictureSet>
<!-- ... more VariationSpecificPictureSet nodes allowed here ... -->
</Pictures>
<Variation> VariationType
<DiscountPriceInfo> DiscountPriceInfoType
<MadeForOutletComparisonPrice> AmountType (double) </MadeForOutletComparisonPrice>
<MinimumAdvertisedPrice> AmountType (double) </MinimumAdvertisedPrice>
<MinimumAdvertisedPriceExposure> MinimumAdvertisedPriceExposureCodeType </MinimumAdvertisedPriceExposure>
<OriginalRetailPrice> AmountType (double) </OriginalRetailPrice>
<SoldOffeBay> boolean </SoldOffeBay>
<SoldOneBay> boolean </SoldOneBay>
</DiscountPriceInfo>
<Quantity> int </Quantity>
<SKU> SKUType (string) </SKU>
<StartPrice> AmountType (double) </StartPrice>
<VariationSpecifics> NameValueListArrayType
<NameValueList> NameValueListType
<Name> string </Name>
<Value> string </Value>
<!-- ... more Value values allowed here ... -->
</NameValueList>
<!-- ... more NameValueList nodes allowed here ... -->
</VariationSpecifics>
<!-- ... more VariationSpecifics nodes allowed here ... -->
</Variation>
<!-- ... more Variation nodes allowed here ... -->
<VariationSpecificsSet> NameValueListArrayType
<NameValueList> NameValueListType
<Name> string </Name>
<Value> string </Value>
<!-- ... more Value values allowed here ... -->
</NameValueList>
<!-- ... more NameValueList nodes allowed here ... -->
</VariationSpecificsSet>
</Variations>
<VIN> string </VIN>
</Item>
<!-- Standard Input Fields -->
<ErrorLanguage> string </ErrorLanguage>
<MessageID> string </MessageID>
<Version> string </Version>
<WarningLevel> WarningLevelCodeType </WarningLevel>
</VerifyAddFixedPriceItemRequest>
| Argument | Type | Occurrence | Meaning |
|---|
| Call-specific Input Fields [Jump to standard fields] |
| Item | ItemType | Required | Root container holding all values that define a new fixed-price listing. |
| Item.ConditionDescription | string | Optional |
This string field is used by the seller to more clearly describe the condition of items that are not brand new. The ConditionDescription field is available for all categories, including categories where the condition type is not applicable (e.g., Antiques). This field is applicable for all item conditions except "New", "Brand New", "New with tags", and "New in box". If ConditionDescription is used with these conditions (Condition IDs 1000-1499), eBay will simply ignore this field if included, and eBay will return a warning message to the user. This field should only be used to further clarify the condition of the used item. For example, "The right leg of the chair has a small scratch, and on the seat back there is a light blue stain about the shape and size of a coin." It should not be used for branding, promotions, shipping, returns, payment or other information unrelated to the condition of the item. Make sure that the condition type (Item.ConditionID), condition description, item description (Item.Description), and the listing's pictures do not contradict one another. Note: The ConditionDescription field is optional For Add/Revise/Relist API calls. However, this field may become required in some categories starting with the Spring 2013 Seller Release. ConditionDescription is currently supported only on the eBay US, UK and Motors sites. The ConditionDescription field is returned by GetItem (and other related calls that return the Item object) if a condition description is specified in the listing. Max length: 1000. |
| Item.ConditionID | int | Conditional |
The numeric ID (e.g., 1000) for the item condition. Sellers should also clarify the item's condition in their own item description. Note: In addition to including notes on flaws or wear and tear on an used item in the Item.Description, and including a ConditionID value, you can provide additional information about the condition of your used item through the Item.ConditionDescription string field. For the AddItem family of calls: Use GetCategoryFeatures for details about which categories support (or require) ConditionID, plus policies and help on choosing the right condition for the item (to reduce disputes). Please note the following behavior if you pass a ConditionID value that is not valid for the category: If ConditionID is disabled (or not applicable) for the category, the item is listed with no condition. If ConditionID is enabled or required for the category, the listing request fails. If you are listing in two categories, the primary category determines which condition model (ConditionID or item specifics) and which condition values can be used. US eBay Motors Parts & Accessories and vehicle categories require ConditionID for new listings and re-listings. Not applicable to Half.com in listing requests (e.g., AddItem). However, ConditionID could be returned in responses for Half.com listings that are available to or sold on the eBay site (as appropriate for the corresponding eBay category). For Revise/Relist calls: In most cases, you can add or modify ConditionID when you revise or relist. If GetCategoryFeatures returns ConditionEnabled=Required for the listing's category, you cannot remove ConditionID from the listing. If an auction has bids or ends within 12 hours, you cannot remove or change its condition, and you cannot replace a condition attribute or custom item specific with ConditionID. In this case, you will still be able to modify other fields that are normally editable, even if ConditionID is not present. In most cases, you can add or modify ConditionID for multi-quantity fixed price listings. (If a multi-quantity fixed price listing has revision restrictions imposed by other choices the seller has made in the listing, you might not be able to remove or change the condition.) If you revise or relist a GTC listing that only has a condition attribute or custom item specific, you need to specify ConditionID (if the category requires it). ReviseInventoryStatus also fails if you attempt to revise listings that are missing ConditionID. (This rule does not apply during auto-renewal of a GTC listing. It only applies when you perform an action on the listing.) For GetItem and GetSellerList: Only returned when the seller specified ConditionID in their listing. Also returns a localized display name. Note: For most categories, eBay does not convert item condition data in the older AttributeSetArray, LookupAttributeArray, or ItemSpecifics format to this format in older listings or when you revise or relist items. This means GTC listings and older ended or sold listings may still return the item condition in these other fields even after new listings only support ConditionID. There are a few categories in which automatic mapping does occur, where the old and newer conditions are identical. See the "Automatic Mapping" tab in the Item Condition Look-up Table link below for details. Also, if you specified ConditionID but the category also supports condition in item specifics, you may receive a "Dropped condition from Item specifics" warning. You can ignore this warning as long as you used ConditionID. See:
|
| Item.DiscountPriceInfo | DiscountPriceInfoType | Optional |
This container provides information for an item that has a Strikethrough Price (STP) or a Minimum Advertised Price (MAP) discount pricing treatment. STP and MAP apply only to fixed-price listings and auction listings with the Buy It Now opton. STP is available on the US, UK, and German (DE) sites, while MAP is available only on the US site. Discount pricing is available to qualified sellers (and their associated developers) who participate in the Discount Pricing Program. Once qualified, sellers receive a "special account flag" (SAF) that allows them to apply Discount Pricing to both single-variation and multi-variation items. Sellers should contact their account manager or Customer Service to see if they qualify for the Strikethrough Pricing program. As a seller listing Discount Price items, you are required to maintain records of your discount pricing in the event you are called upon to substantiate your item pricing. The following link details your legal obligations when you utilize Discount Pricing to sell items: Strikethrough Pricing Requirements For AddFixedPriceItem, RelistFixedPriceItem, ReviseFixedPriceItem, and VerifyAddFixedPriceItem: If you are listing variations (MSKU items), use Variation.DiscountPriceInfo for each variation. |
|
Item.DiscountPriceInfo .MadeForOutletComparisonPrice |
AmountType (double) | Conditional |
Applicable only if the item was specifically made for sale through dedicated eBay outlet pages (e.g., eBay Fashion Outlet). The comparison price is the price of a comparable product sold through non-outlet channels on eBay (or elsewhere), or not specifically made for the outlet. In fashion, a "comparable" product shares the same design, but is not considered an identical product. Some products are specifically made for outlets, and may have a different SKU than the "comparable" product. These made-for-outlet products may be manufactured in a different place, with different materials, or according to different specifications (i.e. different stitch pattern, seam reinforcement, button quality, etc.) |
|
Item.DiscountPriceInfo .MinimumAdvertisedPrice |
AmountType (double) | Conditional | 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 offer prices below MAP by means of other discounts. This only applies to fixed-price listings and auction listings with the Buy It Now option. |
|
Item.DiscountPriceInfo .MinimumAdvertisedPriceExposure |
MinimumAdvertisedPriceExposureCodeType | Conditional |
For MinimumAdvertisedPrice (MAP) listings only. A seller cannot show the actual discounted price on eBay's View Item page. Instead, the buyer can either click on a pop-up on eBay's View Item page, or the discount price will be shown during checkout.
Applicable values: • CustomCode (in/out) Reserved for future use. • DuringCheckout (in/out) DuringCheckout specifies that the discounted price must be shown on the eBay checkout flow page. • None (in/out) None means the discount price is not shown via either PreCheckout nor DuringCheckout. • PreCheckout (in/out) PreCheckout specifies that the buyer must click a link (or a button) to navigate to a separate page (or window) that displays the discount price. eBay displays the discounted item price in a pop-up window. |
|
Item.DiscountPriceInfo .OriginalRetailPrice |
AmountType (double) | Conditional | The actual retail price set by the manufacturer (OEM). eBay does not maintain or validate the OriginalRetailPrice supplied by the seller. OriginalRetailPrice should always be more than StartPrice. Compare the StartPrice/BuyItNowPrice to OriginalRetailPrice to determine the amount of savings to the buyer. |
|
Item.DiscountPriceInfo .SoldOffeBay |
boolean | Conditional |
Used by the eBay UK and eBay Germany (DE) sites, this flag indicates that the discount price (specified as StartPrice) is the price for which the seller offered the same (or similar) item for sale on a Web site or offline store other than eBay in the previous 30 days. The discount price is always in reference to the seller's own price for the item. If this field is set to 'true', eBay displays 'Was*' in the UK and 'Ursprunglich*' in Germany, next to the discounted price of the item. In the event both SoldOffeBay and SoldOneBay fields are set, SoldOneBay takes precedence. Default: false. |
|
Item.DiscountPriceInfo .SoldOneBay |
boolean | Conditional |
Used by the eBay UK and eBay Germany (DE) sites, this flag indicates that the discount price (specified as StartPrice) is the price for which the seller offered the same (or similar) item for sale on eBay within the previous 30 days. The discount price is always in reference to the seller's own price for the item. If this field is set to 'true', eBay displays 'Was' in the UK and 'Ursprunglich' in Germany, next to the discounted price of the item. In the event both SoldOffeBay and SoldOneBay fields are set to 'true', SoldOneBay takes precedence. Default: false. |
| Item.IncludeRecommendations | boolean | Optional |
If this field is included and set to 'true' in the request of an Add/Revise/Relist/Verify API call, the call response will include any listing recommendations that will help the seller improve the quality of the listing. The type of listing recommendations include the following:
Default: false. |
| Item.ProductListingDetails | ProductListingDetailsType | Optional |
Specifies stock product information to include in a listing. Only applicable when listing items with product details. See the eBay Trading API Guide for information on listing with product details. As ProductID and ProductReferenceID are defined by eBay, they provide the most reliable means to identify a product. If you use one of the other industry identifiers (e.g., UPC), eBay attempts to find a matching product on your behalf and use it in the listing. If no match is found, you can try using FindProducts in the Shopping API to determine a ProductReferenceID. When you specify ProductListingDetails, you must specify at least one of the available identifiers (e.g., UPC). If you specify more than one (such as UPC and BrandMPN), eBay uses the first one that matches a product in eBay's catalog system. (This may be useful if you aren't sure which identifier is more likely to result in a match.) When you specify TicketListingDetails, you must specify the Event Tickets category as the primary category. For other product identifiers: If you list in two categories and the primary and secondary categories are both catalog-enabled, this product identifier should correspond to the primary category (not the secondary category). If only one category is catalog-enabled, the product identifier should correspond to the catalog-enabled category. Note: As a general rule, the primary category is required. However, if you have trouble finding a catalog-enabled category, you may be able to omit the primary category (except for event tickets). If you do, eBay will attempt to determine an appropriate category based on the product ID (if we find a matching product). When you specify a category that corresponds to the product, your category is used. If we don't find a match in our catalogs, we will list the item in the primary category you specified, without product details. We will not pre-fill the listing's item specifics in this case, and the identifier won't be surfaced in View Item or returned in GetItem. However, it will still be indexed for search on eBay, and it will be searchable by more third-party natural search engines. As this can help buyers find your listing more easily, we strongly recommend that you always use ProductListingDetails to pass in these values. (This product indexing behavior is only available if you use UPC, ISBN, EAN, or GTIN in ProductListingDetails. It is not available if you use ExternalProductID, and it may not be available if you exclusively use Item Specifics.) Either Item.ExternalProductID or Item.ProductListingDetails can be specified in an AddItem request, but not both. (ExternalProductID is no longer recommended.) For ReviseItem and RelistItem only: If a listing includes product details and you change a category, the rules for continuing to include product details depend on whether or not the new category is mapped to a characteristic set associated with the same product ID. When you revise a listing, if it has bids or it ends within 12 hours, you cannot change the product ID and you cannot remove existing product data. However, you can change or add preferences such as IncludeStockPhotoURL, UseStockPhotoURLAsGallery, and IncludePrefilledItemInformation. To delete all catalog data when you revise or relist an item, specify Item.ProductListingDetails in DeletedField and don't pass ProductListingDetails in the request. For GetMyeBayBuying only: When products have been added to a buyer's Wish List, the product information is returned in ItemArray.Item.ProductListingDetails within the UserDefinedList node. Products can be added to a buyer's Wish List only. Does not apply to any other user-defined list. The ProductListingDetails node is not included for items in the Wish List. Not applicable to Half.com. |
|
Item.ProductListingDetails .IncludePrefilledItemInformation |
boolean | Optional |
If true, specifies that the listing should include additional information about the product, such as a publisher's description or film credits. Such information is hosted through the eBay site and cannot be edited. If true, Item.Description is optional in item-listing requests. For GetItem and related calls: The eBay site shows the catalog product description in the product details section of a listing. You cannot download this pre-filled description text via the API. To retrieve a URL for the catalog product details page, see DetailsURL in GetProductSearchResults, GetProductFamilyMembers, or GetProductSellingPages. Or see DetailsURL in FindProducts in the Shopping API (which may be easier to use if your application doesn't support eBay Attributes). Default: true. |
|
Item.ProductListingDetails .IncludeStockPhotoURL |
boolean | Optional |
If true, indicates that the item listing includes the stock photo. To use an eBay stock photo in an item listing, set IncludeStockPhotoURL to true. If a stock photo is available, it is used at the top of the View Item page and in the Item Specifics section of the listing. If you also include Item.PictureDetails.PictureURL, the stock photo only appears in the Item Specifics section of the listing. Other pictures you specify by using Item.PictureDetails.PictureURL appear in a separate section of the listing. If you use Item.ExternalProductID instead of Item.ProductListingDetails, eBay sets IncludeStockPhotoURL to true (and you cannot set it to false). In GetItem, the URL of the stock photo will be returned in StockPhotoURL. If you set IncludeStockPhotoURL to false, the stock photo does not appear in the listing at all. Note: The following sites offer free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146). On these sites, eBay selects a Gallery thumbnail from image URLs included in the request (i.e. either GalleryURL or the first PictureURL), using selection rules that consider which of these URLs has been specified and whether an eBay stock photo exists for the item. Also, eBay selects an image regardless of whether you have specified either GalleryType or GalleryURL. A Gallery fee will only apply if you have set GalleryType to Plus or Featured (as basic Gallery is free). Along with these changes, IncludeStockPhotoURL will be used in the request. In some cases, if IncludeStockPhotoURL is set to false, no image will be generated for the Gallery. A common example of this occurrence is when only GalleryURL has been set in the request (i.e., no PictureURL elements are defined). In this case, eBay will not use a stock photo, even if it is available. See "Using Gallery Features on Sites with Free Gallery" in the eBay Web Services Guide for complete information. Not applicable to Half.com. Default: true. See:
|
|
Item.ProductListingDetails .ProductID |
string | Conditional |
eBay's unique identifier for a specific version of a product. This is the long alphanumeric ID that is returned from GetProductSearchResults and related calls. See the Trading API Guide for information about finding this type of product ID. (For the shorter product ID (ePID) value that is displayed on the eBay Web site, see ProductReferenceID instead.) If the primary and secondary categories are both catalog-enabled, this ID should correspond to the primary category (not the secondary category). In item-listing requests, if you pass in an old product ID, eBay lists the item with the latest version of the product and the latest product ID, and the call returns a warning indicating that the data has changed. Some sites (such as eBay US, Germany, Austria, and Switzerland) are updating, replacing, deleting, or merging some products (as a result of migrating from one catalog data provider to another). If you specify one of these products in a request, the call may return the product with a warning, or it may fail with an error if the product has been deleted. Max length: 4000. |
|
Item.ProductListingDetails .UseStockPhotoURLAsGallery |
boolean | Optional |
If true, indicates that the stock photo for an item (if available) is used as the gallery thumbnail. When listing an item, IncludeStockPhotoURL must also be true and Item.PictureDetails.GalleryType must be passed in with a value of Gallery or Gallery Featured (but not both). See the eBay Trading API guide for additional validation rules for pictures. Note: The following sites offer free Gallery: US (site ID 0), the Parts & Accessories Category on US Motors (site ID 100), CA (site ID 2), CAFR (site ID 210), ES (site ID 186), FR (site ID 71), IT (site ID 101),and NL (site ID 146). On these sites, eBay selects a Gallery thumbnail from image URLs included in the request (i.e. either GalleryURL or the first PictureURL), using selection rules that consider which of these URLs has been specified and whether an eBay stock photo exists for the item. Also, eBay selects an image regardless of whether you have specified either GalleryType or GalleryURL. A Gallery fee will only apply if you have set GalleryType to Plus or Featured (as basic Gallery is free). Along with these changes, UseStockPhotoURLAsGallery will be used in the request. In some cases, if UseStockPhotoURLAsGallery is set to false, no image will be generated for the Gallery. A common example of this occurrence is when only GalleryURL has been set in the request (i.e., no PictureURL elements are defined). In this case, eBay will not use a stock photo, even if it is available. See "Using Gallery Features on Sites with Free Gallery" in the eBay Web Services Guide for complete information. Default: true. See:
|
| Item.QuantityInfo | QuantityInfoType | Optional |
This container is used to set the minimum number of event tickets that should remain available after a buyer makes a purchase. This functionality allows the seller to avoid the possibility of being left with just one event ticket after a sale. This container can be used when adding, revising, or relisting event tickets, and it will only be returned in GetItem if set for the listing. |
|
Item.QuantityInfo .MinimumRemnantSet |
int | Conditional |
Enables you (the seller) to avoid being left with 1 item in your listing. A typical use case is event tickets in reserved, adjacent seats, or items that typically only sell if more than 1 can be purchased at once. Specify the minimum number of items that should remain if a buyer doesn't purchase all the items. Based on the value of MinimumRemnantSet and the listing's available quantity (Quantity-QuantitySold), eBay calculates how many items a buyer can purchase. For example, suppose you list 5 tickets, and you want at least 2 tickets remaining for the final buyer to purchase. In this case, you would set MinimumRemnantSet to 2. This means a buyer can purchase 1, 2, 3, or 5 tickets, but not 4 (because 4 would leave the seller with 1 ticket). To remove this restriction when you revise or relist, set MinimumRemnantSet to 1. Applicable to multi-quantity, fixed-price listings. Currently supported for US and CA event ticket listings. Default: 1. |
|
Item .QuantityRestrictionPerBuyer |
QuantityRestrictionPerBuyerInfoType | Optional |
This container is used by the seller to restrict the quantity of items that may be purchased by one buyer during the duration of a fixed-price listing (single or multi-variation). This is an optional container that can be used with an Add, Revise, or Relist call. This container is not applicable to auction listings. |
|
Item .QuantityRestrictionPerBuyer .MaximumQuantity |
int | Conditional |
This integer value indicates the maximum quantity of items that a single buyer may purchase during the duration of a fixed-price listing (single or multi-variation). The buyer is blocked from the purchase if that buyer is attempting to purchase a quantity of items that will exceed this value. Previous purchases made by the buyer are taken into account. For example, if MaximumQuantity is set to '5' for an item listing, and Buyer1 purchases a quantity of three, Buyer1 is only allowed to purchase an additional quantity of two in subsequent orders on the same item listing. This field is required if the QuantityRestrictionPerBuyer container is used. Min: 1. |
| Item.ReturnPolicy | ReturnPolicyType | Conditional |
Container that describes the seller's return policy. Most categories on most eBay sites require the seller to include a return policy through the ReturnPolicy container. For the AddItem family of calls: Required for most categories on most sites. Use ReturnPolicyEnabled in GetCategoryFeatures to determine which categories require this field. To determine which ReturnPolicy fields can be used on each site, call GeteBayDetails with DetailName set to ReturnPolicyDetails. eBay India (IN), Australia (AU), and US eBay Motors Parts and Accessories categories typically support but do not require a return policy. (However, we strongly recommend that you specify a clear return policy whenever possible.) For ReviseItem only: If the listing has bids or sales and it ends within 12 hours, you can't change the return policy details. If the listing is a GTC listing that has sales or ends within 12 hours (one or the other, but not both), you can add a return policy to the GTC listing (but you can't change return policy details if already present). If the listing has no bids or sales and more than 12 hours remain before the listing ends, you can add or change the return policy. When you revise your return policy, you only need to specify the fields you want to add or change. You don't need to specify all the other ReturnPolicy fields again. The other fields will retain their existing settings. For the GetItem family of calls: Only returned if the site you sent the request to supports the seller's return policy. Typically, the return policy details are only returned when the request is sent to the listing site. See:
|
| Item.ReturnPolicy.Description | string | Optional |
A detailed explanation of the seller's return policy. eBay uses this text string as-is in the Return Policy section of the View Item page. Avoid HTML, and avoid character entity references (such as £ or £). If you include special characters in the return policy description, use the literal UTF-8 or ISO-8559-1 character (e.g. £). For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but does not specify this field when listing the item, GetItem returns this as an empty node For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. Max length: 5000. See (GeteBayDetails) ReturnPolicyDetails.Description for sites that support this field. |
| Item.ReturnPolicy.EAN | string | Optional |
The European Article Number (EAN) associated with the item, if any. To determine if your site supports this field, call GeteBayDetails with DetailName set to ReturnPolicyDetails, and then look for a 'true' value in the ReturnPolicyDetails.EAN field. Only returned if the seller has specified this value in their return policy. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. |
| Item.ReturnPolicy.RefundOption | token | Optional |
Indicates how the seller will compensate the buyer for a returned item. Use the ReturnPolicy.Description field to explain the policy details (such as how quickly the seller will process the refund, whether the seller must receive the item before processing the refund, and other useful details.). The RefundOption field is not supported by any of the European sites. Applicable values: To get the applicable RefundOption values for your site, call GeteBayDetails with DetailName set to ReturnPolicyDetails, and then look for the ReturnPolicyDetails.Refund.RefundOption fields in the response. For Add/Revise/Relist/VerifyAdd API calls): If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this RefundOption field when listing the item, some eBay sites may set a default value (like 'MoneyBack'), and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. For Revise calls only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. Note: As of version 771, listings created, revised, or relisted on the US site with deprecated RefundOption and/or ReturnsWithinOption values (using Add/Revise/Relist API calls) will be blocked. For RefundOption, the deprecated values for the US site are MerchandiseCredit and Exchange. Instead of these deprecated values, the seller must offer a MoneyBack or a MoneyBackOrExchange refund option. Consider using the MoneyBackOrExchange option when you have the depth of inventory to support an exchange for a different size, color, or undamaged unit. Otherwise, use the MoneyBack option if you have limited inventory. See (GeteBayDetails) RefundOption. Applicable values: See RefundOptionsCodeType |
|
Item.ReturnPolicy .RestockingFeeValueOption |
token | Optional |
This enumeration value indicates the restocking fee charged by the seller for returned items. In order to charge the buyer a restocking fee when an item is returned, a US seller must input a restocking fee value as part of the return policy. For Add/Revise/Relist calls: To obtain the list of applicable values, call GeteBayDetails with DetailName set to ReturnPolicyDetails. Then look for the list of restocking fee value options in the ReturnPolicyDetails.RestockingFeeValue container in the response. For Get calls: The RestockingFeeValue field is directly related to RestockingFeeValueOption, and gives a user-friendly description of the restocking fee policy. See GeteBayDetails.ReturnPolicyDetails for applicable values for RestockingFeeValueOption. Applicable values: See RestockingFeeCodeType |
|
Item.ReturnPolicy .ReturnsAcceptedOption |
token | Conditional |
Indicates whether the seller allows the buyer to return the item. This field is required when ReturnPolicy is specified. (If you specify ReturnsNotAccepted, the View Item page may initially show the return policy as unspecified. In a future release, the View Item page will be updated to indicate that returns are not accepted instead.) All sites support the ability for a seller to not accept returns. If the seller doesn't accept returns, the item must specifically indicate ReturnsNotAccepted. (The return policy cannot be omitted from the item.) On the eBay UK and Ireland sites, business sellers must accept returns for fixed price items (including auction items with Buy It Now, and any other fixed price formats) when the category requires a return policy. On some European sites (such as eBay Germany (DE)), registered business sellers are required to accept returns. Your application can call GetUser to determine a user's current business seller status. Note: In order for Top-Rated sellers to receive a Top-Rated Plus seal for their listings, returns must be accepted for the item (ReturnsAcceptedOption=ReturnsAccepted) and handling time should be set to one day (or zero days when same-day shipping becomes available in late May). The handling time is set through the Item.DispatchTimeMax field. Top-Rated listings qualify for the greatest average boost in Best Match and for the 20 percent Final Value Fee discount. For more information on changes to eBay's Top-Rated seller program, see the Becoming a Top Rated Seller and qualifying for Top Rated Plus page. Applicable values: To get the applicable ReturnsAcceptedOption values for your site, call GeteBayDetails with DetailName set to ReturnPolicyDetails, and then look for the ReturnPolicyDetails.ReturnsAccepted.Description fields in the response. ReturnsAcceptedOptionsCodeType defines all the possible values. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See:
Applicable values: See ReturnsAcceptedOptionsCodeType |
|
Item.ReturnPolicy .ReturnsWithinOption |
token | Conditional |
The buyer can return the item within this period of time from the day they receive the item. Use the ReturnPolicy.Description field to explain the policy details. Applicable values: To get the applicable ReturnsWithinOption values for your site, call GeteBayDetails with DetailName set to ReturnPolicyDetails, and then look for the ReturnPolicyDetails.ReturnsWithin.ReturnsWithinOption fields in the response. ReturnsWithinOptionsCodeType defines all the possible values. For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this ReturnsWithinOption field when listing the item, some eBay sites may set a default value (like Days_14), and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. Note: As of version 771, listings created, revised, or relisted with deprecated RefundOption and/or ReturnsWithinOption values (using Add/Revise/Relist API calls) will be blocked. For ReturnsWithinOption, the deprecated values are Days_3 and Days_7. Instead of these deprecated values, the seller must offer a 14-day, 30-day, or 60-day return window. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) ReturnsWithinOption. Applicable values: See ReturnsWithinOptionsCodeType |
|
Item.ReturnPolicy .ShippingCostPaidByOption |
token | Optional |
The party who pays the shipping cost for a returned item. Use the ReturnPolicy.Description field to explain any additional details. Applicable values: To get the applicable ShippingCostPaidByOption values for your site, call GeteBayDetails with DetailName set to ReturnPolicyDetails, and then look for the ReturnPolicyDetails.ShippingCostPaidBy.ShippingCostPaidByOption fields in the response. ShippingCostPaidByOptionsCodeType defines all the possible values. For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this ShippingCostPaidByOption field when listing the item, some eBay sites may set a default value (like Buyer), and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) ShippingCostPaidByOption for sites that support this field, and applicable values. Applicable values: See ShippingCostPaidByOptionsCodeType |
|
Item.ReturnPolicy .WarrantyDurationOption |
token | Optional |
The warranty period. Applicable values: To get the applicable WarrantyDurationOption values for your site, call GeteBayDetails with DetailName set to ReturnPolicyDetails, and then look for the ReturnPolicyDetails.WarrantyDuration. WarrantyDurationOption fields in the response. WarrantyDurationOptionsCodeType defines all the possible values. For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this WarrantyDurationOption field when listing the item, the eBay India site may set a default value, and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) WarrantyDurationOption. Applicable values: See WarrantyDurationOptionsCodeType |
|
Item.ReturnPolicy .WarrantyOfferedOption |
token | Optional |
Indicates whether a warranty is offered for the item. Applicable values: To get the applicable WarrantyOfferedOption values for your site, call GeteBayDetails with DetailName set to ReturnPolicyDetails, and then look for the ReturnPolicyDetails.WarrantyOffered.WarrantyOfferedOption fields in the response. WarrantyOfferedCodeType defines all the possible values. Note: Only the eBay India site supports this field. For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this WarrantyOfferedOption field when listing the item, the eBay India site may set a default value, and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. Note: For the US eBay Motors limited warranty (Short-Term Service Agreement) option, use Item.LimitedWarrantyEligible instead. For the US eBay Motors "Is There an Existing Warranty?" option, use Item.AttributeSetArray instead. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See:
Applicable values: See WarrantyOfferedCodeType |
|
Item.ReturnPolicy .WarrantyTypeOption |
token | Optional |
Indicates the source or type of the warranty, if any. Applicable values: To get the applicable WarrantyTypeOption values for your site, call GeteBayDetails with DetailName set to ReturnPolicyDetails, and then look for the ReturnPolicyDetails.WarrantyType.WarrantyTypeOption fields in the response. WarrantyTypeOptionsCodeType defines all the possible values. Note: Only the eBay India site supports this field. For AddItem, VerifyAddItem, and RelistItem: If the seller accepts returns (ReturnsAcceptedOption=ReturnsAccepted) but you do not pass in this WarrantyTypeOption field when listing the item, the eBay India site may set a default value, and the seller is obligated to honor this setting. Therefore, to avoid unexpected obligations, the seller should set a specific value for this field. For ReviseItem only: If the listing has bids or sales and/or ends within 12 hours, you can't change this value. See the parent ReturnPolicy node description for more details. See (GeteBayDetails) WarrantyTypeOption for sites that support this field, and applicable values. Applicable values: See WarrantyTypeOptionsCodeType |
| Item.ScheduleTime | dateTime | Optional |
Allows the user to specify the time that the listing becomes active on eBay. To schedule the listing start time, specify a time in the future in GMT format. In GetItem and related calls, the scheduled time is returned in StartTime. For ReviseItem, you can modify this value if the currently scheduled start time is in the future. When you schedule a start time, the start time is randomized within 15-minute intervals. Randomized start times applies to the following sites: AT, BEFR, BENL, CH, DE, ES, FR, IE, IT, NL, PL, UK Also see the following article in the Knowledge Base: Why scheduled time is sometimes getting reset. Not applicable to Half.com. |
| Item.ShippingPackageDetails | ShipPackageDetailsType | Conditional | Container consisting of dimension and size details related to a shipping package in which an item will be sent. The information in this container is applicable if the seller is using calculated shipping or flat rate shipping using shipping rate tables with weight surcharges. This container is only returned in the "Get" calls if specified for the item. |
|
Item.ShippingPackageDetails .MeasurementUnit |
MeasurementSystemCodeType | Conditional |
Specifies the unit type of the weight and dimensions of a shipping package. If MeasurementUnit is used, it overrides the system specified by measurementSystem. If MeasurementUnit and measurementSystem are not specified, the following defaults will be used: English: US Metric: CA, CAFR, AU CA and CAFR supports both English and Metric, while other sites only support the site's default. Use MeasurementUnit with weight and package dimensions. For example, to represent a 5 lbs 2 oz package: <MeasurementUnit>English</MeasurementUnit> <WeightMajor>5</WeightMajor> <WeightMinor>2</WeightMinor> Applicable values: • English (in/out) English system of measurement. • Metric (in/out) Metric system of measurement. |
|
Item.ShippingPackageDetails .PackageDepth |
MeasureType (decimal) | Conditional |
Depth of the package, in whole number of inches, needed to ship the item. This is validated against the selected shipping service. Upon mismatch, a message is returned, such as, "Package dimensions exceeds maximum allowable limit for service XXXXX," where XXXXX is the name of the shipping service. For calculated shipping only. Only returned if the seller specified the value for the item. (In many cases, the seller only specifies the weight fields.) Developer impact: UPS requires dimensions for any Ground packages that are 3 cubic feet or larger and for all air packages, if they are to provide correct shipping cost. If package dimensions are not included for an item listed with calculated shipping, the shipping cost returned will be an estimate based on standard dimensions for the defined package type. eBay enforces a dimensions requirement on listings so that buyers receive accurate calculated shipping costs. |
|
Item.ShippingPackageDetails .PackageLength |
MeasureType (decimal) | Conditional | Length of the package, in whole number of inches, needed to ship the item. Upon mismatch, a message is returned, such as, "Package dimensions exceeds maximum allowable limit for service XXXXX," where XXXXX is the name of the shipping service. For calculated shipping only. Only returned if the seller specified the value for the item. (In many cases, the seller only specifies the weight fields.) |
|
Item.ShippingPackageDetails .PackageWidth |
MeasureType (decimal) | Conditional | Width of the package, in whole number of inches, needed to ship the item. Upon mismatch, a message is returned, such as, "Package dimensions exceeds maximum allowable limit for service XXXXX," where XXXXX is the name of the shipping service. For calculated shipping only. Only returned if the seller specified the value for the item. (In many cases, the seller only specifies the weight fields.) |
|
Item.ShippingPackageDetails .ShippingIrregular |
boolean | Optional | Whether a package is irregular and therefore cannot go through the stamping machine at the shipping service office and thus requires special or fragile handling. For calculated shipping only. |
|
Item.ShippingPackageDetails .ShippingPackage |
ShippingPackageCodeType | Conditional |
The nature of the package used to ship the item(s). Required for calculated shipping only.
Applicable values: See ShippingPackage. |
|
Item.ShippingPackageDetails .WeightMajor |
MeasureType (decimal) | Conditional |
WeightMajor and WeightMinor are used to specify the weight of a shipping package. Here is how you would represent a package weight of 5 lbs 2 oz: <WeightMajor unit="lbs">5</WeightMajor> <WeightMinor unit="oz">2</WeightMinor> See http://www.ups.com for the maximum weight allowed by UPS. Above this maximum, the shipping type becomes Freight, an option that can only be selected via the eBay Web site and not via API. The weight details are validated against the selected shipping service. For calculated shipping or for flat rate shipping if shipping rate tables are specified and the shipping rate table uses weight surcharges. Required on input when calculated shipping is used. |
|
Item.ShippingPackageDetails .WeightMinor |
MeasureType (decimal) | Conditional |
See the definition of WeightMajor. For calculated shipping or for flat rate shipping if shipping rate tables are specified and the shipping rate table uses weight surcharges. (When used with the shipping rate tables with weight surcharge, any WeightMinor value greater than zero results in WeightMajor getting rounded up in the shipping cost calculation for example, 1 lb, 2 oz is rounded up to 2 lbs.) Required on input when calculated shipping is used. |
| Item.SubTitle | string | Optional |
Subtitle to use in addition to the title. Provides more keywords when buyers search in titles and descriptions. You cannot use HTML in the Subtitle. (HTML characters will be interpreted literally as plain text.) If you pass any value, this feature is applied (with applicable fees). Not applicable to listings in US eBay Motors passenger vehicle, motorcycle, and "other vehicle" categories or to listings in CA eBay Motors passenger vehicle and motorcycle categories. For eBay Motors categories that do not support this field, use Item Specifics (AttributeSetArray) to specify the vehicle subtitle. When you revise a item, you can add, change, or remove the subtitle. Not applicable to Half.com. Max length: 55. See:
|
| Item.TaxCategory | string | Conditional | Tax exception category code. 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. |
| Item.Variations | VariationsType | Optional |
Variations are multiple similar (but not identical) items in a single fixed-price listing. For example, a T-shirt listing could contain multiple items of the same brand that vary by color and size (like "Blue, Large" and "Black, Medium"). Each variation specifies a combination of one of these colors and sizes. Each variation can have a different quantity and price. You can buy multiple items from one variation at the same time. (That is, one order line item can contain multiple items from a single variation.) If you list in two categories, both categories must support listing with variations. See VariationsEnabled in GetCategoryFeatures to determine applicable categories. For ReviseFixedPriceItem and RelistFixedPriceItem: Once a listing has been submitted with variations, you can't delete all the variations when you revise or relist the listing (because it would be considered a different listing). However, you can delete or replace individual variations as needed to match your current inventory. If a variation has no purchases, use the Variation.Delete field to delete the variation. If it has inventory, set the Quantity to 0. As a best practice, if you want to revise multiple variations in the same listing at the same time (i.e, within a very short period), use a single ReviseFixedPriceItem request and include all the variation revisions in the same request. If your application design requires you to revise each variation individually, then avoid using multiple parallel threads. Instead, use a serial, synchronous process. That is, wait until each revision has been processed by eBay before submitting the next revision request for another variation in the same listing. For GetItem and related calls Only returned when a listing has variations. For GetSellerList: Only returned when a listing has variations, IncludeVariations was set to true in the request, the DetailLevel was set to ReturnAll, and an applicable pagination value and time range were specified. For GetItemTransactions Only returned in Item when a listing has variations and IncludeVariations was set to true in the request. (Also see Variation returned in Transaction for information about which variation was actually purchased.) For GetSellerEvents, GetMyeBayBuying, and GetMyeBaySelling: Only returned when a listing has variations and HideVariations was set to false or not specified in the request. See:
|
| Item.Variations.Pictures | PicturesType | Optional |
Contains a set of pictures that correspond to one of the variation specifics, such as Color. For example, if a listing has blue and black color variations, you could choose Color for all the pictures, and then include a set of pictures for the blue variations and another set of pictures for the black variations. We strongly recommend that you also include shared pictures in Item.PictureDetails, as this results in a better experience for buyers. For ReviseFixedPriceItem only: To replace or delete individual pictures, pass in the entire Pictures node with the complete set of variation pictures that you want in the listing. If the applicable variations have purchases or the listing ends in less than 12 hours, you can add pictures, but you can't remove existing pictures. Variation, Pictures, or ModifyNameList (or all) need to be specified when the Variations node is specified in listing requests Note: Only one Pictures node is allowed for a listing. However, the node has been defined as unbounded (repeatable) in the schema to allow for different use cases for some calls or sites in the future. |
|
Item.Variations.Pictures .VariationSpecificName |
string | Conditional |
One aspect of the variations that will be illustrated in the pictures for all variations. For example, if each variation is visually distinguished by color and the pictures show the different colors available, then specify "Color" as the name. The name must match one of the names specified in the VariationSpecifics container. This field is required in each Item.Variations.Pictures container that is used. Max length: 40. |
|
Item.Variations.Pictures .VariationSpecificPictureSet |
VariationSpecificPictureSetType | Conditional,
repeatable: [0..*] |
A container consisting of one or more picture URLs associated with a variation specific value (e.g., color=blue). For example, suppose a listing contains blue and black color variations, and VariationSpecificName= Color. In this case, one picture set could contain pictures of the blue shirts (e.g., front view, back view, and close-up of a trim detail), and another picture set could contain pictures of the black shirts. A variation specific picture set can consist of up to 12 images hosted by eBay Picture Services (EPS). However, only one picture may be used if that picture is hosted outside of eBay. eBay Picture Services and self-hosted images can never be combined into the same variation specific picture set. At least one picture set is required if the Pictures node is present in the request. You are not required to provide pictures for all values that correspond to the variation specific name. For example, a listing could have pictures depicting the blue and black color variations, but not the pink variations. |
|
Item.Variations.Pictures .VariationSpecificPictureSet .PictureURL |
anyURI | Conditional,
repeatable: [0..*] |
The URL of a picture that is associated with the VariationSpecificValue. A variation specific picture set can consist of up to 12 images hosted by eBay Picture Services (EPS). However, only one picture may be used if that picture is hosted outside of eBay. eBay Picture Services and self-hosted images can never be combined into the same variation specific picture set. To specify multiple eBay Picture Services images, use multiple PictureURL fields, passing in a distinct URL in each of those fields. If specified, this field cannot have an empty/null value. The picture located at the URL specified in the first PictureURL field is also used as the thumbnail image for applicable variations. For example, if the picture set contains pictures of red shirts (i.e., VariationSpecificName=Color and VariationSpecificValue=Red), the first picture is used as the thumbnail image for all the red shirt variations. You can use Item.PictureDetails to specify additional pictures. For example, the item-level pictures could include a model wearing a black shirt, as a typical example of the shirt style. Note: If a URI contains spaces, replace them with %20. For example, http://example.com/my image.jpg must be submitted as http://example.com/my%20image.jpg to replace the space in the image file name.
|
|
Item.Variations.Pictures .VariationSpecificPictureSet .VariationSpecificValue |
string | Conditional | A value that is associated with VariationSpecificName. For example, suppose this set of pictures is showing blue shirts, and some of the variations include Color=Blue in their variation specifics. If VariationSpecificName is "Color", then VariationSpecificValue would be "Blue". |
| Item.Variations.Variation | VariationType | Conditional,
repeatable: [1..120] |
Contains data that distinguishes one variation from another. For example, if the items vary by color and size, each Variation node specifies a combination of one of those colors and sizes. When listing or relisting an item, you are allowed to create a listing with only one variation if you plan to add more variations to it in the future. However, if you don't plan to add other variations, we recommend that you avoid listing with only one variation, so that you avoid confusing buyers. When you modify a variation, it's safest to specify all the fields with the values you want in the listing. At a minimum, StartPrice and VariationSpecifics are required to modify an existing variation. If you omit SKU, the existing SKU (if any) is deleted from the variation. If you omit Quantity, it is set to 0. Variation, Pictures, or ModifyNameList (or all) need to be specified when the Variations node is specified in listing requests. |
|
Item.Variations.Variation .DiscountPriceInfo |
DiscountPriceInfoType | Optional |
This container provides information for an item that has a Strikethrough Price (STP) or a Minimum Advertised Price (MAP) discount pricing treatment. STP and MAP apply only to fixed-price listings and auction listings with the Buy It Now opton. STP is available on the US, UK, and German (DE) sites, while MAP is available only on the US site. Discount pricing is available to qualified sellers (and their associated developers) who participate in the Discount Pricing Program. Once qualified, sellers receive a "special account flag" (SAF) that allows them to apply Discount Pricing to both single-variation and multi-variation items. Sellers should contact their account manager or Customer Service to see if they qualify for the Strikethrough Pricing program. As a seller listing Discount Price items, you are required to maintain records of your discount pricing in the event you are called upon to substantiate your item pricing. The following link details your legal obligations when you utilize Discount Pricing to sell items: Strikethrough Pricing Requirements For AddFixedPriceItem, RelistFixedPriceItem, ReviseFixedPriceItem, and VerifyAddFixedPriceItem: If you are listing variations (MSKU items), use Variation.DiscountPriceInfo for each variation. |
|
Item.Variations.Variation .DiscountPriceInfo .MadeForOutletComparisonPrice |
AmountType (double) | Conditional |
Applicable only if the item was specifically made for sale through dedicated eBay outlet pages (e.g., eBay Fashion Outlet). The comparison price is the price of a comparable product sold through non-outlet channels on eBay (or elsewhere), or not specifically made for the outlet. In fashion, a "comparable" product shares the same design, but is not considered an identical product. Some products are specifically made for outlets, and may have a different SKU than the "comparable" product. These made-for-outlet products may be manufactured in a different place, with different materials, or according to different specifications (i.e. different stitch pattern, seam reinforcement, button quality, etc.) |
|
Item.Variations.Variation .DiscountPriceInfo .MinimumAdvertisedPrice |
AmountType (double) | Conditional | 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 offer prices below MAP by means of other discounts. This only applies to fixed-price listings and auction listings with the Buy It Now option. |
|
Item.Variations.Variation .DiscountPriceInfo .MinimumAdvertisedPriceExposure |
MinimumAdvertisedPriceExposureCodeType | Conditional |
For MinimumAdvertisedPrice (MAP) listings only. A seller cannot show the actual discounted price on eBay's View Item page. Instead, the buyer can either click on a pop-up on eBay's View Item page, or the discount price will be shown during checkout.
Applicable values: • CustomCode (in/out) Reserved for future use. • DuringCheckout (in/out) DuringCheckout specifies that the discounted price must be shown on the eBay checkout flow page. • None (in/out) None means the discount price is not shown via either PreCheckout nor DuringCheckout. • PreCheckout (in/out) PreCheckout specifies that the buyer must click a link (or a button) to navigate to a separate page (or window) that displays the discount price. eBay displays the discounted item price in a pop-up window. |
|
Item.Variations.Variation .DiscountPriceInfo .OriginalRetailPrice |
AmountType (double) | Conditional | The actual retail price set by the manufacturer (OEM). eBay does not maintain or validate the OriginalRetailPrice supplied by the seller. OriginalRetailPrice should always be more than StartPrice. Compare the StartPrice/BuyItNowPrice to OriginalRetailPrice to determine the amount of savings to the buyer. |
|
Item.Variations.Variation .DiscountPriceInfo.SoldOffeBay |
boolean | Conditional |
Used by the eBay UK and eBay Germany (DE) sites, this flag indicates that the discount price (specified as StartPrice) is the price for which the seller offered the same (or similar) item for sale on a Web site or offline store other than eBay in the previous 30 days. The discount price is always in reference to the seller's own price for the item. If this field is set to 'true', eBay displays 'Was*' in the UK and 'Ursprunglich*' in Germany, next to the discounted price of the item. In the event both SoldOffeBay and SoldOneBay fields are set, SoldOneBay takes precedence. Default: false. |
|
Item.Variations.Variation .DiscountPriceInfo.SoldOneBay |
boolean | Conditional |
Used by the eBay UK and eBay Germany (DE) sites, this flag indicates that the discount price (specified as StartPrice) is the price for which the seller offered the same (or similar) item for sale on eBay within the previous 30 days. The discount price is always in reference to the seller's own price for the item. If this field is set to 'true', eBay displays 'Was' in the UK and 'Ursprunglich' in Germany, next to the discounted price of the item. In the event both SoldOffeBay and SoldOneBay fields are set to 'true', SoldOneBay takes precedence. Default: false. |
|
Item.Variations.Variation .Quantity |
int | Required |
This value indicates the quantity of items in the specific variation that are available for purchase. If you set Variation.Quantity to '0' when you create, revise, or relist an item listing, the variation is dropped from the listing. For GetItem (and other related calls that retrieve the Item object), the Variation.Quantity value indicates the total number of items associated with the variation, including the quantity available and the quantity sold. To calculate the quantity available for sale, subtract SellingStatus.QuantitySold from this value. For ReviseFixedPriceItem: You can revise a variation's quantity at any time, even if it has purchases. However, at least one variation must remain with a non-zero quantity in order for the listing to remain active. When you modify a variation during revise or relist, you need to include both its StartPrice and Quantity. If you revise the Quantity value for a variation after items have already sold, specify the quantity available for sale. (eBay will automatically add the quantity sold to the value you specify.) If you set the quantity to 0 and the variation has no purchases, the variation may be dropped from the listing. For GetSellerTransactions: See Item.Quantity instead. See the Trading API Guide for more details about setting and modifying a variation's quantity. Min: 0. |
| Item.Variations.Variation.SKU | SKUType (string) | Conditional |
A SKU (stock keeping unit) is an identifier defined by a seller. It is only intended for the seller's use (not for buyers). Many sellers assign a SKU to an item of a specific type, size, and color. For the seller's convenience, eBay preserves the SKU on the variation, and also on corresponding order line items. This enables you (as a seller) use the SKU to reconcile your eBay inventory with your own inventory system instead of using the variation specifics. It is a good idea to track how many items of each type, size, and color are selling so that you can restock your shelves or update the variation quantity on eBay according to customer demand. (eBay does not use the SKU.) If specified, all SKU values must be unique within the Variations node. That is, no two variations within the same listing can have the same SKU. If you set Item.InventoryTrackingMethod to true, the variation SKU values are required and they must be unique across all the seller's active listings. For GetItem and related calls: Only returned if the seller specified a SKU for the variation. Max length: 80. |
|
Item.Variations.Variation .StartPrice |
AmountType (double) | Conditional |
The fixed price of all items identified by this variation. For example, a "Blue, Large" variation price could be USD 10.00, and a "Black, Medium" variation price could be USD 5.00. Each variation requires its own price, and the prices can be different for each variation. This enables sellers to provide discounts on certain variations without affecting the price of others. Required (and always returned) for listings with variations. You can revise a variation's price at any time (even if it has purchases). When you modify a variation during revise or relist, you need to include both its StartPrice and Quantity. |
|
Item.Variations.Variation .VariationSpecifics |
NameValueListArrayType | Conditional,
repeatable: [2..5] |
A list of name/value pairs that uniquely identify the variation within the listing. All variations must specify the same set of names, and each variation must provide a unique combination of values for those names. For example, if the items vary by color and size, then every variation must specify Color and Size as names, and no two variations can specify the same combination of color and size values. When you revise a listing that includes variations, you can change names in variation specifics by using ModifyNameList. You can also add, delete, or replace individual variations as needed to match your current inventory. Use the Variation.Delete field to delete a variation that has no sales (order line items). If the variation has sales, then set the Quantity to 0. For GetSellerEvents To keep the GetSellerEvents response smaller, variation specifics are not returned if the variation has a SKU. If the variation has no SKU, then variation specifics are returned instead. Optionally, you can pass IncludeVariationSpecifics as true in the request to force variation specifics to be returned, even when the SKU is returned. See:
|
|
Item.Variations.Variation .VariationSpecifics .NameValueList |
NameValueListType | Conditional,
repeatable: [2..5] |
For the AddItem family of calls: Contains the name and value(s) for an Item Specific. Only required when the ItemSpecifics container is specified. For the AddFixedPriceItem family of calls: The same NameValueList schema is used for the ItemSpecifics node, the VariationSpecifics node, and the VariationSpecifcsSet node. If the listing has varations, any name that you use in the VariationSpecifics and VariationSpecificsSet nodes can't be used in the ItemSpecifics node. When you list with Item Variations: a) Specify shared Item Specifics (e.g., Brand) in the ItemSpecifics node. b) Specify up to five VariationSpecifics in each Variation node. c) Specify all applicable names with all their supported values in the VariationSpecificSet node. See the Variation sample in the AddFixedPriceItem call reference for examples. For PlaceOffer: Required if the item being purchased includes Item Variations. |
|
Item.Variations.Variation .VariationSpecifics .NameValueList.Name |
string | Conditional |
A name in a name/value pair. For the AddItem and AddFixedPriceItem families of calls: In the Item.ItemSpecifics context, this can be any name that the seller wants to use. However, to help buyers find items more easily, it is a good idea to try to use a recommended name when possible (see GetCategorySpecifics or GetItemRecommendations). You can't specify the same name twice within the same listing. For the AddFixedPriceItem family of calls: In the VariationSpecifics context, this can be any name that the seller wants to use, unless the VariationsEnabled flag is false for the name in the GetCategorySpecifics response. For example, for some categories eBay may recommend that you only use "Brand" as a shared name at the Item level, not in variations. For GetCategorySpecifics and GetItemRecommendations: This is a recommended (popular) name to use for items in the specified category (e.g., "Brand" might be recommended, not "Manufacturer"). For PlaceOffer: Required if the item being purchased includes Item Variations. Max length: 40. |
|
Item.Variations.Variation .VariationSpecifics .NameValueList.Value |
string | Conditional,
repeatable: [0..*] |
A value associated with the name. For the AddItem family of calls: If you specify multiple values for Item Specifics, eBay only stores the first one, unless GetCategorySpecifics or GetItemRecommendations indicates that the corresponding name supports multiple values. For the AddFixedPriceItem family of calls: If you specify multiple values for Item Specifics or Variation Specifics, eBay only stores the first one, unless GetCategorySpecifics or GetItemRecommendations indicates that the corresponding name supports multiple values. In VariationSpecificSet, you typically specify multiple Value fields for each name. For example, if Name=Size, you would specify all size values that you wan to offer in the listing. For GetCategorySpecifics and GetItemRecommendations: The most highly recommended values are returned first. For these calls, Value is only returned when recommended values are available. For PlaceOffer: Required if the item being purchased includes Item Variations. Max length: 50. |
|
Item.Variations .VariationSpecificsSet |
NameValueListArrayType | Conditional |
The set of all variation specific names and values that can be applicable to the listing (at any time in its life cycle). This must include all names and values specified in the VariationSpecifics nodes. Required when Variations are specified in a new listing, and when you modify the name of a variation by using ModifyNameList. When you modify variation specific names, VariationSpecificsSet must include the new names plus the names that are not changing (but omit the old names), This set configures variation selection widgets that appear on eBay's View Item page. For example, if you specify Color and Size names in the set, eBay's View Item page displays Color and Size drop-down lists to enable a buyer to choose a variation of interest. The order in which you specify the names and values also controls the order in which the selection widgets appear on the View Item page. For example, if you specify "Color", then "Size", and then "Sleeve Style" as names, the View Item page shows drop-down lists with those labels in that order. For "Size", if you specify "S", "M", and "L" as values, the View Item page shows the values in that order in the Size drop-down list. Use GetCategorySpecifics to retrieve recommendations for names, values, and order. Required when Variations are specified in a new listing (e.g., in AddFixedPriceItem). Also required when you change variation specific names or values in ReviseFixedPriceItem and RelistFixedPriceItem. |
|
Item.Variations .VariationSpecificsSet .NameValueList |
NameValueListType | Conditional,
repeatable: [2..5] |
For the AddItem family of calls: Contains the name and value(s) for an Item Specific. Only required when the ItemSpecifics container is specified. For the AddFixedPriceItem family of calls: The same NameValueList schema is used for the ItemSpecifics node, the VariationSpecifics node, and the VariationSpecifcsSet node. If the listing has varations, any name that you use in the VariationSpecifics and VariationSpecificsSet nodes can't be used in the ItemSpecifics node. When you list with Item Variations: a) Specify shared Item Specifics (e.g., Brand) in the ItemSpecifics node. b) Specify up to five VariationSpecifics in each Variation node. c) Specify all applicable names with all their supported values in the VariationSpecificSet node. See the Variation sample in the AddFixedPriceItem call reference for examples. For PlaceOffer: Required if the item being purchased includes Item Variations. |
|
Item.Variations .VariationSpecificsSet .NameValueList.Name |
string | Conditional |
A name in a name/value pair. For the AddItem and AddFixedPriceItem families of calls: In the Item.ItemSpecifics context, this can be any name that the seller wants to use. However, to help buyers find items more easily, it is a good idea to try to use a recommended name when possible (see GetCategorySpecifics or GetItemRecommendations). You can't specify the same name twice within the same listing. For the AddFixedPriceItem family of calls: In the VariationSpecifics context, this can be any name that the seller wants to use, unless the VariationsEnabled flag is false for the name in the GetCategorySpecifics response. For example, for some categories eBay may recommend that you only use "Brand" as a shared name at the Item level, not in variations. For GetCategorySpecifics and GetItemRecommendations: This is a recommended (popular) name to use for items in the specified category (e.g., "Brand" might be recommended, not "Manufacturer"). For PlaceOffer: Required if the item being purchased includes Item Variations. Max length: 40. |
|
Item.Variations .VariationSpecificsSet .NameValueList.Value |
string | Conditional,
repeatable: [0..*] |
A value associated with the name. For the AddItem family of calls: If you specify multiple values for Item Specifics, eBay only stores the first one, unless GetCategorySpecifics or GetItemRecommendations indicates that the corresponding name supports multiple values. For the AddFixedPriceItem family of calls: If you specify multiple values for Item Specifics or Variation Specifics, eBay only stores the first one, unless GetCategorySpecifics or GetItemRecommendations indicates that the corresponding name supports multiple values. In VariationSpecificSet, you typically specify multiple Value fields for each name. For example, if Name=Size, you would specify all size values that you wan to offer in the listing. For GetCategorySpecifics and GetItemRecommendations: The most highly recommended values are returned first. For these calls, Value is only returned when recommended values are available. For PlaceOffer: Required if the item being purchased includes Item Variations. Max length: 50. |
| Item.VIN | string | Conditional |
Vehicle Identification Number, which is a unique serial number for a motor vehicle. Applicable to listings in US eBay Motors Cars and Trucks (6001), Motorcycles (6024), Commercial Trucks (63732), RVs and Campers (50054), ATVs (6723), Snowmobiles (42595), and UTVs (173665); and to Cars and Trucks listings in CA, CAFR and AU eBay Motors. For vehicle categories that do not use VIN, call GetCategorySpecifics to determine applicable custom item specifics (such as "Hull ID Number" for Boats). For the US, CA, and CAFR eBay Motors sites, required for cars and trucks from model year 1981 and later. (The US developed national standards for VIN values as of 1981.) For the eBay Australia site, required for vehicles from model year 1989 or later. For the eBay Australia site, only appears on the View Item page if you also specify the date of first registration in the listing's item specifics. Appears in the VIN field in the Item Specifics section of eBay's View Item page. Not applicable to Half.com. Max length: 17. |
| Standard Input Fields |
| ErrorLanguage | string | Optional |
Use ErrorLanguage to return error strings for the call in a different language from the language commonly associated with the site that the requesting user is registered with. Specify the standard RFC 3066 language identification tag (e.g., en_US). ID--- country ----- ----- de_AT Austria de_CH Switzerland de_DE Germany en_AU Australia en_CA Canada en_GB United Kingdom en_SG Singapore en_US United States es_ES Spain fr_BE Belgium (French) fr_CA Canada (French) fr_FR France it_IT Italy nl_BE Belgium (Dutch) nl_NL Netherlands zh_CN China en_IN India en_IE Ireland zh_HK Hong Kong |
| MessageID | string | Optional |
Most Trading API calls support a MessageID element in the request and a CorrelationID element in the response. If you pass in a MessageID in a request, the same value will be returned in the CorrelationID field in the response. Pairing these values can help you track and confirm that a response is returned for every request and to match specific responses to specific requests. If you do not pass a MessageID value in the request, CorrelationID is not returned. Note: GetCategories is designed to retrieve very large sets of metadata that change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). When this occurs, the MessageID and CorrelationID fields aren't applicable. However, if you specify an input filter to reduce the amount of data returned, the calls retrieve the latest data (not cached). When this occurs, MessageID and CorrelationID are applicable. |
| Version | string | Conditional |
The version number of the API code that you are programming against (e.g., 549). The version you specify for a call has these basic effects: - It indicates the version of the code lists and other data that eBay should use to process your request. - It indicates the schema version you are using. You need to use a version that is greater than or equal to the lowest supported version. For the SOAP API: If you are using the SOAP API, this field is required. Specify the version of the WSDL your application is using. For the XML API: If you are using the XML API, this field has no effect. Instead, specify the version in the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header. (If you specify Version in the body of an XML API request and it is different from the value in the HTTP header, eBay returns an informational warning that the value in the HTTP header was used instead.) See:
|
| WarningLevel | WarningLevelCodeType | Optional |
Controls whether or not to return warnings when the application passes unrecognized or deprecated elements in a request. An unrecognized element is one that is not defined in any supported version of the schema. Schema element names are case-sensitive, so using WarningLevel can also help you remove any potential hidden bugs within your application due to incorrect case or spelling in field names before you put your application into the Production environment. WarningLevel only validates elements; it doesn't validate XML attributes. It also doesn't control warnings related to user-entered strings or numbers, or warnings for logical errors. We recommend that you only use this during development and debugging. Do not use this in requests in your production code. Applicable values: • High (in) Return warnings when the application passes unrecognized or deprecated elements in a request. • Low (in) Do not return warnings when the application passes unrecognized or deprecated elements in a request. This is the default value if WarningLevel is not specified. See Warning Level. |
| Input Detail Controls Samples Change History Top Errors for VerifyAddFixedPriceItem User Notes |
The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).
See also Samples.
See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).
<?xml version="1.0" encoding="utf-8"?> <VerifyAddFixedPriceItemResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <!-- Call-specific Output Fields --> <Category2ID> string </Category2ID> <CategoryID> string </CategoryID> <DiscountReason> DiscountReasonCodeType </DiscountReason> <!-- ... more DiscountReason values allowed here ... --> <Fees> FeesType <Fee> FeeType <Fee> AmountType (double) </Fee> <Name> string </Name> <PromotionalDiscount> AmountType (double) </PromotionalDiscount> </Fee> <!-- ... more Fee nodes allowed here ... --> </Fees> <ItemID> ItemIDType (string) </ItemID> <ListingRecommendations> ListingRecommendationsType <Recommendation> ListingRecommendationType <Code> string </Code> <FieldName> string </FieldName> <Group> string </Group> <Message> string </Message> <Type> string </Type> <Value> string </Value> <!-- ... more Value values allowed here ... --> </Recommendation> <!-- ... more Recommendation nodes allowed here ... --> </ListingRecommendations> <!-- Standard Output Fields --> <Ack> AckCodeType </Ack> <Build> string </Build> <CorrelationID> string </CorrelationID> <Errors> ErrorType <ErrorClassification> ErrorClassificationCodeType </ErrorClassification> <ErrorCode> token </ErrorCode> <ErrorParameters ParamID="string"> ErrorParameterType <Value> string </Value> </ErrorParameters> <!-- ... more ErrorParameters nodes allowed here ... --> <LongMessage> string </LongMessage> <SeverityCode> SeverityCodeType </SeverityCode> <ShortMessage> string </ShortMessage> </Errors> <!-- ... more Errors nodes allowed here ... --> <HardExpirationWarning> string </HardExpirationWarning> <Message> string </Message> <Timestamp> dateTime </Timestamp> <Version> string </Version> </VerifyAddFixedPriceItemResponse>
| Return Value | Type | Occurrence | Meaning |
|---|
| Call-specific Output Fields [Jump to standard fields] |
| Category2ID | string | Conditionally |
ID of the secondary category in which the item would be listed. Only returned if you set Item.CategoryMappingAllowed to true in the request and the ID you passed in SecondaryCategory was mapped to a new ID by eBay. If the secondary category has not changed or it has expired with no replacement, Category2ID does not return a value. Max length: 10. |
| CategoryID | string | Conditionally |
ID of the primary category in which the item would be listed. Only returned if you set Item.CategoryMappingAllowed to true in the request and the ID you passed in PrimaryCategory was mapped to a new ID by eBay. If the primary category has not changed or it has expired with no replacement, CategoryID does not return a value. Max length: 10. |
| DiscountReason | DiscountReasonCodeType | Conditionally,
repeatable: [0..*] |
The nature of the discount, if a discount would have applied had this actually been listed at this time.
Applicable values: • CustomCode (out) Reserved for future use • Promotion (out) An offer that applies to an unlimited number of listings during the offering period. Example: "Get subtitle for $0.10 in Tech category when listing between 12/25 and 12/28. No limit to the number of items listed during this period." • SpecialOffer (out) An offer that applies to a limited number of listings during the offering period. Example: "There is no insertion fee for up to 5 auctions when listing between 12/1 and 12/10." |
| Fees | FeesType | Always | Child elements contain the estimated listing fees for the new item listing. The fees do not include the Final Value Fee (FVF), which cannot be determined until an item is sold. |
| Fees.Fee | FeeType | Always,
repeatable: [1..*] |
Contains the name, fee, and possible discount amount for an item listing feature. A Fee container is returned for each listing feature, even if the associated cost (Fee value) is 0. |
| Fees.Fee.Fee | AmountType (double) | Always |
Amount of the fee that eBay will charge the member for the associated listing feature. See the eBay.com Web site online help for a current schedule of listing features and their associated fees.
See eBay.com Fees. |
| Fees.Fee.Name | string | Always | Name of the listing feature, for identification purposes. See the Trading API guide for a list of current listing features names and associated fees. |
| Fees.Fee.PromotionalDiscount | AmountType (double) | Always |
This field exists in the response when the user has selected the features that participate in a promotional discount. See the eBay.com Web site online help for a current fee schedule.
See eBay.com Fees. |
| ItemID | ItemIDType (string) | Always |
Represents the item ID for the new fixed-price listing. VerifyAddFixedPriceItem does not actually list an item, so 0 is returned instead of a normal item ID. Max length: 19 (Note: The eBay database specifies 38. Currently, Item IDs are usually 9 to 12 digits). |
| ListingRecommendations | ListingRecommendationsType | Conditionally |
Container consisting of one or more Recommendation containers. Each Recommendation container provides a message to the seller on how a listing can be improved or brought up to standard in reqards to Top-Rated Plus listing requirements, Item Specifics, picture requirements, and/or a recommendation to use a product code to list the item, such as a UPC, an EAN, or an ISBN. This container is only returned if the IncludeRecommendations flag was included and set to 'true' in the VerifyAddFixedPriceItem request, and if at least one listing recommendation exists for the listing about to be listed. If one or more listing recommendations are returned, it will be at the seller's discretion about whether to revise the listing based on eBay's listing recommendation(s) before actually creating the listing through an AddFixedPriceItem call. |
|
ListingRecommendations .Recommendation |
ListingRecommendationType | Conditionally,
repeatable: [0..*] |
Each Recommendation container provides a message to the seller on how a listing can be improved or brought up to standard in regards to recommended Item Specifics, Picture quality requirements, Top-Rated seller/listing requirements, and/or a recommendation to use a product code (such as a UPC or ISBN value) to create a higher-quality listing. One or more Recommendation containers can be returned for each listing. |
|
ListingRecommendations .Recommendation.Code |
string | Conditionally |
This code value provides a generic, "human-friendly" message summarizing what is wrong with the listing (such as 'MANDATORY_STANDARDS_NOT_MET' or 'RECOMMENDED_FIELD_VALUE_MISSING'). Max length: 128. |
|
ListingRecommendations .Recommendation.FieldName |
string | Conditionally |
This value indicates the specific field that the seller needs to update to improve the quality of the listing. For example, if the listing recommendation type was 'eTRS' and the listing recommendation group was 'SHIPPING', the FieldName value may be 'DispatchTimeMax'. If the seller was returned a listing recommendation like this, it would most likely indicate that the seller must reduce the DispatchTimeMax value (handling time) in the listing to 1 day (or 0 days when zero-day handling becomes available) in order for the listing to qualify as a Top-Rated Plus listing and receive a Top-Rated Plus seal in View Item and Search Results pages, plus other benefits that Top-Rated Plus listings receive. Max length: 256. |
|
ListingRecommendations .Recommendation.Group |
string | Conditionally |
This value indicates the group that a specific listing recommendation belongs to. There may be multiple groups for each listing recommendation type. For example, two groups of the eTRS listing recommendation type are 'SHIPPING' and 'RETURNS'. Max length: 256. |
|
ListingRecommendations .Recommendation.Message |
string | Conditionally |
This textual message is the detailed description of a specific action that a seller can take to improve the quality of the listing. Max length: 4000. |
|
ListingRecommendations .Recommendation.Type |
string | Conditionally |
This value indicates the specific type of listing recommendation being provided to the seller. Possible values include the following:
Max length: 128. |
|
ListingRecommendations .Recommendation.Value |
string | Conditionally,
repeatable: [0..*] |
This value is only applicable for the 'ItemSpecifics' listing recommendation type. The value in the Value field is a recommended value for the recommended item specific name found in the Recommendation.FieldName field. Each item specific name can have more than one recommended value, so it is possible to have multiple Recommendation.Value fields in the response. Max length: 128. |
| Standard Output Fields |
| Ack | AckCodeType | Always |
A token representing the application-level acknowledgement code that indicates the response status (e.g., success). The AckCodeType list specifies the possible values for Ack.
Applicable values: • CustomCode (out) Reserved for internal or future use. • Failure (out) Request processing failed • Success (out) Request processing succeeded • Warning (out) Request processing completed with warning information being included in the response message (Not all values in AckCodeType apply to this field.) |
| Build | string | Always | This refers to the specific software build that eBay used when processing the request and generating the response. This includes the version number plus additional information. eBay Developer Support may request the build information when helping you resolve technical issues. |
| CorrelationID | string | Conditionally |
Most Trading API calls support a MessageID element in the request and a CorrelationID element in the response. If you pass in a MessageID in a request, the same value will be returned in the CorrelationID field in the response. Pairing these values can help you track and confirm that a response is returned for every request and to match specific responses to specific requests. If you do not pass a MessageID value in the request, CorrelationID is not returned. Note: GetCategories is designed to retrieve very large sets of metadata that change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). When this occurs, the MessageID and CorrelationID fields aren't applicable. However, if you specify an input filter to reduce the amount of data returned, the calls retrieve the latest data (not cached). When this occurs, MessageID and CorrelationID are applicable. |
| Errors | ErrorType | Conditionally,
repeatable: [0..*] |
A list of application-level errors (if any) that occurred when eBay processed the request.
See Error Handling. |
| Errors.ErrorClassification | ErrorClassificationCodeType | Conditionally |
API errors are divided between two classes: system errors and request errors.
Applicable values: • CustomCode (out) Reserved for internal or future use. • RequestError (out) An error has occurred either as a result of a problem in the sending application or because the application's end-user has attempted to submit invalid data (or missing data). In these cases, do not retry the request. The problem must be corrected before the request can be made again. If the problem is due to something in the application (such as a missing required field), the application must be changed. If the problem is a result of end-user data, the application must alert the end-user to the problem and provide the means for the end-user to correct the data. Once the problem in the application or data is resolved, resend the request to eBay with the corrected data. • SystemError (out) Indicates that an error has occurred on the eBay system side, such as a database or server down. An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. |
| Errors.ErrorCode | token | Conditionally | A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. See the "Errors by Number" document. |
| Errors.ErrorParameters | ErrorParameterType | Conditionally,
repeatable: [0..*] |
This optional element carries a list of context-specific error variables that indicate details about the error condition. These are useful when multiple instances of ErrorType are returned. |
| Errors.ErrorParameters [ attribute ParamID ] |
string | Conditionally | The index of the parameter in the list of parameter types returned within the error type. |
| Errors.ErrorParameters.Value | string | Conditionally | The value of the variable (e.g., the attribute set ID) |
| Errors.LongMessage | string | Conditionally | A more detailed description of the condition that raised the error. |
| Errors.SeverityCode | SeverityCodeType | Conditionally |
Indicates whether the error is a severe error (causing the request to fail) or an informational error (a warning) that should be communicated to the user.
Applicable values: • CustomCode (out) Reserved for internal or future use • Error (out) Application-level error • Warning (out) Warning or informational error |
| Errors.ShortMessage | string | Conditionally | A brief description of the condition that raised the error. |
| HardExpirationWarning | string | Conditionally | Expiration date of the user's authentication token. Only returned within the 7-day period prior to a token's expiration. To ensure that user authentication tokens are secure and to help avoid a user's token being compromised, tokens have a limited life span. A token is only valid for a period of time (set by eBay). After this amount of time has passed, the token expires and must be replaced with a new token. |
| Message | string | Conditionally |
Supplemental information from eBay, if applicable. May elaborate on errors (such as how a listing violates eBay policies) or provide useful hints that may help a seller increase sales. This data can accompany the call's normal data result set or a result set that contains only errors. Applications must recognize when the Message field is returned and provide a means to display the listing hints and error message explanations to the user. The string can return HTML, including TABLE, IMG, and HREF elements. In this case, an HTML-based application should be able to include the HTML as-is in the HTML page that displays the results. A non-HTML application would need to parse the HTML and convert the table elements and image references into UI elements particular to the programming language used. As usual for string data types, the HTML markup elements are escaped with character entity references (e.g.,<table><tr>...). |
| Timestamp | dateTime | Always |
This value represents the date and time when eBay processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See Time Values in the eBay Web Services guide for information about this time format and converting to and from the GMT time zone. Note: GetCategories and other Trading API calls are designed to retrieve very large sets of metadata that change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). When this occurs, this time value reflects the time the cached response was created. Thus, this value is not necessarily when the request was processed. However, if you specify an input filter to reduce the amount of data returned, the calls retrieve the latest data (not cached). When this occurs, this time value does reflect when the request was processed. |
| Version | string | Always | The version of the response payload schema. Indicates the version of the schema that eBay used to process the request. See "Standard Data for All Calls" in the eBay Web Services Guide for information on using the response version when troubleshooting "CustomCode" values that appear in the response. |
| Input Output Samples Change History Top Errors for VerifyAddFixedPriceItem User Notes |
This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.
| Input Output Detail Controls Change History Top Errors for VerifyAddFixedPriceItem User Notes |
New to making API calls? Please see Routing the Request.
Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.
Tests the creation of a listing with variations that will require inventory management over a long period.
Description
A salesperson from megaonlinemerchant is listing multiple, similar women's tops that vary in size and color. To save fees and improve best match scores, he is listing all the items in a single listing.
See the description of this sample in AddFixedPriceItem for details.
Input
The salesperson specifies shared details (like Brand) for all the tops in Item.ItemSpecifics.
He specifies the details that differ for each set of tops in Item.Variations.
In addition to defining the variation details, the salesperson configures the way buyers will browse the variations. He expects buyers to first choose their size, and then choose a color that is available in their size. He uses Variations.VariationSpecificSet to configure these details.
The salesman includes pictures for each color in Variations.Pictures. He also includes some shared pictures (such as a model wearing a representative example of the shirt style) in Item.PictureDetails.
See the description of this sample in AddFixedPriceItem for details.
XML format (HTTP POST). Also available is the .txt version of this XML. <?xml version="1.0" encoding="utf-8"?> <VerifyAddFixedPriceItemRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <ErrorLanguage>en_US</ErrorLanguage> <WarningLevel>High</WarningLevel> <Item> <Country>US</Country> <Currency>USD</Currency> <Description><![CDATA[New Ralph Lauren Polo womens tops shirts! Black, Pink, Yellow, Blue. NWT]]></Description> <DispatchTimeMax>3</DispatchTimeMax> <ListingDuration>GTC</ListingDuration> <ListingType>FixedPriceItem</ListingType> <PaymentMethods>PayPal</PaymentMethods> <PayPalEmailAddress>megaonlinemerchant@gmail.com</PayPalEmailAddress> <PostalCode>95125</PostalCode> <PrimaryCategory> <CategoryID>37565</CategoryID> </PrimaryCategory> <Title>New Ralph Lauren Polo shirt Pink Black Blue Yellow</Title> <PictureDetails> <PictureURL>http://i12.ebayimg.com/03/i/04/8a/5f/a1_1_sbl.JPG</PictureURL> <PictureURL>http://i22.ebayimg.com/01/i/04/8e/53/69_1_sbl.JPG</PictureURL> <PictureURL>http://i4.ebayimg.ebay.com/01/i/000/77/3c/d88f_1_sbl.JPG</PictureURL> </PictureDetails> <ReturnPolicy> <ReturnsAcceptedOption>ReturnsAccepted</ReturnsAcceptedOption> <RefundOption>MoneyBack</RefundOption> <ReturnsWithinOption>Days_30</ReturnsWithinOption> <Description>Text description of return policy details</Description> <ShippingCostPaidByOption>Buyer</ShippingCostPaidByOption> </ReturnPolicy> <ShippingDetails> <CalculatedShippingRate> <OriginatingPostalCode>95125</OriginatingPostalCode> <PackageDepth>6</PackageDepth> <PackageLength>7</PackageLength> <PackageWidth>7</PackageWidth> <ShippingPackage>PackageThickEnvelope</ShippingPackage> <WeightMajor>2</WeightMajor> <WeightMinor>0</WeightMinor> </CalculatedShippingRate> <PaymentInstructions>Payment must be received within 7 business days of purchase.</PaymentInstructions> <SalesTax> <SalesTaxPercent>8.75</SalesTaxPercent> <SalesTaxState>CA</SalesTaxState> </SalesTax> <ShippingServiceOptions> <FreeShipping>true</FreeShipping> <ShippingService>USPSPriority</ShippingService> <ShippingServicePriority>1</ShippingServicePriority> </ShippingServiceOptions> <ShippingServiceOptions> <ShippingService>UPSGround</ShippingService> <ShippingServicePriority>2</ShippingServicePriority> </ShippingServiceOptions> <ShippingServiceOptions> <ShippingService>UPSNextDay</ShippingService> <ShippingServicePriority>3</ShippingServicePriority> </ShippingServiceOptions> <ShippingType>Calculated</ShippingType> </ShippingDetails> <ItemSpecifics> <NameValueList> <Name>Condition</Name> <Value>New</Value> </NameValueList> <NameValueList> <Name>Occasion</Name> <Value>Casual</Value> </NameValueList> <NameValueList> <Name>Brand</Name> <Value>Ralph Lauren</Value> </NameValueList> <NameValueList> <Name>Style</Name> <Value>Polo Shirt</Value> </NameValueList> <NameValueList> <Name>Sleeve Style</Name> <Value>Short Sleeve</Value> </NameValueList> </ItemSpecifics> <Variations> <VariationSpecificsSet> <NameValueList> <Name>Size</Name> <Value>XS</Value> <Value>S</Value> <Value>M</Value> <Value>L</Value> <Value>XL</Value> </NameValueList> <NameValueList> <Name>Color</Name> <Value>Black</Value> <Value>Pink</Value> <Value>Yellow</Value> <Value>Blue</Value> </NameValueList> </VariationSpecificsSet> <Variation> <SKU>RLauren_Wom_TShirt_Pnk_S</SKU> <StartPrice>17.99</StartPrice> <Quantity>4</Quantity> <VariationSpecifics> <NameValueList> <Name>Color</Name> <Value>Pink</Value> </NameValueList> <NameValueList> <Name>Size</Name> <Value>S</Value> </NameValueList> </VariationSpecifics> </Variation> <Variation> <SKU>RLauren_Wom_TShirt_Pnk_M</SKU> <StartPrice>17.99</StartPrice> <Quantity>8</Quantity> <VariationSpecifics> <NameValueList> <Name>Color</Name> <Value>Pink</Value> </NameValueList> <NameValueList> <Name>Size</Name> <Value>M</Value> </NameValueList> </VariationSpecifics> </Variation> <Variation> <SKU>RLauren_Wom_TShirt_Blk_S</SKU> <StartPrice>20.00</StartPrice> <Quantity>10</Quantity> <VariationSpecifics> <NameValueList> <Name>Color</Name> <Value>Black</Value> </NameValueList> <NameValueList> <Name>Size</Name> <Value>S</Value> </NameValueList> </VariationSpecifics> </Variation> <Variation> <SKU>RLauren_Wom_TShirt_Blk_M</SKU> <StartPrice>20.00</StartPrice> <Quantity>10</Quantity> <VariationSpecifics> <NameValueList> <Name>Color</Name> <Value>Black</Value> </NameValueList> <NameValueList> <Name>Size</Name> <Value>M</Value> </NameValueList> </VariationSpecifics> </Variation> <Variation> <SKU>RLauren_Wom_TShirt_Blu_S</SKU> <StartPrice>20.00</StartPrice> <Quantity>10</Quantity> <VariationSpecifics> <NameValueList> <Name>Color</Name> <Value>Blue</Value> </NameValueList> <NameValueList> <Name>Size</Name> <Value>S</Value> </NameValueList> </VariationSpecifics> </Variation> <Variation> <SKU>RLauren_Wom_TShirt_Blu_M</SKU> <StartPrice>20.00</StartPrice> <Quantity>10</Quantity> <VariationSpecifics> <NameValueList> <Name>Color</Name> <Value>Blue</Value> </NameValueList> <NameValueList> <Name>Size</Name> <Value>M</Value> </NameValueList> </VariationSpecifics> </Variation> <Pictures> <VariationSpecificName>Color</VariationSpecificName> <VariationSpecificPictureSet> <VariationSpecificValue>Pink</VariationSpecificValue> <PictureURL>http://i12.ebayimg.com/03/i/04/8a/5f/a1_1_sbl.JPG</PictureURL> <PictureURL>http://i12.ebayimg.com/03/i/04/8a/5f/a1_1_sb2.JPG</PictureURL> </VariationSpecificPictureSet> <VariationSpecificPictureSet> <VariationSpecificValue>Blue</VariationSpecificValue> <PictureURL>http://i22.ebayimg.com/01/i/04/8e/53/69_1_sbl.JPG</PictureURL> <PictureURL>http://i22.ebayimg.com/01/i/04/8e/53/69_1_sb2.JPG</PictureURL> <PictureURL>http://i22.ebayimg.com/01/i/04/8e/53/69_1_sb3.JPG</PictureURL> </VariationSpecificPictureSet> <VariationSpecificPictureSet> <VariationSpecificValue>Black</VariationSpecificValue> <PictureURL>http://i4.ebayimg.ebay.com/01/i/000/77/3c/d88f_1_sbl.JPG</PictureURL> </VariationSpecificPictureSet> <VariationSpecificPictureSet> <VariationSpecificValue>Yellow</VariationSpecificValue> <PictureURL>http://i4.ebayimg.ebay.com/01/i/000/77/3c/d89f_1_sbl.JPG</PictureURL> </VariationSpecificPictureSet> </Pictures> </Variations> </Item> <RequesterCredentials> <eBayAuthToken>YOURTOKENHERE</eBayAuthToken> </RequesterCredentials> </VerifyAddFixedPriceItemRequest>
Output
The response includes the list of estimated fees associated with listing megaonlinemerchant's items. For this particular VerifyAddFixedPriceItem call with variations, the fees are the insertion fee and picture fees.
XML format. Also available is the .txt version of this XML. <?xml version="1.0" encoding="utf-8"?> <VerifyAddFixedPriceItemResponse xmlns="urn:ebay:apis:eBLBaseComponents"> <Timestamp>2009-03-01T21:22:04.602Z</Timestamp> <Ack>Success</Ack> <Version>615</Version> <Build>e615_core_API_8047594_R1</Build> <ItemID>0</ItemID> <Fees> <Fee> <Name>AuctionLengthFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>BoldFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>BuyItNowFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>CategoryFeaturedFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>FeaturedFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>GalleryPlusFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>FeaturedGalleryFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>FixedPriceDurationFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>GalleryFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>GiftIconFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>HighLightFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>InsertionFee</Name> <Fee currencyID="USD">0.35</Fee> </Fee> <Fee> <Name>InternationalInsertionFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>ListingDesignerFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>ListingFee</Name> <Fee currencyID="USD">0.35</Fee> </Fee> <Fee> <Name>PhotoDisplayFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>PhotoFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>ReserveFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>SchedulingFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>SubtitleFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>BorderFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>ProPackBundleFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>BasicUpgradePackBundleFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>ValuePackBundleFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>PrivateListingFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>ExtendedDurationFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>ProPackPlusBundleFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> <Fee> <Name>MotorsGermanySearchFee</Name> <Fee currencyID="USD">0.0</Fee> </Fee> </Fees> </VerifyAddFixedPriceItemResponse>
| Input Output Detail Controls Samples Top Errors for VerifyAddFixedPriceItem User Notes |
| Version | Description |
|---|---|
| 819 2013-04-10 |
|
| 817 2013-03-27 |
|
| 801 2012-11-28 |
|
| 791 2012-09-12 |
|
| 789 2012-08-29 |
|
| 787 2012-08-15 |
|
| 783 2012-07-18 |
|
| 781 2012-07-04 |
|
| 775 2012-05-23 |
|
| 763 2012-02-29 |
|
| 757 2012-01-18 |
|
| 743 2011-10-12 |
|
| 735 2011-08-17 |
|
| 723 2011-05-25 |
|
| 691 2010-10-13 |
|
| 689 2010-09-20 |
|
| 661 2010-03-17 |
|
| 635 2009-09-16 |
|
| 627 2009-07-22 |
|
| 619 2009-05-27 |
|
| 615 2008-04-29 |
|
| Input Output Detail Controls Samples Change History Top Errors for VerifyAddFixedPriceItem User Notes |
Copyright © 2005–2013 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.