Search

Reference: Purchase Order API

A purchase order represents instructions to a vendor or warehouse to ship the specified items to the end customer.

The Purchase Order object

A Purchase Order is associated with:

  • A single Shipping Address
  • One or more Order Items

Each Purchase Order has the following attributes:

Field Description
id

The unique numeric identifier for the purchase order.

This is assigned by Duoplane and cannot be changed.

This id is used primarily for interaction with the API.
public_reference

The alphanumeric purchase order number reference to the purchase order.

This value is unique for a given retailer. Depending on the settings of the retailer, the PO number is either an auto-incrementing numeric value, or it is the sales order number followed by a numeric suffix (e.g. 1001-1).
created_at The date and time in UTC when the purchase order was created.
updated_at The date and time in UTC when the purchase order was last updated.
ordered_at The date and time in UTC when the sales order was placed.
sent_at The date and time in UTC when the purchase order was sent to the vendor.
order_id

The unique numeric identifier for the sales order.

This is assigned by Duoplane and cannot be changed.
order_public_reference The order number or code assigned to the sales order by the ecommerce platform.
retailer_id The unique numeric identifier for the purchase order's retailer. This value is assigned by Duoplane.
retailer_account

The account number for this retailer in the vendor's internal systems.

This must be configured within Duoplane in order to appear.
retailer_name The name of the retailer who created this purchase order.
vendor_id The unique numeric identifier for the purchase order's vendor. This value is assigned by Duoplane.
vendor_account

The account number for this vendor in the retailer's internal systems.

This must be configured within Duoplane in order to appear.
vendor The name of the vendor of this purchase order.
vendor_reference A reference to this purchase order in the vendor's system. This value can be assigned by a vendor in order to link a purchase order to a sales order or other record in the vendor's system.
status

The status of the purchase order. Possible values are:

  • open (not sent): The PO is unfulfilled and has not yet been sent to the vendor
  • open: The PO has been sent to the vendor but has not been fulfilled
  • partially fulfilled: Some items on the PO have been fulfilled, and others have not yet been fulfilled.
  • complete: All items on the PO have been fulfilled.
  • canceled: All items on the PO have been canceled.
store_name The name of the store for the associated sales order.
ship_method The ship method specified for this purchase order.
total_shipping_revenue The shipping revenue collected from the end customer for the items on this purchase order.
Depending on the merchant’s settings, total_shipping_revenue may not be visible on purchase orders.
total_tax The tax collected from the end customer for the items on this purchase order.
Depending on the merchant’s settings, total_tax may not be visible on purchase orders.
promise_date

The date by which this purchase order is expected to ship. If the purchase order has multiple items with different expected ship dates, the overall promise_date is the earliest expected ship date of the unfulfilled items on the purchase order.
customer_note Order-level customer note.
Depending on the merchant’s settings, customer_note may not be visible on purchase orders.
order_notes

An array of order-level attributes from the ecommerce channel:

  • title: The note title / key
  • body: The note body / value
Depending on the merchant’s settings, order_notes may not be visible on purchase orders.
shipping_address

The address where the order should be shipped. The fields provided for the shipping address are:

  • first_name
  • last_name
  • company_name
  • address_1
  • address_2
  • city
  • province
  • post_code
  • country
  • phone*
  • email*
* Depending on the merchant's settings, customer email addresses and phone numbers may not be visible on purchase orders.
order_items

The items on the purchase order.

  • id: The unique numeric ID assigned to this line item by Duoplane.
  • retailer_product_id: The unique numeric ID of the product associated with this line item.
  • name: The name of the line item.
  • retailer_sku: The SKU of the item in the retailer's internal systems.
  • vendor_sku: The SKU of the item in the vendor's internal systems.
  • upc: The UPC (Universal Product Code) of the item
  • mpn: The MPN (Manufacturer Part Number) of the item
  • other_barcode: Other user-defined product identifier for the item
  • quantity: The quantity of this item requested.
  • quantity_open: The quantity of this item remaining to be fulfilled.
  • cost: The agreed-upon wholesale cost of this item. (Cost per unit)
  • price: The retail price of the item. (Price per unit) This will only display if allowed by the retailer.
  • total_discount: The total discount for this line item. This will only display if allowed by the retailer.
  • net_price: The total price of the item less any discounts. This will only display if allowed by the retailer.
  • promise_date: The date by which this item is expected to be shipped.
  • order_item_notes: An array of item-level attributes from the ecommerce channel.
    • title: The note title / key
    • body: The note body / value
  • order_item_comments: An array of item-level messages between the retailer and vendor.
    • id: The unique numeric ID assigned to this comment by Duoplane.
    • commenter_company_name: The name of the company that created the comment.
    • recipient_company_name: The name of the recipient of the comment.
    • body: The comment contents.
  • order_item_parent: If the item was part of a bundle, the parent (bundle) order item. This is only visible to the retailer.
    • id: The unique numeric ID assigned to the bundle order item by Duoplane.
    • name: The name of the parent order item.
    • retailer_sku: The SKU of the parent order item.
    • retailer_product_id: The unique numeric ID of the product associated with the parent order item.

