PurchaseOrder

Endpoints relating to PurchaseOrder objects. The Purchase Order endpoints need special permission to access. Please contact your Flexport Sales representative if you are interested in using these endpoints.

List all purchase orders

Returns a list of purchase orders

Request
query Parameters
page
integer >= 1
Default: 1

Page number of the page to retrieve

Example: page=1
per
integer [ 1 .. 100 ]
Default: 20

Count of items in each page Should be between 1 and 100 (inclusive)

Example: per=20
sort
string
Default: "id"

Sort results by the specified field (only id is supported at this time)

Value: "id"
direction
string
Default: "asc"

Set sort order. Allows "asc"(ascending) or "desc" (descending)

Enum: "asc" "desc"
f.archived_at.exists
boolean

Filter out all archived purchase orders (f.archived_at.exists=false) or filter out all unarchived purchase orders (f.archived_at.exists=true)

f.status
string

Filters the list based on the PO status

Enum: "open" "closed" "cancelled"
f.buyer_ref
string

Filters the list based on PO buyer

Example: f.buyer_ref=amazon-us
f.seller_ref
string

Filters the list based on the PO seller

Example: f.seller_ref=amazon-us
f.seller_entity_ref
string

Filters the list based on the PO seller entity

Example: f.seller_entity_ref=id-12345
f.buyer_entity_ref
string

Filters the list based on the PO buyer entity

Example: f.buyer_entity_ref=id-54321
f.roles
Array of strings

Filters the list based on which role you take in the PO. You can state multiple roles with a comma.

Items Enum: "buyer" "seller" "owner" "shipper" "consignee" "freight_forwarder" "notify_party" "customs_broker" "carrier" "manufacturer" "buyers_agent" "sellers_agent"
Example: f.roles=buyer,carrier,shipper
f.shipment.id
integer

Filter the list based on whether a PO is on the shipment matching the provided ID

Example: f.shipment.id=123456
f.name
string

Filter the list based on PO name

Example: f.name=PO-123456
f.updated_at.lt
string

Filter the list for POs last updated before the provided time

Example: f.updated_at.lt=2022-01-01 18:26:37 PST
f.updated_at.gt
string

Filter the list for POs last updated after the provided time

Example: f.updated_at.gt=2022-01-01 18:26:37 PST
f.created_at.lt
string

Filter the list for POs created before the provided time

Example: f.created_at.lt=2023-01-01 04:52:36 PST
f.created_at.gt
string

Filter the list for POs created after the provided time

Example: f.created_at.gt=2023-01-01 04:52:36 PST
Responses
200

collection of purchase orders

Response Schema: application/json
_object
string
self
string
version
integer
object
_object
string
prev
string
next
string
Array of objects (PurchaseOrder)
400

error

get/purchase_orders
Response samples
application/json

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/purchase_orders?page=13&per=10",
  • "version": 3,
  • "data": {
    • "_object": "/api/collections/paginated",
    • "prev": "https://api.flexport.com/purchase_orders?page=12&per=10",
    • "next": null,
    • "data": [
      • {
        }
      ]
    }
}

Create and return a purchase order

Create and return a purchase order. If the purchase order already exists, update action is performed.

Errors

When a request fails validation, the API returns a 400 with an error object. error.code is invalid_param for malformed/invalid input or bad_request for business-rule violations, and error.message describes the specific problem. The table below lists the errors you may encounter, their cause, and how to resolve them.

Error message Code Cause Suggested fix
company entity ref <ref> does not exist invalid_param A party (buyer/seller) references a company entity ref that is not in your network. Use a party company entity ref that exists in your Network.
Cannot update a line item to request fewer units than have already been booked (line item <key>) bad_request The request reduces a line item's units below the quantity already booked against it. Do not reduce a line item's units below what has already been booked.
Missing property <field> (e.g. name) invalid_param A required field is absent from the request body. Include all required fields in the request.
Invalid enum value provided for: incoterm invalid_param The incoterm is not one of the accepted values. Use a valid incoterm (EXW, FOB, FAS, FCA, CPT, CFR, CIF, CIP, DAT, DAP, DDP, DPU).
Cannot remove line items that have been booked, missing item key: <key> bad_request The request omits a line item that already has bookings against it. Keep booked line items in the request; they cannot be removed.
<location> Location ref <ref> does not exist invalid_param An origin/destination location ref is not a valid location in your network. Use a location ref that exists in your Network.
Must arrive date <date> must be after Cargo Ready Date <date> on line item <key> bad_request A line item's must-arrive date is earlier than its cargo-ready date. Set must_arrive_date later than cargo_ready_date.
Request
Request Body schema: application/json
required
name
required
string

Always required. Name of the purchase order.

memo
string

Your notes or instructions on this purchase order.

user_email
string

Email of the user that the purchase order should be attributed to as creator/updater. The user must belong to your company. If omitted, it defaults to your company's admin.

status
string
Default: "open"

The status of the purchase order. Open POs denote POs that are ready to be booked. Closed POs are ones that you'd like to mark as done (typically because they've finished shipping), while Cancelled POs denote POs that were mistakenly uploaded or that should not be used

Enum: "open" "cancelled" "closed"
external_system_unique_id
string

A stable identifier for this purchase order from your external system (e.g. ERP or TMS). Recommended format: "{system_name}|{account_id}|{external_po_id}", for example "MYERP|12345|PO-67890". Required when using buyer_candidate or seller_candidate — this can be used as the lookup key for subsequent updates when buyer/seller entity IDs are not yet resolved.

object

Free-form buyer identity to use when no buyer party is provided in the parties array. Mutually exclusive with providing a buyer entry in parties. When provided, Flexport will attempt to match this to a known company entity. If unresolved immediately, the match will be completed asynchronously. Requires external_system_unique_id to be set.

legal_name
string

The legal name of the buyer company.

object

Free-form seller identity to use when no seller party is provided in the parties array. Mutually exclusive with providing a seller entry in parties. When provided, Flexport will attempt to match this to a known company entity. If unresolved immediately, the match will be completed asynchronously. Requires external_system_unique_id to be set.

legal_name
string

The legal name of the seller company.

Array of objects

Free-form destination addresses to use when destination location refs are not available. When provided, Flexport will attempt to match each address to a known location. Processed only after both buyer and seller are resolved. If either party is pending async resolution (via buyer_candidate/seller_candidate), destination location matching will also be completed asynchronously once both parties are known.

Array
street_address
string
street_address2
string
city
string
state
string
postal_code
string
country_code
string
required
Array of objects (CreateParty)

A list of the parties in this purchase order. Seller is required unless seller_candidate is provided. If the buyer is not specified, the primary entity of the company calling will be assumed to be the buyer. Owner is the owner of this order and will default to the buyer if not specified.

Array
role
required
string

The role that the party has

Enum: "buyer" "seller" "owner" "shipper" "consignee" "freight_forwarder" "notify_party" "customs_broker" "carrier" "manufacturer" "buyers_agent" "sellers_agent"
external_ref
required
string

The external ref of the company entity that you wish to tie to this party

location_ref
string

The external ref of the location that you wish to tie to this party. This should be the address that would be associated with the party at the top of a purchase order document. Used for order delivery to suppliers, not in the booking process.

Array of objects

A list of contact data for who should be contacted should there be questions about this order. For example, if your supplier needs to contact someone, who should they contact?

currency_code
string

Required if there is no currency_code in each line item. The currency code being used in this purchase order.

object (CreatePurchaseOrderPort)

The origin port

code
required
string

A unique identifier for this port

code_type
required
string

The code type of the port

Enum: "unlocode" "iata" "icao" "us_cbp"
object (CreatePurchaseOrderPort)

The destination port

code
required
string

A unique identifier for this port

code_type
required
string

The code type of the port

Enum: "unlocode" "iata" "icao" "us_cbp"
must_arrive_date
string <date>

The must arrive date for this purchase order.

issue_date
string <date>

The issue date for this purchase order.

freight_payment_terms
string

The freight payment term for the purchase order

Enum: "freight_collect" "freight_prepaid"
cargo_ready_date
string <date>

Date when cargo is ready for pickup at the origin location.

transportation_mode
string
Enum: "air" "ocean" "truck" "rail"
incoterm
string

The incoterm of your purchase order.

Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP"
origin_location_ref
string

Customizable reference ID of the network location that is the origin location.

destination_location_refs
Array of strings

Reference ID of the network locations that are the destination locations. Multiple values are allowed, which would signify that this order is going to be shipped to multiple locations.

priority
string
Default: "standard"

priority of the purchase order.

Enum: "high" "standard"
order_class
string
Default: "purchase_order"

Class of the purchase order.

Enum: "purchase_order" "sales_order" "transfer_order" "delivery_order" "work_order"
order_type
string

Type of purchase order, which is used for rules, searching, and reporting

required
Array of objects (CreateLineItem)

A list of the line items in this purchase order

Array
item_key
required
string

Value uniquely identifying a line item within a Purchase Order.

line_item_number
integer

Integer used to sequence the order of line items. Line items will appear in the UX in this order. Assigned automatically if not provided

required
object (CreatePurchaseOrderProduct)
object (CreatePurchaseOrderPort)

Optional. The origin port

object (CreatePurchaseOrderPort)

Optional. The destination port

must_arrive_date
string <date>

The must arrive date for this purchase order.

cargo_ready_date
string <date>

Date when cargo is ready for pickup at the origin location.

transportation_mode
string
Enum: "air" "ocean" "truck" "rail"
incoterm
string

The Incoterm of your line item.

Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP"
origin_location_ref
string

Optional. Customizable reference ID of network location that is the origin location.

Array of objects (CreateLineItemDestinationLocation)

List of destinations locations for this line item and the number of units to be sent

units
required
integer

Always required. The number of units for this line item.

object (MoneyCreate)

The cost and currency per unit for this line item

