> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchase Order List API

> Retrieve list of a purchase order including vendor, line items, matched invoices, and GRNs

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

## Request

### Query Parameters

| Parameter       | Type   | Required | Description                                                                                                 |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `sortBy`        | string | No       | Field to sort results by. Allowed values: `amount`, `date_created`, `expected_delivery_date`, `identifier`. |
| `sortOrder`     | string | No       | Sort direction. Allowed values: `asc` (ascending), `desc` (descending).                                     |
| `sortNullOrder` | string | No       | Where to place results with null values in the sorted field. Allowed values: `first`, `last`.               |
| `limit`         | int    | No       | The max number of rows to be returned. Max 100, Default 30.                                                 |
| `cursor`        | string | No       | The pagination cursor, rows to offset/skip. Default 0.                                                      |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.pazy.io/v1.0/procurement/purchase-orders \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/procurement/purchase-orders', {
    method: 'GET',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    }
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/procurement/purchase-orders"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                                                   | Type    | Description                                                                                                  |
| ------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `ok`                                                    | boolean | Indicates whether the request was successful                                                                 |
| `data`                                                  | object  | Contains the purchase order details                                                                          |
| `data.purchaseOrders`                                   | array   | List of purchase orders                                                                                      |
| `data.purchaseOrders[].poId`                            | string  | Unique slug identifier for the purchase order                                                                |
| `data.purchaseOrders[].poNumber`                        | string  | Purchase order number assigned to the document                                                               |
| `data.purchaseOrders[].state`                           | string  | Current state of the PO. Possible values: `DRAFTED`, `PENDING`, `APPROVED`, `DECLINED`, `CLOSED`, `ARCHIVED` |
| `data.purchaseOrders[].poType`                          | string  | Purchase order type. Possible values: `GOODS`, `SERVICES`                                                    |
| `data.purchaseOrders[].matchingType`                    | string  | Matching type. Possible values: `TWO_WAY`, `THREE_WAY`                                                       |
| `data.purchaseOrders[].currency`                        | string  | ISO 4217 currency code (e.g., `INR`)                                                                         |
| `data.purchaseOrders[].amount`                          | number  | Total purchase order amount                                                                                  |
| `data.purchaseOrders[].description`                     | string  | Short description for the purchase order                                                                     |
| `data.purchaseOrders[].poDate`                          | string  | Purchase order date (ISO 8601 format, YYYY-MM-DD)                                                            |
| `data.purchaseOrders[].deliveryDate`                    | string  | Requested delivery date (ISO 8601 format, YYYY-MM-DD)                                                        |
| `data.purchaseOrders[].termsAndConditions`              | string  | Terms and conditions for the purchase order                                                                  |
| `data.purchaseOrders[].additionalNotes`                 | string  | Additional notes for delivery or special requirements                                                        |
| `data.purchaseOrders[].paymentTerms`                    | string  | Agreed payment terms                                                                                         |
| `data.purchaseOrders[].vendor`                          | object  | Linked vendor information (`null` if no vendor linked)                                                       |
| `data.purchaseOrders[].vendor.displayName`              | string  | Vendor display name                                                                                          |
| `data.purchaseOrders[].vendor.legalName`                | string  | Vendor legal name                                                                                            |
| `data.purchaseOrders[].lineItems`                       | array   | List of line items on the purchase order                                                                     |
| `data.purchaseOrders[].lineItems[].identifier`          | string  | SKU or identifier for the line item                                                                          |
| `data.purchaseOrders[].lineItems[].quantity`            | number  | Quantity requested                                                                                           |
| `data.purchaseOrders[].lineItems[].rate`                | number  | Unit rate                                                                                                    |
| `data.purchaseOrders[].lineItems[].amount`              | number  | Total amount for this line item (quantity × rate)                                                            |
| `data.purchaseOrders[].matchedInvoices`                 | array   | List of invoices matched against this purchase order                                                         |
| `data.purchaseOrders[].matchedInvoices[].invoiceId`     | string  | Unique identifier of the matched invoice                                                                     |
| `data.purchaseOrders[].matchedInvoices[].invoiceNumber` | string  | Invoice number                                                                                               |
| `data.purchaseOrders[].matchedInvoices[].state`         | string  | Current state of the invoice                                                                                 |
| `data.purchaseOrders[].matchedInvoices[].amount`        | number  | Invoice amount                                                                                               |
| `data.purchaseOrders[].matchedInvoices[].currency`      | string  | Invoice currency                                                                                             |
| `data.purchaseOrders[].matchedInvoices[].invoiceDate`   | string  | Invoice date (ISO 8601 format)                                                                               |
| `data.purchaseOrders[].matchedGrns`                     | array   | List of Goods Receipt Notes matched against this purchase order                                              |
| `data.purchaseOrders[].matchedGrns[].grnId`             | string  | Unique identifier of the matched GRN                                                                         |
| `data.purchaseOrders[].matchedGrns[].grnNumber`         | string  | GRN number                                                                                                   |
| `data.purchaseOrders[].matchedGrns[].state`             | string  | Current state of the GRN                                                                                     |
| `data.purchaseOrders[].matchedGrns[].amount`            | number  | GRN total amount                                                                                             |
| `data.purchaseOrders[].matchedGrns[].totalQuantity`     | number  | Total quantity received in the GRN                                                                           |
| `data.purchaseOrders[].matchedGrns[].createdAt`         | string  | Date the GRN was created (ISO 8601 format)                                                                   |
| `data.context.count`                                    | number  | Total number of vendor payments                                                                              |
| `data.context.hasMore`                                  | boolean | If there is more Purchase Order                                                                              |
| `data.context.count`                                    | number  | Total number of vendor payments                                                                              |

