Accounts API

Use accounts for customers, creators, merchants, sellers, or connected businesses your integration supports. Use the Accounts API to create accounts, list accounts visible to your credentials, retrieve or update an account, suspend or delete a subaccount managed by your platform, and retrieve the account associated with the current API key. The business_type, industry_group, and industry_type fields classify accounts. See the business types and industries glossary for every valid value.

Endpoints

Endpoint	Request
List Accounts	GET `/accounts`
Retrieve Account	GET `/accounts/{id}`
Retrieve Account Customer Tracking	GET `/accounts/{account_id}/customer_tracking`
Retrieve Account Fees	GET `/accounts/{account_id}/fees`
List Financing Providers	GET `/accounts/{account_id}/financing_providers`
Retrieve Account Preferences	GET `/accounts/{account_id}/preferences`
List Account Reserves	GET `/accounts/{account_id}/reserves`
Create Account	POST `/accounts`
Form Company	POST `/accounts/{id}/form_company`
Retry Failed Ads Payments	POST `/accounts/{id}/retry_ads_payment`
Suspend a Subaccount	POST `/accounts/{id}/suspend`
Transfer Account Ownership	POST `/accounts/{id}/transfer_ownership`
Update Account	PATCH `/accounts/{id}`
Update Account Fees	PATCH `/accounts/{account_id}/fees`
Update Account Preferences	PATCH `/accounts/{account_id}/preferences`
Delete a Subaccount	DELETE `/accounts/{id}`

Fee markups

Fee markups let a platform add charges or subsidize payout fees for its subaccounts. Manage them through the account fees document: set defaults on the platform account or override individual fees on a subaccount. See Fee markups & subsidies for examples, limits, and funding requirements.

Fee endpoints

Action	Endpoint	SDK Method
Retrieve account fees	`GET /api/v1/accounts/{account_id}/fees`	`client.accounts.fees.retrieve(accountId)`
Update account fees	`PATCH /api/v1/accounts/{account_id}/fees`	`client.accounts.fees.update(accountId, changes)`

Use the platform account’s API key with company:update_child_fees permission to configure markups. Each returned markup includes adjustable and unadjustable_reason so your integration can determine whether editing is available.

Read fees

const fees = await client.accounts.fees.retrieve("biz_connected_account");

The markups section contains the subaccount’s effective rates. The child_markups section on a platform account contains its defaults for subaccounts. A markup’s source is custom when configured at that level, or default when it falls through to an inherited rate or zero. Its default field shows the rate that would apply if the custom markup were cleared. Returned fixed amounts use the Money object; updates accept fixed as a number in US dollars.

Set platform defaults

Update child_markups on the platform account. This example sets a 2% payment markup with no fixed charge:

await client.accounts.fees.update("biz_platform_id", {
	child_markups: { payments: { percentage: 2, fixed: 0 } },
});

percentage: 2 means 2%. Defaults apply to subaccounts without an override for that fee. Payment markups apply when no checkout application fee is set.

Set a Subaccount override

Update markups on the subaccount. This example replaces its inherited payment markup with 1% plus $0.25:

await client.accounts.fees.update("biz_connected_account", {
	markups: { payments: { percentage: 1, fixed: 0.25 } },
});

Only the keys you send change. For other transaction types, use transfers, crypto_swaps, deposits keyed by rail, or payouts keyed by payout method. See the update endpoint for the supported keys and request schema.

Clear a markup

Send null for the markup to clear it. Clearing a subaccount’s override restores its platform default, or zero if no default is configured:

await client.accounts.fees.update("biz_connected_account", {
	markups: { payments: null },
});

To clear a platform default, send child_markups: { payments: null } to the platform account. An explicit { percentage: 0, fixed: 0 } remains a configured rate; use null to restore inheritance.

Legal documents

An account publishes its legal documents as PDF files: terms_of_service, privacy_policy, return_policy, cancellation_policy, shipping_policy, and eula. Each reads back as a File and is set through Update Account with the id of a file you uploaded. New disputes default their policy evidence from these documents. The cancellation policy slot takes cancellation_policy, then terms_of_service, then return_policy. The refund policy slot takes return_policy, then terms_of_service. Either slot falls back to Whop’s platform policy when none is set, and shipping_policy rides along on physical-goods disputes. Set them once here, and use Upload Dispute Evidence only when one dispute needs a different version of a policy.

import { readFile } from "node:fs/promises";

const file = await client.files.create({ filename: "terms-of-service.pdf" });
await fetch(file.upload_url!, {
	method: "PUT",
	headers: file.upload_headers as Record<string, string>,
	body: await readFile("./terms-of-service.pdf"),
});

await client.accounts.update({
	id: "biz_xxxxxxxxxxxxx",
	terms_of_service: { id: file.id },
});

import requests

file = client.files.create(filename="terms-of-service.pdf")
with open("./terms-of-service.pdf", "rb") as contents:
    requests.put(file.upload_url, headers=file.upload_headers or {}, data=contents)

client.accounts.update(
    "biz_xxxxxxxxxxxxx",
    terms_of_service={"id": file.id},
)

Send null for a document to remove it. Only PDF files are accepted.

Attributes

string

required

Account ID, prefixed biz_.

number | null

required

Lifetime charged ad spend for the account, in USD. Computed only on list for callers with stats:read on the account; null otherwise.

object[]

required

Account holdings, each with USD value. Empty when total_usd is null.

Properties

string

required

Total amount held in native units, as a decimal string.

object

required

Balance split into available, pending, and reserve amounts, as native-unit decimal strings, with the days the pending amount is expected to settle.

Properties

string

required

Amount you can spend, send, or withdraw now, in native units, as a decimal string.

string

required

The part of pending that has already settled and is waiting to move into the account’s crypto wallet or Whop Card, where it becomes available. The move usually starts within the hour; while it runs, the amount is reported in in_transit instead. Money moved only to top up the account’s retained minimum balance is not included. In native units, as a decimal string.

string

required

Amount moving between the account’s own destinations, such as a card top-up. In native units, as a decimal string.

string

required

Amount from recent payments still settling, in native units, as a decimal string.

object[]

required

When the pending amount is expected to settle, one entry per day, earliest first. Money without a scheduled settlement day, including finishing_settlement, is left out, so these entries plus finishing_settlement can sum to less than pending, never more.

Properties

string

required

Amount expected that day, in native units, as a decimal string.

string

required

The day this money is expected to finish settling, as an ISO 8601 date.

string

required

Amount held back, in native units, as a decimal string. Retrieve the account’s reserves for why it is held and when it unlocks.

string | null

required

Holding icon URL.

string

required

The holding’s display name

number | null

required

USD price per unit, or null when no exchange rate is available.

string

required

Holding display symbol, such as USDT, cbBTC, or EUR.

string | null

required

Holding USD value, or null when no exchange rate is available.

string | null

required

Account banner image URL.

object | null

required

Account business address used to calculate tax, with line1, line2, city, state, postal_code, and country. null when no address is set.

string | null

required

The account’s legal business name used with its tax address.

string | null

required

High-level business category for the account. See the business types and industries glossary for valid values.

boolean

required

Whether pending funds may be transferred from this platform account to its subaccounts.

object | null

required

The account’s cancellation policy document, or null if they have not published one.

Properties

string

required

The file’s ID, prefixed file_.

string | null

required

BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.

string | null

required

The original file’s MIME type, for example application/pdf. It is kept when moderation removes the file.

string

required

When the file was created, as an ISO 8601 timestamp.

number | null

required

Audio or video duration in seconds. Null when unavailable or removed by moderation.

string | null

required

The original filename, including its extension.

integer | null

required

Image or video height in pixels. Null when unavailable or removed by moderation.

integer | null

The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.

string | null

The ID of the multipart upload, passed back to complete. Present only on create, and only for multipart uploads.

object[] | null

The presigned URL for each part. Present only on create, and only for multipart uploads.

Properties

integer

required

The 1-based index of this part within the multipart upload.

string

required

The presigned URL to PUT this part’s bytes to.

string

required

The type of this object, always file.

boolean

required

Whether moderation removed the file. When true, url serves a replacement image. filename, size and content_type still describe the original file.

integer | null

required

The file size in bytes. null until the upload has finished.

object

Headers to send with the upload PUT. Present only on create.

string

required

Where the file is in its upload lifecycle.Available options: pending, processing, ready, failed

string | null

Presigned URL to PUT the file’s bytes to. Present only on create, and only for single-part uploads.

string | null

required

A URL to download the file. Public files get a permanent CDN URL, and private files get a signed URL that expires. null until the upload has finished. When moderation removes the file, a replacement image URL.

string

required

public files are served from an unsigned CDN URL. private files are served from a signed URL that expires.Available options: public, private

string | null

required

Audio waveform URL. Null when unavailable or removed by moderation.

integer | null

required

Image or video width in pixels. Null when unavailable or removed by moderation.

object | null

required

Payment rails enabled for this account, each active, inactive, or pending (onboarding or review in progress). Computed only on retrieve and me for callers with company:balance:read scope; null otherwise.

Properties

string

required

Bank payins: debits, transfers, and local bank railsAvailable options: active, inactive, pending

string

required

Buy-now-pay-later payins; requires approvalAvailable options: active, inactive, pending

string

required

Card payins, including Apple Pay and Google PayAvailable options: active, inactive, pending

string

required

Deposits by bank wire or ACH to the account’s virtual bank accountAvailable options: active, inactive, pending

string

required

Balance top-ups by charging a stored payment methodAvailable options: active, inactive, pending

string

required

Issuing Whop cards; requires card application approvalAvailable options: active, inactive, pending

string

required

On-chain deposits to the account’s crypto walletAvailable options: active, inactive, pending

string

required

On-chain payouts to a crypto walletAvailable options: active, inactive, pending

string

required

Instant payouts to an eligible payout destinationAvailable options: active, inactive, pending

string

required

Launching ad campaigns through Whop Ads. inactive until the account’s identity or business is verified, while a requested ads services agreement is awaiting the account’s signature, and while the account is suspended from Whop Ads.Available options: active, inactive, pending

string

required

Standard payouts to an external payout destinationAvailable options: active, inactive, pending

string

required

Transfers to other accountsAvailable options: active, inactive, pending

object | null

required

Whop Cards application details for the account. Returned on list, retrieve, and me for callers with company:balance:read scope; null otherwise, or when the account has no card application or blocking application review.

Properties

string | null

required

Whether the card application verifies a business (business, KYB) or a person (individual, consumer identity). null when the application is not yet linked to a verification.Available options: individual, business

string

required

Where the card application stands. approved means cards can be issued. needs_verification means the applicant has not completed identity verification yet; needs_information means they did, but the documents were rejected for a fixable reason and must be resubmitted. pending and manual_review are in flight. denied, locked, and canceled are terminal.Available options: approved, pending, manual_review, denied, locked, canceled, needs_verification, needs_information

boolean

required

Whether checkout shows a VAT/tax ID field for buyers to optionally enter. Does not require a VAT ID to purchase.

object

required

Company formation state for the account, managed through Form Company. A draft status until the formation checkout is paid, then filing progress with downloadable documents and signatures awaiting action. Empty when the formation state is temporarily unavailable.

Properties

object[]

Formation documents available for download, such as the Articles of Organization and the EIN confirmation letter. Present once status leaves draft.

Properties

string

required

Document ID, prefixed file_.

string

required

Human-readable document name, such as Articles of Organization.

string

required

Document category: articles_of_organization, operating_agreement, ein_letter, signed_ss4, signed_form8821, or mail for postal correspondence received on the company’s behalf.

string

required

CDN URL for downloading the document.

boolean

Whether the company’s EIN has been issued by the IRS. Present once status leaves draft.

string | null

Registered company name including the entity ending, for example Acme, LLC. Present once status leaves draft.

object

IRS forms still awaiting a founder’s signature, each with a hosted signing URL. Present once status leaves draft; empty when nothing needs signing.

Properties

object

Signature state for IRS Form 8821, the tax information authorization. Present only while the form still needs the founder’s action.

Properties

string

When the signing URL expires, as an ISO 8601 timestamp. Present only when the signing URL is included.

string

required

pending when a signing session is ready for the founder; unknown when the signature state could not be determined.Available options: pending, unknown

string

Hosted signing URL where the founder completes the form. Present while status is pending and the caller has incorporation:write. Omitted from webhooks.

object

Signature state for IRS Form SS-4, the EIN application. Present only while the form still needs the founder’s action.

Properties

string

When the signing URL expires, as an ISO 8601 timestamp. Present only when the signing URL is included.

string

required

pending when a signing session is ready for the founder; unknown when the signature state could not be determined.Available options: pending, unknown

string

Hosted signing URL where the founder completes the form. Present while status is pending and the caller has incorporation:write. Omitted from webhooks.

boolean

Whether the state formation filing is complete. Present once status leaves draft.

string

Available options: draft, processing, filed, rejected, completed

string | null

required

Country where the account is located.

string

required

When the account was created, as an ISO 8601 timestamp.

integer | null

required

Distinct customers with a paid receipt at the account in the last 30 days, refreshed every few hours. Computed only on retrieve for callers with stats:read on the account; null otherwise, and when the count is unavailable.

string | null

required

Account promotional description.

integer

How many team members report to the business directly, with no manager above them. Present on single-account reads.

boolean

required

Whether Whop assembles and files dispute evidence for this account. Enabling it opts the account into the success fee charged on disputes it wins.

boolean

required

Whether Economic Intelligence is on for the account. It turns off automatically when its committed period ends. While it is off, the account can’t activate an experiment or run a recommendation.

string | null

required

Account owner email address.

object | null

required

The account’s end-user license agreement document, or null if they have not published one.

Properties

string

required

The file’s ID, prefixed file_.

string | null

required

BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.

string | null

required

The original file’s MIME type, for example application/pdf. It is kept when moderation removes the file.

string

required

When the file was created, as an ISO 8601 timestamp.

number | null

required

Audio or video duration in seconds. Null when unavailable or removed by moderation.

string | null

required

The original filename, including its extension.

integer | null

required

Image or video height in pixels. Null when unavailable or removed by moderation.

integer | null

The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.

string | null

The ID of the multipart upload, passed back to complete. Present only on create, and only for multipart uploads.

object[] | null

The presigned URL for each part. Present only on create, and only for multipart uploads.

Properties

integer

required

The 1-based index of this part within the multipart upload.

string

required

The presigned URL to PUT this part’s bytes to.

string

required

The type of this object, always file.

boolean

required

Whether moderation removed the file. When true, url serves a replacement image. filename, size and content_type still describe the original file.

integer | null

required

The file size in bytes. null until the upload has finished.

object

Headers to send with the upload PUT. Present only on create.

string

required

Where the file is in its upload lifecycle.Available options: pending, processing, ready, failed

string | null

Presigned URL to PUT the file’s bytes to. Present only on create, and only for single-part uploads.

string | null

required

string

required

public files are served from an unsigned CDN URL. private files are served from a signed URL that expires.Available options: public, private

string | null

required

Audio waveform URL. Null when unavailable or removed by moderation.

integer | null

required

Image or video width in pixels. Null when unavailable or removed by moderation.

string | null

required

The parent platform’s own identifier for this subaccount, unique among the platform’s subaccounts. null when unset.

object | null

required

The account’s most recent financing application. Computed only on retrieve and me for callers with company:balance:read scope; null otherwise, or when the account has never applied for financing.

Properties

string

required

The ID of the account’s most recent financing application, starting with inrq_. Retrieve it for requirements and review feedback.