Array of objects (CreatePurchaseOrderHsCode)
Default: []

A list of the hs codes in this line item

line_type
string
Default: "main_line"

type of the line item

Enum: "main_line" "sub_line" "component_line"
Array of objects (CreateLineItemMeasurement)

Measurements for the unit of measure provided on the line item. For example, if the unit of measure on the line is barrels, these are the measurements for a barrel

unit_of_measure
string
Default: "EA"

The measurement per unit for this line item.

Enum: "BBL" "CAR" "CGM" "CKG" "CM" "CM2" "CTN" "CYK" "DOZ" "DPC" "DPR" "DS" "FBM" "G" "GBQ" "GR" "GRL" "HUN" "IRG" "JWL" "K" "KG" "KM3" "KM" "KWH" "L" "LNM" "M" "M2" "M3" "MBQ" "NO" "OSG" "PCS" "PDG" "PFL" "PK" "PRS" "PTG" "PX" "RHG" "RUG" "T" "TDWB" "THS" "W" "X" "20" "21" "2W" "43" "AS" "BA" "BC" "BD" "BG" "BJ" "BK" "BN" "BO" "BU" "BX" "CA" "CB" "CC" "CF" "CG" "CI" "CN" "CP" "CQ" "CR" "CS" "CT" "CX" "CY" "DF" "DH" "DIS" "DR" "DZ" "EA" "FT" "GA" "GRAM" "GS" "IN" "JO" "JR" "LB" "LF" "LT" "MM" "MP" "MR" "MT" "OZ" "PC" "PQ" "PR" "PS" "PT" "QT" "RA" "RL" "RM" "RO" "SC" "SF" "SH" "SI" "SJ" "SL" "SM" "SO" "SQ" "ST" "SV" "SX" "SY" "TE" "TN" "TO" "UN" "YD" "Z3"
parent_line_key
string

The line_item_key of the parent line item. This can not be set if this line item is a main line item.

assigned_party_ref
string

The party that this line item is assigned to. Useful if assigning line items to different factories under a vendor, for example.

object or Array of objects (MetadataCreate)
object or Array of objects (MetadataCreate)
One of:

Metadata has two allowed formats. Either array format or object format. Refer to the metadata section in this documentation for more information.

example_key
Array of strings
Responses
200

The created purchase order

Response Schema: application/json
id
integer

A unique identifier for the purchase order

_object
string

Type of the object

name
string

The name of the purchase order

status
string
Default: "open"

The status of the purchase order. Open POs denote POs that are ready to be booked. Closed POs are ones that you'd like to mark as done (typically because they've finished shipping), while Cancelled POs denote POs that were mistakenly uploaded or that should not be used.

Enum: "open" "closed" "cancelled"
incoterm
string
Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
order_type
string

Type of purchase order, which is used for rules, searching, and reporting

order_class
string

Class of the purchase order.

Enum: "purchase_order" "sales_order" "transfer_order" "delivery_order" "work_order"
issue_date
string <date>

the date that the order was issued

freight_paymnet_terms
string
Enum: "freight_collect" "freight_prepaid"
priority
string
Enum: "standard" "high"
transportation_mode
string (TransportationMode)
Enum: "ocean" "air" "barge" "truck" "rail" "unknown_transportation" "ocean_air" "truck_intl" "warehouse_storage"
cargo_ready_date
string <date>
must_arrive_date
string <date>
object or null (Place)
_object
string

Type of the object

name
string

Name of the place

object (Address)
Array of Airport (object) or Placeport (object) or Manufacturer (object)
object (Address)
_object
string

Type of the object

street_address
string
street_address2
string or null
city
string
state
string or null
country
string
country_code
string
zip
string or null
timezone
string
ref
string
unlocode
string or null
object or null (Place)
_object
string

Type of the object

name
string

Name of the place

object (Address)
Array of Airport (object) or Placeport (object) or Manufacturer (object)
Array of objects (Address)
Array
_object
string

Type of the object

street_address
string
street_address2
string or null
city
string
state
string or null
country
string
country_code
string
zip
string or null
timezone
string
ref
string
unlocode
string or null
Array of objects (Parties)

A list of the parties in this purchase order. Buyer, Seller and Owner parties will always be returned.

Array
role
string

The role that the party has

Enum: "buyer" "seller" "owner" "shipper" "consignee" "freight_forwarder" "notify_party" "customs_broker" "carrier" "manufacturer" "buyers_agent" "sellers_agent"
object (CompanyEntity)
object (Address)

The object of the location that is tied to this party. This should be the address that would be associated with the party at the top of a purchase order document. Used for order delivery to suppliers, not in the booking process.

Array of objects

A list of contact data for who should be contacted should there be questions about this order. For example, if your supplier needs to contact someone, who should they contact?

memo
string
archived_at
string <date_time>
created_at
string <date_time>
updated_at
string <date_time>
object (PurchaseOrderLineItemCollectionRef)
_object
string

Type of the object

ref_type
string

Type of the object in this list

link
string

