> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Purchase Orders

> Sell on credit to another business with its tax invoice, record the payments it makes outside Recurrente, and hear when it pays, falls due or is voided

A purchase order (orden de compra) is a credit sale to another business: you send the order with its tax invoice, your buyer pays later through its link or outside Recurrente (a bank transfer, a cheque), and you record that payment. It is what a business does in the dashboard from **Cobrar → Orden de compra** and follows in **Finanzas → Por cobrar**, now from your ERP, your order system or an agent.

If you know Stripe Invoices, the model is the same: a draft you edit, finalize to send, and that is then paid, voided or marked uncollectible.

> **Note**
>
> Purchase orders are for business accounts. A personal account gets `403` with `code: purchase_orders_not_available` on every endpoint.

## When to use it

Use a purchase order when:

* You sell to another business that pays you in 15, 30, 60 or 90 days, or on a date.
* The sale needs its tax invoice: if the account issues tax invoices with Recurrente, the order carries a **factura cambiaria**, SAT's invoice for credit sales.
* Your buyer may pay you outside Recurrente, in full or in installments, and you want what they owe kept up to date.

To get paid on the spot, use a [checkout](/referencia-api/api-reference/checkouts/create-checkout) or a payment link.

## Lifecycle

| Status          | What it means                                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `draft`         | Nothing has reached the buyer. It can be edited and deleted. An order whose tax invoice failed to certify also stays here. |
| `open`          | Sent and owed. It can no longer be edited, except its `metadata`.                                                          |
| `paid`          | Paid, through its link or by payments recorded outside Recurrente.                                                         |
| `void`          | Voided: its tax invoice was voided at SAT and its link stopped taking payments.                                            |
| `uncollectible` | Written off. It no longer counts as owed, but its link still collects: if the buyer pays, it moves to `paid`.              |

```
draft ──finalization──▶ open ──▶ paid
  │                       │
  └──DELETE (gone)        ├──void──▶ void
                          └──uncollectible──▶ uncollectible ──▶ paid / void
```

Overdue is not a status: an `open` order whose due date has passed carries `overdue: true`.

## A typical flow

**1. Create the order and send it.** Send an amount (`amount_in_cents`, with `description`) or lines (`items`), never both. A line is the `price_id` of a one-time price from your store, or a `name` with its `amount_in_cents` that never shows in your catalog. Identify the buyer by `customer_id`, or by their email and name to find or create them. The order keeps the buyer's name as it was written (`buyer_name`, or the customer's when you send none): renaming the customer later doesn't change an order already sent. `quantity` is a whole number above 0: `1.9` or `"2 boxes"` is refused with `422`. Use a unique `Idempotency-Key` per order.

```bash
curl -X POST https://app.recurrente.com/api/purchase_orders \
  -H "X-SECRET-KEY: sk_live_..." -H "Idempotency-Key: order-55120" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_3jfrywsf",
    "items": [
      { "name": "Liquid soap, case", "amount_in_cents": 4625, "quantity": 40 }
    ],
    "net_days": 30,
    "buyer_tax_id": "8812345",
    "buyer_reference": "PO-889",
    "external_reference": "SAP-55120",
    "metadata": { "erp_id": "SO-55120" },
    "send": true
  }'
```

Without `send`, the order stays a `draft` and you send it later with `POST /purchase_orders/{purchase_order_id}/finalization`. With `send: true`, the same call certifies the tax invoice, moves the order to `open` with its `issued_on` and `due_on`, and delivers it to the buyer by email (or WhatsApp, or both, per `delivery`) with its link to pay. With `delivery: link` nothing is sent: you share `checkout_url` yourself.