### PO State Values

| Value      | Description                            |
| ---------- | -------------------------------------- |
| `DRAFTED`  | PO is in draft state and can be edited |
| `PENDING`  | PO is pending approval                 |
| `APPROVED` | PO has been approved                   |
| `DECLINED` | PO was declined and can be edited      |
| `CLOSED`   | PO has been closed                     |
| `ARCHIVED` | PO has been archived                   |

### Response Example

```json theme={null}
{
    "ok": true,
    "data": {
        "purchaseOrders": [
            {
                "poId": "po-id",
                "poNumber": null,
                "state": "CREATED",
                "poType": null,
                "matchingType": null,
                "currency": "INR",
                "amount": null,
                "description": null,
                "poDate": "2026-01-13T10:32:19.526Z",
                "deliveryDate": null,
                "termsAndConditions": null,
                "additionalNotes": null,
                "vendor": null,
                "lineItems": [],
                "matchedInvoices": [],
                "matchedGrns": []
            },
            {
                "poId": "po-id",
                "poNumber": "PO123456",
                "state": "ARCHIVED",
                "poType": "GOODS",
                "matchingType": "TWO_WAY",
                "currency": "INR",
                "amount": null,
                "description": "Purchase order with SKU",
                "poDate": "2025-04-28T05:13:47.507Z",
                "deliveryDate": null,
                "termsAndConditions": null,
                "additionalNotes": null,
                "vendor": {
                    "displayName": "Acme Suppliers",
                    "legalName": "ACME SUPPLIERS PRIVATE LIMITED"
                },
                "lineItems": [
                    {
                        "identifier": "item1",
                        "quantity": 10,
                        "rate": 100,
                        "amount": 1000,
                        "taxId": "132",
                        "taxAmount": 100
                    },
                    {
                        "identifier": "Item 1",
                        "quantity": 10,
                        "rate": 100,
                        "amount": 1000,
                        "taxId": "132",
                        "taxAmount": 100
                    }
                ],
                "matchedInvoices": [],
                "matchedGrns": []
            },
            ...
        ],
        "context": {
            "count": 100,
            "hasMore": true,
            "nextCursor": "100"
        }
    }
}
```

## Error Responses

### Purchase Order Not Found

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "PURCHASE_ORDER_NOT_FOUND",
    "message": "Purchase order not found"
  }
}
```

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Internal Error

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}
```

## Best Practices

* The `matchedInvoices` array is populated when invoices are linked to the PO (TWO\_WAY or THREE\_WAY matching)
* The `matchedGrns` array is populated only for THREE\_WAY matching POs
* Check `state` to understand where the PO is in the approval workflow before taking further actions