string

required

The most recent financing application’s review state: requires_collection (waiting on the merchant, including after a request for more information), awaiting_review, approved, denied, or completed. Whether financing payment methods are enabled is capabilities.accept_bnpl_payments.Available options: requires_collection, awaiting_review, completed, approved, denied

string | null

required

When a suspended account can pay out its balance to its own payout method, as an ISO 8601 timestamp. A dispute can move it later. Computed on retrieve, me, and suspend; null otherwise, when status is not suspended, and when the suspension holds the balance.

string[]

required

Public account home page preferences.Available options: hide_member_count, hide_members_card

string | null

required

Specific industry vertical for the account. See the business types and industries glossary for valid values.

string | null

required

Prefix used for account invoices.

object | null

required

The Whop Levels progress of the account’s owner, counted across every account they own, so all of them show the same level. Computed only on retrieve and me for callers with company:basic:read scope; null otherwise, and when the account is not in Whop Levels.

Properties

integer

required

This account’s own level from its points alone, from 0 up to 10. applied_level is higher when the owner’s other accounts lift it.

integer

required

The level that applies: the highest the owner reached this month or in the 5 months before, from 0 up to 10.

boolean

required

true when this account’s own points this month fall short of applied_level, so the owner’s other accounts lift it to that level.

object[]

required

Every level from 0 through 10, with the monthly qualifying spend it takes and its standard card processing percentage in each card region.

Properties

integer

required

The processing level.

object

required

The monthly qualifying spend required to reach this level.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

How many decimal places to SHOW. Usually equal to decimals, and deliberately not always: COP is charged in centavos but written in whole pesos, so it is 2 and 0. Format the number in your own locale using this.

number

required

The standard US and Canada card processing percentage at this level, regardless of the account’s custom rate.

object[]

required

The card processing percentage at this level for each card region, starting with US and Canada.

Properties

number

required

The standard card processing percentage at this level for cards from this region, regardless of the account’s custom rate.

string

required

The card region this fee applies to.Available options: us_and_canada, europe_uk_and_australia, latin_america, peru, brazil

object

required

Whop Ads charges paid this calendar month across every account the owner owns, net of refunds, in USD, so it can be negative. An account whose month nets to zero or below is left out.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

Captured Whop Card spend this calendar month across every account the owner owns, net of refunds, in USD, so it can be negative. An account whose month nets to zero or below is left out.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

Qualifying spend this calendar month across every account the owner owns, plus the owner’s personal trading and partner points, in USD: points divided by 10.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

Perpetual trading volume filled through Whop this calendar month across every account the owner owns and their personal wallet, in USD. An account whose month nets to zero or below is left out.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

integer

required

Points earned this month across every account the owner owns, plus the owner’s partner points, rounded down. An account whose month nets below zero counts as zero.

object

required

This month’s points, split by where they were earned. Each source is net of its refunds, so one can be negative.

Properties

integer

required

Points from paid Whop Ads charges, net of refunds: 10 for every dollar, rounded toward zero.

integer

required

Points from captured Whop Card spend, net of refunds: 10 for every dollar, rounded toward zero.

integer

required

Points from accounts the owner referred as a partner: 1 for every 3 they earn, rounded toward zero.

integer

required

Points from perpetual trading volume filled through Whop: 1 for every dollar traded, rounded toward zero.

integer | null

required

Points still needed this month to reach the next level, or null at level 10.

string

required

When this month’s points reset to zero, as an ISO 8601 timestamp.

string | null

required

Account logo image URL.

object

required

Arbitrary key/value metadata supplied at account creation.

string | null

required

Type of onboarding the account has completed.Available options: platform, seller

string | null

required

Account Open Graph image URL.

string | null

required

Account Open Graph image variant.Available options: white, black, orange

boolean

required

Whether payment orchestration is enabled for this account.

string | null

required

Business type details when business_type is other.

string | null

required

Industry details when industry_type is other.

object

required

The single user who owns the account, whose email is the email above. Distinct from the owner role on team members, which any number of them can hold.

Properties

string

required

User ID, prefixed user_.

string | null

required

Display name.

object

required

Avatar wrapper. Its url is always present, and is a generated placeholder when the user set no picture.

Properties

string

required

Avatar image URL. Always present. It is a generated placeholder when the user set no picture.

string

required

Public username.

object | null

required

Parent account for subaccounts, or null for standalone accounts.

Properties

string

required

Account ID, prefixed biz_.

object

Markup rates this parent charges the subaccount being read, keyed by fee type (for example crypto_deposit_markup), each with percentage_fee and fixed_fee_usd. Resolved with the subaccount’s own overrides winning over the platform default.

string | null

required

Account logo image URL.

string

required

Account public route identifier.

string

required

Account display name.

object | null

The account’s active first-tier partner. Present on retrieve responses; null when no active first-tier partner is attributed to the account. Omitted from other responses.

Properties

string

required

User ID, prefixed user_.

string | null

required

Email address for contacting the partner. Null when the partner has not added their own email address.

string | null

required

Display name.

object

required

Avatar wrapper. Its url is always present, and is a generated placeholder when the user set no picture.

Properties

string

required

Avatar image URL. Always present. It is a generated placeholder when the user set no picture.

object | null

required

Business the partner referred this account on behalf of, when the referral belongs to their team. null for a personal referral.

Properties

string

required

Account ID, prefixed biz_.

string

required

Account display name.

string

required

Public username.

string | null

required

When the user became a verified Whop Partner, as an ISO 8601 timestamp. Null if not verified.

object | null

required

Payment health controls currently applied to the account. Computed only on retrieve and me for callers with company:balance:read scope; null otherwise.

Properties

object

required

Automatic refund settings for pre-chargeback dispute alerts.

Properties

boolean

required

Whether the account owner is prevented from changing this threshold.

number | null

required

Maximum dispute alert amount automatically refunded in USD. null when automatic refunds are disabled.

number | null

required

Fee charged for each dispute alert in USD. null when unavailable.

boolean

required

Whether 3-D Secure is forced on every card payment at checkout. The account cannot bypass it while set.

boolean

required

Whether payment health controls explicitly disable financing. This is independent of financing approval in capabilities.accept_bnpl_payments.

number

required

Additional processing fee percentage for high-risk processing.

object[]

required

Payment methods the account has been warned are nearing their dispute-rate line. Each entry carries payment_method, measure (disputes, disputes_and_tc40s or fraud_disputes), warned_at as an ISO 8601 timestamp, and the rate, warning_rate and target_rate as fractions where 0.01 is 1%. Empty when none are warned. A warned method is paused, and appears in restricted_payment_methods, if it is still over its target rate about four weeks later.

number

required

Percentage fee charged when pending, not-yet-settled balance is advanced to fund the account’s cards balance, where 2 means 2%. 0 when the account is exempt.

integer

required

Additional days payments remain pending before becoming available.

object

required

Reserve currently applied to incoming payment volume.

Properties

integer

required

Number of days reserved funds are held before release.

number | null

required

Percentage of incoming payment volume held in reserve. null when no reserve is applied.

object

required

Automatic refund settings for resolution center cases.

Properties

number | null

required

Maximum card-funded resolution center case amount automatically refunded in USD. null when automatic refunds are disabled for cards.

number | null

required

Maximum financing-funded resolution center case amount automatically refunded in USD. null when automatic refunds are disabled for financing.

boolean

required

Whether the account owner is prevented from changing these thresholds.

number | null

required

Maximum PayPal-funded resolution center case amount automatically refunded in USD. null when automatic refunds are disabled for PayPal.

string[]

required

