1. CORE CONCEPTS & GUIDES
  2. >
  3. GUIDES
  4. >
  5. Dropship Guide Managing Orders

Overview

Onboarding

Managing Products

Managing Orders

Launch


Overview

The goal of the Managing Orders stage is to ensure you are able to successfully ship products.

Understanding some important concepts up-front will make this easier.

Order Status

Every order has a status, which updates throughout the lifecycle of the order. If the order status values used in your system do not have a suitable correlate in the order status values provided by iQmetrix, you can use the 8 (Other) status and provide your own label in the Message property.

When the Dropship order is created, the order is automatically assigned a status of 0 (PendingSupplier) by the Dropship service.

It’s important for you, the supplier, to note that when you receive the order in your system it is your responsibility to update the status of the order to 1 (Ordered). Updating the status of an order updates the status of each item in the order.

Order Status Values and Order Flow

The set of status values that can be set for orders maps onto the order lifecycle flow in the ordering lifecycle. The flow showing all potential status values for a complete order is shown below.

Dropship Order status values

Avoiding Duplicate Orders

The iQmetrix architecture is distributed, and to ensure that messages are never lost the system employs an “at-least-once” delivery mechanism. “At-least-once” means that message delivery is reliable; however, occasionally messages may be duplicated.

To avoid processing the same order more than once, your system should track the identifier for the Dropship order. In the order feed, this information is captured in the order-created.order-id field.

The Order Notifications Feed

The Supplier Orders API produces an Order Notifications Feed that records that captures all Dropship order events from the supplier’s point of view. Newly created orders are prepended to the beginning of the notification feed. You can use this feed to track or verify order events arriving from the iQmetrix system.

The Order Notifications Feed is provided in “Atom Syndication Format” using “Archived Feeds” and is encoded as atom+xml. Each page of the feed contains up to 50 events.

Create Shipping Provider API

Suppliers typically want to present customers with their options for shipping the order after the customer has selected their items for purchase. This might include options for shipping providers (for example, Fedex, UPS, or the postal service) or other options (for example, free shipping vs. faster shipping). These options will vary with individual supplier shipping practices.

To specify shipping options for your customers, you implement your own version of an API, the Shipping Options. Specifying a Shipping Options API gives iQmetrix the ability to request your shipping options for a given delivery address and set of products.

For your shipping options to interoperate correctly with iQmetrix Dropship product, your implementation of the Shipping Options API_ must exactly match the API specifications, shown on the Shipping Options page.

Once an order has been created, shipping options are displayed using the Shipping Aggregator service.

Definition: The Shipping Aggregator (SACCS) API is a shipping options arbitrator between end customer products (e.g. RQ) and iQmetrix services. The SACCS service will first call out the Supplier Availability service to determine whether or not the products are available, and pass this information to the Shipping service. Then the Shipping service will request shipping options via your API and includes the shipping address' postal code.

Shipping Options Diagram

Create Backup Shipping Provider API

To prevent service interruptions, iQmetrix strongly recommends suppliers provide a secondary shipping options API to be used as a failover if the original service is taken down accidentally or for maintenance.

If provided, this must be in the form of a list of options with flat rate shipping fees.

Provide Shipping Provider API Details

Once you have created the Shipping Provider API, provide iQmetrix with the following information for all available environments:

Request Test Orders

When you are ready to start testing orders, contact your Launch Specialist to create Test Orders for your integration.

Access the Order Feed

Once orders have been placed in iQmetrix applications, you can view them using the Order Notifications Feed.

You may also use Dropship Webhooks as an alternative to polling the Dropship API.

Order Feed Diagram

When reading the order entry, one of two shipping addresses are given: the store address or the customer address, determined by the shipping-address.type field.

Order notifications are an archive of all your orders, regardless of retailer or location.

Each page of the feed will contain up to 50 events. If a page has 50 events and a new event occurs, then those 50 events are pushed into an archived page. The current feed will contain the new event at this time. This feed must be monitored by the supplier and when a new order is placed the supplier can process this order. It is up to the supplier’s system to keep track of the orders that have been processed and their current status.

It is also possible to get historical archives from the order feed, see Parse Order Archives.

The Order Feed is divided into two order types: order-created, generated by the client (i.e. RQ), and order-status-updated, generated by the supplier. Each resource has its own list of fields and is set up as a separate entry in the Order Feed.

The order-id is found in the Order Notifications Feed under the order type. This order-id is separate from the order ID that is generated by the retailer. Use the order-id when updating the status of your orders.

To get the latest Order Notification Feed entries, use the request Getting the Order Feed and the following parameters:

Example Request

GET https://dropshiprc.iqmetrix.net/v1/Suppliers(14107)/Notifications
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/atom+xml

Example Response

HTTP 200 Content-Type: application/json

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="https://www.w3.org/2005/Atom">
    <title type="text">Dropship Order Event Feed</title>
    <id>urn:uuid:477d9f09-2965-4452-8770-bfbc24328b21</id>
    <updated>2017-08-04T21:57:25Z</updated>
    <author>
        <name>iQmetrix</name>
    </author>
    <link rel="current" href="https://dropshiprc.iqmetrix.net/v1/Suppliers(14107)/Notifications" />
    <link rel="self" href="https://dropshiprc.iqmetrix.net/v1/Suppliers(14107)/Notifications/Pages(477d9f09-2965-4452-8770-bfbc24328b21)" />  
    <entry>
        <id>urn:uuid:659a9f09-0d1d-46da-8899-aff5ebd758b8</id>
        <title type="text">Dropship Order Status Updated</title>
        <published>2017-08-04T21:52:33Z</published>
        <updated>2017-08-04T21:52:33Z</updated>
        <content type="application/xml">
            <order-status-updated xmlns:i="https://www.w3.org/2001/XMLSchema-instance" xmlns="urn:iQmetrix:dropship">
                <company-id>14066</company-id>
                <items>
                    <item-information>
                        <catalog-id>cec02f3f-22d7-4504-83a8-5afda2dfc1a0</catalog-id>
                        <info>www.ups.com</info>
                        <message></message>
                        <quantity>1</quantity>
                        <reference-name i:nil="true" />
                        <reference-value i:nil="true" />
                        <shipping-provider>UPS</shipping-provider>
                        <sku>9101AGAP6</sku>
                        <status>Shipped</status>
                        <tracking-info>23923408863</tracking-info>
                    </item-information>
                </items>
                <order-id>0ff6f9f7-9e31-4039-8365-ff5471dbee7e</order-id>
                <supplier-id>14107</supplier-id>
            </order-status-updated>
        </content>
    </entry>
    <entry>
        <id>urn:uuid:f01bbbda-c0b5-4a77-9563-5d62d3f8dc08</id>
        <title type="text">Dropship Order Created</title>
        <published>2015-12-03T23:36:22Z</published>
        <updated>2015-12-03T23:36:22Z</updated>
        <content type="application/xml">
            <order-created xmlns:i="https://www.w3.org/2001/XMLSchema-instance" xmlns="urn:iQmetrix:dropship">
                <items>
                    <order-item>
                        <catalog-id>b85cb879-bb5f-4847-a856-8287de0a92d5</catalog-id>
                        <description>Samsung Galaxy S4 Standard Battery</description>
                        <quantity>1</quantity>
                        <selling-price>39.99</selling-price>
                        <sku>B00LAOKN4S</sku>
                    </order-item>
                </items>
                <order-id>abe6a66f-7009-4af4-b02d-3aaf08dba043</order-id>
                <seller>
                    <company-id>14146</company-id>
                    <location-id>14223</location-id>
                    <po-reference>TT101IN18</po-reference>
                    <printable-id>7400009</printable-id>
                </seller>
                <ship-to-store>false</ship-to-store>
                <shipping-address>
                    <address-id>a08b0640-606a-41f0-901a-facaf50e75dd</address-id>
                    <attention-to i:nil="true" />
                    <business-name i:nil="true" />
                    <country>Canada</country>
                    <country-code>CA</country-code>
                    <locality>Yellowknife</locality>
                    <notes i:nil="true" />
                    <phone i:nil="true" />
                    <post-office-box-number i:nil="true" />
                    <postal-code>X1A 3X7</postal-code>
                    <region>Northwest Territories</region>
                    <region-code>NT</region-code>
                    <street-address-1>4702 Anderson-Thomson Blvd</street-address-1>
                    <street-address-2 i:nil="true" />
                    <type>Home</type>
                </shipping-address>
                <shipping-customer>
                    <alternate-name i:nil="true" />
                    <customer-id>659c2a38-d083-4421-9330-46d779702f85</customer-id>
                    <family-name>Jasmine</family-name>
                    <middle-name i:nil="true" />
                    <notes>Interested in iPhone 6</notes>
                    <primary-name>Princess</primary-name>
                    <title>Ms</title>
                    <type>Person</type>
                </shipping-customer>
                <shipping-entity-id>0</shipping-entity-id>
                <shipping-method>1716</shipping-method>
                <supplier-id>14107</supplier-id>
            </order-created>
        </content>
    </entry>
