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.role
string

Filters the list based on which role you take in the PO

Enum: "buyer" "seller"
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 or null
next
string or null
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": 2,
  • "data": {
    • "_object": "/api/collections/paginated",
    • "prev": "https://api.flexport.com/purchase_orders?page=12&per=10",
    • "next": null,
    • "data": [
      • {
        }
      ]
    }
}

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

The status of the purchase order

Enum: "open" "closed" "cancelled"
incoterm
string
Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
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 (DeprecatedCompany)
object (DeprecatedCompany)
object or null (Place)
object (Address)
object or null (Place)
object (Address)
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": "/api/response",
  • "self": "https://api.flexport.com/purchase_orders/1234",
  • "version": 2,
  • "data": {
    • "_object": "/purchase_order",
    • "id": 123456,
    • "name": "PO1234",
    • "status": "open",
    • "seller": {
      • "_object": "/company",
      • "id": 1234,
      • "name": "Seller Co.",
      • "ref": "sellerco"
      },
    • "buyer": {
      • "_object": "/company",
      • "id": 2345,
      • "name": "Studio Apparel",
      • "ref": "studio"
      },
    • "incoterm": "FOB",
    • "transportation_mode": "ocean",
    • "cargo_ready_date": "2019-02-04",
    • "must_arrive_date": "2019-03-11",
    • "origin_port": null,
    • "origin_address": {
      • "_object": "/address",
      • "street_address": "10th YouSong Industrial District",
      • "street_address2": "",
      • "city": "Shenzhen",
      • "state": "44",
      • "country": "China",
      • "country_code": "CN",
      • "zip": null,
      • "unlocode": null,
      • "timezone": "China/Shenzhen",
      • "ref": "sellingcoaddress"
      },
    • "destination_port": null,
    • "destination_address": {
      • "_object": "/address",
      • "street_address": "1556 20TH ST STE 2D",
      • "street_address2": "",
      • "city": "SANTA MONICA",
      • "state": "CA",
      • "country": "United States",
      • "country_code": "US",
      • "zip": "90404-3465",
      • "unlocode": null,
      • "timezone": "America/Los_Angeles",
      • "ref": "studiosantamonica"
      },
    • "line_items": {},
    • "memo": "FTZ",
    • "archived_at": "2019-06-05T15:32:08.723Z"
    }
}
➔ Next to BookingAmendment