Skip to main content
To enroll a subaccount on your platform, create an Account object for them under your platform account. That account can then accept direct charges, receive transfers, and use Whop payout flows.

Example

Create an account for the subaccount:
In this example:
  • email is the subaccount’s email address. Whop uses it to identify the subaccount and send important notifications.
  • The Account API key determines which platform account owns the subaccount.
  • title is the required display name for the subaccount.
  • external_id is your platform’s own ID for this subaccount, for example your store ID. Each ID maps to one subaccount, and you can look the account up by it later.
  • metadata contains custom key-value pairs, such as seller_tier, a classification or tier level for the subaccount (e.g., “bronze,” “silver,” or “gold”).
  • The response includes an account.id that you can use to reference this subaccount in future API calls
The email address should belong to the subaccount (business or individual) who will be managing the account. This person will receive account setup and payment notifications.

Find a subaccount by your ID

List your subaccounts with external_id to get the account for one of your records. End the value with % to get every account whose ID starts with a namespace you chose, such as shopline:%. Matching is case-sensitive, _ matches literally, and % works only at the end, so IDs you create can’t contain it.
TypeScript
Update Account sets or clears external_id on an existing subaccount. Only your platform can change it. The subaccount can read it but can’t edit it.

Reusing an email address

Several subaccounts can share one email address, as long as each one has a distinct external_id. Creating an account is idempotent on the email and external_id pair:
  • New external_id: Whop creates a new subaccount, even when the email is already in use.
  • Same email and external_id: Whop returns the existing subaccount instead of creating a duplicate, so retries are safe.
  • external_id already used with another email: Whop returns a 409 instead of creating a second account with that ID. To move the ID to the new account in the same request, see Replace the account behind an ID.
  • No external_id: Whop returns the existing subaccount for that email that has no external_id, if there is one.
Accounts that share an email are managed by the same Whop user, the person who receives that inbox.
Earlier versions of this guide put external_id inside metadata. Whop still accepts it there on every API version, sets external_id from it, and returns it in metadata. It follows the same rules as the top-level field, including the 409 when another subaccount already has it, so send reassign_external_id: true to reuse one. Changing metadata.external_id later doesn’t change external_id. To change it, use Update Account. New integrations should send the top-level field.

Replace the account behind an ID

When you reissue an account on your side, for example a store that moves to a new owner, create the new subaccount with the same external_id and reassign_external_id: true. Whop moves the ID to the new subaccount in the same request instead of returning a 409.
TypeScript
  • The subaccount that had the ID isn’t deleted or changed in any other way. It stays active with external_id set to null, keeps its metadata and balance, and sends an account.updated webhook. Delete it yourself if you no longer need it.
  • If the create fails, the ID stays where it was.
  • The request needs the company:update permission on your platform account as well as company:create_child, because it changes an existing subaccount.
  • A request with the same email and external_id as an existing subaccount returns that subaccount, even when it sets the flag.
  • The ID only moves between your own subaccounts.
To move an ID between two subaccounts that already exist, call Update Account twice: clear external_id on the old one, then set it on the other. Update Account has no reassign_external_id, and setting the ID before clearing it returns a 409.

Finish onboarding

If the recipient doesn’t already have a Whop account, send them an account onboarding link after you create the account. They complete Know Your Customer (KYC) verification through that link, and then the account can receive transfers and other payout flows.
After the recipient completes onboarding, you can:
  • create checkout flows for them with application fees.
  • transfer funds to their account balance.
  • let them withdraw funds with the payout portal.

Getting started

Before you can enroll subaccounts, you need to set up your platform account:
  1. Sign up for a platform account: Create an account at whop.com/dashboard
  2. Generate an Account API key: Go to your developer settings page and generate an Account API key
  3. Use the API key for authentication: This API key is how you authenticate with the Current API and control your subaccounts
The Account API key provides the necessary permissions to create and manage subaccounts under your platform account.

Custom metadata

You can attach custom metadata to accounts when creating them. Metadata lets you store additional information about each subaccount as key-value pairs. This is useful for:
  • Tracking subaccount tiers or classifications
  • Linking to your platform’s database records
Whop stores metadata on the Account object and returns it on every read, but you can’t filter accounts by it. Put the identifier you look accounts up by in external_id instead.

API reference

Create Account API

See the full API reference for creating accounts and all available parameters

Next steps

After creating an Account for a subaccount:

Collect and split payments

Choose between direct charges and transfers

Render payout portal

Let subaccounts withdraw their funds