Card brands blocked at checkout for this account. Empty when none are blocked. The account cannot re-enable them itself.Available options: card_visa, card_mastercard, card_american_express, card_discover_global_network, addi, affirm, afterpay_clearpay, alma, billie, capchase_pay, claritypay, flex_pay, klarna, kriya, kueski, mondu, oney, scalapay, sequra, sezzle, splitit, sunbit, tabby, tamara, zip, card_installments_three, card_installments_six, card_installments_twelve, oney_3x, oney_4x, klarna_pay_now, us_bank_account, sepa_debit, bacs_debit, au_becs_debit, acss_debit, pay_by_bank, payto, paypal, cashapp, venmo, amazon_pay, link, wechat_pay

string | null

required

Why pending funds without a settlement date aren’t moving yet. kyc_incomplete, pending_information_request, and update_payout_profile are things the merchant can act on. compliance_review means a verification the merchant already submitted is being reviewed, so these funds stay pending until it clears. withdrawals_disabled means Whop has blocked withdrawals, so these funds cannot become available. null when there’s no reason to show — still clearing, or held for a reason that isn’t named here.Available options: kyc_incomplete, pending_information_request, update_payout_profile, compliance_review, withdrawals_disabled

object

required

How the account’s balance automatically withdraws.

Properties

integer | null

required

Day the automatic withdrawal runs on: 0-6 (Sunday-Saturday) for weekly, 1-31 for monthly. null for manual and daily.

string

required

How often the account’s balance automatically withdraws.Available options: manual, daily, weekly, monthly

string | null

required

Next date the automatic withdrawal is scheduled to run, as an ISO 8601 date. null for manual and daily, where no single next date applies.

object | null

required

The account’s default payment methods at checkout. A variant’s or checkout configuration’s own payment_method_configuration takes precedence. null when the account uses Whop’s platform defaults.

Properties

string[]

required

Payment methods this checkout withholds, even when the defaults would offer them.

string[]

required

Payment methods this checkout offers on top of whatever the defaults provide.

boolean

required

Whether Whop’s default set is the starting point. When false, only enabled is offered.

object[]

required

Whop-issued platform credits per currency, read from the balance cache. Credits can only be spent on eligible Whop products such as Whop Ads, can never be withdrawn, and are not included in balances or total_usd. Empty when the account holds none or total_usd is null.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object | null

required

The account’s privacy policy document, or null if they have not published one.

Properties

string

required

The file’s ID, prefixed file_.

string | null

required

BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.

string | null

required

The original file’s MIME type, for example application/pdf. It is kept when moderation removes the file.

string

required

When the file was created, as an ISO 8601 timestamp.

number | null

required

Audio or video duration in seconds. Null when unavailable or removed by moderation.

string | null

required

The original filename, including its extension.

integer | null

required

Image or video height in pixels. Null when unavailable or removed by moderation.

integer | null

The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.

string | null

The ID of the multipart upload, passed back to complete. Present only on create, and only for multipart uploads.

object[] | null

The presigned URL for each part. Present only on create, and only for multipart uploads.

Properties

integer

required

The 1-based index of this part within the multipart upload.

string

required

The presigned URL to PUT this part’s bytes to.

string

required

The type of this object, always file.

boolean

required

Whether moderation removed the file. When true, url serves a replacement image. filename, size and content_type still describe the original file.

integer | null

required

The file size in bytes. null until the upload has finished.

object

Headers to send with the upload PUT. Present only on create.

string

required

Where the file is in its upload lifecycle.Available options: pending, processing, ready, failed

string | null

Presigned URL to PUT the file’s bytes to. Present only on create, and only for single-part uploads.

string | null

required

string

required

public files are served from an unsigned CDN URL. private files are served from a signed URL that expires.Available options: public, private

string | null

required

Audio waveform URL. Null when unavailable or removed by moderation.

integer | null

required

Image or video width in pixels. Null when unavailable or removed by moderation.

object | null

required

Tax classification code applied by default to the account’s products, with id, name, and product_type. null when no default is set.

object[] | null

required

DEPRECATED: Use the GET /economic_intelligence?account_id=\{account_id} endpoint instead.

Properties

string

required

The recommendation; new values may be added, so handle unknown actions gracefullyAvailable options: theme_business, create_product, create_plan, verify_identity, connect_affiliate_program, create_promotion, migrate_from_stripe, accept_first_payment, launch_first_ad, launch_draft_campaign, increase_ad_budget, refresh_ad_creatives, fix_ad_billing, exclude_customers_from_ads, retarget_abandoned_checkouts, fix_funnel_dropoff, invite_team_member, enable_tax_collection, create_card, apply_for_financing

string[]

required

Capabilities this would unlock, or empty

string

required

The URL the call-to-action links to

string

required

Button label

string

required

Supporting copy, or empty

string | null

required

Illustration icon URL, or null

integer | null

required

Estimated impact from 0-100, or null when not ranked

string | null

required

Why this action was recommended, or null

string

required

Always optional — never blockingAvailable options: optional

string

required

Headline for the recommendation

boolean

required

Whether authorized users must enable two-factor authentication.

object[] | null

required

Actions the account owner must take to unblock capabilities like payouts and card spend, ordered by display priority. Computed only on retrieve and me for callers with company:balance:read scope; null otherwise.

Properties

string

required

What the holder must do; new values may be added, so handle unknown actions gracefullyAvailable options: deposit_funds, review_held_payments, submit_information_request, update_automatic_withdrawal_method, reauthorize_payout_methods, update_payout_method, update_payout_profile, card_usage_review, verify_identity, scale_account_setup, sign_formation_documents, configure_tax_remitter, add_vat_registration, confirm_tax_details, accept_payout_terms, enable_two_factor_authentication, respond_to_abuse_report

string[]

required

Capabilities gated until this is resolved

string | null

required

The URL the call-to-action links to, or null when there is no button

string

required

Button label, or empty when there is no button

string

required

Supporting copy, or empty

string | null

required

The URL of the action’s illustration icon, or null if it has none

string

required

required (act now) or pending (under review)Available options: required, pending

string

required

Headline for the action

object | null

required

The account’s return policy document, or null if they have not published one.

Properties

string

required

The file’s ID, prefixed file_.

string | null

required

BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.

string | null

required

The original file’s MIME type, for example application/pdf. It is kept when moderation removes the file.

string

required

When the file was created, as an ISO 8601 timestamp.

number | null

required

Audio or video duration in seconds. Null when unavailable or removed by moderation.

string | null

required

The original filename, including its extension.

integer | null

required

Image or video height in pixels. Null when unavailable or removed by moderation.

integer | null

The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.

string | null

The ID of the multipart upload, passed back to complete. Present only on create, and only for multipart uploads.

object[] | null

The presigned URL for each part. Present only on create, and only for multipart uploads.

Properties

integer

required

The 1-based index of this part within the multipart upload.

string

required

The presigned URL to PUT this part’s bytes to.

string

required

The type of this object, always file.

boolean

required

Whether moderation removed the file. When true, url serves a replacement image. filename, size and content_type still describe the original file.

integer | null

required

The file size in bytes. null until the upload has finished.

object

Headers to send with the upload PUT. Present only on create.

string

required

Where the file is in its upload lifecycle.Available options: pending, processing, ready, failed

string | null

Presigned URL to PUT the file’s bytes to. Present only on create, and only for single-part uploads.

string | null

required

string

required

public files are served from an unsigned CDN URL. private files are served from a signed URL that expires.Available options: public, private

string | null

required

Audio waveform URL. Null when unavailable or removed by moderation.

integer | null

required

Image or video width in pixels. Null when unavailable or removed by moderation.

object[]

Business rewards attached through this account’s active referral link, with account-specific progress and ledger status. Present on retrieve responses; empty without both balance and stats read access.

Properties

string

required

Reward definition ID, prefixed prwd_. Progress and status apply to the containing account.

object

required

Qualifying USD volume required to earn this reward.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

Qualifying USD volume for the reward’s activity accumulated by this account since attribution, calculated using the fulfillment rules.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

string

required

