> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Migra desde las facturas heredadas

> Pasa de la API de facturas heredada a las facturas nativas: cambia la versión de la API, reconstruye las solicitudes en torno a ítems y mapea campos, estados y webhooks.

Las facturas nativas usan las mismas rutas `/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.

> [!NOTE]
>
> 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](https://docs.whop.com/es/developer/api/versioning.md) explica cómo los encabezados
> prevalecen sobre las versiones fijadas en las credenciales.

## Qué cambia

| | Facturas heredadas | Facturas nativas |
| - | - | - |
| **ID** | `inv_` | `pay_`, el mismo que el del pago de la factura |
| **Qué facturas** | Un plan, con etiquetas opcionales que suman su precio | De 1 a 50 ítems, cada uno una variante existente o una encontrada o creada en línea |
| **Creación** | Se finaliza en una sola llamada, salvo que se establezca `save_as_draft` o `automatically_finalizes_at` | Siempre guarda un borrador. Después la emites o la envías. |
| **Importes** | El precio del plan | `subtotal`, `buyer_fee_amount`, `tax_amount`, `total`, `amount_due` |
| **Página de pago** | `pay_online_url`, una URL | `checkout_link`, un token firmado que se usa para abrir el checkout |
| **Vencida** | `status: past_due` | `overdue: true` en una factura `open` o `uncollectible` |
| **Webhooks** | `invoice.*` | Eventos de pago para el ID `pay_` de la factura |

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.

| Función heredada | Comportamiento nativo |
| - | - |
| Webhooks `invoice.*` | Las facturas nativas usan eventos de pago. Algunos eventos heredados no tienen equivalente directo. Consulta [Mapea los webhooks](#map-webhooks). |
| Marcar una factura como pagada tras cobrar el dinero fuera de Whop | No existe un endpoint nativo `mark_paid`. |
| Eliminar un borrador | No existe un `DELETE /invoices/{id}` nativo. Anular conserva el registro y el número de la factura. |
| `plan.payment_method_configuration` | La solicitud de factura no acepta este campo. Configura en su lugar los métodos de pago de la variante existente o de la cuenta. |
| Pruebas gratuitas y cargos iniciales en planes recurrentes | A partir de `2026-11-11`, la factura añade el cargo inicial. Las versiones anteriores facturan el precio de renovación, así que añade el cargo como ítem de pago único. Se aplica la prueba de la variante. |
| `subscription_billing_anchor_at` | Envía `subscription_starts_at` en la factura. Si esa fecha ya ha pasado cuando se paga la factura, el periodo empieza en el momento del pago. Como antes, omite la prueba gratuita. |
| Etiquetas arbitrarias en `line_items`, cantidades fraccionarias o créditos negativos | Las líneas nativas facturan variantes. Las cantidades deben ser enteros positivos y las etiquetas proceden de los títulos del producto o la variante. Reconstruye los cargos en lugar de copiar el desglose. |
| Reutilizar el `current_plan.id` de la factura heredada | Las facturas nativas rechazan las variantes vinculadas a facturas heredadas. Usa una variante distinta o crea una en línea. |

## 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. Usa `4.99` para 4.99 USD. Enviar `499` factura 499 USD.

```json Legacy theme={null}
{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"product_id": "prod_xxxxxxxxxxxxx",
	"member_id": "mber_xxxxxxxxxxxxx",
	"collection_method": "send_invoice",
	"due_date": "2026-12-01T00:00:00Z",
	"plan": {
		"plan_type": "one_time",
		"initial_price": 19.99,
		"currency": "usd"
	},
	"line_items": [
		{ "label": "Setup", "quantity": 1, "unit_price": 15 },
		{ "label": "Service fee", "quantity": 1, "unit_price": 4.99 }
	]
}
```

```json Native theme={null}
{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"member_id": "mber_xxxxxxxxxxxxx",
	"due_at": "2026-12-01T00:00:00Z",
	"items": [
		{ "variant_id": "plan_xxxxxxxxxxxxx", "quantity": 1 },
		{
			"variant": {
				"title": "Service fee",
				"billing_type": "one_time",
				"initial_price": 4.99,
				"currency": "usd"
			}
		}
	]
}
```

La solicitud nativa crea un borrador. Envíalo con `POST /invoices/{id}/send` para emitirlo y enviarlo por email. `member_id` identifica a un cliente (`mber_`), no una suscripción (`mem_`).

| Campo heredado | Campo nativo | Notas |
| - | - | - |
| `account_id` | `account_id` | La cuenta que emite la factura. |
| `plan` | `items` | Cada ítem acepta `variant_id` o una `variant` en línea, más una `quantity` opcional. Todos los ítems usan la misma moneda. |
| `product`, `product_id` | `items[].variant.product`, `items[].variant.product_id` | Usa uno de los dos. Un `product` en línea requiere `external_identifier` y `title`. Una variante recurrente necesita un producto. Un cargo personalizado de pago único puede omitirlo. |
| `line_items` | `items` | Reconstruye las líneas facturadas como variantes. `quantity` es 1 de forma predeterminada. Los valores superiores a 1 requieren una variante que admita varias cantidades. |
| `collection_method` | `payment_method_id` y después emitir o enviar | Establece un método guardado para un cobro automático, u omítelo para el pago a través del checkout. Consulta [Emite, envía y cobra](#issue-send-and-charge). |
| `save_as_draft` | Ninguno | La creación siempre guarda un borrador. |
| `automatically_finalizes_at` | `send_at` en Send Invoice | Retrasa la emisión hasta el envío programado. `charge_at` retrasa un cobro con método guardado, no la emisión. |
| `due_date` | `due_at` | Envía una marca de tiempo ISO 8601. |
| `charge_buyer_fee` | `buyer_fee_percentage` | Mapea `false` a `0` y la comisión heredada `true` a `5`. Otros porcentajes distintos de cero deben estar entre 5 y 100, con dos decimales como máximo. |
| `payment_method_id`, `payment_token_id` | `payment_method_id` | Uno de los métodos de pago guardados del cliente, con el prefijo `payt_`. Establecerlo requiere `payment:charge`. |
| `member_id`, `email_address`, `customer_name` | Iguales en la creación | Elige `member_id` o `email_address`, no ambos. Las facturas nativas también aceptan `recipient_emails`, independientemente del cliente facturado. |
| `mailing_address_id`, `billing_address` | Mismos nombres, entrada de dirección más limitada | Elige uno. Una dirección en línea necesita `line1`, `city`, `postal_code` y `country`. También acepta `name`, `line2`, `state` y `phone`. No acepta los campos heredados `tax_id_type` ni `tax_id_value`. |
| `subscription_billing_anchor_at` | `subscription_starts_at` | Cuándo empieza el primer periodo de facturación. Debe ser en el futuro y necesita un ítem recurrente. |
| Ninguno | `memo`, `metadata` | `memo` aparece en el email, el PDF y el checkout. `metadata` almacena pares clave-valor de tipo string. |

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_address` y `customer_name` son entradas exclusivas de la creación.
* Los importes e ítems emitidos están bloqueados. Una actualización que solo contenga `memo` y/o `recipient_emails` está permitida en facturas `draft`, `open` y `uncollectible`, incluido un borrador programado.