If the tax invoice fails to certify, the response is still `201`, but the order stays a `draft` with `tax_invoice.status: failed` and nothing is sent. Read `tax_invoice.error_code` to know what to do (see [Errors](#errors)).

**2. Record what you are paid outside Recurrente.** If your buyer transferred to your bank, record it. No money moves; it keeps the record and lowers what is owed. It can be a partial payment: the order stays `open` and its link charges only what is left. The payment that settles the debt marks it `paid`.

```bash
curl -X POST https://app.recurrente.com/api/purchase_orders/oc_k3j9x2ab/payments \
  -H "X-SECRET-KEY: sk_live_..." -H "Idempotency-Key: payment-48213" \
  -H "Content-Type: application/json" \
  -d '{ "amount_in_cents": 50000, "payment_method": "transfer", "reference": "TRX-48213" }'
```

Without `amount_in_cents` it records everything still owed, dated today. `payment_method` is `transfer`, `deposit`, `cheque`, `cash` or `other` (the default). The response is the order, with the payment in `payments` and what is left in `amount_remaining_in_cents`.

**3. Listen for `purchase_order.paid`.** It arrives when the order is paid, whether the buyer paid through its link or your recorded payments settled it. If they paid through the link, you also get that payment's own webhook (`intent.succeeded`), like any other payment.

```json
{
  "event_type": "purchase_order.paid",
  "api_version": "2024-04-24",
  "id": "oc_k3j9x2ab",
  "status": "paid",
  "reference": "OC-1001",
  "currency": "GTQ",
  "total_in_cents": 185000,
  "amount_paid_out_of_band_in_cents": 50000,
  "amount_remaining_in_cents": 0,
  "metadata": { "erp_id": "SO-55120" },
  "paid_at": "2026-11-20T18:30:00Z"
}
```

The example shows only some fields: every event carries the full order, as `GET /purchase_orders/{id}` returns it. Use `metadata` to find it in your system.

## Prevent ERP duplicates

Send `external_reference` when creating an order: an optional, case-sensitive
string of 1–255 characters, not blank or whitespace-only. Spaces are preserved.
It is unique per account and environment **without expiration**, even after an
order is voided or a draft deleted. It cannot be added or changed with `PATCH`
(`422 external_reference_immutable`).

A repeated reference returns `409 external_reference_exists`, with `id`,
`status` and `external_reference` identifying the original order, without creating
or sending another. `status` reflects its current state, or `deleted`.

Use `GET /purchase_orders/by_external_reference?external_reference=SAP-55120`
to retrieve the full order, or just `id`, `status: deleted` and
`external_reference` for a deleted draft. URL-encode the query value as needed.
An unknown reference in that account and environment returns `404`.

Keep using `Idempotency-Key` for immediate retries: within 24 hours it may replay
the original response. The external reference still protects against duplicates
after that period and when a different idempotency key is sent. `buyer_reference`
and `metadata` are not unique. Webhooks also include `external_reference`.

## All operations

| Operation             | Endpoint                                                                  | Notes                                                                                                                                                                                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| List                  | `GET /purchase_orders`                                                    | Filter by `status`, `customer_id`, `overdue=true` and `from_time`/`until_time` (creation date). Paginated.                                                                                                                                                                                     |
| Retrieve              | `GET /purchase_orders/{id}`                                               | With what is owed, recorded payments and the tax invoice.                                                                                                                                                                                                                                      |
| Find by ERP reference | `GET /purchase_orders/by_external_reference?external_reference=SAP-55120` | Retrieve the order or its deletion record.                                                                                                                                                                                                                                                     |
| Create                | `POST /purchase_orders`                                                   | A `draft`, unless `send: true`.                                                                                                                                                                                                                                                                |
| Update                | `PATCH /purchase_orders/{id}`                                             | A draft changes whatever you send and keeps the rest (send only `amount_in_cents` and it keeps its currency), and gets a new `checkout_url`. To change the currency of an order with `items`, send its `items` too. A sent order only changes its `metadata`; a key sent as `null` is removed. |
| Delete a draft        | `DELETE /purchase_orders/{id}`                                            | The order is gone: `GET` answers `404` and lists omit it. Responds `{ "id": "oc_…", "status": "deleted" }`.                                                                                                                                                                                    |
| Send                  | `POST /purchase_orders/{purchase_order_id}/finalization`                  | Certifies the tax invoice and delivers the order to the buyer. If the tax invoice fails, call it again to retry.                                                                                                                                                                               |
| Record a payment      | `POST /purchase_orders/{purchase_order_id}/payments`                      | Payments made outside Recurrente, full or partial.                                                                                                                                                                                                                                             |
| Remind                | `POST /purchase_orders/{purchase_order_id}/reminder`                      | Sends a reminder now, like «Recordar ahora» in Por cobrar. Once a day.                                                                                                                                                                                                                         |
| Mark uncollectible    | `POST /purchase_orders/{purchase_order_id}/uncollectible`                 | Only an `open` order. Stops reminders; the tax invoice stays valid.                                                                                                                                                                                                                            |
| Void                  | `POST /purchase_orders/{purchase_order_id}/void`                          | Voids the tax invoice at SAT (or, past the voiding window, issues a credit note) and the link stops taking payments. Accepts `reason`.                                                                                                                                                         |

A sent order is not corrected: void it and create another, as in the dashboard. A draft you won't send is deleted, not voided. **Descartar orden** in the dashboard does the same, and both emit `purchase_order.deleted`.

Automatic reminders follow the account's collection policy (Política de cobro); `send_reminders: false` sends the order with them paused.

## Webhooks

Every event carries the order as it was at that moment, with `api_version`.

| Event                                 | When                                                                                     |
| ------------------------------------- | ---------------------------------------------------------------------------------------- |
| `purchase_order.created`              | A draft was created, from the API or from Cobrar.                                        |
| `purchase_order.updated`              | It was edited with `PATCH`.                                                              |
| `purchase_order.deleted`              | A draft was deleted (`DELETE` or «Descartar orden»). Carries the order as it was before. |
| `purchase_order.finalized`            | It was sent: the tax invoice certified and the order is `open`.                          |
| `purchase_order.sent`                 | It reached the buyer by email or WhatsApp. Not emitted with `delivery: link`.            |
| `purchase_order.payment_recorded`     | A payment made outside Recurrente was recorded, full or partial.                         |
| `purchase_order.paid`                 | It was paid, through its link or by recorded payments.                                   |
| `purchase_order.voided`               | It was voided.                                                                           |
| `purchase_order.marked_uncollectible` | It was written off.                                                                      |
| `purchase_order.will_be_due`          | Three days or fewer before its due date. Once per order.                                 |
| `purchase_order.overdue`              | Its due date passed unpaid. Once per order, the next morning.                            |

Orders created in the dashboard emit the same events. To register your endpoint and verify signatures, see [Webhooks](/guides-english/getting-started/webhooks).

## Errors

A transition the order's status doesn't allow answers `422` with a `code` you can branch on:

| `code`                                                                               | Where                            | What it means                                                                                                                                                                             |
| ------------------------------------------------------------------------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_purchase_order`                                                             | create, update                   | A field is invalid. `errors` says which field and why, using this API's names.                                                                                                            |
| `not_draft`                                                                          | update, delete, send             | The order was already sent. To correct it, void it and create another.                                                                                                                    |
| `fel_outcome_unknown`                                                                | update, delete, void             | We don't know yet whether its tax invoice certified. Call `finalization` to retry before changing it.                                                                                     |
| `fel_issued`                                                                         | delete                           | The draft already has a certified tax invoice. Void it.                                                                                                                                   |
| `fel_failed`                                                                         | send                             | The tax invoice did not certify; the order stays a `draft`. See `tax_invoice.error_code`.                                                                                                 |
| `amount_changed`                                                                     | send                             | A product's price changed since the order was created.                                                                                                                                    |
| `not_collectable`                                                                    | record a payment                 | The order is no longer owed, or was never sent.                                                                                                                                           |
| `payment_in_progress`                                                                | record a payment, void           | The buyer is paying it through its link. Retry in a few minutes.                                                                                                                          |
| `invalid_payment`                                                                    | record a payment                 | For example, more than what is left. See `errors`.                                                                                                                                        |
| `not_open`                                                                           | remind, mark uncollectible, void | The order is not open.                                                                                                                                                                    |
| `draft`                                                                              | void                             | It is a draft: drafts are not voided, they are deleted with `DELETE`.                                                                                                                     |
| `fel_not_reversed`                                                                   | void                             | SAT did not void the tax invoice; the order stays open. The `message` says whether retrying in a few minutes can help.                                                                    |
| `already_reminded_today`, `held`, `unreachable`, `contract_declined`, `already_sent` | remind                           | Already reminded today, reminders paused (or waiting on a promise to pay), a link-only order with nobody to write to, the buyer declined the contract, or that reminder already went out. |

### Why the tax invoice did not certify

When an order's tax invoice fails, `tax_invoice.error_code` says who can fix it, and `tax_invoice.error_message` says it in Spanish, as Por cobrar shows it:

| `error_code`              | What happened                                                       | What to do                                                                                  |
| ------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `service_unavailable`     | The certification service did not answer in time.                   | Retry `finalization` in a few minutes.                                                      |
| `buyer_tax_id_invalid`    | SAT does not recognize the buyer's NIT.                             | Fix `buyer_tax_id` with `PATCH` (or delete the draft and create another) and send it again. |
| `buyer_tax_id_required`   | Over Q2,500 the tax invoice needs the buyer's NIT.                  | Same: add `buyer_tax_id` and send it again.                                                 |
| `account_action_required` | Something about the account at SAT (its signature, its tax regime). | `error_message` says what to fix; then retry.                                               |
| `processing_error`        | Any other failure.                                                  | We are already looking into it.                                                             |

## Sandbox

In a [Sandbox](/guides-english/guides/sandboxes-and-test-clocks) purchase orders work with these differences:

* The tax invoice is simulated: it has a `uuid`, but never reaches SAT and has no page (`tax_invoice.url` is `null`). Voiding is simulated too.
* Nothing reaches the buyer, so you never get `purchase_order.sent`. Share `checkout_url` by hand and pay it with the test card.
* `reminder` is blocked, because a Sandbox writes to no one.
* List, retrieve, update, delete, record payments and mark uncollectible work as they do live, on the Sandbox's own orders.
* Events go only to the Sandbox's webhooks.

## Agents: CLI and MCP

Every operation in this guide is in the agent catalog, so the `recurrente` CLI and the MCP server run them with no extra code:

```bash
recurrente purchase-orders list --overdue true
recurrente purchase-orders record-payment --purchase-order-id oc_k3j9x2ab --amount-in-cents 50000 --payment-method transfer
```