Skip to main content
Una factura es un cobro numerado por una o más de tus variantes, dirigido a un cliente. Una variante es una configuración de precio y facturación que vendes, normalmente para un producto. Su ID empieza por plan_, y los artículos de la factura la reciben como plan_id. Usa una factura cuando acuerdes un precio con un cliente antes de que pague, como un presupuesto, un servicio o un pedido de empresa. Construyes un borrador hasta que esté correcto y luego lo emites para fijar los totales y abrirlo para el pago. Enviarlo hace eso y además lo manda por correo en una sola llamada. Para enviar una desde tu panel sin código, consulta Crea y envía facturas.
Las facturas de esta página necesitan Api-Version-Date: 2026-10-24 o posterior en cada solicitud. Las solicitudes con una versión anterior llegan a la API de facturas heredada, que funciona de otra manera. Consulta Antes de empezar.

Cómo funciona una factura

Una factura nativa es un pago. Su ID empieza por pay_ y se mantiene igual después de que el cliente pague, así que también puedes leerla con Retrieve Payment. Cada factura recibe además el siguiente número de la secuencia propia de tu cuenta, como #00000042, o #ACME-00000042 cuando tu cuenta tiene un prefijo de factura.
  1. Creas un borrador con artículos, un cliente y datos de facturación. Un borrador no cobra nada ni envía correos a nadie.
  2. Lo emites o lo envías. Emitirla calcula el impuesto final y abre la factura para el pago. Enviarla la emite y la manda por correo, ya sea ahora o en el momento que programes.
  3. El cliente paga. Whop cobra el método de pago guardado del cliente en cuanto emites o envías la factura, o el cliente paga a través del checkout alojado de Whop.
  4. Realizas el fulfillment del pedido desde el webhook payment.succeeded.
Las facturas cobran variantes de compra inmediata, las que tienen release_method: buy_now en lugar de una lista de espera. Una variante de pago único se cobra una vez, y una variante recurrente inicia una suscripción cuando se paga la factura. Consulta Factura una suscripción, que también explica cómo detenerla después de un número determinado de pagos.

Antes de empezar

Envía la versión de la API

/invoices sirve dos APIs diferentes, y el Api-Version-Date al que se resuelve tu solicitud decide cuál responde. Emitir, enviar, cancelar un envío programado y generar un PDF existen solo en la API nativa, así que llegan a las facturas nativas sea cual sea la versión que envíes. Las rutas que tienen ambas APIs, como GET /invoices y POST /invoices/{id}/void, siguen la versión. Envía el encabezado en cada solicitud en lugar de depender de la versión fijada de una clave, para que cambiar de clave nunca te mueva entre ambas. Versiones de la API explica las versiones fijadas y el changelog. La API nativa no lista ni recupera las facturas heredadas inv_, y la API heredada no devuelve las nativas.

Llama a la API

Los ejemplos de esta página llaman a la API mediante un pequeño helper que envía el encabezado de versión en cada solicitud.
Envía una Idempotency-Key en cada POST para que un reintento nunca cree una segunda factura ni repita una acción. Generate Invoice PDF es la excepción: cada llamada crea un archivo nuevo, así que no reproduce respuestas.

Crea un borrador

Create Invoice guarda un borrador con POST /invoices.
La respuesta es 201 Created con el borrador. Crear un borrador no cobra nada, no envía correos y no envía webhooks. Esta respuesta muestra un subconjunto de los campos:
account_id es la cuenta que emite la factura, con el prefijo biz_. Una clave de API de cuenta puede omitirlo para usar su propia cuenta. Create Invoice enumera todos los campos de solicitud y respuesta. Un borrador usa su número al crearlo, así que un borrador que descartas deja un hueco en tu secuencia. Para descartar un borrador, elimínalo. Para mantenerlo en tu lista, anúlalo en su lugar.

Añade artículos

