There is a newer version of the API available. To link to the newest API documentation, click here - Version 20110301
  1. Callbacks

Callbacks

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

Refer to the Sandbox Web Site section for information regarding the callback URL.

Callbacks are sent as an HTTP POST to the callback URL stored in your account. In PHP, the XML data is contained in the $_POST['xml'] variable.

To ensure proper security for callback updates, you should only accept callbacks originating from IP address range of 64.58.224.x.

Callbacks we send that don't get an HTTP 200 response will be retried 5 times. If it fails 5 times we will stop attemping to send them. We then send an email to the technical contact email address we have on file containing the responses we received when attempting to send the callback to your callback URL so that you are aware of the problem. If this happens 25 times, we will turn off callbacks and stop sending them to you and you will need to contact Doba Technical Support at api@doba.com to reset your account.

 

 

Retailer/Partner Permission Acceptance

If an existing Doba retailer wants to utilize your system you must "link" the retailers account to your API account. Your system will need to request authorization from the retailer to make calls on their behalf by utilizing the requestPartnerPermission API method.

The data contained in the callback is identical to the data received via the hasPartnerPermission API Method.

Below is an example of the data provided in a product callback update:

<?xml version="1.0"?>
<dce>
  <response>
    <outcome>success</outcome>
    <callback_type>hasPartnerPermission</callback_type>
    <has_permission>accepted</has_permission>
    <retailer_id>123</retailer_id>
  </response>
</dce>

 

 

Product/Inventory Updates

Product and inventory information can be automatically sent to your system whenever a supplier updates a product that is stored in the retailers watchlist.

The product update callbacks will utilize the XML response within the getProductDetail API method.

The inventory update callbacks will utilize the XML response within the getProductInventory API method.

In order to receive automicatic updates via callbacks, the following criteria must be meet:

Follow these steps to test your inventory callback URL:

  1. Log into sandbox.doba.com with a retailer username and password that has authorized their account to work with your partner API account.
  2. Find a product you want to receive a callback for and add it to a watchlist.
  3. Put a check in the check-box under "Send Callback" and select "UPDATE".
  4. Select the "VIEW" button on the watchlist you just created.
  5. Select the "PRODUCT ID" of the product you wish to receive the callback for.
  6. Click on the yellow button labeled "Send API Callback".
  7. A callback will be sent to your system within a few minutes.

Below is an example of the data provided in a product callback update:

<dce>
<response>
<outcome>success</outcome>
<retailer_id>157</retailer_id>
<callback_type>item_detail</callback_type>
<items>
	<item>
		<product_id>51423</product_id>
		<item_id>64397</item_id>
		<product_title>Horn for Car Alarms</product_title>
		<item_name>Horn for Car Alarms</item_name>
		<description>&lt;li&gt;6-tone, 125dB electronic siren</description>
		<additional_details/>
		<product_sku>CS-198III</product_sku>
		<brand>Crime Stopper</brand>
		<condition>new</condition>
		<freight>0</freight>
		<ship_width>4.00</ship_width>
		<ship_length>4.00</ship_length>
		<ship_height>3.00</ship_height>
		<ship_weight>1.00</ship_weight>
		<ship_cost>7.38</ship_cost>
		<sku>CS-198III</sku>
		<upc>048097100197</upc>
		<map>0.00</map>
		<price>9.39</price>
		<prepay_price>8.99</prepay_price>
		<msrp>19.95</msrp>
		<qty_avail>16</qty_avail>
		<stock>in-stock</stock>
		<last_update>2008-09-18 10:11:53</last_update>
		<images>
			<image>
				<url>http://d1k0ppjronk6up.cloudfront.net/products/_thumb/cs-198iii.jpg</url>
				<thumb_url/><image_height>0</image_height>
				<image_width>0</image_width>
				<default>1</default>
			</image>
		</images>
		<supplier_id>1</supplier_id>
		<supplier_name>DBL</supplier_name>
		<supplier_processing>1-4 business days to ship out and receive tracking number.</supplier_processing>
		<supplier_alerts/>
		<supplier_notes>This supplier does not ship to Hawaii or Alaska. These products are not eligible for return. Please contact the appropriate manufacturer for troubleshooting repair service.</supplier_notes>
		<supplier_drop_fee>1.50</supplier_drop_fee>
		<product_group>basic</product_group>
		<categories>
			<category>
				<id>33596</id>
				<name>Product Catalog</name>
				<selected/>
				<count/>
			</category>
			<category>
				<id>30971</id>
				<name>automotive and tool</name>
				<selected/>
				<count/>
			</category>
			<category>
				<id>30972</id>
				<name>automotive</name>
				<selected/>
				<count/>
			</category>
			<category>
				<id>30986</id>
				<name>alarms</name>
				<selected/>
				<count/>
			</category>
			<category>
				<id>30987</id>
				<name>alarm with lcd</name>
				<selected/>
				<count/>
			</category>
		</categories>
	</item>
