http://developer.ebay.com/DevZone/XML/docs/WebHelp/ManagingItemListings-Revising_Items.html
Managing Listed Items > Managing Item Listings > Revising Items   
 



Revising Items  

Changing Payment Methods in a Revised Item

Restrictions on Changing Item Properties During a Revision

Multiple Choice Arguments

Revising US eBay Motors Listings

Revising Real Estate Listings

Revising eBay Stores Listings

Revising Items that Include Item Specifics (Attributes)

Revising Items with Product Details (Catalogs)

Reducing Reserve Price

Revising Items for Third-Party Checkout

Sellers often need to change a currently active listing. Typically, the change makes the item more appealing to buyers.

Changing the properties that define an active listing is known as revising the item. This is accomplished using ReviseItem. This call is directly analogous to the Revise Your Item (RYI) page on the eBay site.

When a seller revises an item, the seller might add information that was not in the original listing, such as information that answers a question received by the seller. See also Listing Policies.

For information about considering an item's rank in search results, see Considering Best Match When Revising and Relisting Items.

To revise an item listing using ReviseItem, the following conditions must be met:

Additionally, there are restrictions on what can be changed based on whether the listing has bids and based on whether the listing will end within twelve hours. For more on this, see Restrictions on Changing Item Properties During a Revision.

Revising an item using ReviseItem entails three general steps: setting up the execution environment, specifying the item to revise (by its item ID) and the item properties to change, and making the API call.

Revising an item entails creating and specifying an ItemType object representing the item listing to be revised and specifying which item properties are being changed in the revision. See the schema documentation for ItemType for a complete list of its properties.

The application identifies the item listing that is being revised by assigning the item ID for that listing to the ItemType.ItemID property.

The CategoryMappingAllowed flag is transient. If it was specified as true when the item was originally listed, it will not automatically be set to true when you revise the item. Therefore, it should be specified again as a new property. See Mapping Old Category IDs to Current IDs.

Indicating the Changed Fields When Revising an Item

To make a change to an item property using ReviseItem, the application must change the value of the property in the Item object used as input.

Using the VerifyOnly Field to Test Your Changes

You can use the VerifyOnly boolean field with the flag set to 'true', if you wnat the response to include the calculated listing price change (if there is an increase in the BIN/Start price) but you do not want the values to persist in the database.

Including the VerifyOnly field in ReviseItem is similar to using VerifyAddItem or VerifyRelistItem to test calls before you actually add or relist the item.

Removing a Field When Revising an Item

You can remove certain fields when you revise an item, subject to the rules described in Restrictions on Changing Item Properties During a Revision and in the ReviseItem field descriptions in the eBay Trading API Call Reference.

In some cases, you can remove a setting from a listing by changing the value of the corresponding field. For example, you can set a boolean like PrivateListing to false to "remove" the private listing setting.

However, in several cases, you need to use a special mechanism to remove a property from a listing. This is particularly true for strings (because an empty string is not the same as a deleted string), monetary amounts (because a price of 0.00 usually means "free" rather than "unspecified"), and other fields where null values may be ambiguous. To delete an item property of this kind, use DeletedField to specify the property. The documentation of DeletedField lists the fields that are subject to this rule..

For example, if you are changing the start price and the Listing Designer theme for the item and removing payment instructions, your request should contain the following XML:

Example 12-3 Sample XML for Modifying and Removing Fields with a ReviseItem  
... 
<Item> 
  <ItemID>4046156497</ItemID> 
  <StartPrice currencyID="USD">200.0</StartPrice> 
  <ListingDesigner> 
    <ThemeID>10</ThemeID> 
  </ListingDesigner> 
</Item> 
<DeletedField>Item.ShippingDetails.PaymentInstructions</DeletedField> 
...

Changing Payment Methods in a Revised Item

A listing must have at least one valid payment method, but you can change it when you revise the item.

Changing a payment method for a revised item involves adding the change to an ItemType object. For example, if you want to change the payment method for an item currently listed, you would follow these steps, after authenticating and creating the request object:

Restrictions on Changing Item Properties During a Revision

Making changes to an item's listing using ReviseItem is subject to a few restrictions, depending on whether any bids have been placed on the item, and whether the change is being attempted within twelve hours of the end of the auction.

The table below indicates the nature of changes that the seller can make and specifies changes that cannot be made given these two restrictions.

