/invoices que las facturas heredadas, pero tienen un formato de solicitud y un ciclo de vida distintos. Esta guía mapea los campos y las acciones que debes cambiar al migrar una integración.
Las rutas compartidas dirigen a las facturas nativas a partir de
Api-Version-Date: 2026-10-24.
Los ejemplos nativos de abajo usan Api-Version-Date: 2026-11-02-1, con los
nombres de campo de variante actuales y las reglas de bloqueo de cliente. Envía ese encabezado en
cada solicitud nativa. Mantén las llamadas heredadas en una versión publicada anterior, como
2026-10-15-1. Versiones de la API explica cómo los encabezados
prevalecen sobre las versiones fijadas en las credenciales.Qué cambia
La API nativa no lista ni obtiene las facturas heredadas
inv_. Sigue consultando las facturas heredadas existentes con la versión anterior de la API. Crear una factura nativa crea una factura independiente. No convierte ni liquida una factura heredada.
Antes de migrar
Comprueba estas diferencias antes de trasladar un flujo. Mantenlo en la API heredada si necesita una función que la API nativa no ofrece.Mapea la solicitud de creación
Una creación heredada envía un plan y, opcionalmente, etiquetas que dividen su precio. Una creación nativa envía un ítem por cada variante facturada. Estos ejemplos fijan un precio combinado de los ítems de 19.99 USD. La variante nativa existente representa el cargo de configuración de 15 USD. La comisión de servicio de 4.99 USD es un cargo personalizado de pago único sin producto. Ambas APIs aceptan precios en unidades de moneda. Usa4.99 para 4.99 USD. Enviar 499 factura 499 USD.
POST /invoices/{id}/send para emitirlo y enviarlo por email. member_id identifica a un cliente (mber_), no una suscripción (mem_).
En las versiones nativas anteriores a
2026-10-27-2, usa plan_id, plan y plan_type en lugar de variant_id, variant y billing_type. Las líneas de la respuesta también usan plan_id en esas versiones anteriores.
Mantén bloqueados los importes emitidos
PATCH /invoices/{id} edita los ítems y los datos de facturación de un borrador. Enviar items reemplaza la lista completa usando los precios actuales de las variantes. Omitirlo conserva los ítems y precios guardados.
- Cancela un envío programado antes de editar ítems o datos de facturación.
- A partir de
2026-11-02-1, no puedes reemplazar ni eliminar el cliente asignado a un borrador. Un borrador sin cliente todavía puede recibir uno. Anula el borrador antes de crear una factura nueva para otra persona. email_addressycustomer_nameson entradas exclusivas de la creación.- Los importes e ítems emitidos están bloqueados. Una actualización que solo contenga
memoy/orecipient_emailsestá permitida en facturasdraft,openyuncollectible, incluido un borrador programado.
Emite, envía y cobra
Una creación heredada elige el comportamiento de cobro concollection_method. Las facturas nativas usan llamadas separadas después de crear el borrador:
- Emítela con
POST /invoices/{id}/issuepara calcular el impuesto final y abrirla para el pago sin enviar el email inicial de la factura. - O envíala con
POST /invoices/{id}/send. Esto emite el borrador. Envía un email a los destinatarios, salvo que cobre de inmediato un método guardado. Enviar una facturaopenla vuelve a enviar por email.send_atprograma el envío de un borrador.POST /invoices/{id}/unschedulecancela esa programación. - Cobra un método guardado estableciendo
payment_method_iden el borrador. Para un total positivo, emitir o enviar cobra en uncharge_atfuturo; si no lo hay, en undue_atfuturo; y si tampoco, de inmediato.charge_atdebe ser en el futuro y no puede ser anterior asend_at.
open no confirma el pago. Espera a payment.succeeded antes de completar el pedido. Para cobrar o reintentar una factura abierta, usa Charge Invoice. Volver a emitirla o enviarla no inicia otro cobro.
En una variante recurrente, collection_method en Issue Invoice o Send Invoice controla las renovaciones. charge_automatically cobra automáticamente los pagos futuros. send_invoice crea y envía por email una factura nueva en cada periodo. No sustituye a payment_method_id para cobrar la primera factura. Consulta Factura una suscripción.
Mapea la respuesta
Para descargar un PDF, llama a
POST /invoices/{id}/generate_pdf y obtendrás un enlace de corta duración.
Abre el checkout de la factura
checkout_link contiene el ID de la factura y un token firmado separados por un .. Pasa el valor completo como link a POST /checkout_sessions para abrir una sesión para esta factura. Para obtener una URL para el cliente, sigue Crea la URL del checkout alojado.
El campo solo está presente mientras el checkout está disponible: la factura debe estar open. Los compradores empresariales y las membresías canceladas no pueden usar este checkout. Tu clave necesita payment:charge, o invoice:create/invoice:update cuando la factura no tiene un método de pago guardado. Es null en una factura en borrador, pagada, anulada o incobrable, y para compradores empresariales.
Mapea los estados
Las facturas nativas también pueden devolver
authorized, pending o unresolved. No trates todos los estados fuera del enum heredado como pagados o fallidos. Estados y ciclo de vida los explica.
Mapea los endpoints
Mapea los webhooks
Las facturas nativas envían eventos de pago para su IDpay_. Los eventos invoice.* describen las facturas heredadas.
Los eventos de pago también cubren pagos no relacionados con facturas. Haz coincidir el ID de pago del evento con los ID de facturas nativas que almacenas. Webhooks muestra cómo completar pedidos a partir de
payment.succeeded.
Permisos
member:basic:read expone los nombres de los clientes y los ID de miembros/membresías. member:email:read expone email_address y recipient_emails. Los campos de método de pago y dirección requieren payment:basic:read.
Lista de comprobación de la migración
- Consulta Antes de migrar para ver los flujos de trabajo que deben quedarse en la API heredada.
- Fija las llamadas nativas a una versión publicada que coincida con sus nombres de campo, como
2026-11-02-1para estos ejemplos. - Construye
itemsa partir de variantes elegibles, comprobando cantidades, precios, moneda y requisitos de producto. - Sustituye la creación heredada en una sola llamada por crear y después emitir o enviar. Elige cobros con método guardado para la primera factura y un método de cobro para las renovaciones.
- Mapea las fechas de vencimiento, los envíos programados y las comisiones al comprador según su comportamiento, no solo según sus nombres de campo.
- Mantén separados los ID nativos
pay_y los heredadosinv_. Mantén las lecturas heredadas en la versión anterior. - Lee los importes desde los objetos de dinero y abre el checkout con el
checkout_linkfirmado. - Gestiona
overduey los estados de pago adicionales. - Completa los pedidos a partir de
payment.succeededpara el ID de pago de la factura. - Concede los permisos que usa tu flujo, incluidos los de variante/producto en línea y los de lectura de clientes.
Próximos pasos
Guía de facturas
Crea, emite, envía y cobra facturas nativas.
Referencia de la API de facturas
Cada endpoint y campo de las facturas nativas.
API de facturas heredada
Los endpoints a los que llama tu integración actual.
Versiones de la API
Cómo funcionan
Api-Version-Date y las versiones fijadas.
