Reference: Duoplane API Workflow For Vendors

Vendors generally use the Duoplane API in order to (a) pull purchase orders and (b) push back tracking for completed shipments. This article provides a quick-start guide for this workflow.

Getting started

1. Create an API user: In order to get started, you will first need to create an API user. To do that, please refer to the section called "How to create an API user" in our Duoplane API overview article.
2. Review the API endpoints: This guide uses two endpoints: the Purchase Order API and the Shipment API.

Pulling purchase orders

The strategy outlined below looks for any purchase orders that were created or updated during a certain time period. Alternate strategies are discussed below.

The Purchase Order API reference is linked here.

1. Decide on a start time. In this example, we are starting at 2:00am UTC on May 5, 2021 (2021-05-01T02:00:00Z).
2. Call the GET purchase_orders endpoint to pull POs that were created or updated since the start time. This call requests all POs that have been created or updated since our start time:

   GET https://app.duoplane.com/purchase_orders.json?search[updated_at_min]=2021-05-01T02:00:00Z&page=1

3. Store the purchase order information in your system. Remember to store the id values of the purchase order and each order item. You will need these in order to mark the items as shipped.

4. The next time you call the GET purchase_orders endpoint, update the search[updated_at_min] query parameter based in the time when you last called the endpoint. That will fetch POs that were created or updated since the last time you checked.

The strategy outlined above queries for purchase orders based on the updated_at timestamp. The updated_at timestamp will change every time a PO is updated for any reason, so you will likely see purchase orders in the API response that you have seen in previous responses.

That means that you will need a way to prevent duplicates in your system. The id value of each purchase order is unique, so you can rely on the id to identify POs that you have already added to your system.

Alternate querying strategies

Query for POs based on the sent_at value

If you only want to see new POs (and not updated ones), you can query using the sent_at_min and sent_at_max search parameters. Those will show POs that were marked as "sent" within a certain timeframe. POs can only be marked as sent once, so the sent_at timestamp will not change.

Query for unconfirmed POs and confirm them once received

To only search for unconfirmed POs:

1. Call the GET purchase_orders endpoint to pull unfulfilled POs where confirmed = false:

   GET https://app.duoplane.com/purchase_orders.json?search[fulfilled]=0&search[confirmed]=0&page=1

2. Store the purchase order information in your system.

3. Mark each PO as confirmed by calling:

   PUT https://app.duoplane.com/purchase_orders/[id].json
   {
       "purchase_order": {
       	"confirmed": 1
       }
   }

Tips

• Remember that the purchase_orders endpoint uses pagination, so you might need to fetch subsequent pages. The Duoplane-Has-Next-Page header value tells you whether there are more records to get.
• Also note that at least one search criteria must be present. In other words: GET https://app.duoplane.com/purchase_orders.json will yield no results.

A typical response might look like this: (not all fields are shown)

GET https://app.duoplane.com/purchase_orders.json?search[updated_at_min]=2021-05-01T02:00:00Z&page=1
[
    {
        "id": 987654,
        "public_reference": "1001-1",
        "shipping_address": {
            "first_name": "Joe",
            "last_name": "Customer",
            "company_name": "",
            "address_1": "123 Main St.",
            "address_2": "",
            "city": "Anywhere",
            "province": "NY",
            "province_iso": "NY",
            "post_code": "10005",
            "country": "United States",
            "country_iso2": "US",
        },
        "order_items": [
            {
                "id": 239417,
                "name": "Running shoes - 11 / Orange",
                "vendor_sku": "SHOE-ORANGE-11",
                "quantity": 1
            },
            {
                "id": 239418,
                "name": "Socks - black",
                "vendor_sku": "SOCKS",
                "quantity": 2
            }
        ]
    },
    {
        "id": 123456,
        "public_reference": "1002-2",
        "shipping_address": {
            "first_name": "Jill",
            "last_name": "Customer",
            "company_name": "",
            "address_1": "123 Main St.",
            "address_2": "",
            "city": "Anywhere",
            "province": "NY",
            "province_iso": "NY",
            "post_code": "10005",
            "country": "United States",
            "country_iso2": "US",
        },
        "order_items": [
            {
                "id": 239419,
                "name": "Hat",
                "vendor_sku": "HAT",
                "quantity": 1
            }
        ]
    },
]

Pushing back tracking for completed shipments

The Shipment API reference is linked here.

For each shipment, call POST https://app.duoplane.com/purchase_orders/[purchase_order_id]/shipments.json to mark the purchase order as fulfilled.

For example, to fulfill the first PO in the example above, you can make this API call:

POST https://app.duoplane.com/purchase_orders/987654/shipments.json
{
    "shipment": {
    	"shipper_name": "UPS",
    	"shipment_items_attributes": [
    		{
    			"order_item_id": 239417,
    			"quantity": 1
    		},
    		{
    			"order_item_id": 239418,
    			"quantity": 2
    		}
    	],
    	"shipment_trackings_attributes": [
    		{
    			"tracking": "1234"
    		},
    		{
    			"tracking": "5678"
    		}
    	]
        
    }
}