There is a newer version of the API available. To link to the newest API documentation, click here - Version 20110301
  1. Introduction
  2. Getting Started
  3. Failure Codes
  4. Sandbox
  5. Export Automation
  6. Limits
  7. Order Lifecycle


Copyright Notice

© 2005-2018 DOBA, Inc. All Rights Reserved.

The information contained in this reference document is proprietary and confidential. For more information, contact:

This document and the API therein may only be used in accordance with the terms contained within a signed Doba Partnership Agreement.

Doba and the Doba logo are trademarks of DOBA, Inc. All other brands are the property of their respective owners.


The Doba API allows you to utilize the Doba supply chain platform programmatically within your own application. The API includes functions to search or browse the Doba product catalog, obtain detailed product information, lookup shipping and handling charges, submit orders, fund orders, obtain shipment information for orders when they ship. Additional functions are provided for partners who want to create subscription members or leads and manage the account through the member life-cycle.

The API includes the following systems:


User API

Allows for the creation and manipulation of Doba member accounts.

The User API can be used to submit leads or new users to the Doba platform. If agreed to beforehand, revenue due to upgrades and subscription payments can be shared.


Product API

Allows for the retrieval of on-demand and up-to-the-minute product data from the Doba platform.


Order API

Allows for the submittal of orders to the Doba platform as well as the retrieval of current order status and shipping/tracking data.

Orders submitted via the API can be funded through the API using several different payment methods.

Current order status can be called at any time although status updates can be provided in real-time through callback's.



Callbacks are sent to the URL on file to notify the integrators system of changes in order status, product status, etc. Callbacks are significant due to its purpose of keeping the end-user up to date with the most accurate information available to the Doba platform.

For example: When the status of a product changes from in-stock to out-of-stock, the retailer's system will be informed via callback if the product is currently being sold by that retailer. When an supplier submits shipment tracking information through the Doba platform, the retailers system will be notified via callback.

Release Notes

Version Release Date Change By
Beta January 30, 2008 Beta-Release TW
Beta February 08, 2008 Updated Sandbox and WSDL sections along with minor updates throughout. TW
Beta February 28, 2008 Updated XML Authentication sections for both Partner and Retailer API calls.
Added required dashes to phone number in addRetailer calls.
Updated sandbox URL to reflect correct URL for Retailers.
Beta March 05, 2008 Removed requirements for retailer_id in Retailer API calls. TW
Beta July 23, 2008 Minor updates throughout the documentation. Added additional examples to Method Reference. TW
Beta September 18, 2008 Updated callback section to reflect new format. TW
Final January 6, 2009 The Doba API is now in final release status. TW
Final March 3, 2009 Major documentation update along with new API methods for the Retailer API. TW
Final August 26, 2009 getProductSearch will be updated soon to return the new category information.
getProductDetail will return the new category information on August 31, 2009.
getItemSearch should be used for all new implimentations.

Release Schedule

Doba strives to provide the most robust, flexible and reliable API and as such may deem it necessary to update functionality or provide bug fixes as required. We understand that certain changes to the API could disrupt the integrations of our API clients and have set up the following schedule for releaseing any updates to the API.

  1. All updates will be available on the Sandbox server for testing and validation for one week prior to any updates being released on the production servers.
  2. Notification of all changes to the API will be provided to all API clients one week prior to the release.
  3. Updates will be sent to the email address stored on your account.
  4. Updates to the API will be released, typically, on the first Tuesday of the month at 2:00 PM MST.




Getting Started


The Doba API utilizes industry standard solutions including SOAP and XML in an effort to simplify the integration process and to ensure compatibility among software platforms.



SOAP, which stands for Simple Object Access Protocol, is a protocol for exchanging XML-based messages over computer networks, normally using HTTP/HTTPS. SOAP forms the foundation layer of the Web services stack, providing a basic messaging framework upon which abstract layers can be built.

Please visit Wikipedia for a more thorough introduction to SOAP.

All API calls are sent via HTTPS requests. The XML for the SOAP request is sent as an HTTP POST request; the response is sent back as the response to the POST.