Activity that qualifies this account for the reward.Available options: sales, ad_spend

object

required

USD amount credited for this reward. Uses the saved grant amount once fulfillment has started.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

string

required

This account’s reward state. Credited requires a posted ledger entry; processing includes a met requirement awaiting fulfillment. Reversing and reversed reflect a subsequent reward reversal.Available options: in_progress, processing, credited, reversing, reversed, unavailable

string

required

Account public route identifier.

boolean

required

Whether Whop sends transactional emails to customers on behalf of this account.

object | null

required

The account’s shipping policy document, or null if they have not published one.

Properties

string

required

The file’s ID, prefixed file_.

string | null

required

BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.

string | null

required

The original file’s MIME type, for example application/pdf. It is kept when moderation removes the file.

string

required

When the file was created, as an ISO 8601 timestamp.

number | null

required

Audio or video duration in seconds. Null when unavailable or removed by moderation.

string | null

required

The original filename, including its extension.

integer | null

required

Image or video height in pixels. Null when unavailable or removed by moderation.

integer | null

The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.

string | null

The ID of the multipart upload, passed back to complete. Present only on create, and only for multipart uploads.

object[] | null

The presigned URL for each part. Present only on create, and only for multipart uploads.

Properties

integer

required

The 1-based index of this part within the multipart upload.

string

required

The presigned URL to PUT this part’s bytes to.

string

required

The type of this object, always file.

boolean

required

Whether moderation removed the file. When true, url serves a replacement image. filename, size and content_type still describe the original file.

integer | null

required

The file size in bytes. null until the upload has finished.

object

Headers to send with the upload PUT. Present only on create.

string

required

Where the file is in its upload lifecycle.Available options: pending, processing, ready, failed

string | null

Presigned URL to PUT the file’s bytes to. Present only on create, and only for single-part uploads.

string | null

required

string

required

public files are served from an unsigned CDN URL. private files are served from a signed URL that expires.Available options: public, private

string | null

required

Audio waveform URL. Null when unavailable or removed by moderation.

integer | null

required

Image or video width in pixels. Null when unavailable or removed by moderation.

boolean

required

Whether the account appears in joined whops on other accounts.

boolean

required

Whether reviews are displayed on direct-to-consumer product pages.

boolean

required

Whether the account shows users in the user directory.

Account social links.

Properties

string

required

The ID of the social link

string | null

required

The optional display title for the social link

string

required

The social link URL

string

required

The social platform for this linkAvailable options: x, instagram, facebook, tiktok, youtube, linkedin, twitch, website, custom

string | null

required

Whether the account can operate on Whop: active or suspended. Computed on list, retrieve, me, and suspend; null otherwise.

string | null

required

Why the account was suspended, as the label shown to the account owner, such as Suspended - Fraudulent activity. Computed on retrieve, me, and suspend; null otherwise, when status is not suspended, and when the suspension was recorded without a reason.

object

required

Account store page display configuration.

Properties

string | null

required

Accent color used on the account store page.Available options: ruby, tomato, red, crimson, pink, plum, purple, violet, iris, cyan, teal, jade, green, grass, brown, blue, orange, indigo, sky, mint, yellow, amber, lime, lemon, magenta, gold, bronze, gray

string | null

required

Layout used on the account store page.Available options: featured, compact

string | null

required

Profile presentation used on the account store page.Available options: personal, business

boolean

required

Whether the account store page shows a Whop affiliate link.

string | null

required

Target audience for this account.

string[]

required

US state codes (of the 50 states plus DC) where the account collects tax: the full set when Whop remits (tax_remitted_by whop), the configured subset when the account self-remits (self), and empty when neither. On update, send the complete list to replace it (only allowed when self).

object[]

required

Account tax/VAT registrations. Empty when none are set.

Properties

string

required

Tax identifier ID.

string

required

Tax ID type.Available options: ad_nrt, ao_tin, ar_cuit, al_tin, am_tin, aw_tin, au_abn, au_arn, eu_vat, az_tin, bs_tin, bh_vat, bd_bin, bb_tin, by_tin, bj_ifu, bo_tin, ba_tin, br_cnpj, br_cpf, bg_uic, bf_ifu, kh_tin, cm_niu, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, cv_nif, cl_tin, cn_tin, co_nit, cd_nif, cr_tin, hr_oib, do_rcn, ec_ruc, eg_tin, sv_nit, et_tin, eu_oss_vat, ge_vat, gh_tin, de_stn, gb_vat, gn_nif, hk_br, hu_tin, is_vat, in_gst, id_npwp, il_vat, jp_cn, jp_rn, jp_trn, kz_bin, ke_pin, kg_tin, la_tin, li_uid, li_vat, my_frp, my_itn, my_sst, mr_nif, mx_rfc, md_vat, me_pib, ma_vat, np_pan, nz_gst, ng_tin, mk_vat, no_vat, no_voec, om_vat, pe_ruc, ph_tin, pl_nip, ro_tin, ru_inn, ru_kpp, sa_vat, sn_ninea, rs_pib, sg_gst, sg_uen, si_tin, za_vat, kr_brn, es_cif, ch_uid, ch_vat, tw_vat, tj_tin, tz_vat, th_vat, tr_tin, ug_tin, ua_vat, ae_trn, us_ein, uy_ruc, uz_tin, uz_vat, ve_rif, vn_tin, zm_tin, zw_tin, sr_fin, xi_vat

string

required

Tax ID value, for example DE123456789. See the tax IDs guide.

string | null

required

Who calculates and remits tax for the account. whop means Whop calculates and remits. self means Whop calculates, and the account collects and remits. none means neither, and the account is responsible. New businesses start on whop, and new connected accounts start on none. null means the account has no setting yet.Available options: whop, self, none

string | null

required

How tax is applied to the account’s prices: inclusive (tax included in the listed price) or exclusive (tax added on top). Defaults to exclusive when unset; null only when the account has no payment connection.Available options: inclusive, exclusive

object | null

required

The account’s terms of service document, or null if they have not published one.

Properties

string

required

The file’s ID, prefixed file_.

string | null

required

BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.

string | null

required

The original file’s MIME type, for example application/pdf. It is kept when moderation removes the file.

string

required

When the file was created, as an ISO 8601 timestamp.

number | null

required

Audio or video duration in seconds. Null when unavailable or removed by moderation.

string | null

required

The original filename, including its extension.

integer | null

required

Image or video height in pixels. Null when unavailable or removed by moderation.

integer | null

The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.

string | null

The ID of the multipart upload, passed back to complete. Present only on create, and only for multipart uploads.

object[] | null

The presigned URL for each part. Present only on create, and only for multipart uploads.

Properties

integer

required

The 1-based index of this part within the multipart upload.

string

required

The presigned URL to PUT this part’s bytes to.

string

required

The type of this object, always file.

boolean

required

Whether moderation removed the file. When true, url serves a replacement image. filename, size and content_type still describe the original file.

integer | null

required

The file size in bytes. null until the upload has finished.

object

Headers to send with the upload PUT. Present only on create.

string

required

Where the file is in its upload lifecycle.Available options: pending, processing, ready, failed

string | null

Presigned URL to PUT the file’s bytes to. Present only on create, and only for single-part uploads.

string | null

required

string

required

public files are served from an unsigned CDN URL. private files are served from a signed URL that expires.Available options: public, private

string | null

required

Audio waveform URL. Null when unavailable or removed by moderation.

integer | null

required

Image or video width in pixels. Null when unavailable or removed by moderation.

string | null

required

3D Secure behavior for supported on-session card payments. mandate_challenge requires a 3DS challenge before payment processing; mandate_if_required mandates a challenge only when the payment processor requires it; frictionless_if_required uses the regular frictionless 3DS flow. Payments of $1,000 or more use mandate_if_required unless mandate_challenge is selected. Risk and authentication recovery requirements can override the preference. null uses the standard checkout flow.Available options: mandate_challenge, mandate_if_required, frictionless_if_required

