1. Introduction
  2. Doba API
  3. Getting Started
  4. Failure Codes
  5. Export Automation
  6. Limits
  7. Order Lifecycle

Introduction

Copyright Notice

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

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

partners@doba.com

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.

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.

What does Doba do?

Doba is an Inventory on Demand platform designed to solve the major pain points with inventory management. The platform is the technology infrastructure to support a virtual warehouse and fulfillment system as well as the relationships with hundreds of suppliers. These suppliers are capable of drop shipping their inventory of products on behalf of retailers directly to end customers.

How much does it cost to get products live on your website and keep them updated? How much does it cost to onboard new suppliers and product catalogs? How much overhead do you lose in the ongoing management of products and catalogs? How quickly can you get new products and/or supplier up and running on your website? Doba can help address these business challenges and maximize your return on investment with our Inventory on Demand platform. Doba will save you time and resources so you can focus on growing your business. No longer will you incur expenses testing new suppliers, finding new suppliers, and sorting/filtering/standardizing data. You can test new products, move into new product lines, find new suppliers and access their virtual catalogs, and ultimately sell more products to your customers without near the cost of trying to do all of that yourself. You can also avoid the hassles of storing, packing, shipping and handling the products.

 

Inventory on Demand: Technology Infrastructure

Doba has been developing our technology infrastructure for over 5 years and has invested millions of dollars in building a robust and scalable virtual warehouse and fulfillment system. We have also enabled an API so that you can use our website interfaces and programmatically access our service.

 

Inventory on Demand: Products and Suppliers

With one connection to Doba's platform you are linked to over 3,400,000 unique SKU's and more than 7,700 manufacturers. Instead of creating separate and costly relationships with suppliers one at a time, with one integration to Doba you are connected with an expansive virtual catalog. You can grow and scale your business more effectively through our Inventory on Demand platform.

We support both direct relationships and brokered relationships with suppliers. This means you can either pay the supplier directly and use all of our data aggregation, order management, catalog updates, etc OR order through us acting as a broker on your behalf. We are indifferent to the relationship type as we do not add margin to product costs.

Direct Relationships

On the direct side, it allows you to keep special pricing and merchandising/marketing support that you may enjoy from working directly with the supplier. You use Doba for our data aggregation and feeds, order management, catalog updates, etc.

Brokered Relationships

This allows you to test suppliers without going through the full account setup. It also means that in many cases (especially with more fringe suppliers), you can get better pricing than if you were to go direct because of the order volumes we send the supplier.

We do not charge suppliers any fees, nor are there integration fees. We specialize in rapid, standardized onboarding of direct-fulfillment suppliers and their catalogs. Since we do not charge manufacturers for inclusion in our catalog, there is generally very little barrier in gaining compliance. Manufacturers control retailer access to their data which is a win for both them and the suppliers.

Because we offer both Direct and Brokered options and are indifferent to which you pick for each supplier, it also means that we can onboard your existing suppliers, integrate new manufacturers, and/or give you immediate access to our current supply base.

 

 

Doba API

Introduction

The Doba API allows Retailers to access product data, submit orders, fund orders and follow orders through the fulfillment process programmatically.

The Doba API utilizes industry standard Web Services solutions that allow Retailers to automate the retrieval of product data and submittal of orders allowing for a seamless integration between the Retailers online presence and the fulfillment of orders through the Doba Inventory on Demand Platform.

 

Compatibility

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

Because the API operates as a Web Service, you are not limited to a specific set of web platform environments. Any platform that is able to communicate via SOAP or XML via HTTP POST requests can utilize the Doba API.

 

Previous API Versions

The Doba API is versioned to allow easy updates and additions without the need for you to imediately update a currently running integration.

Below are listed the previous versions of the Doba API. To link to a previous version click on the corresponding link.

Change Log

 

Obtaining an API Account

If you are not working with a Doba account manager, please contact Doba Enterprise <enterprise@doba.com> to set up your account.

When you are ready to begin development you will be provided with account information for use in the sandbox environment as well as in the production environment. We ask that all development be performed using the sandbox. The sandbox is a separate server that mimics Doba's production server which allows you to develop your implementation without fear of impacting the production environment.

 

 

 

Getting Started

Standards

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

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.

 

WSDL

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.

 