Retrieve a list of purchase orders

GET https://app.duoplane.com/purchase_orders.json

All request parameters must be nested in a hash / associative array with the key "search". E.g.:

?search[fulfilled]=1
Search Parameter Description
ids

An array of numeric purchase orders IDs.

Note that this refers to the unique IDs that are automatically assigned by Duoplane to each purchase order, not the commonly referenced purchase order number.
customer_name

The name of the customer on the shipping address of this purchase order.

Partial matches are allowed. (E.g. a search for "B Smi" will find "Bill Smith".)
public_reference The purchase order number as it appears on the purchase order.
order_public_reference The order number or code assigned to the sales order by the ecommerce platform.
vendor_reference A reference to this purchase order in the vendor's system.
order_item_name

The name of an item on the purchase order.

Partial matches are allowed. (E.g. a search for "R Bag" will find "Red Bag".)
fulfilled

Whether the purchase order has been completely fulfilled.

Acceptable values for "true" are "true", "1", or "yes" (all case insensitive). Any other value is "false".
late Whether any items on the purchase order are late, as determined by the item's most recent promise date.
confirmed Whether the purchase order has been marked as "confirmed".
canceled Whether all of the items on the purchase order have been canceled.
vendor_id The Duoplane-assigned unique numeric ID of the vendor on the purchase order.
retailer_id The Duoplane-assigned unique numeric ID of the retailer on the purchase order.
created_at_min Retrieve only purchase orders created after this time.*
created_at_max Retrieve only purchase orders created before this time.*
updated_at_min Retrieve only purchase orders updated after this time.*
updated_at_max Retrieve only purchase orders updated before this time.*
sent_at_min Retrieve only purchase orders that were sent to the vendor after this time.*
sent_at_max Retrieve only purchase orders that were sent to the vendor before this time.*

 

* Times should be in ISO 8601 format with time zone or zone offset. If not explicitly provided, the time zone is assumed to be that of the requesting API user.

Pagination

In addition to the search filters, you can specify paging parameters:

Paging Parameter Description
per_page

 

The maximum number of records to return with each call. The default and maximum value is 250.
page

 

If the count of records matching the search exceeds the number that are returned in a single response, the page number for subsequent requests.

Update a purchase order

PUT https://app.duoplane.com/purchase_orders/#{purchase_order_id}.json

The following fields can be used to update an existing purchase order:

Field Description
confirmed

Set this to acknowledge the receipt and acceptance of a purchase order.

Any of the following values are acceptable to indicating that a purchase order is confirmed (case-insensitive): yes, y, true, or 1
hold_purchase_order_until

For purchase order that have not yet been sent to the vendor, this is a timestamp for the earliest time to release the purchase order to the vendor. This is useful for holding purchase orders until a future date. The timestamp should be in ISO 8601 format with time zone or zone offset.

This field can only be updated by the purchase order retailer, and it can only be updated before a purchase order is sent to the vendor.
promise_date The date by which this purchase order is expected to ship. If this value is updated via the API, the promise dates of all unfulfilled items on the purchase order will be updated to this value.
vendor_reference A reference to this purchase order in the vendor's system.
new_vendor_id

Set new_vendor_id to move all items on this PO to a new PO whose vendor is identified by new_vendor_id.

Setting a new_vendor_id will create a new purchase order. The new purchase order will be returned in the API response.

This field can only be set by the purchase order retailer.

Sample request for confirming a purchase order and setting a vendor reference:

PUT https://app.duoplane.com/purchase_orders/987654.json
{
    "purchase_order": {
    	"confirmed": 1,
    	"vendor_reference": "SO9876"
    }
}