Retrieve purchase orders to view order history, check status, and access detailed information. Use the list endpoint to find orders with filtering, or get a specific order by ID to see full details including all products.
Use the GET method with /v2/purchase_orders to retrieve a paginated list of purchase orders. You can filter the results by status, warehouse, dates, and other criteria.
Use the following query parameters to filter your purchase orders:
| Query Parameter | Type | Description |
|---|---|---|
order_number | string | Filter by the auto-generated order number |
status | enumerated string | Filter by purchase order status: draft, open, receiving, received, closed, cancelled |
warehouse_id | string | Filter by warehouse ID where products will be received |
reference_number | string | Filter by your custom reference number |
create_date_start | string (date-time) | Filter by creation date start (inclusive). Format: ISO 8601 (e.g., 2025-01-01T00:00:00Z) |
page_size | integer | Number of results per page (default: 50, minimum: 1, maximum: 500) |
The response includes a purchase_orders array with the following properties for each purchase order:
| Property | Type | Description |
|---|---|---|
purchase_order_id | string | Unique identifier for the purchase order |
order_number | string | Auto-generated order number (e.g., "02162026-02") |
supplier_id | string | Identifier for the supplier |
supplier_name | string | Name of the supplier |
status | enumerated string | Current status: draft, open, receiving, received, cancelled, closed |
order_date | string (date-time) | Date when the order was placed with the supplier |
expected_delivery_date | string (date-time) | Expected delivery date for the order |
create_date | string (date-time) | Date when the purchase order was created in the system |
modify_date | string (date-time) | Date when the purchase order was last modified |
reference_number | string | Optional custom reference number |
warehouse_id | string | Warehouse where products will be received |
The response also includes pagination metadata: total (total number of purchase orders) and links (HATEOAS navigation links). The cursor for the next page is embedded in the links.next.href URL.
GET /v2/purchase_orders
- Productionhttps://api.shipstation.com/v2/purchase_orders
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://api.shipstation.com/v2/purchase_orders?order_number=02162026-02&status=draft&warehouse_id=string&reference_number=string&create_date_start=2025-01-01T00%3A00%3A00Z&page_size=50' \
-H 'api-key: YOUR_API_KEY_HERE'Use the GET method with /v2/purchase_orders/{purchase_order_id} to retrieve detailed information about a specific purchase order, including all products.
| Parameter | Type | Description |
|---|---|---|
purchase_order_id | string | The unique identifier of the purchase order |
| Property | Type | Description |
|---|---|---|
purchase_order_id | string | Unique identifier for the purchase order |
order_number | string | Auto-generated order number (e.g., "02162026-02") |
supplier_id | string | Identifier for the supplier |
status | enumerated string | Current status: draft, open, receiving, received, cancelled, closed |
order_date | string (date-time) | Date when the order was placed with the supplier |
expected_delivery_date | string (date-time) | Expected delivery date for the order |
create_date | string (date-time) | Date when the purchase order was created in the system |
modify_date | string (date-time) | Date when the purchase order was last modified |
reference_number | string | Optional custom reference number |
warehouse_id | string | Warehouse where products will be received |
payment_terms | enumerated string | Payment terms: none, cash_on_delivery, payment_on_receipt, payment_in_advance, net_7, net_15, net_30, net_45, net_60 |
payment_status | enumerated string | Payment status: none, unpaid, partially_paid, paid, refunded, credit_issued, other |
currency_code | string | ISO 4217 currency code (e.g., "USD") |
shipping_carrier | string | Shipping carrier name for shipment tracking |
tracking_number | string | Tracking number for the shipment from supplier |
note_to_supplier | string | Notes or special instructions for the supplier |
products | array | Array of product objects (see below) |
Each product in the products array contains:
| Property | Type | Description |
|---|---|---|
sku | string | Stock Keeping Unit identifier |
supplier_sku | string | Supplier's SKU for this product |
quantity | integer | Quantity ordered |
cost | number | Unit cost of the product |
GET /v2/purchase_orders/{purchase_order_id}
- Productionhttps://api.shipstation.com/v2/purchase_orders/{purchase_order_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
https://api.shipstation.com/v2/purchase_orders/se-234 \
-H 'api-key: YOUR_API_KEY_HERE'Find purchase orders by status:
GET /v2/purchase_orders?status=open&page_size=50Find orders from a specific warehouse:
GET /v2/purchase_orders?warehouse_id=se-123456&page_size=50Find orders by order number:
GET /v2/purchase_orders?order_number=02162026-02Find orders created after a specific date:
GET /v2/purchase_orders?create_date_start=2025-01-01T00:00:00Z&page_size=50Combine multiple filters:
GET /v2/purchase_orders?status=open&warehouse_id=se-123456&page_size=25Get first page of results:
GET /v2/purchase_orders?page_size=50Get next page using cursor from response links:
GET /v2/purchase_orders?cursor=eyJQYWdlIjoyLCJQYWdlU2l6ZSI6NTAsIk9yZGVyTnVtYmVyIjpudWxsLCJTdGF0dXMiOiJvcGVuIiwiV2FyZWhvdXNlSWQiOm51bGwsIlJlZmVyZW5jZU51bWJlciI6bnVsbCwiQ3JlYXRlRGF0ZVN0YXJ0IjpudWxsfQ- First page: Make request without
cursorparameter - Next page: Use the
cursorvalue fromlinks.next.hrefin the response - Page size: Control number of results with
page_size(default: 50, max: 500) - End of results: When
links.nextis null, you've reached the last page - Filters persist: The cursor preserves all filter parameters from the original request
Purchase orders follow a specific lifecycle:
- draft: Initial state when a purchase order is created
- open: Purchase order has been sent to the supplier
- receiving: Products are being received (partial receipt)
- received: All products have been fully received
- cancelled: Purchase order has been cancelled
- closed: All Purchase order action has been processed