URL to fetch list of objects

metadata
object (Metadata)

Set of custom key-values specific to the object. The keys are strings and values are arrays of strings. The set of valid keys is always the consignee's list of keys, even if call was made by a different party.

400

error

post/purchase_orders
Request samples
application/json
{
  • "name": "PO 123",
  • "memo": "memo",
  • "status": "open",
  • "order_type": "Apparel",
  • "order_class": "purchase_order",
  • "parties": [
    • {
      • "role": "buyer",
      • "external_ref": "id-1232",
      • "contacts": [
        ],
      • "location_ref": "id-1232"
      },
    • {
      • "role": "seller",
      • "external_ref": "id-321",
      • "contacts": [
        ],
      • "location_ref": "id-432"
      }
    ],
  • "currency_code": "USD",
  • "origin_port": {
    • "code": "USFBN",
    • "code_type": "unlocode"
    },
  • "destination_port": {
    • "code": "USFBN",
    • "code_type": "unlocode"
    },
  • "cargo_ready_date": "2019-06-30",
  • "issue_date": "2019-06-30",
  • "freight_payment_terms": "freight_collect",
  • "must_arrive_date": "2019-07-31",
  • "priority": "standard",
  • "transportation_mode": "ocean",
  • "incoterm": "FOB",
  • "origin_location_ref": "id-123456",
  • "destination_location_refs": [
    • "id-654321",
    • "id-654322"
    ],
  • "line_items": [
    • {
      • "item_key": "item_key_1",
      • "line_item_number": 1,
      • "assigned_party_ref": "id-12355",
      • "product": {
        },
      • "origin_port": {
        },
      • "destination_port": {
        },
      • "cargo_ready_date": "2019-06-30",
      • "must_arrive_date": "2019-07-31",
      • "transportation_mode": "ocean",
      • "incoterm": "FOB",
      • "origin_location_ref": "id-123456",
      • "destination_locations": [
        ],
      • "measurements": [
        ],
      • "units": 10,
      • "unit_cost": {
        },
      • "hs_codes": [
        ],
      • "metadata": {
        }
      }
    ]
}
Response samples
application/json
{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/purchase_orders",
  • "version": 3,
  • "data": {
    • "metadata": {
      • "size": [
        ]
      },
    • "_object": "/purchase_order",
    • "id": 109771,
    • "name": "PO 123",
    • "incoterm": "FOB",
    • "transportation_mode": "ocean",
    • "cargo_ready_date": "2019-06-30",
    • "must_arrive_date": "2019-07-31",
    • "origin_port": {
      • "_object": "/place",
      • "name": "Fairburn",
      • "address": {
        },
      • "details": [
        ]
      },
    • "origin_address": {
      • "_object": "/address",
      • "street_address": "No 1, 123 St",
      • "street_address2": null,
      • "city": "Shenzhen",
      • "state": "Beijing",
      • "country": "China",
      • "country_code": "CN",
      • "zip": null,
      • "unlocode": null,
      • "timezone": "Asia/Shanghai",
      • "ref": "id-274346"
      },
    • "destination_port": {
      • "_object": "/place",
      • "name": "Fairburn",
      • "address": {
        },
      • "details": [
        ]
      },
    • "destination_addresses": [
      • {
        }
      ],
    • "line_items": {},
    • "parties": [
      • {
        },
      • {
        },
      • {
        }
      ],
    • "memo": "memo",
    • "status": "open",
    • "archived_at": null,
    • "created_at": "2020-07-31T19:52:58.140Z",
    • "updated_at": "2020-07-31T19:52:58.161Z",
    • "priority": "standard",
    • "order_type": "Apparel",
    • "issue_date": "2019-06-30",
    • "freight_payment_terms": "freight_collect"
    },
  • "error": null
}

Retrieve a purchase order

Retrieves the details of a single purchase order.

Request
path Parameters
id
required
integer

The unique id for the purchase order to be retrieved

query Parameters
f.purchase_order_version.id
integer

The id of the version of a purchase order. By default, the latest version of the purchase order is used.

Responses
200

Success

Response Schema: application/json
_object
string
self
string
version
integer
object (PurchaseOrder)
id
integer

A unique identifier for the purchase order

_object
string

Type of the object

name
string

The name of the purchase order

status
string
Default: "open"

The status of the purchase order. Open POs denote POs that are ready to be booked. Closed POs are ones that you'd like to mark as done (typically because they've finished shipping), while Cancelled POs denote POs that were mistakenly uploaded or that should not be used.

Enum: "open" "closed" "cancelled"
incoterm
string
Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
order_type
string

Type of purchase order, which is used for rules, searching, and reporting

order_class
string

Class of the purchase order.

Enum: "purchase_order" "sales_order" "transfer_order" "delivery_order" "work_order"
issue_date
string <date>

the date that the order was issued

