getOrders

getOrders Get pending, sold and shipped orders for a buyer or seller.

Take a look at some examples in C#, Java, Python, and Ruby.

getOrders Input

getOrders is a secure API method with the following URL and HTTP header requirements:

Submit to URL: https://api.bonanza.com/api_requests/secure_request
Required in HTTP header: X-BONANZLE-API-DEV-NAME set to your dev_id
  X-BONANZLE-API-CERT-NAME set to your cert_id

Note that all secure methods except for fetchToken and getBoothItems require you to submit a user token so that we know what user account you are acting on behalf of.  For details about setting up and submitting user tokens, see our intro to user tokens.

The name for your request should be getOrdersRequest.

Here are the available input parameters that can be serialized into JSON:

Argument Type Occurrence Meaning
requesterCredentials Container Required Container for user credentials
requesterCredentials .bonanzleAuthToken string Required The verified user token for the user who you are acting on behalf of.
Call-specific Input Fields
createTimeFrom dateTime Optional The createTimeFrom and createTimeTo fields specify a date range for retrieving orders. The createTimeFrom field is the starting date range. All Bonanza orders that were created within this date range are returned in the output. This field is not applicable if one or more order IDs are passed in the request.
createTimeTo dateTime Optional The createTimeFrom and createTimeTo fields specify a date range for retrieving orders. The createTimeTo field is the ending date range. All Bonanza orders that were created within this date range are returned in the output. This field is not applicable if one or more order IDs are passed in the request.
modTimeFrom dateTime optional The modTimeFrom and modTimeTo fields specify a date range for retrieving orders. The modTimeFrom field is the starting date range. All Bonanza orders that were modified within this date range are returned in the output. This field is not applicable if one or more order IDs are passed in the request.
modTimeTo dateTime optional The modTimeFrom and modTimeTo fields specify a date range for retrieving orders. The modTimeTo field is the ending date range. All Bonanza orders that were modified within this date range are returned in the output. This field is not applicable if one or more order IDs are passed in the request.
orderIDArray Array of integers Optional Container for an array of specific order IDs to be grabbed.

orderRole
string Optional Specify who to return orders for:
  • Buyer: Value of "buyer" returns all orders in which this user was a buyer.
  • Seller: Value of "seller" returns all orders in which this user was a seller.
orderStatus OrderStatusType Optional

Status of the order. Possible values include

  • Active: The order is in the cart, hasn't yet been checked out
  • Cancelled: The order is cancelled
  • Completed: The order is sold (payment has been successfully processed) but not yet marked as shipped
  • Incomplete: There was an error processing payment for offer
  • InProcess: The order has been checked out by the buyer and we're awaiting payment verification from the payment processor
  • Invoiced: Seller has sent buyer an invoice for sold offer, offer is awaiting payment from buyer
  • Proposed: Offer has been proposed by buyer and is awaiting acceptance
  • Shipped: The order has been marked as shipped
  • Sold: The order is sold (payment has been successfully processed)
soldTimeFrom dateTime optional The soldTimeFrom and soldTimeTo fields specify a date range for retrieving orders. The soldTimeFrom field is the starting date range. All Bonanza orders that were sold within this date range are returned in the output. This field is not applicable if one or more order IDs are passed in the request.
soldTimeTo dateTime optional The soldTimeFrom and soldTimeTo fields specify a date range for retrieving orders. The soldTimeTo field is the ending date range. All Bonanza orders that were sold within this date range are returned in the output. This field is not applicable if one or more order IDs are passed in the request.
paginationInput Container Optional Controls the pagination of the result set. Child elements specify the maximum number of item listings to return per call and the page of data to return. Controls the number of listings returned in the response, but does not specify the details to return for each listing.

Note: No more than 10,000 items can be retrieved for a given search, regardless of how many matches are found. This limit is enforced by the maximum page number allowed (100) and the maximum entries per page allowed (100).
paginationInput.entriesPerPage int Optional Specifies the maximum number of entries to return in a single call. If the number of entries found on the specified pageNumber is less than the value specified here, the number of items returned will be less than the value of entriesPerPage. This indicates the end of the result set.

If entriesPerPage is set to a number greater than 100, the default value, 100, will be used.
Max: 100. Default: 100.
paginationInput.pageNumber int Optional Specifies which subset of data (or "page") to return in the call response. The number of data pages is determined by the total number of items matching the request search criteria (returned in paginationOutput.totalEntries) divided by the number of entries to display in each response (entriesPerPage). You can return up to the first 100 pages of the result set by issuing multiple requests and specifying, in sequence, the pages to return.
Max: 100. Default: 1.

 

getOrders Output

The name for the output returned from this request is getOrdersResponse. So, after parsing the serialized response into JSON, you can access the data with something like my_json_hash['getOrdersResponse']

Here are all the possible output parameters:

 

Argument Type Occurrence Meaning
Standard Output Fields
errorMessage Container Conditionally Description of an error or warning that occurred when Bonanza processed the request. Not returned if the ack value is Success.
errorMessage.error Container Conditionally,
repeatable: [0..*]
errorMessage.error.category ErrorCategory Conditionally Currently unused.
errorMessage.error.message string Conditionally A description of the error
errorMessage.error.type ErrorType Conditionally A unique descriptive name for the error.
timestamp dateTime Always This value represents the date and time when Bonanza processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about this time format and converting to and from the GMT time zone.
warnings Container Conditionally Description of a warning that occurred when Bonanza processed the request.
warnings.unrecognized_parameters Container Conditionally,
repeatable: [0..*]
An array of unrecognized parameters.
Call-specific Output Fields
hasMoreOrders boolean Always Returns true if there are additional orders beyond those returned here, false if not.
paginationOutput Container Conditionally Indicates the pagination of the result set. Child elements indicate the page number that is returned, the maximum number of item listings to return per page, total number of pages that can be returned, and the total number of listings that match the search criteria.
paginationOutput
  .entriesPerPage
int Conditionally The maximum number of items that can be returned in the response. This number is always equal to the value input for paginationInput.entriesPerPage.

The end of the result set has been reached if the number specified for entriesPerPage is greater than the number of items found on the specified pageNumber. In this case, there will be fewer items returned than the number specified in entriesPerPage. This can be determined by comparing the entriesPerPage value with the value returned in the count attribute for the searchResult field.
paginationOutput.pageNumber int Conditionally The subset of item data returned in the current response. Search results are divided into sets, or "pages," of item data. The number of pages is equal to the total number of items matching the search criteria divided by the value specified for entriesPerPage in the request. The response for a request contains one "page" of item data.

This returned value indicates the page number of item data returned (a subset of the complete result set). If this field contains 1, the response contains the first page of item data (the default). If the value returned in totalEntries is less than the value for entriesPerPage, pageNumber returns 1 and the response contains the entire result set.

The value of pageNumber is normally equal to the value input for paginationInput.pageNumber. However, if the number input for pageNumber is greater than the total possible pages of output, Bonanza returns the last page of item data in the result set, and the value for pageNumber is set to the respective (last) page number.
paginationOutput.totalEntries int Conditionally The total number of items found that match the search criteria in your request. Depending on the input value for entriesPerPage, the response might include only a portion (a page) of the entire result set. A value of "0" is returned if Bonanza does not find any items that match the search criteria.
paginationOutput.totalPages int Conditionally The total number of pages of data that could be returned by repeated search requests. Note that if you modify the value of inputPagination.entriesPerPage in a request, the value output for totalPages will change. A value of "0" is returned if Bonanza does not find any items that match the search criteria.
orderArray Container Always Container for array of returned orders.
orderArray.order Container Always Container for an individual order.
orderArray.order.
amountPaid
Amount (double) Always Final price of the order.
orderArray.order.
amountSaved
Amount (double) Always The sum of all discounts (shipping and item) applied to this order.
orderArray.order.
buyerCheckoutMessage
string Always Message from buyer to seller provided during checkout.
orderArray.order.
buyerUserId
integer Always

Bonanza's unique user ID for the buyer.

orderArray.order.
buyerUserName
string Always

User name of the Bonanza buyer.

orderArray.order.
checkoutStatus
Container Always Container for details about checkout status.
orderArray.order.
checkoutStatus.
status
string Always Status of the order in checkout. Possible values include:
  • Complete: Checkout is complete for this order
  • Incomplete: Order has not been through checkout, or order has some other status besides the two above.
  • InProcess: Seller has completed checkout, we're currently awaiting payment information from the processor.
  • Invoiced: Seller has accepted offer, invoice buyer, and checkout is pending buyer action.
  • Pending: 
orderArray.order.
createdTime
dateTime Always The time the order was created.
orderArray.order.
creatingUserRole
string Always Whether this order was initiated by the buyer or seller. Possible values include:
  • Buyer: This order was initiated by a buyer
  • Seller: This order was initiated by a seller (i.e., as a counteroffer)
