Python Examples
Compatible with Python 2.7 and 3.6
- add_fixed_price_item example
- fetch_token example
- find_items_by_keywords example
- get_categories example
- get_orders example
- set_notification_preferences example
Python Example for addFixedPriceItem
Sample: Adding an Item
Code
Python script to add an item
import requests import json url = 'https://api.bonanza.com/api_requests/secure_request' headers = { 'Content-Type' : 'application/json; charset=utf-8', 'X-BONANZLE-API-DEV-NAME' : 'my_dev_name', 'X-BONANZLE-API-CERT-NAME' : 'my_cert_name' } request_name = 'addFixedPriceItemRequest' # create an input dictionary describing a new item input_dictionary = { 'requesterCredentials': { 'bonanzleAuthToken': 'the_sellers_auth_token' }, 'item': { 'title': 'Lightsaber', 'primaryCategory': { 'categoryId': '163128' }, 'description': 'An elegant weapon, for a more civilized age<br>* SELLER <strong>NOT LIABLE</strong> FOR DISMEMBERMENT *', 'itemSpecifics': [['condition', 'used'], ['danger', 'extreme']], 'price': 42, 'quantity': 3, 'shippingDetails': { 'shippingServiceOptions': { 'shippingType': 'Free', } }, 'pictureDetails': { 'pictureURL': ['https://upload.wikimedia.org/wikipedia/commons/thumb/1/14/Lightsaber%2C_silver_hilt%2C_blue_blade.png/330px-Lightsaber%2C_silver_hilt%2C_blue_blade.png', 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Lightsaber_chopsticks.jpg/255px-Lightsaber_chopsticks.jpg'] }, 'variations': [ { 'quantity': 2, 'nameValueList': [ { 'name': 'Colour', 'value': 'Blue' }, { 'name': 'Style', 'value': 'Single' } ] }, { 'quantity': 1, 'nameValueList': [ { 'name': 'Colour', 'value': 'Red' }, { 'name': 'Style', 'value': 'Double' }, ] } ] }, } # convert the dictionary to JSON payload = json.dumps({ request_name : input_dictionary }) # make the request to Bonanza response = requests.post(url, data=payload, headers=headers) # the JSON response as a dictionary response_json = response.json() if response_json['ack'] == 'Success' and 'addFixedPriceItemResponse' in response_json: output_fields = response_json['addFixedPriceItemResponse'] print("Item ID: " + str(output_fields['itemId'])) print("Category ID: " + str(output_fields['categoryId'])) print("Selling State: " + output_fields['sellingState']) print("Message: " + output_fields['message']) else: print(response_json['errorMessage'])
Data
response_json's value (JSON [formatted for legibility] ):
{ "ack": "Success", "addFixedPriceItemResponse": { "categoryId": 163128, "itemId": 200509, "message": "", "sellingState": "Ready for sale" }, "timestamp": "2019-03-05T10:29:14.000Z", "version": "1.0" }
Python Example for fetchToken
Sample: User Token Fetching
Code
Python script to fetch a token:
import requests url = 'https://api.bonanza.com/api_requests/secure_request' # See your Bonapitit welcome e-mail or your Bonapitit dashboard for # your developer and certificate identifiers headers = { 'X-BONANZLE-API-DEV-NAME' : 'my_dev_name', 'X-BONANZLE-API-CERT-NAME' : 'my_cert_name' } request_name = 'fetchTokenRequest' # make the request to Bonanza response = requests.post(url, data=request_name, headers=headers) # the json response as a dictionary response_json = response.json() # examine the response if response_json['ack'] == 'Success' and 'fetchTokenResponse' in response_json: token_response = response_json['fetchTokenResponse'] print("Your token: " + token_response['authToken']) print("Token expiration time: " + token_response['hardExpirationTime']) print("Authentication URL: " + token_response['authenticationURL']) else: print(response_json)
Data
response_json's value (JSON [formatted for legibility]):
{ "ack": "Success", "fetchTokenResponse": { "authToken": "SomeAuthToken", "authenticationURL": "http://www.bonanza.com/login?apitoken=SomeAuthToken", "hardExpirationTime": "2020-03-05T10:36:36.000Z" }, "timestamp": "2019-03-05T10:36:36.000Z", "version": "1.0" }
Python Example for findItemsByKeywords
Sample: Basic Call
Retrieves a set of items based on keywords provided.
Code
Basic Python script to search for items matching "The King":
import requests import json url = 'https://api.bonanza.com/api_requests/standard_request' headers = { 'Content-Type' : 'application/json; charset=utf-8', 'X-BONANZLE-API-DEV-NAME' : 'my_dev_name', 'X-BONANZLE-API-CERT-NAME' : 'my_cert_name' } request_name = 'findItemsByKeywords' # create an input dictionary specifying the search input_dictionary = { 'keywords' : 'The King', 'paginationInput' : { 'entriesPerPage' : 3 } } # convert dictionary to json payload = json.dumps({ request_name : input_dictionary }) # make the request to Bonanza response = requests.post(url, data=payload, headers=headers) # the json response as a dictionary response_json = response.json() # examine the response if response_json['ack'] == 'Success' and 'findItemsByKeywordsResponse' in response_json: for item in response_json['findItemsByKeywordsResponse']['item']: print("Title: " + item['title']) print("Item URL: " + item['viewItemURL']) else: print(response_json)
Data
response_json's value (JSON):
{ "ack": "Success", "findItemsByKeywordsResponse": { "item": [ { "descriptionBrief": " THE KING MAKER John RhysDavies New DVD ALL OF OUR ITEMS ARE NEW AND FACTORY SEALED THE KING MAKER Gary Stretch Description: Fernando sets sail for the Orient in order to find the man who...", "galleryURL": "http://s3.amazonaws.com/bonanzaimages/afu/images/2889/3800/shirt-chess-king.jpg", "globalId": "BONANZLE", "itemId": 176038, "listingInfo": { "bestOfferEnabled": "false", "buyItNowPrice": "9.0", "convertedBuyItNowPrice": "9.0", "lastChangeTime": "2008-09-19T22:49:17.000Z", "listingType": "FixedPrice", "price": "9.0", "startTime": "2008-09-19T22:49:17.000Z" }, "location": "Dayton, IA", "paymentMethod": [ "PayPal" ], "postalCode": "51442", "primaryCategory": { "categoryId": 617, "categoryIdHierarchy": [ 11232 ], "categoryName": "DVDs & Movies >> DVD, HD DVD & Blu-ray" }, "sellerInfo": { "availableForChat": "false", "feedbackRatingStar": "Red", "membershipLevel": null, "positiveFeedbackPercent": "99.7", "sellerUserName": "aSellerOfItems", "userPicture": "http://s3.amazonaws.com/bonanzaimages/afu/images/2889/3800/shirt-chess-king.jpg" }, "sellingStatus": { "convertedCurrentPrice": "9.0", "currentPrice": "9.0", "sellingState": "Active" }, "shippingInfo": { "internationalShipping": null, "shipToLocations": [ "United States" ], "shippingServiceCost": "4.75", "shippingType": "Flat" }, "sku": null, "storeInfo": { "storeDiscount": null, "storeItemCount": 4875, "storeName": "MOVIE MAGIC USA", "storeURL": "https://bonanza.com/booths/aSellerOfItems" }, "title": "THE KING MAKER - John Rhys-Davies - New DVD", "viewItemURL": "https://www.bonanza.com/booths/moviemagicusa/items/176038" }, { "descriptionBrief": " Filmed on location in Lake Havasu, AZ, this madeforcable domestic drama stars Tim Matheson as Al Dodge, a burnedout intellectual working as a handyman and living in a rundown trailer in the middle of the Arizona desert. Some 15 years earlier, Al ...", "galleryURL": "https://bonanzleimages.s3.amazonaws.com/afu/images/0002/3333/moonlight_001_thumb155_crop.jpg", "globalId": "BONANZLE", "itemId": 5604, "listingInfo": { "bestOfferEnabled": "true", "buyItNowPrice": "3.0", "convertedBuyItNowPrice": "3.0", "lastChangeTime": "2008-08-01T21:23:47.000Z", "listingType": "FixedPrice", "price": "3.0", "startTime": "2008-08-01T21:23:47.000Z" }, "location": "Campton, NC", "paymentMethod": [ "PayPal" ], "postalCode": "27229", "primaryCategory": { "categoryId": 617, "categoryIdHierarchy": [ 11232 ], "categoryName": "DVDs & Movies >> DVD, HD DVD & Blu-ray" }, "sellerInfo": { "availableForChat": "false", "feedbackRatingStar": "Red", "membershipLevel": null, "positiveFeedbackPercent": "99.7", "sellerUserName": "wd350", "userPicture": null }, "sellingStatus": { "convertedCurrentPrice": "3.0", "currentPrice": "3.0", "sellingState": "Active" }, "shippingInfo": { "internationalShipping": null, "shipToLocations": [ "United States" ], "shippingServiceCost": "6.0", "shippingType": "Flat" }, "sku": null, "storeInfo": { "storeDiscount": null, "storeItemCount": 496, "storeName": "wd350's booth", "storeURL": "https://www.bonanza.com/booths/wd350" }, "title": "The King and Queen of Moonlight Bay DVD NEW SEALED", "viewItemURL": "https://www.bonanza.com/booths/wd350/items/5604" }, { "descriptionBrief": "BRAND NEW AND FACTORY SEALED Track listing 1. Tutti Frutti 2. Rip It Up 1 3. Lucille2 4. Jenny Jenny 5. She's Got It 15 6. Girl Can't Help It, The 11 7. Long Tall Sally 1 8. Send Me Lovin' 9. Baby Face 10. Keep A Knockin' 11. Slippin' And Slid...", "galleryURL": "https://bonanzleimages.s3.amazonaws.com/afu/images/0041/4734/alphabetical_richard_thumb155_crop.jpg", "globalId": "BONANZLE", "itemId": 121432, "listingInfo": { "bestOfferEnabled": "false", "buyItNowPrice": "9.99", "convertedBuyItNowPrice": "9.99", "lastChangeTime": "2008-09-12T18:55:09.000Z", "listingType": "FixedPrice", "price": "9.99", "startTime": "2008-09-12T18:55:09.000Z" }, "location": "Flint, AR", "paymentMethod": [ "PayPal" ], "postalCode": "71701", "primaryCategory": { "categoryId": 307, "categoryIdHierarchy": [ 11233 ], "categoryName": "Music >> CDs" }, "sellerInfo": { "availableForChat": "false", "feedbackRatingStar": "Red", "membershipLevel": null, "positiveFeedbackPercent": "99.8", "sellerUserName": "SteveTheSeller", "userPicture": "https://bonanzleimages.s3.amazonaws.com/user_profile_image/afu/user_profile_images/0000/3686/avatar_007.jpg" }, "sellingStatus": { "convertedCurrentPrice": "9.99", "currentPrice": "9.99", "sellingState": "Active" }, "shippingInfo": { "internationalShipping": null, "shipToLocations": [ "United States" ], "shippingServiceCost": 0, "shippingType": "Free" }, "sku": null, "storeInfo": { "storeDiscount": null, "storeItemCount": 186, "storeName": "SomeOtherSeller's booth", "storeURL": "https://www.bonanza.com/booths/SomeOtherSeller" }, "title": "The King of Rock 'N' Roll - Richard, Little (CD 2002) *New*", "viewItemURL": "https://www.bonanza.com/booths/SomeOtherSeller/items/121432" } ], "paginationOutput": { "entriesPerPage": 3, "pageNumber": 1, "totalEntries": 113 } }, "timestamp": "2019-03-05T10:43:17.000Z", "version": "1.0" }
Python Example for getCategories
Sample: Getting Categories
Code
Python script to get information of all children categories of the provided categoryID:
import requests import json url = 'https://api.bonanza.com/api_requests/standard_request' headers = { 'Content-Type' : 'application/json; charset=utf-8', 'X-BONANZLE-API-DEV-NAME' : 'my_dev_name', 'X-BONANZLE-API-CERT-NAME' : 'my_cert_name' } request_name = 'getCategoriesRequest' # create an input dictionary searching for 'Baby' category (2984) input_dictionary = { 'categoryParent': 2984 } # convert the request parameters to json payload = json.dumps({ request_name : input_dictionary }) # make the request to Bonanza response = requests.post(url, data=payload, headers=headers) # the json response as a dictionary response_json = response.json() # examine the response if response_json['ack'] == 'Success' and 'getCategoriesResponse' in response_json: response = response_json['getCategoriesResponse'] for category in response['categoryArray']: print("Category ID: " + str(category['categoryId'])) print("Category Name: " + str(category['categoryName'])) else: print(response_json)
Data
response_json's value (JSON [formatted for legibility]):
{ "ack": "Success", "getCategoriesResponse": { "categoryArray": [ { "categoryBriefName": "Other", "categoryId": 1261, "categoryLevel": 2, "categoryName": "Baby >> Other", "leafCategory": "true", "traitCount": 1 }, { "categoryBriefName": "Strollers", "categoryId": 2989, "categoryLevel": 2, "categoryName": "Baby >> Strollers", "leafCategory": "true", "traitCount": 1 }, { "categoryBriefName": "Toys for Baby", "categoryId": 19068, "categoryLevel": 2, "categoryName": "Baby >> Toys for Baby", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Bathing & Grooming", "categoryId": 20394, "categoryLevel": 2, "categoryName": "Baby >> Bathing & Grooming", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Feeding", "categoryId": 20400, "categoryLevel": 2, "categoryName": "Baby >> Feeding", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Nursery Bedding", "categoryId": 20416, "categoryLevel": 2, "categoryName": "Baby >> Nursery Bedding", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Nursery Furniture", "categoryId": 20422, "categoryLevel": 2, "categoryName": "Baby >> Nursery Furniture", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Baby Safety & Health", "categoryId": 20433, "categoryLevel": 2, "categoryName": "Baby >> Baby Safety & Health", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Potty Training", "categoryId": 37631, "categoryLevel": 2, "categoryName": "Baby >> Potty Training", "leafCategory": "true", "traitCount": 1 }, { "categoryBriefName": "Diapering", "categoryId": 45455, "categoryLevel": 2, "categoryName": "Baby >> Diapering", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Wholesale Lots", "categoryId": 48757, "categoryLevel": 2, "categoryName": "Baby >> Wholesale Lots", "leafCategory": "true", "traitCount": 1 }, { "categoryBriefName": "Car Safety Seats", "categoryId": 66692, "categoryLevel": 2, "categoryName": "Baby >> Car Safety Seats", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Nursery Decor", "categoryId": 66697, "categoryLevel": 2, "categoryName": "Baby >> Nursery Decor", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Baby Gear", "categoryId": 100223, "categoryLevel": 2, "categoryName": "Baby >> Baby Gear", "leafCategory": "false", "traitCount": 1 }, { "categoryBriefName": "Stroller Accessories", "categoryId": 117038, "categoryLevel": 3, "categoryName": "Baby >> Stroller Accessories", "leafCategory": "true", "traitCount": 1 }, { "categoryBriefName": "Keepsakes & Baby Announcements", "categoryId": 117388, "categoryLevel": 2, "categoryName": "Baby >> Keepsakes & Baby Announcements", "leafCategory": "false", "traitCount": 1 } ] }, "timestamp": "2019-03-05T10:46:41.000Z", "version": "1.0" }
Python Example for getOrders
Sample: Getting Orders
Code
Python script to get order information for a seller in a specific time period
import requests import json url = 'https://api.bonanza.com/api_requests/secure_request' headers = { 'Content-Type' : 'application/json; charset=utf-8', 'X-BONANZLE-API-DEV-NAME' : 'my_dev_name', 'X-BONANZLE-API-CERT-NAME' : 'my_cert_name' } request_name = 'getOrdersRequest' # create an input hash searching for orders in a time period input_dictionary = { 'requesterCredentials': { 'bonanzleAuthToken': 'sellers_auth_token' }, 'orderRole': 'seller', 'soldTimeFrom': '2018-01-13', 'soldTimeTo': '2019-01-13', 'paginationInput': { 'entriesPerPage': 3 } } payload = json.dumps({ request_name : input_dictionary }) # make the request to Bonanza response = requests.post(url, data=payload, headers=headers) # the json response as a dictionary response_json = response.json() # examine the response if response_json['ack'] == 'Success' and 'getOrdersResponse' in response_json: response = response_json['getOrdersResponse'] for order_dico in response['orderArray']: order = order_dico['order'] print("Order " + str(order['orderID']) + "------------------") print("Buyer Username: " + str(order['buyerUserName'])) print("Amount Paid: " + str(order['amountPaid'])) print("Checkout Status: " + str(order['checkoutStatus']['status'])) print("Created Time: " + str(order['createdTime'])) else: print(response_json)
Data
response_json's value (JSON [formatted for legibility]):
{ "ack": "Success", "getOrdersResponse": { "hasMoreOrders": "true", "orderArray": [ { "order": { "amountPaid": "10.4", "amountSaved": 0.0, "buyerCheckoutMessage": "", "buyerUserID": 1382, "buyerUserName": "JonnyBonz", "checkoutStatus": { "status": "Complete" }, "createdTime": "2018-12-11T18:03:58Z", "creatingUserRole": "Buyer", "itemArray": [ { "item": { "itemID": 200369, "parentItemID": 200356, "personalizedText": [], "price": "10.0", "quantity": 1, "sellerInventoryID": "5k00", "sku": "5k00", "thumbnailURL": null, "title": "uBSZW8iWWhIv Title" } } ], "orderID": 1675, "orderStatus": "Completed", "paidTime": "2018-12-11T18:14:47Z", "shippingAddress": { "addressID": 5004, "cityName": "Faubourg", "country": "US", "countryName": null, "name": "Jonny Bonz", "postalCode": "98121", "stateOrProvince": "WA", "street1": "123 Rue des fausses", "street2": "" }, "shippingDetails": { "amount": "0.0", "insuranceFee": 0, "notes": null, "servicesArray": [], "shipmentTrackingNumber": { "200369": [] }, "shippingService": "Standard shipping" }, "subtotal": 10.0, "taxAmount": 0.4, "total": "10.4", "transactionArray": { "transaction": { "buyer": { "email": "api@bonanza.com" }, "finalValueFee": "0.5", "providerID": "a_provider_id", "providerName": "Stripe" } } } }, { "order": { "amountPaid": "10.4", "amountSaved": 0.0, "buyerCheckoutMessage": "", "buyerUserID": 1357, "buyerUserName": "JimmyBonz", "checkoutStatus": { "status": "Complete" }, "createdTime": "2018-12-11T18:04:15Z", "creatingUserRole": "Buyer", "itemArray": [ { "item": { "itemID": 200371, "parentItemID": 200357, "personalizedText": [], "price": "10.0", "quantity": 1, "sellerInventoryID": "5k00", "sku": "5k00", "thumbnailURL": null, "title": "lHOb Title" } } ], "orderID": 1676, "orderStatus": "Completed", "paidTime": "2018-12-11T18:14:09Z", "shippingAddress": { "addressID": 5004, "cityName": "Faubourg", "country": "US", "countryName": null, "name": "Jimmy Bonz", "postalCode": "98121", "stateOrProvince": "WA", "street1": "125 Rue des fausses", "street2": "" }, "shippingDetails": { "amount": "0.0", "insuranceFee": 0, "notes": null, "servicesArray": [], "shipmentTrackingNumber": { "200371": [] }, "shippingService": "Standard shipping" }, "subtotal": 10.0, "taxAmount": 0.4, "total": "10.4", "transactionArray": { "transaction": { "buyer": { "email": "api@bonanza.com" }, "finalValueFee": "0.5", "providerID": "anotherId", "providerName": "Stripe" } } } }, { "order": { "amountPaid": "10.4", "amountSaved": 0.0, "buyerCheckoutMessage": "", "buyerUserID": 1357, "buyerUserName": "JammyBonz", "checkoutStatus": { "status": "Complete" }, "createdTime": "2018-12-11T18:04:26Z", "creatingUserRole": "Buyer", "itemArray": [ { "item": { "itemID": 200368, "parentItemID": 200358, "personalizedText": [], "price": "10.0", "quantity": 1, "sellerInventoryID": "5k00", "sku": "5k00", "thumbnailURL": null, "title": "7Em Title" } } ], "orderID": 1677, "orderStatus": "Completed", "paidTime": "2018-12-11T18:13:36Z", "shippingAddress": { "addressID": 5004, "cityName": "Faubourg", "country": "US", "countryName": null, "name": "Jammy Bonz", "postalCode": "98121", "stateOrProvince": "WA", "street1": "124 Rue des fausses", "street2": "" }, "shippingDetails": { "amount": "0.0", "insuranceFee": 0, "notes": null, "servicesArray": [], "shipmentTrackingNumber": { "200368": [] }, "shippingService": "Standard shipping" }, "subtotal": 10.0, "taxAmount": 0.4, "total": "10.4", "transactionArray": { "transaction": { "buyer": { "email": "api@bonanza.com" }, "finalValueFee": "0.5", "providerID": "yet_another_id", "providerName": "Stripe" } } } } ], "pageNumber": 1, "paginationResult": { "totalNumberOfEntries": 59, "totalNumberOfPages": 20 } }, "timestamp": "2019-03-05T10:49:49.000Z", "version": "1.0" }
Python Example for setNotificationPreferences
Sample: Setting notification preferences
Code
Python code to register a URL to listen for seller question/feedback notifications
import requests import json url = 'https://api.bonanza.com/api_requests/secure_request' headers = { 'Content-Type' : 'application/json; charset=utf-8', 'X-BONANZLE-API-DEV-NAME' : 'your_dev_id', 'X-BONANZLE-API-CERT-NAME' : 'your_cert_id' } request_name = 'setNotificationPreferencesRequest' # register foo.com/notifications to listen for askSellerQuestion and seller feedback notifications input_dictionary = { 'requesterCredentials': { 'bonanzleAuthToken': 'sellers_auth_token' }, 'applicationDeliveryPreferences': { 'applicationEnable': 'Enable', 'deliveryURLDetails': { 'deliveryURL': 'foo.com/notifications', 'status': 'Enable' } }, 'userDeliveryPreferenceArray': { 'notificationEnable': [ { 'eventEnable': 'Enable', 'eventType': 'askSellerQuestion' }, { 'eventEnable': 'Enable', 'eventType': 'feedback' } ] } } # convert the dictionary to JSON payload = json.dumps({ request_name : input_dictionary }) # make the request to Bonanza response = requests.post(url, data=payload, headers=headers) # the JSON response as a dictionary response_json = response.json() if response_json['ack'] == 'Success' and 'setNotificationPreferencesResponse' in response_json: response_details = response_json['setNotificationPreferencesResponse'] print(response_details) else: print(response_json)
Data
response_json's value (JSON [formatted for legibility]):
{ "ack": "Success", "setNotificationPreferencesResponse": { "deliveryURLsProcessed": 1, "eventsProcessed": 2, "notificationId": 1 }, "timestamp": "2019-03-05T10:52:16.000Z", "version": "1.0" }