This is the third article of the series dedicated to Ebay APIs and their use via python. In the first article we saw how to setup our working environment, creating a developer and a sandbox "test" account, generating our API keys and installing the python SDK.
In the second article we approached the
Finding API, focusing on the
findItemsByKeywords call. In this article we will introduce the
In this tutorial you will learn:
- What are some of the most useful "Trading API" calls
- How to create an item by using the
Software Requirements and Conventions Used
|Category||Requirements, Conventions or Software Version Used|
|System||Operating system agnostic.|
|Software||git and python3|
|Other||Knowledge of the python programming language and of the basic object oriented concepts.|
|Conventions|| # - requires given linux commands to be executed with root privileges either directly as a root user or by use of |
The Trading API
Trading API is the subject of this third article in this series dedicated to python and the Ebay APIs. This specific API includes a lot of very useful calls: by using it we can, among other things, create or end items and retrieve information about categories, stores or sellers.
The Trading API calls
The list of the available
Trading API calls is too long to be presented here in its entirety, however, here we present some of them and the goal we can accomplish with their use:
- AddItem - By using this call we can start selling an item both with fixed price or with an auction
- AddToWatchList - By using this call we can add one or more items to our watchlist
- EndItem - With this call we can stop selling an article before the set expiration date
- GetCategories - Use this call to obtain information about Ebay's categories for a specific site
- GetMyEbaySelling - Retrieve information about our selling activity
- GetStore - Retrieve information about a specific Ebay store
The way we use these calls is the same we saw in the previous article: we create and send a request together with the call name. To find the complete list of available calls, please read the official documentation.
Generating a token
Before proceeding, make sure you have created a sandbox "test" user and followed the steps included in the first article of this series. Inside the root of our project, we used the
ebay.yaml file to store our credentials for the various domains. To use the
Trading API, and interact with the sandbox "test" user, we must provide our
Cert ID and a token we will now generate.
Obtaining a token is quite easy. Access the Ebay developer program website, and navigate to the Application keys page; here, in the sandbox section (left side), inside the
App ID field, click on the
User Tokens link. You will be redirected to this section:
Click on the "Sign in to Sandbox" blue button and you will be sent to the sandbox site login page. Here you must use the sandbox "test" user you previously created. Once you log in successfully, you will prompted to confirm you want to grant access to your account data:
Click on the "agree" button, and you will be redirected back to the token generation page. Here you will see the new generated token:
The next step is to copy the token and the other credentials inside the
ebay.yaml file, in the corresponding section, just like in the picture below:
All is in place, let's create our item!
Creating an item with the AddItem API call
Inside the root of our project, let's create a new script, and call it
additem.py. Inside of it we will write the code needed to create our first item. Supposing we want to sell a mechanical keyboard, here is the code we could write:
Let's take a look at the code above. As a first thing, we imported the
Connection class from the
ebaysdk.trading module. We the needed library in place, we created a new instance of the
Connection class: in its constructor we specified the location of the configuration file, just as we did for the Finding API, and also the domain to be used for the request, which in this case is
Doing so we declared that our request will be sent to the sandbox site: our credentials will be searched in the configuration file depending on this domain. Finally, we enabled debug mode: this is very useful when doing a complex request, because possible errors will be immediately detected.
The next step was the creation of the request and the description of our
Item in the form of a simple python dictionary. Let's briefly see the various properties we used.
Location and country information
By using the
Title option we specified the title of our listing: when selling an item on Ebay, finding a good title is very important. With
Country we declared the country of the seller registration address: this value consists in two digits; you can consult this list to find all the possible applicable values.
The next key we used is
Location: this is needed to specify the geographical location of the item, in this case Italy.
Site, instead, we specified the Ebay Site in which the item should appear. This parameter does affect other ones, like, for example, the identifiers of the available categories, since the same category can have different IDs on the different websites. This value must be consistent with the site specified in the constructor of the
Connection class (the default is "EBAY-US").
Declaring the item conditions
Another important thing to define is the condition of the article. An article can be new or used for example, and some particular articles have dedicated condition that can be used, depending on their category. In this case we used
"1000" which is the code that corresponds to the "new" status. A table of the available codes can be found here.
Setting a payment method
The payment method we are willing to accept can be picked from the list of all the available payment methods. In this case we used "PayPal", and we also provided the email address to be used for the payment, respectively by using the
Choosing a category for the item
The next step was defining a category for the item we are selling: we did it by using the
PrimaryCategory key, which corresponds to a dictionary in which the actual category ID is identified by the
CategoryID key. Each category is identified by an unique ID in the context of a specific site, but the identifiers can be different on the several Ebay sites. Finding the right category can be a tedious task. To find the appropriate one you can use specific calls like
GetSuggestedCategories or you can consult online tools like this.
Another important thing to notice is that, when choosing a category for an item, Ebay expects that you use one of the last segment of a category tree (a "leaf" category): you can't use a generic one. In this case we used
33963 which corresponds to
Keyboards & Keypads and is one of the last segments of the
Computers/Tablets & Networking category, its full path being Computers/Tablets & Networking > Keyboards, Mice & Pointers > Keyboards & Keypads.
Setting the item description and price
CDATA specific syntax when using the python SDK:
"Description": "<![CDATA[Html tags are allowed here]]>"
ListingDuration we specified the interval of time the listing should remain active. Ebay uses a list of code types to be used in this field (some types have a restricted use). In this case we used
"Days_10" which specify a duration of 10 days.
The value we provide for
StartPrice is interpreted differently depending on the type of listing: if it is an auction, this is considered to be the auction starting price; if it is a fixed-price listing, instead, it is considered as the constant price the client must pay to buy the item. Our keyboard costs
150 unit of the currency we specified with
Currency. The value to be used here must be picked from the list of available currencies.
Establishing a return policy
The next section we defined was the
ReturnPolicy section which describes our policy about returns. This section is defined as a dictionary itself, inside which we used the following keys:
ReturnAcceptedOption defines if whether the seller accepts returns or not: applicable values are
RefundOption defines how sellers refunds the buyers on returns: on all Ebay marketplaces this value must be set to
MoneyBack, while on the US marketplace it can be also set to
ReturnsWithinOption parameter is pretty self explanatory: with this parameter we specify the amount of time from deliver the buyer has to return the item back. The list of the values usable in this section is available at this page. In this case we used
"Days_30": a time of 30 days must be used to qualify as a "Top Rated" listing.
Description field contains a detailed explanation of the seller return policy and its displayed in the relative section of the "view item" page. A friendly message is usually provided here.
ShippingCostPaidByOption parameter it's possible to declare who, between the seller and the buyer should pay the return shipping charges; the accepted values are
Another very important section to define is the one about the shipping policy and costs: this can be done by using the
ShippingServiceOption key. This key is associated with a dictionary in which we can define various parameters. In this case we set a free shipping policy, by using the
FreeShipping key, and providing
True (string) as the value, and we defined the shipping service with
ShippingService. Consult this list for a complete overview of possible values to be used here.
Finally, we used the
DispatchTimeMax option, which basically defines the maximum number of business days a seller declares will be used to prepare the shipping after receiving a payment.
Sending our request and verify the result
We prepared our request and provided the needed information about the item we want to sell; now we can send our request by using the
execute method, providing, just like we did for the
Finding API, the name of the call,
AddItem as its first argument, and the request dictionary as the second one. If everything goes well after the request is sent, the item should be now present on the sandbox site. So it is:
In this article we approached the
Trading API. Among the many available calls, we focused on the
AddItem one. We created an item providing the necessary fields for a basic configuration and sent our request successfully to our sandbox account. In the next article of this series we will talk about the
Table of Content