orderArray.order.
itemArray
Container Always Array providing details about the items in the order.
orderArray.order.
itemArray.
item
Container Always Container for details about an individual item.
orderArray.order.
itemArray.
item.
itemID
integer Always Bonanza's unique ID for this item. For multi-quantity items, this item represents a historical snapshot.
orderArray.order.
itemArray.
item.
parentItemID
integer Conditional When a multi-quantity item is sold, a duplicate historical item is created. parentItemID is the original (non-historical) item's ID.
orderArray.order.
itemArray.
item.
ebayId
integer Optional The unique ebay ID for this item.
orderArray.order.
itemArray.
item.
sellerInventoryID
integer Always The seller-provided SKU for this item.
orderArray.order.
itemArray.
item.
price
Amount (double) Always The price per item for this item.
orderArray.order.
itemArray.
item.
thumbnailURL
String Always URL of the item's image's thumbnail.
orderArray.order.
itemArray.
item.
quantity
integer Always The quantity of this item included in this order.
orderArray.order.
itemArray.
item.
title
string Always The title of this item.
orderArray.order.
itemArray.
item.
variations
Container Optional Container for an item's variations
orderArray.order.
itemArray.
item.
variations.
variation
ItemVariation, optionally [0..*] Optional Details about the selected variation for this item
orderArray.order.
itemArray.
item.
variations.
variation.
nameValueList
NameValueList container, optionally [0..*] Optional A container for the one or more name/value pairs of the item variations
orderArray.order.
itemArray.
item.
variations.
variation.
nameValueList.
name
string Optional The name of the attribute being specified, i.e., "Size". Gathered from GetCategoryTraits.
orderArray.order.
itemArray.
item.
variations.
variation.
nameValueList.
value
string Optional The value of the attribute referred to by "name." For example, if name was "Size" value may be "L". Potential values can be gleaned from from GetCategoryTraits.
orderArray.order.
orderID
integer Always Bonanza's unique numeric identifier for this order
orderArray.order.
orderStatus
OrderStatusType Always

Status of the order. Possible values include

  • Active: The order is in the cart, hasn't yet been checked out
  • Cancelled: The order is cancelled
  • Completed: The order is sold (payment has been successfully processed) but not yet marked as shipped
  • Incomplete: There was an error processing payment for offer
  • InProcess: The order has been checked out by the buyer and we're awaiting payment verification from the payment processor
  • Invoiced: Seller has sent buyer an invoice for sold offer, offer is awaiting payment from buyer
  • Proposed: Offer has been proposed by buyer and is awaiting acceptance
  • Shipped: The order has been marked as shipped
orderArray.order.
paidTime
dateTime Always The time this order was paid for (if applicable).
orderArray.order.
shippingAddress
Container Conditionally Container for details about the shipping destination. Not present in cancelled orders.
orderArray.order.
shippingAddress.
addressID
integer Always Bonanza's unique identifier for this shipping address
orderArray.order.
shippingAddress.
cityName
string Always Name of the city to ship to
orderArray.order.
shippingAddress.
country
string Always Two letter code for the country being shipped to
orderArray.order.
shippingAddress.
countryName
string Always Full name of the country being shipped to
orderArray.order.
shippingAddress.
name
string Always Full name of the person being shipped to
orderArray.order.
shippingAddress.
postalCode
string Always Postal code for the shipping destination
orderArray.order.
shippingAddress.
stateOrProvince
string Always State or province of the shipping destination
orderArray.order.
shippingAddress.
street1
string Always First line of the street address for shipping destination
orderArray.order.
shippingAddress.
street2
string Always Second line of the street address for shipping destination
orderArray.order.
shippingDetails
Container Always Container for details about the order's shipping
orderArray.order.
shippingDetails.
amount
Amount (double) Always Amount charged for shipping on this order.
orderArray.order.
shippingDetails.
insuranceFee
Amount (double) Always Amount charged for shipping insurance on this order, if applicable.
orderArray.order.
shippingDetails.
notes
string Always Notes left to buyer
orderArray.order.
shippingDetails.
servicesArray
Array of strings Always All shipping services the seller offered for the items included in this order.
orderArray.order.
shippingDetails.
shippingService
string Always Any available details on the shipping service specified for the items. Default value for unspecified shipping is "Standard shipping". If the buyer has chosen a more specific shipping option (e.g., "USPS Express Mail (1 business day)") this will be provided.
orderArray.order.
shippedTime
dateTime Always The time the order was shipped (if applicable).
orderArray.order.
subtotal
Amount (double) Always Amount of the order before tax, shipping and discounts
orderArray.order.
total
Amount (double) Always Amount of the order after tax, shipping and discounts
orderArray.order.
transactionArray
Container Always Array of details about this transaction
orderArray.order.
transactionArray.
transaction
Container Always Container for details about this transaction
orderArray.order.
transactionArray.
transaction.
buyer
Container Always Container for details about the buyer in this transaction
orderArray.order.
transactionArray.
transaction.
finalValueFee
Amount (double) Always Total cost of this order billed to seller
orderArray.order.
transactionArray.
transaction.
providerName
string Always Transaction service provider name, one of:
  • Paypal
  • Checkout by Amazon
  • Google Checkout
  • Money order
  • Gift Card
orderArray.order.
transactionArray.
transaction.
providerID
string Always Transaction service provider's ID for this transaction

getOrders Examples