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:
|
orderStatus | OrderStatusType | Optional |
Status of the order. Possible values include
|
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:
|
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:
|
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
|
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. |
Container | Always | Container that will map item id(s) to shipment tracking number(s) |
orderArray.order. |
Container | Optional | Lists all tracking ids submitted for this item within the order |
orderArray.order. |
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:
|
orderArray.order. transactionArray. transaction. providerID |
string | Always | Transaction service provider's ID for this transaction |