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

# Dar de alta subcuentas

> Crea subcuentas para los negocios o las personas de tu plataforma y envíales un enlace para completar la incorporación.

Para dar de alta una subcuenta en tu plataforma, crea un objeto Account para ella bajo la cuenta de tu plataforma. Esa cuenta podrá entonces aceptar cargos directos, recibir transferencias y usar los flujos de pagos salientes de Whop.

## Ejemplo

Crea una cuenta para la subcuenta:

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

En este ejemplo:

* `email` es la dirección de correo electrónico de la subcuenta. Whop la usa para identificar la subcuenta y enviar notificaciones importantes.
* La clave de API de la cuenta determina qué cuenta de plataforma es propietaria de la subcuenta.
* `title` es el nombre visible obligatorio de la subcuenta.
* `external_id` es el ID propio de tu plataforma para esta subcuenta, por ejemplo el ID de tu tienda. Cada ID corresponde a una subcuenta, y puedes buscar la cuenta por él más adelante.
* `metadata` contiene pares clave-valor personalizados, como `seller_tier`, una clasificación o nivel para la subcuenta (p. ej., "bronze", "silver" o "gold").
* La respuesta incluye un `account.id` que puedes usar para hacer referencia a esta subcuenta en futuras llamadas a la API

> [!TIP]
>
> La dirección de correo electrónico debe pertenecer a la subcuenta (negocio o
> persona física) que gestionará la cuenta. Esta persona recibirá las notificaciones
> de configuración de la cuenta y de pagos.

## Buscar una subcuenta por tu ID

Lista tus subcuentas con `external_id` para obtener la cuenta correspondiente a uno de tus registros. Termina el valor con `%` para obtener todas las cuentas cuyo ID empieza por un espacio de nombres que hayas elegido, como `shopline:%`. La coincidencia distingue entre mayúsculas y minúsculas, `_` coincide de forma literal y `%` solo funciona al final, así que los ID que crees no pueden contenerlo.

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

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

Update Account establece o borra `external_id` en una subcuenta existente. Solo tu plataforma puede cambiarlo. La subcuenta puede leerlo, pero no editarlo.

## Reutilizar una dirección de correo electrónico

Varias subcuentas pueden compartir una dirección de correo electrónico, siempre que cada una tenga un `external_id` distinto. La creación de una cuenta es idempotente respecto al par de correo electrónico y `external_id`:

* **`external_id` nuevo**: Whop crea una subcuenta nueva, aunque el correo electrónico ya esté en uso.
* **Mismo correo electrónico y `external_id`**: Whop devuelve la subcuenta existente en lugar de crear un duplicado, así que los reintentos son seguros.
* **`external_id` ya usado con otro correo electrónico**: Whop devuelve un `409` en lugar de crear una segunda cuenta con ese ID. Para mover el ID a la cuenta nueva en la misma solicitud, consulta [Sustituir la cuenta asociada a un ID](#replace-the-account-behind-an-id).
* **Sin `external_id`**: Whop devuelve la subcuenta existente para ese correo electrónico que no tiene `external_id`, si la hay.

Las cuentas que comparten un correo electrónico las gestiona el mismo usuario de Whop: la persona que recibe esa bandeja de entrada.

> [!NOTE]
>
> Las versiones anteriores de esta guía ponían `external_id` dentro de `metadata`. Whop sigue aceptándolo ahí en todas las versiones
> de la API, establece `external_id` a partir de él y lo devuelve en `metadata`. Sigue las mismas reglas que el campo de nivel superior,
> incluido el `409` cuando otra subcuenta ya lo tiene, así que envía `reassign_external_id: true` para reutilizar uno.
> Cambiar `metadata.external_id` más adelante no cambia `external_id`. Para cambiarlo, usa Update Account. Las integraciones
> nuevas deben enviar el campo de nivel superior.

## Sustituir la cuenta asociada a un ID

Cuando vuelves a emitir una cuenta por tu parte, por ejemplo una tienda que pasa a un nuevo propietario, crea la nueva subcuenta con el mismo `external_id` y `reassign_external_id: true`. Whop mueve el ID a la nueva subcuenta en la misma solicitud en lugar de devolver un `409`.

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

* La subcuenta que tenía el ID no se elimina ni se modifica de ninguna otra forma. Sigue activa con `external_id` establecido en `null`, conserva su `metadata` y su saldo, y envía un webhook `account.updated`. Elimínala tú mismo si ya no la necesitas.
* Si la creación falla, el ID se queda donde estaba.
* La solicitud necesita el permiso `company:update` en la cuenta de tu plataforma además de `company:create_child`, porque modifica una subcuenta existente.
* Una solicitud con el mismo correo electrónico y `external_id` que una subcuenta existente devuelve esa subcuenta, aunque establezca el indicador.
* El ID solo se mueve entre tus propias subcuentas.

Para mover un ID entre dos subcuentas que ya existen, llama a Update Account dos veces: borra `external_id` en la antigua y luego establécelo en la otra. Update Account no tiene `reassign_external_id`, y establecer el ID antes de borrarlo devuelve un `409`.

## Completar la incorporación

Si el destinatario aún no tiene una cuenta de Whop, envíale un enlace de incorporación de cuenta después de crear la cuenta. Completa la verificación Know Your Customer (KYC) a través de ese enlace y, a partir de ahí, la cuenta puede recibir transferencias y otros flujos de pagos salientes.

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

Una vez que el destinatario completa la incorporación, puedes:

* crear flujos de checkout para él con comisiones de aplicación.
* transferir fondos al saldo de su cuenta.
* permitirle retirar fondos con el portal de pagos salientes.

## Primeros pasos

Antes de poder dar de alta subcuentas, debes configurar la cuenta de tu plataforma:

1. **Regístrate para obtener una cuenta de plataforma**: crea una cuenta en [whop.com/dashboard](https://whop.com/dashboard)
2. **Genera una clave de API de cuenta**: ve a la página de configuración de desarrollador y genera una clave de API de cuenta
3. **Usa la clave de API para la autenticación**: esta clave de API es la forma de autenticarte con la API actual y controlar tus subcuentas

La clave de API de cuenta proporciona los permisos necesarios para crear y gestionar subcuentas bajo la cuenta de tu plataforma.

## Metadatos personalizados

Puedes adjuntar metadatos personalizados a las cuentas al crearlas. Los metadatos te permiten almacenar información adicional sobre cada subcuenta como pares clave-valor. Esto es útil para:

* Hacer seguimiento de los niveles o clasificaciones de las subcuentas
* Vincular con los registros de la base de datos de tu plataforma

Whop almacena los metadatos en el objeto Account y los devuelve en cada lectura, pero no puedes filtrar cuentas por ellos. Pon en `external_id` el identificador por el que buscas las cuentas.

## Referencia de la API

> [card] [API Create Account](https://docs.whop.com/es/api-reference/accounts/create-account.md)
>
> Consulta la referencia completa de la API para crear cuentas y todos los parámetros disponibles

## Próximos pasos

Después de crear una cuenta para una subcuenta:

> [card] [Cobrar y repartir pagos](https://docs.whop.com/es/developer/platforms/collect-payments-for-subaccounts.md)
>
> Elige entre cargos directos y transferencias

> [card] [Renderizar el portal de pagos salientes](https://docs.whop.com/es/developer/platforms/render-payout-portal.md)
>
> Permite que las subcuentas retiren sus fondos


## Related topics

- [Cobrar pagos para subcuentas](https://docs.whop.com/es/developer/platforms/collect-payments-for-subaccounts.md)
- [Inicio rápido de plataformas](https://docs.whop.com/es/developer/platforms/quickstart.md)
- [Marketplaces y plataformas](https://docs.whop.com/es/developer/marketplaces/overview.md)
