Reference: Purchase Order API – Duoplane Support Center

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.

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"
    }
}