freight_paymnet_terms
string
Enum: "freight_collect" "freight_prepaid"
priority
string
Enum: "standard" "high"
transportation_mode
string (TransportationMode)
Enum: "ocean" "air" "barge" "truck" "rail" "unknown_transportation" "ocean_air" "truck_intl" "warehouse_storage"
cargo_ready_date
string <date>
must_arrive_date
string <date>
object or null (Place)
object (Address)
object or null (Place)
Array of objects (Address)
Array of objects (Parties)

A list of the parties in this purchase order. Buyer, Seller and Owner parties will always be returned.

memo
string
archived_at
string <date_time>
created_at
string <date_time>
updated_at
string <date_time>
object (PurchaseOrderLineItemCollectionRef)
metadata
object (Metadata)

Set of custom key-values specific to the object. The keys are strings and values are arrays of strings. The set of valid keys is always the consignee's list of keys, even if call was made by a different party.

400

error

get/purchase_orders/{id}
Response samples
application/json

Success

{
  • "_object": "/purchase_order",
  • "id": 109771,
  • "name": "PO 123",
  • "incoterm": "FOB",
  • "transportation_mode": "ocean",
  • "cargo_ready_date": "2019-06-30",
  • "must_arrive_date": "2019-07-31",
  • "origin_port": {
    • "_object": "/place",
    • "name": "Fairburn",
    • "address": {
      • "_object": "/address",
      • "street_address": null,
      • "street_address2": null,
      • "city": "Fairburn",
      • "state": "GA",
      • "country": "United States",
      • "country_code": "US",
      • "zip": null,
      • "unlocode": "USFBN",
      • "timezone": "America/New_York",
      • "ref": "id-313120"
      },
    • "details": [
      • {
        },
      • {
        },
      • {
        }
      ]
    },
  • "origin_address": {
    • "_object": "/address",
    • "street_address": "No 1, 123 St",
    • "street_address2": null,
    • "city": "Shenzhen",
    • "state": "Beijing",
    • "country": "China",
    • "country_code": "CN",
    • "zip": null,
    • "unlocode": null,
    • "timezone": "Asia/Shanghai",
    • "ref": "id-274346"
    },
  • "destination_port": {
    • "_object": "/place",
    • "name": "Fairburn",
    • "address": {
      • "_object": "/address",
      • "street_address": null,
      • "street_address2": null,
      • "city": "Fairburn",
      • "state": "GA",
      • "country": "United States",
      • "country_code": "US",
      • "zip": null,
      • "unlocode": "USFBN",
      • "timezone": "America/New_York",
      • "ref": "id-313120"
      },
    • "details": [
      • {
        },
      • {
        },
      • {
        }
      ]
    },
  • "destination_addresses": [
    • {
      • "_object": "/address",
      • "street_address": "Vandelay street 1",
      • "street_address2": null,
      • "city": "Duisburg",
      • "state": "North Rhine Westphalia",
      • "country": "Germany",
      • "country_code": "DE",
      • "zip": "56776",
      • "unlocode": null,
      • "timezone": "Europe/Berlin",
      • "ref": "id-318238"
      }
    ],
  • "line_items": {},
  • "parties": [
    • {
      • "_object": "purchase_orders/party",
      • "role": "buyer",
      • "company_entity": {
        },
      • "location_address": null,
      • "contacts": [ ]
      },
    • {
      • "_object": "purchase_orders/party",
      • "role": "seller",
      • "company_entity": {
        },
      • "location_address": {
        },
      • "contacts": [
        ]
      },
    • {
      • "_object": "purchase_orders/party",
      • "role": "owner",
      • "company_entity": {
        },
      • "location_address": null,
      • "contacts": [
        ]
      }
    ],
  • "memo": "memo",
  • "status": "open",
  • "archived_at": null,
  • "created_at": "2020-07-31T19:52:58.140Z",
  • "updated_at": "2020-07-31T19:52:58.161Z",
  • "priority": "standard",
  • "order_type": "Apparel",
  • "issue_date": "2019-06-30",
  • "freight_payment_terms": "freight_collect",
  • "metadata": {
    • "size": [
      • "M"
      ]
    }
}

Update and return a purchase order

Update and return a purchase order.

Errors

When a request fails validation, the API returns a 400 with an error object. error.code is invalid_param for malformed/invalid input or bad_request for business-rule violations, and error.message describes the specific problem. The table below lists the errors you may encounter, their cause, and how to resolve them.

Error message Code Cause Suggested fix
Cannot update a line item to request fewer units than have already been booked (line item <key>) bad_request The request reduces a line item's units below the quantity already booked against it. Do not reduce a line item's units below what has already been booked.
Missing property <field> (e.g. name) invalid_param A required field is absent from the request body. Include all required fields in the request.
Cannot update name and involved parties of purchase orders bad_request The request attempts to change the name or involved parties of an existing purchase order. Name and involved parties cannot be changed on an existing PO; omit those changes.
Must arrive date <date> must be after Cargo Ready Date <date> on line item <key> bad_request A line item's must-arrive date is earlier than its cargo-ready date. Set must_arrive_date later than cargo_ready_date.
Cannot remove line items that have been booked, missing item key: <key> bad_request The request omits a line item that already has bookings against it. Keep booked line items in the request; they cannot be removed.
Request
path Parameters
id
required
integer

