Skip to navigation

Editar una orden de compra

Edita un borrador, como actualizar una factura en borrador en Stripe: cambia solo lo que envíes, con los mismos campos que al crearla, y conserva lo demás: si solo mandas amount_in_cents, conserva su moneda; si solo mandas currency, su monto. Para cambiar la moneda de una orden con items, manda también sus items. Al editarla se le abre un link nuevo (checkout_url cambia; el anterior nunca le llegó a nadie y abre como vencido).

external_reference no se puede cambiar, ni siquiera en borrador (422 external_reference_immutable).

Una orden ya enviada solo cambia su metadata; cualquier otro campo responde 422 con code: not_draft.

Authentication

X-SECRET-KEYstring

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.

Path parameters

idstringRequired
ID de la orden de compra

Headers

X-ACCOUNT-IDstringOptional

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

This endpoint expects an object.
amount_in_centsintegerOptional

Monto de la orden, en centavos. Envía este o items.

currencystringOptional
Moneda del monto. Por defecto, la moneda principal de tu cuenta.
itemslist of objectsOptional

Productos de tu tienda que vende la orden. Envía este o amount_in_cents.

descriptionstringOptional<=100 characters

Qué vende la orden, como lo lee el comprador. Solo con amount_in_cents; sin ella, la línea se llama como la orden.

buyer_namestringOptional

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.

deliveryenumOptionalDefaults to email

Por dónde le llega la orden al comprador: email, whatsapp, ambos (both), o link para no enviarle nada y compartir tú el link.

Allowed values:
buyer_emailstringOptional

Correo del comprador. Requerido con delivery email o both.

buyer_phonestringOptional

WhatsApp del comprador. Requerido con delivery whatsapp o both.

cc_emailslist of stringsOptional

Hasta tres correos que reciben copia (cuentas por pagar, un gerente)

buyer_tax_idstringOptional

NIT del comprador para su factura. Vacío es consumidor final.

external_referencestring or nullOptional1-255 characters

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.

buyer_referencestringOptional<=60 characters

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.

net_daysenumOptional

Días de crédito desde que se envía. Por defecto, 30.

Allowed values:
due_ondateOptional

Fecha de vencimiento propia, a partir de mañana. Reemplaza a net_days.

issue_tax_invoicebooleanOptional

false envía la orden sin factura. Solo aplica si tu cuenta emite facturas electrónicas con Recurrente.

contract_template_idstringOptional
Plantilla de contrato que el comprador firma antes de poder pagar
send_remindersbooleanOptionalDefaults to true

false envía la orden con sus recordatorios en pausa.

customer_idstringOptional

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.

metadatamap from strings to anyOptional

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.

Response

Orden editada
idstringOptional
ID de la orden de compra
statusenumOptional

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.

Allowed values:
overduebooleanOptional

Abierta y con la fecha de vencimiento ya pasada. «Vencida» no es un estado.

referencestringOptional

Número de la orden con su prefijo, como lo ve el comprador

external_referencestring or nullOptional

Referencia inmutable del ERP; también se incluye en los webhooks

prefixstringOptional
numberintegerOptional
Consecutivo de la orden en tu cuenta
descriptionstring or nullOptional

Qué vende, como lo lee el comprador

checkout_urlstringOptional
Link donde el comprador paga la orden. No vence mientras la orden se deba.
metadatamap from strings to anyOptional

La metadata que tu integración le puso

currencystringOptional
total_in_centsintegerOptional
Total de la orden, en centavos
amount_paid_out_of_band_in_centsintegerOptional

Lo que se registró como pagado fuera de Recurrente, en centavos

amount_remaining_in_centsintegerOptional

Lo que el comprador todavía debe, en centavos. 0 si está pagada o anulada.

paymentslist of objectsOptional

Pagos registrados fuera de Recurrente, del más antiguo al más reciente

net_daysinteger or nullOptional

Días de crédito desde que se envió. null cuando la orden tiene una fecha de vencimiento propia.

issued_ondate or nullOptional

Fecha en que se envió. null en borrador.

due_ondate or nullOptional
Fecha de vencimiento
promised_ondate or nullOptional

Fecha en que el comprador prometió pagar, si la registraste en el dashboard

reminders_pausedbooleanOptional

Los recordatorios automáticos están en pausa

void_reasonstring or nullOptional

Por qué se anuló

customer_idstringOptional
ID del cliente comprador
buyer_namestringOptional

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.

buyer_emailstring or nullOptional

Correo al que se envía la orden

buyer_phonestring or nullOptional

WhatsApp al que se envía la orden

buyer_tax_idstring or nullOptional

NIT de la factura. null es consumidor final.

buyer_referencestring or nullOptional

El número con el que el comprador archiva su orden de compra

cc_emailslist of stringsOptional
Correos que reciben copia
tax_invoice_requestedbooleanOptional

La orden se envía con factura electrónica

tax_invoiceobject or nullOptional

La factura de la orden tal como está (el último intento de certificarla). null si no se ha intentado.

sent_atdatetime or nullOptional
paid_atdatetime or nullOptional
voided_atdatetime or nullOptional
uncollectible_atdatetime or nullOptional
created_atdatetimeOptional
updated_atdatetimeOptional

Errors

422
Unprocessable Entity Error