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

# Inscrire des sous-comptes

> Créez des sous-comptes pour les entreprises ou les personnes de votre plateforme, et envoyez-leur un lien pour finaliser leur onboarding.

Pour inscrire un sous-compte sur votre plateforme, créez pour lui un objet Account sous le compte de votre plateforme. Ce compte peut alors accepter des débits directs, recevoir des transferts et utiliser les parcours de versement de Whop.

## Exemple

Créez un compte pour le sous-compte :

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({
	token: "Account API Key",
});

const account = await client.accounts.create({
	email: "merchant@example.com",
	title: "Acme Merchant Store",
	external_id: "user_12345",
	metadata: {
		seller_tier: "gold",
	},
});

console.log(account.id);
```

```python Python theme={null}
from whop_sdk import Whop

client = Whop(
    token="Account API Key",
)

account = client.accounts.create(
    email="merchant@example.com",
    title="Acme Merchant Store",
    external_id="user_12345",
    metadata={
        "seller_tier": "gold",
    },
)

print(account.id)
```

```rust Rust theme={null}
use whop_sdk::prelude::*;

let config = ClientConfig {
    token: Some("Account API Key".to_string()),
    ..Default::default()
};
let client = Whop::new(config).expect("Failed to build client");

let account = client
    .accounts
    .create(
        &CreateAccountsRequest {
            email: Some("merchant@example.com".to_string()),
            title: "Acme Merchant Store".to_string(),
            external_id: Some("user_12345".to_string()),
            metadata: Some(HashMap::from([
                ("seller_tier".to_string(), json!("gold")),
            ])),
            ..Default::default()
        },
        None,
    )
    .await?;

println!("{}", account.id);
```

```go Go theme={null}
import (
    "context"
    "fmt"
    "log"

    whopsdk "github.com/whopio/whopsdk-go/v2"
    "github.com/whopio/whopsdk-go/v2/client"
    "github.com/whopio/whopsdk-go/v2/option"
)

client := client.NewWhop(option.WithToken("Account API Key"))

