> ## 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.

# Facturas

> Cobra a un cliente con una factura numerada a través de la API y recauda el pago desde un método guardado o un checkout alojado.

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](https://docs.whop.com/es/manage-your-business/manage-payments/send-invoice.md).

> [!NOTE]
>
> 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](#before-you-start).

## 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](https://docs.whop.com/es/api-reference/payments/retrieve-payment.md). 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](#invoice-a-subscription), 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.

| Envías | `/invoices` sirve |
| - | - |
| `Api-Version-Date: 2026-10-24` o posterior | Las facturas nativas de esta página |
| Un `Api-Version-Date` anterior | La [API de facturas heredada](https://docs.whop.com/es/api-reference/legacy/invoices/legacy-invoice.md) |
| Sin encabezado | La versión fijada almacenada de tu credencial. Sin versión fijada, la API de facturas heredada. |
| Una fecha que no es una versión publicada | Un error `400` |

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](https://docs.whop.com/es/developer/api/versioning.md) explica las versiones fijadas y el changelog.

| | Facturas nativas | Facturas heredadas |
| - | - | - |
| **ID** | `pay_`, el mismo que el del pago | `inv_` |
| **Qué cobras** | Variantes de pago único y recurrentes, como `items` | Facturación única o recurrente |
| **Correo de la factura** | Se envía cuando llamas a Send Invoice, con recordatorios después de `due_at` | Whop envía la factura por correo y manda recordatorios |
| **Webhooks** | `payment.*` | `invoice.*` |
| **Panel** | Pestaña **Invoices**: listadas, creadas y enviadas | Pestaña **Legacy invoices** |

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.

```typescript TypeScript theme={null}
const WHOP_API = "https://api.whop.com/api/v1";

export async function whop(method: string, path: string, body?: unknown, idempotencyKey?: string) {
	const response = await fetch(`${WHOP_API}${path}`, {
		method,
		headers: {
			Authorization: `Bearer ${process.env.WHOP_API_KEY}`,
			"Api-Version-Date": "2026-10-24",
			"Content-Type": "application/json",
			...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
		},
		body: body === undefined ? undefined : JSON.stringify(body),
	});
	const data = await response.json();
	if (!response.ok) throw new Error(`${data.error.type}: ${data.error.message}`);
	return data;
}
```

```python Python theme={null}
import os
import uuid

import requests

WHOP_API = "https://api.whop.com/api/v1"


def whop(method, path, body=None, idempotency_key=None):
    headers = {
        "Authorization": f"Bearer {os.environ['WHOP_API_KEY']}",
        "Api-Version-Date": "2026-10-24",
    }
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    response = requests.request(method, f"{WHOP_API}{path}", json=body, headers=headers)
    data = response.json()
    if not response.ok:
        raise RuntimeError(f"{data['error']['type']}: {data['error']['message']}")
    return data
```

Envía una [`Idempotency-Key`](https://docs.whop.com/es/developer/api/idempotency) 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](https://docs.whop.com/es/api-reference/invoices/create-invoice.md) guarda un borrador con `POST /invoices`.

```typescript TypeScript theme={null}
const invoice = await whop(
	"POST",
	"/invoices",
	{
		account_id: "biz_xxxxxxxxxxxxx",
		email_address: "dana@example.com",
		customer_name: "Dana Lee",
		items: [{ plan_id: "plan_xxxxxxxxxxxxx", quantity: 2 }],
		due_at: "2026-11-30T17:00:00Z",
		billing_address: {
			line1: "123 Main St",
			city: "New York",
			state: "NY",
			postal_code: "10001",
			country: "US",
		},
		metadata: { order_id: "ord_1042" },
	},
	crypto.randomUUID(),
);

console.log(invoice.id, invoice.number, invoice.status); // pay_xxxxxxxxxxxxx #00000042 draft
```

```python Python theme={null}
invoice = whop(
    "POST",
    "/invoices",
    {
        "account_id": "biz_xxxxxxxxxxxxx",
        "email_address": "dana@example.com",
        "customer_name": "Dana Lee",
        "items": [{"plan_id": "plan_xxxxxxxxxxxxx", "quantity": 2}],
        "due_at": "2026-11-30T17:00:00Z",
        "billing_address": {
            "line1": "123 Main St",
            "city": "New York",
            "state": "NY",
            "postal_code": "10001",
            "country": "US",
        },
        "metadata": {"order_id": "ord_1042"},
    },
    idempotency_key=str(uuid.uuid4()),
)

print(invoice["id"], invoice["number"], invoice["status"])  # pay_xxxxxxxxxxxxx #00000042 draft
```

```bash cURL theme={null}
curl -X POST https://api.whop.com/api/v1/invoices \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-10-24" \
  -H "Idempotency-Key: 6f1c2a0e-3b7d-4d55-9a8e-2c4b1f0d9e21" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "biz_xxxxxxxxxxxxx",
    "email_address": "dana@example.com",
    "customer_name": "Dana Lee",
    "items": [{ "plan_id": "plan_xxxxxxxxxxxxx", "quantity": 2 }],
    "due_at": "2026-11-30T17:00:00Z",
    "billing_address": { "line1": "123 Main St", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" },
    "metadata": { "order_id": "ord_1042" }
  }'
```

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:

```json theme={null}
{
	"id": "pay_xxxxxxxxxxxxx",
	"object": "invoice",
	"number": "#00000042",
	"status": "draft",
	"totals_status": "estimated",
	"member_id": "mber_xxxxxxxxxxxxx",
	"recipient_emails": ["dana@example.com"],
	"line_items": [
		{
			"id": "li_xxxxxxxxxxxxx",
			"plan_id": "plan_xxxxxxxxxxxxx",
			"product_id": "prod_xxxxxxxxxxxxx",
			"label": "Strategy workshop",
			"quantity": 2,
			"unit_amount": { "currency": "usd", "amount": "250.00", "decimals": 2, "display_decimals": 2 },
			"subtotal": { "currency": "usd", "amount": "500.00", "decimals": 2, "display_decimals": 2 }
		}
	],
	"subtotal": { "currency": "usd", "amount": "500.00", "decimals": 2, "display_decimals": 2 },
	"tax_amount": null,
	"total": { "currency": "usd", "amount": "500.00", "decimals": 2, "display_decimals": 2 },
	"amount_due": { "currency": "usd", "amount": "500.00", "decimals": 2, "display_decimals": 2 },
	"metadata": { "order_id": "ord_1042" }
}
```

`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](https://docs.whop.com/es/api-reference/invoices/create-invoice.md) 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](#delete-an-invoice). Para mantenerlo en tu lista, [anúlalo](#void-or-mark-uncollectible) 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](https://docs.whop.com/es/api-reference/payments/create-payment.md), 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

| Campo | Qué hace |
| - | - |
| `member_id` | El cliente, un miembro existente de la cuenta con el prefijo `mber_`. |
| `email_address`, `customer_name` | El cliente por correo electrónico, en lugar de `member_id`. Whop usa el miembro de la cuenta con ese correo, luego un usuario de Whop con él, y crea un usuario cuando no existe ninguno. `customer_name` da nombre al nuevo. |
| `billing_address` | Una nueva dirección de facturación para el cliente, con `line1`, `city`, `postal_code` y un `country` ISO 3166-1 alfa-2, además de `name`, `line2`, `state` y `phone` opcionales. |
| `mailing_address_id` | Una de las direcciones guardadas del cliente en su lugar, con el prefijo `ma_`. |
| `payment_method_id` | Un método de pago guardado del cliente, con el prefijo `payt_`. Whop lo cobra cuando emites la factura. Consulta [Cobra un método de pago guardado](#charge-a-saved-payment-method). |
| `due_at` | Cuándo vence el pago, como marca de tiempo ISO 8601. Define `overdue`, las fechas de los recordatorios y la fecha de vencimiento que muestran el correo, el PDF y el checkout. |
| `buyer_fee_percentage` | Una comisión que paga el comprador, como porcentaje del subtotal de 0 a 100 con un máximo de dos decimales. La respuesta devuelve el porcentaje como `buyer_fee_percentage` y la comisión como `buyer_fee_amount`. |
| `recipient_emails` | Hasta 50 direcciones que reciben el correo de la factura, aparte del cliente facturado. De forma predeterminada es el correo del cliente al crear el borrador. Una actualización que lo omite conserva la lista guardada, incluso cuando cambia el cliente. Guardarlo no envía ningún correo. Consulta [Quién recibe el correo](#who-gets-the-email). |
| `metadata` | Hasta 50 pares clave-valor de tipo cadena propios. Whop los copia en la membresía que crea al emitir la factura y en el cobro automático. |

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](https://docs.whop.com/es/api-reference/invoices/update-invoice.md) modifica un borrador con `PATCH /invoices/{id}`. Envía solo los campos que cambias.

```typescript TypeScript theme={null}
const updated = await whop("PATCH", `/invoices/${invoice.id}`, {
	items: [
		{ plan_id: "plan_xxxxxxxxxxxxx", quantity: 3 },
		{ plan_id: "plan_yyyyyyyyyyyyy" },
	],
	buyer_fee_percentage: 2.5,
});
```

```python Python theme={null}
updated = whop(
    "PATCH",
    f"/invoices/{invoice['id']}",
    {
        "items": [
            {"plan_id": "plan_xxxxxxxxxxxxx", "quantity": 3},
            {"plan_id": "plan_yyyyyyyyyyyyy"},
        ],
        "buyer_fee_percentage": 2.5,
    },
)
```

* `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](#schedule-a-send) 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.

| | Cobrar un método de pago guardado | El cliente paga a través del checkout |
| - | - | - |
| **Cliente presente** | No. Whop cobra el método fuera de sesión. | Sí, en el checkout alojado de Whop |
| **Qué necesitas** | `payment_method_id` en el borrador | El `checkout_link` de la factura |
| **3D Secure** | El cobro no puede completar un desafío | El cliente lo completa |
| **Tus reglas de pago** | Se aplican `block` y `allow` | Se aplican las cuatro acciones |

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](https://docs.whop.com/es/developer/guides/save-payment-methods.md) muestra cómo un cliente guarda uno, y [List payment methods](https://docs.whop.com/es/api-reference/legacy/payment-methods/list-payment-methods.md) 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](https://docs.whop.com/es/api-reference/payments/create-payment.md) 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`](#webhooks) 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](#payment-rules-on-invoice-payments) 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](https://docs.whop.com/es/api-reference/payments/retrieve-payment.md) 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](#who-gets-the-email), 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](#send-limit).

> [!WARNING]
>
> 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](https://docs.whop.com/es/api-reference/invoices/issue-invoice.md) 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](#charge-a-saved-payment-method).

```typescript TypeScript theme={null}
const issued = await whop("POST", `/invoices/${invoice.id}/issue`, undefined, crypto.randomUUID());

console.log(issued.status, issued.totals_status); // open final
```

```python Python theme={null}
issued = whop("POST", f"/invoices/{invoice['id']}/issue", idempotency_key=str(uuid.uuid4()))

print(issued["status"], issued["totals_status"])  # open final
```

```bash cURL theme={null}
curl -X POST https://api.whop.com/api/v1/invoices/pay_xxxxxxxxxxxxx/issue \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-10-24" \
  -H "Idempotency-Key: 0b6f2d3c-91a4-4c7e-8f1e-5a2d7c9b3e10"
```

* **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](#if-the-automatic-charge-is-declined). Para enviar la factura por correo, [envíala](#send-schedule-and-remind) 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](#issue-errors) enumera los motivos.

### Obtén el enlace de checkout

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.

```typescript TypeScript theme={null}
const { id, checkout_link } = await whop("GET", `/invoices/${invoice.id}`);

if (checkout_link) {
	const token = checkout_link.slice(checkout_link.indexOf(".") + 1);
	const url = `https://whop.com/checkout/${id}/?token=${encodeURIComponent(token)}`;
	console.log(url);
}
```

```python Python theme={null}
from urllib.parse import quote

current = whop("GET", f"/invoices/{invoice['id']}")

if current["checkout_link"]:
    token = current["checkout_link"].split(".", 1)[1]
    url = f"https://whop.com/checkout/{current['id']}/?token={quote(token, safe='')}"
    print(url)
```

**3. Envíaselo al cliente**

[Envía la factura](#send-schedule-and-remind) 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](#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](https://docs.whop.com/es/api-reference/invoices/send-invoice.md) 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.

```typescript TypeScript theme={null}
await whop("POST", `/invoices/${invoice.id}/send`, undefined, crypto.randomUUID());
```

```python Python theme={null}
whop("POST", f"/invoices/{invoice['id']}/send", idempotency_key=str(uuid.uuid4()))
```

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](#if-the-automatic-charge-is-declined) 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](#if-the-automatic-charge-is-declined) 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](#if-the-automatic-charge-is-declined) 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.

```typescript TypeScript theme={null}
const scheduled = await whop("POST", `/invoices/${invoice.id}/send`, { send_at: "2026-12-01T15:00:00Z" }, crypto.randomUUID());

console.log(scheduled.status, scheduled.scheduled_send_at); // draft 2026-12-01T15:00:00.000Z
```

```python Python theme={null}
scheduled = whop("POST", f"/invoices/{invoice['id']}/send", {"send_at": "2026-12-01T15:00:00Z"}, idempotency_key=str(uuid.uuid4()))

print(scheduled["status"], scheduled["scheduled_send_at"])  # draft 2026-12-01T15:00:00.000Z
```

* **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](https://docs.whop.com/es/api-reference/invoices/cancel-scheduled-send.md)** 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.

```typescript TypeScript theme={null}
await whop("POST", `/invoices/${invoice.id}/unschedule`, undefined, crypto.randomUUID());
```

```python Python theme={null}
whop("POST", f"/invoices/{invoice['id']}/unschedule", idempotency_key=str(uuid.uuid4()))
```

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](https://docs.whop.com/es/api-reference/invoices/list-invoice-sends.md) 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](https://docs.whop.com/es/api-reference/invoices/generate-invoice-pdf.md) genera la factura como PDF y devuelve un enlace de corta duración a ella. Necesita `payment:basic:read` y funciona con cualquier estado.

```typescript TypeScript theme={null}
const pdf = await whop("POST", `/invoices/${invoice.id}/generate_pdf`);

console.log(pdf.url, pdf.expires_at);
```

```python Python theme={null}
pdf = whop("POST", f"/invoices/{invoice['id']}/generate_pdf")

print(pdf["url"], pdf["expires_at"])
```

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:

| Permiso | Añade al PDF |
| - | - |
| `member:basic:read` | El nombre del cliente bajo **Bill to**. Sin él, el PDF solo muestra un nombre guardado en la dirección de facturación. |
| `member:email:read` | El correo del cliente bajo **Bill to** |
| `payment:charge` | Un enlace **Pay now** que abre el checkout de la factura, en una factura que tiene `checkout_link` |

## 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](#start-with-a-free-trial). 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](https://docs.whop.com/es/api-reference/invoices/issue-invoice.md) o [Send Invoice](https://docs.whop.com/es/api-reference/invoices/send-invoice.md) 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`.

| `collection_method` | Cada renovación |
| - | - |
| `charge_automatically` | Cobra el método de pago que pagó la factura: el `payment_method_id` del borrador, o el que usa el cliente para pagar el enlace de la factura. Es el valor predeterminado. |
| `send_invoice` | Emite una nueva factura numerada con vencimiento en la fecha de renovación y la envía por correo, con su enlace de pago y recordatorios, a los `recipient_emails` de la última factura |

`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](https://docs.whop.com/es/api-reference/memberships/cancel-membership.md) 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](https://docs.whop.com/es/api-reference/payments/retrieve-payment.md) 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` | Qué significa | Qué puede ocurrir después |
| - | - | - |
| `draft` | Aún puedes editarla. Los totales son una estimación y el impuesto aún no se ha calculado. | La emites, la envías, la programas, la anulas o la eliminas |
| `open` | Emitida. Los totales y el impuesto son finales, y la factura está a la espera del pago. | El cliente paga, o la anulas o la marcas como incobrable |
| `paid` | El cliente pagó. `amount_due` es cero. | Nada |
| `uncollectible` | Marcaste una factura abierta como una que no esperas cobrar. | La anulas |
| `void` | Cancelada. `amount_due` es cero. | La eliminas |

`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](https://docs.whop.com/es/api-reference/invoices/void-invoice.md) 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](https://docs.whop.com/es/api-reference/invoices/mark-invoice-uncollectible.md) 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:

```typescript TypeScript theme={null}
await whop("POST", `/invoices/${invoice.id}/mark_uncollectible`, undefined, crypto.randomUUID());

await whop("POST", `/invoices/${invoice.id}/void`, undefined, crypto.randomUUID());
```

```python Python theme={null}
whop("POST", f"/invoices/{invoice['id']}/mark_uncollectible", idempotency_key=str(uuid.uuid4()))

whop("POST", f"/invoices/{invoice['id']}/void", idempotency_key=str(uuid.uuid4()))
```

### Elimina una factura

[Delete Invoice](https://docs.whop.com/es/api-reference/invoices/delete-invoice.md) 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](https://docs.whop.com/es/api-reference/invoices/cancel-scheduled-send.md). 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.

```typescript TypeScript theme={null}
await whop("DELETE", `/invoices/${invoice.id}`);
```

```python Python theme={null}
whop("DELETE", f"/invoices/{invoice['id']}")
```

## Lista y recupera facturas

[List Invoices](https://docs.whop.com/es/api-reference/invoices/list-invoices.md) 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:

| Parámetro | Filtra por |
| - | - |
| `account_id` | Una cuenta |
| `status` | Un estado, como `open`. Un valor desconocido es un `400`. |
| `overdue` | `true` para facturas vencidas, `false` para el resto |
| `scheduled` | `true` para borradores programados, `false` para el resto |
| `member_id` | Un cliente |
| `product_id` | Facturas que cobran un producto, con el prefijo `prod_` |
| `created_after`, `created_before` | Un intervalo de creación, como marcas de tiempo ISO 8601 |

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.

```typescript TypeScript theme={null}
const overdue = await whop("GET", "/invoices?account_id=biz_xxxxxxxxxxxxx&overdue=true&order=due_at&direction=asc");

for (const invoice of overdue.data) {
	console.log(invoice.number, invoice.due_at, invoice.amount_due.amount);
}
```

```python Python theme={null}
overdue = whop("GET", "/invoices?account_id=biz_xxxxxxxxxxxxx&overdue=true&order=due_at&direction=asc")

for invoice in overdue["data"]:
    print(invoice["number"], invoice["due_at"], invoice["amount_due"]["amount"])
```

[Retrieve Invoice](https://docs.whop.com/es/api-reference/invoices/retrieve-invoice.md) lee una factura por su ID `pay_`. [List Payments](https://docs.whop.com/es/api-reference/payments/list-payments.md) omite los borradores.

Para exportar facturas como archivo CSV, llama a [Create Export](https://docs.whop.com/es/api-reference/exports/create-export.md) 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.

| Evento | Cuándo |
| - | - |
| `payment.created` | Emites la factura. Los borradores no envían nada. |
| `payment.succeeded` | La factura se paga. Realiza el fulfillment a partir de este evento. |

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](https://docs.whop.com/es/developer/guides/webhooks.md).

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](https://docs.whop.com/es/developer/guides/webhooks.md#verify-and-handle-events), busca el pedido por ese ID. En este handler, `orders` representa tu propio almacén de pedidos:

```typescript TypeScript theme={null}
export async function handleWhopEvent(event: { type: string; data: { id: string } }) {
	if (event.type !== "payment.succeeded") return;

	const order = await orders.findByInvoiceId(event.data.id);
	if (!order || order.fulfilled) return;

	await orders.fulfill(order.id);
}
```

```python Python theme={null}
def handle_whop_event(event):
    if event["type"] != "payment.succeeded":
        return

    order = orders.find_by_invoice_id(event["data"]["id"])
    if order is None or order.fulfilled:
        return

    orders.fulfill(order.id)
```

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](https://docs.whop.com/es/developer/guides/manage-fraud.md) 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](https://docs.whop.com/es/developer/guides/manage-fraud.md).

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](https://docs.whop.com/es/payments/send-an-invoice.md).

## Permisos

| Llamada | Permiso |
| - | - |
| [Crear](https://docs.whop.com/es/api-reference/invoices/create-invoice.md), [actualizar](https://docs.whop.com/es/api-reference/invoices/update-invoice.md), [emitir](https://docs.whop.com/es/api-reference/invoices/issue-invoice.md), [enviar](https://docs.whop.com/es/api-reference/invoices/send-invoice.md), [cancelar un envío programado](https://docs.whop.com/es/api-reference/invoices/cancel-scheduled-send.md), [anular](https://docs.whop.com/es/api-reference/invoices/void-invoice.md) o [marcar como incobrable](https://docs.whop.com/es/api-reference/invoices/mark-invoice-uncollectible.md) | `payment:charge` |
| [Listar](https://docs.whop.com/es/api-reference/invoices/list-invoices.md), [recuperar](https://docs.whop.com/es/api-reference/invoices/retrieve-invoice.md) o [generar un PDF](https://docs.whop.com/es/api-reference/invoices/generate-invoice-pdf.md) | `payment:basic:read` |

Toda escritura necesita `payment:charge`, el mismo permiso que [Create Payment](https://docs.whop.com/es/api-reference/payments/create-payment.md), 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.

| Permiso | Campos que revela |
| - | - |
| `member:basic:read` | `member_id`, `customer_name` |
| `member:email:read` | `email_address`, `recipient_emails` |
| `payment:basic:read` | `payment_method_id`, `mailing_address_id`, `billing_address` |
| `payment:charge` | `checkout_link` |

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](https://docs.whop.com/es/developer/guides/permissions.md).

## 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

| `error.code` | Por qué |
| - | - |
| `invoice_item_count_invalid`, `invoice_item_invalid` | `items` no tiene de 1 a 50 entradas, o un artículo no tiene exactamente uno de `plan_id` y `plan`. |
| `invoice_plan_account_mismatch`, `invoice_plan_duplicated`, `invoice_currency_mismatch` | Una variante pertenece a otra cuenta, aparece dos veces o usa una moneda distinta a la del resto. |
| `invoice_quantity_unsupported` | `quantity` es mayor que 1 para una variante que no permite varias cantidades. |
| `invoice_plan_type_unsupported`, `invoice_legacy_plan_unsupported` | La variante no es de compra inmediata o pertenece a una factura heredada. |
| `invoice_installment_count_mismatch` | Los artículos recurrentes de la factura se detienen tras números de pagos distintos. |
| `invoice_recurring_plan_product_required` | Una variante recurrente no tiene producto. |
| `invoice_plan_unavailable`, `invoice_plan_archived`, `invoice_plan_currency_changed` | Se eliminó o archivó una variante, o una variante guardada cambió de moneda. Vuelve a enviar `items`. |
| `invoice_customer_ambiguous`, `invoice_address_ambiguous` | Enviaste tanto `member_id` como `email_address`, o tanto `billing_address` como `mailing_address_id`. |
| `invoice_address_properties_invalid`, `invoice_address_incomplete`, `invoice_address_country_invalid` | `billing_address` tiene un campo desconocido, le falta uno obligatorio o tiene un `country` que no es un código válido. |
| `invoice_address_member_required`, `invoice_member_mismatch`, `invoice_address_mismatch`, `invoice_payment_method_mismatch` | La dirección no tiene cliente, o el miembro, la dirección o el método de pago pertenecen a otra persona. |
| `invoice_payment_method_unsupported` | El método de pago guardado no puede pagar facturas. |
| `invoice_buyer_fee_invalid`, `invoice_metadata_invalid`, `invoice_recipients_invalid` | `buyer_fee_percentage` está fuera de rango, un valor de `metadata` no es una cadena o `recipient_emails` no es un array. |
| `invoice_not_editable`, `invoice_recipients_not_editable` | La factura no es un borrador, o un cambio en `recipient_emails` llegó a una factura que no es borrador, `open` ni `uncollectible`. |
| `invoice_scheduled_not_editable`, `invoice_scheduled_recipients_required` | El borrador tiene un envío programado. Cancélalo antes de editar o antes de eliminar el último destinatario. |

### Errores de emisión

| `error.code` | Por qué |
| - | - |
| `invoice_not_issuable` | La factura no es un borrador ni está `open`. |
| `invoice_recipient_required` | La factura no tiene cliente. |
| `invoice_account_verification_required` | Tu cuenta no ha completado la verificación. |
| `invoice_account_suspended` | Tu cuenta está suspendida. |
| `invoice_items_required`, `invoice_items_changed`, `invoice_plan_unavailable`, `invoice_plan_archived` | La factura no tiene artículos, o una variante se eliminó, se archivó o cambió de cuenta, moneda o producto. Actualiza los artículos. |
| `invoice_tax_address_required` | Se aplican impuestos y Whop no puede saber dónde está el cliente. Añade una dirección de facturación. |
| `invoice_tax_unresolved` | No se pudo calcular el impuesto. |
| `invoice_changed_during_issuance`, `invoice_changed_during_calculation` | La factura cambió mientras se calculaba el impuesto. Vuelve a emitirla. |
| `invoice_payment_method_unavailable`, `invoice_payment_method_unsupported`, `payment_method_unavailable` | El método de pago guardado se eliminó del cliente, no puede pagar facturas o ya no funciona. |
| `out_of_stock` | Solo al cobrar un método de pago guardado: una variante no tiene stock suficiente para la cantidad facturada. |
| `payment_fees_unavailable` | Solo al cobrar un método de pago guardado: no se pudieron preparar las comisiones del pago. |

### 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](#issue-errors).

| `error.code` | Por qué |
| - | - |
| `invoice_not_sendable` | La factura no es un borrador ni está `open`. |
| `invoice_send_recipients_required` | La factura no tiene `recipient_emails` ni nada que cobrar. |
| `invoice_payment_link_unavailable` | No hay enlace de pago que enviar: una factura `open` no tiene `checkout_link`, o un borrador sin método de pago guardado factura a un comprador empresarial. |
| `invoice_send_limit_reached` | Un `429`: la factura ya se envió por correo tres veces en las últimas 24 horas. |
| `invoice_not_schedulable` | Solo se puede programar un borrador. |
| `invoice_scheduled_send_in_past` | `send_at` no está en el futuro. |

### Otros errores

| `error.code` | Por qué |
| - | - |
| `invoice_not_uncollectible` | Solo una factura `open` se puede marcar como incobrable. |
| `invoice_replay_permission_revoked` | Un `403`: una repetición idempotente mostraría campos que tu credencial ya no puede leer. |

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

## Próximos pasos

> [card] [Referencia de la API de facturas](https://docs.whop.com/es/api-reference/invoices/create-invoice.md)
>
> Todos los endpoints, parámetros y campos de respuesta de las facturas.

> [card] [Guarda métodos de pago](https://docs.whop.com/es/developer/guides/save-payment-methods.md)
>
> Recopila el método de pago guardado que una factura cobra al emitirse.

> [card] [Gestiona el fraude](https://docs.whop.com/es/developer/guides/manage-fraud.md)
>
> Escribe las reglas de pago que filtran los pagos de facturas.

> [card] [Escucha webhooks](https://docs.whop.com/es/developer/guides/webhooks.md)
>
> Supervisa `payment.created` y `payment.succeeded` para tus facturas.


## Related topics

- [Factura heredada](https://docs.whop.com/es/api-reference/legacy/invoices/legacy-invoice.md)
- [API de facturas](https://docs.whop.com/es/api-reference/invoices/invoice.md)
- [Migra desde las facturas heredadas](https://docs.whop.com/es/developer/guides/migrate-from-legacy-invoices.md)