The unique id for the purchase order to be updated

Request Body schema: application/json
required
name
required
string

Always required. Name of the purchase order.

memo
string

Your notes or instructions on this purchase order.

user_email
string

Email of the user that the purchase order should be attributed to as creator/updater. The user must belong to your company. If omitted, it defaults to your company's admin.

status
string
Default: "open"

The status of the purchase order. Open POs denote POs that are ready to be booked. Closed POs are ones that you'd like to mark as done (typically because they've finished shipping), while Cancelled POs denote POs that were mistakenly uploaded or that should not be used

Enum: "open" "cancelled" "closed"
external_system_unique_id
string

A stable identifier for this purchase order from your external system (e.g. ERP or TMS). Recommended format: "{system_name}|{account_id}|{external_po_id}", for example "MYERP|12345|PO-67890". Required when using buyer_candidate or seller_candidate — this can be used as the lookup key for subsequent updates when buyer/seller entity IDs are not yet resolved.

object

Free-form buyer identity to use when no buyer party is provided in the parties array. Mutually exclusive with providing a buyer entry in parties. When provided, Flexport will attempt to match this to a known company entity. If unresolved immediately, the match will be completed asynchronously. Requires external_system_unique_id to be set.

legal_name
string

The legal name of the buyer company.

object

Free-form seller identity to use when no seller party is provided in the parties array. Mutually exclusive with providing a seller entry in parties. When provided, Flexport will attempt to match this to a known company entity. If unresolved immediately, the match will be completed asynchronously. Requires external_system_unique_id to be set.

legal_name
string

The legal name of the seller company.

Array of objects

Free-form destination addresses to use when destination location refs are not available. When provided, Flexport will attempt to match each address to a known location. Processed only after both buyer and seller are resolved. If either party is pending async resolution (via buyer_candidate/seller_candidate), destination location matching will also be completed asynchronously once both parties are known.

Array
street_address
string
street_address2
string
city
string
state
string
postal_code
string
country_code
string
required
Array of objects (CreateParty)

A list of the parties in this purchase order. Seller is required unless seller_candidate is provided. If the buyer is not specified, the primary entity of the company calling will be assumed to be the buyer. Owner is the owner of this order and will default to the buyer if not specified.

Array
role
required
string

The role that the party has

Enum: "buyer" "seller" "owner" "shipper" "consignee" "freight_forwarder" "notify_party" "customs_broker" "carrier" "manufacturer" "buyers_agent" "sellers_agent"
external_ref
required
string

The external ref of the company entity that you wish to tie to this party

location_ref
string

The external ref of the location that you wish to tie to this party. This should be the address that would be associated with the party at the top of a purchase order document. Used for order delivery to suppliers, not in the booking process.

Array of objects

A list of contact data for who should be contacted should there be questions about this order. For example, if your supplier needs to contact someone, who should they contact?

currency_code
string

Required if there is no currency_code in each line item. The currency code being used in this purchase order.

object (CreatePurchaseOrderPort)

The origin port

code
required
string

A unique identifier for this port

code_type
required
string

The code type of the port

Enum: "unlocode" "iata" "icao" "us_cbp"
object (CreatePurchaseOrderPort)

The destination port

code
required
string

A unique identifier for this port

code_type
required
string

The code type of the port

Enum: "unlocode" "iata" "icao" "us_cbp"
must_arrive_date
string <date>

The must arrive date for this purchase order.

issue_date
string <date>

The issue date for this purchase order.

freight_payment_terms
string

The freight payment term for the purchase order

Enum: "freight_collect" "freight_prepaid"
cargo_ready_date
string <date>

Date when cargo is ready for pickup at the origin location.

transportation_mode
string
Enum: "air" "ocean" "truck" "rail"
incoterm
string

The incoterm of your purchase order.

Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP"
origin_location_ref
string

Customizable reference ID of the network location that is the origin location.

destination_location_refs
Array of strings

Reference ID of the network locations that are the destination locations. Multiple values are allowed, which would signify that this order is going to be shipped to multiple locations.

priority
string
Default: "standard"

priority of the purchase order.

Enum: "high" "standard"
order_class
string
Default: "purchase_order"

Class of the purchase order.

Enum: "purchase_order" "sales_order" "transfer_order" "delivery_order" "work_order"
order_type
string

Type of purchase order, which is used for rules, searching, and reporting

required
Array of objects (CreateLineItem)

A list of the line items in this purchase order

Array
item_key
required
string

Value uniquely identifying a line item within a Purchase Order.

line_item_number
integer

Integer used to sequence the order of line items. Line items will appear in the UX in this order. Assigned automatically if not provided

required
object (CreatePurchaseOrderProduct)
object (CreatePurchaseOrderPort)

Optional. The origin port

object (CreatePurchaseOrderPort)

Optional. The destination port

must_arrive_date
string <date>