</items>
</response>
</dce>

Below is an example of the data provided in an inventory callback update:

<dce>
<response>
<outcome>success</outcome>
<retailer_id>157</retailer_id>
<callback_type>inventory_update</callback_type>
<items>
	<item>
		<item_id>64397</item_id>
		<product_id>51423</product_id>
		<stock>in-stock</stock>
		<qty_avail>16</qty_avail>
		<price>9.26</price>
		<prepay_price>8.99</prepay_price>
	</item>
	<item>
		<item_id>54678</item_id>
		<product_id>41254</product_id>
		<stock>in-stock</stock>
		<qty_avail>126</qty_avail>
		<price>92.64</price>
		<prepay_price>90.99</prepay_price>
	</item>
</items>	
</response>
</dce>

 

 

Watchlist Updates

Watchlist changes will be delivered to your system whenever a watchlist is added or deleted or renamed or the send_callback option is updated.

The callback will contain the latest changes to the callback since the last callback. All changes are logged and sent in batches.

Possible events are:

The data contained in the callback is identical to the data received via the getWatchlists API method, except for the addition of the event tag information contained in the callback.

<dce>
<response>
<outcome>success</outcome>
<retailer_id>123456</retailer_id>
<callback_type>get_watchlists</callback_type>
<watchlists>
    <watchlist>
        <event>name_changed</event>
        <event_date>2009-04-02 14:18:31</event_date>
        <watchlist_id>94252</watchlist_id>
        <retailer_id>123456</retailer_id>
        <name>Golf Renamed</name>
        <default>0</default>
        <send_callback>1</send_callback>
        <item_count>4</item_count>
    </watchlist>
</watchlists>
</response>
</dce>
<dce>
<response>
<outcome>success</outcome>
<retailer_id>123456</retailer_id>
<callback_type>get_watchlists</callback_type>
<watchlists>
    <watchlist>
        <event>callback_status_changed</event>
        <event_date>2009-04-02 14:18:35</event_date>
        <watchlist_id>94574</watchlist_id>
        <retailer_id>123456</retailer_id>
        <name>new watchlist</name>
        <default>0</default>
        <send_callback>0</send_callback>
        <item_count>1</item_count>
    </watchlist>
</watchlists>
</response>
</dce>
<dce>
<response>
<outcome>success</outcome>
<retailer_id>123456</retailer_id>
<callback_type>get_watchlists</callback_type>
<watchlists>
    <watchlist>
        <event>deleted</event>
        <event_date>2009-04-06 11:25:12</event_date>
        <watchlist_id>94574</watchlist_id>
        <retailer_id>123456</retailer_id>
       <name>asdf</name>
       <default/>
       <send_callback>1</send_callback>
       <item_count/>
    </watchlist>
</watchlists>
</response>
</dce>
<dce>
<response>
<outcome>success</outcome>
<retailer_id>123456</retailer_id>
<callback_type>get_watchlists</callback_type>
<watchlists>
    <watchlist>
       <event>created</event>
       <event_date>2009-04-06 11:24:55</event_date>
        <watchlist_id>94574</watchlist_id>
        <retailer_id>123456</retailer_id>
       <name>asdf</name>
       <default/>
       <send_callback>0</send_callback>
       <item_count/>
    </watchlist>
</watchlists>
</response>
</dce>

 

 

Watchlist Product Updates

Watchlist product changes will be delivered to your system whenever an item is added to, or deleted from, a watchlist.