XML

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.

 

 

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
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
2017 Permission denied missing credentials
202 Missing syntax
203 Invalid xml
204 Call requires https
300 Non existent retailer
3001 Retailer not expired
3002 Retailer missing access sub
301 Missing email
3010 Email or phone required
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
3220 Invalid shipping postal
3221 Shipping postal not allowed
3222 Invalid billing postal
323 Missing shipping country
324 Missing order items
325 Missing shipping city
326 Missing shipping street
3260 'Shipping street' longer than 25 characters
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 Inventory List id
342 Inventory List user mismatch
343 Inventory List invalid
3430 Folder invalid
344 Could not save Inventory List
3440 Max Inventory Lists reached
3441 Duplicate Inventory List name
345 Could not delete Inventory List
3450 Could not add items
34501 Items not available
346 Missing saved search id
347 Saved search user mismatch
348 Saved search invalid
349 Could not save search
3490 Max saved searches reached
3491 Duplicate saved search name
350 Could not delete saved search
3501 Old saved search
3502 Duplicate customization profile name
3503 Could not load customization profile
3504 Customization profile not allowed
3505 Could not delete customization profile
3506 Could not rename customization profile
3507 Empty customization profile name
3508 Could not remove customization data from item
3509 Missing customization profile id
351 Order not specified
352 Missing ip address
353 Order not available to user
354 Shipping address missing
355 No items in cart
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
3740 Missing shipment date
3741 Invalid shipment date
3742 Missing carrier
3743 missing tracking
3744 Invalid parcel count
3745 Could not save tracking
375 Missing warehouse folder path
3750001 Failed to copy folder
376 Failed to save path
377 Failed to delete folder
378 Missing warehouse folder id
3780 Push request id
379 Failed to retrieve folders
380 Permission to retailer denied
381 Missing items
382 Missing folder name
383 Failed to add items to folder
3830 Failed to add items to push request
3831 Folder item limit reached
3830001 Failed to copy items to folder
384 Failed to delete items from foler
385 Failed to rename folder
3850 Folder name already exists
386 Invalid retailer id
3860 Invalid from date
3861 Invalid to date
387 Invalid billing country
390 Call limit reached
400 Unavailable order item
4001 Invalid order item
4002 Duplicate 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
4080 Invalid order group id
409 Invalid order status
410 Invalid order po number
411 Cannot mix directrelation orders
4110 Cannot group specified orders
4111 Cannot ungroup specified orders
412 Invalid export
413 Missing export
416 Missing export name
417 Missing transform commands
418 Invalid transform commands
419 Missing records
420 Missing url tag
421 Invalid url tag
422 Duplicate url tag
423 Missing folder id
4230 Missing search id
4231 Missing source type
4232 INvalid search id
424 Invalid folder id
425 Invalid changes since time
426 Invalis changes since secs
427 Missing transform
428 Missing transform id
429 Invalid transform id
430 Missing transform name
431 Missing transform format
432 Invalid transform format
433 Missing transform format parameters
434 Invalid transform format parameters
435 Invalid transform criteria
436 Invalid transform scope
437 Transform edit permission
438 Could not load export
439 Failed to run export
440 Could not run export transform
441 Failed to add export transform
442 Failed to edit export transform
443 Failed to delete export transform
444 Failed to create product export
445 Failed to edit product export
446 Failed to delete product export
447 Unavailable export
448 Unavailable transform
500 Failed to save order
501 Failed to fund order
502 Payment failed
503 Failed to save payment
510 Product not found
520 Product id required
521 Invalid status trigger
522 Item id required
523 Profile id required
530 Trigger required
531 Invalid status trigger
532 Frequency required
534 Frequency time required
535 Invalid frequency time
536 Unable to set folder preferences
537 Unable to remove folder preferences

 

 

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:

https://username:password@www.doba.com/retailer-export/get/type/product/tag/export_name

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.

 

 

Data Export Product File Definition

Data Export Inventory File Definition

 

 

 

Limits

API version 4.0 introduced 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, any incoming connections will be rejected after the limit has been reached. To ensure that the limit is never reached, all API calls should be batched when possible. Requesting details for one single product should be an exception rather than the rule.

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 method.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 method at the schedule of your choice (see Inventory lists at http://www.doba.com). 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 method. You may wish to immediately fund the order using the fundOrder method after creating the order. You could also do this at a separate time.
  4. Check on the order status at the time of your choice using the getOrders or the getOrderDetail methods.