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

# 하위 계정 등록

> 플랫폼의 비즈니스나 개인을 위한 하위 계정을 생성하고, 온보딩을 완료할 수 있는 링크를 보내세요.

플랫폼에 하위 계정을 등록하려면 플랫폼 계정 아래에 해당 대상을 위한 Account 객체를 생성하세요. 그러면 해당 계정은 직접 청구를 받고, 이체를 수신하며, Whop 지급 흐름을 사용할 수 있습니다.

## 예시

하위 계정을 위한 계정을 생성하세요:

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

이 예시에서:

* `email`은 하위 계정의 이메일 주소입니다. Whop은 이를 사용해 하위 계정을 식별하고 중요한 알림을 보냅니다.
* Account API 키에 따라 하위 계정을 소유하는 플랫폼 계정이 결정됩니다.
* `title`은 하위 계정의 필수 표시 이름입니다.
* `external_id`는 이 하위 계정에 대한 플랫폼 자체의 ID입니다(예: 스토어 ID). 각 ID는 하나의 하위 계정에 매핑되며, 나중에 이 ID로 계정을 조회할 수 있습니다.
* `metadata`에는 하위 계정의 분류 또는 등급 수준인 `seller_tier`(예: "bronze", "silver", "gold")와 같은 사용자 지정 키-값 쌍이 포함됩니다.
* 응답에는 향후 API 호출에서 이 하위 계정을 참조하는 데 사용할 수 있는 `account.id`가 포함됩니다

> [!TIP]
>
> 이메일 주소는 계정을 관리할 하위 계정(비즈니스 또는
> 개인)의 것이어야 합니다. 이 사람이 계정
> 설정 및 결제 알림을 받게 됩니다.

## 자체 ID로 하위 계정 찾기

`external_id`로 하위 계정 목록을 조회하여 레코드 중 하나에 해당하는 계정을 가져오세요. 값 끝에 `%`를 붙이면 `shopline:%`처럼 선택한 네임스페이스로 시작하는 ID를 가진 모든 계정을 가져옵니다. 일치는 대소문자를 구분하며, `_`는 문자 그대로 일치하고, `%`는 끝에서만 작동하므로 생성하는 ID에 이 문자를 포함할 수 없습니다.

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

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

Update Account는 기존 하위 계정의 `external_id`를 설정하거나 지웁니다. 플랫폼만 이를 변경할 수 있습니다. 하위 계정은 읽을 수 있지만 편집할 수는 없습니다.

## 이메일 주소 재사용

각 하위 계정에 고유한 `external_id`가 있는 한 여러 하위 계정이 하나의 이메일 주소를 공유할 수 있습니다. 계정 생성은 이메일과 `external_id` 쌍에 대해 멱등적입니다:

* **새 `external_id`**: 이메일이 이미 사용 중이더라도 Whop이 새 하위 계정을 생성합니다.
* **동일한 이메일과 `external_id`**: Whop이 중복을 생성하는 대신 기존 하위 계정을 반환하므로 재시도가 안전합니다.
* **다른 이메일에 이미 사용된 `external_id`**: Whop은 해당 ID로 두 번째 계정을 생성하는 대신 `409`를 반환합니다. 같은 요청에서 ID를 새 계정으로 옮기려면 [ID에 연결된 계정 교체](#replace-the-account-behind-an-id)를 참고하세요.
* **`external_id` 없음**: 해당 이메일에 대해 `external_id`가 없는 기존 하위 계정이 있으면 Whop이 이를 반환합니다.

이메일을 공유하는 계정은 해당 받은편지함을 받는 사람인 동일한 Whop 사용자가 관리합니다.

> [!NOTE]
>
> 이 가이드의 이전 버전에서는 `external_id`를 `metadata` 안에 넣었습니다. Whop은 모든 API
> 버전에서 여전히 이를 허용하며, 이 값으로 `external_id`를 설정하고 `metadata`에 반환합니다. 최상위 필드와 동일한 규칙을 따르며,
> 다른 하위 계정이 이미 해당 값을 가지고 있으면 `409`를 반환하므로, 재사용하려면 `reassign_external_id: true`를 보내세요.
> 나중에 `metadata.external_id`를 변경해도 `external_id`는 변경되지 않습니다. 변경하려면 Update Account를 사용하세요. 새
> 통합에서는 최상위 필드를 보내야 합니다.

## ID에 연결된 계정 교체

새 소유자에게 이전되는 스토어처럼 자체 시스템에서 계정을 다시 발급하는 경우, 동일한 `external_id`와 `reassign_external_id: true`로 새 하위 계정을 생성하세요. Whop은 `409`를 반환하는 대신 같은 요청에서 ID를 새 하위 계정으로 옮깁니다.

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

* ID를 가지고 있던 하위 계정은 삭제되거나 다른 방식으로 변경되지 않습니다. `external_id`가 `null`로 설정된 상태로 활성 상태를 유지하고, `metadata`와 잔액을 유지하며, `account.updated` 웹훅을 보냅니다. 더 이상 필요하지 않으면 직접 삭제하세요.
* 생성이 실패하면 ID는 원래 위치에 그대로 남습니다.
* 기존 하위 계정을 변경하므로, 요청에는 `company:create_child`와 함께 플랫폼 계정에 대한 `company:update` 권한이 필요합니다.
* 기존 하위 계정과 동일한 이메일과 `external_id`를 가진 요청은 플래그를 설정하더라도 해당 하위 계정을 반환합니다.
* ID는 자신의 하위 계정 사이에서만 이동합니다.

이미 존재하는 두 하위 계정 사이에서 ID를 옮기려면 Update Account를 두 번 호출하세요: 이전 계정에서 `external_id`를 지운 다음, 다른 계정에 설정합니다. Update Account에는 `reassign_external_id`가 없으며, ID를 지우기 전에 설정하면 `409`가 반환됩니다.

## 온보딩 완료

수신자에게 아직 Whop 계정이 없다면, 계정을 생성한 후 계정 온보딩 링크를 보내세요. 수신자는 해당 링크를 통해 고객 확인(KYC) 인증을 완료하며, 그 후 계정은 이체 및 기타 지급 흐름을 받을 수 있습니다.

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

수신자가 온보딩을 완료하면 다음을 할 수 있습니다:

* 애플리케이션 수수료가 포함된 체크아웃 흐름을 생성합니다.
* 계정 잔액으로 자금을 이체합니다.
* 지급 포털로 자금을 출금하도록 합니다.

## 시작하기

하위 계정을 등록하려면 먼저 플랫폼 계정을 설정해야 합니다:

1. **플랫폼 계정에 가입**: [whop.com/dashboard](https://whop.com/dashboard)에서 계정을 생성하세요
2. **Account API 키 생성**: 개발자 설정 페이지로 이동하여 Account API 키를 생성하세요
3. **인증에 API 키 사용**: 이 API 키로 Current API에 인증하고 하위 계정을 제어합니다

Account API 키는 플랫폼 계정 아래에서 하위 계정을 생성하고 관리하는 데 필요한 권한을 제공합니다.

## 사용자 지정 메타데이터

계정을 생성할 때 사용자 지정 메타데이터를 첨부할 수 있습니다. 메타데이터를 사용하면 각 하위 계정에 대한 추가 정보를 키-값 쌍으로 저장할 수 있습니다. 다음과 같은 경우에 유용합니다:

* 하위 계정 등급 또는 분류 추적
* 플랫폼 데이터베이스 레코드와 연결

Whop은 메타데이터를 Account 객체에 저장하고 모든 읽기에서 반환하지만, 이를 기준으로 계정을 필터링할 수는 없습니다. 계정을 조회할 때 사용하는 식별자는 대신 `external_id`에 넣으세요.

## API 레퍼런스

> [card] [Create Account API](https://docs.whop.com/ko/api-reference/accounts/create-account.md)
>
> 계정 생성 및 사용 가능한 모든 매개변수에 대한 전체 API 레퍼런스를 확인하세요

## 다음 단계

하위 계정을 위한 Account를 생성한 후:

> [card] [결제 수금 및 분배](https://docs.whop.com/ko/developer/platforms/collect-payments-for-subaccounts.md)
>
> 직접 청구와 이체 중에서 선택하기

> [card] [지급 포털 렌더링](https://docs.whop.com/ko/developer/platforms/render-payout-portal.md)
>
> 하위 계정이 자금을 출금할 수 있도록 하기


## Related topics

- [하위 계정을 위한 결제 수금](https://docs.whop.com/ko/developer/platforms/collect-payments-for-subaccounts.md)
- [임베디드 채팅에 사용자 동기화하기](https://docs.whop.com/ko/developer/guides/chat/sync-users.md)
- [플랫폼 빠른 시작](https://docs.whop.com/ko/developer/platforms/quickstart.md)
