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

# Factures

> Facturez un client avec une facture numérotée via l'API et encaissez le paiement à partir d'un moyen de paiement enregistré ou d'un checkout hébergé.

Une facture est une note numérotée portant sur une ou plusieurs de vos variantes, adressée à un client. Une variante est une configuration de prix et de facturation que vous vendez, généralement pour un produit. Son ID commence par `plan_`, et les éléments de facture la reçoivent sous la forme `plan_id`. Utilisez une facture lorsque vous convenez d'un prix avec un client avant qu'il ne paie, par exemple pour un devis, une prestation de service ou une commande professionnelle. Vous construisez un brouillon jusqu'à ce qu'il soit correct, puis vous l'émettez pour figer les totaux et l'ouvrir au paiement. L'envoyer fait la même chose et l'envoie par e-mail en un seul appel. Pour en envoyer une depuis votre tableau de bord sans code, consultez [Créer et envoyer des factures](https://docs.whop.com/fr/manage-your-business/manage-payments/send-invoice.md).

> [!NOTE]
>
> Les factures de cette page nécessitent `Api-Version-Date: 2026-10-24` ou une version ultérieure sur chaque requête. Les requêtes avec une version antérieure atteignent l'ancienne API de factures, qui fonctionne différemment. Consultez [Avant de commencer](#before-you-start).

## Fonctionnement d'une facture

Une facture native est un paiement. Son ID commence par `pay_` et reste le même après le paiement du client : vous pouvez donc aussi la lire avec [Retrieve Payment](https://docs.whop.com/fr/api-reference/payments/retrieve-payment.md). Chaque facture reçoit également le numéro suivant dans la séquence propre à votre compte, par exemple `#00000042`, ou `#ACME-00000042` lorsque votre compte dispose d'un préfixe de facture.

1. **Vous créez un brouillon** avec des éléments, un client et des informations de facturation. Un brouillon ne débite rien et n'envoie aucun e-mail.
2. **Vous l'émettez, ou vous l'envoyez.** L'émission calcule la taxe finale et ouvre la facture au paiement. L'envoi l'émet et l'envoie par e-mail, immédiatement ou à une date que vous planifiez.
3. **Le client paie.** Whop débite le moyen de paiement enregistré du client dès que vous émettez ou envoyez la facture, ou bien le client paie via le checkout hébergé de Whop.
4. **Vous traitez la commande** à partir du webhook `payment.succeeded`.

Les factures portent sur des variantes à achat immédiat, c'est-à-dire celles avec `release_method: buy_now` plutôt qu'une liste d'attente. Une variante ponctuelle est facturée une seule fois, et une variante récurrente démarre un abonnement lorsque la facture est payée. Consultez [Facturer un abonnement](#invoice-a-subscription), qui explique aussi comment l'arrêter après un nombre défini de paiements.

## Avant de commencer

### Envoyer la version de l'API

`/invoices` sert deux API différentes, et l'`Api-Version-Date` à laquelle votre requête correspond détermine laquelle répond.

| Vous envoyez | `/invoices` sert |
| - | - |
| `Api-Version-Date: 2026-10-24` ou ultérieure | Les factures natives de cette page |
| Une `Api-Version-Date` antérieure | L'[ancienne API de factures](https://docs.whop.com/fr/api-reference/legacy/invoices/legacy-invoice.md) |
| Aucun en-tête | La version épinglée de vos identifiants. Sans épinglage, l'ancienne API de factures. |
| Une date qui n'est pas une version publiée | Une erreur `400` |

L'émission, l'envoi, l'annulation d'un envoi planifié et la génération d'un PDF n'existent que dans l'API native : ils atteignent donc les factures natives quelle que soit la version envoyée. Les chemins communs aux deux API, comme `GET /invoices` et `POST /invoices/{id}/void`, suivent la version.

Envoyez l'en-tête sur chaque requête plutôt que de vous fier à l'épinglage d'une clé, afin qu'un changement de clé ne vous fasse jamais basculer d'une API à l'autre. [Versions de l'API](https://docs.whop.com/fr/developer/api/versioning.md) explique l'épinglage et le changelog.

| | Factures natives | Anciennes factures |
| - | - | - |
| **ID** | `pay_`, identique à celui du paiement | `inv_` |
| **Ce que vous facturez** | Variantes ponctuelles et récurrentes, sous forme d'`items` | Facturation ponctuelle ou récurrente |
| **E-mail de facture** | Envoyé lorsque vous appelez Send Invoice, avec des relances après `due_at` | Whop envoie la facture par e-mail et des relances |
| **Webhooks** | `payment.*` | `invoice.*` |
| **Tableau de bord** | Onglet **Invoices** : listées, créées et envoyées | Onglet **Legacy invoices** |

L'API native ne liste ni ne récupère les anciennes factures `inv_`, et l'ancienne API ne renvoie pas les factures natives.

### Appeler l'API

Les exemples de cette page appellent l'API via un petit helper qui envoie l'en-tête de version sur chaque requête.

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

Envoyez une [`Idempotency-Key`](https://docs.whop.com/fr/developer/api/idempotency) sur chaque `POST` afin qu'une nouvelle tentative ne crée jamais une seconde facture ni ne répète une action. Generate Invoice PDF fait exception : chaque appel crée un nouveau fichier, il ne rejoue donc pas les réponses.

## Créer un brouillon

[Create Invoice](https://docs.whop.com/fr/api-reference/invoices/create-invoice.md) enregistre un brouillon avec `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 réponse est `201 Created` avec le brouillon. Créer un brouillon ne débite rien, n'envoie aucun e-mail et n'envoie aucun webhook. Cette réponse présente un sous-ensemble des champs :

```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` est le compte qui émet la facture, préfixé `biz_`. Une clé API de compte peut l'omettre pour utiliser son propre compte. [Create Invoice](https://docs.whop.com/fr/api-reference/invoices/create-invoice.md) liste tous les champs de requête et de réponse.

Un brouillon consomme son numéro dès sa création : un brouillon que vous abandonnez laisse donc un trou dans votre séquence. Pour abandonner un brouillon, [supprimez-le](#delete-an-invoice). Pour le conserver dans votre liste, [annulez-le](#void-or-mark-uncollectible) plutôt.

### Ajouter des éléments

`items` accepte de 1 à 50 éléments. Chaque élément prend soit `plan_id` pour une variante existante, soit `plan` pour en trouver ou en créer une inline, ainsi qu'une `quantity` facultative.

Un `plan` inline utilise la même entrée « trouver ou créer » que [Create Payment](https://docs.whop.com/fr/api-reference/payments/create-payment.md), par exemple `{ "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }`. Il nécessite `plan:create`, et un `product` inline nécessite également la permission produit, `access_pass:create` ou `access_pass:update`.

La création et la mise à jour refusent les éléments qui enfreignent ces règles :

* Chaque élément est une variante à achat immédiat de votre compte. Une variante n'apparaît qu'une fois : utilisez `quantity` pour plusieurs unités.
* Aucune variante n'est archivée, et l'émission ou l'envoi d'un brouillon le vérifie à nouveau : désarchivez la variante ou choisissez-en une autre.
* `quantity` est comprise entre 1 et 999 999, et supérieure à 1 uniquement pour une variante qui autorise plusieurs quantités. Ce n'est pas le cas des variantes récurrentes : la quantité d'un élément récurrent est donc 1.
* Une variante récurrente doit appartenir à un produit.
* Tous les éléments utilisent la même devise.
* Dans une facture comportant plusieurs éléments, chaque élément associé à un produit doit être un produit standard (le type de produit standard), et non une app. Les éléments récurrents partagent une même période de facturation, une même durée d'essai gratuit et un même `split_pay_required_payments`, et tous les éléments nécessitent des paramètres de paiement, de taxe et d'accès compatibles. Les variantes avec des champs personnalisés ou un mot de passe ne peuvent pas être combinées. Les éléments sans produit, comme des frais personnalisés, peuvent côtoyer les autres.

Chaque ligne de la réponse possède un `label`, qui correspond au titre du produit, ou au titre de la variante pour une variante sans produit. L'e-mail, le PDF et le checkout l'affichent.

Le brouillon conserve le prix de chaque variante au moment où vous avez enregistré ses éléments : une modification ultérieure du prix de la variante ne change donc pas la facture. Un élément ponctuel est facturé à son prix. À partir de la version d'API `2026-11-11`, la création ou le remplacement d'un élément récurrent inclut son `initial_price` plus son `renewal_price` dans la première facture. Les épinglages de versions antérieures utilisent uniquement le prix de renouvellement. Les modifications qui omettent `items` conservent les prix enregistrés.

### Définir le client et les informations de facturation

| Champ | Rôle |
| - | - |
| `member_id` | Le client, un membre existant du compte, préfixé `mber_`. |
| `email_address`, `customer_name` | Le client identifié par e-mail, à la place de `member_id`. Whop utilise le membre du compte ayant cet e-mail, puis un utilisateur Whop ayant cet e-mail, et crée un utilisateur si aucun n'existe. `customer_name` nomme le nouvel utilisateur. |
| `billing_address` | Une nouvelle adresse de facturation pour le client, avec `line1`, `city`, `postal_code` et un `country` au format ISO 3166-1 alpha-2, ainsi que `name`, `line2`, `state` et `phone` facultatifs. |
| `mailing_address_id` | L'une des adresses enregistrées du client à la place, préfixée `ma_`. |
| `payment_method_id` | Un moyen de paiement enregistré du client, préfixé `payt_`. Whop le débite lorsque vous émettez la facture. Consultez [Débiter un moyen de paiement enregistré](#charge-a-saved-payment-method). |
| `due_at` | La date d'échéance du paiement, sous forme d'horodatage ISO 8601. Elle détermine `overdue`, les dates de relance et la date d'échéance affichée par l'e-mail, le PDF et le checkout. |
| `buyer_fee_percentage` | Des frais payés par l'acheteur, en pourcentage du sous-total de 0 à 100 avec au plus deux décimales. La réponse renvoie le pourcentage dans `buyer_fee_percentage` et les frais dans `buyer_fee_amount`. |
| `recipient_emails` | Jusqu'à 50 adresses qui reçoivent l'e-mail de facture, distinctes du client facturé. Par défaut, l'e-mail du client lors de la création du brouillon. Une mise à jour qui l'omet conserve la liste enregistrée, même si le client change. L'enregistrer n'envoie aucun e-mail. Consultez [Qui reçoit l'e-mail](#who-gets-the-email). |
| `metadata` | Jusqu'à 50 paires clé-valeur de type chaîne qui vous appartiennent. Whop les copie sur l'adhésion qu'il crée lorsque vous émettez la facture, ainsi que sur le débit automatique. |

Envoyez `member_id` ou `email_address`, et `billing_address` ou `mailing_address_id`, jamais les deux d'une même paire. Une adresse de facturation nécessite un client. Un client est facultatif sur un brouillon et obligatoire pour l'émettre.

Whop calcule la taxe lorsque vous émettez la facture, en utilisant l'adresse de facturation pour localiser le client. Lorsqu'une taxe s'applique et que Whop ne peut pas déterminer où se trouve le client, l'émission est refusée : ajoutez donc une adresse de facturation dès que vous collectez des taxes.

### Modifier un brouillon

[Update Invoice](https://docs.whop.com/fr/api-reference/invoices/update-invoice.md) modifie un brouillon avec `PATCH /invoices/{id}`. N'envoyez que les champs que vous modifiez.

```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` remplace toute la liste et lit le prix actuel de chaque variante. Omettez-le pour conserver les éléments et les prix enregistrés.
* Changer `member_id` supprime l'adresse de facturation et le moyen de paiement enregistrés, sauf si vous en envoyez de nouveaux. Cela conserve `recipient_emails` : envoyez donc aussi une nouvelle liste, sinon le client précédent recevra toujours l'e-mail de facture.
* `email_address` et `customer_name` ne sont pas acceptés. Envoyez un autre `member_id` pour facturer quelqu'un d'autre.
* Un brouillon avec un [envoi planifié](#schedule-a-send) n'accepte qu'une modification de `recipient_emails` tant que vous n'annulez pas l'envoi.
* Une fois la facture émise, la seule modification possible est `recipient_emails`, envoyé seul, et uniquement tant que la facture est `open` ou `uncollectible`. Toute autre modification est refusée avec une erreur `400`.

## Choisir comment le client paie

Il existe deux façons d'être payé pour une facture émise. Choisissez-en une avant de l'émettre, car le moyen de paiement enregistré se définit sur le brouillon.

| | Débiter un moyen de paiement enregistré | Le client paie via le checkout |
| - | - | - |
| **Client présent** | Non. Whop débite le moyen de paiement hors session. | Oui, sur le checkout hébergé de Whop |
| **Ce dont vous avez besoin** | `payment_method_id` sur le brouillon | Le `checkout_link` de la facture |
| **3D Secure** | Le débit ne peut pas compléter une authentification | Le client la complète |
| **Vos règles de paiement** | `block` et `allow` s'appliquent | Les quatre actions s'appliquent |

Une facture émise reçoit un `checkout_link` même si elle comporte un moyen de paiement enregistré. Si le débit automatique échoue, le client peut toujours payer via le checkout.

### Débiter un moyen de paiement enregistré

Placez un moyen de paiement enregistré sur le brouillon avec `payment_method_id`. Il doit s'agir de l'un des moyens enregistrés du client. [Enregistrer des moyens de paiement](https://docs.whop.com/fr/developer/guides/save-payment-methods.md) montre comment un client en enregistre un, et [List payment methods](https://docs.whop.com/fr/api-reference/legacy/payment-methods/list-payment-methods.md) permet de trouver ceux d'un membre.

Lorsque vous émettez ou envoyez la facture et que son total est supérieur à zéro, Whop :

1. Effectue les mêmes vérifications que [Create Payment](https://docs.whop.com/fr/api-reference/payments/create-payment.md) sur un moyen de paiement enregistré.
2. Réserve le stock pour les quantités facturées et prépare les frais du paiement.
3. Renvoie la facture en tant que `open` et débite le moyen de paiement hors session. Le débit a lieu au `charge_at` que vous transmettez à Issue Invoice ou Send Invoice, sinon à `due_at` si cette date n'est pas encore passée, sinon immédiatement. `scheduled_charge_at` indique un débit encore à venir.

La réponse ne vous indique pas si le débit a réussi. Traitez la commande à partir du [webhook `payment.succeeded`](#webhooks) pour l'ID `pay_` de la facture. Une facture payée finalise l'adhésion, et vos `metadata` figurent sur le débit et sur l'adhésion. [Règles de paiement sur les paiements de factures](#payment-rules-on-invoice-payments) explique comment vos règles de paiement filtrent le débit.

### Si le débit automatique est refusé

Un débit refusé laisse la facture `open` et restitue le stock réservé. [Récupérez la facture en tant que paiement](https://docs.whop.com/fr/api-reference/payments/retrieve-payment.md) et lisez `failure_message` pour savoir pourquoi la dernière tentative a échoué.

Lorsque le débit est refusé ou nécessite une action du client, Whop envoie par e-mail le lien de paiement de la facture à ses [destinataires](#who-gets-the-email), afin que le client puisse payer via le checkout à la place. C'est le seul e-mail que Whop envoie pour une facture que vous émettez sans l'envoyer. Il nécessite un `checkout_link` et au moins une entrée dans `recipient_emails`, et il n'est pas comptabilisé dans la [limite d'envoi](#send-limit).

> [!WARNING]
>
> Un débit hors session ne peut pas présenter d'authentification 3D Secure au client. Si sa banque en exige une, le débit automatique n'aboutit pas, et la facture reste impayée jusqu'à ce que le client s'authentifie ou paie autrement.

## Émettre la facture

[Issue Invoice](https://docs.whop.com/fr/api-reference/invoices/issue-invoice.md) transforme un brouillon en facture ouverte. Whop vérifie à nouveau la facture, calcule la taxe finale, et définit `status` sur `open` et `totals_status` sur `final`. Lorsque la facture comporte un moyen de paiement enregistré et un total supérieur à zéro, Whop le débite ensuite, comme décrit dans [Débiter un moyen de paiement enregistré](#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"
```

* **La taxe devient définitive.** `tax_amount` vaut `null` sur un brouillon et est défini une fois la facture émise. `total` et `amount_due` l'incluent.
* **Whop crée l'adhésion du client** lorsque la facture porte sur un produit. Elle reste à l'état de brouillon, sans accès, jusqu'au paiement de la facture. Une facture dont aucun élément n'a de produit ne reçoit pas d'adhésion.
* **`payment.created` est déclenché une seule fois** pour l'ID `pay_` de la facture.
* **Émettre à nouveau est sans risque.** Émettre une facture déjà `open` relance les mêmes vérifications et, si elles réussissent, la renvoie inchangée : ses totaux restent les mêmes et rien n'est débité à nouveau.
* **L'émission n'envoie pas la facture par e-mail,** hormis le [lien de paiement après un débit refusé](#if-the-automatic-charge-is-declined). Pour envoyer la facture par e-mail, [envoyez-la](#send-schedule-and-remind) plutôt, ou transmettez vous-même le lien de checkout.

Une émission refusée ne modifie rien et ne débite rien. Corrigez la cause et émettez à nouveau la facture. [Erreurs d'émission](#issue-errors) liste les raisons possibles.

### Obtenir le lien de checkout

Une facture émise et `open` porte un `checkout_link`, une valeur signée de la forme `pay_xxxxxxxxxxxxx.<signature>`. Il ouvre la facture sur le checkout hébergé de Whop à son prix fixe.

**1. Lire le lien depuis la facture émise**

`checkout_link` vaut `null` sauf si la facture est `open` : les brouillons et les factures payées, annulées ou irrécouvrables n'en ont donc pas. Il vaut aussi `null` pour une facture adressée à un acheteur professionnel, pour une facture dont l'adhésion a été annulée, et lorsque vos identifiants n'ont pas `payment:charge`. Un acheteur professionnel est un client qui est un autre compte Whop plutôt qu'une personne.

**2. Construire l'URL du checkout hébergé**

Coupez le lien à son premier `.` : l'ID `pay_` de la facture se trouve avant, et le jeton aprè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. L'envoyer au client**

[Envoyez la facture](#send-schedule-and-remind) pour que Whop envoie le lien par e-mail, ou placez l'URL dans votre propre e-mail ou page de facture. Seul le client de la facture peut payer via ce lien. Toute autre personne est refusée et invitée à se connecter en tant que client de la facture. Le lien cesse de fonctionner une fois la facture payée, annulée ou marquée comme irrécouvrable.

**4. Traiter la commande depuis le webhook**

Écoutez `payment.succeeded` pour l'ID `pay_` de la facture, comme pour le débit automatique. [Webhooks](#webhooks) présente un handler.

Le checkout affiche le numéro et la date d'échéance de la facture à côté de ses éléments, et la date d'échéance passe au rouge une fois dépassée. Le client paie les éléments et le total de la facture et ne peut pas ajouter de code promo.

## Envoyer, planifier et relancer

[Send Invoice](https://docs.whop.com/fr/api-reference/invoices/send-invoice.md) envoie une facture par e-mail avec `POST /invoices/{id}/send`. L'envoi d'un brouillon l'émet d'abord, comme Issue Invoice. L'envoi d'une facture `open` la renvoie par e-mail.

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

L'e-mail affiche le nom et le logo de votre compte, le numéro de facture, le total, la date d'échéance, chaque élément et un bouton qui ouvre le checkout de la facture. Whop n'envoie par e-mail qu'une facture que le client peut payer depuis l'e-mail. Une facture `open` doit avoir un `checkout_link` pour être envoyée, et un brouillon nécessite un client qui n'est pas un acheteur professionnel. Un brouillon adressé à un acheteur professionnel peut tout de même être envoyé s'il comporte un moyen de paiement enregistré, car celui-ci est débité à la place.

### Qui reçoit l'e-mail

Chaque envoi adresse un e-mail distinct à chaque adresse, une seule fois, afin que les destinataires ne voient jamais les adresses des autres. Les adresses sont :

* L'e-mail du compte Whop du client, que le PDF de la facture imprime sous **Bill to**.
* Chaque entrée de `recipient_emails`.

Whop enregistre `recipient_emails` en minuscules et dédoublonne la liste : une adresse présente aux deux endroits reçoit donc un seul e-mail.

Un `recipient_emails` vide signifie que Whop n'envoie d'e-mail à personne, client compris. Utilisez-le pour empêcher Whop d'envoyer une facture par e-mail :

* Send Invoice refuse la facture, sauf si elle débite un moyen de paiement enregistré à la place.
* Aucun [lien de paiement](#if-the-automatic-charge-is-declined) n'est envoyé après un débit refusé.
* Aucune relance n'est envoyée. Vider `recipient_emails` sur une facture `open` arrête ses relances restantes.

### Quand Whop débite au lieu d'envoyer un e-mail

Un brouillon avec un `payment_method_id` et un total supérieur à zéro est débité au lieu d'être envoyé par e-mail, comme lors de son émission. [Si le débit automatique est refusé](#if-the-automatic-charge-is-declined) explique ce qui se passe en cas d'échec du débit. Un tel brouillon peut être envoyé avec un `recipient_emails` vide, puisque personne n'a besoin de l'e-mail.

### Limite d'envoi

Chaque facture peut être envoyée par e-mail trois fois en 24 heures, y compris l'envoi qui l'a émise. Un quatrième envoi dans cet intervalle est refusé avec une erreur `429` dont le `error.code` est `invoice_send_limit_reached`. Les relances, le [lien de paiement après un débit refusé](#if-the-automatic-charge-is-declined) et un envoi qui débite au lieu d'envoyer un e-mail ne sont pas comptabilisés dans la limite.

### Planifier un envoi

Pour envoyer un brouillon plus tard, transmettez `send_at`. Le brouillon reste un brouillon et affiche l'heure dans `scheduled_send_at`. À ce moment-là, Whop l'envoie comme si vous aviez appelé Send Invoice.

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

* **Seul un brouillon peut être planifié,** et `send_at` doit être dans le futur. Whop vérifie les destinataires et le lien de paiement au moment de la planification, comme pour un envoi immédiat.
* **Envoyez à nouveau avec un nouveau `send_at`** pour déplacer l'heure.
* **La modification est verrouillée** jusqu'à ce que l'envoi ait lieu ou que vous l'annuliez. Une mise à jour qui ne modifie que `recipient_emails` fonctionne toujours, mais elle ne peut pas retirer le dernier destinataire d'un brouillon qui ne sera pas débité.
* **[Cancel Scheduled Send](https://docs.whop.com/fr/api-reference/invoices/cancel-scheduled-send.md)** avec `POST /invoices/{id}/unschedule`. `scheduled_send_at` repasse à `null`, et le brouillon peut de nouveau être modifié. Annuler une facture sans envoi planifié la renvoie inchangée.
* **Annuler (void) un brouillon planifié** arrête son envoi planifié.

```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 vérifie les envois arrivés à échéance chaque minute : un envoi planifié part donc environ une minute après `send_at`. S'il est refusé, par exemple parce qu'une variante a été supprimée depuis la planification, la facture reste un brouillon, `scheduled_send_at` repasse à `null`, et l'API ne renvoie pas la raison. Tout autre échec est retenté environ toutes les 10 minutes, jusqu'à 12 tentatives au total. Tant qu'une tentative n'a pas réussi ou que Whop n'a pas cessé de réessayer, `scheduled_send_at` affiche l'heure de la prochaine tentative plutôt que `null`. Lisez la facture après `send_at` pour confirmer qu'elle est `open`.

### Relances

Lorsque Send Invoice envoie par e-mail une facture qui a une `due_at`, Whop planifie aussi des relances 1, 3, 7, 14, 30 et 60 jours après `due_at`, en ignorant celles dont la date est déjà passée. Chaque relance est envoyée aux mêmes adresses que la facture et indique depuis combien de jours la facture est en retard.

Les relances ne sont envoyées que tant que la facture est `open` : elles s'arrêtent donc une fois la facture payée, annulée ou marquée comme irrécouvrable. Une relance qui arrive à échéance pendant qu'un paiement est en cours attend la fin du paiement. Une facture que vous émettez sans l'envoyer, ou qui est débitée au lieu d'être envoyée par e-mail, ne reçoit aucune relance.

### Historique des e-mails

[List Invoice Sends](https://docs.whop.com/fr/api-reference/invoices/list-invoice-sends.md) renvoie les lots d'e-mails enregistrés avec `GET /invoices/{id}/sends`, du plus récent au plus ancien. Il inclut les e-mails initiaux et répétés, les e-mails planifiés, les relances et les suivis de paiement après un débit échoué sur un moyen de paiement enregistré. Utilisez la première entrée pour l'envoi enregistré le plus récent, et `page_info.end_cursor` comme `after` pour lire les entrées plus anciennes. Les lots manuels utilisent `send` lorsque la facture n'a pas d'historique d'e-mails terminé antérieur, et `resend` sinon. Le type est déterminé au moment où le lot terminé est enregistré : les requêtes mises en file ensemble sont donc classées dans l'ordre de leur achèvement. Les e-mails antérieurs non enregistrés restent inconnus.

Chaque entrée contient `kind`, `sent_at`, `recipient_count`, `recipients` et `actor`. La lecture de l'historique nécessite `payment:basic:read`. Les adresses nécessitent aussi `member:email:read`. Sans cette permission, `recipients` est vide. L'expéditeur nécessite aussi `company:authorized_user:read`. Sinon, `actor` est null. Les envois automatiques et les clés API de compte ont également un `actor` null.

Le worker ajoute une entrée après avoir soumis l'ensemble du lot pour livraison. Pour un lot partiel, il n'ajoute une entrée que si une nouvelle tentative complète le lot. L'entrée conserve la liste de destinataires d'origine. Un lot enregistré ne confirme pas la livraison en boîte de réception. Le service d'envoi peut supprimer des messages si la facture ou les destinataires changent avant la livraison. L'historique exclut les e-mails envoyés avant l'introduction de cette fonctionnalité. Émettre une facture sans l'envoyer par e-mail n'ajoute aucune entrée à l'historique.

## Télécharger un PDF

[Generate Invoice PDF](https://docs.whop.com/fr/api-reference/invoices/generate-invoice-pdf.md) génère la facture au format PDF et renvoie un lien temporaire vers celle-ci. Il nécessite `payment:basic:read` et fonctionne quel que soit le statut.

```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 réponse contient `url` et `expires_at`. Le lien fonctionne pendant 15 minutes, et toute personne qui le détient peut télécharger le fichier. Générez-en un nouveau lorsqu'il expire.

Le PDF met votre entreprise en avant : le nom de votre compte figure en tête de page, et le pied de page indique que Whop Inc émet la facture en votre nom et pour votre compte. Il affiche le numéro de facture, sa date et sa date d'échéance, ainsi que les informations **Bill to**. Chaque élément affiche sa quantité, son prix unitaire et son montant, suivis du sous-total, des frais de service, de la taxe et du montant dû. Une facture comportant un élément récurrent indique aussi le montant du renouvellement et sa fréquence. Le PDF d'un brouillon affiche ses totaux estimés, avec une taxe à zéro jusqu'à l'émission.

Certains contenus dépendent des permissions de vos identifiants :

| Permission | Ajoute au PDF |
| - | - |
| `member:basic:read` | Le nom du client sous **Bill to**. Sans cette permission, le PDF n'affiche que le nom enregistré sur l'adresse de facturation. |
| `member:email:read` | L'e-mail du client sous **Bill to** |
| `payment:charge` | Un lien **Pay now** qui ouvre le checkout de la facture, sur une facture qui possède un `checkout_link` |

## Facturer un abonnement

Placez une variante récurrente sur une facture pour démarrer un abonnement lorsque le client la paie. Whop le renouvelle ensuite une fois par période de facturation.

1. **La facture couvre la première période et les éventuels frais initiaux.** Un élément récurrent doit appartenir à un produit et a une quantité de 1. À partir de la version d'API `2026-11-11`, sa première facture porte sur `initial_price` plus `renewal_price`. Le paiement démarre immédiatement la première période de facturation payante, sauf si la variante comporte un essai gratuit. L'abonnement [démarre alors par l'essai](#start-with-a-free-trial). Dans le tableau de bord, un élément récurrent personnalisé dispose d'un champ facultatif **Upfront fee**. Le `initial_price` de la ligne indique cette part ponctuelle de `unit_amount`, et la page de facture, l'e-mail et le PDF la listent sur une ligne **Upfront fee** distincte.
2. **Le paiement de la facture démarre l'abonnement,** que Whop débite le moyen de paiement enregistré à l'émission ou que le client paie via le `checkout_link`. La première période commence au paiement. Le checkout ouvert depuis le lien indique le montant du renouvellement, frais acheteur de la facture compris, et sa fréquence.
3. **Chaque renouvellement est encaissé selon la méthode choisie lors de l'émission ou de l'envoi de la facture.** Il ne facture que les éléments récurrents, avec les frais acheteur de la facture, au prix de renouvellement de chaque variante au moment de l'émission. Celui-ci peut différer du prix enregistré sur le brouillon si le prix de la variante a changé après l'enregistrement des éléments. Les éléments ponctuels ne sont facturés qu'une fois.

Transmettez `collection_method` à [Issue Invoice](https://docs.whop.com/fr/api-reference/invoices/issue-invoice.md) ou [Send Invoice](https://docs.whop.com/fr/api-reference/invoices/send-invoice.md) pour choisir comment les renouvellements sont encaissés. Un envoi planifié applique le `collection_method` avec lequel vous l'avez planifié, que le brouillon affiche dans `scheduled_collection_method`.

| `collection_method` | Chaque renouvellement |
| - | - |
| `charge_automatically` | Débite le moyen de paiement qui a payé la facture : le `payment_method_id` du brouillon, ou celui avec lequel le client paie via le lien de facture. Valeur par défaut. |
| `send_invoice` | Émet une nouvelle facture numérotée arrivant à échéance à la date de renouvellement, et l'envoie par e-mail avec son lien de paiement et ses relances aux `recipient_emails` de la dernière facture |

`send_invoice` nécessite au moins une adresse dans `recipient_emails` et n'est pas disponible pour les factures adressées à une entreprise. Tant qu'il s'applique, le dernier destinataire de la facture ne peut pas être retiré. Une facture sans élément récurrent refuse `collection_method`. Payer la première facture par carte conserve `send_invoice`.

Chaque renouvellement est un paiement distinct, avec son propre ID `pay_` et ses propres webhooks `payment.*`. Un renouvellement `charge_automatically` n'est pas une facture numérotée : il n'apparaît donc pas dans List Invoices. Un renouvellement `send_invoice` est une facture numérotée dans List Invoices, et Whop ne la débite pas automatiquement. L'abonnement reste `past_due` jusqu'à ce que le client paie via le `checkout_link` de la facture. Le client conserve son accès entre-temps. [Annulez l'adhésion](https://docs.whop.com/fr/api-reference/memberships/cancel-membership.md) pour arrêter les renouvellements. Une fois l'adhésion annulée, le `checkout_link` d'une facture de renouvellement ouverte cesse de fonctionner.

Pour trouver l'abonnement, [récupérez la facture en tant que paiement](https://docs.whop.com/fr/api-reference/payments/retrieve-payment.md) et lisez son `membership_id`, ce qui nécessite `member:basic:read`.

### Commencer par un essai gratuit

Une facture respecte le `trial_period_days` d'une variante récurrente, comme le fait le checkout. La première facture ne porte que sur le `initial_price` de la variante. Son paiement démarre l'essai, et le premier renouvellement facture `renewal_price` à la fin de l'essai. Les factures créées avant le 16/11/2026 à 17:00 UTC facturent la première période et ignorent l'essai.

* Un client qui avait déjà un abonnement à la variante ne bénéficie pas d'essai. Sa première facture porte sur `initial_price` plus `renewal_price`. Les factures de renouvellement ne démarrent jamais d'essai.
* L'essai provient de la variante. Pour un élément récurrent personnalisé, définissez `variant.trial_period_days`. Un `trial_period_days` au niveau de l'élément est refusé.
* Tous les éléments récurrents de la facture doivent avoir la même durée d'essai.
* Lorsque la facture ne débite rien, émettez-la ou envoyez-la avec un `payment_method_id`, ce qui démarre l'essai immédiatement, ou avec `collection_method: "send_invoice"`.
* Dans le tableau de bord, un élément récurrent personnalisé dispose d'un champ **Free trial days**. Le plan de facturation d'un produit affiche son propre essai.

### Arrêter après un nombre défini de paiements

Pour facturer un plan de paiement fixe, par exemple six mensualités, définissez `split_pay_required_payments` sur la variante récurrente, de 2 à 115. La facture constitue le premier paiement, frais initiaux compris. Par exemple, des frais initiaux de 75 $avec trois versements de 40$ facturent 115 $, puis 40 $, puis 40 \$. Whop cesse de renouveler une fois ce nombre de paiements atteint, et l'adhésion reste active. Le client ne peut pas annuler lui-même l'abonnement avant cette échéance, mais vous le pouvez. Laissez ce champ vide pour renouveler jusqu'à l'annulation de l'abonnement.

## Statuts et cycle de vie

| `status` | Signification | Étape suivante possible |
| - | - | - |
| `draft` | Vous pouvez encore la modifier. Les totaux sont estimés et la taxe n'est pas encore calculée. | Vous l'émettez, l'envoyez, la planifiez, l'annulez ou la supprimez |
| `open` | Émise. Les totaux et la taxe sont définitifs, et la facture attend le paiement. | Le client paie, ou vous l'annulez ou la marquez comme irrécouvrable |
| `paid` | Le client a payé. `amount_due` vaut zéro. | Rien |
| `uncollectible` | Vous avez marqué une facture ouverte comme une facture que vous ne pensez pas encaisser. | Vous l'annulez |
| `void` | Annulée. `amount_due` vaut zéro. | Vous la supprimez |

`status` prend ses valeurs parmi celles des paiements : une facture peut donc aussi afficher un état de paiement comme `pending` pendant qu'un paiement est en cours. `totals_status` vous indique si les champs monétaires sont définitifs : `estimated` tant que la facture est un brouillon, `final` après son émission. `overdue` vaut `true` pour une facture `open` ou `uncollectible` dont la `due_at` est dépassée.

### Annuler ou marquer comme irrécouvrable

[Void Invoice](https://docs.whop.com/fr/api-reference/invoices/void-invoice.md) annule une facture `draft`, `open` ou `uncollectible`. Annuler une facture déjà annulée la renvoie inchangée, et une facture payée ne peut pas être annulée.

[Marquez une facture comme irrécouvrable](https://docs.whop.com/fr/api-reference/invoices/mark-invoice-uncollectible.md) pour indiquer que vous ne pensez pas l'encaisser. Seule une facture `open` peut être marquée, et marquer à nouveau une facture irrécouvrable la renvoie inchangée. Une facture irrécouvrable n'a pas de `checkout_link` et ne reçoit aucune relance.

Cet exemple marque une facture `open` comme irrécouvrable, puis l'annule :

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

### Supprimer une facture

[Delete Invoice](https://docs.whop.com/fr/api-reference/invoices/delete-invoice.md) supprime une facture `draft` ou `void` avec `DELETE /invoices/{id}`. La réponse est `{ id, deleted: true }`. Une facture supprimée n'apparaît plus dans List Invoices ni dans List Payments, et son ID renvoie une erreur `404`. Une suppression est irréversible.

Annulez une facture `open` avant de la supprimer. Un brouillon avec un envoi ou un débit planifié nécessite d'abord [Cancel Scheduled Send](https://docs.whop.com/fr/api-reference/invoices/cancel-scheduled-send.md). Un brouillon de facture de renouvellement ne peut pas être supprimé tant qu'il facture un abonnement. Une facture annulée qui a encaissé de l'argent ou qui attend encore un virement bancaire ne peut pas être supprimée, pas plus qu'une facture payée, en attente ou irrécouvrable. Le champ `deletable` d'une facture vaut `true` lorsqu'elle peut être supprimée.

La suppression nécessite `invoice:update` ou `payment:charge`. Le numéro d'un brouillon supprimé n'est pas réutilisé.

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

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

## Lister et récupérer des factures

[List Invoices](https://docs.whop.com/fr/api-reference/invoices/list-invoices.md) renvoie les factures que vos identifiants peuvent lire, de la plus récente à la plus ancienne. Une clé API voit son propre compte, et un jeton utilisateur voit tous les comptes dont l'utilisateur peut lire les paiements. Affinez la liste avec ces paramètres de requête :

| Paramètre | Filtre sur |
| - | - |
| `account_id` | Un compte |
| `status` | Un statut, comme `open`. Une valeur inconnue renvoie une `400`. |
| `overdue` | `true` pour les factures en retard, `false` pour les autres |
| `scheduled` | `true` pour les brouillons planifiés, `false` pour les autres |
| `member_id` | Un client |
| `product_id` | Les factures qui portent sur un produit, préfixé `prod_` |
| `created_after`, `created_before` | Une fenêtre de création, sous forme d'horodatages ISO 8601 |

Un brouillon planifié est un brouillon qui a un `scheduled_send_at`. Une facture `open` n'est jamais planifiée, pas plus qu'un brouillon envoyé à sa date d'échéance.

Triez avec `order` (`created_at`, `due_at` ou `scheduled_send_at`) et `direction` (`asc` ou `desc`). Un tri par `due_at` ou `scheduled_send_at` place en dernier les factures sans cette date. La réponse est `{ data, page_info }`. Tant que `page_info.has_next_page` vaut `true`, transmettez `page_info.end_cursor` comme `after` pour lire la page suivante.

```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/fr/api-reference/invoices/retrieve-invoice.md) lit une facture à partir de son ID `pay_`. [List Payments](https://docs.whop.com/fr/api-reference/payments/list-payments.md) exclut les brouillons.

Pour exporter des factures dans un fichier CSV, appelez [Create Export](https://docs.whop.com/fr/api-reference/exports/create-export.md) avec `resource: "receipt_invoices"`. Cela nécessite `payment:basic:read` et `payment:basic:export`. Les colonnes client n'apparaissent que si vos identifiants disposent aussi de `member:basic:read` ou `member:email:read`.

## Webhooks

Les factures natives envoient des webhooks de paiement pour leur ID `pay_`. Les événements `invoice.*` appartiennent à l'ancienne API de factures, et les factures natives ne les envoient pas.

| Événement | Quand |
| - | - |
| `payment.created` | Vous émettez la facture. Les brouillons n'envoient rien. |
| `payment.succeeded` | La facture est payée. Traitez la commande à partir de cet événement. |

D'autres événements `payment.*`, comme `payment.failed`, peuvent aussi arriver pour l'ID `pay_` de la facture à mesure que ses tentatives de paiement évoluent. Abonnez-vous à ces événements à l'aide du [guide des webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md).

Pour traiter une commande, enregistrez l'`id` de la facture avec la commande lors de la création du brouillon. Le `data` d'un événement `payment.succeeded` est le paiement : `data.id` est donc l'ID `pay_` de la facture. Après avoir [vérifié l'événement](https://docs.whop.com/fr/developer/guides/webhooks.md#verify-and-handle-events), recherchez la commande à partir de cet ID. Dans ce handler, `orders` représente votre propre stockage de commandes :

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

Vérifier `fulfilled` empêche un événement relivré de traiter la commande deux fois. Les renouvellements d'abonnement ont leurs propres ID `pay_` : ils ne correspondent donc pas à une facture.

## Règles de paiement sur les paiements de factures

Vos [règles de paiement](https://docs.whop.com/fr/developer/guides/manage-fraud.md) s'exécutent sur les paiements de factures après le filtrage antifraude propre à Whop, comme sur n'importe quel checkout. Ce qu'elles peuvent faire dépend de la présence ou non du client.

* **Le débit automatique à l'émission a lieu hors session.** Une règle `block` le refuse, et une règle `allow` l'exempte de vos autres règles. Les règles `review` et `enforce_3ds` sont ignorées, car le débit a lieu hors session.
* **Un paiement via le lien de checkout a lieu en session.** Les quatre actions s'appliquent, avec les limites d'éligibilité décrites dans [Gérer la fraude](https://docs.whop.com/fr/developer/guides/manage-fraud.md).

Pour le débit automatique, les conditions de carte lisent le moyen de paiement enregistré et les conditions de facturation lisent l'adresse de facturation de la facture. `customer_email` est l'e-mail du compte Whop du client. Le champ `payment_rule_matches` du paiement liste la règle qui a statué. Une règle ignorée n'est pas listée.

## Les factures dans le tableau de bord

La page **Invoices** liste, crée et envoie des factures natives. Les anciennes factures se trouvent dans son onglet **Legacy invoices**, décrit dans [Envoyer une facture](https://docs.whop.com/fr/payments/send-an-invoice.md).

## Permissions

| Appel | Permission |
| - | - |
| [Créer](https://docs.whop.com/fr/api-reference/invoices/create-invoice.md), [mettre à jour](https://docs.whop.com/fr/api-reference/invoices/update-invoice.md), [émettre](https://docs.whop.com/fr/api-reference/invoices/issue-invoice.md), [envoyer](https://docs.whop.com/fr/api-reference/invoices/send-invoice.md), [annuler un envoi planifié](https://docs.whop.com/fr/api-reference/invoices/cancel-scheduled-send.md), [annuler (void)](https://docs.whop.com/fr/api-reference/invoices/void-invoice.md) ou [marquer comme irrécouvrable](https://docs.whop.com/fr/api-reference/invoices/mark-invoice-uncollectible.md) | `payment:charge` |
| [Lister](https://docs.whop.com/fr/api-reference/invoices/list-invoices.md), [récupérer](https://docs.whop.com/fr/api-reference/invoices/retrieve-invoice.md) ou [générer un PDF](https://docs.whop.com/fr/api-reference/invoices/generate-invoice-pdf.md) | `payment:basic:read` |

Chaque écriture nécessite `payment:charge`, la même permission que [Create Payment](https://docs.whop.com/fr/api-reference/payments/create-payment.md), et chaque lecture nécessite `payment:basic:read`. Les permissions `invoice:*` appartiennent à l'ancienne API de factures, et les factures natives ne les utilisent pas. Une création ou une mise à jour qui envoie un élément `plan` inline nécessite aussi `plan:create`.

Certains champs nécessitent leur propre permission. Sans elle, le champ est renvoyé à `null`, et `recipient_emails` est renvoyé vide.

| Permission | Champs révélés |
| - | - |
| `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 vos identifiants perdent l'une de ces permissions de lecture après un `POST`, le rejouer avec la même `Idempotency-Key` est refusé avec une erreur `403` dont le `error.code` est `invoice_replay_permission_revoked` lorsque la réponse stockée affiche ces champs. Récupérez plutôt la facture avec `GET`. Ajoutez des permissions depuis le [guide des permissions](https://docs.whop.com/fr/developer/guides/permissions.md).

## Erreurs

Les refus sont renvoyés sous la forme `{ error: { type, message, code } }`. Chaque code ci-dessous correspond à une erreur `400`, sauf indication contraire. Un `plan_id`, `member_id`, `mailing_address_id` ou `payment_method_id` inconnu renvoie une `404`, et un horodatage que Whop ne peut pas lire renvoie une `400` avec `invalid_timestamp`.

Ces refus sont des erreurs `400` sans `error.code` : lisez donc `error.message` pour connaître la raison :

* Un champ de premier niveau inconnu.
* Une `quantity` en dehors de la plage 1 à 999 999.
* Une adresse invalide dans `recipient_emails`, ou plus de 50 adresses.
* Une règle multi-éléments non respectée, comme une incohérence de période de facturation.

### Erreurs de création et de mise à jour

| `error.code` | Raison |
| - | - |
| `invoice_item_count_invalid`, `invoice_item_invalid` | `items` ne contient pas de 1 à 50 entrées, ou un élément n'a pas exactement l'un de `plan_id` et `plan`. |
| `invoice_plan_account_mismatch`, `invoice_plan_duplicated`, `invoice_currency_mismatch` | Une variante appartient à un autre compte, apparaît deux fois ou utilise une devise différente des autres. |
| `invoice_quantity_unsupported` | `quantity` est supérieure à 1 pour une variante qui n'autorise pas plusieurs quantités. |
| `invoice_plan_type_unsupported`, `invoice_legacy_plan_unsupported` | La variante n'est pas à achat immédiat, ou appartient à une ancienne facture. |
| `invoice_installment_count_mismatch` | Les éléments récurrents de la facture s'arrêtent après des nombres de paiements différents. |
| `invoice_recurring_plan_product_required` | Une variante récurrente n'a pas de produit. |
| `invoice_plan_unavailable`, `invoice_plan_archived`, `invoice_plan_currency_changed` | Une variante a été supprimée ou archivée, ou une variante enregistrée a changé de devise. Renvoyez `items`. |
| `invoice_customer_ambiguous`, `invoice_address_ambiguous` | Vous avez envoyé à la fois `member_id` et `email_address`, ou à la fois `billing_address` et `mailing_address_id`. |
| `invoice_address_properties_invalid`, `invoice_address_incomplete`, `invoice_address_country_invalid` | `billing_address` contient un champ inconnu, omet un champ obligatoire ou a un `country` qui n'est pas un code valide. |
| `invoice_address_member_required`, `invoice_member_mismatch`, `invoice_address_mismatch`, `invoice_payment_method_mismatch` | L'adresse n'a pas de client, ou le membre, l'adresse ou le moyen de paiement appartient à quelqu'un d'autre. |
| `invoice_payment_method_unsupported` | Le moyen de paiement enregistré ne peut pas payer de factures. |
| `invoice_buyer_fee_invalid`, `invoice_metadata_invalid`, `invoice_recipients_invalid` | `buyer_fee_percentage` est hors limites, une valeur de `metadata` n'est pas une chaîne, ou `recipient_emails` n'est pas un tableau. |
| `invoice_not_editable`, `invoice_recipients_not_editable` | La facture n'est pas un brouillon, ou une modification de `recipient_emails` a visé une facture qui n'est ni un brouillon, ni `open`, ni `uncollectible`. |
| `invoice_scheduled_not_editable`, `invoice_scheduled_recipients_required` | Le brouillon a un envoi planifié. Annulez-le avant de modifier le brouillon ou de retirer le dernier destinataire. |

### Erreurs d'émission

| `error.code` | Raison |
| - | - |
| `invoice_not_issuable` | La facture n'est ni un brouillon ni `open`. |
| `invoice_recipient_required` | La facture n'a pas de client. |
| `invoice_account_verification_required` | Votre compte n'a pas terminé la vérification. |
| `invoice_account_suspended` | Votre compte est suspendu. |
| `invoice_items_required`, `invoice_items_changed`, `invoice_plan_unavailable`, `invoice_plan_archived` | La facture n'a aucun élément, ou une variante a été supprimée, archivée, ou a changé de compte, de devise ou de produit. Mettez à jour les éléments. |
| `invoice_tax_address_required` | Une taxe s'applique et Whop ne peut pas déterminer où se trouve le client. Ajoutez une adresse de facturation. |
| `invoice_tax_unresolved` | La taxe n'a pas pu être calculée. |
| `invoice_changed_during_issuance`, `invoice_changed_during_calculation` | La facture a changé pendant le calcul de la taxe. Émettez-la à nouveau. |
| `invoice_payment_method_unavailable`, `invoice_payment_method_unsupported`, `payment_method_unavailable` | Le moyen de paiement enregistré a été retiré du client, ne peut pas payer de factures ou ne fonctionne plus. |
| `out_of_stock` | Uniquement lors du débit d'un moyen de paiement enregistré : une variante n'a pas assez de stock pour la quantité facturée. |
| `payment_fees_unavailable` | Uniquement lors du débit d'un moyen de paiement enregistré : les frais du paiement n'ont pas pu être préparés. |

### Erreurs d'envoi et de planification

L'envoi d'un brouillon l'émet : un envoi peut donc aussi être refusé pour n'importe quelle raison figurant dans [Erreurs d'émission](#issue-errors).

| `error.code` | Raison |
| - | - |
| `invoice_not_sendable` | La facture n'est ni un brouillon ni `open`. |
| `invoice_send_recipients_required` | La facture n'a pas de `recipient_emails` et rien à débiter. |
| `invoice_payment_link_unavailable` | Il n'y a aucun lien de paiement à envoyer : une facture `open` n'a pas de `checkout_link`, ou un brouillon sans moyen de paiement enregistré est adressé à un acheteur professionnel. |
| `invoice_send_limit_reached` | Une erreur `429` : la facture a déjà été envoyée par e-mail trois fois au cours des dernières 24 heures. |
| `invoice_not_schedulable` | Seul un brouillon peut être planifié. |
| `invoice_scheduled_send_in_past` | `send_at` n'est pas dans le futur. |

### Autres erreurs

| `error.code` | Raison |
| - | - |
| `invoice_not_uncollectible` | Seule une facture `open` peut être marquée comme irrécouvrable. |
| `invoice_replay_permission_revoked` | Une erreur `403` : un rejeu idempotent afficherait des champs que vos identifiants ne peuvent plus lire. |

L'annulation d'une facture payée renvoie une erreur `400` sans code.

## Prochaines étapes

> [card] [Référence de l'API Invoices](https://docs.whop.com/fr/api-reference/invoices/create-invoice.md)
>
> Chaque endpoint, paramètre et champ de réponse des factures.

> [card] [Enregistrer des moyens de paiement](https://docs.whop.com/fr/developer/guides/save-payment-methods.md)
>
> Collectez le moyen de paiement enregistré qu'une facture débite à l'émission.

> [card] [Gérer la fraude](https://docs.whop.com/fr/developer/guides/manage-fraud.md)
>
> Rédigez les règles de paiement qui filtrent les paiements de factures.

> [card] [Écouter les webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md)
>
> Suivez `payment.created` et `payment.succeeded` pour vos factures.


## Related topics

- [API Factures](https://docs.whop.com/fr/api-reference/invoices/invoice.md)
- [Facture (ancienne version)](https://docs.whop.com/fr/api-reference/legacy/invoices/legacy-invoice.md)
- [Migrer depuis les factures legacy](https://docs.whop.com/fr/developer/guides/migrate-from-legacy-invoices.md)