Only one callback will be returned per watchlist. If two different watchlists are updated you will receive two callbacks.

The data contained in the callback is identical to the data received via the getWatchlistProducts API method.

<dce>
<response>
<outcome>success</outcome>
<retailer_id>123456</retailer_id>
<callback_type>get_watchlist_products</callback_type>
<products>
    <ApiGetWatchlistProductsResponse>
    <watchlist_id>924252</watchlist_id>
    <result_total>2</result_total>
    <products>
        <watchlist_items>
            <item_id>595465</item_id>
            <stock>in-stock</stock>
            <qty_avail>21</qty_avail>
            <item_name>Football Jersey 18x18 Beveled</item_name>
            <product_id>358175</product_id>
            <price>25.08</price>
            <msrp>48.00</msrp>
            <last_update>2009-03-02 15:53:39</last_update>
            <event>added</event>
        </watchlist_items>
        <watchlist_items>
            <item_id>885915</item_id>
            <stock>in-stock</stock>
            <qty_avail>98</qty_avail>
            <item_name>ALL ABOUT FOOTBALL Size: M</item_name>
            <product_id>593905</product_id>
            <price>18.36</price>
            <msrp>27.00</msrp>
            <last_update>2009-03-02 15:53:45</last_update>
            <event>removed</event>
        </watchlist_items>
        </products>
    </ApiGetWatchlistProductsResponse>
</products>
</response>
</dce>

 

 

Order Updates

Order updates will be delivered to your system whenever a funded order has been updated by the supplier.

The data contained in the callback is identical to the data received via the getOrderDetail API method.

To test shipment tracking callbacks within the Sandbox environment, please contact your account manager at Doba. At this time, all shipping information must be added manually by Doba. To expidite your request, please provide the order_id's you would like shipping added to.

Follow these steps to test your order callback URL:

  1. Create an order through using the createOrder API method.
  2. Log into sandbox.doba.com with the retailer username and password of the retailer you created the order for.
  3. Select "Orders" from the top navigation options.
  4. Select the "ORDER" number of the order you want a callback for.
  5. Select the yellow "Change Order Status" button.
  6. A pop-up window will be displayed. Select the "STATUS" from the drop-down box that you wish to change the order status to and click "SAVE".
  7. A callback will be sent to your system within a few minutes.

Below is an example of the data provided in a order callback update:

<dce>
<response>
<outcome>success</outcome>
<retailer_id>157</retailer_id>
<callback_type>order_update</callback_type>
<orders>
    <order>
        <retailer_id>1</retailer_id>
        <order_id>321519</order_id>
        <po_number/>
        <status>Various</status>
        <subtotal>18.27</subtotal>
        <shipping_fees>13.62</shipping_fees>
        <drop_ship_fees/>
        <order_total>36.89</order_total>
        <ship_name>Test Firstname Test Lastname</ship_name>
        <ship_street>That one street</ship_street>
        <ship_city>That one city</ship_city>
        <ship_state>CA</ship_state>
        <ship_postal>84058</ship_postal>
        <ship_country>US</ship_country>
        <supplier_orders>
            <supplier_order>
                <status>Awaiting Payment</status>
                <credits/>
                <items>
                    <item>
                        <item_status>Pending</item_status>
                        <item_id>540202</item_id>
                        <quantity>1</quantity>
                        <price>1.62</price>
                        <prepay_price>1.57</prepay_price>
                    </item>
                </items>
                <supplier_id>5</supplier_id>
                <drop_ship_fees/>
                <transaction_fees/>
                <shipping_fees>6.50</shipping_fees>
                <sub_total>1.62</sub_total>
                <order_total>10.62</order_total>
            </supplier_order>
        </supplier_orders>
        <shipments>
		    <shipment>
                <supplier_id>5</supplier_id>
                <carrier>UPS</carrier>
                <tracking>564564564564654</tracking>
                <shipment_date>2008-05-29</shipment_date>
                <num_parcels>1</num_parcels>
                <weight>1.000</weight>
                <shipment_items>
                    <shipment_item>
                        <item_id>540202</item_id>
                        <quantity>1</quantity>
                    </shipment_item>
                </shipment_items>
            </shipment>
        <shipments>
    </order>
</orders>
</response>
</dce>