To aid in development, you may utilize toolkits specially designed to work with SOAP API's. Together with the WSDL, explained below, development time of your application with the Doba API can be shortened greatly. The toolkit will do the heavy lifting when it comes to generating the XML required to interact with the API. The WSDL provides the necessary API specifications required for each function and provides your application with the format and options available to each API function.

The toolkit you will use depends on the development environment you currently employ. Some toolkits require you to write more XML than others so research the options available to you before implementing a new solution.



The Web Services Description Language (WSDL, pronounced 'wiz-dul' or spelled out, 'W-S-D-L') is an XML-based language that provides a model for describing Web services.

Please visit Wikipedia for a more thorough introduction.

The Doba API WSDL defines all of the functions available through the API along with their data types. Using the WSDL can greatly decrease the development time needed to integrate with the Doba API. The location of the Doba API WSDL's are provided below.



Extensible Markup Language (XML) is a general-purpose markup language. It is classified as an extensible language because it allows its users to define their own tags. Its primary purpose is to facilitate the sharing of structured data across different information systems, particularly via the Internet.

Please visit Wikipedia for a more thorough introduction to XML.






When implimenting the API using XML, you will POST your calls to the URL intended for the environment you are currently working in.

The following URL is to be used for development and testing: [link]

The following URL is to be used in production after testing on the sandbox server has been validated: [link]



XML Structure

Certain required elements are required of every API call regardless of the functions used.

The <dce> tag must enclose everything else, meaning that it should open at the beginning of the call and should close as the end of the call.

The <authentication> tag must follow the opening <dce> tag. The API account's username and password will be included to verify access rights to the API.

The <request> tag will encapsulate the actions request, the core of each API call.



XML Request Outline

            <username><!-- retailer username --></username>
            <password><!-- retailer password --></password>

  <action><!-- request specific action --></action>
  <!-- action specific xml request data -->




XML Response Outline

Each API request will return a response inside the <response> tag. The <action> tag will repeat the action requested.

The <outcome> tag will indicate whether the call succeeded or failed. If the call failed, it will provide additional information that will indicate the level of failure that has occurred.

The ENTITY information is provided to ensure that no special characters will cause problems while parsing the data. Your XML parsing system should use the ENTITY information to replace special characters throughout the response automatically.