The must arrive date for this purchase order.

cargo_ready_date
string <date>

Date when cargo is ready for pickup at the origin location.

transportation_mode
string
Enum: "air" "ocean" "truck" "rail"
incoterm
string

The Incoterm of your line item.

Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP"
origin_location_ref
string

Optional. Customizable reference ID of network location that is the origin location.

Array of objects (CreateLineItemDestinationLocation)

List of destinations locations for this line item and the number of units to be sent

units
required
integer

Always required. The number of units for this line item.

object (MoneyCreate)

The cost and currency per unit for this line item

Array of objects (CreatePurchaseOrderHsCode)
Default: []

A list of the hs codes in this line item

line_type
string
Default: "main_line"

type of the line item

Enum: "main_line" "sub_line" "component_line"
Array of objects (CreateLineItemMeasurement)

Measurements for the unit of measure provided on the line item. For example, if the unit of measure on the line is barrels, these are the measurements for a barrel

unit_of_measure
string
Default: "EA"

The measurement per unit for this line item.

Enum: "BBL" "CAR" "CGM" "CKG" "CM" "CM2" "CTN" "CYK" "DOZ" "DPC" "DPR" "DS" "FBM" "G" "GBQ" "GR" "GRL" "HUN" "IRG" "JWL" "K" "KG" "KM3" "KM" "KWH" "L" "LNM" "M" "M2" "M3" "MBQ" "NO" "OSG" "PCS" "PDG" "PFL" "PK" "PRS" "PTG" "PX" "RHG" "RUG" "T" "TDWB" "THS" "W" "X" "20" "21" "2W" "43" "AS" "BA" "BC" "BD" "BG" "BJ" "BK" "BN" "BO" "BU" "BX" "CA" "CB" "CC" "CF" "CG" "CI" "CN" "CP" "CQ" "CR" "CS" "CT" "CX" "CY" "DF" "DH" "DIS" "DR" "DZ" "EA" "FT" "GA" "GRAM" "GS" "IN" "JO" "JR" "LB" "LF" "LT" "MM" "MP" "MR" "MT" "OZ" "PC" "PQ" "PR" "PS" "PT" "QT" "RA" "RL" "RM" "RO" "SC" "SF" "SH" "SI" "SJ" "SL" "SM" "SO" "SQ" "ST" "SV" "SX" "SY" "TE" "TN" "TO" "UN" "YD" "Z3"
parent_line_key
string

The line_item_key of the parent line item. This can not be set if this line item is a main line item.

assigned_party_ref
string

The party that this line item is assigned to. Useful if assigning line items to different factories under a vendor, for example.

object or Array of objects (MetadataCreate)
object or Array of objects (MetadataCreate)
One of:

Metadata has two allowed formats. Either array format or object format. Refer to the metadata section in this documentation for more information.

example_key
Array of strings
Responses
200

The update purchase order

Response Schema: application/json
id
integer

A unique identifier for the purchase order

_object
string

Type of the object

name
string

The name of the purchase order

status
string
Default: "open"

The status of the purchase order. Open POs denote POs that are ready to be booked. Closed POs are ones that you'd like to mark as done (typically because they've finished shipping), while Cancelled POs denote POs that were mistakenly uploaded or that should not be used.

Enum: "open" "closed" "cancelled"
incoterm
string
Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
order_type
string

Type of purchase order, which is used for rules, searching, and reporting

order_class
string

Class of the purchase order.

Enum: "purchase_order" "sales_order" "transfer_order" "delivery_order" "work_order"
issue_date
string <date>

the date that the order was issued

freight_paymnet_terms
string
Enum: "freight_collect" "freight_prepaid"
priority
string
Enum: "standard" "high"
transportation_mode
string (TransportationMode)
Enum: "ocean" "air" "barge" "truck" "rail" "unknown_transportation" "ocean_air" "truck_intl" "warehouse_storage"
cargo_ready_date
string <date>
must_arrive_date
string <date>
object or null (Place)
_object
string

Type of the object

name
string

Name of the place

object (Address)
Array of Airport (object) or Placeport (object) or Manufacturer (object)
object (Address)
_object
string

Type of the object

street_address
string
street_address2
string or null
city
string
state
string or null
country
string
country_code
string
zip
string or null
timezone
string
ref
string
unlocode
string or null
object or null (Place)
_object
string

Type of the object

name
string

Name of the place

object (Address)
Array of Airport (object) or Placeport (object) or Manufacturer (object)
Array of objects (Address)
Array
_object
string

Type of the object

street_address
string
street_address2
string or null
city
string
state
string or null
country
string
country_code
string
zip
string or null
timezone
string
ref
string
unlocode
string or null
Array of objects (Parties)

A list of the parties in this purchase order. Buyer, Seller and Owner parties will always be returned.

Array
role
string

The role that the party has

Enum: "buyer" "seller" "owner" "shipper" "consignee" "freight_forwarder" "notify_party" "customs_broker" "carrier" "manufacturer" "buyers_agent" "sellers_agent"
object (CompanyEntity)
object (Address)