account, err := client.Accounts.Create(context.TODO(), &whopsdk.CreateAccountsRequest{
    Email: whopsdk.String("merchant@example.com"),
    Title: "Acme Merchant Store",
    ExternalID: whopsdk.String("user_12345"),
    Metadata: map[string]any{
        "seller_tier": "gold",
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(account.ID)
```

Dans cet exemple :

* `email` est l'adresse e-mail du sous-compte. Whop l'utilise pour identifier le sous-compte et lui envoyer les notifications importantes.
* La clé API Account détermine le compte de plateforme propriétaire du sous-compte.
* `title` est le nom d'affichage obligatoire du sous-compte.
* `external_id` est l'ID propre à votre plateforme pour ce sous-compte, par exemple l'ID de votre boutique. Chaque ID correspond à un seul sous-compte, et vous pouvez ensuite retrouver le compte grâce à lui.
* `metadata` contient des paires clé-valeur personnalisées, comme `seller_tier`, une classification ou un niveau pour le sous-compte (par exemple "bronze", "silver" ou "gold").
* La réponse inclut un `account.id` que vous pouvez utiliser pour faire référence à ce sous-compte dans les appels API suivants

> [!TIP]
>
> L'adresse e-mail doit appartenir au sous-compte (entreprise ou
> particulier) qui gérera le compte. Cette personne recevra les notifications
> de configuration du compte et de paiement.

## Retrouver un sous-compte à partir de votre ID

Listez vos sous-comptes avec `external_id` pour obtenir le compte correspondant à l'un de vos enregistrements. Terminez la valeur par `%` pour obtenir tous les comptes dont l'ID commence par un espace de noms de votre choix, comme `shopline:%`. La correspondance est sensible à la casse, `_` est interprété littéralement et `%` ne fonctionne qu'en fin de valeur : les ID que vous créez ne peuvent donc pas le contenir.

```typescript TypeScript theme={null}
const accounts = await client.accounts.list({ external_id: "user_12345" });

console.log(accounts.data[0]?.id);
```

Update Account définit ou efface `external_id` sur un sous-compte existant. Seule votre plateforme peut le modifier. Le sous-compte peut le lire mais pas le modifier.

## Réutiliser une adresse e-mail

Plusieurs sous-comptes peuvent partager une même adresse e-mail, à condition que chacun ait un `external_id` distinct. La création d'un compte est idempotente sur la paire e-mail et `external_id` :

* **Nouvel `external_id`** : Whop crée un nouveau sous-compte, même si l'e-mail est déjà utilisé.
* **Même e-mail et même `external_id`** : Whop renvoie le sous-compte existant au lieu de créer un doublon, les nouvelles tentatives sont donc sans risque.
* **`external_id` déjà utilisé avec un autre e-mail** : Whop renvoie une erreur `409` au lieu de créer un second compte avec cet ID. Pour transférer l'ID vers le nouveau compte dans la même requête, consultez [Remplacer le compte associé à un ID](#replace-the-account-behind-an-id).
* **Pas d'`external_id`** : Whop renvoie le sous-compte existant sans `external_id` pour cet e-mail, s'il en existe un.

Les comptes qui partagent un e-mail sont gérés par le même utilisateur Whop, la personne qui reçoit les messages de cette boîte.

> [!NOTE]
>
> Les versions précédentes de ce guide plaçaient `external_id` dans `metadata`. Whop l'y accepte toujours, quelle que soit la version de l'API,
> définit `external_id` à partir de cette valeur et la renvoie dans `metadata`. Les mêmes règles que pour le champ de premier niveau s'appliquent,
> y compris l'erreur `409` lorsqu'un autre sous-compte le possède déjà : envoyez donc `reassign_external_id: true` pour en réutiliser un.
> Modifier `metadata.external_id` par la suite ne modifie pas `external_id`. Pour le modifier, utilisez Update Account. Les nouvelles
> intégrations doivent envoyer le champ de premier niveau.

## Remplacer le compte associé à un ID

Lorsque vous réattribuez un compte de votre côté, par exemple une boutique qui change de propriétaire, créez le nouveau sous-compte avec le même `external_id` et `reassign_external_id: true`. Whop transfère l'ID vers le nouveau sous-compte dans la même requête au lieu de renvoyer une erreur `409`.

```typescript TypeScript theme={null}
const account = await client.accounts.create({
	email: "new-owner@example.com",
	external_id: "user_12345",
	reassign_external_id: true,
});
```

* Le sous-compte qui possédait l'ID n'est ni supprimé ni modifié d'une autre façon. Il reste actif avec `external_id` défini sur `null`, conserve ses `metadata` et son solde, et envoie un webhook `account.updated`. Supprimez-le vous-même si vous n'en avez plus besoin.
* Si la création échoue, l'ID reste là où il était.
* La requête nécessite la permission `company:update` sur le compte de votre plateforme en plus de `company:create_child`, car elle modifie un sous-compte existant.
* Une requête avec le même e-mail et le même `external_id` qu'un sous-compte existant renvoie ce sous-compte, même si elle définit l'indicateur.
* L'ID ne peut être transféré qu'entre vos propres sous-comptes.

Pour transférer un ID entre deux sous-comptes existants, appelez Update Account deux fois : effacez `external_id` sur l'ancien, puis définissez-le sur l'autre. Update Account ne dispose pas de `reassign_external_id`, et définir l'ID avant de l'effacer renvoie une erreur `409`.

## Finaliser l'onboarding

Si le destinataire n'a pas encore de compte Whop, envoyez-lui un lien d'onboarding après avoir créé le compte. Il effectue la vérification Know Your Customer (KYC) via ce lien, après quoi le compte peut recevoir des transferts et utiliser les autres parcours de versement.

```typescript TypeScript theme={null}
const accountLink = await client.accountLinks.create({
	account_id: account.id,
	refresh_url: "https://yourapp.com/onboarding/refresh",
	return_url: "https://yourapp.com/onboarding/complete",
	use_case: "account_onboarding",
});

console.log(accountLink.url);
```

```python Python theme={null}
account_link = client.account_links.create(
    account_id=account.id,
    refresh_url="https://yourapp.com/onboarding/refresh",
    return_url="https://yourapp.com/onboarding/complete",
    use_case="account_onboarding",
)

print(account_link.url)
```

```rust Rust theme={null}
let account_link = client
    .account_links
    .create(
        &CreateAccountLinksRequest {
            account_id: "biz_xxxxxxxxxxxxx".to_string(),
            refresh_url: "https://yourapp.com/onboarding/refresh".to_string(),
            return_url: "https://yourapp.com/onboarding/complete".to_string(),
            use_case: AccountLinkUseCases::AccountOnboarding,
        },
        None,
    )
    .await?;

println!("{}", account_link.url);
```

```go Go theme={null}
accountLink, err := client.AccountLinks.Create(context.TODO(), &whopsdk.CreateAccountLinksRequest{
    AccountID:  "biz_xxxxxxxxxxxxx",
    RefreshURL: "https://yourapp.com/onboarding/refresh",
    ReturnURL:  "https://yourapp.com/onboarding/complete",
    UseCase:    whopsdk.AccountLinkUseCasesAccountOnboarding,
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(accountLink.URL)
```

Une fois que le destinataire a terminé son onboarding, vous pouvez :

* créer pour lui des parcours de checkout avec des frais d'application.
* transférer des fonds vers le solde de son compte.
* lui permettre de retirer ses fonds avec le portail de versement.

## Prise en main

Avant de pouvoir inscrire des sous-comptes, vous devez configurer le compte de votre plateforme :

1. **Créez un compte de plateforme** : créez un compte sur [whop.com/dashboard](https://whop.com/dashboard)
2. **Générez une clé API Account** : accédez à la page des paramètres développeur et générez une clé API Account
3. **Utilisez la clé API pour l'authentification** : cette clé API vous permet de vous authentifier auprès de l'API actuelle et de contrôler vos sous-comptes

La clé API Account fournit les permissions nécessaires pour créer et gérer des sous-comptes sous le compte de votre plateforme.

## Métadonnées personnalisées

Vous pouvez associer des métadonnées personnalisées aux comptes lors de leur création. Les métadonnées vous permettent de stocker des informations supplémentaires sur chaque sous-compte sous forme de paires clé-valeur. C'est utile pour :

* Suivre les niveaux ou classifications des sous-comptes
* Établir un lien avec les enregistrements de la base de données de votre plateforme

Whop stocke les métadonnées sur l'objet Account et les renvoie à chaque lecture, mais vous ne pouvez pas filtrer les comptes selon celles-ci. Placez plutôt l'identifiant qui vous sert à rechercher les comptes dans `external_id`.

## Référence de l'API

> [card] [API Create Account](https://docs.whop.com/fr/api-reference/accounts/create-account.md)
>
> Consultez la référence complète de l'API pour la création de comptes et tous les paramètres disponibles

## Étapes suivantes

Après avoir créé un compte pour un sous-compte :

> [card] [Encaisser et répartir des paiements](https://docs.whop.com/fr/developer/platforms/collect-payments-for-subaccounts.md)
>
> Choisissez entre débits directs et transferts

> [card] [Afficher le portail de versement](https://docs.whop.com/fr/developer/platforms/render-payout-portal.md)
>
> Permettez aux sous-comptes de retirer leurs fonds


## Related topics

- [Encaisser des paiements pour des sous-comptes](https://docs.whop.com/fr/developer/platforms/collect-payments-for-subaccounts.md)
- [Synchroniser les utilisateurs avec le chat intégré](https://docs.whop.com/fr/developer/guides/chat/sync-users.md)
- [Démarrage rapide de plateforme](https://docs.whop.com/fr/developer/platforms/quickstart.md)