items acepta de 1 a 50 artículos. Cada artículo recibe plan_id para una variante existente o plan para encontrar o crear una en línea, además de una quantity opcional. Un plan en línea usa la misma entrada de búsqueda o creación que Create Payment, por ejemplo { "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }. Necesita plan:create, y un product en línea también necesita el permiso de producto, access_pass:create o access_pass:update. La creación y la actualización rechazan los artículos que incumplen estas reglas:
  • Cada artículo es una variante de compra inmediata de tu cuenta. Una variante aparece una sola vez, así que usa quantity para más unidades.
  • Ninguna variante está archivada, y emitir o enviar un borrador lo vuelve a comprobar, así que desarchiva la variante o elige otra.
  • quantity está entre 1 y 999,999, y es mayor que 1 solo para una variante que permite varias cantidades. Las variantes recurrentes no lo permiten, así que la cantidad de un artículo recurrente es 1.
  • Una variante recurrente debe pertenecer a un producto.
  • Todos los artículos usan la misma moneda.
  • En una factura con varios artículos, cada artículo que tenga un producto debe ser un producto regular (el tipo de producto estándar), no una app. Los artículos recurrentes comparten un mismo periodo de facturación, duración de prueba gratuita y split_pay_required_payments, y todos los artículos necesitan ajustes de pago, impuestos y acceso compatibles. Las variantes con campos personalizados o contraseña no se pueden combinar. Los artículos sin producto, como una tarifa personalizada, pueden ir junto al resto.
Cada línea de la respuesta tiene un label, que es el título del producto, o el título de la variante si la variante no tiene producto. El correo, el PDF y el checkout lo muestran. El borrador conserva el precio que tenía cada variante cuando guardaste sus artículos, así que un cambio de precio posterior en la variante no altera la factura. Un artículo de pago único se cobra a su precio. A partir de la versión de la API 2026-11-11, crear o sustituir un artículo recurrente incluye su initial_price más su renewal_price en la primera factura. Las versiones fijadas anteriores usan solo el precio de renovación. Las ediciones que omiten items conservan los precios guardados.

Define el cliente y los datos de facturación

Envía member_id o email_address, y billing_address o mailing_address_id, nunca ambos de un par. Una dirección de facturación necesita un cliente. El cliente es opcional en un borrador y obligatorio para emitirlo. Whop calcula el impuesto cuando emites la factura, usando la dirección de facturación para ubicar al cliente. Cuando se aplican impuestos y Whop no puede saber dónde está el cliente, la emisión se rechaza, así que añade una dirección de facturación siempre que cobres impuestos.

Edita un borrador

Update Invoice modifica un borrador con PATCH /invoices/{id}. Envía solo los campos que cambias.
  • items sustituye la lista completa y lee el precio actual de cada variante. Omítelo para conservar los artículos y precios guardados.
  • Cambiar member_id elimina la dirección de facturación y el método de pago guardados, a menos que envíes otros nuevos. Conserva recipient_emails, así que envía también una lista nueva, o el cliente anterior seguirá recibiendo el correo de la factura.
  • No se aceptan email_address ni customer_name. Envía un member_id diferente para facturar a otra persona.
  • Un borrador con un envío programado solo acepta un cambio en recipient_emails hasta que canceles el envío.
  • Una vez emitida la factura, el único cambio que puedes hacer es recipient_emails, enviado por sí solo, y solo mientras la factura esté open o uncollectible. Cualquier otra edición se rechaza con un 400.

Elige cómo paga el cliente

Hay dos formas de cobrar una factura emitida. Elige una antes de emitirla, porque el método de pago guardado va en el borrador. Una factura emitida recibe un checkout_link aunque tenga un método de pago guardado. Si el cobro automático falla, el cliente puede seguir pagando a través del checkout.

Cobra un método de pago guardado

Añade un método de pago guardado al borrador con payment_method_id. Debe ser uno de los métodos guardados del cliente. Guarda métodos de pago muestra cómo un cliente guarda uno, y List payment methods encuentra los que tiene un miembro. Cuando emites o envías la factura y su total es mayor que cero, Whop:
  1. Ejecuta las mismas comprobaciones que Create Payment ejecuta sobre un método de pago guardado.
  2. Reserva stock para las cantidades facturadas y prepara las comisiones del pago.
  3. Devuelve la factura como open y cobra el método fuera de sesión. El cobro se ejecuta en el charge_at que pasas a Issue Invoice o Send Invoice; si no, en due_at mientras aún sea futuro; si no, de inmediato. scheduled_charge_at muestra un cobro que aún está por llegar.
La respuesta no te dice si el cobro se realizó correctamente. Realiza el fulfillment desde el webhook payment.succeeded para el ID pay_ de la factura. Una factura pagada completa la membresía, y tu metadata queda en el cobro y en la membresía. Reglas de pago en los pagos de facturas explica cómo tus reglas de pago filtran el cobro.

Si se rechaza el cobro automático

Un cobro rechazado deja la factura en open y libera el stock reservado. Recupera la factura como un pago y lee failure_message para saber por qué falló el último intento. Cuando el cobro se rechaza o requiere que el cliente actúe, Whop envía por correo el enlace de pago de la factura a sus destinatarios, para que el cliente pueda pagar a través del checkout. Es el único correo que Whop envía para una factura que emites sin enviarla. Necesita un checkout_link y al menos una entrada en recipient_emails, y no cuenta para el límite de envíos.
Un cobro fuera de sesión no puede mostrar al cliente un desafío 3D Secure. Si su banco lo pide, el cobro automático no se completa y la factura sigue sin pagar hasta que el cliente se autentique o pague de otra forma.

Emite la factura

Issue Invoice convierte un borrador en una factura abierta. Whop vuelve a comprobar la factura, calcula el impuesto final y establece status en open y totals_status en final. Cuando la factura tiene un método de pago guardado y un total mayor que cero, Whop lo cobra a continuación, como se describe en Cobra un método de pago guardado.
  • El impuesto pasa a ser final. tax_amount es null en un borrador y se establece al emitirlo. total y amount_due lo incluyen.
  • Whop crea la membresía del cliente cuando la factura cobra un producto. Permanece en borrador, sin acceso, hasta que se paga la factura. Una factura cuyos artículos no tienen ningún producto no recibe membresía.
  • payment.created se dispara una vez para el ID pay_ de la factura.
  • Volver a emitir es seguro. Emitir una factura que ya está open vuelve a ejecutar las mismas comprobaciones y, si se superan, la devuelve sin cambios: sus totales se mantienen y no se vuelve a cobrar nada.
  • Emitir no envía la factura por correo, salvo el enlace de pago tras un cobro rechazado. Para enviar la factura por correo, envíala en su lugar, o entrega tú mismo el enlace de checkout.
Una emisión rechazada no cambia nada ni cobra nada. Corrige la causa y vuelve a emitir la factura. Errores de emisión enumera los motivos. Una factura emitida y open lleva un checkout_link, un valor firmado con el formato pay_xxxxxxxxxxxxx.<signature>. Abre la factura en el checkout alojado de Whop a su precio fijo.
1

Lee el enlace de la factura emitida

checkout_link es null a menos que la factura esté open, así que los borradores y las facturas pagadas, anuladas o incobrables no tienen ninguno. También es null para una factura emitida a un comprador empresarial, para una cuya membresía se canceló y cuando tu credencial no tiene payment:charge. Un comprador empresarial es un cliente que es otra cuenta de Whop en lugar de una persona.
2

Construye la URL del checkout alojado

Divide el enlace por su primer .: el ID pay_ de la factura va antes y el token después.
3

Envíaselo al cliente

Envía la factura para que Whop mande el enlace por correo, o pon la URL en tu propio correo o página de factura. Solo el cliente de la factura puede pagar a través de él. Cualquier otra persona es rechazada y se le pide que inicie sesión como el cliente de la factura. El enlace deja de funcionar una vez que la factura se paga, se anula o se marca como incobrable.
4

Realiza el fulfillment desde el webhook

Escucha payment.succeeded para el ID pay_ de la factura, igual que con el cobro automático. Webhooks muestra un handler.
El checkout muestra el número de la factura y la fecha de vencimiento junto a sus artículos, y la fecha de vencimiento se vuelve roja una vez pasada. El cliente paga los artículos y el total de la factura y no puede añadir un código promocional.

Envía, programa y recuerda

Send Invoice envía una factura por correo con POST /invoices/{id}/send. Enviar un borrador primero lo emite, igual que Issue Invoice. Enviar una factura open la vuelve a mandar por correo.
El correo muestra el nombre y el logotipo de tu cuenta, el número de factura, el total, la fecha de vencimiento, cada artículo y un botón que abre el checkout de la factura. Whop solo envía por correo una factura que el cliente pueda pagar desde el correo. Una factura open necesita un checkout_link para enviarse, y un borrador necesita un cliente que no sea un comprador empresarial. Un borrador facturado a un comprador empresarial aún puede enviarse cuando tiene un método de pago guardado, porque en su lugar se cobra.

Quién recibe el correo

Cada envío manda un correo a cada dirección una vez, como un correo separado, para que los destinatarios nunca vean las direcciones de los demás. Las direcciones son:
  • El correo de la cuenta de Whop del cliente, que el PDF de la factura imprime bajo Bill to.
  • Cada entrada de recipient_emails.
Whop guarda recipient_emails en minúsculas y elimina los duplicados de la lista, así que una dirección que aparece en ambos recibe un solo correo. Un recipient_emails vacío significa que Whop no envía correos a nadie, incluido el cliente. Úsalo para evitar que Whop envíe una factura por correo:
  • Send Invoice rechaza la factura, a menos que en su lugar cobre un método de pago guardado.
  • No se envía ningún enlace de pago después de un cobro rechazado.
  • No se envían recordatorios. Vaciar recipient_emails en una factura open detiene sus recordatorios restantes.

Cuándo Whop cobra en lugar de enviar el correo

Un borrador con un payment_method_id y un total mayor que cero se cobra en lugar de enviarse por correo, igual que cuando lo emites. Si se rechaza el cobro automático explica qué ocurre cuando el cobro falla. Un borrador así puede enviarse con recipient_emails vacío, porque nadie necesita el correo.

Límite de envíos

Cada factura puede enviarse por correo tres veces en 24 horas, incluido el envío que la emitió. Un cuarto envío en ese intervalo se rechaza con un 429 cuyo error.code es invoice_send_limit_reached. Los recordatorios, el enlace de pago tras un cobro rechazado y un envío que cobra en lugar de mandar un correo no cuentan para el límite.

Programa un envío

Para enviar un borrador más tarde, pasa send_at. El borrador sigue siendo un borrador y muestra la hora en scheduled_send_at. En ese momento, Whop lo envía como si hubieras llamado a Send Invoice entonces.
  • Solo se puede programar un borrador, y send_at debe estar en el futuro. Whop comprueba los destinatarios y el enlace de pago al programarlo, igual que en un envío inmediato.
  • Vuelve a enviar con un nuevo send_at para cambiar la hora.
  • La edición queda bloqueada hasta que se produce el envío o lo cancelas. Una actualización que solo cambia recipient_emails sigue funcionando, pero no puede eliminar el último destinatario de un borrador que no se va a cobrar.
  • Cancel Scheduled Send con POST /invoices/{id}/unschedule. scheduled_send_at vuelve a null y el borrador se puede editar de nuevo. Cancelar una factura sin envío programado la devuelve sin cambios.
  • Anular un borrador programado detiene su envío programado.
Whop busca envíos pendientes cada minuto, así que un envío programado sale aproximadamente en el minuto siguiente a send_at. Si se rechaza, por ejemplo porque se eliminó una variante después de programarlo, la factura sigue siendo un borrador, scheduled_send_at vuelve a null y la API no devuelve el motivo. Cualquier otro fallo se reintenta aproximadamente cada 10 minutos, hasta 12 intentos en total. Hasta que un intento tiene éxito o Whop deja de reintentar, scheduled_send_at muestra la hora del siguiente intento en lugar de null. Lee la factura después de send_at para confirmar que está open.

Recordatorios

Cuando Send Invoice envía por correo una factura que tiene due_at, Whop también programa recordatorios 1, 3, 7, 14, 30 y 60 días después de due_at, omitiendo los que ya hayan pasado. Cada recordatorio va a las mismas direcciones que la factura e indica cuántos días lleva vencida. Los recordatorios solo se envían mientras la factura está open, así que se detienen una vez que se paga, se anula o se marca como incobrable. Un recordatorio que vence mientras hay un pago en curso espera hasta que el pago termina. Una factura que emites sin enviar, o una que se cobra en lugar de enviarse por correo, no recibe recordatorios.

Historial de correos

List Invoice Sends devuelve los lotes de correo registrados con GET /invoices/{id}/sends, del más reciente al más antiguo. Incluye correos iniciales y repetidos, correos programados, recordatorios y seguimientos de pago tras un cobro fallido a un método de pago guardado. Usa la primera entrada para el envío registrado más reciente, y page_info.end_cursor como after para leer entradas más antiguas. Los lotes manuales usan send cuando la factura no tiene historial de correos completados anterior y resend en caso contrario. El tipo se selecciona cuando se registra el lote completado, así que las solicitudes encoladas juntas se clasifican por orden de finalización. Los correos anteriores no registrados siguen siendo desconocidos. Cada entrada contiene kind, sent_at, recipient_count, recipients y actor. Leer el historial requiere payment:basic:read. Las direcciones también requieren member:email:read. Sin él, recipients está vacío. El remitente requiere además company:authorized_user:read. De lo contrario, actor es null. Los envíos automáticos y las claves de API de cuenta también tienen un actor null. El worker añade una entrada después de enviar el lote completo para su entrega. Para un lote parcial, añade una entrada solo si un reintento completa el lote. La entrada conserva la lista original de destinatarios. Un lote registrado no confirma la entrega en la bandeja de entrada. El sistema de correo puede suprimir mensajes si la factura o los destinatarios cambian antes de la entrega. El historial excluye los correos enviados antes de que se introdujera esta función. Emitir una factura sin enviarla por correo no añade ninguna entrada al historial.

Descarga un PDF

Generate Invoice PDF genera la factura como PDF y devuelve un enlace de corta duración a ella. Necesita payment:basic:read y funciona con cualquier estado.
La respuesta tiene url y expires_at. El enlace funciona durante 15 minutos, y cualquiera que lo tenga puede descargar el archivo. Genera uno nuevo cuando caduque. El PDF destaca tu negocio: el nombre de tu cuenta encabeza la página, y el pie indica que Whop Inc emite la factura en tu nombre y por tu cuenta. Muestra el número de factura, su fecha y fecha de vencimiento, y los datos de Bill to. Cada artículo muestra su cantidad, precio unitario e importe, seguidos del subtotal, la tarifa de servicio, el impuesto y el importe adeudado. Una factura con un artículo recurrente también indica el importe de renovación y con qué frecuencia se renueva. El PDF de un borrador muestra sus totales estimados, con el impuesto en cero hasta que lo emitas. Parte del contenido depende de los permisos de tu credencial:

Factura una suscripción

Añade una variante recurrente a una factura para iniciar una suscripción cuando el cliente la pague. Después, Whop la renueva una vez por periodo de facturación.
  1. La factura cobra el primer periodo y cualquier tarifa inicial. Un artículo recurrente debe pertenecer a un producto y tiene una cantidad de 1. A partir de la versión de la API 2026-11-11, su primera factura cobra initial_price más renewal_price. El pago inicia de inmediato el primer periodo de facturación pagado, a menos que la variante tenga una prueba gratuita. En ese caso, la suscripción empieza con la prueba. En el panel, un artículo recurrente personalizado tiene un campo opcional Upfront fee. El initial_price de la línea indica esa parte única de unit_amount, y la página de la factura, el correo y el PDF la muestran en su propia línea Upfront fee.
  2. Pagar la factura inicia la suscripción, tanto si Whop cobra el método de pago guardado al emitirla como si el cliente paga a través del checkout_link. El primer periodo empieza con el pago. El checkout abierto desde el enlace indica el importe de renovación, incluida la comisión del comprador de la factura, y con qué frecuencia se renueva.
  3. Cada renovación se cobra de la forma que elegiste al emitir o enviar la factura. Solo cobra los artículos recurrentes, con la comisión del comprador de la factura, al precio de renovación que tenía cada variante cuando emitiste la factura. Puede diferir del precio guardado en el borrador si el precio de la variante cambió después de guardar los artículos. Los artículos de pago único se cobran una vez.
Pasa collection_method a Issue Invoice o Send Invoice para elegir cómo se cobran las renovaciones. Un envío programado aplica el collection_method con el que lo programaste, que el borrador muestra como scheduled_collection_method. send_invoice necesita al menos una dirección en recipient_emails y no está disponible para facturas emitidas a una empresa. Mientras se aplique, no se puede eliminar el último destinatario de la factura. Una factura sin artículos recurrentes rechaza collection_method. Pagar la primera factura con tarjeta conserva send_invoice. Cada renovación es su propio pago, con su propio ID pay_ y sus propios webhooks payment.*. Una renovación charge_automatically no es una factura numerada, así que no aparece en List Invoices. Una renovación send_invoice es una factura numerada en List Invoices, y Whop no la cobra automáticamente. La suscripción permanece en past_due hasta que el cliente paga a través del checkout_link de la factura. Mientras tanto, el cliente conserva el acceso. Cancela la membresía para detener las renovaciones. Una vez cancelada la membresía, el checkout_link de una factura de renovación abierta deja de funcionar. Para encontrar la suscripción, recupera la factura como un pago y lee su membership_id, que necesita member:basic:read.

Empieza con una prueba gratuita

Una factura respeta el trial_period_days de una variante recurrente, igual que el checkout. La primera factura cobra solo el initial_price de la variante. Pagarla inicia la prueba, y la primera renovación cobra renewal_price cuando termina la prueba. Las facturas creadas antes del 2026-11-16 a las 17:00 UTC cobran el primer periodo y omiten la prueba.
  • Un cliente que ya tuvo una suscripción a la variante no recibe prueba. Su primera factura cobra initial_price más renewal_price. Las facturas de renovación nunca inician una prueba.
  • La prueba viene de la variante. Para un artículo recurrente personalizado, establece variant.trial_period_days. Un trial_period_days a nivel de artículo se rechaza.
  • Todos los artículos recurrentes de la factura necesitan la misma duración de prueba.
  • Cuando la factura no cobra nada, emítela o envíala con un payment_method_id, que inicia la prueba de inmediato, o con collection_method: "send_invoice".
  • En el panel, un artículo recurrente personalizado tiene un campo Free trial days. El plan de facturación de un producto muestra su propia prueba.

Detén la suscripción tras un número determinado de pagos

Para cobrar un plan de pagos fijo, como seis pagos mensuales, establece split_pay_required_payments en la variante recurrente, de 2 a 115. La factura es el primer pago, incluida cualquier tarifa inicial. Por ejemplo, una tarifa inicial de $75 con tres cuotas de $40 cobra $115, luego $40 y luego $40. Whop deja de renovar una vez realizados esos pagos, y la membresía sigue activa. El cliente no puede cancelar la suscripción por su cuenta antes de ese momento, pero tú sí. Déjalo sin definir para renovar hasta que se cancele la suscripción.

Estados y ciclo de vida

status toma sus valores de los pagos, así que una factura también puede mostrar un estado de pago como pending mientras hay un pago en curso. totals_status indica si los campos de dinero son finales: estimated mientras la factura es un borrador, final después de emitirla. overdue es true para una factura open o uncollectible cuyo due_at ya pasó.

Anula o marca como incobrable

Void Invoice cancela una factura draft, open o uncollectible. Anular una factura que ya está anulada la devuelve sin cambios, y una factura pagada no se puede anular. Marca una factura como incobrable para registrar que no esperas cobrarla. Solo se puede marcar una factura open, y volver a marcar una factura incobrable la devuelve sin cambios. Una factura incobrable no tiene checkout_link y no recibe recordatorios. Este ejemplo marca una factura open como incobrable y luego la anula:

Elimina una factura

Delete Invoice elimina una factura draft o void con DELETE /invoices/{id}. La respuesta es { id, deleted: true }. Una factura eliminada ya no aparece en List Invoices ni en List Payments, y su ID devuelve un 404. No puedes deshacer una eliminación. Anula una factura open antes de eliminarla. Un borrador con un envío o cobro programado necesita primero Cancel Scheduled Send. Un borrador de factura de renovación no se puede eliminar mientras cobre una suscripción. Una factura anulada que recaudó dinero o que aún espera una transferencia bancaria no se puede eliminar, como tampoco una factura pagada, pendiente o incobrable. El campo deletable de una factura es true cuando se puede eliminar. Eliminar necesita invoice:update o payment:charge. El número de un borrador eliminado no se reutiliza.

Lista y recupera facturas

List Invoices devuelve las facturas que tu credencial puede leer, de la más reciente a la más antigua. Una clave de API ve su propia cuenta, y un token de usuario ve todas las cuentas cuyos pagos puede leer el usuario. Acota la lista con estos parámetros de consulta: Un borrador programado es uno con scheduled_send_at. Una factura open nunca está programada, ni tampoco un borrador que se envía en su fecha de vencimiento. Ordena con order (created_at, due_at o scheduled_send_at) y direction (asc o desc). Ordenar por due_at o scheduled_send_at coloca al final las facturas sin esa fecha. La respuesta es { data, page_info }. Mientras page_info.has_next_page sea true, pasa page_info.end_cursor como after para leer la página siguiente.
Retrieve Invoice lee una factura por su ID pay_. List Payments omite los borradores. Para exportar facturas como archivo CSV, llama a Create Export con resource: "receipt_invoices". Necesita payment:basic:read y payment:basic:export. Las columnas del cliente solo aparecen cuando tu credencial también tiene member:basic:read o member:email:read.

Webhooks

Las facturas nativas envían webhooks de pago para su ID pay_. Los eventos invoice.* pertenecen a la API de facturas heredada, y las facturas nativas no los envían. Otros eventos payment.*, como payment.failed, también pueden llegar para el ID pay_ de la factura a medida que cambian sus intentos de pago. Suscríbete a ellos con la guía de webhooks. Para realizar el fulfillment de un pedido, guarda el id de la factura con el pedido cuando crees el borrador. El data de un evento payment.succeeded es el pago, así que data.id es el ID pay_ de la factura. Después de verificar el evento, busca el pedido por ese ID. En este handler, orders representa tu propio almacén de pedidos:
Comprobar fulfilled evita que un evento reenviado realice el fulfillment del pedido dos veces. Las renovaciones de suscripción tienen sus propios ID pay_, así que no coinciden con una factura.

Reglas de pago en los pagos de facturas

Tus reglas de pago se ejecutan sobre los pagos de facturas después del propio filtrado antifraude de Whop, como en cualquier checkout. Lo que pueden hacer depende de si el cliente está presente.
  • El cobro automático al emitir es fuera de sesión. Una regla block lo rechaza, y una regla allow lo exime de tus demás reglas. Las reglas review y enforce_3ds se omiten porque el cobro es fuera de sesión.
  • Un pago a través del enlace de checkout es en sesión. Se aplican las cuatro acciones, con los límites de elegibilidad de Gestiona el fraude.
En el cobro automático, las condiciones de tarjeta leen el método de pago guardado y las condiciones de facturación leen la dirección de facturación de la factura. customer_email es el correo de la cuenta de Whop del cliente. El payment_rule_matches del pago enumera la regla que lo decidió. Una regla omitida no aparece.

Facturas en el panel

La página Invoices lista, crea y envía facturas nativas. Las facturas heredadas están en su pestaña Legacy invoices, que se explica en Envía una factura.

Permisos

Toda escritura necesita payment:charge, el mismo permiso que Create Payment, y toda lectura necesita payment:basic:read. Los permisos invoice:* pertenecen a la API de facturas heredada, y las facturas nativas no los usan. Una creación o actualización que envía un artículo plan en línea también necesita plan:create. Algunos campos necesitan un permiso propio. Sin él, el campo vuelve como null, y recipient_emails vuelve vacío. Si tu credencial pierde uno de estos permisos de lectura después de un POST, repetirlo con la misma Idempotency-Key se rechaza con un 403 cuyo error.code es invoice_replay_permission_revoked cuando la respuesta almacenada muestra esos campos. En su lugar, obtén la factura con GET. Añade permisos desde la guía de permisos.

Errores

Los rechazos vuelven como { error: { type, message, code } }. Todos los códigos siguientes son 400 salvo que se indique lo contrario. Un plan_id, member_id, mailing_address_id o payment_method_id desconocido es un 404, y una marca de tiempo que Whop no puede leer es un 400 con invalid_timestamp. Estos rechazos son un 400 sin error.code, así que lee error.message para conocer el motivo:
  • Un campo de nivel superior desconocido.
  • Una quantity fuera del rango de 1 a 999,999.
  • Una dirección no válida en recipient_emails, o más de 50.
  • Una regla de varios artículos incumplida, como una discrepancia en el periodo de facturación.

Errores de creación y actualización

Errores de emisión

Errores de envío y programación

Enviar un borrador lo emite, así que un envío también puede rechazarse por cualquiera de los motivos de Errores de emisión.

Otros errores

Anular una factura pagada es un 400 sin código.

Próximos pasos

Referencia de la API de facturas

Todos los endpoints, parámetros y campos de respuesta de las facturas.

Guarda métodos de pago

Recopila el método de pago guardado que una factura cobra al emitirse.

Gestiona el fraude

Escribe las reglas de pago que filtran los pagos de facturas.

Escucha webhooks

Supervisa payment.created y payment.succeeded para tus facturas.