string

required

Account display name.

number | null

required

Account lifetime sales, normalized to USD. Computed only on retrieve and me for callers with stats:read scope; null otherwise.

string | null

required

Total USD value across balances with known exchange rates. Computed only on single-account reads (retrieve and me); null on list responses, writes, missing balance-read permission, or unavailable balance source.

trading_account | null

required

The trading account address, a snapshot of its margin and open positions, and its WebSocket subscriptions. Opt in with include_trading=true on single-account reads. null otherwise, without trading permission, or without an Ethereum wallet.

Properties

string

required

The Whop wallet ID backing this trading account, prefixed cwal_.

string | null

required

The account that owns this trading account, prefixed biz_. null when a user owns it.

object | null

required

Hyperliquid-specific state. Present when provider is hyperliquid, otherwise null.

Properties

string

required

Lowercase wallet address that holds the Hyperliquid account.

string | null

required

USDT0 in the Whop wallet on Plasma that a deposit trade can move into this account, as a decimal string. null when the chain could not be read.

object | null

required

Account value and margin across the main exchange and the xyz markets, read from Hyperliquid at most once a second. null when Hyperliquid could not be read. Use websocket_subscriptions for live updates.

Properties

object

required

Total account value in USD, including unrealized profit and loss.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

Margin allocated across open positions, in USD.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

Combined notional value of open positions, in USD.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

USD that can be withdrawn now without closing positions.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

trading_position[] | null

required

Open perpetual positions across the main exchange and the xyz markets, read from Hyperliquid at most once a second. null when Hyperliquid could not be read. Use websocket_subscriptions for live updates.

Properties

string

required

Trading position ID, prefixed trdpos_. Stable for a market within one trading account.

object | null

required

Average entry price in USD, or null when the provider omits it.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object | null

required

Hyperliquid perpetual details. Present on Hyperliquid positions, otherwise null.

Properties

object

required

Funding paid on the position over several windows, in USD.

Properties

object | null

required

Funding paid on this market across the account’s history, in USD, or null when unavailable.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object | null

required

Funding paid since the position size last changed, in USD, or null when unavailable.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object | null

required

Funding paid since the position opened, in USD, or null when unavailable.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

Margin mode and multiplier for the position.

Properties

string

required

cross shares margin across positions. isolated limits margin to this position.Available options: cross, isolated

integer

required

Multiplier applied to the position’s margin, such as 10 for 10x.

object | null

required

Estimated liquidation price in USD, or null when Hyperliquid reports none.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

Margin allocated to the position, in USD.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

string

required

Return on equity as a decimal ratio string, such as 0.1 for 10%.

string

required

Market symbol on the provider, such as ETH.

string

required

object

required

Current position value in USD.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

string

required

Available options: long, short

string

required

Absolute position size as a decimal string.

object

required

Unrealized profit or loss in USD. Negative for a loss.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object[]

required

Subscriptions for live account updates. Send each message unchanged after connecting to websocket_url.

Properties

string

required

The live update stream this subscription opens.Available options: clearinghouse_state, open_orders, order_updates, user_fills, user_events

string

required

JSON subscription message to send unchanged over the Hyperliquid WebSocket.

string

required

Hyperliquid WebSocket URL to connect to directly for live updates.

string

required

string

required

Trading venue that holds the positions and orders.Available options: hyperliquid

object | null

required

Spot holdings in the Whop wallet with their entry price and profit and loss. null when it could not be read.

Properties

object[]

required

Each spot asset the wallet still holds, with its average entry price and profit and loss. Cost basis counts the oldest units as sold first and includes assets that arrived from outside Whop.

Properties

object | null

required

The average price paid per unit of what is still held, in USD, counting the oldest units as sold first. null when it is not known.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

What was paid in USD for the units still held.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

string

required

The spot market’s id from GET /trades/markets, such as BTC, XAUT, or a tokenized stock’s ticker such as AAPL.

object

required

Gains and losses already locked in by selling, in USD.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

object

required

The value of the units still held minus their cost_basis, in USD.

Properties

string

required

The amount in major units, as an exact decimal string. For example, "10.00" is ten dollars. It is a string so that no float rounds it in transit.

string

required

Three-letter ISO 4217 currency code, lowercase.

integer

required

How many decimal places the amount carries. This is the precision the charge itself runs at.

integer

required

number | null

required

unrealized_pnl as a percentage of cost_basis, where 2 means up 2%. null when it is not known.

string | null

required

The user who owns this trading account, prefixed user_. null when an account owns it.

boolean

required

Whether the account uses its logo as the fallback Open Graph image.

object

required

Account identity verification status for the individual (KYC) and business (KYB) profiles. Each is null until created, otherwise a status of not_started, pending, manual_review, approved, or rejected.

number | null

required

Volume through the account in the last 30 days (GMV from paid receipts), normalized to USD. Computed only on list for callers with stats:read on the account; null otherwise.

number | null

required

Lifetime volume through the account — sales plus transfers received — normalized to USD. Computed only on list for callers with stats:read on the account; null otherwise.

object | null

required

Account primary crypto wallet, or null if none has been provisioned.

Properties

string

required

Wallet ID, prefixed wallet_.

string

required

The on-chain address of the wallet

string

required

The blockchain network the wallet lives onAvailable options: solana, ethereum, bitcoin

string | null

required

The account’s business website URL, or null if none has been provided. Setting it also adds a website entry to social_links.

string | null

When the account turned on Whop Partner mode, as an ISO 8601 timestamp. Present on single-account reads and update responses; null until the account turns Whop Partner mode on by sending whop_partner_enabled: true on update.

Account

