# List & Get Purchase Orders

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.

## List Purchase Orders

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.

### Query Parameters

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) |


### Response Properties

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.

### Example Request & Response

**GET /v2/purchase_orders**

## Get Purchase Order Details

Use the GET method with `/v2/purchase_orders/{purchase_order_id}` to retrieve detailed information about a specific purchase order, including all products.

### Path Parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `purchase_order_id` | *string* | The unique identifier of the purchase order |


### Response Properties

| 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) |


### Product Properties

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 |


### Example Request & Response

**GET /v2/purchase_orders/{purchase_order_id}**

## Filtering and Pagination Examples

### Filter Examples

**Find purchase orders by status:**


```http
GET /v2/purchase_orders?status=open&page_size=50
```

**Find orders from a specific warehouse:**


```http
GET /v2/purchase_orders?warehouse_id=se-123456&page_size=50
```

**Find orders by order number:**


```http
GET /v2/purchase_orders?order_number=02162026-02
```

**Find orders created after a specific date:**


```http
GET /v2/purchase_orders?create_date_start=2025-01-01T00:00:00Z&page_size=50
```

**Combine multiple filters:**


```http
GET /v2/purchase_orders?status=open&warehouse_id=se-123456&page_size=25
```

### Pagination Examples

**Get first page of results:**


```http
GET /v2/purchase_orders?page_size=50
```

**Get next page using cursor from response links:**


```http
GET /v2/purchase_orders?cursor=eyJQYWdlIjoyLCJQYWdlU2l6ZSI6NTAsIk9yZGVyTnVtYmVyIjpudWxsLCJTdGF0dXMiOiJvcGVuIiwiV2FyZWhvdXNlSWQiOm51bGwsIlJlZmVyZW5jZU51bWJlciI6bnVsbCwiQ3JlYXRlRGF0ZVN0YXJ0IjpudWxsfQ
```

### Pagination Tips

- **First page**: Make request without `cursor` parameter
- **Next page**: Use the `cursor` value from `links.next.href` in the response
- **Page size**: Control number of results with `page_size` (default: 50, max: 500)
- **End of results**: When `links.next` is null, you've reached the last page
- **Filters persist**: The cursor preserves all filter parameters from the original request


## Purchase Order Statuses

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