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

# Facturen

> Factureer een klant met een genummerde factuur via de API en ontvang de betaling via een opgeslagen betaalmethode of een gehoste checkout.

Een factuur is een genummerde rekening voor een of meer van je varianten, gericht aan één klant. Een variant is een prijs- en factureringsinstelling die je verkoopt, meestal voor een product. Het ID begint met `plan_` en factuuritems accepteren het als `plan_id`. Gebruik een factuur wanneer je vóór de betaling een prijs met een klant afspreekt, zoals bij een offerte, een dienst of een zakelijke bestelling. Je werkt een concept bij tot het klopt en geeft het daarna uit om de totalen vast te leggen en het open te stellen voor betaling. Verzenden doet dat en mailt de factuur in één aanroep. Zie [Facturen maken en verzenden](https://docs.whop.com/nl/manage-your-business/manage-payments/send-invoice.md) om er een zonder code vanuit je dashboard te verzenden.

> [!NOTE]
>
> Facturen op deze pagina hebben bij elk verzoek `Api-Version-Date: 2026-10-24` of later nodig. Verzoeken met een eerdere versie komen bij de legacy-factuur-API terecht, die anders werkt. Zie [Voordat je begint](#before-you-start).

## Hoe een factuur werkt

Een native factuur is een betaling. Het ID begint met `pay_` en blijft hetzelfde nadat de klant heeft betaald, dus je kunt de factuur ook lezen met [Retrieve Payment](https://docs.whop.com/nl/api-reference/payments/retrieve-payment.md). Elke factuur krijgt ook het volgende nummer in de eigen reeks van je account, zoals `#00000042`, of `#ACME-00000042` als je account een factuurprefix heeft.

1. **Je maakt een concept** met items, een klant en factuurgegevens. Een concept brengt niets in rekening en mailt niemand.
2. **Je geeft het uit of verzendt het.** Uitgeven berekent de definitieve belasting en stelt de factuur open voor betaling. Verzenden geeft de factuur uit en mailt deze, nu of op een tijdstip dat je inplant.
3. **De klant betaalt.** Whop belast de opgeslagen betaalmethode van de klant zodra je de factuur uitgeeft of verzendt, of de klant betaalt via de gehoste checkout van Whop.
4. **Je levert de bestelling uit** vanuit de webhook `payment.succeeded`.

Facturen factureren buy-now-varianten, die met `release_method: buy_now` in plaats van een wachtlijst. Een eenmalige variant wordt één keer gefactureerd en een terugkerende variant start een abonnement wanneer de factuur is betaald. Zie [Een abonnement factureren](#invoice-a-subscription), waar ook staat hoe je het na een vast aantal betalingen stopt.

## Voordat je begint

### De API-versie meesturen

`/invoices` bedient twee verschillende API's, en de `Api-Version-Date` waarnaar je verzoek wordt herleid, bepaalt welke antwoordt.

| Je stuurt | `/invoices` bedient |
| - | - |
| `Api-Version-Date: 2026-10-24` of later | De native facturen op deze pagina |
| Een eerdere `Api-Version-Date` | De [legacy-factuur-API](https://docs.whop.com/nl/api-reference/legacy/invoices/legacy-invoice.md) |
| Geen header | De opgeslagen versiepin van je credential. Zonder pin de legacy-factuur-API. |
| Een datum die geen uitgebrachte versie is | Een `400`-fout |

Uitgeven, verzenden, een geplande verzending annuleren en een pdf genereren bestaan alleen in de native API, dus die bereiken native facturen, ongeacht welke versie je stuurt. De paden die beide API's hebben, zoals `GET /invoices` en `POST /invoices/{id}/void`, volgen de versie.

Stuur de header bij elk verzoek mee in plaats van te vertrouwen op de pin van een sleutel, zodat het wisselen van sleutels je nooit tussen de twee laat verspringen. [API-versies](https://docs.whop.com/nl/developer/api/versioning.md) legt pins en de changelog uit.

| | Native facturen | Legacy-facturen |
| - | - | - |
| **ID** | `pay_`, hetzelfde als de betaling | `inv_` |
| **Wat je factureert** | Eenmalige en terugkerende varianten, als `items` | Eenmalige of terugkerende facturering |
| **Factuurmail** | Verzonden wanneer je Send Invoice aanroept, met herinneringen na `due_at` | Whop mailt de factuur en stuurt herinneringen |
| **Webhooks** | `payment.*` | `invoice.*` |
| **Dashboard** | Tabblad **Invoices**: weergeven, aanmaken en verzenden | Tabblad **Legacy invoices** |

De native API geeft geen legacy `inv_`-facturen weer en haalt ze niet op, en de legacy-API retourneert geen native facturen.

### De API aanroepen

De voorbeelden op deze pagina roepen de API aan via een kleine helper die bij elk verzoek de versieheader meestuurt.

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

Stuur bij elke `POST` een [`Idempotency-Key`](https://docs.whop.com/nl/developer/api/idempotency) mee, zodat een nieuwe poging nooit een tweede factuur aanmaakt of een actie herhaalt. Generate Invoice PDF is de uitzondering: elke aanroep maakt een nieuw bestand, dus antwoorden worden niet opnieuw afgespeeld.

## Een concept maken

[Create Invoice](https://docs.whop.com/nl/api-reference/invoices/create-invoice.md) slaat een concept op met `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" }
  }'
```

Het antwoord is `201 Created` met het concept. Een concept aanmaken brengt niets in rekening, verstuurt geen e-mail en verstuurt geen webhook. Dit antwoord toont een deel van de velden:

```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` is het account dat de factuur uitgeeft, met het voorvoegsel `biz_`. Een account-API-sleutel kan het weglaten om het eigen account te gebruiken. [Create Invoice](https://docs.whop.com/nl/api-reference/invoices/create-invoice.md) vermeldt elk verzoek- en antwoordveld.

Een concept gebruikt zijn nummer bij het aanmaken, dus een concept dat je weggooit, laat een gat in je reeks achter. Om een concept weg te gooien, [verwijder je het](#delete-an-invoice). Om het in je lijst te houden, [maak je het in plaats daarvan ongeldig](#void-or-mark-uncollectible).

### Items toevoegen

`items` accepteert 1 tot 50 items. Elk item accepteert ofwel `plan_id` voor een bestaande variant, ofwel `plan` om er inline een te vinden of aan te maken, plus een optionele `quantity`.

Een inline `plan` gebruikt dezelfde find-or-create-invoer als [Create Payment](https://docs.whop.com/nl/api-reference/payments/create-payment.md), bijvoorbeeld `{ "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }`. Het vereist `plan:create`, en een inline `product` vereist ook de productmachtiging, `access_pass:create` of `access_pass:update`.

Aanmaken en bijwerken weigeren items die deze regels overtreden:

* Elk item is een buy-now-variant van je account. Een variant komt één keer voor, dus gebruik `quantity` voor meer eenheden.
* Geen enkele variant is gearchiveerd, en uitgeven of verzenden van een concept controleert dit opnieuw, dus haal de variant uit het archief of kies een andere.
* `quantity` ligt tussen 1 en 999.999, en is alleen hoger dan 1 voor een variant die meerdere hoeveelheden toestaat. Terugkerende varianten doen dat niet, dus de hoeveelheid van een terugkerend item is 1.
* Een terugkerende variant moet bij een product horen.
* Elk item gebruikt dezelfde valuta.
* In een factuur met meerdere items moet elk item met een product een gewoon product zijn (het standaardproducttype), geen app. Terugkerende items delen één factureringsperiode, lengte van de gratis proefperiode en `split_pay_required_payments`, en alle items hebben compatibele betalings-, belasting- en toegangsinstellingen nodig. Varianten met aangepaste velden of een wachtwoord kunnen niet worden gecombineerd. Items zonder product, zoals een aangepaste vergoeding, kunnen naast de rest staan.

Elk regelitem in het antwoord heeft een `label`, de titel van het product, of de titel van de variant voor een variant zonder product. De e-mail, de pdf en de checkout tonen het.

Het concept behoudt de prijs die elke variant had toen je de items opsloeg, dus een latere prijswijziging van de variant verandert de factuur niet. Een eenmalig item wordt tegen zijn prijs gefactureerd. Vanaf API-versie `2026-11-11` neemt het aanmaken of vervangen van een terugkerend item de `initial_price` plus `renewal_price` op in de eerste factuur. Eerdere versiepins gebruiken alleen de verlengingsprijs. Bewerkingen die `items` weglaten, behouden de opgeslagen prijzen.

### De klant en factuurgegevens instellen

| Veld | Wat het doet |
| - | - |
| `member_id` | De klant, een bestaand lid van het account met het voorvoegsel `mber_`. |
| `email_address`, `customer_name` | De klant op basis van e-mailadres, in plaats van `member_id`. Whop gebruikt het lid van het account met dat e-mailadres, daarna een Whop-gebruiker ermee, en maakt een gebruiker aan als geen van beide bestaat. `customer_name` geeft een nieuwe gebruiker een naam. |
| `billing_address` | Een nieuw factuuradres voor de klant, met `line1`, `city`, `postal_code` en een ISO 3166-1 alpha-2 `country`, plus optioneel `name`, `line2`, `state` en `phone`. |
| `mailing_address_id` | In plaats daarvan een van de opgeslagen adressen van de klant, met het voorvoegsel `ma_`. |
| `payment_method_id` | Een opgeslagen betaalmethode van de klant, met het voorvoegsel `payt_`. Whop belast deze wanneer je de factuur uitgeeft. Zie [Een opgeslagen betaalmethode belasten](#charge-a-saved-payment-method). |
| `due_at` | Wanneer de betaling verschuldigd is, als ISO 8601-tijdstempel. Het bepaalt `overdue`, de herinneringsdata en de vervaldatum die de e-mail, de pdf en de checkout tonen. |
| `buyer_fee_percentage` | Een vergoeding die de koper betaalt, als percentage van het subtotaal van 0 tot 100 met maximaal twee decimalen. Het antwoord retourneert het percentage als `buyer_fee_percentage` en de vergoeding als `buyer_fee_amount`. |
| `recipient_emails` | Maximaal 50 adressen die de factuurmail ontvangen, los van de gefactureerde klant. Standaard het e-mailadres van de klant bij het aanmaken van het concept. Een update die het weglaat, behoudt de opgeslagen lijst, ook als de klant verandert. Opslaan verstuurt geen e-mail. Zie [Wie de e-mail ontvangt](#who-gets-the-email). |
| `metadata` | Maximaal 50 eigen sleutel-waardeparen als strings. Whop kopieert ze naar het lidmaatschap dat het aanmaakt wanneer je de factuur uitgeeft, en naar de automatische afschrijving. |

Stuur `member_id` of `email_address`, en `billing_address` of `mailing_address_id`, nooit beide van een paar. Een factuuradres vereist een klant. Een klant is optioneel bij een concept en verplicht om het uit te geven.

Whop berekent de belasting wanneer je de factuur uitgeeft en gebruikt het factuuradres om de klant te lokaliseren. Als er belasting van toepassing is en Whop niet kan bepalen waar de klant zich bevindt, wordt het uitgeven geweigerd, dus voeg altijd een factuuradres toe wanneer je belasting int.

### Een concept bewerken

[Update Invoice](https://docs.whop.com/nl/api-reference/invoices/update-invoice.md) wijzigt een concept met `PATCH /invoices/{id}`. Stuur alleen de velden die je wijzigt.

```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` vervangt de hele lijst en leest de huidige prijs van elke variant. Laat het weg om de opgeslagen items en prijzen te behouden.
* Het wijzigen van `member_id` verwijdert het opgeslagen factuuradres en de opgeslagen betaalmethode, tenzij je nieuwe meestuurt. `recipient_emails` blijft behouden, dus stuur ook een nieuwe lijst mee, anders ontvangt de vorige klant nog steeds de factuurmail.
* `email_address` en `customer_name` worden niet geaccepteerd. Stuur een andere `member_id` om iemand anders te factureren.
* Een concept met een [geplande verzending](#schedule-a-send) accepteert alleen een wijziging van `recipient_emails` totdat je de verzending annuleert.
* Zodra de factuur is uitgegeven, is de enige wijziging die je kunt doen `recipient_emails`, los meegestuurd, en alleen zolang de factuur `open` of `uncollectible` is. Elke andere bewerking wordt geweigerd met een `400`.

## Kiezen hoe de klant betaalt

Er zijn twee manieren om voor een uitgegeven factuur betaald te krijgen. Kies er een voordat je de factuur uitgeeft, omdat de opgeslagen betaalmethode op het concept komt.

| | Een opgeslagen betaalmethode belasten | Klant betaalt via checkout |
| - | - | - |
| **Klant aanwezig** | Nee. Whop belast de methode off-session. | Ja, op de gehoste checkout van Whop |
| **Wat je nodig hebt** | `payment_method_id` op het concept | De `checkout_link` van de factuur |
| **3D Secure** | De afschrijving kan geen verificatie voltooien | De klant voltooit deze |
| **Je betalingsregels** | `block` en `allow` zijn van toepassing | Alle vier de acties zijn van toepassing |

Een uitgegeven factuur krijgt een `checkout_link`, ook als er een opgeslagen betaalmethode op staat. Als de automatische afschrijving mislukt, kan de klant nog steeds via de checkout betalen.

### Een opgeslagen betaalmethode belasten

Zet een opgeslagen betaalmethode op het concept met `payment_method_id`. Het moet een van de opgeslagen methoden van de klant zijn. [Betaalmethoden opslaan](https://docs.whop.com/nl/developer/guides/save-payment-methods.md) laat zien hoe een klant er een opslaat, en [List payment methods](https://docs.whop.com/nl/api-reference/legacy/payment-methods/list-payment-methods.md) vindt de methoden die een lid heeft.

Wanneer je de factuur uitgeeft of verzendt en het totaal hoger is dan nul, doet Whop het volgende:

1. Voert dezelfde controles uit die [Create Payment](https://docs.whop.com/nl/api-reference/payments/create-payment.md) uitvoert op een opgeslagen betaalmethode.
2. Reserveert voorraad voor de gefactureerde hoeveelheden en bereidt de vergoedingen van de betaling voor.
3. Retourneert de factuur als `open` en belast de methode off-session. De afschrijving vindt plaats op de `charge_at` die je aan Issue Invoice of Send Invoice meegeeft, anders op `due_at` zolang die nog in de toekomst ligt, en anders direct. `scheduled_charge_at` toont een afschrijving die nog moet plaatsvinden.

Het antwoord vertelt je niet of de afschrijving is geslaagd. Lever uit vanuit de [`payment.succeeded`-webhook](#webhooks) voor het `pay_`-ID van de factuur. Een betaalde factuur voltooit het lidmaatschap, en je `metadata` staat op de afschrijving en het lidmaatschap. [Betalingsregels bij factuurbetalingen](#payment-rules-on-invoice-payments) beschrijft hoe je betalingsregels de afschrijving screenen.

### Als de automatische afschrijving wordt geweigerd

Een geweigerde afschrijving laat de factuur `open` en geeft de gereserveerde voorraad vrij. [Haal de factuur op als betaling](https://docs.whop.com/nl/api-reference/payments/retrieve-payment.md) en lees `failure_message` om te zien waarom de laatste poging is mislukt.

Wanneer de afschrijving wordt geweigerd of een actie van de klant vereist, mailt Whop de betaallink van de factuur naar de [ontvangers](#who-gets-the-email), zodat de klant in plaats daarvan via de checkout kan betalen. Het is de enige e-mail die Whop verstuurt voor een factuur die je uitgeeft zonder deze te verzenden. Hiervoor zijn een `checkout_link` en minstens één item in `recipient_emails` nodig, en het telt niet mee voor de [verzendlimiet](#send-limit).

> [!WARNING]
>
> Een off-session afschrijving kan de klant geen 3D Secure-verificatie tonen. Als de bank erom vraagt, wordt de automatische afschrijving niet voltooid en blijft de factuur onbetaald totdat de klant zich verifieert of op een andere manier betaalt.

## De factuur uitgeven

[Issue Invoice](https://docs.whop.com/nl/api-reference/invoices/issue-invoice.md) maakt van een concept een open factuur. Whop controleert de factuur opnieuw, berekent de definitieve belasting en zet `status` op `open` en `totals_status` op `final`. Als de factuur een opgeslagen betaalmethode en een totaal boven nul heeft, belast Whop deze vervolgens, zoals beschreven in [Een opgeslagen betaalmethode belasten](#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"
```

* **De belasting wordt definitief.** `tax_amount` is `null` bij een concept en wordt ingesteld zodra je het uitgeeft. `total` en `amount_due` bevatten de belasting.
* **Whop maakt het lidmaatschap van de klant aan** wanneer de factuur een product factureert. Het blijft een concept, zonder toegang, totdat de factuur is betaald. Een factuur waarvan geen enkel item een product heeft, krijgt geen lidmaatschap.
* **`payment.created` wordt één keer geactiveerd** voor het `pay_`-ID van de factuur.
* **Opnieuw uitgeven is veilig.** Een factuur uitgeven die al `open` is, voert dezelfde controles opnieuw uit en retourneert de factuur ongewijzigd als ze slagen: de totalen blijven staan en er wordt niets opnieuw afgeschreven.
* **Uitgeven mailt de factuur niet,** behalve de [betaallink na een geweigerde afschrijving](#if-the-automatic-charge-is-declined). Om de factuur te mailen, [verzend je deze](#send-schedule-and-remind), of je bezorgt de checkoutlink zelf.

Een geweigerde uitgifte wijzigt niets en schrijft niets af. Los de oorzaak op en geef de factuur opnieuw uit. [Fouten bij uitgeven](#issue-errors) somt de redenen op.

### De checkoutlink ophalen

Een uitgegeven factuur met de status `open` heeft een `checkout_link`, een ondertekende waarde in de vorm `pay_xxxxxxxxxxxxx.<signature>`. Deze opent de factuur tegen de vaste prijs op de gehoste checkout van Whop.

**1. Lees de link uit de uitgegeven factuur**

`checkout_link` is `null` tenzij de factuur `open` is, dus concepten en betaalde, ongeldige of oninbare facturen hebben er geen. Het is ook `null` voor een factuur die aan een zakelijke koper is gericht, een factuur waarvan het lidmaatschap is opgezegd, en wanneer je credential geen `payment:charge` heeft. Een zakelijke koper is een klant die een ander Whop-account is in plaats van een persoon.

**2. Stel de URL van de gehoste checkout samen**

Splits de link bij de eerste `.`: het `pay_`-ID van de factuur staat ervoor en het token erachter.

```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. Stuur hem naar de klant**

[Verzend de factuur](#send-schedule-and-remind) om Whop de link te laten mailen, of zet de URL in je eigen e-mail of factuurpagina. Alleen de klant van de factuur kan ermee betalen. Iedereen anders wordt geweigerd en gevraagd in te loggen als de klant van de factuur. De link werkt niet meer zodra de factuur is betaald, ongeldig gemaakt of als oninbaar gemarkeerd.

**4. Lever uit vanuit de webhook**

Luister naar `payment.succeeded` voor het `pay_`-ID van de factuur, net als bij de automatische afschrijving. [Webhooks](#webhooks) toont een handler.

De checkout toont het factuurnummer en de vervaldatum naast de items, en de vervaldatum wordt rood zodra deze is verstreken. De klant betaalt de items en het totaal op de factuur en kan geen promotiecode toevoegen.

## Verzenden, inplannen en herinneren

[Send Invoice](https://docs.whop.com/nl/api-reference/invoices/send-invoice.md) mailt een factuur met `POST /invoices/{id}/send`. Een concept verzenden geeft het eerst uit, net als Issue Invoice. Een `open` factuur verzenden mailt deze opnieuw.

```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()))
```

De e-mail toont de naam en het logo van je account, het factuurnummer, het totaal, de vervaldatum, elk item en een knop die de checkout van de factuur opent. Whop mailt alleen een factuur die de klant vanuit de e-mail kan betalen. Een `open` factuur heeft een `checkout_link` nodig om te worden verzonden, en een concept heeft een klant nodig die geen zakelijke koper is. Een concept dat aan een zakelijke koper is gericht, kan nog steeds worden verzonden als het een opgeslagen betaalmethode heeft, omdat het dan in plaats daarvan wordt afgeschreven.

### Wie de e-mail ontvangt

Elke verzending mailt elk adres één keer, als aparte e-mail, zodat ontvangers elkaars adressen nooit zien. De adressen zijn:

* Het e-mailadres van het Whop-account van de klant, dat de factuur-pdf onder **Bill to** afdrukt.
* Elk item in `recipient_emails`.

Whop slaat `recipient_emails` op in kleine letters en ontdubbelt de lijst, dus een adres dat in beide voorkomt, krijgt één e-mail.

Een lege `recipient_emails` betekent dat Whop niemand mailt, ook de klant niet. Gebruik dit om te voorkomen dat Whop een factuur mailt:

* Send Invoice weigert de factuur, tenzij er in plaats daarvan een opgeslagen betaalmethode wordt belast.
* Er gaat geen [betaallink](#if-the-automatic-charge-is-declined) uit na een geweigerde afschrijving.
* Er gaan geen herinneringen uit. Het leegmaken van `recipient_emails` op een `open` factuur stopt de resterende herinneringen.

### Wanneer Whop afschrijft in plaats van mailt

Een concept met een `payment_method_id` en een totaal boven nul wordt afgeschreven in plaats van gemaild, net als wanneer je het uitgeeft. [Als de automatische afschrijving wordt geweigerd](#if-the-automatic-charge-is-declined) beschrijft wat er gebeurt als de afschrijving mislukt. Zo'n concept kan worden verzonden met een lege `recipient_emails`, omdat niemand de e-mail nodig heeft.

### Verzendlimiet

Elke factuur kan drie keer per 24 uur worden gemaild, inclusief de verzending waarmee deze is uitgegeven. Een vierde verzending binnen die periode wordt geweigerd met een `429` waarvan de `error.code` `invoice_send_limit_reached` is. Herinneringen, de [betaallink na een geweigerde afschrijving](#if-the-automatic-charge-is-declined) en een verzending die afschrijft in plaats van mailt, tellen niet mee voor de limiet.

### Een verzending inplannen

Om een concept later te verzenden, geef je `send_at` mee. Het concept blijft een concept en toont het tijdstip in `scheduled_send_at`. Op dat moment verzendt Whop het alsof je toen Send Invoice had aangeroepen.

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

* **Alleen een concept kan worden ingepland,** en `send_at` moet in de toekomst liggen. Whop controleert de ontvangers en de betaallink bij het inplannen, net als bij direct verzenden.
* **Verzend opnieuw met een nieuwe `send_at`** om het tijdstip te verplaatsen.
* **Bewerken is vergrendeld** totdat de verzending plaatsvindt of je deze annuleert. Een update die alleen `recipient_emails` wijzigt, werkt nog steeds, maar kan niet de laatste ontvanger verwijderen van een concept dat niet wordt afgeschreven.
* **[Cancel Scheduled Send](https://docs.whop.com/nl/api-reference/invoices/cancel-scheduled-send.md)** met `POST /invoices/{id}/unschedule`. `scheduled_send_at` wordt weer `null` en het concept kan weer worden bewerkt. Het annuleren voor een factuur zonder geplande verzending retourneert deze ongewijzigd.
* **Een ingepland concept ongeldig maken** stopt de geplande verzending.

```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 controleert elke minuut op verzendingen die aan de beurt zijn, dus een geplande verzending gaat binnen ongeveer een minuut na `send_at` uit. Als deze wordt geweigerd, bijvoorbeeld omdat een variant is verwijderd sinds je hem inplande, blijft de factuur een concept, wordt `scheduled_send_at` weer `null` en retourneert de API de reden niet. Elke andere fout wordt ongeveer elke 10 minuten opnieuw geprobeerd, tot in totaal 12 pogingen. Totdat een poging slaagt of Whop stopt met opnieuw proberen, toont `scheduled_send_at` het tijdstip van de volgende poging in plaats van `null`. Lees de factuur na `send_at` om te bevestigen dat deze `open` is.

### Herinneringen

Wanneer Send Invoice een factuur met een `due_at` mailt, plant Whop ook herinneringen in op 1, 3, 7, 14, 30 en 60 dagen na `due_at`, waarbij herinneringen waarvan de datum al voorbij is, worden overgeslagen. Elke herinnering gaat naar dezelfde adressen als de factuur en vermeldt hoeveel dagen de factuur over de vervaldatum is.

Herinneringen gaan alleen uit zolang de factuur `open` is, dus ze stoppen zodra de factuur is betaald, ongeldig gemaakt of als oninbaar gemarkeerd. Een herinnering die verschuldigd wordt terwijl een betaling bezig is, wacht tot de betaling is afgerond. Een factuur die je uitgeeft zonder te verzenden, of een die wordt afgeschreven in plaats van gemaild, krijgt geen herinneringen.

### E-mailgeschiedenis

[List Invoice Sends](https://docs.whop.com/nl/api-reference/invoices/list-invoice-sends.md) retourneert geregistreerde e-mailbatches met `GET /invoices/{id}/sends`, de nieuwste eerst. Dit omvat eerste en herhaalde e-mails, ingeplande e-mails, herinneringen en betalingsopvolgingen na een mislukte afschrijving van een opgeslagen betaalmethode. Gebruik het eerste item voor de meest recente geregistreerde verzending, en `page_info.end_cursor` als `after` om oudere items te lezen. Handmatige batches gebruiken `send` als de factuur geen eerdere voltooide e-mailgeschiedenis heeft, en anders `resend`. Het soort wordt gekozen wanneer de voltooide batch wordt geregistreerd, dus verzoeken die samen in de wachtrij staan, worden in volgorde van voltooiing ingedeeld. Eerdere niet-geregistreerde e-mails blijven onbekend.

Elk item bevat `kind`, `sent_at`, `recipient_count`, `recipients` en `actor`. Het lezen van de geschiedenis vereist `payment:basic:read`. Adressen vereisen ook `member:email:read`. Zonder die machtiging is `recipients` leeg. De afzender vereist ook `company:authorized_user:read`. Anders is `actor` null. Automatische verzendingen en account-API-sleutels hebben ook een null-actor.

De worker voegt een item toe nadat de hele batch ter bezorging is aangeboden. Voor een gedeeltelijke batch voegt hij alleen een item toe als een nieuwe poging de batch voltooit. Het item behoudt de oorspronkelijke ontvangerslijst. Een geregistreerde batch bevestigt geen bezorging in de inbox. De mailer kan berichten onderdrukken als de factuur of de ontvangers vóór de bezorging veranderen. De geschiedenis bevat geen e-mails die zijn verzonden voordat deze functie werd geïntroduceerd. Een factuur uitgeven zonder te mailen voegt geen item aan de geschiedenis toe.

## Een pdf downloaden

[Generate Invoice PDF](https://docs.whop.com/nl/api-reference/invoices/generate-invoice-pdf.md) bouwt de factuur als pdf en retourneert een kortlevende link ernaartoe. Het vereist `payment:basic:read` en werkt bij elke status.

```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"])
```

Het antwoord bevat `url` en `expires_at`. De link werkt 15 minuten en iedereen die hem heeft, kan het bestand downloaden. Genereer een nieuwe wanneer hij verloopt.

De pdf begint met je bedrijf: de naam van je account staat bovenaan de pagina en de voettekst vermeldt dat Whop Inc de factuur op jouw naam en namens jou uitgeeft. De pdf toont het factuurnummer, de factuurdatum en vervaldatum, en de gegevens onder **Bill to**. Elk item toont de hoeveelheid, de eenheidsprijs en het bedrag, gevolgd door het subtotaal, de servicekosten, de belasting en het verschuldigde bedrag. Een factuur met een terugkerend item vermeldt ook het verlengingsbedrag en hoe vaak er wordt verlengd. De pdf van een concept toont de geschatte totalen, met belasting op nul totdat je het uitgeeft.

Sommige inhoud hangt af van de machtigingen van je credential:

| Machtiging | Voegt toe aan de pdf |
| - | - |
| `member:basic:read` | De naam van de klant onder **Bill to**. Zonder deze machtiging toont de pdf alleen een naam die op het factuuradres is opgeslagen. |
| `member:email:read` | Het e-mailadres van de klant onder **Bill to** |
| `payment:charge` | Een link **Pay now** die de checkout van de factuur opent, op een factuur met een `checkout_link` |

## Een abonnement factureren

Zet een terugkerende variant op een factuur om een abonnement te starten wanneer de klant deze betaalt. Whop verlengt het daarna één keer per factureringsperiode.

1. **De factuur factureert de eerste periode en eventuele vooruitbetaalde kosten.** Een terugkerend item moet bij een product horen en heeft een hoeveelheid van 1. Vanaf API-versie `2026-11-11` factureert de eerste factuur `initial_price` plus `renewal_price`. Betalen start direct de eerste betaalde factureringsperiode, tenzij de variant een gratis proefperiode heeft. Dan [begint het abonnement met de proefperiode](#start-with-a-free-trial). In het dashboard heeft een aangepast terugkerend item een optioneel veld **Upfront fee**. De `initial_price` van het regelitem geeft dat eenmalige deel van `unit_amount` aan, en de factuurpagina, de e-mail en de pdf vermelden het op een eigen regel **Upfront fee**.
2. **Het betalen van de factuur start het abonnement,** of Whop nu de opgeslagen betaalmethode bij uitgifte belast of de klant via de `checkout_link` betaalt. De eerste periode begint bij de betaling. De checkout die vanuit de link wordt geopend, vermeldt het verlengingsbedrag, inclusief de kopersvergoeding van de factuur, en hoe vaak er wordt verlengd.
3. **Elke verlenging wordt geïnd op de manier die je koos toen je de factuur uitgaf of verzond.** Ze factureert alleen de terugkerende items, met de kopersvergoeding van de factuur, tegen de verlengingsprijs die elke variant had toen je de factuur uitgaf. Die kan afwijken van de prijs die op het concept is opgeslagen als de prijs van de variant is gewijzigd nadat je de items opsloeg. Eenmalige items worden één keer gefactureerd.

Geef `collection_method` mee aan [Issue Invoice](https://docs.whop.com/nl/api-reference/invoices/issue-invoice.md) of [Send Invoice](https://docs.whop.com/nl/api-reference/invoices/send-invoice.md) om te kiezen hoe verlengingen worden geïnd. Een geplande verzending past de `collection_method` toe waarmee je deze hebt ingepland, die het concept als `scheduled_collection_method` toont.

| `collection_method` | Elke verlenging |
| - | - |
| `charge_automatically` | Belast de betaalmethode waarmee de factuur is betaald: de `payment_method_id` van het concept, of de methode waarmee de klant via de factuurlink betaalt. De standaard. |
| `send_invoice` | Geeft een nieuwe genummerde factuur uit die op de verlengingsdatum verschuldigd is, en mailt deze met de betaallink en herinneringen naar de `recipient_emails` van de laatste factuur |

`send_invoice` vereist minstens één adres in `recipient_emails` en is niet beschikbaar voor facturen die aan een bedrijf zijn gericht. Zolang het van toepassing is, kan de laatste ontvanger van de factuur niet worden verwijderd. Een factuur zonder terugkerend item weigert `collection_method`. Het betalen van de eerste factuur met een kaart behoudt `send_invoice`.

Elke verlenging is een eigen betaling, met een eigen `pay_`-ID en eigen `payment.*`-webhooks. Een `charge_automatically`-verlenging is geen genummerde factuur, dus deze verschijnt niet in List Invoices. Een `send_invoice`-verlenging is een genummerde factuur in List Invoices, en Whop schrijft deze niet automatisch af. Het abonnement blijft `past_due` totdat de klant betaalt via de `checkout_link` van de factuur. De klant behoudt in de tussentijd toegang. [Zeg het lidmaatschap op](https://docs.whop.com/nl/api-reference/memberships/cancel-membership.md) om verlengingen te stoppen. Zodra het lidmaatschap is opgezegd, werkt de `checkout_link` van een openstaande verlengingsfactuur niet meer.

Om het abonnement te vinden, [haal je de factuur op als betaling](https://docs.whop.com/nl/api-reference/payments/retrieve-payment.md) en lees je de `membership_id`, waarvoor `member:basic:read` nodig is.

### Beginnen met een gratis proefperiode

Een factuur respecteert de `trial_period_days` van een terugkerende variant, net als de checkout. De eerste factuur factureert alleen de `initial_price` van de variant. Het betalen ervan start de proefperiode, en de eerste verlenging factureert `renewal_price` wanneer de proefperiode eindigt. Facturen die vóór 2026-11-16 17:00 UTC zijn aangemaakt, factureren de eerste periode en slaan de proefperiode over.

* Een klant die al een abonnement op de variant had, krijgt geen proefperiode. De eerste factuur factureert `initial_price` plus `renewal_price`. Verlengingsfacturen starten nooit een proefperiode.
* De proefperiode komt van de variant. Stel voor een aangepast terugkerend item `variant.trial_period_days` in. Een `trial_period_days` op itemniveau wordt geweigerd.
* Elk terugkerend item op de factuur heeft dezelfde lengte van de proefperiode nodig.
* Als de factuur niets in rekening brengt, geef je deze uit of verzend je deze met een `payment_method_id`, waarmee de proefperiode direct start, of met `collection_method: "send_invoice"`.
* In het dashboard heeft een aangepast terugkerend item een veld **Free trial days**. Het factureringsplan van een product toont zijn eigen proefperiode.

### Stoppen na een vast aantal betalingen

Om een vast betalingsplan te factureren, zoals zes maandelijkse betalingen, stel je `split_pay_required_payments` in op de terugkerende variant, van 2 tot 115. De factuur is de eerste betaling, inclusief eventuele vooruitbetaalde kosten. Een vooruitbetaling van $75 met drie termijnen van $40 factureert bijvoorbeeld $115, dan $40 en dan \$40. Whop stopt met verlengen zodra dat aantal betalingen is gedaan, en het lidmaatschap blijft actief. De klant kan het abonnement vóór die tijd niet zelf opzeggen, maar jij wel. Laat het leeg om te verlengen totdat het abonnement wordt opgezegd.

## Statussen en levenscyclus

| `status` | Wat het betekent | Wat er daarna kan gebeuren |
| - | - | - |
| `draft` | Je kunt het nog bewerken. De totalen zijn een schatting en de belasting is nog niet berekend. | Je geeft het uit, verzendt het, plant het in, maakt het ongeldig of verwijdert het |
| `open` | Uitgegeven. Totalen en belasting zijn definitief en de factuur wacht op betaling. | De klant betaalt, of je maakt de factuur ongeldig of markeert deze als oninbaar |
| `paid` | De klant heeft betaald. `amount_due` is nul. | Niets |
| `uncollectible` | Je hebt een open factuur gemarkeerd als een factuur die je niet verwacht te innen. | Je maakt de factuur ongeldig |
| `void` | Geannuleerd. `amount_due` is nul. | Je verwijdert de factuur |

`status` neemt zijn waarden over van betalingen, dus een factuur kan ook een betalingsstatus tonen, zoals `pending`, terwijl een betaling bezig is. `totals_status` vertelt je of de geldvelden definitief zijn: `estimated` zolang de factuur een concept is, `final` nadat je deze hebt uitgegeven. `overdue` is `true` voor een `open` of `uncollectible` factuur waarvan de `due_at` is verstreken.

### Ongeldig maken of als oninbaar markeren

[Void Invoice](https://docs.whop.com/nl/api-reference/invoices/void-invoice.md) annuleert een factuur met de status `draft`, `open` of `uncollectible`. Een factuur ongeldig maken die al ongeldig is, retourneert deze ongewijzigd, en een betaalde factuur kan niet ongeldig worden gemaakt.

[Markeer een factuur als oninbaar](https://docs.whop.com/nl/api-reference/invoices/mark-invoice-uncollectible.md) om vast te leggen dat je niet verwacht deze te innen. Alleen een `open` factuur kan worden gemarkeerd, en een oninbare factuur opnieuw markeren retourneert deze ongewijzigd. Een oninbare factuur heeft geen `checkout_link` en krijgt geen herinneringen.

Dit voorbeeld markeert een `open` factuur als oninbaar en maakt deze daarna ongeldig:

```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()))
```

### Een factuur verwijderen

[Delete Invoice](https://docs.whop.com/nl/api-reference/invoices/delete-invoice.md) verwijdert een factuur met de status `draft` of `void` met `DELETE /invoices/{id}`. Het antwoord is `{ id, deleted: true }`. Een verwijderde factuur verschijnt niet meer in List Invoices of List Payments, en het ID ervan retourneert een `404`. Je kunt een verwijdering niet ongedaan maken.

Maak een `open` factuur ongeldig voordat je deze verwijdert. Een concept met een geplande verzending of afschrijving heeft eerst [Cancel Scheduled Send](https://docs.whop.com/nl/api-reference/invoices/cancel-scheduled-send.md) nodig. Een verlengingsfactuur in concept kan niet worden verwijderd zolang deze een abonnement factureert. Een ongeldige factuur die geld heeft geïnd of nog op een bankoverschrijving wacht, kan niet worden verwijderd, en een betaalde, lopende of oninbare factuur ook niet. Het veld `deletable` van een factuur is `true` als deze kan worden verwijderd.

Verwijderen vereist `invoice:update` of `payment:charge`. Het nummer van een verwijderd concept wordt niet hergebruikt.

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

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

## Facturen weergeven en ophalen

[List Invoices](https://docs.whop.com/nl/api-reference/invoices/list-invoices.md) retourneert de facturen die je credential kan lezen, de nieuwste eerst. Een API-sleutel ziet het eigen account, en een gebruikerstoken ziet elk account waarvan de gebruiker betalingen kan lezen. Beperk de lijst met deze queryparameters:

| Parameter | Filtert op |
| - | - |
| `account_id` | Eén account |
| `status` | Eén status, zoals `open`. Een onbekende waarde geeft een `400`. |
| `overdue` | `true` voor achterstallige facturen, `false` voor de rest |
| `scheduled` | `true` voor ingeplande concepten, `false` voor de rest |
| `member_id` | Eén klant |
| `product_id` | Facturen die een product factureren, met het voorvoegsel `prod_` |
| `created_after`, `created_before` | Een aanmaakperiode, als ISO 8601-tijdstempels |

Een ingepland concept is een concept met een `scheduled_send_at`. Een `open` factuur is nooit ingepland, en een concept dat op de vervaldatum wordt verzonden ook niet.

Sorteer met `order` (`created_at`, `due_at` of `scheduled_send_at`) en `direction` (`asc` of `desc`). Sorteren op `due_at` of `scheduled_send_at` zet facturen zonder die datum achteraan. Het antwoord is `{ data, page_info }`. Zolang `page_info.has_next_page` `true` is, geef je `page_info.end_cursor` mee als `after` om de volgende pagina te lezen.

```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/nl/api-reference/invoices/retrieve-invoice.md) leest één factuur op basis van het `pay_`-ID. [List Payments](https://docs.whop.com/nl/api-reference/payments/list-payments.md) laat concepten weg.

Om facturen als csv-bestand te exporteren, roep je [Create Export](https://docs.whop.com/nl/api-reference/exports/create-export.md) aan met `resource: "receipt_invoices"`. Dit vereist `payment:basic:read` en `payment:basic:export`. De klantkolommen verschijnen alleen als je credential ook `member:basic:read` of `member:email:read` heeft.

## Webhooks

Native facturen versturen betalingswebhooks voor hun `pay_`-ID. De `invoice.*`-events horen bij de legacy-factuur-API, en native facturen versturen ze niet.

| Event | Wanneer |
| - | - |
| `payment.created` | Je geeft de factuur uit. Concepten versturen niets. |
| `payment.succeeded` | De factuur is betaald. Lever uit vanuit dit event. |

Andere `payment.*`-events, zoals `payment.failed`, kunnen ook binnenkomen voor het `pay_`-ID van de factuur wanneer de betalingspogingen veranderen. Abonneer je erop met de [webhooksgids](https://docs.whop.com/nl/developer/guides/webhooks.md).

Om een bestelling uit te leveren, sla je het `id` van de factuur op bij de bestelling wanneer je het concept aanmaakt. De `data` van een `payment.succeeded`-event is de betaling, dus `data.id` is het `pay_`-ID van de factuur. Nadat je [het event hebt geverifieerd](https://docs.whop.com/nl/developer/guides/webhooks.md#verify-and-handle-events), zoek je de bestelling op met dat ID. In deze handler staat `orders` voor je eigen bestellingenopslag:

```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)
```

Het controleren van `fulfilled` voorkomt dat een opnieuw bezorgd event de bestelling twee keer uitlevert. Abonnementsverlengingen hebben hun eigen `pay_`-ID's, dus ze komen niet overeen met een factuur.

## Betalingsregels bij factuurbetalingen

Je [betalingsregels](https://docs.whop.com/nl/developer/guides/manage-fraud.md) worden op factuurbetalingen uitgevoerd na de eigen fraudescreening van Whop, net als bij elke checkout. Wat ze kunnen doen, hangt af van of de klant aanwezig is.

* **De automatische afschrijving bij uitgifte is off-session.** Een `block`-regel weigert deze, en een `allow`-regel stelt deze vrij van je andere regels. `review`- en `enforce_3ds`-regels worden overgeslagen omdat de afschrijving off-session is.
* **Een betaling via de checkoutlink is on-session.** Alle vier de acties zijn van toepassing, met de geschiktheidslimieten uit [Fraude beheren](https://docs.whop.com/nl/developer/guides/manage-fraud.md).

Bij de automatische afschrijving lezen kaartvoorwaarden de opgeslagen betaalmethode en factuurvoorwaarden het factuuradres van de factuur. `customer_email` is het e-mailadres van het Whop-account van de klant. De `payment_rule_matches` van de betaling vermeldt de regel die de beslissing nam. Een overgeslagen regel wordt niet vermeld.

## Facturen in het dashboard

De pagina **Invoices** toont, maakt en verzendt native facturen. Legacy-facturen staan op het tabblad **Legacy invoices**, dat wordt beschreven in [Een factuur verzenden](https://docs.whop.com/nl/payments/send-an-invoice.md).

## Machtigingen

| Aanroep | Machtiging |
| - | - |
| [Aanmaken](https://docs.whop.com/nl/api-reference/invoices/create-invoice.md), [bijwerken](https://docs.whop.com/nl/api-reference/invoices/update-invoice.md), [uitgeven](https://docs.whop.com/nl/api-reference/invoices/issue-invoice.md), [verzenden](https://docs.whop.com/nl/api-reference/invoices/send-invoice.md), [een geplande verzending annuleren](https://docs.whop.com/nl/api-reference/invoices/cancel-scheduled-send.md), [ongeldig maken](https://docs.whop.com/nl/api-reference/invoices/void-invoice.md) of [als oninbaar markeren](https://docs.whop.com/nl/api-reference/invoices/mark-invoice-uncollectible.md) | `payment:charge` |
| [Weergeven](https://docs.whop.com/nl/api-reference/invoices/list-invoices.md), [ophalen](https://docs.whop.com/nl/api-reference/invoices/retrieve-invoice.md) of [een pdf genereren](https://docs.whop.com/nl/api-reference/invoices/generate-invoice-pdf.md) | `payment:basic:read` |

Elke schrijfbewerking vereist `payment:charge`, dezelfde machtiging als [Create Payment](https://docs.whop.com/nl/api-reference/payments/create-payment.md), en elke leesbewerking vereist `payment:basic:read`. De `invoice:*`-machtigingen horen bij de legacy-factuur-API, en native facturen gebruiken ze niet. Aanmaken of bijwerken met een inline `plan`-item vereist ook `plan:create`.

Sommige velden vereisen een eigen machtiging. Zonder die machtiging komt het veld terug als `null`, en `recipient_emails` komt leeg terug.

| Machtiging | Velden die het zichtbaar maakt |
| - | - |
| `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` |

Als je credential na een `POST` een van deze leesmachtigingen verliest, wordt het opnieuw afspelen met dezelfde `Idempotency-Key` geweigerd met een `403` waarvan de `error.code` `invoice_replay_permission_revoked` is, wanneer het opgeslagen antwoord die velden toont. Haal de factuur in plaats daarvan op met `GET`. Voeg machtigingen toe via de [gids over machtigingen](https://docs.whop.com/nl/developer/guides/permissions.md).

## Fouten

Weigeringen komen terug als `{ error: { type, message, code } }`. Elke onderstaande code is een `400`, tenzij anders vermeld. Een onbekende `plan_id`, `member_id`, `mailing_address_id` of `payment_method_id` is een `404`, en een tijdstempel die Whop niet kan lezen, is een `400` met `invalid_timestamp`.

Deze weigeringen zijn een `400` zonder `error.code`, dus lees `error.message` voor de reden:

* Een onbekend veld op het hoogste niveau.
* Een `quantity` buiten 1 tot 999.999.
* Een ongeldig adres in `recipient_emails`, of meer dan 50 adressen.
* Een overtreden regel voor meerdere items, zoals een verschil in factureringsperiode.

### Fouten bij aanmaken en bijwerken

| `error.code` | Waarom |
| - | - |
| `invoice_item_count_invalid`, `invoice_item_invalid` | `items` heeft niet 1 tot 50 items, of een item heeft niet precies één van `plan_id` en `plan`. |
| `invoice_plan_account_mismatch`, `invoice_plan_duplicated`, `invoice_currency_mismatch` | Een variant hoort bij een ander account, komt twee keer voor of gebruikt een andere valuta dan de rest. |
| `invoice_quantity_unsupported` | `quantity` is hoger dan 1 voor een variant die geen meerdere hoeveelheden toestaat. |
| `invoice_plan_type_unsupported`, `invoice_legacy_plan_unsupported` | De variant is geen buy-now-variant of hoort bij een legacy-factuur. |
| `invoice_installment_count_mismatch` | Terugkerende items op de factuur stoppen na verschillende aantallen betalingen. |
| `invoice_recurring_plan_product_required` | Een terugkerende variant heeft geen product. |
| `invoice_plan_unavailable`, `invoice_plan_archived`, `invoice_plan_currency_changed` | Een variant is verwijderd of gearchiveerd, of een opgeslagen variant heeft een andere valuta gekregen. Stuur `items` opnieuw. |
| `invoice_customer_ambiguous`, `invoice_address_ambiguous` | Je hebt zowel `member_id` als `email_address` gestuurd, of zowel `billing_address` als `mailing_address_id`. |
| `invoice_address_properties_invalid`, `invoice_address_incomplete`, `invoice_address_country_invalid` | `billing_address` heeft een onbekend veld, mist een verplicht veld of heeft een `country` die geen geldige code is. |
| `invoice_address_member_required`, `invoice_member_mismatch`, `invoice_address_mismatch`, `invoice_payment_method_mismatch` | Het adres heeft geen klant, of het lid, het adres of de betaalmethode hoort bij iemand anders. |
| `invoice_payment_method_unsupported` | De opgeslagen betaalmethode kan geen facturen betalen. |
| `invoice_buyer_fee_invalid`, `invoice_metadata_invalid`, `invoice_recipients_invalid` | `buyer_fee_percentage` valt buiten het bereik, een `metadata`-waarde is geen string, of `recipient_emails` is geen array. |
| `invoice_not_editable`, `invoice_recipients_not_editable` | De factuur is geen concept, of een wijziging van `recipient_emails` betrof een factuur die geen concept is en niet `open` of `uncollectible` is. |
| `invoice_scheduled_not_editable`, `invoice_scheduled_recipients_required` | Het concept heeft een geplande verzending. Annuleer deze voordat je het bewerkt of de laatste ontvanger verwijdert. |

### Fouten bij uitgeven

| `error.code` | Waarom |
| - | - |
| `invoice_not_issuable` | De factuur is geen concept en niet `open`. |
| `invoice_recipient_required` | De factuur heeft geen klant. |
| `invoice_account_verification_required` | Je account heeft de verificatie niet voltooid. |
| `invoice_account_suspended` | Je account is opgeschort. |
| `invoice_items_required`, `invoice_items_changed`, `invoice_plan_unavailable`, `invoice_plan_archived` | De factuur heeft geen items, of een variant is verwijderd, gearchiveerd of van account, valuta of product gewijzigd. Werk de items bij. |
| `invoice_tax_address_required` | Er is belasting van toepassing en Whop kan niet bepalen waar de klant zich bevindt. Voeg een factuuradres toe. |
| `invoice_tax_unresolved` | De belasting kon niet worden berekend. |
| `invoice_changed_during_issuance`, `invoice_changed_during_calculation` | De factuur is gewijzigd terwijl de belasting werd berekend. Geef deze opnieuw uit. |
| `invoice_payment_method_unavailable`, `invoice_payment_method_unsupported`, `payment_method_unavailable` | De opgeslagen betaalmethode is bij de klant verwijderd, kan geen facturen betalen of werkt niet meer. |
| `out_of_stock` | Alleen bij het belasten van een opgeslagen betaalmethode: een variant heeft niet genoeg voorraad voor de gefactureerde hoeveelheid. |
| `payment_fees_unavailable` | Alleen bij het belasten van een opgeslagen betaalmethode: de vergoedingen van de betaling konden niet worden voorbereid. |

### Fouten bij verzenden en inplannen

Een concept verzenden geeft het uit, dus een verzending kan ook worden geweigerd om elke reden uit [Fouten bij uitgeven](#issue-errors).

| `error.code` | Waarom |
| - | - |
| `invoice_not_sendable` | De factuur is geen concept en niet `open`. |
| `invoice_send_recipients_required` | De factuur heeft geen `recipient_emails` en niets om af te schrijven. |
| `invoice_payment_link_unavailable` | Er is geen betaallink om te mailen: een `open` factuur heeft geen `checkout_link`, of een concept zonder opgeslagen betaalmethode factureert een zakelijke koper. |
| `invoice_send_limit_reached` | Een `429`: de factuur is in de afgelopen 24 uur al drie keer gemaild. |
| `invoice_not_schedulable` | Alleen een concept kan worden ingepland. |
| `invoice_scheduled_send_in_past` | `send_at` ligt niet in de toekomst. |

### Andere fouten

| `error.code` | Waarom |
| - | - |
| `invoice_not_uncollectible` | Alleen een `open` factuur kan als oninbaar worden gemarkeerd. |
| `invoice_replay_permission_revoked` | Een `403`: een idempotente herhaling zou velden tonen die je credential niet meer kan lezen. |

Het ongeldig maken van een betaalde factuur geeft een `400` zonder code.

## Volgende stappen

> [card] [API-referentie voor facturen](https://docs.whop.com/nl/api-reference/invoices/create-invoice.md)
>
> Elk factuur-endpoint, elke parameter en elk antwoordveld.

> [card] [Betaalmethoden opslaan](https://docs.whop.com/nl/developer/guides/save-payment-methods.md)
>
> Verzamel de opgeslagen betaalmethode die een factuur bij uitgifte belast.

> [card] [Fraude beheren](https://docs.whop.com/nl/developer/guides/manage-fraud.md)
>
> Schrijf de betalingsregels die factuurbetalingen screenen.

> [card] [Naar webhooks luisteren](https://docs.whop.com/nl/developer/guides/webhooks.md)
>
> Volg `payment.created` en `payment.succeeded` voor je facturen.


## Related topics

- [Migreren van legacy-facturen](https://docs.whop.com/nl/developer/guides/migrate-from-legacy-invoices.md)
- [Verouderde factuur](https://docs.whop.com/nl/api-reference/legacy/invoices/legacy-invoice.md)
- [QuickBooks](https://docs.whop.com/nl/third-party-integrations/quickbooks.md)