</feed>

Example Request (C#)

using System;
using System.Configuration;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.ServiceModel.Syndication;
using System.Xml;
using System.Xml.Linq;
using System.Xml.Serialization;

public void GetAtomFeedFirstPage(string authToken, int supplierId)
{
    var stream = GetAtomFeed(authToken, supplierId);
    var reader = XmlReader.Create(stream);
    var feed = SyndicationFeed.Load(reader);

    // Note: this example does not include logic to recursively navigate through previous feed pages until the last processed order is found.

    foreach (var item in feed.Items)
    {
        // process feed items
        // this could include using an XmlSerializer to deserialsize
        var textContent = item.Content as XmlSyndicationContent;
        if (textContent != null)
        {
            var element = textContent.ReadContent<XElement>();
            using (var reader = element.CreateReader())
            {
                var serializer = new XmlSerializer(typeof(AtomFeedOrder));
                var order = (AtomFeedOrder)serializer.Deserialize(reader);
            }
        }
    }
}

public Stream GetAtomFeed(string authToken, int supplierId, string
archiveUrl = null)
{
    Stream result = null;
    HttpClient client = new HttpClient();

    var baseUrl = "https://dropshiprc.iqmetrix.net/";
    var url = archiveUrl == null
        ? string.Format("v1/Suppliers({0})/Notifications", supplierId)
        : archiveUrl;
    client.BaseAddress = baseUrl;
    client.DefaultRequestHeaders.Accept.Clear();
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/atom+xml"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", authToken);
    return client.GetStreamAsync(url).GetAwaiter().GetResult();
}

Parse Order Archives

Each order feed archive, including the current order feed, contains a link to the previously archived 50 events.

We recommend storing the ID of the last order retrieved to access the next batch of orders.

To get the latest Order Notification Archives, use the request Getting the Order Feed Archives and the following parameters:

Example Request

GET https://dropshiprc.iqmetrix.net/v1/Suppliers(14017)/Notifications/Pages(477d9f09-2965-4452-8770-bfbc24328b21)
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/atom+xml

Example Response

Example response truncated for brevity.

HTTP 200 Content-Type: application/json

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="https://www.w3.org/2005/Atom">
    <title type="text">Dropship Order Event Feed</title>
    <id>urn:uuid:477d9f09-2965-4452-8770-bfbc24328b21</id>
    <updated>2017-08-04T21:57:25Z</updated>
    <author>
        <name>iQmetrix</name>
    </author>
    <link rel="current" href="https://dropshiprc.iqmetrix.net/v1/Suppliers(14107)/Notifications" />
    <link rel="self" href="https://dropshiprc.iqmetrix.net/v1/Suppliers(14107)/Notifications/Pages(477d9f09-2965-4452-8770-bfbc24328b21)" />
    <entry>
        <id>urn:uuid:dc43a5eb-b9dd-4dce-b2a2-39ecfef3c090</id>
        <title type="text">Dropship Order Status Updated</title>
        <published>2017-08-04T21:57:24Z</published>
        <updated>2017-08-04T21:57:24Z</updated>
        <content type="application/xml">
            <order-status-updated xmlns:i="https://www.w3.org/2001/XMLSchema-instance" xmlns="urn:iQmetrix:dropship">
                <company-id>14066</company-id>
                <items>
                    <item-information>
                        <catalog-id>cec02f3f-22d7-4504-83a8-5afda2dfc1a0</catalog-id>
                        <info>www.ups.com</info>
                        <message></message>
                        <quantity>1</quantity>
                        <reference-name i:nil="true" />
                        <reference-value i:nil="true" />
                        <shipping-provider>UPS</shipping-provider>
                        <sku>9101AGAP6</sku>
                        <status>PartiallyShipped</status>
                        <tracking-info>23923408863</tracking-info>
                    </item-information>
                </items>
                <order-id>0ff6f9f7-9e31-4039-8365-ff5471dbee7e</order-id>
                <supplier-id>14107</supplier-id>
            </order-status-updated>
        </content>
    </entry>
</feed>

Shipping an Order

It is recommended to hold the order (i.e. BackOrdered) until all items are available and in-stock to reduce any overhead involved with partial shipments.

Partial shipments are supported but are currently limited. It is highly recommended to ship a complete order, rather than a partially shipped order. See (Optional) Partially Ship an Order for more information.

Notifying the End Customer

Once the order, or one or more items, are set to a Shipped status, an email is automatically generated by iQmetrix and sent to the end customer. In the case of item status updates, an email is sent for each unique batch of items set to the Shipped status.

It is the responsibility of the courier to notify the end customer when their shipment is en route. The end customer’s phone number is provided via the shipping-customer under the Order Created resource in the Order Notifications Feed.

Should the end customer not provide a phone number, we recommended contacting the store via the seller.location-id property under the Order Created resource.

Update Shipping Status for an Order

Once you have processed an order, you must update the status of the Order - which will generate an email for the consumer.

Tip: Updating the Status of an Order will update the status of each Item on the Order.

Dropship Order Status

To perform a status update use the request Update the Status of a Dropship Order and the following parameters:

Example Request

PUT https://dropshiprc.iqmetrix.net/v1/Suppliers(14107)/Orders(0ff6f9f7-9e31-4039-8365-ff5471dbee7e)/OrderStatusUpdate
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
{
    "Id": "0ff6f9f7-9e31-4039-8365-ff5471dbee7e",
    "Info": "www.ups.com",
    "Message": "",
    "ShippingProvider": "UPS",
    "Status": 2,
    "TrackingInfo": "23923408863"
}

Example Response

HTTP 202 Content-Type: application/json

{
    "Id": "0ff6f9f7-9e31-4039-8365-ff5471dbee7e",
    "Status": "Shipped",
    "TrackingInfo": "23923408863",
    "ShippingProvider": "UPS",
    "ReferenceName": null,
    "ReferenceValue": null,
    "Info": "www.ups.com",
    "Message": ""
}

(Optional) Partially Ship an Order

There are two scenarios when updating the status of an order:

  1. All items are available and a full shipment is sent to the end customer.
  2. One or more items are not available but partial shipment to the end customer is possible.

iQmetrix recommends avoiding partial shipments wherever possible. However, while partial shipment is not recommended, the Dropship service does support multiple tracking numbers for a single order item.

To let Dropship know that quantities on a single order item are being shipped separately, use "Status": 6 (PartiallyShipped) when updating item status until all quantities have been shipped, then use "Status": 2 (Shipped).

Clients subscribed to iQmetrix shipping notification emails are notified when the ItemStatus is updated to "Status": 2 (Shipped).

Multiple tracking numbers may be put in the TrackingInfo field delimited by commas, e.g. 1Z863YY60392796356,1Z863YY60393998. Note that quantities in each shipment will not be indicated to customer.

Warning: When adding additional tracking number(s) to an order, ensure you retrieve any existing tracking number(s) on the order first and send them as a single comma-delimited field ('TrackingInfo': '1Z863YY60392796356,1Z863YY60393998'). This will prevent overriding existing tracking numbers on the order.

If an order has items that are currently unavailable but must be shipped, then you must contact iQmetrix Support to coordinate with the partial shipments.

There are two main cases when handling partial shipments, choose the most appropriate case that applies to you:

Dropship Partial Order

Incremental Shipments

In this scenario, the supplier would continue to update the status of individual items up to and including the final partial shipment.

For example, an order has 3 different items that have different levels of availability. One of the items is currently available, and so a partial shipment is made with that item stated as Shipped. This occurs two more times, when each product becomes available, including the final partial shipment. The Shipped status needs to be repeated for each subsequent partial shipment.

Partial Shipments followed by a Complete Order

In this scenario, the supplier would continue to update the status of individual items, and send a complete order for the final shipment.

For example, an order has 3 different items that have different levels of availability. One of the items is currently available, and so a partial shipment is made with that item stated as Shipped. This occurs one more time when one of the products becomes available. The final shipment is a complete order shipment, requiring only one status update. The Shipped status needs to be repeated for each partial shipment.

Updating Item Status

For Partial Shipments, use the request Update the Status of an Item on an Order and the following parameters:

Example Request

PUT https://dropshiprc.iqmetrix.net/v1/Suppliers(14107)/Orders(0ff6f9f7-9e31-4039-8365-ff5471dbee7e)/ItemStatusUpdate
Authorization: Bearer b0k0dY70N3Vv9jR1b9oEdW9IeT5WIn85WCYFJRo6AiIKLEMBFwNbEQsfeCUeM3gdPA1gAAVxWTJacX8mJyBaGRcFVwQOEV49NgBz
Accept: application/json
Content-Type: application/json
{
    "Id": "0ff6f9f7-9e31-4039-8365-ff5471dbee7e",
    "ItemInformation": [
        {
            "Status": 6,
            "Sku": "9101AGAP6",
            "Info": "www.ups.com",
            "Message": "",
            "ProductName": "239234SMS L720 BLU SPT RTD8863",
            "Quantity": 5,
            "ShippingProvider": "UPS",
            "TrackingInfo": "23923408863"
        }
    ]
}

Example Response

HTTP 202 Content-Type: application/json

{
    "Id": "0ff6f9f7-9e31-4039-8365-ff5471dbee7e",
    "ItemInformation": [
        {
            "Sku": "9101AGAP6",
            "CatalogId": "cec02f3f-22d7-4504-83a8-5afda2dfc1a0",
            "Quantity": 1,
            "Status": "PartiallyShipped",
            "TrackingInfo": "23923408863",
            "TrackingUrl": "https://wwwapps.ups.com/etracking/tracking.cgi?tracknum=23923408863",
            "ShippingProvider": "UPS",
            "ReferenceName": null,
            "ReferenceValue": null,
            "Info": "www.ups.com",
            "Message": ""
        }
    ]
}

Cancel an Order

Order cancellations require human interaction and are a manual process between a retailer and supplier to provide a refund to an end customer.

There are three possible scenarios when cancelling an order:

Supplier Cancels Order

Two concurrent processes occur when a supplier cancels an order.

First, they must communicate with their retailer’s support contact who handles orders and cancellations. It is assumed that suppliers will have the company’s support contact information and that all support-related inquiries are handled at the corporate level, rather than individual store locations.

Second, the supplier must update the Dropship item or order status to Cancelled. This will notify iQmetrix to update records for the order.

Retailer Cancels Order

A supplier has the exclusive ability to cancel a Dropship order, as the retailer is unaware of the current status of the Dropship order at the supplier level (picked, packed or shipped).

This scenario follows the same process as a supplier cancelling an order.

Customer Cancels Order

Customers cannot cancel orders with a supplier, they must cancel with the retailer, who will contact the supplier to cancel the order.

Overview

Onboarding

Managing Products

Managing Orders

Launch