---
title: "List purchase orders"
method: GET
path: "/v1/erp/payouts/purchase_orders"
tags: ["Purchase Order"]
---

# List purchase orders

`GET /v1/erp/payouts/purchase_orders`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/erp/payouts/purchase_orders`
- Auth: HTTP bearer

Returns a paginated list of purchase orders for the company. This endpoint provides comprehensive filtering, sorting, and pagination capabilities to help you query purchase order history effectively.

## Key Features
- **Pagination**: Control result size with `_start` and `_end` parameters (default: 25 items)
- **Sorting**: Sort by any field in ascending or descending order
- **Filtering**: Apply complex filters on multiple fields including amounts, types, statuses, and dates
- **Relationships**: Automatically includes related entities (business partners, items, payables)

## Authorization
- Regular users can only view purchase orders from companies they are members of.
- Admin users can view all purchase orders.

## Response Structure
The response includes the purchase order details along with nested relationships:
- **business_partner**: Complete vendor/supplier information
- **items**: List of purchase order items with approval status and linked invoices
- **payables**: Related fiscal invoices (when items are linked)
- **type**: The specific purchase order type (AgainstInvoice, ByMilestone, or ByPercentage)

## Purchase Order Types
1. **AgainstInvoice**: Single invoice purchase order (exactly 1 item at 100%)
2. **ByMilestone**: Multiple named deliverables with percentages (e.g., Design 30%, Development 70%)
3. **ByPercentage**: Multiple payment stages with percentages (e.g., 30% advance, 70% final)

## Common Use Cases
1. **Get recent purchase orders**: Use default pagination without filters
2. **Find high-value orders**: Filter by amount range
3. **Check approval status**: Filter by item review status
4. **Audit trail**: Sort by `created_at` or `updated_at` with date filters
5. **Vendor reconciliation**: Filter by `business_partner_id`
6. **Budget tracking**: Filter by type and sum amounts

## Query parameters

- `type` string
- `business_partner_id` string, uuid
- `folio` integer
- `created_at` string
- `updated_at` string
- `description` string
- `currency` 'CLP' | 'CLF' | 'USD'
- `review_status` 'draft' | 'pending' | 'approved' | 'declined'

## Parameters

- `#/paths/~1v1~1erp~1payouts~1rules/get/parameters/0` (unresolved $ref)
- `#/paths/~1v1~1erp~1payouts~1rules/get/parameters/1` (unresolved $ref)
- `#/paths/~1v1~1erp~1payouts~1rules/get/parameters/2` (unresolved $ref)
- `#/paths/~1v1~1erp~1payouts~1rules/get/parameters/3` (unresolved $ref)
- `#/paths/~1v1~1erp~1payouts~1rules/get/parameters/4` (unresolved $ref)
- `#/paths/~1v1~1erp~1payouts~1reviews/get/parameters/5` (unresolved $ref)

## Response `200`

Successfully retrieved purchase orders list

- Schema[] (unresolved $ref)

## Other responses

- `401`: Unauthorized — typically missing/invalid `Authorization` or missing `company-id` header. **The response body is empty** for this guard. Branch your client logic on the status code, not the body. See [Errors](https://docs.cardda.com/docs/errors) for details.

---

[API](https://skmtc.dev/cardda/apis/erp-api.md) - [All operations](https://skmtc.dev/cardda/apis/erp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/erp-api/revisions/0730ed26bc3c?raw)