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.

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.

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"
required
Array of objects (CreateParty)

A list of the parties in this purchase order. Seller is required. 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

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.

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"
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)
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"
Array of objects (CreateLineItemDestinationLocation)

List of destinations locations for this line item

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

line_type
string
Default: "main_line"

type of the line item

Enum: "main_line" "sub_line" "component_line"
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.

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" "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",
  • "parties": [
    • {
      • "role": "buyer",
      • "external_ref": "id-1232"
      },
    • {
      • "role": "seller",
      • "external_ref": "id-321"
      }
    ],
  • "currency_code": "USD",
  • "origin_port": {
    • "code": "USFBN",
    • "code_type": "unlocode"
    },
  • "destination_port": {
    • "code": "USFBN",
    • "code_type": "unlocode"
    },
  • "cargo_ready_date": "2019-06-30",
  • "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": {
        },
      • "cargo_ready_date": "2019-06-30",
      • "must_arrive_date": "2019-07-31",
      • "transportation_mode": "ocean",
      • "destination_locations": [
        ],
      • "units": 10,
      • "unit_cost": {
        },
      • "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" "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

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.

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"
required
Array of objects (CreateParty)

A list of the parties in this purchase order. Seller is required. 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

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.

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"
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)
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"
Array of objects (CreateLineItemDestinationLocation)

List of destinations locations for this line item

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

line_type
string
Default: "main_line"

type of the line item

Enum: "main_line" "sub_line" "component_line"
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.

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