<?xml version="1.0"?>
<!DOCTYPE dce [
<!ENTITY apos "&#39;">
<!ENTITY minus "&#45;">
<!ENTITY circ "&#94;">
<!ENTITY tilde "&#126;">
<!ENTITY Scaron "&#138;">
<!ENTITY lsaquo "&#139;">
<!ENTITY OElig "&#140;">
<!ENTITY lsquo "&#145;">
<!ENTITY rsquo "&#146;">
<!ENTITY ldquo "&#147;">
<!ENTITY rdquo "&#148;">
<!ENTITY bull "&#149;">
<!ENTITY ndash "&#150;">
<!ENTITY mdash "&#151;">
<!ENTITY trade "&#153;">
<!ENTITY scaron "&#154;">
<!ENTITY rsaquo "&#155;">
<!ENTITY oelig "&#156;">
<!ENTITY Yuml "&#159;">
<!ENTITY yuml "&#255;">
<!ENTITY fnof "&#402;">
<!ENTITY Alpha "&#913;">
<!ENTITY Beta "&#914;">
<!ENTITY Gamma "&#915;">
<!ENTITY Delta "&#916;">
<!ENTITY Epsilon "&#917;">
<!ENTITY Zeta "&#918;">
<!ENTITY Eta "&#919;">
<!ENTITY Theta "&#920;">
<!ENTITY Iota "&#921;">
<!ENTITY Kappa "&#922;">
<!ENTITY Lambda "&#923;">
<!ENTITY Mu "&#924;">
<!ENTITY Nu "&#925;">
<!ENTITY Xi "&#926;">
<!ENTITY Omicron "&#927;">
<!ENTITY Pi "&#928;">
<!ENTITY Rho "&#929;">
<!ENTITY Sigma "&#931;">
<!ENTITY Tau "&#932;">
<!ENTITY Upsilon "&#933;">
<!ENTITY Phi "&#934;">
<!ENTITY Chi "&#935;">
<!ENTITY Psi "&#936;">
<!ENTITY Omega "&#937;">
<!ENTITY alpha "&#945;">
<!ENTITY beta "&#946;">
<!ENTITY gamma "&#947;">
<!ENTITY delta "&#948;">
<!ENTITY epsilon "&#949;">
<!ENTITY zeta "&#950;">
<!ENTITY eta "&#951;">
<!ENTITY theta "&#952;">
<!ENTITY iota "&#953;">
<!ENTITY kappa "&#954;">
<!ENTITY lambda "&#955;">
<!ENTITY mu "&#956;">
<!ENTITY nu "&#957;">
<!ENTITY xi "&#958;">
<!ENTITY omicron "&#959;">
<!ENTITY pi "&#960;">
<!ENTITY rho "&#961;">
<!ENTITY sigmaf "&#962;">
<!ENTITY sigma "&#963;">
<!ENTITY tau "&#964;">
<!ENTITY upsilon "&#965;">
<!ENTITY phi "&#966;">
<!ENTITY chi "&#967;">
<!ENTITY psi "&#968;">
<!ENTITY omega "&#969;">
<!ENTITY thetasym "&#977;">
<!ENTITY upsih "&#978;">
<!ENTITY piv "&#982;">
<!ENTITY ensp "&#8194;">
<!ENTITY emsp "&#8195;">
<!ENTITY thinsp "&#8201;">
<!ENTITY zwnj "&#8204;">
<!ENTITY zwj "&#8205;">
<!ENTITY lrm "&#8206;">
<!ENTITY rlm "&#8207;">
<!ENTITY sbquo "&#8218;">
<!ENTITY bdquo "&#8222;">
<!ENTITY dagger "&#8224;">
<!ENTITY Dagger "&#8225;">
<!ENTITY hellip "&#8230;">
<!ENTITY permil "&#8240;">
<!ENTITY prime "&#8242;">
<!ENTITY Prime "&#8243;">
<!ENTITY oline "&#8254;">
<!ENTITY frasl "&#8260;">
<!ENTITY euro "&#8364;">
<!ENTITY image "&#8465;">
<!ENTITY weierp "&#8472;">
<!ENTITY real "&#8476;">
<!ENTITY alefsym "&#8501;">
<!ENTITY larr "&#8592;">
<!ENTITY uarr "&#8593;">
<!ENTITY rarr "&#8594;">
<!ENTITY darr "&#8595;">
<!ENTITY harr "&#8596;">
<!ENTITY crarr "&#8629;">
<!ENTITY lArr "&#8656;">
<!ENTITY uArr "&#8657;">
<!ENTITY rArr "&#8658;">
<!ENTITY dArr "&#8659;">
<!ENTITY hArr "&#8660;">
<!ENTITY forall "&#8704;">
<!ENTITY part "&#8706;">
<!ENTITY exist "&#8707;">
<!ENTITY empty "&#8709;">
<!ENTITY nabla "&#8711;">
<!ENTITY isin "&#8712;">
<!ENTITY notin "&#8713;">
<!ENTITY ni "&#8715;">
<!ENTITY prod "&#8719;">
<!ENTITY sum "&#8721;">
<!ENTITY lowast "&#8727;">
<!ENTITY radic "&#8730;">
<!ENTITY prop "&#8733;">
<!ENTITY infin "&#8734;">
<!ENTITY ang "&#8736;">
<!ENTITY and "&#8743;">
<!ENTITY or "&#8744;">
<!ENTITY cap "&#8745;">
<!ENTITY cup "&#8746;">
<!ENTITY int "&#8747;">
<!ENTITY there4 "&#8756;">
<!ENTITY sim "&#8764;">
<!ENTITY cong "&#8773;">
<!ENTITY asymp "&#8776;">
<!ENTITY ne "&#8800;">
<!ENTITY equiv "&#8801;">
<!ENTITY le "&#8804;">
<!ENTITY ge "&#8805;">
<!ENTITY sub "&#8834;">
<!ENTITY sup "&#8835;">
<!ENTITY nsub "&#8836;">
<!ENTITY sube "&#8838;">
<!ENTITY supe "&#8839;">
<!ENTITY oplus "&#8853;">
<!ENTITY otimes "&#8855;">
<!ENTITY perp "&#8869;">
<!ENTITY sdot "&#8901;">
<!ENTITY lceil "&#8968;">
<!ENTITY rceil "&#8969;">
<!ENTITY lfloor "&#8970;">
<!ENTITY rfloor "&#8971;">
<!ENTITY lang "&#9001;">
<!ENTITY rang "&#9002;">
<!ENTITY loz "&#9674;">
<!ENTITY spades "&#9824;">
<!ENTITY clubs "&#9827;">
<!ENTITY hearts "&#9829;">
<!ENTITY diams "&#9830;">
<!ENTITY nbsp "&#160;">
<!ENTITY iexcl "&#161;">
<!ENTITY cent "&#162;">
<!ENTITY pound "&#163;">
<!ENTITY curren "&#164;">
<!ENTITY yen "&#165;">
<!ENTITY brvbar "&#166;">
<!ENTITY sect "&#167;">
<!ENTITY uml "&#168;">
<!ENTITY copy "&#169;">
<!ENTITY ordf "&#170;">
<!ENTITY laquo "&#171;">
<!ENTITY not "&#172;">
<!ENTITY shy "&#173;">
<!ENTITY reg "&#174;">
<!ENTITY macr "&#175;">
<!ENTITY deg "&#176;">
<!ENTITY plusmn "&#177;">
<!ENTITY sup2 "&#178;">
<!ENTITY sup3 "&#179;">
<!ENTITY acute "&#180;">
<!ENTITY micro "&#181;">
<!ENTITY para "&#182;">
<!ENTITY middot "&#183;">
<!ENTITY cedil "&#184;">
<!ENTITY sup1 "&#185;">
<!ENTITY ordm "&#186;">
<!ENTITY raquo "&#187;">
<!ENTITY frac14 "&#188;">
<!ENTITY frac12 "&#189;">
<!ENTITY frac34 "&#190;">
<!ENTITY iquest "&#191;">
<!ENTITY Agrave "&#192;">
<!ENTITY Aacute "&#193;">
<!ENTITY Acirc "&#194;">
<!ENTITY Atilde "&#195;">
<!ENTITY Auml "&#196;">
<!ENTITY Aring "&#197;">
<!ENTITY AElig "&#198;">
<!ENTITY Ccedil "&#199;">
<!ENTITY Egrave "&#200;">
<!ENTITY Eacute "&#201;">
<!ENTITY Ecirc "&#202;">
<!ENTITY Euml "&#203;">
<!ENTITY Igrave "&#204;">
<!ENTITY Iacute "&#205;">
<!ENTITY Icirc "&#206;">
<!ENTITY Iuml "&#207;">
<!ENTITY ETH "&#208;">
<!ENTITY Ntilde "&#209;">
<!ENTITY Ograve "&#210;">
<!ENTITY Oacute "&#211;">
<!ENTITY Ocirc "&#212;">
<!ENTITY Otilde "&#213;">
<!ENTITY Ouml "&#214;">
<!ENTITY times "&#215;">
<!ENTITY Oslash "&#216;">
<!ENTITY Ugrave "&#217;">
<!ENTITY Uacute "&#218;">
<!ENTITY Ucirc "&#219;">
<!ENTITY Uuml "&#220;">
<!ENTITY Yacute "&#221;">
<!ENTITY THORN "&#222;">
<!ENTITY szlig "&#223;">
<!ENTITY agrave "&#224;">
<!ENTITY aacute "&#225;">
<!ENTITY acirc "&#226;">
<!ENTITY atilde "&#227;">
<!ENTITY auml "&#228;">
<!ENTITY aring "&#229;">
<!ENTITY aelig "&#230;">
<!ENTITY ccedil "&#231;">
<!ENTITY egrave "&#232;">
<!ENTITY eacute "&#233;">
<!ENTITY ecirc "&#234;">
<!ENTITY euml "&#235;">
<!ENTITY igrave "&#236;">
<!ENTITY iacute "&#237;">
<!ENTITY icirc "&#238;">
<!ENTITY iuml "&#239;">
<!ENTITY eth "&#240;">
<!ENTITY ntilde "&#241;">
<!ENTITY ograve "&#242;">
<!ENTITY oacute "&#243;">
<!ENTITY ocirc "&#244;">
<!ENTITY otilde "&#245;">
<!ENTITY ouml "&#246;">
<!ENTITY divide "&#247;">
<!ENTITY oslash "&#248;">
<!ENTITY ugrave "&#249;">
<!ENTITY uacute "&#250;">
<!ENTITY ucirc "&#251;">
<!ENTITY uuml "&#252;">
<!ENTITY yacute "&#253;">
<!ENTITY thorn "&#254;">
<!ENTITY lt "&lt;">
<!ENTITY gt "&gt;">
<!ENTITY amp "&amp;">

  <outcome><!-- 'success', 'failure' : level 3, 'api_error' : level 2, 'system_error' : level 1 --></outcome>
  <!-- if the outcome is not 'success' then the section below will contain error information -->
  <!-- response data specific to the request made -->




XML Code Example - PHP5

$api_url = "";
$api_username = "username";
$api_password = "password";
$api_retailer_id = "123456";

$strRequest = "
            <username>". $api_username ."</username>
            <password>". $api_password ."</password>
        <retailer_id>". $api_retailer_id ."</retailer_id>
//initialize a CURL session
$connection = curl_init();
//set the server we are using (could be Sandbox or Production server)
curl_setopt($connection, CURLOPT_URL, $api_url );
//stop CURL from verifying the peer's certificate
curl_setopt($connection, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($connection, CURLOPT_SSL_VERIFYHOST, 0);
//set method as POST
curl_setopt($connection, CURLOPT_POST, 1);
//set the XML body of the request
curl_setopt($connection, CURLOPT_POSTFIELDS, $strRequest);
//set it to return the transfer as a string from curl_exec
curl_setopt($connection, CURLOPT_RETURNTRANSFER, 1);
//increase time-out as some calls can take a long time to respond with data
//Send the Request
$strResponse = curl_exec($connection);
if(curl_errno($connection)) {
    print 'Curl error: ' . curl_error($connection);
//close the connection







The following URL is to be used for development and testing:

Product Methods: [link]

Order Methods: [link]

The following URL's are to be used in production after testing on the sandbox server has been validated:

Product Methods: [link]

Order Methods: [link]


SOAP Code Example - PHP5

The PHP5 example code below shows how to set up a SOAP client to call the API. There are three variables (username, password and retailer_id) within the code that you will need to replace with your own.

This code requires PHP5 with SOAP configured properly. Other development environments may use similar structure, although the functions will need to be customized accordingly.

$client = new   SoapClient("", array('trace' => 1));
$objAuth = new stdClass();
$objAuth->username = '%username%'; 
$objAuth->password = '%password%';
$objRequest = new stdClass();   
$objRequest->authentication = $objAuth; 
$objRequest->retailer_id = '%retailer_id%';
$objRequest->products = array(147129); 
$objRequest->items = array(); 
$objRequest->watchlists = array(); 
$response = $client->getProductDetail($objRequest); 
if(false == is_soap_fault($response)){   
 foreach($response as $product) {   
  foreach ($product->items as $item) { 
   print   "price: "  . $item->price . "\n\n"; 
 echo   "error code: " . $response->faultstring . "<br>"; 
 echo   "error message: " . $response->detail . "<br>"; 


SOAP Code Example - .NET

The .NET example code below shows how to set up a SOAP client to call the API. There are three variables (username, password and retailer_id) within the code that you will need to replace with your own.

This code requires that you initially build a DLL with the WSDL file. Once that is accomplished, the code below can be utilized to submit and accept the content of the request..

<%@ Page Language="C#" %>
<%@ import Namespace="System.Data" %>
<%@ import Namespace="System.IO" %>
<%@ import Namespace="System.Text" %>
  ApiRetailerAuthenticationInfo _auth = new ApiRetailerAuthenticationInfo();
  ApiRetailerSearch _ret = new ApiRetailerSearch();
  ApiRetailerBrandRequest _brand = new ApiRetailerBrandRequest();
  ApiBrandResponse[] _brandResponse;
  _auth.username = "username";
  _auth.password = "password";
  _brand.authentication = _auth;
  _brand.retailer_id = "retailer_id";
  _brandResponse = _ret.getBrands(_brand);
  for (int x = 0; x < _brandResponse.Length; x++) 
 Response.Write(_brandResponse[x].name + "<BR>");


Failure Codes

Provides specific information regarding the failure of any given API call.

Because there are several layers at which an API call can fail, the API breaks the failures into varying code levels which are explained below.

Level 1 = Fatal System Error, contact Doba

There was a system error and the request was unable to be processed. The call format and/or authentication may be OK, but the system was not able to process the request properly or there was a server or communication error. Typically, these calls should be resubmitted after the cause of the error has been resolved.

It is inevitable that this error level will be provided at some point in your integrations life-time. Although Doba strives for 100% uptime, it is not always possible. Doba monitors the systems responsible for keeping the API available at all times and will be notified of any problems. If you feel that Doba is taking an unreasonable amount of time to resolve the errors, please contact us.

Level 2 = Syntax Error

There was a problem with request format.

The system is attempting to process your request, but there is a problem with the API call's XML format or the syntax of the action you are attempting to submit. Please review this documentation thoroughly to ensure that your calls are properly formatted. Please review your code and the syntax of the action you are attempting to ensure that all required sections of the call are accounted for. If this error persists, please contact Doba where your call can be reviewed and possible solution(s) can be provided.

Level 3 = Data Error

There was a problem with the authentication.

Either your username or password is incorrect or your account is not currently active or it does not have the appropriate permissions assigned. If you are unable to resolve this error on your own, please contact Doba to find out if your account has been configured properly.


Failure Code List

Error Explanation
200 Invalid action
201 Permission denied
202 Missing syntax
203 Invalid xml
204 Call requires https
300 Non existent retailer
301 Missing email
302 Missing firstname
303 Missing lastname
304 Missing phone
305 Missing billing street
306 Missing billing city
307 Missing billing state
308 Missing billing postal
309 Missing billing country
310 Missing creditcard number
311 Missing creditcard expiration
312 Missing username
313 Missing api code
314 Missing frequency
315 Missing billing responsibility
316 Missing trial
317 Missing subscription action
318 Missing retailer id
319 Missing item id
320 Missing quantity
321 Missing shipping state
322 Missing shipping postal
323 Missing shipping country
324 Missing order items
325 Missing shipping city
326 Missing shipping street
327 Missing shipping firstname
328 Missing shipping lastname
329 Missing order id
330 Missing fund method
331 Missing payment account id
332 Missing billing name
333 Missing cvv2
334 Missing orderlist item info
335 Missing order status
336 Missing orderlist items
337 Missing billing lastname
338 Missing billing firstname
339 Missing creditcard expiration year
340 Missing creditcard expiration month
341 Missing watchlist id
342 Watchlist user mismatch
343 Watchlist invalid
344 Could not save watchlist
345 Could not delete watchlist
346 Missing saved search id
347 Saved search user mismatch
348 Saved search invalid
349 Could not save search
350 Could not delete saved search
351 Order not specified
352 Missing ip address
353 Order not available to user
354 Shipping address missing
355 No
356 Cannot cancel supplier order
357 Missing cancellation reason
358 No decisions submitted
359 No decisions exist
360 Invalid email
361 Invalid phone
362 Invalid creditcard number
363 Invalid subscription action
364 Invalid shipping state
365 Invalid shipping country
366 No action taken
367 Invalid ip address
368 Invalid username
369 Username already exists
370 Supplier order unavailable
371 Missing rma reason
372 Missing rma type
373 Missing rma items
374 Missing rma id
380 Permission to retailer denied
390 Call limit reached
400 Unavailable order item
401 Inaccessible order item
402 Unavailable order
403 Invalid order
404 Invalid payment account
405 Invalid subscription
406 Invalid frequency
407 Invalid billing responsibility
408 Invalid order id
409 Invalid order status
410 Invalid order po number
411 Cannot mix directrelation orders
500 Failed to save order
501 Failed to fund order
502 Payment failed
503 Failed to save payment
2011 Permission denied no resource access
2012 Permission denied neither partner nor retailer
2013 Permission denied invalid retailer action
2014 Permission denied invalid action
2015 Permission denied insufficient permissions
2016 Permission denied invalid credentials




A sandbox is a testing (or virtual) environment that isolates untested code changes and outright experimentation from the production environment. Sandbox environments protect production servers and their data from changes that could be damaging (regardless of the intent of the author of those changes) to a mission-critical system or which could simply be difficult to revert. Sandboxes replicate the functionality needed to test accurately the programs or other code under development. See Wikipedia for further clarification.

Notice: Although we strive to keep the sandbox server available at all times, there may be times when it will not be accessible. If this is the case, please contact Doba.

Sandbox URL

The sandbox API URL information is found in the following locations...



Sandbox Web Site

Additionally, a sandbox web site, mimicking the Doba web site, is available at the URL below.  [link]

The sandbox web site can be used to perform several tasks that would normally be done by suppliers. For orders, you can log in as a retailer so that you can view orders and change status' and/or send callbacks upon status changes.

To change the status of an order, log in as the retailer your using in your API calls and select "orders". Select an order from the list by clicking the number in the "order" column or by searching for the order number at the top. In the supplier order section of the order detail, select the yellow button labeled "Change Order Status". Select and save the new status and a callback will be issued to the location saved in your sandbox URL settings.

To change the callback URL used in your sandbox environment, go to, log in using your username and password and select Settings from the top menu. Next, select API on the sub-menu. Here, you can add your callback URL as well as select the updates that you would like callbacks sent for. Typically, you will want all of the preferences selected.




Export Automation

SMB Retailers who have access to the Warehouse Folders feature are also able to automate the download of export files set up in the Export tab.

Go to the Export tab and modify the Persistent URL to look like the following:

Replace the 'username' and 'password' parameters with your own username and password and make sure to use HTTPS as its insecure to pass sensitive information such as your username and password over URL's with HTTP.

Using this URL you can now download the export file automatically without having to log into the site and request the export file manually.





API version 4.0 introduces the limiting of product data that can be obtained by retailers and partners.

Doba limits the number of product API calls per minute for each retailer account. For any given minute, only 100 API calls will be allowed. If there are more than 100, those from 101 and on will wait for the next minute and then they will be returned, meaning that if you plan on making a lot of API calls per minute, it would be best to extend your time-out settings so your scripts will run longer without failing. In most cases, the limits will never be hit unless your script is set up to obtain product detail for one item at a time. As long as multiple items are requested per call, the limit should never be hit.

There are no limits on Order API calls.

The getRetailerAccessInfo API call returns information regarding the limits and current usage for the specified retailer. The limits depend on the subscription package sold to the retailer.

The product_detail_total parameter refers to the limit on the number of products the retailer can receive detailed information for, obtained by using the getProductDetail API command.The product_detail_count parameter refers to to the current progress approaching the limit. As soon as this number matches the limit total the retailer will receive errors upon subsequent product detail calls.

The product_inventory_total parameter refers to the limit on the number of products the retailer can receive inventory information for, obtained by using the getProductInventory API command and also through triggered callbacks for which you have elected to receive inventory updates for (see the watch-list at The product_inventory_count parameter refers to to the current progress approaching the limit. As soon as this number matches the limit total the retailer will receive errors upon subsequent product inventory calls.




Order Lifecycle

A Doba order will normally progress through the following four primary stages. These four stages are also the core statuses for the Doba order life cycle.

  1. Payment Pending
  2. Funded
  3. Processing
  4. Shipped

Understanding the order life cycle is important when building an application which includes Doba order integration.

You will notice that the "Awaiting Review" status is encountered during the course of some orders. This is a fraud prevention related step where the Doba order management team reviews orders and payments which exceed a risk threshold. No action is required by integration partners to progress orders through this step. A Doba support representative may contact the client in the process of reviewing orders.

At any point in the order process an order may be placed in a "hold" or "cancelled" status. The "hold" status is used when manual intervention is required during order processing. Examples of scenarios for held orders include shipping address correction. Both the "shipped" and "cancelled" status are considered terminal statuses.


Order Status'

It's important to understand the structure of an order to understand the different status' that may be encountered through the order lifecycle.

A Doba order is broken into three levels. The highest level encompases the entire order, including the totals for all items, shipping, drop-ship fees, etc.

The second level contains all of the individual supplier orders, or orders broken into groups of items that come from the same supplier. Each supplier order will have its own status.

Because there can be multiple supplier orders in one order, the top-level order status will sometimes be "Various". This will happen if the suppler order status' differ from each another. If all supplier order status' are the same, the order status will be identical to the supplier order status'.

The scenerios below will help explain how different status' are represented:

Order 1
Order Status = Completed
Supplier Order Status = Completed

Order 2
Order Status = Completed
Supplier Order 1 Status = Completed
Supplier Order 2 Status = Completed
Supplier Order 3 Status = Completed

Order 3
Order Status = Various
Supplier Order 1 Status = Completed
Supplier Order 2 Status = Shipment Pending
Supplier Order 3 Status = Completed

Order 4
Order Status = Cancelled
Supplier Order 1 Status = Cancelled
Supplier Order 2 Status = Cancelled
Supplier Order 3 Status = Cancelled

Order 5
Order Status = Cancelled
Supplier Order Status = Cancelled

The last level is item status which has its own set of status'.


Supplier Order Status'

The full range of order lifecycle status' are explained in the following table.

Status Description
Error - Contact Support The order is in an erroneous state and is being investigated by a Doba fulfillment specialist.
Awaiting Payment Customer must submit payment for the order to continue; initiated PayPal payment may be outstanding.
Funded The order has been funded. It is being processed by the Doba platform and will be deleivered to the supplier for fulfillment if no problems are found.
Shipped Shipment information has been received from the supplier and the order is en-route or received.
Payment Declined Authorized payment failed to settle.
Processing The Doba order engine is processing the order. This status is fleeting and will normally not be encountered by integrated systems.
Hold - Input Needed Retailer input is needed for the order to be processed; customer is notified by e-mail and can provide input by logging into the site.
Shipment Pending The order has been sent to the supplier and is being fulfilled; Doba is waiting for supplier response and a shipment notice is expected.
Awaiting Payment Confirmation This normally only occurs during an eCheck transaction through PayPal, where Doba is notified of the payment but it has not yet cleared.
Awaiting Supplier Cancel The customer has requested cancellation and Doba is initiating the cancellation process with the supplier.
Cancelled The order is cancelled and will not be fulfilled.
Fraudulent Order The order was aborted and deemed to be fraudulent.
Returned The product(s) have been returned to the supplier and return receipt verified.
Completed The order completed normally.
Awaiting Supplier Acceptance Some suppliers use an asynchronous acknowledgement. In this state the order has been submitted but not acknowledged.


Line Item Status'

In addition to better overall order tracking and statuses the API also exposes line item statuses for each item in an order.

Status Description
Pending The item is waiting to be sent to the supplier.
Processing The DOBA order engine is processing the order. This status is fleeting and will normally not be encountered by integrated systems.
Scheduled The item has not yet been accepted by the supplier as part of an order, but the order is on back order with Doba. i.e. Doba is waiting for new inventory to re-send the item to the supplier.
Shipment Pending The item has been sent to the supplier.
Shipped The item is on route to the end consumer.
Partial Some of the quantity have shipped, others are pending shipment or possible cancellation
Cancelled The item has been cancelled and removed from the order.
Returned The item has been returned to the supplier.
Discontinued The item has been discontinued and removed from the order.
Waiting The item is waiting for the supplier to update its status.


Order Lifecycle Integration Work-Flow

Typically, when integrating the Order API into your application, you will want to follow the outline below as a basic work-flow.

  1. Gather all item_id's and call the orderLookup function making sure to deal with any out-of-stock items or items that may not be currently available.
  2. Display the totals found in the orderLookup function and wait for the end-user to submit the final order.
  3. Create the order using the createOrder API call. You may wish to fund the order using this call or fund the order at a separate time.
  4. Wait until order updates are delivered using the call-back functions.