Purchase Orders
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.
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 or a payment link.
Lifecycle
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.
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).
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.
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.
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
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.
Orders created in the dashboard emit the same events. To register your endpoint and verify signatures, see Webhooks.
Errors
A transition the order’s status doesn’t allow answers 422 with a code you can branch on:
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:
Sandbox
In a Sandbox 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.urlisnull). Voiding is simulated too. - Nothing reaches the buyer, so you never get
purchase_order.sent. Sharecheckout_urlby hand and pay it with the test card. reminderis 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:

