Purchase Order API Tutorial
Table of contents
We have developed a robust set of APIs to accommodate complex orders. With lightweight and agile API endpoints, the onboarding process is made easy with speed and quality. Using Flexport's Purchase Order API, you can get your orders into the Flexport platform from your Enterprise Resource Planning (ERP) or Truck Managment Software (TMS) and enable end-to-end supply chain transparency and control.
Directly integrating with our platform through our APIs can help you scale your order management integration while reducing time and manual effort.
The Flexport PO API is available at its endpoint of: https://api.flexport.com/purchase_orders
We’ll start out by first creating a purchase order and continue to revise it as we go along.
Endpoints
GET /purchase_orders
GET /purchase_orders/id
GET /purchase_order_line_items
GET /purchase_order_line_items/id
A few things need to be established before you can use the Purchase Order API:
- Network Setup - The Buyer and Seller Refs to be used in a purchase order need to be set up as Legal Entity Reference ID’s. The Origin Location and Destination Location Refs on the order will need to be set up as Network Location Reference ID’s (under the appropriate parent company)
- SKU Creation - If a purchase order contains both an SKU and Product Name, a new Product Library record will be created with only those two values if one does not already exist. If a Product Library record already exists, the order only needs to include the SKU in a request.
We create an order with a HTTP POST:
curl -X "POST" "https://api.flexport.com/purchase_orders" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Content-Type: application/json" \
-d $'{
"name": "Our First PO",
"status": "open",
"priority": "standard",
"order_class": "purchase_order",
"parties": [
{
"role": "buyer",
"external_ref": "id-739011"
},
{
"role": "seller",
"external_ref": "id-740685"
}
],
"currency_code": "USD",
"must_arrive_date": "2004-08-10",
"cargo_ready_date": "2004-05-24",
"transportation_mode": "ocean",
"incoterm": "FOB",
"line_items": [
{
"item_key": "1",
"product": {
"sku": "sku123",
"name": "Cool Product 123"
},
"must_arrive_date": null,
"cargo_ready_date": null,
"transportation_mode": null,
"incoterm": null,
"units": "500",
"unit_cost": {
"_object": "/money",
"amount": "4.65",
"currency_code": "USD"
},
"line_type": "main_line",
"unit_of_measure": "EA"
}
]
}'
Here, our end point is https://api.flexport.com/purchase_orders. We use the typical HTTP JSON headers, Accept: application/json and Content-Type: application/json, along with your API token:
-H "Authorization: Bearer {Your token}"
The request has quite a few data elements. Let’s review the required and optional elements separately.
A name element must always be assigned to a new PO. Though we use the value of Our First PO in our example, note that the name element is actually the purchase order number. Remember to use the PO number for name.
You’ll need to explicitly declare how the shipment is being transported. Use the transportation_mode element and provide a valid value of either: ocean, air, truck
An incoterm is required. An incoterm (international commercial terms) is a designation for the terms of sale which defines payment and handling details about shipped goods. Supply only one of the following:
- EXW (Ex Works)
- FCA (Free Carrier)
- CPT (Carriage Paid To)
- CIP (Carriage & Insurance Paid To)
- DAT (Delivered at Terminal)
- DPU (Delivered at Place Unloaded)
- DAP (Delivered at Place)
- DDP (Delivered Duty Paid)
- FAS (Fee Alongside Ship)
- FOB (Free on Board)
- CFR (Cost & Freight)
- CIF (Cost Insurance Freight)
Next, we’ll look at the more commonly used optional elements.
The status parameter is optional: if not sent, status defaults to open. An open PO is one which is ready to be booked. Other values are closed and cancelled. Sending a request with a status of cancelled will cancel the order entirely prior to Booking. This will archive the order, thus making it unavailable. Sending closed if some booking activity has occurred on the order, thus preventing any further activity; closing an order also preserves the quantities ordered so they can be compared to what was shipped.
There is also an Auto-Close value where you may specify the number of days after a certain date to do so. A purchase order’s status will change to one of those during its life cycle, but remember, it always starts out as open.
Just as importantly, order_class must be set to purchase_order. Doing so declares that the type of Order object being sent is indeed a PO order object.
The parties object is a bit more involved. It is an array of other objects and name-value pairs with which you convey the details of those involved in the actual purchase. Before diving into its components, let’s go over some of the more important ones which record the who, what and where aspects of the PO.
We describe who is involved in the purchase using both a role and a company_entity object. Valid roles include buyer, seller and owner. See link for the full list of roles. The owner is the party who has issued the Order and whose rules should be applied to it. For Purchase Orders, this is almost always the same as the buyer. The company_entity object allows you to add more detail to each role involved.
A word is in order about a couple of other optional elements: must_arrive_date and cargo_ready_date. Their meanings are pretty straightforward: the date that the shipment must arrive by, and the date that the cargo will actually be ready to ship, respectively. It’s important to note that the following logic applies:
If both must_arrive_date and cargo_ready_date are sent, cargo_ready_date must chronologically precede must_arrive_date, that is, the cargo must be available to ship before the declared arrival date.
Here’s an example of a complete listing of a HTTP response showing the returned parties object:
{
"_object": "/api/response",
"self": "https://api.flexport.com/purchase_orders/?expand=line_items&f.name=PO0153310816a",
"version": 3,
"data": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 1,
"data": [
{
"metadata": {},
"_object": "/purchase_order",
"id": 171997,
"name": "PO0153310816a",
"incoterm": "FOB",
"transportation_mode": "ocean",
"cargo_ready_date": "2004-05-24",
"must_arrive_date": "2004-08-10",
"origin_port": {
"_object": "/place",
"name": "Xiamen, China",
"address": {
"_object": "/address",
"street_address": null,
"street_address2": null,
"city": "Xiamen",
"state": null,
"country": "China",
"country_code": "CN",
"zip": null,
"unlocode": "CNXMN",
"timezone": "Asia/Shanghai",
"ref": "id-36028"
},
"details": [
{
"_object": "/trucking/port",
"port_code": "57069"
},
{
"_object": "/ocean/port",
"port_code": "57069"
}
]
},
"origin_address": {
"_object": "/address",
"street_address": "335 Meixing Rd",
"street_address2": null,
"city": "Shenzhen",
"state": null,
"country": "China",
"country_code": "CN",
"zip": null,
"unlocode": null,
"timezone": "Asia/Shanghai",
"ref": "lex_corp_warehouse"
},
"destination_port": {
"_object": "/place",
"name": "Oakland, CA",
"address": {
"_object": "/address",
"street_address": null,
"street_address2": null,
"city": "Oakland",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": null,
"unlocode": "USOAK",
"timezone": "America/Los_Angeles",
"ref": "id-41584"
},
"details": [
{
"_object": "/ocean/railport",
"port_code": "2811"
},
{
"_object": "/trucking/port",
"port_code": "2811"
},
{
"_object": "/ocean/port",
"port_code": "2811"
}
]
},
"line_items": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 2,
"data": [
{
"metadata": {},
"_object": "/purchase_orders/line_item",
"id": 5137136,
"purchase_order": {
"_object": "/api/refs/object",
"ref_type": "/purchase_order",
"link": "https://api.flexport.com/purchase_orders/171997",
"id": 171997
},
"line_item_number": 1,
"item_key": "1",
"line_type": "main_line",
"parent_line_key": null,
"units": 500,
"unit_cost": {
"_object": "/money",
"amount": "4.65",
"currency_code": "USD"
},
"product": {
"_object": "purchase_orders/line_item_product",
"name": "Cool Product 123",
"sku": "sku123",
"color": "Black",
"country_of_origin": "CN",
"dangerous": false,
"ean_ucc_13": "1234567890123",
"ean_ucc_8": "12345678",
"lot_number": "146",
"product_category": "Tops",
"size": "Medium",
"style": "T1234",
"upc": "123456789012"
},
"incoterm": null,
"transportation_mode": null,
"unit_of_measure": "EA",
"must_arrive_date": null,
"cargo_ready_date": null,
"assigned_party": {
"_object": "/company_entity",
"id": 561911,
"name": "ARCCorp",
"mailing_address": {
"_object": "/address",
"street_address": "3551 Market St",
"street_address2": null,
"city": "Oakland",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94610",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": null
},
"ref": "HQ",
"vat_numbers": []
},
"origin_port": null,
"origin_address": {
"_object": "/address",
"street_address": "355 100 Foot Rd",
"street_address2": null,
"city": "Shenzhen",
"state": null,
"country": "China",
"country_code": "CN",
"zip": null,
"unlocode": null,
"timezone": "Asia/Shanghai",
"ref": "lex_corp_warehouse"
},
"destination_port": null,
"destination_addresses": [
{
"_object": "/purchase_orders/line_items/destination_address",
"units": 500,
"address": {
"_object": "/address",
"street_address": "353 Hollywood Ave",
"street_address2": "",
"city": "Los Angeles",
"state": "California",
"country": "United States",
"country_code": "US",
"zip": "90016",
"unlocode": "USLAX",
"timezone": "America/Los_Angeles",
"ref": "los_angeles"
}
}
],
"hs_codes": [
{
"_object": "/hs_code",
"description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted:: Of cotton: Singlets, all white, without pockets, trim or embroidery (352)",
"code": "6109.10.00.07",
"country_code": "US"
}
],
"measurements": [
{
"_object": "/line_item_measurement",
"measure_type": "net_weight",
"unit_of_measure": "KG",
"value": "0.14"
},
{
"_object": "/line_item_measurement",
"measure_type": "gross_weight",
"unit_of_measure": "KG",
"value": "0.16"
}
],
"booking_line_items": {
"_object": "/api/refs/collection",
"ref_type": "/purchase_orders/booking_line_item",
"link": "https://api.flexport.com/booking_line_items?f.purchase_order_line_item.id=5137136"
}
},
{
"metadata": {},
"_object": "/purchase_orders/line_item",
"id": 5137135,
"purchase_order": {
"_object": "/api/refs/object",
"ref_type": "/purchase_order",
"link": "https://api.flexport.com/purchase_orders/171997",
"id": 171997
},
"line_item_number": 2,
"item_key": "2",
"line_type": "main_line",
"parent_line_key": null,
"units": 3000,
"unit_cost": {
"_object": "/money",
"amount": "75.49",
"currency_code": "USD"
},
"product": {
"_object": "purchase_orders/line_item_product",
"name": "Winter Coat",
"sku": "65274389rhc20210616",
"color": null,
"country_of_origin": null,
"dangerous": null,
"ean_ucc_13": null,
"ean_ucc_8": null,
"lot_number": null,
"product_category": null,
"size": null,
"style": null,
"upc": null
},
"incoterm": null,
"transportation_mode": null,
"unit_of_measure": "EA",
"must_arrive_date": null,
"cargo_ready_date": null,
"assigned_party": {
"_object": "/company_entity",
"id": 561911,
"name": "ARCCorp",
"mailing_address": {
"_object": "/address",
"street_address": "3553 Market St",
"street_address2": null,
"city": "Oakland",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94610",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": null
},
"ref": "lexHQ",
"vat_numbers": []
},
"origin_port": null,
"origin_address": {
"_object": "/address",
"street_address": "100 Foot Rd",
"street_address2": null,
"city": "Shenzhen",
"state": null,
"country": "China",
"country_code": "CN",
"zip": null,
"unlocode": null,
"timezone": "Asia/Shanghai",
"ref": "lex_corp_warehouse"
},
"destination_port": null,
"destination_addresses": [
{
"_object": "/purchase_orders/line_items/destination_address",
"units": 1500,
"address": {
"_object": "/address",
"street_address": "3553 Hollywood Ave",
"street_address2": "",
"city": "Los Angeles",
"state": "California",
"country": "United States",
"country_code": "US",
"zip": "90016",
"unlocode": "USLAX",
"timezone": "America/Los_Angeles",
"ref": "los_angeles"
}
}
],
"hs_codes": [
{
"_object": "/hs_code",
"description": "Women's or girls' overcoats, carcoats, capes, and cloaks, anoraks (including ski-jackets), windbreakers and similar articles (including padded, sleeveless jackets), other than those of heading 6204:: Of wool or fine animal hair: Women's (435)",
"code": "6202.11.00.10",
"country_code": "US"
}
],
"measurements": [
{
"_object": "/line_item_measurement",
"measure_type": "gross_weight",
"unit_of_measure": "KG",
"value": "1.3"
}
],
"booking_line_items": {
"_object": "/api/refs/collection",
"ref_type": "/purchase_orders/booking_line_item",
"link": "https://api.flexport.com/booking_line_items?f.purchase_order_line_item.id=5137135"
}
}
]
},
"memo": "This is a PO with 2 lines going to a single Destination",
"status": "closed",
"archived_at": null,
"created_at": "2021-08-17T06:33:53.074Z",
"updated_at": "2021-08-17T11:08:58.450Z",
"freight_payment_terms": "freight_collect",
"destination_addresses": [
{
"_object": "/address",
"street_address": "3553 Hollywood Ave",
"street_address2": "",
"city": "Los Angeles",
"state": "California",
"country": "United States",
"country_code": "US",
"zip": "90016",
"unlocode": "USLAX",
"timezone": "America/Los_Angeles",
"ref": "los_angeles"
}
],
"issue_date": "2004-03-18",
"order_type": "Apparel",
"parties": [
{
"_object": "purchase_orders/party",
"role": "buyer",
"company_entity": {
"_object": "/company_entity",
"id": 529296,
"name": "PROSERVE Test Account",
"mailing_address": {
"_object": "/address",
"street_address": "455 Market Street",
"street_address2": "Suite 233",
"city": "San Francisco",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94102",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": null
},
"ref": "Main_Address",
"vat_numbers": [
{
"_object": "/company_entity/vat_number",
"country_code": "DE",
"number": "DE811949297"
}
]
},
"location_address": null,
"contacts": [
{
"_object": "purchase_orders/contact",
"name": "Luigi Smith",
"phone": "800-555-6614",
"email": "lsmith@buyer.com",
"fax": "800-555-5594",
"department": "Purchasing"
}
]
},
{
"_object": "purchase_orders/party",
"role": "seller",
"company_entity": {
"_object": "/company_entity",
"id": 561911,
"name": "ARCCorp",
"mailing_address": {
"_object": "/address",
"street_address": "3531 Market St",
"street_address2": null,
"city": "Oakland",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94610",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": null
},
"ref": "HQ",
"vat_numbers": []
},
"location_address": null,
"contacts": [
{
"_object": "purchase_orders/contact",
"name": "Jane Doe",
"phone": "800-555-2837",
"email": "jdoe@seller.com",
"fax": "800-555-6968",
"department": "Sales"
}
]
},
{
"_object": "purchase_orders/party",
"role": "owner",
"company_entity": {
"_object": "/company_entity",
"id": 529296,
"name": "PROSERVE Test Account",
"mailing_address": {
"_object": "/address",
"street_address": "353 Market Street",
"street_address2": "Suite 366",
"city": "San Francisco",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94102",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": null
},
"ref": "Main_Address",
"vat_numbers": [
{
"_object": "/company_entity/vat_number",
"country_code": "DE",
"number": "DE811949297"
}
]
},
"location_address": null,
"contacts": [
{
"_object": "purchase_orders/contact",
"name": "Luigi Smith",
"phone": "800-555-6614",
"email": "lsmith@buyer.com",
"fax": "800-555-5594",
"department": "Purchasing"
}
]
},
{
"_object": "purchase_orders/party",
"role": "manufacturer",
"company_entity": {
"_object": "/company_entity",
"id": 561911,
"name": "ARCCorp",
"mailing_address": {
"_object": "/address",
"street_address": "355 Market St",
"street_address2": null,
"city": "Oakland",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94610",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": null
},
"ref": "HQ",
"vat_numbers": []
},
"location_address": null,
"contacts": [
{
"_object": "purchase_orders/contact",
"name": "Pete Stanton",
"phone": "800-555-5829",
"email": "pstanton@seller.com",
"fax": "800-555-6968",
"department": "Manufacturing"
}
]
}
],
"priority": "standard"
}
]
},
"error": null
}
You can update nearly all parameters in a PO. Beware though, all fields passed replace any and all existing information for that PO. Flexport considers an order amendment as a full-replace HTTP POST request.
This has several implications:
- Any data passed for any parameter will replace that parameter’s original value.
- Any parameter that is not included in JSON will be assigned a null value. If that parameter had a non-null value prior to the call, the value will now be null.
Using an HTTP POST request, you must pass the name of the PO and any name-value pairs, or objects, which you’d like to update. One caveat to remember: the name, buyer_reference and seller_reference must be the same values used to create the order. A new order will be created if they’re not.
You may be building an app which presents a group of purchase orders to end users. You’ll probably want to list those POs in tabular fashion. You’re in luck because we’ve got an API and endpoints for that!
The purchase order API includes a specific endpoint for retrieving all POs, List all purchase orders. Even better, you can filter which POs to list by passing certain filtering values.
Here’s a cURL example which will get all POs:
curl -X "GET" "https://api.flexport.com/purchase_orders" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Accept: application/json" \
This will provide you with a list of up to 20 POs (the default) which you are entitled to retrieve (in the form of a JSON object). Let’s take a look at using filters to narrow our search.
You can filter the response on the parameters mentioned in the reference document.
Let’s looks at just one example using filtering, limiting and sorting:
curl -X "GET" "https://api.flexport.com/purchase_orders?page=1&per=10&f.status=ope" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Accept: application/json" \
The response will only include purchase orders from the first page (page=1) returned orders, up to a maximum of 10 orders (per=10) , and only those whose status is open.
Feel free to try other combinations of parameters and filters to better understand the options available to you.
On occasion, things don’t always proceed as you expect. Naturally, various HTTP error codes, along with an exception JSON object, are returned to help you build your exception handling routines. An example of an Error Response is shown below.
{
"_object": "/api/error",
"status": 400,
"code": "invalid_pagination",
"message": "Invalid Sort Direction. allowed values: desc, asc"
}
You’ll want to use the status and message fields to handle exceptions. Let’s take a look at possible values in those fields.
A status value of 422 typically denotes a logical error found in the JSON message included in your request. Here are some error messages you may receive, and actions to help you resolve those issues.
- Purchase order xxxxx may not be cancelled since it has an active booking: A purchase order was partially or completely booked but the value of
statuswas Cancelled in your JSON. The request failed because the purchase order is part of an active booking. Revise yourstatusvalue and re-post the request. - Cannot remove line items that have been booked: You attempted to remove PO line item(s) that has already been booked. Make sure that you don’t try to remove booked line items from your PO.
- Cannot update a line item to request fewer units than have already been booked: You created a purchase order indicating an original quantity; the PO was completely booked using that quantity; you then posted the same PO a second time in which the requested quantity was less than the booked quantity. You can only change the quantity from the originally booked quantity if the new quantity is higher than the original request.
- Company does not exist for reference ...: The network setup is not up to date with supplier/destination warehouse data. Contact Customer Service for the supplier/destination warehouse setup information including reference ID.
- Purchase Order xxxxx has multiple line items with same item key: You sent multiple line items with the same key. Resubmit the purchase order with unique line item keys.
- ...location_ref requires: Note that a location_ref may refer to one of several different location references: an
origin location reference, aseller location reference, or adestination location reference. You might have received this error message when you had booked a purchase order:- Against an unknown seller or destination location
- Without all required information
- Using multiple location references for the same seller/origin/destination location
Contact Customer Service to confirm the addition of a new location reference.
- ...Must arrive date: The transmitted purchase order’s must_arrive_by date is set to a date prior to the creation date. Correct the must_arrive_by date and re-post the request.
- ...not a valid Purchase Order Status: You sent an invalid value in the
statusfield of your request. Valid values are open, closed, and cancelled. Correct the value in thestatusfield and re-post the request. - ...product_name cannot be empty for a new product...: You’ll need to include a name for your purchase order. Correct the name field and try re-posting the request. If the name field in your request did indeed have a value, contact Customer Service to add the product name and SKU.
- ...product_sku must be specified...: You’ll need to include a value in the SKU field in your request. Try adding a value in the SKU field and re-post the request.
- Unknown unit of measure: As the message states, you included an invalid value in the
unit_of_measurefield. Try correcting the value and re-post your request. - ...invalid transportation mode...: The value for
invalid transportation modein your request wasn’t valid. Try correcting the value and re-post your request. - ...Invalid incoterm...: The request contained an invalude value for the
incotermsfield. Try correcting the value and re-post your request. - You must specify at least one line item under po_line_items: Your request has to contain at least one line item. Add a line item and re-post your request.
- ...can not change the seller role...: Your request was originally sent with a particular entity listed as the seller. When you attempted to update the purchase order, that entity was mistakenly changed to the buyer instead. Try correcting this and repost your request.
A status value of either 503 or 504 indicates the service is unavailable, or a gateway time out, respectively. The message returned will be either:
- Error 503: Error message received from Http Server, Code 503: Service Unavailable.
- Error message received from Http Server, Code 504: Gateway Time-out.
These occur when our server is down. Allow a period of time to pass and re-post the request.
We have developed webhooks so you can get instant updates on your purchase orders. The Flexport PO webhooks are available at its endpoint of: https://apidocs.flexport.com/v3/tag/Milestones#section/PurchaseOrder-Events. To integrate with our webhooks, follow these steps
- Create a webhook in https://app.flexport.com/account_settings/webhooks, make sure to select the “Order Management” checkbox.
- For all PO webhooks, the payload contains two fields,
contextandpurchase_order. a.contextfield includes metadata that is unique to each webhook event. Thecontext.purchase_order_version_idfield is the PO version id when the event occurred, which can be used to retrieve the PO snapshot through our public API b.purchase_orderfield is the header-level information of a purchase order.
Here’s a sample of the /purchase_order#acknowledged webhook payload
{
body: "2023-03-27T17:03:54.151Z",
data: {
_object: "/order_management_event_data",
context: {
_object: "/order_management_event_data/acknowledged_context",
purchase_order_version_id: 123,
},
purchase_order: {
_object: "/purchase_order",
...
}
}
}