Adding an Item with the
API
Overview
This topic illustrates the minimal steps to use a call to the
API function AddItem to list an item on eBay from an eBay
SDK application.
The
SDK provides classes that are wrappers around
API functions. In this particular case, the
SDK class AddItemCall is the wrapper class for the
API function AddItem. An instance of the Integration Library interface IItem is needed to contain the definition for the new item. This IItem object is used by the AddItemCall object, in its ItemToAdd property. The AddItemCall.AddItem method calls the
API function AddItem and sends the item definition in ItemToAdd to eBay as a new item listing.
NOTE: When listing an item entirely using the Integration Library, data for the new item is stored in the Integration Database and synchronized to eBay from the Integration Database through built-in Integration Library class methods (IEBaySession.SaveItem and IEBaySynchronizer.ListItemsToEBay). But when listing an item using the AddItemCall class from the
API library, no such local database integration and synchronization is provided. An application can still save the item data to the Integration Database (with IEBaySession.SaveItem), but once there its data must be maintained programmatically by the application. The call to the AddItemCall.AddItem method "synchronizes" to eBay only one item definition per call, and so this must be repeated for each additional new item.
While the source code examples shown here to illustrate the process of submitting an item with AddItemCall are in VB.NET, the same steps need to be performed regardless of the actual programming language used.
There are four simple steps to submitting an item using the
API Library. An optional fifth step describes verifying that the item was successfully submitted.
Prerequisite: Import the Applicable Libraries
Step 1: Create an
API Call Session
Step 2: Define the Item
Step 3: Create the AddItemCall object
Step 4: Submit the Item to eBay
Optional Step: Verify the Item Submission
Prerequisite: Import the Applicable Libraries
An application that uses the objects and methods described here must reference the libraries in which those objects are defined and the base
SDK libraries that support them.
Imports System
Imports System.IO
Imports eBay.SDK
Imports eBay.SDK.API
Imports eBay.SDK.Model
Imports eBay.SDK.Model.Item
Imports eBay.SDK.Integration
Step 1: Create an
API Call Session
The first step in submitting a new item to eBay using the AddItemCall class is to create and configure an
API call session: an IAPISession object. The
API call session object contains such information as the header data for the
API call, the
URL to which to send the
API request, and the user name and password for the seller (the requestor for the call to the
API function AddItem). In this example, the IAPISession object is named ApiCallSession and its properties are set here from memory variables.
' Instantiate a new IApiSession object
Dim ApiCallSession As eBay.SDK.API.IApiSession
ApiCallSession = new ApiSession()
' Enable
API-
XML logging
ApiCallSession.Log = new LogFile();
ApiCallSession.Log.Open("MyLogfile.txt");
ApiCallSession.LogCallXml = true;
' Set environment information
ApiCallSession.Developer = mTxtDeveloperId
ApiCallSession.Application = mTxtApplicationId
ApiCallSession.Certificate = mTxtCertificate
' Set
URL for
API Call
ApiCallSession.Url = mTxtUrl
' Set requesting user (seller) information
ApiCallSession.RequestUserId = mTxtUser
ApiCallSession.RequestPassword = mTxtUserPass
This step is only required once each time the application is run. However, if multiple users would be using the application, this step would need to be performed each time a different user would act as an item seller.
Step 2: Define the Item
The most verbose step in submitting an item is defining the item itself. This involves setting such item properties as its title, the duration of the listing, and the minimum bid for the item. The item is represented with an IItem object, in the variable item in this example. The first part of this step is creating the IItem object.
' Create the IItem object
Dim item As IItem = New eBay.SDK.Model.Item.Item()
Last, set the item's listing properties.
item.SiteId = SiteIdEnum.US
item.Type = ItemTypes.Auction
item.Title = "The item's title"
item.Description = "The item's description"
item.Currency = CurrencyEnum.USDollar
item.Location = "San Jose, CA"
item.Country = "us"
item.CategoryId = 355
item.Quantity = 1
item.Duration = 5
item.StartPrice = 10.00
item.BuyItNowPrice = 15.00
item.ReservePrice = 0
item.PaymentTerms.SeeDescription = True
item.ShippingOptions.ShippingRange = ShippingRangeEnum.SiteOnly
item.ShippingOptions.ShippingPayment.SeeDescriptio n = True
item.Uuid = New Uuid(True)
This step is required for each new item to be listed.
Step 3: Create the AddItemCall object
The AddItemCall class is a wrapper around the
API function AddItem, that lists a new item to eBay. The AddItemCall.ItemToAdd property (which is of type IItem) represents the definition of the new item to list on eBay. Use the IItem object created in Step 2 for the value of the ItemToAdd property.
In this example, the instantiated AddItemCall object is named
api.
' Instantiate the AddItemCall object
Dim
api As AddItemCall = New AddItemCall(ApiCallSession)
' Insert the item definition from Step 2
api.ItemToAdd = item
' Set the level for returned
API error strings
api.ErrorLevel = ErrorLevelEnum.BothShortAndLongErrorStrings
Step 4: Submit the Item to eBay
Once the item has been defined, the AddItemCall object has been created, and the item definition has been inserted into the AddItemCall object, the item is ready to be sent off to eBay. Do this with a call to the AddItemCall.AddItem method. Store the results from the call to AddItem into an IFees object (in this example, named ife).
' Always use a Try..Catch construct to
handle API call exceptions.
Try
' IFees is returned with listing fee information.
Dim ife As IFees =
api.AddItem()
' If there's an error an
exception is thrown.
' So if we get to here, everything is okay.
MsgBox("AddItem succeeded! The new item ID is: " + item.ItemId)
' React to any
API exception.
Catch ex As APIException
MsgBox("APIException - AddItem call failed: " + ex.Message)
' React to any general
exception.
Catch ex As
Exception
MsgBox("
Exception - AddItem call failed: " + ex.Message)
End Try
The IFees object that is returned by a successful call to AddItem contains the fees for listing the new item on eBay. Of these fees, the insertion fee is the one that will almost always be a nonzero value (except on the Free Listing Days that eBay occasionally offers). So a nonzero insertion fee (and the lack of any
exception) is typically a good indicator that the call was successful and the item was listed on eBay. To check the resulting insertion fee, inspect the value of the IFees.InsertionFee property.
Optional Step: Verify the Item Submission
The ultimate verification that the new item was successfully listed on eBay and all of its properties are correct is to view the item. In the context of an
SDK application, this could be a matter of calling the
API function GetItem (through use of a GetItemCall object). For information on how to do this, see Retrieving an Item with the
API.