## Emite, envía y cobra

Una creación heredada elige el comportamiento de cobro con `collection_method`. Las facturas nativas usan llamadas separadas después de crear el borrador:

1. **Emítela** con `POST /invoices/{id}/issue` para calcular el impuesto final y abrirla para el pago sin enviar el email inicial de la factura.
2. **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 factura `open` la vuelve a enviar por email. `send_at` programa el envío de un borrador. `POST /invoices/{id}/unschedule` cancela esa programación.
3. **Cobra un método guardado** estableciendo `payment_method_id` en el borrador. Para un total positivo, emitir o enviar cobra en un `charge_at` futuro; si no lo hay, en un `due_at` futuro; y si tampoco, de inmediato. `charge_at` debe ser en el futuro y no puede ser anterior a `send_at`.

Enviar un borrador que cobra de inmediato omite el email inicial de la factura. Enviarlo con un cobro posterior envía el email ahora. Un cobro automático fallido puede desencadenar un email con un enlace de pago aunque hayas usado Issue Invoice. [Cobra un método de pago guardado](https://docs.whop.com/es/developer/guides/invoices.md#charge-a-saved-payment-method) explica el flujo.

Una respuesta `open` no confirma el pago. Espera a `payment.succeeded` antes de completar el pedido. Para cobrar o reintentar una factura abierta, usa [Charge Invoice](https://docs.whop.com/es/api-reference/invoices/charge-invoice.md). 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](https://docs.whop.com/es/developer/guides/invoices.md#invoice-a-subscription).

## Mapea la respuesta

| Campo heredado | Campo nativo | Notas |
| - | - | - |
| `id` (`inv_`) | `id` (`pay_`) | `object` es `invoice`. El mismo ID identifica el pago. |
| Precio de `current_plan` | `subtotal`, `buyer_fee_amount`, `tax_amount`, `total`, `amount_due` | Los objetos de dinero contienen un `amount` como string decimal, `currency`, `decimals` y `display_decimals`. `totals_status` es `estimated` en un borrador y `final` en los demás casos. |
| `company.id` | `account_id` | Obtén la cuenta por ID. |
| `product.id`, `current_plan.id` | `line_items[].product_id`, `line_items[].variant_id` | Cada línea facturada identifica su producto y su variante. Un cargo personalizado puede no tener producto. |
| `member.id` | `member_id` | ID del cliente, con el prefijo `mber_`. Requiere `member:basic:read`. |
| `user` | Sin campo de usuario de nivel superior | Obtén el miembro para encontrar su usuario. `membership_id` (`mem_`) identifica una membresía, no al cliente. |
| `mailing_address` | `billing_address`, `mailing_address_id` | La dirección en línea sigue siendo un objeto. |
| `payment.id` | El propio `id` de la factura | Obtén los detalles del pago con `GET /payments/{id}` usando el mismo ID `pay_`. |
| `number` | `number`, `invoice_prefix` | El número con formato y el prefijo de la cuenta. |
| `due_date` | `due_at` | Marca de tiempo ISO 8601 o `null`. |
| `automatically_finalizes_at` | `scheduled_send_at` | `scheduled_charge_at` muestra un cobro planificado con método guardado. `scheduled_collection_method` muestra la opción de cobro de renovaciones para un envío programado. |
| `charge_buyer_fee` | `buyer_fee_percentage`, `buyer_fee_amount` | El porcentaje y su importe calculado. |
| `customer_name`, `email_address` | Iguales | Además de `recipient_emails`. Estos campos están restringidos por permisos. |
| `pay_online_url` | `checkout_link` | Un token firmado, no una URL. Consulta [Abre el checkout de la factura](#open-the-invoice-checkout). |
| `line_items` | `line_items` | Las líneas tienen `variant_id`, `product_id`, `label`, `description`, `quantity`, `unit_amount`, `subtotal`, `discount_amount` y `tax_amount`. |
| `status` | `status`, `overdue` | Consulta [Mapea los estados](#map-statuses). |
| `payment_processing` | `status`, más los detalles del pago | Gestiona `pending` mientras el pago se liquida. `paid_at` registra cuándo se completó el pago. No es un indicador de procesamiento. |
| `fetch_invoice_token` | Sin equivalente directo | Usa lecturas autenticadas de la factura, `checkout_link` para el checkout y Generate Invoice PDF para el PDF. |
| Ninguno | `paid_at`, `memo`, `metadata` | Momento en que se completó el pago, la nota para el cliente y tus metadatos. |

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](https://docs.whop.com/es/developer/guides/invoices.md#get-the-checkout-link).

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

| `status` heredado | Nativo |
| - | - |
| `draft` | `draft` |
| `open` | `open` |
| `past_due` | `open` o `uncollectible`, con `overdue: true` |
| `paid` | `paid` |
| `uncollectible` | `uncollectible` |
| `void` | `void` |

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](https://docs.whop.com/es/developer/guides/invoices.md#statuses-and-lifecycle) los explica.

## Mapea los endpoints

| Heredado | Nativo |
| - | - |
| `GET /invoices` | [List Invoices](https://docs.whop.com/es/api-reference/invoices/list-invoices.md), con un filtro `overdue` |
| `GET /invoices/{id}` | [Retrieve Invoice](https://docs.whop.com/es/api-reference/invoices/retrieve-invoice.md) |
| `POST /invoices` | [Create Invoice](https://docs.whop.com/es/api-reference/invoices/create-invoice.md), que guarda un borrador |
| `PATCH /invoices/{id}` | [Update Invoice](https://docs.whop.com/es/api-reference/invoices/update-invoice.md), sujeto a las reglas de borradores y facturas emitidas anteriores |
| `POST /invoices/{id}/resend` | [Send Invoice](https://docs.whop.com/es/api-reference/invoices/send-invoice.md) |
| `POST /invoices/{id}/void` | [Void Invoice](https://docs.whop.com/es/api-reference/invoices/void-invoice.md) |
| `POST /invoices/{id}/mark_uncollectible` | [Mark an invoice uncollectible](https://docs.whop.com/es/api-reference/invoices/mark-invoice-uncollectible.md) |
| `DELETE /invoices/{id}` | Sin equivalente. Anula el borrador para cancelarlo conservando su registro. |
| `POST /invoices/{id}/mark_paid` | Sin equivalente |
| Ninguno | [Issue Invoice](https://docs.whop.com/es/api-reference/invoices/issue-invoice.md), [Cancel Scheduled Send](https://docs.whop.com/es/api-reference/invoices/cancel-scheduled-send.md), [Charge Invoice](https://docs.whop.com/es/api-reference/invoices/charge-invoice.md), [List Invoice Sends](https://docs.whop.com/es/api-reference/invoices/list-invoice-sends.md), [Generate Invoice PDF](https://docs.whop.com/es/api-reference/invoices/generate-invoice-pdf.md) |

## Mapea los webhooks

Las facturas nativas envían eventos de pago para su ID `pay_`. Los eventos `invoice.*` describen las facturas heredadas.

| Evento heredado | Comportamiento nativo |
| - | - |
| `invoice.created` | `payment.created` cuando se emite un borrador, no cuando se crea |
| `invoice.paid` | `payment.succeeded` |
| `invoice.past_due` | Lee o filtra por `overdue`. No hay un evento de pago vencido equivalente. |
| `invoice.voided`, `invoice.marked_uncollectible` | Lee el `status` de la factura. No hay un evento de pago que sustituya directamente estas transiciones. |

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](https://docs.whop.com/es/developer/guides/invoices.md#webhooks) muestra cómo completar pedidos a partir de `payment.succeeded`.

## Permisos

| Operación | Permiso requerido |
| - | - |
| Crear un borrador sin método de pago guardado | `invoice:create` o `payment:charge` |
| Actualizar un borrador sin método de pago guardado ni envío programado | `invoice:update`, `invoice:create` o `payment:charge` |
| Enviar o programar un borrador sin método de pago guardado, o cancelar su envío programado | `invoice:update`, `invoice:create` o `payment:charge` |
| Establecer un método de pago guardado, escribir una factura que lo tenga, emitir, cobrar, anular o marcar como incobrable | `payment:charge` |
| Actualizar un borrador programado, o actualizar o reenviar una factura emitida | `payment:charge` |
| Listar, obtener, generar un PDF o listar los envíos de email | `payment:basic:read` |
| Proporcionar una `variant` en línea | También `plan:create` |
| Crear o actualizar un `product` en línea | También `access_pass:create` o `access_pass:update`, respectivamente |

`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

1. Consulta [Antes de migrar](#before-you-migrate) para ver los flujos de trabajo que deben quedarse en la API heredada.
2. Fija las llamadas nativas a una versión publicada que coincida con sus nombres de campo, como `2026-11-02-1` para estos ejemplos.
3. Construye `items` a partir de variantes elegibles, comprobando cantidades, precios, moneda y requisitos de producto.
4. 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.
5. 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.
6. Mantén separados los ID nativos `pay_` y los heredados `inv_`. Mantén las lecturas heredadas en la versión anterior.
7. Lee los importes desde los objetos de dinero y abre el checkout con el `checkout_link` firmado.
8. Gestiona `overdue` y los estados de pago adicionales.
9. Completa los pedidos a partir de `payment.succeeded` para el ID de pago de la factura.
10. Concede los permisos que usa tu flujo, incluidos los de variante/producto en línea y los de lectura de clientes.

## Próximos pasos

> [card] [Guía de facturas](https://docs.whop.com/es/developer/guides/invoices.md)
>
> Crea, emite, envía y cobra facturas nativas.

> [card] [Referencia de la API de facturas](https://docs.whop.com/es/api-reference/invoices/create-invoice.md)
>
> Cada endpoint y campo de las facturas nativas.

> [card] [API de facturas heredada](https://docs.whop.com/es/api-reference/legacy/invoices/legacy-invoice.md)
>
> Los endpoints a los que llama tu integración actual.

> [card] [Versiones de la API](https://docs.whop.com/es/developer/api/versioning.md)
>
> Cómo funcionan `Api-Version-Date` y las versiones fijadas.


## Related topics

- [Factura heredada](https://docs.whop.com/es/api-reference/legacy/invoices/legacy-invoice.md)
- [Facturas](https://docs.whop.com/es/developer/guides/invoices.md)
- [Migra desde versiones anteriores](https://docs.whop.com/es/developer/api/migrate-from-previous-versions.md)
