Crear una orden de compra
Crea una orden de compra en borrador (draft) junto con la venta que
cobra: un monto (amount_in_cents) o productos de tu tienda
(items), nunca los dos. Nada le llega al comprador hasta que la envías
con POST /purchase_orders/{purchase_order_id}/finalization.
Al comprador se le encuentra o se le crea como cliente por su correo, o
por su WhatsApp cuando la orden va solo por ahí. Con delivery: link no
se le envía nada: compartes checkout_url tú.
Si tu cuenta emite facturas electrónicas con Recurrente, la orden pide su
factura (una Factura Cambiaria) salvo que mandes issue_tax_invoice: false.
Un NIT que la SAT no reconoce se rechaza aquí, y arriba de Q2,500 la
factura necesita el NIT del comprador.
Usa un Idempotency-Key único por orden. Para impedir duplicados sin
vencimiento, envía también external_reference: es única por cuenta y
ambiente, incluso después de anular o eliminar. Repetirla responde
409 external_reference_exists con el id y status actuales de la
orden original (deleted si fue eliminada), sin crear ni enviar otra.
Una repetición de la misma Idempotency-Key dentro de sus 24 horas
sigue devolviendo la respuesta original almacenada.
Authentication
Tu clave secreta de API.
Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.
La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).
Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.
Headers
ID de una cuenta hija conectada. Ejecuta el request dentro de esa cuenta,
como Stripe-Account en Stripe Connect. La plataforma puede acceder a
todos los recursos API que pertenecen a la hija, sin filtrar por creador.
Solo aplica a hijas directas: si la cuenta no está conectada a la tuya,
el request responde 404 con code: connected_account_not_found.
Con una llave de organización este header nombra la cuenta miembro sobre
la que quieres operar; si no pertenece a la organización, el request
responde 404 con code: organization_account_not_found. En una lectura
puedes omitirlo para abarcar todas las cuentas de la organización.
Request
Lo que se envía para crear o editar una orden de compra.
Monto de la orden, en centavos. Envía este o items.
Productos de tu tienda que vende la orden. Envía este o amount_in_cents.
Qué vende la orden, como lo lee el comprador. Solo con amount_in_cents; sin ella, la línea se llama como la orden.
Nombre o razón social del comprador. Si lo omites y mandas un NIT, se usa el nombre que la SAT tiene para ese NIT.
Por dónde le llega la orden al comprador: email, whatsapp, ambos (both),
o link para no enviarle nada y compartir tú el link.
Correo del comprador. Requerido con delivery email o both.
WhatsApp del comprador. Requerido con delivery whatsapp o both.
Hasta tres correos que reciben copia (cuentas por pagar, un gerente)
NIT del comprador para su factura. Vacío es consumidor final.
Referencia opcional del ERP, única por cuenta y ambiente para siempre,
incluso si la orden se anula o elimina. Distingue mayúsculas y
minúsculas y conserva espacios; no acepta texto vacío ni solo espacios.
Solo se asigna al crear: no se puede cambiar ni agregar con PATCH
(422 external_reference_immutable). null al crear equivale a omitirla.
El número con el que el comprador archiva su orden de compra. Va en el asunto del correo, la factura y la página de pago.
Días de crédito desde que se envía. Por defecto, 30.
Fecha de vencimiento propia, a partir de mañana. Reemplaza a net_days.
false envía la orden sin factura. Solo aplica si tu cuenta emite facturas electrónicas con Recurrente.
false envía la orden con sus recordatorios en pausa.
Cliente comprador, de esta cuenta y del ambiente de tu llave (como lo ve GET /customers). Su nombre, correo, WhatsApp y NIT llenan lo que no envíes; un buyer_name que envíes queda en la orden, sin renombrar al cliente. Sin él, al comprador se le encuentra o se le crea por su correo o su WhatsApp.
Hasta 50 llaves (de 40 caracteres) con valores de hasta 500 caracteres. Al editar se combina con la que tiene; una llave en null se borra.
true la envía en la misma llamada, como POST /purchase_orders/{purchase_order_id}/finalization. Si la factura no se certifica, la respuesta es 201 con la orden en draft y tax_invoice.status: failed.
Response
draft no se ha enviado (o su factura no se certificó); open se
envió y se debe; paid se pagó, con su link o afuera; void se
anuló; uncollectible se dio por perdida, aunque su link sigue
cobrando.
Abierta y con la fecha de vencimiento ya pasada. «Vencida» no es un estado.
Número de la orden con su prefijo, como lo ve el comprador
Referencia inmutable del ERP; también se incluye en los webhooks
Qué vende, como lo lee el comprador
La metadata que tu integración le puso
Lo que se registró como pagado fuera de Recurrente, en centavos
Lo que el comprador todavía debe, en centavos. 0 si está pagada o anulada.
Pagos registrados fuera de Recurrente, del más antiguo al más reciente
Días de crédito desde que se envió. null cuando la orden tiene una fecha de vencimiento propia.
Fecha en que se envió. null en borrador.
Fecha en que el comprador prometió pagar, si la registraste en el dashboard
Los recordatorios automáticos están en pausa
Por qué se anuló
Nombre o razón social del comprador como se escribió en la orden (lo que envió buyer_name, o el nombre del cliente). Renombrar al cliente después no lo cambia.
Correo al que se envía la orden
WhatsApp al que se envía la orden
NIT de la factura. null es consumidor final.
El número con el que el comprador archiva su orden de compra
La orden se envía con factura electrónica
La factura de la orden tal como está (el último intento de certificarla). null si no se ha intentado.

