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 Trading API.
In this tutorial you will learn:
- What are some of the most useful “Trading API” calls
- How to create an item by using the
AddItemAPI call
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 sudo command$ – requires given linux commands to be executed as a regular non-privileged user |
The Trading API
The 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 App ID, Dev ID, 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:
ebay.yaml configuration with newly eBay generated token and other credentialsAll 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:
#!/usr/bin/env python3
from ebaysdk.trading import Connection
if __name__ == '__main__':
api = Connection(config_file="ebay.yaml", domain="api.sandbox.ebay.com", debug=True)
request = {
"Item": {
"Title": "Professional Mechanical Keyboard",
"Country": "US",
"Location": "IT",
"Site": "US",
"ConditionID": "1000",
"PaymentMethods": "PayPal",
"PayPalEmailAddress": "nobody@gmail.com",
"PrimaryCategory": {"CategoryID": "33963"},
"Description": "A really nice mechanical keyboard!",
"ListingDuration": "Days_10",
"StartPrice": "150",
"Currency": "USD",
"ReturnPolicy": {
"ReturnsAcceptedOption": "ReturnsAccepted",
"RefundOption": "MoneyBack",
"ReturnsWithinOption": "Days_30",
"Description": "If you are not satisfied, return the keyboard.",
"ShippingCostPaidByOption": "Buyer"
},
"ShippingDetails": {
"ShippingServiceOptions": {
"FreeShipping": "True",
"ShippingService": "USPSMedia"
}
},
"DispatchTimeMax": "3"
}
}
api.execute("AddItem", request)
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 api.sandbox.ebay.com.
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.
With 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 PaymentMethods and PayPalEmailAddress keys.
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
The description is another very important field: this allow us to describe the item with an higher level of details. We are not limited to plain text here, we can also use basic html and css code, but we are not allowed to use active contents, so the use of Javascript, for example, is forbidden. If case we want to provide html tags and take advantage of this feature, we must use CDATA specific syntax when using the python SDK:
"Description": "<![CDATA[Html tags are allowed here]]>"
With 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 ReturnsAccepted or ReturnsNotAccepted.
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 MoneyBackOrReplacement.
The 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.
The 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.
With the ShippingCostPaidByOption parameter it’s possible to declare who, between the seller and the buyer should pay the return shipping charges; the accepted values are Seller or Buyer.
Shipping details
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:
Conclusions
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 Merchandising API.
Table of Content
