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. This includes invoiced and accepted offers.
  • 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
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.
paginationResult 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.
paginationResult.totalNumberOfEntries 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.
paginationResult.totalNumberOfPages 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.
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.
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.
mpn		 String Optional The MPN for this item, if specified.
orderArray.order.
itemArray.
personalizedText		 Container Optional Container for details about an individual item.
orderArray.order.
itemArray.
item.
personalizedText.
label		 String Always The label of this item personalization field.
orderArray.order.
itemArray.
item.
personalizedText.
body		 String Always The buyer-provided text for this personalization field.
orderArray.order.
itemArray.
item.
price		 Amount (double) Always The price per item for this item.
orderArray.order.
itemArray.
item.
sellerInventoryID		 integer Always The seller-provided SKU 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.
itemArray.
item.
variations.
variation.
sku		 string Optional The SKU of the variation.
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.
shippingDetails.
shipmentTrackingNumber

 Container Always Container that will map item id(s) to shipment tracking number(s)

orderArray.order.
shippingDetails.
shipmentTrackingNumber.
ItemId

 Container Optional Lists all tracking ids submitted for this item within the order

orderArray.order.
shippingDetails.
shipmentTrackingNumber.
ItemId.
trackingId

 string, optionally [0..*] Optional Tracking code provided by the seller in completeSale or from Selling Dashboard
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.
taxAmount		 Amount (double) Conditionally Amount of taxed charged for the order
orderArray.order.
telephoneNumber		 String Always The buyer's telephone number
orderArray.order.
total		 Amount (double) Always Amount of the order after tax, shipping and discounts
orderArray.order.
currencyCode		 String Always Currency code used for the purchase
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