Hack 89 Automate Auction Revisions


Simplify the task of revising several auctions at once with the ReviseItem API call.

Once an auction has started, you can normally change most aspects of the listing using the procedure outlined in [Hack #50]. But it's also possible to submit a revision using the API.

8.9.1 ReviseItem

Let's start with a simple script, reviseitem.pl, that will let you change any aspect of an active listing:

require 'ebay.pl';

my $item_id = shift @ARGV;
my %ARGS    = @ARGV;

my @options = qw/AdditionalShippingCosts AmEx AutoPay BoldTitle
  BuyItNowPrice CashOnPickupAccepted Category Category2 CCAccepted
  CheckoutDetailsSpecified CheckoutInstructions COD Counter Description
  Discover Duration Escrow EscrowBySeller Featured Gallery GalleryFeatured
  GalleryURL GiftExpressShipping GiftWrap Highlight InsuranceOption
  InsuranceFee LayoutId Location MinimumBid MoneyXferAccepted
  MoneyXferAcceptedinCheckout MOCashiers PackageHandlingCosts
  PaymentOther PaymentOtherOnline PaymentSeeDescription PayPalAccepted
  PayPalEmailAddress PersonalCheck PhotoCount PhotoDisplayType PictureURL
  Private Quantity Region ReservePrice SalesTaxPercent SalesTaxState
  SellerPays ShipFromZipCode ShippingHandlingCosts ShippingInTax
  ShippingIrregular ShippingOption ShippingPackage ShippingService
  ShippingType ShipToAfrica ShipToAsia ShipToCaribbean ShipToEurope
  ShipToLatinAmerica ShipToMiddleEast ShipToNorthAmerica ShipToOceania
  ShipToSouthAmerica SuperFeatured ThemeId Title VisaMaster WeightMajor
  WeightMinor WeightUnit/;

my %args = ( Verb => 'ReviseItem',
      DetailLevel => 0,
           SiteId => $site_id,
           ItemId => $item_id);
    foreach (@options) {
        $args{$_} = $ARGS{$_} if defined $ARGS{$_};

my $rsp = call_api(\%args);
if ($rsp->{Errors}) {
} else {
    print "Revised item #$rsp->{Item}[0]{Id}\n";

To use the script from the command line, include only the item number and the fields you want to change. For example, to change the title, type:

reviseitem.pl 4500205202 Title 'This is My New Title'

(Notice the single quotes used around text with spaces.) To change the starting bid to $8.50, type:

reviseitem.pl 4500205202 MinimumBid 8.50

To add the Bold listing upgrade (as described in [Hack #36]), type:

reviseitem.pl 4500205202 BoldTitle 1

where 1 means on (or true) and 0 means off (or false).

Note that the field names (Title, MinimumBid, and BoldTitle) are all case sensitive; make sure to type them exactly as they appear in the script.

Revisions made through the API follow the same rules as those made through eBay.com; for instance, you can't change your title if the item has received bids. See [Hack #50] for details.

8.9.2 AddToItemDescription

If the item has received bids, the number of changes you'll be able to make will be diminished greatly. But, just like on eBay.com, you can add to the item description with the API, using the addtodescription.pl script:

require 'ebay.pl';

my $item_id = shift @ARGV;
my $addition = shift @ARGV;

my $rsp = call_api({ Verb => 'AddToItemDescription',
              DetailLevel => 0,
                   ItemId => $item_id,
                   SiteId => $site_id,
              Description => $addition
if ($rsp->{Errors}) {
} else {
  print "Successfully added to the description.\n";

This much-simpler script is used somewhat like the first one. For instance:

addtodescription.pl 4500205202 'Just a quick note.'

will add the following to the end of your auction description:

On Nov-28-54 at 12:11:06 PDT, seller added the following information:
Just a quick note.

Note that you probably want to use this only if your item has received bids.

8.9.3 Let's Automate

The power of the API lies in its ability to turn a laborious task into a simple one. Combining these scripts with our ability to retrieve a list of all running auctions, you can create a script, reviseall.pl, that will make the same revision to an arbitrary number of listings in a single step:

require 'ebay.pl';

$today = &formatdate(time);
$tendays = &formatdate(time + 864000);

my $page_number = 1;
while (1) {
    my $rsp = call_api({ Verb => 'GetSellerList',
                  DetailLevel => 0,
                       UserId => $user_id,
                  EndTimeFrom => $today,
                    EndTimeTo => $tendays,
                   PageNumber => $page_number

    if ($rsp->{Errors}) {
      last PAGE;
    foreach (@{$rsp->{SellerList}{Item}}) {
      my %i = %$_;
      $id = @i{qw/Id/};

      if ($ARGV[0] eq "AddToDescription") {
        system './addtodescription.pl', $id, $ARGV[1];
      } else {
        system './reviseitem.pl', $id, @ARGV;
    last PAGE unless $rsp->{SellerList}{HasMoreItems};

This script requires the reviseitem.pl and addtodescription.pl scripts listed earlier in this hack. To submit a global change, type:

reviseall.pl BoldTitle 1

Note that the syntax is the same as reviseitem.pl except that the item number is obviously not required, since the changes apply to all running auctions.

There are many things you can do with this tool. For example, you can inform all your potential customers that you'll be out of town:

reviseall.pl AddToDescription 'Note to customers: I will be out of town from
    August 3rd to the 6th, and will respond to all questions when I return.'

Add the American Express option to all your auctions:

reviseall.pl AmEx 1

Change the shipping surcharge to $4.50 for all your auctions:

reviseall.pl CheckoutDetailsSpecified 1
reviseall.pl ShippingHandlingCosts 4.50

It's important to note that all revisions are absolute. That is, if you change the shipping surcharge to $4.50, that change will be made regardless of the original amount entered for each listing. If you want to do more complex revisions, such as lowering the starting bid or reserve price by 15% for items that have not yet received bids, you'll either have to raise the DetailLevel value for GetSellerList, as in the script in [Hack #87], or use the GetItem API call, as described in [Hack #90]. Refer to the API documentation for details.