Purchase Order
The Purchase Order API is used to create new purchase orders, or to update, cancel, approve or to get information about already created purchase orders. A purchase order will create one or more fulfillment orders.
Order API vs. Purchase Order API
Our Purchase Order and Order APIs are both used to send fulfillment orders to our warehouses for outbound shipments. The Order API will be sufficient for B2C orders as it would have the necessary fields for standard direct-to-consumer shipments such as the customer’s contact info, ship-to address, SKU and QTY, shipping method, etc.
For B2B shipments, most retailers will require additional info to process your Purchase Order. The Purchase Order API will have all the fields available in the Order API, along with additional fields to meet the requirements for these more complex retailer orders. These fields include retailer SKUs, bill-to info, shipping/delivery windows, and more.
Another reason to use the PO API would be if you have more complex requirements for B2C shipments, such as printing extra product information (retailer SKU, UPC, custom product descriptions per retailer, etc), or additional order level attributes on custom packing lists. The Orders API is not able to handle these use cases.
Important note: By default, if a PO you submit has errors, it will be placed on hold, and a fulfillment order will not be created until the PO is corrected with an update (PUT). We strongly suggest that you avoid this default behavior by adding “doNotPersistOnWarnings”:1 under the root level in the request JSON (ie, directly beneath “purchaseOrderNo” is a good spot). To determine whether a specific post to the PO API was successful, check the JSON response to see that resource.total = 1. If it is 0, then the PO was not created. In that case, v4Errors and/or v4Warnings will contain the issues with the PO that need to be resolved before attempting posting again. Please surface these within your integration to your users. Note that resource.total may be 1 and there may be some v4Warnings. An example would be invalid address, which will not prevent the PO from posting.
Note on retries: Our PO API typically responds in less than 10 seconds, but please allow for up to 150 seconds for a response before enforcing a network timeout and retrying your post. When you retry, if you receive an error message with “duplicate” in it, it indicates that your previous request was successful. If you need details from that order or want to confirm that is in our system, you may retrieve it by doing a GET call using the externalId or orderNo parameters.
Note: By default, a PO will go into a “needs approval” status, so that you can build a workflow to either approve or cancel POs. The majority of customers choose to bypass this flow and post POs as already approved by passing “isApproved”:1 under “options”.
Use of externalIds and the “canSplit” option
External ids must be unique in our system, so, when splitting orders across two warehouses, we follow the convention of adding “.1” to the first order’s externalId and “.2” to the split order. You will need to use this when trying to GET an order by its externalId, or to cross reference the externalId in an order.completed webhook JSON body with the original externalId on your end. Also note that externalIds are limited to 32 characters in our system. If you use the canSplit option or have us enable splitting all of your orders on our end, you must limit the externalId you send to us to 30 characters, so we can add “.1” or “.2” to the end.
External ids must be unique in our system, so, when splitting orders across two warehouses, we follow the convention of adding “.1” to the first order’s externalId and “.2” to the split order. You will need to use this when trying to GET an order by its externalId, or to cross reference the externalId in an order.completed webhook JSON body with the original externalId on your end. Also note that externalIds are limited to 32 characters in our system. If you use the canSplit option or have us enable splitting all of your orders on our end, you must limit the externalId you send to us to 30 characters, so we can add “.1” or “.2” to the end.