Órdenes de compra
Una orden de compra es una venta a crédito a otro negocio: le mandas la orden con su factura, tu cliente la paga después con su link o por fuera de Recurrente (una transferencia, un cheque), y tú registras ese pago. Es lo mismo que el comercio hace en el panel desde Cobrar → Orden de compra y sigue en Finanzas → Por cobrar, ahora desde tu ERP, tu sistema de pedidos o un agente.
Si conoces las facturas de Stripe, el modelo es el mismo: un borrador que editas, lo finalizas para enviarlo, y luego se paga, se anula o se da por perdido.
Las órdenes de compra son para cuentas de negocio. Una cuenta personal recibe 403 con code: purchase_orders_not_available en todos sus endpoints.
Cuándo usarla
Usa una orden de compra cuando:
- Le vendes a otra empresa y te paga a 15, 30, 60 o 90 días, o en una fecha.
- Necesitas que la venta salga con su factura: si la cuenta emite facturas con Recurrente, la orden lleva una factura cambiaria, la factura de la SAT para ventas al crédito.
- Tu cliente puede pagarte por fuera, todo o en abonos, y quieres que lo que te debe se mantenga al día.
Para cobrar en el momento, usa un checkout o un link de pago.
Ciclo de vida
Vencida no es un estado: una orden open con la fecha de vencimiento ya pasada lleva overdue: true.
El flujo típico
1. Crea la orden y envíala. Manda un monto (amount_in_cents, con description) o líneas (items), nunca los dos. Una línea es el price_id de un precio de pago único de tu tienda, o un name con su amount_in_cents que no aparece en tu catálogo. Identifica al comprador con customer_id, o con su correo y nombre para encontrarlo o crearlo. La orden guarda el nombre del comprador como se escribió (buyer_name, o el del cliente si no mandas uno): renombrar al cliente después no cambia una orden ya enviada. quantity es un entero mayor a 0: 1.9 o "2 cajas" se rechazan con 422. Usa un Idempotency-Key distinto por orden.
Sin send, la orden queda en draft y la envías después con POST /purchase_orders/{purchase_order_id}/finalization. Con send: true, en la misma llamada se certifica la factura, la orden pasa a open con su issued_on y su due_on, y le llega al comprador por correo (o por WhatsApp, o ambos, según delivery) con su link para pagar. Con delivery: link no se le envía nada: compartes tú checkout_url.
Si la factura no se certifica, la respuesta sigue siendo 201, pero la orden queda en draft con tax_invoice.status: failed y no se envía nada. Lee tax_invoice.error_code para saber qué hacer (ver Errores).
2. Registra lo que te pagan por fuera. Si tu cliente te transfirió a tu banco, regístralo. No mueve dinero; deja constancia y baja lo que debe. Puede ser un abono: la orden sigue open y su link cobra solo lo que falta. El pago que completa la deuda la deja paid.
Sin amount_in_cents registra todo lo que falta, con fecha de hoy. payment_method es transfer, deposit, cheque, cash u other (por defecto). La respuesta es la orden, con el pago en payments y lo que falta en amount_remaining_in_cents.
3. Escucha purchase_order.paid. Llega cuando la orden queda pagada, sea porque el comprador pagó con su link o porque tus pagos registrados completaron la deuda. Si pagó con su link, también recibes el webhook de ese cobro (intent.succeeded), como cualquier pago.
El ejemplo muestra solo algunos campos: cada evento trae la orden completa, como la responde GET /purchase_orders/{id}. Usa metadata para encontrarla en tu sistema.
Evitar duplicados del ERP
Envía external_reference al crear la orden. Es opcional, de 1 a 255 caracteres,
no puede contener solo espacios y distingue mayúsculas y minúsculas. Se compara
exactamente como la envías, incluidos los espacios. Una vez asignada no cambia,
ni en borrador; tampoco se puede agregar después con PATCH.
La referencia es única por cuenta y ambiente, sin vencimiento. Anular la orden
o eliminar el borrador no la libera. Si SAP reenvía SAP-55120 un mes después,
recibe 409 y no se crea ni envía otra orden:
status es el estado actual de la orden original. Si fue eliminada, dice deleted.
Consulta GET /purchase_orders/by_external_reference?external_reference=SAP-55120
para recuperar la orden completa; de una eliminada devuelve únicamente id,
status y external_reference. Una referencia desconocida en esa cuenta y
ambiente responde 404. Codifica la referencia como parámetro de query si tiene
espacios, / u otros caracteres especiales.
Sigue usando Idempotency-Key para reintentos inmediatos: durante 24 horas puede
reproducir la respuesta original; external_reference protege después de ese
plazo y aunque cambie la llave de idempotencia. buyer_reference y metadata
no son únicos. La referencia externa también viaja en los webhooks.
Todas las operaciones
Una orden enviada no se corrige: anúlala y crea otra, como en el panel. Un borrador que no vas a enviar se elimina, no se anula. Lo mismo hace Descartar orden en el panel, y ambos emiten purchase_order.deleted.
Los recordatorios automáticos siguen la Política de cobro de la cuenta; send_reminders: false envía la orden con ellos en pausa.
Webhooks
Cada evento trae la orden como estaba en ese momento, con api_version.
Las órdenes creadas en el panel emiten los mismos eventos. Para registrar tu endpoint y verificar las firmas, lee Webhooks.
Errores
Una transición que el estado de la orden no permite responde 422 con un code que puedes usar para decidir qué hacer:
Por qué no se certificó la factura
Cuando la factura de una orden falla, tax_invoice.error_code dice quién puede resolverlo, y tax_invoice.error_message lo dice en español, como lo muestra Por cobrar:
Sandbox
En un Sandbox las órdenes de compra funcionan con estas diferencias:
- La factura se simula: tiene
uuid, pero no llega a la SAT ni tiene página (tax_invoice.urlesnull). Anular también se simula. - Al comprador no le llega nada, así que nunca recibes
purchase_order.sent. Compartecheckout_urla mano y págalo con la tarjeta de prueba. reminderestá bloqueado, porque un Sandbox no le escribe a nadie.- Listar, leer, editar, eliminar, registrar pagos y dar por perdida funcionan igual que en vivo, sobre las órdenes del Sandbox.
- Los eventos salen solo a los webhooks del Sandbox.
Agentes: CLI y MCP
Todas las operaciones de esta guía están en el catálogo de agentes, así que el CLI recurrente y el servidor MCP las corren sin código adicional:

