BBAPI: Orders Command
Orders can be viewed and managed from the Nigma API by using the SetOrders and GetOrders commands. This document will explain how to use each.
On This Page:
Available Commands
SetOrders
Save or update an order in the system. This command accepts a cartID to allow you to easily convert a cart to an order.
GetOrders
Retreive order data from the system. By default, 'expensive' data such as tax and shipping calculations are not included in the order details. To see these details you must call getItems in your <param> xml.
Example 1: Input
Here is an example of what would be sent to the API to place an order. The easiest way to place a new order is from an already constructed shopping cart. If you wish to transfer a cart to an order, the shopping cartID should be passed in as a parameter when calling the SetOrders command as shown below.
Example 1: Response
The API will return the results of your request as shown below. There are a few points worth noting regarding how the system generates an order:
- Even if all items in the order are marked as non-shipable, the system will still choose a default shipping method that would be used. The cost of shippig will still come out to 0 as expected.
- Billing and shipping information can be passed into the system (see example below for an in-depth view of order parameters) but if this data is not provided, it will be grabbed from the clients current information.
- Placing an order does not bill the order or create an invoice. All orders marked as pending or active are capable of generating invoices. You should class processOrders to have an invoice generated for the order.
- The items within an order may also have a status. This allows a great deal of flexibility for orders that may contain recurring billing cycles.
Example 2: Input
Orders can also be built from scratch without using a cart. In this method, you only need to specify the product-items and not necassarily the parent product. Using this method, you must also be aware not to break any of the store owners rules regarding optional/required item relationships. If you are adding a required item to the order, you must be aware to add all required items to the order. This method is shown below.
Example 2: Response
The returned xml will include all details such as shipping and tax and all calculations such as the sub-total and grand total pre-computed for you.
Example 3: Input
This next example will demonstrate how to retrieve order xml data from the API.
Example 3: Response
Summary of Nodes
Here is a summary of the nodes that make up the <param> xml and their meaning.
Node |
Type | Description |
|---|---|---|
orderID |
Integer | Unique ID for order. Use this to look up a specific order. |
| orderCartID | Integer | Unqiue ID of a cart that should be converted to an order. |
| orderClientID | Integer | Unique ID of client the order is being inserted for. |
| orderDate | Integer | Date order was created. |
| orderDateLastUpdated | Integer | Date order was last updated. |
| orderSubTotal | Double | Sub-total of order. |
| orderShippingMethodID | Integer | Unqiue ID of shipping method use to calculate order shipping. |
| orderShippingMethodName | String | Name of shipping method used to calculate order shipping. |
| orderShippingCost | Double | Cost of shipping. |
| orderTax | Double | Tax on order. |
| orderTotal | Double | Grand total of order including tax and shipping. |
| orderNote | String | Optional note with order. Typically this is customer's notes. |
| orderCustomData | String/XML | Custom data associated with order. Typically these are notes that will be used in the back-end and not seen by the customer. |
| orderArchive | Char | If the order is archived. |
| orderLocationID | Integer | Unique ID of location that order was placed at. |
| orderLocationName | String | Name of location that order was placed at. |
| orderAdminID | Integer | Unique ID of admin that was used to place the order. |
| orderFirstName | String | Billing first name. |
| orderLastName | String | Billing last name. |
| orderAddress | String | Billing address. |
| orderAddress2 | String | Line 2 of billing address. |
| orderCity | String | Billing city. |
| orderState | String | Billing state. |
| orderZip | String | Billing postal code. |
| orderCountryID | Integer | Billing country ID. |
| orderCountryName | String | Billing country name. |
| orderShippingFirstName | String | Shipping first name. |
| orderShippingLastName | String | Shipping last name. |
| orderShippingAddress | String | Shipping address. |
| orderShippingAddress2 | String | Shipping address line 2. |
| orderShippingCity | String | Shipping city. |
| orderShippingState | String | Shipping state. |
| orderShippingZip | String | Shipping postal code. |
| orderShippingCountryID | Integer | Country ID of shipping country. |
| orderShippingCountryName | String | Name of shipping country. |
| orderEmail | String | Email address of customer. |
| orderPhone | String | Phone of customer. |
| orderProducts | XML | All product nodes that are in the order. |
| orderProduct | XML | A single product within the order. See products page for details in product node. |
| productPrice | Double | Calculated price of product for this order. May have been manipulated by admin for special pricing. |
| orderProductItems | XML | All item nodes that were purchased for the product. |
| orderProductItem | XML | A single item node within the product. |
| orderItemID | Integer | Unique ID for this item. |
| orderItemItemID | Integer | Unique ID of the product-item ID. |
| orderItemQuantity | Integer | Quantity of items ordered. |
| orderItemPrice | Double | Price of item within order. This value may be manipulated to offer special pricing. |
| orderItemCycle | Integer | Unique ID of item's billing cycle. |
| orderItemStatusID | Integer | ID of status. Possible values are:
If an item is cancelled from the order it will not appear in future invoices. |
| orderItemStatusName | String | Textual representation of the item's status. |
| orderItemDownloadCount | Integer | Quantity of files available for download for this item. This should signify if you need to offer a link to download for this item. |
| orderItemName | String | Name of the item. |
| orderHistories | XML | All status-change history xml nodes. You must call <getHistory>y</getHistory> to receive this information. |
| historyID | Integer | Unique ID of history row. |
| historyStatusID | Integer | New status of the order. This is the status the order was changed to on the given date. This may not be the current status. |
| historyStatusName | String | Textual representation of the status. |
| historyDate | Integer | Date status was changed. |
| historyMessage | String | Possible message for why order status was changed. |
| historyAdminID | Integer | ID of admin that changed the status of the order. |
| historyAdminName | String | Name of admin that changed the status. |
