Skip to navigation

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

StatusWhat it means
draftNothing has reached the buyer. It can be edited and deleted. An order whose tax invoice failed to certify also stays here.
openSent and owed. It can no longer be edited, except its metadata.
paidPaid, through its link or by payments recorded outside Recurrente.
voidVoided: its tax invoice was voided at SAT and its link stopped taking payments.
uncollectibleWritten 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.

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

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.

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.

{
"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

OperationEndpointNotes
ListGET /purchase_ordersFilter by status, customer_id, overdue=true and from_time/until_time (creation date). Paginated.
RetrieveGET /purchase_orders/{id}With what is owed, recorded payments and the tax invoice.
Find by ERP referenceGET /purchase_orders/by_external_reference?external_reference=SAP-55120Retrieve the order or its deletion record.
CreatePOST /purchase_ordersA draft, unless send: true.
UpdatePATCH /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 draftDELETE /purchase_orders/{id}The order is gone: GET answers 404 and lists omit it. Responds { "id": "oc_…", "status": "deleted" }.
SendPOST /purchase_orders/{purchase_order_id}/finalizationCertifies the tax invoice and delivers the order to the buyer. If the tax invoice fails, call it again to retry.
Record a paymentPOST /purchase_orders/{purchase_order_id}/paymentsPayments made outside Recurrente, full or partial.
RemindPOST /purchase_orders/{purchase_order_id}/reminderSends a reminder now, like «Recordar ahora» in Por cobrar. Once a day.
Mark uncollectiblePOST /purchase_orders/{purchase_order_id}/uncollectibleOnly an open order. Stops reminders; the tax invoice stays valid.
VoidPOST /purchase_orders/{purchase_order_id}/voidVoids 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.

EventWhen
purchase_order.createdA draft was created, from the API or from Cobrar.
purchase_order.updatedIt was edited with PATCH.
purchase_order.deletedA draft was deleted (DELETE or «Descartar orden»). Carries the order as it was before.
purchase_order.finalizedIt was sent: the tax invoice certified and the order is open.
purchase_order.sentIt reached the buyer by email or WhatsApp. Not emitted with delivery: link.
purchase_order.payment_recordedA payment made outside Recurrente was recorded, full or partial.
purchase_order.paidIt was paid, through its link or by recorded payments.
purchase_order.voidedIt was voided.
purchase_order.marked_uncollectibleIt was written off.
purchase_order.will_be_dueThree days or fewer before its due date. Once per order.
purchase_order.overdueIts 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.

Errors

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

codeWhereWhat it means
invalid_purchase_ordercreate, updateA field is invalid. errors says which field and why, using this API’s names.
not_draftupdate, delete, sendThe order was already sent. To correct it, void it and create another.
fel_outcome_unknownupdate, delete, voidWe don’t know yet whether its tax invoice certified. Call finalization to retry before changing it.
fel_issueddeleteThe draft already has a certified tax invoice. Void it.
fel_failedsendThe tax invoice did not certify; the order stays a draft. See tax_invoice.error_code.
amount_changedsendA product’s price changed since the order was created.
not_collectablerecord a paymentThe order is no longer owed, or was never sent.
payment_in_progressrecord a payment, voidThe buyer is paying it through its link. Retry in a few minutes.
invalid_paymentrecord a paymentFor example, more than what is left. See errors.
not_openremind, mark uncollectible, voidThe order is not open.
draftvoidIt is a draft: drafts are not voided, they are deleted with DELETE.
fel_not_reversedvoidSAT 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_sentremindAlready 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_codeWhat happenedWhat to do
service_unavailableThe certification service did not answer in time.Retry finalization in a few minutes.
buyer_tax_id_invalidSAT 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_requiredOver Q2,500 the tax invoice needs the buyer’s NIT.Same: add buyer_tax_id and send it again.
account_action_requiredSomething about the account at SAT (its signature, its tax regime).error_message says what to fix; then retry.
processing_errorAny other failure.We are already looking into 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.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:

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