Table 12-1 Chinese Listings 
< 12 Hours
Bids
Allowed Revisions & Restrictions
N
N
  • Can extend the listing's duration if it has been fewer than two hours since the listing was created.
  • Can reduce the listing's duration if that would not result in less than 12 hours remaining for the listing.
  • Can revise any information but not the format (listing type)
  • Can remove the following optional features only: Buy It Now, eBay Picture Services, Reserve Price, 10-day listing
  • Can add optional features to increase the item's visibility (for example, bold title)
  • Cannot change the photos display options (photo display type).
  • Can add or change a Gallery picture
  • Can add more images to a listing (picture add date will be visible). Images cannot be removed
  • Can add or change return policy details
  • Can change the handling time (dispatch time) but the value must be greater than 0
N
Y
  • Can change the item description
  • Can change category or add a second category
  • Can add optional seller features to increase the item's visibility
  • Cannot change the photos display options (photo display type).
  • Can add more images to a listing (picture add date will be visible). Images cannot be removed.
  • Can add return policy details, but can't change existing details
  • Can add or change optional flags for product details (see Revising Items with Product Details (Catalogs))
Y
N
  • Can change category or add a second category
  • Can add previously unspecified Item Specifics
  • Can add optional seller features to increase the item's visibility
  • Can add page view counters
  • Cannot change the photos display options (photo display type).
  • Can add or change a Gallery picture
  • Can add more images to a listing (picture add date will be visible). Images cannot be removed.
  • Can add new payment methods
  • Can add new ship-to locations
  • Can add return policy details, but can't change existing details
  • Can add Item Specifics that were not previously specified (see Revising Items that Include Item Specifics (Attributes))
  • Can add or change optional flags for product details (see Revising Items with Product Details (Catalogs))
Y
Y
  • Can add optional features to increase the item's visibility (for example, bold).
  • Cannot change the photos display options (photo display type).
  • Can add or change a Gallery picture

   

Table 12-2 Basic Fixed-Price and Stores Inventory Listings 
< 12 Hours
Bids
Allowed Revisions & Restrictions
N
N
  • Can revise any information but not the format
  • Can remove optional features
  • Can add or change Gallery picture
  • Cannot change the photos display options (photo display type).
  • Can add more images to a listing (picture add date will be visible). Images cannot be removed.
  • Can add or change return policy details
  • Can change the handling time (dispatch time) but the value must be greater than 0
For Basic Fixed-Price listings only:
  • Can extend the listing's duration if it has been fewer than two hours since the listing was created.
  • Can reduce the listing's duration if that would not result in less than 12 hours remaining for the listing.
  • Can revise all shipping details (except for sales tax or when shipping is Freight) for a multi-quantity listing.
For Stores Inventory listings only (no 12-hour limits):
  • No change in duration is allowed.
  • Can revise all shipping details (except for sales tax or when shipping is Freight) if it is a multi-quantity listing with GTC duration.
N
Y
  • Can Revise price and quantity only
  • Cannot change the photos display options (photo display type).
  • Can add more images to a listing (picture add date will be visible). Images cannot be removed.
  • Can add or change optional flags for product details (see Revising Items with Product Details (Catalogs)
  • Can revise all shipping details (except for sales tax or when shipping is Freight) for a multi-quantity Store Inventory Format listing (with duration GTC) or for a multi-quantity Fixed Price listing.
  • Can add return policy details, but can't change existing details
Y
Y
For Basic Fixed-Price listings only:
  • Can change item description
  • Can add gift services
  • Cannot change duration (or set to GTC)
  • Cannot change the photos display options (photo display type).
  • Can add more images to a listing (picture add date will be visible). Images cannot be removed.
  • Can add Item Specifics that were not previously specified (see Revising Items that Include Item Specifics (Attributes))
  • Can add or change optional flags for product details (see Revising Items with Product Details (Catalogs))
  • Can revise all shipping details (except for sales tax or when shipping is Freight) for a multi-quantity listing.
  • Can add return policy details, but can't change existing details
Y
Y
For Stores Inventory listings only (no 12-hour limits):
  • Cannot change format
  • Can remove optional features
  • Can add or change Gallery picture
  • Cannot change the photos display options (photo display type).
  • Can add more images to a listing (picture add date will be visible). Images cannot be removed.
  • Cannot change duration (or set to GTC)
  • Can add Item Specifics that were not previously specified (see Revising Items that Include Item Specifics (Attributes))
  • Can add or change optional flags for product details (see Revising Items with Product Details (Catalogs))
  • Can revise all shipping details (except for sales tax or when shipping is Freight) if it is a multi-quantity listing with GTC duration.
  • Can add return policy details, but can't change existing details
Y
Y
  • Can revise price and quantity only
  • Can revise all shipping details (except for sales tax or when shipping is Freight) for a multi-quantity Store Inventory Format listing (with duration GTC) or for a multi-quantity Fixed Price listing.
  • Can't change return policy details

   

Table 12-3 Ad Format Listings 
< 12 Hours
Bids
Allowed Revisions & Restrictions
N
N
  • Can revise any information except the listing format
N
Y
(Not applicable, as the ad format does not have bids)
Y
N
Y
Y
(Not applicable as ad format does not have bids)

Notes for above tables:

Sellers can change active multiple-quantity fixed price listings, even after one of the items within the listung has been purchased, if that listing does not end within 12 hours. A seller can add, remove, or change the values of certain properties, such as these. (For a more complete list, see ReviseItem and ReviseFixedPriceItem in the eBay Trading API Call Reference).

A transactionID is associated with a snapshot of the item data at the time of the purchase. Sellers or Buyers can get a snapshot of the listing as it was at the time of a given purchase by invoking GetItem with a Transaction ID in the request. Sellers of an item are allowed to view all transactional snapshots of the listing, whereas buyers can only view the transactional snapshots for which they are the successful buyer. Past transactional views of an item are available for up to 90 days from the date the transaction took place.

If you are using Notifications, you can set the transaction event to trigger your notifications or use an event related to the entire listing. Be aware that if you're using item transaction snapshot data, fields like Listing Status may report an Active status (because the listing was Active on the transaction date), but the listing may actually have ended.

You cannot use the ReviseItem to modify eBay Giving Works items. See Identifying Listings that Benefit Nonprofits for additional information.

Multiple Choice Arguments

Because ReviseItem replaces only item properties that are included in the input ItemType object and list of properties changed, be careful when updating properties that are made up of multiple choice options, such as shipping option. In these cases, specify all intended options. For instance, if the listing already has options #1 and #2 and the revision change is to add option #3, include all three in the property of the input ItemType object.

Revising US eBay Motors Listings

In addition to the normal rules for revising listings, the following rules apply for US eBay Motors listings:

Fees Overview
http://pages.ebay.com/help/sell/fees.html

When retrieving items from the US eBay Motors site, GetItem returns information about changes to Buy It Now and reserve prices in the ReviseStatus property of the Item object.

Revising Real Estate Listings

You application can list real estate to the eBay US and Germany sites (SiteCodeType values US and Germany, respectively).

eBay Real Estate listings do not involve legally binding offers to buy and sell, with some exceptions as noted in the eBay online help:

http://pages.ebay.com/help/policies/real-estate-rules.html

When you list real property on the US eBay site, you have the option of listing in a regular Chinese auction format or in an Ad format listing (ListingTypeCodeType values Chinese and LeadGeneration, respectively):

When you list real property on the eBay Germany site, you have the option of listing in the Ad format. As with the US site, when the ad format is used, no auction takes place. Instead, a user can leave a lead for the item listing to show interest. An application can retrieve these leads for the seller by calling GetAdFormatLeads.

When you use the API to list real estate, certain standard inputs (such as payment options) are not applicable. Also, the choice of possible values for some inputs (such as the listing's duration) are different for real estate items than for other types of listings. Please see eBay Real Estate Listings for a list of these differences.

Revising eBay Stores Listings

The Item object properties used to define a new eBay Stores listing are also usable for eBay Stores Inventory listings, but some may have different behavior or validation rules for eBay Stores Inventory format listings. In addition, some properties are applicable only when the seller is a store owner. Such arguments are denoted in the table below with an asterisk in the "Special" column.

The table below lists the subset of the Item object properties used with ReviseItem that are applicable to eBay Stores Inventory format listings and indicates how the validation differs from that of standard auction and Basic Fixed Price listings.

"Not used" in the "Store Inventory" column of this table indicates that the argument is not applicable to eBay Store Inventory listings. If you specify a value of Stores Fixed-price in the Item.ListingType property (or if you specify a value for Item.Storefront.StoreCategoryID), do not specify a value for these properties or the item will be rejected and you will receive an error.

In Table 12-4, the column "Store Inventory" refers to listings with a ListingTypeCodeType value of StoresFixedPrice. The column "Other Types" refers to other types of listings that can appear in an eBay Store when the listing seller is a Store owner (listing with a ListingTypeCodeType value of either Chinese or FixedPriceItem).

Table 12-4 Item Properties for eBay Stores Item Revisions 
Item Property
Data Type
Meaning
Store Inventory
Other Types 
SecondaryCategory  

CategoryType
Optional second category in which the item is listed on eBay.
Not used
Optional 
ListingDuration 

ListingDurationCodeType
Number of days the auction will be active. Max length 3. Must be 30, 60, 90, or 120 days (or GTC for Stores Fixed-Price listings). Specify "GTC" to enable the Good 'Til Cancel feature. A check is also made to ensure that the new duration is not reduced such as to end the auction within 24 hours of the current date-time. If ReviseItem is used to alter an item's duration, the call fails with an error if the new end time minus the current date-time is less than 24 hours.
Optional
Optional 
Location  

string
Geographical location of the item.
Optional
Optional 
MinimumToBid  

AmountType
Fixed purchase price or minimum acceptable bid for the item. The previous insertion fee is credited and a new one applied based on the new minimum bid (if needed). For fixed-price items, the seller can use ReviseItem to change the price so long as the last item in the auction has not been sold (the only item, if the quantity is one). Must be a value greater than zero.
Optional
Optional 
PrivateListing 

boolean
Designates the auction as a private auction.
Optional
Optional 
Quantity 

int
Number of items being sold in a single auction listing. Must be greater than zero.
Optional
Optional 
ReservePrice 

AmountType
The value at which to start the bidding if the bidding starts at a price lower than what the seller is willing to sell the item for. Stores Inventory items cannot have a reserve price.
Error
Optional 
RegionID 

string
Numeric code for a region, used when listing by region. To remove a regional listing constraint, pass a value of zero. Default is zero.
Optional
Optional 
StoreCategoryID 

int
Child of the StorefrontType object. For use with Stores items, only. Custom categories for subdividing the items within an eBay Store. If not specified, the value from the item being revised is used.
Optional
Optional

Revising Items that Include Item Specifics (Attributes)

If you are new to using ID-based Item Specifics (using the Attribute format) in your applications, see Working with Attribute-Based Features for definitions and additional suggested reading.

As indicated in Restrictions on Changing Item Properties During a Revision:

Important: The Item Specifics in your revised listing must be consistent with the Item Specifics that you used in the original listing. This means you need to select Item Specifics based on the original meta-data that was in effect when the item was originally listed. If the meta-data has changed, you cannot use the latest version. Thus, it is a good idea to store the meta-data that was in effect whenever you list an item with Item Specifics.

To add, modify, or remove individual attributes (including the item condition, even if it was originally set by using LookupAttribute), set Item.AttributeSetArray object to contain the complete set of Item Specifics that should appear in the revised listing.

The common scenarios for adding, modifying, or removing attributes include:

You should be familiar with the basic logic that governs the dependencies between different attributes. To reduce the number of errors returned, it is also helpful to be familiar with the rules that are used to validate attributes and values. See Listing with Item Specifics and Catalog Data.

Here are some typical cases that cause errors when your listing includes outdated attributes:

For additional typical attribute error and warning conditions, see Attribute Error Handling.

Revising Items with Product Details (Catalogs)

Items in certain categories can have attributes whose values are well known and don't vary from listing to listing. Instead of filling in this standard information for every listing, a seller can create a listing in which this information has already been partially filled out (pre-filled). This data is called product details. See Working with Attribute-Based Features for more information about this feature.

As indicated in Restrictions on Changing Item Properties During a Revision, when an item has bids or the listing ends in fewer than 12 hours, you cannot change the product ID and you cannot remove the product from the listing. However, you can change the values of the IncludeStockPhotoURL, UseStockPhotoURLAsGallery, and IncludePrefilledItemInformation flags.

When an item has no bids and does not end within 12 hours, you can use ReviseItem to add, modify, or remove product details.

If an item is listed with product details and you change the relevant category, you need to make sure the new category is mapped to the characteristics set associated with the product. The product data must always be consistent with at least one of the listing's categories. If the item already includes product details, but that information is inconsistent with the new category, you must remove the product information or replace it with new product information that is consistent.

These are the common scenarios when revising an item with product details:

Changes to product data in the system do not affect an existing listing. Therefore, the product ID and any pre-filled data that was present at the time of the AddItem request remains constant at the time of the ReviseItem request. When revising product details, refer to the product and characteristic meta-data returned from GetProductSellingPages (not GetAttributesCS). Specify the product ID and set the value of UseCase to ReviseItem retrieve the original meta-data that was in effect for that product ID.

After executing ReviseItem with product details, you should compare the response to the request to make sure that the data that was actually listed matches the data that you sent. For example, if you changed the value of a Type 2 attribute but the value is now pre-filled in the catalog, the pre-filled value overrides the value you send in.

Changing a Listing Start Price

When you revise an item, you can change the listing start price. However, if you reduce the start price, the insertion fee is not credited (for the US site and other participating sites). The insertion fee is based on the maximum price the item has had in its life cycle.

Reducing Reserve Price

Sellers can lower Reserve Prices on listings on the US eBay site, eBay UK site, or eBay Motors site, even after bids have been placed, to increase the likeliness of their items selling. To determine whether a site or category supports this capability, call GetCategories and check the ReduceReserveAllowed and ORRA fields. See Determining Whether a Category Supports Reserve Prices. Depending on the site and category, you also may need to call GetCategoryFeatures and check MinimumReservePrice.

When a category supports lowering the reserve, a seller can adjust the reserve price through the Revise Your Item process or by using ReviseItem, as long as no bids have exceeded the original reserve price. For most categories, this is only allowed when 12 or more hours remain for the listing. The reserve price can be reduced downwards to a minimum of one bid increment above the listing's current price. Once the reserve has been lowered, bidders are notified of the change via email, My eBay, and the listing itself.

If the item has no bids, set ReservePrice to any value within this range:

If the item has bids, set ReservePrice to a value within this range:

If the new reserve price is lower than the high bidder's proxy bid, the proxy bid is also reduced to one increment below the new bid price, to prevent bidders from unexpectedly becoming winning bidders when their prior bid had not yet met the Reserve price. For example, imagine a US listing starts at $1 with a reserve of $100, and the first bidder bids $75. The current price stays at $1 since the bid didn't meet the reserve. Then, if the seller then reduces reserve to $50, the bidder's proxy bid is reduced to one bid increment below $50. For a chance at becoming a winning bidder, the bidder would need to place another bid.

No credit is given for Reserve Price Fee if the listing is revised to reduce the Reserve Price.

See also Revising US eBay Motors Listings.

Revising Items for Third-Party Checkout

This topic is for Third-Party Checkout providers only. See Third Party Checkout.

Items can be revised to enable a custom, Third-Party Checkout process. This is done by passing a value of true in Item.ThirdPartyCheckout. If an item already has Third-Party Checkout enabled, then ThirdPartyCheckout need not be specified in the call to ReviseItem to enable Third-Party Checkout.

The following types of items cannot be revised to enable Third-Party Checkout:

An attempt to revise an item with a value of true for ThirdPartyCheckout will fail with an error under the following conditions. Note that this will be true whether the call to ReviseItem explicitly sets ThirdPartyCheckout, the ThirdPartyCheckout argument is not present in the call, or the original listing had a value of true for ThirdPartyCheckout.

When a seller is revising an item and the seller selects PayPal as an accepted payment method, the Third-Party Checkout application must set Item.PaymentMethods to PayPal for ReviseItem if it is not already set.

If there is at least one bid on the listing or there is less than twelve hours remaining before the end of the listing, then the value of ThirdPartyCheckout cannot be changed in a call to ReviseItem. (See Restrictions on Changing Item Properties During a Revision.)

See also Listing Items for Third-Party Checkout.




User-Contributed Notes

   
 
 
 



 
Managing Listed Items > Managing Item Listings > Revising Items   
http://developer.ebay.com/DevZone/XML/docs/WebHelp/ManagingItemListings-Revising_Items.html
© 2004–2010 eBay Inc. All rights reserved. Version 655