The object of the location that is tied to this party. This should be the address that would be associated with the party at the top of a purchase order document. Used for order delivery to suppliers, not in the booking process.

Array of objects

A list of contact data for who should be contacted should there be questions about this order. For example, if your supplier needs to contact someone, who should they contact?

memo
string
archived_at
string <date_time>
created_at
string <date_time>
updated_at
string <date_time>
object (PurchaseOrderLineItemCollectionRef)
_object
string

Type of the object

ref_type
string

Type of the object in this list

link
string

URL to fetch list of objects

metadata
object (Metadata)

Set of custom key-values specific to the object. The keys are strings and values are arrays of strings. The set of valid keys is always the consignee's list of keys, even if call was made by a different party.

400

error

post/purchase_orders/{id}
Request samples
application/json
{
  • "name": "PO 123",
  • "memo": "memo",
  • "status": "open",
  • "order_type": "Apparel",
  • "order_class": "purchase_order",
  • "parties": [
    • {
      • "role": "buyer",
      • "external_ref": "id-1232",
      • "contact": [
        ],
      • "location_ref": "id-1232"
      },
    • {
      • "role": "seller",
      • "external_ref": "id-321",
      • "contact": [
        ],
      • "location_ref": "id-432"
      }
    ],
  • "currency_code": "USD",
  • "origin_port": {
    • "code": "USLA",
    • "code_type": "unlocode"
    },
  • "destination_port": {
    • "code": "CNSHA",
    • "code_type": "unlocode"
    },
  • "cargo_ready_date": "2019-06-30",
  • "issue_date": "2019-06-30",
  • "freight_payment_terms": "freight_collect",
  • "must_arrive_date": "2019-07-31",
  • "priority": "standard",
  • "transportation_mode": "ocean",
  • "incoterm": "FOB",
  • "origin_location_ref": "id-123456",
  • "destination_location_refs": [
    • "id-654321",
    • "id-654322"
    ],
  • "line_items": {
    • "item_key": "item_key_1",
    • "line_item_number": 1,
    • "product": {
      • "sku": "SKU-123",
      • "name": "AC Adapter 12",
      • "product_category": "furniture",
      • "color": "red",
      • "country_of_origin": "US",
      • "dangerous": true,
      • "ean_ucc_13": 1234567890123,
      • "ean_ucc_8": 12345678,
      • "lot_number": 123456789,
      • "size": "m",
      • "style": "classic",
      • "upc": 123456789
      },
    • "origin_port": {
      • "code": "USLGB",
      • "code_type": "unlocode"
      },
    • "destination_port": {
      • "code": "USFBN",
      • "code_type": "unlocode"
      },
    • "cargo_ready_date": "2019-06-30",
    • "must_arrive_date": "2019-07-31",
    • "transportation_mode": "ocean",
    • "incoterm": "FOB",
    • "origin_location_ref": "id-123456",
    • "destination_locations": [
      • {
        }
      ],
    • "measurements": [
      • {
        }
      ],
    • "units": 10,
    • "unit_cost": {
      • "amount": "100.01",
      • "currency_code": "USD"
      },
    • "hs_codes": [
      • {
        }
      ],
    • "metadata": {
      • "size": [
        ]
      }
    }
}
Response samples
application/json
{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/purchase_orders/12345",
  • "version": 3,
  • "data": {
    • "metadata": {
      • "size": [
        ]
      },
    • "_object": "/purchase_order",
    • "id": 109771,
    • "name": "PO 123",
    • "incoterm": "FOB",
    • "transportation_mode": "ocean",
    • "cargo_ready_date": "2019-06-30",
    • "must_arrive_date": "2019-07-31",
    • "origin_port": {
      • "_object": "/place",
      • "name": "Fairburn",
      • "address": {
        },
      • "details": [
        ]
      },
    • "origin_address": {
      • "_object": "/address",
      • "street_address": "No 1, 123 St",
      • "street_address2": null,
      • "city": "Shenzhen",
      • "state": "Beijing",
      • "country": "China",
      • "country_code": "CN",
      • "zip": null,
      • "unlocode": null,
      • "timezone": "Asia/Shanghai",
      • "ref": "id-274346"
      },
    • "destination_port": {
      • "_object": "/place",
      • "name": "Fairburn",
      • "address": {
        },
      • "details": [
        ]
      },
    • "destination_addresses": [
      • {
        }
      ],
    • "line_items": {},
    • "parties": [
      • {
        },
      • {
        },
      • {
        }
      ],
    • "memo": "memo",
    • "status": "open",
    • "archived_at": null,
    • "created_at": "2020-07-31T19:52:58.140Z",
    • "updated_at": "2020-07-31T19:52:58.161Z",
    • "priority": "standard",
    • "order_type": "Apparel",
    • "issue_date": "2019-06-30",
    • "freight_payment_terms": "freight_collect"
    },
  • "error": null
}
➔ Next to ContainerLoadResult