{
	"id": "biz_xxxxxxxxxxxxx",
	"trading": {
		"id": "cwal_xxxxxxxxxxxxx",
		"object": "trading_account",
		"account_id": "biz_xxxxxxxxxxxxx",
		"user_id": null,
		"provider": "hyperliquid",
		"hyperliquid": {
			"address": "0x1234567890abcdef1234567890abcdef12345678",
			"websocket_url": "wss://api.hyperliquid.xyz/ws",
			"websocket_subscriptions": [
				{
					"channel": "clearinghouse_state",
					"message": "{\"method\":\"subscribe\",\"subscription\":{\"type\":\"clearinghouseState\",\"user\":\"0x1234567890abcdef1234567890abcdef12345678\"}}"
				},
				{
					"channel": "open_orders",
					"message": "{\"method\":\"subscribe\",\"subscription\":{\"type\":\"openOrders\",\"user\":\"0x1234567890abcdef1234567890abcdef12345678\"}}"
				},
				{
					"channel": "order_updates",
					"message": "{\"method\":\"subscribe\",\"subscription\":{\"type\":\"orderUpdates\",\"user\":\"0x1234567890abcdef1234567890abcdef12345678\"}}"
				},
				{
					"channel": "user_fills",
					"message": "{\"method\":\"subscribe\",\"subscription\":{\"type\":\"userFills\",\"user\":\"0x1234567890abcdef1234567890abcdef12345678\"}}"
				},
				{
					"channel": "user_events",
					"message": "{\"method\":\"subscribe\",\"subscription\":{\"type\":\"userEvents\",\"user\":\"0x1234567890abcdef1234567890abcdef12345678\"}}"
				}
			],
			"depositable": "1250.50",
			"margin_summary": {
				"account_value": {
					"currency": "usd",
					"amount": "1520.50",
					"decimals": 2,
					"display_decimals": 2
				},
				"total_position_notional": {
					"currency": "usd",
					"amount": "4350.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"total_margin_used": {
					"currency": "usd",
					"amount": "435.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"withdrawable": {
					"currency": "usd",
					"amount": "500.00",
					"decimals": 2,
					"display_decimals": 2
				}
			},
			"positions": [
				{
					"id": "trdpos_0123456789abcdef",
					"object": "trading_position",
					"market": "ETH",
					"side": "short",
					"size": "1.5",
					"entry_price": {
						"currency": "usd",
						"amount": "3000.00",
						"decimals": 2,
						"display_decimals": 2
					},
					"position_value": {
						"currency": "usd",
						"amount": "4350.00",
						"decimals": 2,
						"display_decimals": 2
					},
					"unrealized_pnl": {
						"currency": "usd",
						"amount": "150.25",
						"decimals": 2,
						"display_decimals": 2
					},
					"hyperliquid": {
						"leverage": {
							"type": "cross",
							"value": 10
						},
						"liquidation_price": {
							"currency": "usd",
							"amount": "4912.40",
							"decimals": 2,
							"display_decimals": 2
						},
						"margin_used": {
							"currency": "usd",
							"amount": "435.00",
							"decimals": 2,
							"display_decimals": 2
						},
						"return_on_equity": "0.33",
						"cumulative_funding": {
							"all_time": {
								"currency": "usd",
								"amount": "1.20",
								"decimals": 2,
								"display_decimals": 2
							},
							"since_open": {
								"currency": "usd",
								"amount": "0.40",
								"decimals": 2,
								"display_decimals": 2
							},
							"since_change": {
								"currency": "usd",
								"amount": "0.10",
								"decimals": 2,
								"display_decimals": 2
							}
						}
					}
				}
			]
		},
		"spot": {
			"holdings": [
				{
					"market": "BTC",
					"average_entry_price": {
						"currency": "usd",
						"amount": "79841.12345678",
						"decimals": 8,
						"display_decimals": 8
					},
					"cost_basis": {
						"currency": "usd",
						"amount": "400.00",
						"decimals": 2,
						"display_decimals": 2
					},
					"unrealized_pnl": {
						"currency": "usd",
						"amount": "38.25",
						"decimals": 2,
						"display_decimals": 2
					},
					"unrealized_pnl_percentage": 9.5625,
					"realized_pnl": {
						"currency": "usd",
						"amount": "3.25",
						"decimals": 2,
						"display_decimals": 2
					}
				}
			]
		}
	},
	"balances": [
		{
			"balance": "1250.5",
			"breakdown": {
				"available": "1200.50",
				"in_transit": "0",
				"pending": "50.00",
				"reserve": "0",
				"pending_settlements": [
					{
						"amount": "50.00",
						"date": "2026-08-01"
					}
				],
				"finishing_settlement": "0"
			},
			"icon_url": "https://cdn.whop.com/tokens/usdt.png",
			"name": "Tether USD",
			"price_usd": 1,
			"symbol": "USDT",
			"value_usd": "1250.50"
		},
		{
			"balance": "45.00",
			"breakdown": {
				"available": "40.00",
				"in_transit": "0",
				"pending": "5.00",
				"reserve": "0",
				"pending_settlements": [
					{
						"amount": "3.00",
						"date": "2026-08-01"
					},
					{
						"amount": "2.00",
						"date": "2026-08-04"
					}
				],
				"finishing_settlement": "0"
			},
			"icon_url": null,
			"name": "EUR",
			"price_usd": 1.11,
			"symbol": "EUR",
			"value_usd": "50.00"
		}
	],
	"platform_credits": [
		{
			"amount": "25.00",
			"currency": "usd",
			"decimals": 2,
			"display_decimals": 2
		}
	],
	"banner_image_url": "https://cdn.whop.com/banner.png",
	"business_type": "ecommerce",
	"can_transfer_pending_balance_to_children": false,
	"cancellation_policy": null,
	"country": "US",
	"created_at": "2026-06-01T12:00:00Z",
	"description": "Petal Post delivers fresh bouquets.",
	"economic_intelligence": false,
	"email": "hello@petalpost.example",
	"eula": null,
	"external_id": null,
	"home_preferences": ["hide_member_count"],
	"industry_type": "flower_delivery_gig",
	"invoice_prefix": "PETAL",
	"company_formation": {
		"status": "filed",
		"legal_name": "Petal Post, LLC",
		"state_registered": true,
		"ein_registered": false,
		"signatures": {
			"ss4": {
				"status": "pending",
				"url": "https://esign.doola.com/session/sess_1a2b3c",
				"expires_at": "2026-08-01T00:00:00Z"
			}
		},
		"documents": [
			{
				"id": "file_petalpost123",
				"name": "Articles of Organization",
				"type": "articles_of_organization",
				"url": "https://img.whop.com/documents/articles-of-organization.pdf"
			}
		]
	},
	"logo_url": "https://cdn.whop.com/logo.png",
	"metadata": {
		"external_merchant_id": "merchant_123"
	},
	"onboarding_type": "seller",
	"opengraph_image_url": "https://cdn.whop.com/og.png",
	"opengraph_image_variant": "black",
	"other_business_description": "Local flower delivery",
	"other_industry_description": "Same-day floral gifts",
	"owner": {
		"id": "user_xxxxxxxxxxxx",
		"username": "petalpost",
		"name": "Ada Flores",
		"profile_picture": {
			"url": "https://cdn.whop.com/user.png"
		}
	},
	"parent_account": {
		"id": "biz_platform123",
		"title": "Petal Platform",
		"route": "petal-platform",
		"logo_url": "https://cdn.whop.com/petal-platform-logo.png"
	},
	"privacy_policy": null,
	"require_2fa": true,
	"dispute_fighter_enabled": false,
	"orchestration_enabled": true,
	"collect_vat_id": false,
	"capabilities": {
		"accept_card_payments": "active",
		"accept_bank_payments": "active",
		"accept_bnpl_payments": "inactive",
		"standard_payout": "inactive",
		"instant_payout": "inactive",
		"crypto_payout": "inactive",
		"transfer": "inactive",
		"bank_deposit": "active",
		"crypto_deposit": "active",
		"card_deposit": "active",
		"card_issuing": "inactive",
		"run_ads": "active"
	},
	"payment_controls": {
		"dispute_alert_auto_refund": {
			"threshold_usd": 250,
			"locked": false
		},
		"resolution_center_auto_refund": {
			"card_threshold_usd": null,
			"financing_threshold_usd": null,
			"paypal_threshold_usd": null,
			"locked": false
		},
		"dispute_alert_fee_usd": 29,
		"high_risk_processing_fee_percentage": 0,
		"pending_auto_topup_fee_percentage": 2,
		"pending_balance_delay_days": 0,
		"financing_disabled": false,
		"enforce_3ds": false,
		"restricted_payment_methods": [],
		"payment_method_warnings": [],
		"reserve": {
			"percentage": null,
			"hold_period_days": 90
		},
		"withdrawal_schedule": {
			"frequency": "monthly",
			"day": 1,
			"next_payout_date": "2026-09-01"
		},
		"undated_pending_reason": null
	},
	"cards": {
		"kind": "business",
		"status": "approved"
	},
	"financing": null,
	"required_actions": [
		{
			"action": "verify_identity",
			"status": "required",
			"title": "Identity verification required",
			"description": "Complete verification before your total earnings exceed $5k to continue accepting payments.",
			"cta_label": "Verify now",
			"cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxx/balance/?verify=true",
			"icon_url": null,
			"blocked_capabilities": [
				"accept_card_payments",
				"accept_bank_payments",
				"standard_payout",
				"instant_payout",
				"crypto_payout",
				"transfer",
				"bank_deposit",
				"card_issuing"
			]
		}
	],
	"recommended_actions": [
		{
			"action": "migrate_from_stripe",
			"status": "optional",
			"title": "Migrate your business from Stripe.",
			"description": "",
			"cta_label": "Get started",
			"cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxx/settings/stripe-migrations/",
			"icon_url": "https://whop.com/illustrations/orange/crane.svg",
			"blocked_capabilities": [],
			"reasoning": null,
			"impact_score": null
		},
		{
			"action": "accept_first_payment",
			"status": "optional",
			"title": "Accept your first payment.",
			"description": "",
			"cta_label": "Create payment link",
			"cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxx/links/checkout/create/",
			"icon_url": "https://whop.com/illustrations/orange/card.svg",
			"blocked_capabilities": [],
			"reasoning": null,
			"impact_score": null
		},
		{
			"action": "apply_for_financing",
			"status": "optional",
			"title": "Offer financing at checkout",
			"description": "Let customers pay over time with buy now, pay later.",
			"cta_label": "Apply",
			"cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxx/settings/payments/",
			"icon_url": "https://whop.com/illustrations/orange/piggy-bank.svg",
			"blocked_capabilities": ["accept_bnpl_payments"],
			"reasoning": null,
			"impact_score": null
		}
	],
	"return_policy": null,
	"route": "petal-post",
	"shipping_policy": null,
	"website": "https://petalpost.example",
	"send_customer_emails": true,
	"payment_method_configuration": {
		"enabled": ["klarna"],
		"disabled": ["crypto"],
		"include_platform_defaults": true
	},
	"show_joined_whops": false,
	"show_reviews_dtc": true,
	"show_user_directory": false,
	"status": "active",
	"status_reason": null,
	"funds_release_at": null,
	"terms_of_service": null,
	"three_ds_level": "mandate_challenge",
	"total_earned_usd": 3450,
	"ads_spend_usd": 180.25,
	"volume_usd": 4250.5,
	"volume_l30d_usd": 1200,
	"customers_l30d": 24,
	"level": {
		"applied_level": 1,
		"points": 41000,
		"points_by_source": {
			"cards": 40000,
			"ads": 0,
			"trading": 1000,
			"partners": 0
		},
		"points_to_next": 59000,
		"resets_at": "2026-11-01T04:00:00.000Z",
		"monthly_qualifying_spend": {
			"currency": "usd",
			"amount": "4100.00",
			"decimals": 2,
			"display_decimals": 2
		},
		"monthly_ads_spend": {
			"currency": "usd",
			"amount": "0.00",
			"decimals": 2,
			"display_decimals": 2
		},
		"monthly_card_spend": {
			"currency": "usd",
			"amount": "4000.00",
			"decimals": 2,
			"display_decimals": 2
		},
		"monthly_trading_volume": {
			"currency": "usd",
			"amount": "1000.00",
			"decimals": 2,
			"display_decimals": 2
		},
		"levels": [
			{
				"level": 0,
				"minimum_spend": {
					"currency": "usd",
					"amount": "0.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 2.7,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 2.7
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 2.7
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 2.9
					},
					{
						"region": "peru",
						"processing_rate_percentage": 4.9
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 8
					}
				]
			},
			{
				"level": 1,
				"minimum_spend": {
					"currency": "usd",
					"amount": "500.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 2.6,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 2.6
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 2.2
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 2.8
					},
					{
						"region": "peru",
						"processing_rate_percentage": 4.7
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 7.7
					}
				]
			},
			{
				"level": 2,
				"minimum_spend": {
					"currency": "usd",
					"amount": "10000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 2.4,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 2.4
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 1.7
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 2.6
					},
					{
						"region": "peru",
						"processing_rate_percentage": 4.4
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 7.2
					}
				]
			},
			{
				"level": 3,
				"minimum_spend": {
					"currency": "usd",
					"amount": "50000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 2.1,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 2.1
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 1.4
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 2.3
					},
					{
						"region": "peru",
						"processing_rate_percentage": 3.9
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 6.6
					}
				]
			},
			{
				"level": 4,
				"minimum_spend": {
					"currency": "usd",
					"amount": "100000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 1.8,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 1.8
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 1.1
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 2
					},
					{
						"region": "peru",
						"processing_rate_percentage": 3.4
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 6
					}
				]
			},
			{
				"level": 5,
				"minimum_spend": {
					"currency": "usd",
					"amount": "250000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 1.5,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 1.5
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 0.9
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 1.7
					},
					{
						"region": "peru",
						"processing_rate_percentage": 3
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 5.4
					}
				]
			},
			{
				"level": 6,
				"minimum_spend": {
					"currency": "usd",
					"amount": "1000000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 1.2,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 1.2
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 0.7
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 1.4
					},
					{
						"region": "peru",
						"processing_rate_percentage": 2.6
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 4.8
					}
				]
			},
			{
				"level": 7,
				"minimum_spend": {
					"currency": "usd",
					"amount": "3000000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 0.9,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 0.9
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 0.5
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 1.1
					},
					{
						"region": "peru",
						"processing_rate_percentage": 2.2
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 4.2
					}
				]
			},
			{
				"level": 8,
				"minimum_spend": {
					"currency": "usd",
					"amount": "5000000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 0.6,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 0.6
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 0.3
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 0.8
					},
					{
						"region": "peru",
						"processing_rate_percentage": 1.9
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 3.8
					}
				]
			},
			{
				"level": 9,
				"minimum_spend": {
					"currency": "usd",
					"amount": "7500000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 0.3,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 0.3
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 0.15
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 0.5
					},
					{
						"region": "peru",
						"processing_rate_percentage": 1.7
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 3.4
					}
				]
			},
			{
				"level": 10,
				"minimum_spend": {
					"currency": "usd",
					"amount": "10000000.00",
					"decimals": 2,
					"display_decimals": 2
				},
				"processing_rate_percentage": 0,
				"regional_rates": [
					{
						"region": "us_and_canada",
						"processing_rate_percentage": 0
					},
					{
						"region": "europe_uk_and_australia",
						"processing_rate_percentage": 0
					},
					{
						"region": "latin_america",
						"processing_rate_percentage": 0.2
					},
					{
						"region": "peru",
						"processing_rate_percentage": 1.5
					},
					{
						"region": "brazil",
						"processing_rate_percentage": 3
					}
				]
			}
		],
		"boosted": true,
		"account_level": 0
	},
	"social_links": [
		{
			"id": "social_petalpost123",
			"title": "Petal Post",
			"url": "https://petalpost.example",
			"website": "website"
		}
	],
	"store_page_config": {
		"accent_color": "red",
		"layout": "compact",
		"profile_variant": "business",
		"whop_affiliate_link": true
	},
	"target_audience": "Customers sending flowers locally",
	"tax_collection_enabled_states": ["CA", "NY"],
	"tax_remitted_by": "whop",
	"tax_type": "exclusive",
	"product_tax_code": {
		"id": "ptc_CzLNn2Z058xEC1",
		"name": "Digital Group Chat",
		"product_type": "digital"
	},
	"business_address": {
		"line1": "123 Garden Way",
		"line2": null,
		"city": "Austin",
		"state": "TX",
		"postal_code": "78701",
		"country": "US"
	},
	"business_name": "Petal Post, LLC",
	"tax_identifiers": [
		{
			"id": "taxid_petalpost123",
			"tax_id_type": "us_ein",
			"tax_id_value": "12-3456789"
		}
	],
	"title": "Petal Post",
	"total_usd": "1300.50",
	"use_logo_as_opengraph_image_fallback": true,
	"verification": {
		"business": null,
		"individual": {
			"status": "approved"
		}
	},
	"wallet": {
		"id": "wallet_petalpost123",
		"address": "So11111111111111111111111111111111111111112",
		"network": "solana"
	}
}

Business types and industries

Three fields classify accounts: business_type, industry_group, and industry_type. The full taxonomy lives on its own page:

Introduction

Reference

Core Resources

Payments

Money

Commerce

Websites

Ads

Analytics

Communication

Partners

Workforce

Media

Developer

Endpoints

Fee markups

Fee endpoints

Read fees

Set platform defaults

Set a Subaccount override

Clear a markup

Legal documents

Attributes

Business types and industries

Business types and industries