{ "components": { "parameters": { "AdsPlatform": { "description": "The platform returned when you last retrieved the campaign, ad group, or ad. A different current platform rejects the request with campaign_changed; retrieve the resource again before editing. Required after a delivery-platform migration when creating ads or ad groups, or changing fields other than title, status, budget, and account scope.", "in": "header", "name": "X-Ads-Platform", "required": false, "schema": { "enum": [ "meta", "google", "tiktok" ], "type": "string" } }, "ApiVersionDate": { "description": "Pins the request to a dated API version.", "in": "header", "name": "Api-Version-Date", "required": false, "schema": { "example": "2026-10-27-3", "type": "string" } }, "IdempotencyKey": { "description": "A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency).", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "example": "d9105228-4a08-46b1-8b91-42fed586d383", "maxLength": 255, "type": "string" } } }, "responses": { "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Conflict" }, "Forbidden": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Forbidden" }, "InvalidParameters": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Invalid Parameters" }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Resource not found" }, "ServiceUnavailable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Service Unavailable" }, "TooManyRequests": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Too Many Requests" }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "Unauthorized" } }, "schemas": { "AccessLevel": { "description": "The access level a given user (or company) has to a product or company.", "enum": [ "no_access", "admin", "customer" ], "type": "string" }, "AccessPassOrder": { "description": "The ways a relation of AccessPasses can be ordered", "enum": [ "active_memberships_count", "created_at", "usd_gmv", "usd_gmv_30_days" ], "type": "string" }, "AccessPassTypes": { "description": "The different types an product can be. Only use 'regular'. The rest are for internal use", "enum": [ "regular", "app", "experience_upsell", "api_only" ], "type": "string" }, "AccessToken": { "description": "A short-lived access token used to authenticate API requests on behalf of a user.", "properties": { "expires_at": { "description": "The timestamp after which this access token is no longer valid and must be refreshed.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "token": { "description": "The signed JWT access token string to include in API request Authorization headers.", "type": "string" } }, "required": [ "token", "expires_at" ], "type": "object" }, "Account": { "properties": { "ads_spend_usd": { "description": "Lifetime charged ad spend for the account, in USD. Computed only on `list` for callers with `stats:read` on the account; `null` otherwise.", "example": 0.0, "type": [ "number", "null" ] }, "balances": { "items": { "$ref": "#/components/schemas/AccountBalanceToken", "description": "Account holdings, each with USD value. Empty when `total_usd` is `null`." }, "type": "array" }, "banner_image_url": { "description": "Account banner image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "business_address": { "description": "Account business address used to calculate tax, with `line1`, `line2`, `city`, `state`, `postal_code`, and `country`. `null` when no address is set.", "example": { "city": "Austin", "country": "US", "line1": "4180 Burnet Rd", "line2": "Suite 2", "postal_code": "78756", "state": "TX" }, "type": [ "object", "null" ] }, "business_name": { "description": "The account's legal business name used with its tax address.", "example": "Shine Time Auto Detailing, LLC", "maxLength": 255, "type": [ "string", "null" ] }, "business_type": { "description": "High-level business category for the account. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "example": "software", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "can_transfer_pending_balance_to_children": { "description": "Whether pending funds may be transferred from this platform account to its connected accounts.", "example": false, "type": "boolean" }, "cancellation_policy": { "description": "The account's cancellation policy document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "capabilities": { "description": "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.", "oneOf": [ { "$ref": "#/components/schemas/AccountCapabilities" }, { "type": "null" } ] }, "cards": { "description": "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.", "oneOf": [ { "$ref": "#/components/schemas/AccountCards" }, { "type": "null" } ] }, "collect_vat_id": { "description": "Whether checkout shows a VAT/tax ID field for buyers to optionally enter. Does not require a VAT ID to purchase.", "example": false, "type": "boolean" }, "company_formation": { "$ref": "#/components/schemas/AccountCompanyFormation", "description": "Company formation state for the account, managed through [Form Company](/api-reference/beta/accounts/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." }, "country": { "description": "Country where the account is located.", "example": "us", "type": [ "string", "null" ] }, "created_at": { "description": "When the account was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "customers_l30d": { "description": "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.", "example": null, "type": [ "integer", "null" ] }, "description": { "description": "Account promotional description.", "example": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "type": [ "string", "null" ] }, "direct_reports_count": { "description": "How many team members report to the business directly, with no manager above them. Present on single-account reads.", "example": 0, "type": "integer" }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files dispute evidence for this account. Enabling it opts the account into the success fee charged on disputes it wins.", "example": false, "type": "boolean" }, "economic_intelligence": { "description": "Whether Economic Intelligence is on for the account. It turns off automatically when its committed period ends.", "example": false, "type": "boolean" }, "email": { "description": "Account owner email address.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "eula": { "description": "The account's end-user license agreement document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "financing": { "description": "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.", "oneOf": [ { "$ref": "#/components/schemas/AccountFinancing" }, { "type": "null" } ] }, "home_preferences": { "items": { "description": "Public account home page preferences.", "enum": [ "hide_member_count", "hide_members_card" ], "example": "hide_member_count", "type": "string" }, "type": "array" }, "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "industry_type": { "description": "Specific industry vertical for the account. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "example": "trading", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "invoice_prefix": { "description": "Prefix used for account invoices.", "example": "INV", "type": [ "string", "null" ] }, "level": { "description": "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.", "oneOf": [ { "$ref": "#/components/schemas/AccountLevel" }, { "type": "null" } ] }, "logo_url": { "description": "Account logo image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "description": "Arbitrary key/value metadata supplied at account creation.", "example": { "external_id": "connected_account_123" }, "type": "object" }, "onboarding_type": { "description": "Type of onboarding the account has completed.", "enum": [ "platform", "seller", null ], "example": "platform", "type": [ "string", "null" ] }, "opengraph_image_url": { "description": "Account Open Graph image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "opengraph_image_variant": { "description": "Account Open Graph image variant.", "enum": [ "white", "black", "orange", null ], "example": "black", "type": [ "string", "null" ] }, "orchestration_enabled": { "description": "Whether payment orchestration is enabled for this account.", "example": true, "type": "boolean" }, "other_business_description": { "description": "Business type details when business_type is `other`.", "example": null, "type": [ "string", "null" ] }, "other_industry_description": { "description": "Industry details when industry_type is `other`.", "example": null, "type": [ "string", "null" ] }, "owner": { "$ref": "#/components/schemas/UserSummary", "description": "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." }, "parent_account": { "description": "Parent account for connected accounts, or `null` for standalone accounts.", "oneOf": [ { "$ref": "#/components/schemas/AccountParent" }, { "type": "null" } ] }, "partner": { "description": "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.", "oneOf": [ { "$ref": "#/components/schemas/AccountPartner" }, { "type": "null" } ] }, "payment_controls": { "description": "Payment health controls currently applied to the account. Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise.", "oneOf": [ { "$ref": "#/components/schemas/AccountPaymentControls" }, { "type": "null" } ] }, "platform_credits": { "items": { "$ref": "#/components/schemas/Money", "description": "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`." }, "type": "array" }, "privacy_policy": { "description": "The account's privacy policy document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "product_tax_code": { "description": "Tax classification code applied by default to the account's products, with `id`, `name`, and `product_type`. `null` when no default is set.", "example": { "id": "ptc_xxxxxxxxxxxxxx", "name": "General - Digital Goods", "product_type": "digital" }, "type": [ "object", "null" ] }, "recommended_actions": { "deprecated": true, "description": "DEPRECATED: Use the `GET /economic_intelligence?account_id={account_id}` endpoint instead.", "items": { "$ref": "#/components/schemas/AccountRecommendedAction", "description": "Deprecated: use the `GET /economic_intelligence?account_id={account_id}` endpoint instead. Optional actions that unlock capabilities or grow the account, same shape as `required_actions`. Computed only on `retrieve` and `me`; `null` otherwise." }, "type": [ "array", "null" ] }, "require_2fa": { "description": "Whether authorized users must enable two-factor authentication.", "example": false, "type": "boolean" }, "required_actions": { "items": { "$ref": "#/components/schemas/AccountRequiredAction", "description": "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." }, "type": [ "array", "null" ] }, "return_policy": { "description": "The account's return policy document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "rewards": { "items": { "$ref": "#/components/schemas/AccountPartnerReward", "description": "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." }, "type": "array" }, "route": { "description": "Account public route identifier.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "send_customer_emails": { "description": "Whether Whop sends transactional emails to customers on behalf of this account.", "example": false, "type": "boolean" }, "shipping_policy": { "description": "The account's shipping policy document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "show_joined_whops": { "description": "Whether the account appears in joined whops on other accounts.", "example": true, "type": "boolean" }, "show_reviews_dtc": { "description": "Whether reviews are displayed on direct-to-consumer product pages.", "example": true, "type": "boolean" }, "show_user_directory": { "description": "Whether the account shows users in the user directory.", "example": true, "type": "boolean" }, "social_links": { "items": { "$ref": "#/components/schemas/AccountSocialLink", "description": "Account social links." }, "type": "array" }, "status": { "description": "Whether the account can operate on Whop: `active` or `suspended`. Computed on `list`, `retrieve`, `me`, and `suspend`; `null` otherwise.", "example": "active", "type": [ "string", "null" ] }, "status_reason": { "description": "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.", "example": "Suspended - Fraudulent activity", "type": [ "string", "null" ] }, "store_page_config": { "$ref": "#/components/schemas/AccountStorePageConfig", "description": "Account store page display configuration." }, "target_audience": { "description": "Target audience for this account.", "example": "Owners of new and enthusiast vehicles in Austin, TX", "type": [ "string", "null" ] }, "tax_collection_enabled_states": { "items": { "description": "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`).", "example": "TX", "type": "string" }, "type": "array" }, "tax_identifiers": { "items": { "$ref": "#/components/schemas/AccountTaxIdentifier", "description": "Account tax/VAT registrations. Empty when none are set." }, "type": "array" }, "tax_remitted_by": { "description": "Who calculates and remits tax for the account: `whop` (Whop calculates and remits), `self` (Whop calculates; the account collects and remits), or `none` (neither; the account is responsible). `null` until the account enrolls in the Whop tax service.", "enum": [ "whop", "self", "none", null ], "example": "self", "type": [ "string", "null" ] }, "tax_type": { "description": "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.", "enum": [ "inclusive", "exclusive", null ], "example": "inclusive", "type": [ "string", "null" ] }, "terms_of_service": { "description": "The account's terms of service document, or `null` if they have not published one.", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "type": "null" } ] }, "three_ds_level": { "description": "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.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": "string" }, "total_earned_usd": { "description": "Account lifetime sales, normalized to USD. Computed only on `retrieve` and `me` for callers with `stats:read` scope; `null` otherwise.", "example": 0.0, "type": [ "number", "null" ] }, "total_usd": { "description": "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.", "example": "50.00", "type": [ "string", "null" ] }, "trading": { "description": "The trading account address and its WebSocket subscriptions. Opt in with `include_trading=true` on single-account reads. `null` otherwise, without trading permission, or without an Ethereum wallet.", "oneOf": [ { "$ref": "#/components/schemas/TradingAccount" }, { "type": "null" } ] }, "use_logo_as_opengraph_image_fallback": { "description": "Whether the account uses its logo as the fallback Open Graph image.", "example": false, "type": "boolean" }, "verification": { "description": "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`.", "example": { "business": null, "individual": null }, "type": "object" }, "volume_l30d_usd": { "description": "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.", "example": 0.0, "type": [ "number", "null" ] }, "volume_usd": { "description": "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.", "type": [ "number", "null" ] }, "wallet": { "description": "Account primary crypto wallet, or `null` if none has been provisioned.", "oneOf": [ { "$ref": "#/components/schemas/AccountWallet" }, { "type": "null" } ] }, "website": { "description": "The account's business website URL, or `null` if none has been provided. Setting it also adds a `website` entry to `social_links`.", "example": "https://shinetimedetail.com", "type": [ "string", "null" ] }, "whop_partner_enabled_at": { "description": "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.", "example": null, "type": [ "string", "null" ] } }, "required": [ "id", "trading", "email", "title", "description", "route", "website", "logo_url", "banner_image_url", "terms_of_service", "privacy_policy", "return_policy", "eula", "shipping_policy", "cancellation_policy", "business_type", "country", "home_preferences", "industry_type", "invoice_prefix", "onboarding_type", "opengraph_image_url", "opengraph_image_variant", "other_business_description", "other_industry_description", "require_2fa", "three_ds_level", "collect_vat_id", "target_audience", "dispute_fighter_enabled", "orchestration_enabled", "send_customer_emails", "show_joined_whops", "show_reviews_dtc", "show_user_directory", "store_page_config", "metadata", "created_at", "use_logo_as_opengraph_image_fallback", "total_earned_usd", "status", "status_reason", "volume_usd", "volume_l30d_usd", "customers_l30d", "ads_spend_usd", "level", "capabilities", "payment_controls", "cards", "financing", "required_actions", "recommended_actions", "tax_remitted_by", "tax_type", "product_tax_code", "business_address", "business_name", "tax_identifiers", "tax_collection_enabled_states", "total_usd", "balances", "platform_credits", "economic_intelligence", "can_transfer_pending_balance_to_children", "verification", "company_formation", "owner", "parent_account", "wallet", "social_links" ], "type": "object" }, "AccountBalanceBreakdown": { "properties": { "available": { "description": "Amount you can spend, send, or withdraw now, in native units, as a decimal string.", "example": "1500.0", "type": "string" }, "finishing_settlement": { "description": "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.", "example": "0", "type": "string" }, "in_transit": { "description": "Amount moving between the account's own destinations, such as a card top-up. In native units, as a decimal string.", "example": "0", "type": "string" }, "pending": { "description": "Amount from recent payments still settling, in native units, as a decimal string.", "example": "0", "type": "string" }, "pending_settlements": { "items": { "$ref": "#/components/schemas/AccountBalanceSettlement", "description": "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." }, "type": "array" }, "reserve": { "description": "Amount held back, in native units, as a decimal string. Retrieve the account's reserves for why it is held and when it unlocks.", "example": "0", "type": "string" } }, "required": [ "available", "pending", "in_transit", "reserve", "pending_settlements", "finishing_settlement" ], "type": "object" }, "AccountBalanceSettlement": { "properties": { "amount": { "description": "Amount expected that day, in native units, as a decimal string.", "example": "0.0", "type": "string" }, "date": { "description": "The day this money is expected to finish settling, as an ISO 8601 date.", "example": "2026-01-01", "type": "string" } }, "required": [ "date", "amount" ], "type": "object" }, "AccountBalanceToken": { "properties": { "balance": { "description": "Total amount held in native units, as a decimal string.", "example": "1500.0", "type": "string" }, "breakdown": { "$ref": "#/components/schemas/AccountBalanceBreakdown", "description": "Balance split into available, pending, and reserve amounts, as native-unit decimal strings, with the days the pending amount is expected to settle." }, "icon_url": { "description": "Holding icon URL.", "example": "https://assets.whop.com/tokens/usdt.png", "type": [ "string", "null" ] }, "name": { "description": "The holding's display name", "example": "Tether USD", "type": "string" }, "price_usd": { "description": "USD price per unit, or `null` when no exchange rate is available.", "example": 1.0, "type": [ "number", "null" ] }, "symbol": { "description": "Holding display symbol, such as `USDT`, `cbBTC`, or `EUR`.", "example": "USDT", "type": "string" }, "value_usd": { "description": "Holding USD value, or `null` when no exchange rate is available.", "example": "1500.00", "type": [ "string", "null" ] } }, "required": [ "symbol", "name", "balance", "value_usd", "price_usd", "icon_url", "breakdown" ], "type": "object" }, "AccountCapabilities": { "properties": { "accept_bank_payments": { "description": "Bank payins: debits, transfers, and local bank rails", "enum": [ "active", "inactive", "pending" ], "example": "active", "type": "string" }, "accept_bnpl_payments": { "description": "Buy-now-pay-later payins; requires approval", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "accept_card_payments": { "description": "Card payins, including Apple Pay and Google Pay", "enum": [ "active", "inactive", "pending" ], "example": "active", "type": "string" }, "bank_deposit": { "description": "Deposits by bank wire or ACH to the account's virtual bank account", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "card_deposit": { "description": "Balance top-ups by charging a stored payment method", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "card_issuing": { "description": "Issuing Whop cards; requires card application approval", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "crypto_deposit": { "description": "On-chain deposits to the account's crypto wallet", "enum": [ "active", "inactive", "pending" ], "example": "active", "type": "string" }, "crypto_payout": { "description": "On-chain payouts to a crypto wallet", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "instant_payout": { "description": "Instant payouts to an eligible payout destination", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "run_ads": { "description": "Launching ad campaigns through Whop Ads. `inactive` until the account's identity or business is verified, and while a requested ads services agreement is awaiting the account's signature.", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "standard_payout": { "description": "Standard payouts to an external payout destination", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" }, "transfer": { "description": "Transfers to other accounts", "enum": [ "active", "inactive", "pending" ], "example": "inactive", "type": "string" } }, "required": [ "accept_card_payments", "accept_bank_payments", "accept_bnpl_payments", "standard_payout", "instant_payout", "crypto_payout", "transfer", "bank_deposit", "crypto_deposit", "card_deposit", "card_issuing", "run_ads" ], "type": "object" }, "AccountCards": { "properties": { "kind": { "description": "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.", "enum": [ "individual", "business", null ], "example": "individual", "type": [ "string", "null" ] }, "status": { "description": "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.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "approved", "type": "string" } }, "required": [ "kind", "status" ], "type": "object" }, "AccountCompanyFormation": { "additionalProperties": true, "properties": { "documents": { "items": { "$ref": "#/components/schemas/AccountCompanyFormationDocument", "description": "Formation documents available for download, such as the Articles of Organization and the EIN confirmation letter. Present once `status` leaves `draft`." }, "type": "array" }, "ein_registered": { "description": "Whether the company's EIN has been issued by the IRS. Present once `status` leaves `draft`.", "example": false, "type": "boolean" }, "legal_name": { "description": "Registered company name including the entity ending, for example `Acme, LLC`. Present once `status` leaves `draft`.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "signatures": { "$ref": "#/components/schemas/AccountCompanyFormationSignatures", "description": "IRS forms still awaiting a founder's signature, each with a hosted signing URL. Present once `status` leaves `draft`; empty when nothing needs signing." }, "state_registered": { "description": "Whether the state formation filing is complete. Present once `status` leaves `draft`.", "example": true, "type": "boolean" }, "status": { "enum": [ "draft", "processing", "filed", "rejected", "completed" ], "type": "string" } }, "required": [], "type": "object" }, "AccountCompanyFormationDocument": { "properties": { "id": { "description": "Document ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Human-readable document name, such as `Articles of Organization`.", "example": "Articles of Organization", "type": "string" }, "type": { "description": "Document category: `articles_of_organization`, `operating_agreement`, `ein_letter`, `signed_ss4`, `signed_form8821`, or `mail` for postal correspondence received on the company's behalf.", "example": "articles_of_organization", "type": "string" }, "url": { "description": "CDN URL for downloading the document.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/audio/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "name", "type", "url" ], "type": "object" }, "AccountCompanyFormationSignatureRequest": { "properties": { "expires_at": { "description": "When the signing URL expires, as an ISO 8601 timestamp. Present only when the signing URL is included.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "`pending` when a signing session is ready for the founder; `unknown` when the signature state could not be determined.", "enum": [ "pending", "unknown" ], "example": "pending", "type": "string" }, "url": { "description": "Hosted signing URL where the founder completes the form. Present while `status` is `pending` and the caller has `incorporation:write`. Omitted from webhooks.", "example": "https://sign.doola.com/shine-time-auto-detailing/form8821", "type": "string" } }, "required": [ "status" ], "type": "object" }, "AccountCompanyFormationSignatures": { "additionalProperties": true, "properties": { "form8821": { "$ref": "#/components/schemas/AccountCompanyFormationSignatureRequest", "description": "Signature state for IRS Form 8821, the tax information authorization. Present only while the form still needs the founder's action." }, "ss4": { "$ref": "#/components/schemas/AccountCompanyFormationSignatureRequest", "description": "Signature state for IRS Form SS-4, the EIN application. Present only while the form still needs the founder's action." } }, "required": [], "type": "object" }, "AccountCoveredPayoutFees": { "properties": { "all": { "description": "Whether this account pays payout fees for all of its connected accounts' payout methods. Turning this off clears category coverage.", "example": false, "type": "boolean" }, "bank_wire": { "description": "Whether this account covers its connected accounts' bank wire payout fees. Individual changes have no effect while `all` is true.", "example": false, "type": "boolean" }, "crypto": { "description": "Whether this account covers its connected accounts' crypto payout fees. Individual changes have no effect while `all` is true.", "example": false, "type": "boolean" }, "digital_wallet": { "description": "Whether this account covers its connected accounts' digital wallet payout fees. Individual changes have no effect while `all` is true.", "example": false, "type": "boolean" }, "next_day_bank": { "description": "Whether this account covers its connected accounts' next day bank payout fees. Individual changes have no effect while `all` is true.", "example": false, "type": "boolean" }, "rtp": { "description": "Whether this account covers its connected accounts' real-time payment payout fees. Individual changes have no effect while `all` is true.", "example": false, "type": "boolean" } }, "required": [ "all", "crypto", "rtp", "next_day_bank", "bank_wire", "digital_wallet" ], "type": "object" }, "AccountCustomerTracking": { "properties": { "accent_color": { "description": "Accent color, as a `#rrggbb` hex color.", "example": "#1d4ed8", "type": "string" }, "business_name": { "description": "The business name shown on its customer tracking page.", "example": "Shine Time Auto Detailing", "type": "string" }, "button_text_color": { "description": "`black` or `white`, whichever reads against the accent color.", "enum": [ "black", "white" ], "example": "white", "type": "string" }, "logo_url": { "description": "The account logo image URL, or `null` when it has not uploaded one.", "example": null, "type": [ "string", "null" ] }, "show_business_name": { "description": "Whether to display the business name on the tracking page and Element.", "example": true, "type": "boolean" }, "show_logo": { "description": "Whether to display the logo on the tracking page and Element.", "example": true, "type": "boolean" }, "support_email": { "description": "Customer support email address, or `null` when not set.", "example": null, "type": [ "string", "null" ] }, "support_url": { "description": "HTTPS customer support URL, or `null` when not set.", "example": null, "type": [ "string", "null" ] } }, "required": [ "business_name", "logo_url", "show_logo", "show_business_name", "accent_color", "button_text_color", "support_email", "support_url" ], "type": "object" }, "AccountDisputeAlertAutoRefundControl": { "properties": { "locked": { "description": "Whether the account owner is prevented from changing this threshold.", "example": false, "type": "boolean" }, "threshold_usd": { "description": "Maximum dispute alert amount automatically refunded in USD. `null` when automatic refunds are disabled.", "example": 500, "type": [ "number", "null" ] } }, "required": [ "threshold_usd", "locked" ], "type": "object" }, "AccountEconomicIntelligenceOffer": { "properties": { "auto_renew": { "description": "Whether this offer renews every period until auto-renew is turned off, rather than ending after one.", "type": "boolean" }, "duration": { "description": "What period of time Economic Intelligence stays on. For an auto-renew offer, the length of each period it renews for.", "type": "integer" }, "duration_unit": { "description": "The unit of time the duration is in (hours or days)", "enum": [ "hours", "days" ], "example": "hours", "type": "string" }, "fee_percentage": { "description": "Percentage of volume charged while Economic Intelligence is on, such as `1.5` for 1.5%.", "type": "number" }, "key": { "description": "The unique identifier for this offer. Pass this value as `economic_intelligence_duration_key` to turn it on.", "enum": [ "weekly", "7_days", "1_day", "1_hour" ], "example": "weekly", "type": "string" }, "recommended": { "description": "Whether Whop recommends this offer. At most one offer is recommended.", "type": "boolean" } }, "required": [ "duration_unit", "duration", "key", "fee_percentage", "auto_renew", "recommended" ], "type": "object" }, "AccountEconomicIntelligencePreviousPeriod": { "properties": { "ended_at": { "description": "When the period ended, as an ISO 8601 timestamp.", "type": "string" }, "fee_percentage": { "description": "Percentage of volume charged during the period, such as `3` for 3%.", "type": "number" } }, "required": [ "ended_at", "fee_percentage" ], "type": "object" }, "AccountFee": { "properties": { "adjustable": { "description": "Whether the caller may change this fee through `PATCH`. Depends on who is asking.", "example": true, "type": "boolean" }, "category": { "description": "Which group of the fee schedule this fee belongs to, for grouping in a UI.", "enum": [ "payments", "disputes", "optimization", "payouts", "other" ], "example": "payments", "type": "string" }, "default": { "$ref": "#/components/schemas/AccountFeeRate", "description": "The platform rate before custom or inherited pricing is applied. Its `percentage` and `fixed` are `null` when a connected account's fees are read without access to its parent account." }, "ends_at": { "description": "When a custom or inherited rate expires and the fee returns to `default`, as an ISO 8601 timestamp. `null` when the default applies, the rate does not expire, or a connected account's fees are read without access to its parent account.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "fixed": { "description": "The amount charged per event in effect. `null` when the fee has no fixed component.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "maximum": { "description": "The highest rate the caller may set. `null` when the fee is not adjustable or the caller is not capped.", "oneOf": [ { "$ref": "#/components/schemas/AccountFeeRate" }, { "type": "null" } ] }, "minimum": { "description": "The lowest rate the caller may set, present only when `adjustable`.", "oneOf": [ { "$ref": "#/components/schemas/AccountFeeRate" }, { "type": "null" } ] }, "percentage": { "description": "The percentage of the transaction in effect, where `2` means 2%. `null` when the fee has no percentage component.", "example": 2.4, "type": [ "number", "null" ] }, "region": { "description": "The acquirer region `percentage` and `fixed` describe, for a fee that varies by where the money is processed. `null` for a fee that does not vary by region.", "enum": [ "usa", "eu", "ca", "uk", "au", "co", "mx", "ke", "cl", "pe", "ar", "cr", "gt", "uy", "br", "ph", "ng", "my", null ], "example": "usa", "type": [ "string", "null" ] }, "regions": { "additionalProperties": { "$ref": "#/components/schemas/AccountFeeRegionalRate" }, "description": "The rate, source, default, reset rate, and editable limits in every other region this fee varies by, keyed by region. Empty for a fee that does not vary by region.", "example": { "ar": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "percentage": 2.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default" }, "au": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 1.5 }, "percentage": 2.7, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default" }, "br": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 8.0 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 30.0 }, "minimum": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "percentage": 8.0, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 8.0 }, "source": "default" }, "ca": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.4 }, "percentage": 2.7, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default" }, "cl": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "percentage": 2.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default" }, "co": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "percentage": 2.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default" }, "eu": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 1.5 }, "percentage": 2.5, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.6 }, "source": "custom" }, "mx": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "percentage": 2.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default" }, "pe": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.7 }, "percentage": 4.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "source": "default" }, "uk": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "1.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 10.0 }, "minimum": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 1.5 }, "percentage": 2.7, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default" } }, "type": "object" }, "reset": { "$ref": "#/components/schemas/AccountFeeRate", "description": "The rate that takes effect when this account's custom rate is cleared, including inherited pricing. Its `percentage` and `fixed` are `null` when a connected account's fees are read without access to its parent account." }, "source": { "description": "Where the rate in effect comes from: `default` is the platform rate, `custom` a rate negotiated for this account, and `inherited` a rate negotiated by the platform this account is connected to. `null` when a connected account's fees are read without access to its parent account.", "enum": [ "default", "custom", "inherited", null ], "example": "inherited", "type": [ "string", "null" ] }, "unadjustable_reason": { "description": "Why the caller may not change this fee, or `null` when `adjustable`. `not_permitted` when the caller has no say over it.", "enum": [ "not_permitted", null ], "example": "not_permitted", "type": [ "string", "null" ] } }, "required": [ "category", "percentage", "fixed", "region", "regions", "default", "reset", "source", "ends_at", "adjustable", "unadjustable_reason", "minimum", "maximum" ], "type": "object" }, "AccountFeeMarkup": { "properties": { "adjustable": { "description": "Whether the caller may change this markup through `PATCH`. True for the platform's team holding the `company:update_child_fees` scope.", "example": false, "type": "boolean" }, "default": { "$ref": "#/components/schemas/AccountFeeRate", "description": "What applies if this row is cleared: the platform's default for all its connected accounts, or zero. Its `percentage` and `fixed` are `null` when a connected account's fees are read without access to its parent account." }, "fixed": { "$ref": "#/components/schemas/Money", "description": "The amount the platform adds per event. Zero when no markup is set." }, "maximum": { "$ref": "#/components/schemas/AccountFeeRate", "description": "The highest markup the platform may set." }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%. `0` when no markup is set.", "example": 0.0, "type": "number" }, "source": { "description": "`custom` when a row is set at this level, `default` when the rate falls through to the platform default or zero. `null` when a connected account's fees are read without access to its parent account.", "enum": [ "default", "custom", null ], "example": "default", "type": [ "string", "null" ] }, "unadjustable_reason": { "description": "Why the caller may not change this markup, or `null` when `adjustable`.", "enum": [ "not_permitted", null ], "example": "not_permitted", "type": [ "string", "null" ] } }, "required": [ "percentage", "fixed", "default", "source", "adjustable", "unadjustable_reason", "maximum" ], "type": "object" }, "AccountFeeMarkups": { "properties": { "card_spend": { "$ref": "#/components/schemas/AccountFeeMarkup", "description": "The markup on card purchases settled by the connected account." }, "crypto_swaps": { "$ref": "#/components/schemas/AccountFeeMarkup", "description": "The markup on cryptocurrency token swaps." }, "deposits": { "additionalProperties": { "$ref": "#/components/schemas/AccountFeeMarkup" }, "description": "Markups on deposits into the account's balance, keyed by rail: `bank` and `crypto`.", "example": { "bank": { "adjustable": false, "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "100.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 100.0 }, "percentage": 0.0, "source": "default", "unadjustable_reason": "not_permitted" }, "crypto": { "adjustable": false, "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "100.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 100.0 }, "percentage": 0.0, "source": "default", "unadjustable_reason": "not_permitted" } }, "type": "object" }, "payments": { "$ref": "#/components/schemas/AccountFeeMarkup", "description": "The markup on payments the connected account collects without a checkout application fee." }, "payouts": { "additionalProperties": { "$ref": "#/components/schemas/AccountFeeMarkup" }, "description": "Markups on withdrawals, keyed by payout method: `bank_wire`, `next_day_bank`, `rtp`, `crypto`, and `digital_wallet`.", "example": { "bank_wire": { "adjustable": false, "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "100.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 100.0 }, "percentage": 0.0, "source": "default", "unadjustable_reason": "not_permitted" }, "crypto": { "adjustable": false, "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "100.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 100.0 }, "percentage": 0.0, "source": "default", "unadjustable_reason": "not_permitted" }, "digital_wallet": { "adjustable": false, "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "100.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 100.0 }, "percentage": 0.0, "source": "default", "unadjustable_reason": "not_permitted" }, "next_day_bank": { "adjustable": false, "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "100.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 100.0 }, "percentage": 0.0, "source": "default", "unadjustable_reason": "not_permitted" }, "rtp": { "adjustable": false, "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": { "fixed": { "amount": "100.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 100.0 }, "percentage": 0.0, "source": "default", "unadjustable_reason": "not_permitted" } }, "type": "object" }, "transfers": { "$ref": "#/components/schemas/AccountFeeMarkup", "description": "The markup on transfers between Whop balances." } }, "required": [ "payouts", "deposits", "transfers", "crypto_swaps", "payments", "card_spend" ], "type": "object" }, "AccountFeeRate": { "properties": { "fixed": { "description": "The amount charged per event. `null` when unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "percentage": { "description": "The percentage of the transaction, where `2` means 2%. `null` when unavailable.", "example": 0.0, "type": [ "number", "null" ] } }, "required": [ "percentage", "fixed" ], "type": "object" }, "AccountFeeRegionalRate": { "properties": { "default": { "$ref": "#/components/schemas/AccountFeeRate", "description": "The platform rate for this region before custom or inherited pricing is applied." }, "fixed": { "description": "The amount charged per event in effect. `null` when the fee has no fixed component.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "maximum": { "description": "The highest regional rate the caller may set. `null` when the fee is not adjustable or the caller is not capped.", "oneOf": [ { "$ref": "#/components/schemas/AccountFeeRate" }, { "type": "null" } ] }, "minimum": { "description": "The lowest regional rate the caller may set, present only when the fee is adjustable.", "oneOf": [ { "$ref": "#/components/schemas/AccountFeeRate" }, { "type": "null" } ] }, "percentage": { "description": "The percentage of the transaction in effect, where `2` means 2%. `null` when the fee has no percentage component.", "type": [ "number", "null" ] }, "reset": { "$ref": "#/components/schemas/AccountFeeRate", "description": "The regional rate that takes effect when this account's custom rate is cleared, including inherited pricing." }, "source": { "description": "Where the regional rate in effect comes from: `default` is the platform rate, `custom` a rate negotiated for this account, and `inherited` a rate negotiated by the platform this account is connected to.", "enum": [ "default", "custom", "inherited", null ], "example": "default", "type": [ "string", "null" ] } }, "required": [ "percentage", "fixed", "source", "minimum", "maximum", "default", "reset" ], "type": "object" }, "AccountFees": { "properties": { "account_id": { "description": "The account these fees are charged to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "ach_dispute": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when the account holder disputes an ACH payment." }, "ach_return": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when an ACH payment is returned by the buyer's bank." }, "bank_deposit": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on bank deposits into the account's balance." }, "billing": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on recurring billing." }, "buyer": { "$ref": "#/components/schemas/AccountFee", "description": "Charged to the buyer at checkout, on top of the price." }, "card_processing": { "$ref": "#/components/schemas/AccountFee", "description": "Card payments. `percentage` and `fixed` are the rate in the headline `region`; every other acquirer region is under `regions`." }, "child_markups": { "description": "The default markups this account charges connected accounts, configurable before any accounts connect. `null` if this account has a parent.", "oneOf": [ { "$ref": "#/components/schemas/AccountFeeMarkups" }, { "type": "null" } ] }, "covered_payout_fees": { "$ref": "#/components/schemas/AccountCoveredPayoutFees", "description": "Which payout fees this account pays for its connected accounts." }, "cross_border": { "$ref": "#/components/schemas/AccountFee", "description": "Added to a payment whose card was issued outside the region where the payment was processed." }, "dispute": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when a payment is disputed." }, "dispute_alert": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when an early dispute alert lets Whop refund a payment before it becomes a dispute." }, "dispute_alert_cdrn": { "$ref": "#/components/schemas/AccountFee", "description": "The early dispute alert fee when the alert comes through Verifi CDRN." }, "dispute_alert_ethoca": { "$ref": "#/components/schemas/AccountFee", "description": "The early dispute alert fee when the alert comes through Ethoca." }, "dispute_alert_rdr": { "$ref": "#/components/schemas/AccountFee", "description": "The early dispute alert fee when the alert comes through Verifi RDR." }, "dispute_representment": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on the amount recovered when Whop fights a dispute and wins." }, "foreign_exchange": { "$ref": "#/components/schemas/AccountFee", "description": "Added to a payment settled in a currency other than the one it was charged in." }, "fraud_screening": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when a payment is screened for fraud." }, "high_risk": { "$ref": "#/components/schemas/AccountFee", "description": "Added to every payment while the account is classed as high risk." }, "marketplace": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on payments attributed to the Whop marketplace." }, "markups": { "description": "What the platform this account is connected to adds on top of Whop's fees, collected by that platform. `null` unless the account has a parent.", "oneOf": [ { "$ref": "#/components/schemas/AccountFeeMarkups" }, { "type": "null" } ] }, "orchestration": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on payments routed through Whop's payment orchestration." }, "parent_account_id": { "description": "The platform this account is connected to, whose markups appear under `markups`. `null` for a standalone account.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_methods": { "additionalProperties": { "$ref": "#/components/schemas/AccountFee" }, "description": "Processing fees for every non-card payment method the platform prices, keyed by payment method type such as `us_bank_account` or `klarna`.", "example": { "acss_debit": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "addi": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 15.0 }, "ends_at": null, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 15.0, "region": "co", "regions": {}, "reset": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "affirm": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "afterpay_clearpay": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "alipay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "au", "regions": { "eu": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default" } }, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "alipayhk": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "au", "regions": { "eu": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default" } }, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "alma": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "bacs_debit": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "bancolombia": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "co", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "bancontact": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "bank_wire": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 1.5 }, "ends_at": null, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 1.5, "region": "usa", "regions": {}, "reset": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 1.5 }, "source": "default", "unadjustable_reason": "not_permitted" }, "billie": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "boleto": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "br", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "bre_b": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "co", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "capchase_pay": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "cashapp": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "claritypay": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "duitnow_qr": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "my", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "efecty": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "co", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "flex_pay": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "gcash": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "ph", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "gopay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "eu", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "grabpay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "my", "regions": { "uk": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default" } }, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "kakao_pay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "eu", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "klarna": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "klarna_pay_now": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "kriya": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "kueski": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 4.9, "region": "mx", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "link": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "m_pesa": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "2.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "2.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "ke", "regions": {}, "reset": { "fixed": { "amount": "2.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "mb_way": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "eu", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "mercado_pago": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 4.9, "region": "cl", "regions": { "mx": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 4.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "source": "default" } }, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "mobilepay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "modo": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "ar", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "mondu": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "multibanco": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "eu", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "nequi": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "co", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "ng_bank_transfer": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "ng", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "opay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "ng", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "oxxo": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 4.9, "region": "mx", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "pago_efectivo": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "pe", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "paypay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "eu", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "payto": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "au", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "pse": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "co", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "rapipago": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "ar", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "satispay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.5 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 4.5, "region": "eu", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.5 }, "source": "default", "unadjustable_reason": "not_permitted" }, "scalapay": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "sencillito": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "cl", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "sequra": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 3.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 3.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 3.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "servipag": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "3.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "3.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "cl", "regions": {}, "reset": { "fixed": { "amount": "3.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "sezzle": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "shopeepay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "my", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "spei": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "mx", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "splitit": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "sunbit": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "swish": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "tabby": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": "usa", "regions": { "eu": { "default": { "fixed": null, "percentage": 15.0 }, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default" } }, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "tamara": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "touch_n_go": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "eu", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "upi": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "region": "usa", "regions": { "in": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default" } }, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "us_bank_account": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 1.5 }, "ends_at": null, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 1.5, "region": "usa", "regions": {}, "reset": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 1.5 }, "source": "default", "unadjustable_reason": "not_permitted" }, "vipps": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 2.7, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 2.7 }, "source": "default", "unadjustable_reason": "not_permitted" }, "webpay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 4.9, "region": "cl", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 4.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "wechat_pay": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "au", "regions": { "uk": { "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default" } }, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "yape": { "adjustable": false, "category": "payments", "default": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "ends_at": null, "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 3.9, "region": "pe", "regions": {}, "reset": { "fixed": { "amount": "0.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 3.9 }, "source": "default", "unadjustable_reason": "not_permitted" }, "zip": { "adjustable": false, "category": "payments", "default": { "fixed": null, "percentage": 15.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 15.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 15.0 }, "source": "default", "unadjustable_reason": "not_permitted" } }, "type": "object" }, "payouts": { "additionalProperties": { "$ref": "#/components/schemas/AccountFee" }, "description": "Fees on withdrawals, keyed by payout method: `bank_wire`, `same_day_bank`, `next_day_bank`, `rtp`, `crypto`, and `digital_wallet`. Payout fees the parent account covers show as zero when a connected account's fees are read without access to its parent account.", "example": { "bank_wire": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "30.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "ends_at": null, "fixed": { "amount": "30.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": null, "region": null, "regions": {}, "reset": { "fixed": { "amount": "30.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "source": "default", "unadjustable_reason": "not_permitted" }, "crypto": { "adjustable": false, "category": "payouts", "default": { "fixed": null, "percentage": 0.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 0.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 0.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "digital_wallet": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "ends_at": null, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 0.0, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "next_day_bank": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "ends_at": null, "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": null, "region": null, "regions": {}, "reset": { "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "source": "default", "unadjustable_reason": "not_permitted" }, "rtp": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "ends_at": null, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 0.0, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "same_day_bank": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "ends_at": null, "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": null, "region": null, "regions": {}, "reset": { "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "source": "default", "unadjustable_reason": "not_permitted" } }, "type": "object" }, "pending_auto_topup": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when pending, not-yet-settled balance is advanced to fund the account's cards balance." }, "platform_processing": { "$ref": "#/components/schemas/AccountFee", "description": "Whop's share of every payment, on top of card processing." }, "pool_payout": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on payouts from a shared pool balance." }, "revshare": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on payments where the account shares revenue with revshare affiliates." }, "sepa_dispute": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when the account holder disputes a SEPA Direct Debit payment." }, "sepa_return": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when a SEPA Direct Debit payment is returned by the buyer's bank." }, "tax_calculation": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when tax is calculated on a payment." }, "tax_service": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when Whop collects and remits tax on the account's behalf." }, "three_ds": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when a payment is authenticated with 3-D Secure." }, "transfers": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on transfers from the account's balance to another Whop balance." } }, "required": [ "account_id", "parent_account_id", "card_processing", "payment_methods", "cross_border", "foreign_exchange", "platform_processing", "marketplace", "buyer", "high_risk", "dispute", "dispute_representment", "dispute_alert", "dispute_alert_ethoca", "dispute_alert_cdrn", "dispute_alert_rdr", "sepa_return", "ach_return", "sepa_dispute", "ach_dispute", "orchestration", "three_ds", "fraud_screening", "billing", "tax_calculation", "tax_service", "transfers", "pool_payout", "revshare", "pending_auto_topup", "bank_deposit", "payouts", "markups", "child_markups", "covered_payout_fees" ], "type": "object" }, "AccountFinancing": { "properties": { "application_id": { "description": "The ID of the account's most recent financing application, starting with inrq_. Retrieve it for requirements and review feedback.", "example": "inrq_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "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`.", "enum": [ "requires_collection", "awaiting_review", "completed", "approved", "denied" ], "example": "awaiting_review", "type": "string" } }, "required": [ "application_id", "status" ], "type": "object" }, "AccountLevel": { "properties": { "boosted": { "description": "`true` when this account's own points this month fall short of `current`, so the owner's other accounts lift it to this level.", "example": true, "type": "boolean" }, "current": { "description": "Current level, from `0` before the first threshold up to `10`.", "example": 1, "type": "integer" }, "points": { "description": "Points earned this month across every account the owner owns.", "example": 41000, "type": "integer" }, "points_by_source": { "$ref": "#/components/schemas/OwnerLevelPoints", "description": "This month's points, split by where they were earned." }, "points_to_next": { "description": "Points still needed this month to reach the next level, or `null` at level `10`.", "example": 59000, "type": [ "integer", "null" ] }, "resets_at": { "description": "When this month's points reset to zero, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "current", "points", "points_by_source", "points_to_next", "resets_at", "boosted" ], "type": "object" }, "AccountLink": { "description": "A temporary, time-limited URL that grants a user access to an external account management page.", "properties": { "expires_at": { "description": "The timestamp after which this account link URL is no longer valid.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "url": { "description": "The temporary URL to redirect the user to for account access. Expires at the time specified by expires_at.", "example": "https://whop.com/verify-identity/biz_xxxxxxxxx/", "type": "string" } }, "required": [ "url", "expires_at" ], "type": "object" }, "AccountLinkUseCases": { "description": "The different use cases for generating an account link.", "enum": [ "account_onboarding", "payouts_portal" ], "type": "string" }, "AccountParent": { "properties": { "fees": { "additionalProperties": { "properties": { "fixed_fee_usd": { "description": "Fixed markup in US dollars per transaction.", "type": "number" }, "percentage_fee": { "description": "Percentage of the transaction charged as markup.", "type": "number" } }, "required": [ "percentage_fee", "fixed_fee_usd" ], "type": "object" }, "description": "Markup rates this parent charges the connected account being read, keyed by fee type (for example `crypto_deposit_markup`), each with `percentage_fee` and `fixed_fee_usd`. Resolved with the connected account's own overrides winning over the platform default.", "example": { "crypto_swap_markup": { "fixed_fee_usd": 0.0, "percentage_fee": 3.0 }, "transfer_markup": { "fixed_fee_usd": 0.0, "percentage_fee": 0.0 } }, "type": "object" }, "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Account public route identifier.", "example": "shine-time-holdings", "type": "string" }, "title": { "description": "Account display name.", "example": "Shine Time Holdings", "type": "string" } }, "required": [ "id", "title", "route", "logo_url" ], "type": "object" }, "AccountPartner": { "properties": { "email": { "description": "Email address for contacting the partner. Null when the partner has not added their own email address.", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "type": "string" }, "name": { "description": "Display name.", "type": [ "string", "null" ] }, "profile_picture": { "$ref": "#/components/schemas/UserProfilePicture", "description": "Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture." }, "username": { "description": "Public username.", "type": "string" }, "whop_partner_verified_at": { "description": "When the user became a verified Whop Partner, as an ISO 8601 timestamp. Null if not verified.", "type": [ "string", "null" ] } }, "required": [ "id", "username", "name", "profile_picture", "email", "whop_partner_verified_at" ], "type": "object" }, "AccountPartnerReward": { "properties": { "id": { "description": "Reward definition ID, prefixed `prwd_`. Progress and status apply to the containing account.", "type": "string" }, "qualification_amount": { "$ref": "#/components/schemas/Money", "description": "Qualifying USD volume required to earn this reward." }, "qualification_progress": { "$ref": "#/components/schemas/Money", "description": "Qualifying USD volume for the reward’s activity accumulated by this account since attribution, calculated using the fulfillment rules." }, "qualification_type": { "description": "Activity that qualifies this account for the reward.", "enum": [ "sales", "ad_spend" ], "example": "sales", "type": "string" }, "reward_amount": { "$ref": "#/components/schemas/Money", "description": "USD amount credited for this reward. Uses the saved grant amount once fulfillment has started." }, "status": { "description": "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.", "enum": [ "in_progress", "processing", "credited", "reversing", "reversed", "unavailable" ], "example": "in_progress", "type": "string" } }, "required": [ "id", "qualification_type", "qualification_amount", "qualification_progress", "reward_amount", "status" ], "type": "object" }, "AccountPaymentControls": { "properties": { "dispute_alert_auto_refund": { "$ref": "#/components/schemas/AccountDisputeAlertAutoRefundControl", "description": "Automatic refund settings for pre-chargeback dispute alerts." }, "dispute_alert_fee_usd": { "description": "Fee charged for each dispute alert in USD. `null` when unavailable.", "example": 29, "type": [ "number", "null" ] }, "enforce_3ds": { "description": "Whether 3-D Secure is forced on every card payment at checkout. The account cannot bypass it while set.", "example": false, "type": "boolean" }, "financing_disabled": { "description": "Whether payment health controls explicitly disable financing. This is independent of financing approval in `capabilities.accept_bnpl_payments`.", "example": false, "type": "boolean" }, "high_risk_processing_fee_percentage": { "description": "Additional processing fee percentage for high-risk processing.", "example": 0, "type": "number" }, "pending_auto_topup_fee_percentage": { "description": "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.", "example": 2.0, "type": "number" }, "pending_balance_delay_days": { "description": "Additional days payments remain pending before becoming available.", "example": 0, "type": "integer" }, "reserve": { "$ref": "#/components/schemas/AccountReserveControl", "description": "Reserve currently applied to incoming payment volume." }, "resolution_center_auto_refund": { "$ref": "#/components/schemas/AccountResolutionCenterAutoRefundControl", "description": "Automatic refund settings for resolution center cases." }, "restricted_payment_methods": { "items": { "description": "Card brands blocked at checkout for this account. Empty when none are blocked. The account cannot re-enable them itself.", "enum": [ "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" ], "example": "card_visa", "type": "string" }, "type": "array" }, "undated_pending_reason": { "description": "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.", "enum": [ "kyc_incomplete", "pending_information_request", "update_payout_profile", "compliance_review", "withdrawals_disabled", null ], "example": "pending_information_request", "type": [ "string", "null" ] }, "withdrawal_schedule": { "$ref": "#/components/schemas/AccountWithdrawalScheduleControl", "description": "How the account's balance automatically withdraws." } }, "required": [ "dispute_alert_auto_refund", "resolution_center_auto_refund", "dispute_alert_fee_usd", "high_risk_processing_fee_percentage", "pending_auto_topup_fee_percentage", "pending_balance_delay_days", "financing_disabled", "reserve", "withdrawal_schedule", "undated_pending_reason", "enforce_3ds", "restricted_payment_methods" ], "type": "object" }, "AccountPreferences": { "properties": { "ads_agreement": { "description": "The account's Whop Ads services and payment authorization agreement. `status` is `not_required`, `pending_signature` (a signature has been requested and campaign launch is blocked until it is provided), or `signed`. While pending, read the fields to answer from `GET /verifications/{id}` and sign by submitting them via `PATCH /verifications/{id}`.", "type": "object" }, "ads_certifications": { "items": { "description": "The account's advertising certifications, one entry per certification type Whop offers. `status` is `not_started`, `pending_information` (an application is open and waiting for answers), `in_review`, `approved`, or `denied`. Start an application by setting a type's `status` to `pending_information` here, then answer the fields it requests via `GET`/`PATCH /verifications/{id}`; `approved_countries` is where approved certifications of that type let the account run ads.", "type": "object" }, "type": "array" }, "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when it fails. Each entry has a `type` of `platform_balance` (id `ldgr_`) or `card` (id `payt_`), plus display fields so the configured source renders even for a viewer who doesn't own it. `backup` is `null` when only one method is configured. `null` until ads billing has been configured.", "type": [ "object", "null" ] }, "ads_reporting_currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`.", "type": "string" }, "ads_scheduling_timezone": { "description": "IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Defaults to `America/New_York` until explicitly overridden.", "type": "string" }, "ads_triple_whale_integration": { "description": "The account's Triple Whale integration, which pushes Whop ad spend to Triple Whale's Data-In API so it reports as a `whop` channel, and tags ad click-through URLs with `tw_source`/`tw_adid` so Triple Whale's pixel attributes conversions back to the right ad. `status` is `connected`, `not_connected`, or `requires_shop_domain` (Triple Whale keys records by shop, so spend only flows once `shop_domain` is set). `masked_api_key` shows the leading characters of the stored key; the full key is never returned. `shop_domain` is the shop spend is reported for.", "type": "object" }, "cards_auto_top_up": { "description": "Whether incoming funds are automatically moved to the account's cards balance. `false` when the account has no cards balance.", "type": "boolean" }, "cards_notifications": { "description": "Whether Whop Card notifications reach this account's team. `true` by default, including when the account has no cards balance. Set it to `false` to stop every card email and push notification for the account — application status, verification and action-required alerts, card-ready alerts, declines, large charges, and cashback summaries. Cardholder onboarding invitations still send, because they carry the only link an invited cardholder can onboard with. Requesting a card is rejected while notifications are off, since the request reaches nobody. Cards on personal accounts are unaffected.", "type": "boolean" }, "covers_connected_account_negative_balances": { "description": "Whether this account covers its connected accounts' negative balances. When a connected account's balance drops below zero (from refunds, disputes, or fees), this account's available balance in the same currency pays it back, up to what is available. Refunds on its connected accounts may also take them negative by up to this account's available balance. `null` when the account has no connected accounts.", "type": [ "boolean", "null" ] }, "customer_tracking": { "description": "The saved customer tracking settings for the hosted tracking page and Element, exactly as saved. `null` until set; tracking is off unless `enabled` is `true`.", "oneOf": [ { "$ref": "#/components/schemas/CustomerTrackingPreferences" }, { "type": "null" } ] }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files the evidence response when this account's payments are disputed. Off by default; enabling it also opts the account into the success fee charged only on disputes it wins.", "type": "boolean" }, "economic_intelligence": { "description": "Whether Economic Intelligence is on for the account. It turns off automatically at `economic_intelligence_ends_at`.", "type": "boolean" }, "economic_intelligence_auto_renew": { "description": "Whether Economic Intelligence renews itself every week, with no end date. Turn it on with the `weekly` offer. Set it to `false` to stop renewing, which keeps Economic Intelligence on until the end of the current week, shown in `economic_intelligence_ends_at`; stopping before the first renewal charges the rest of that week at the `7_days` offer's fee. Set it back to `true` before then to keep renewing at the weekly fee.", "type": "boolean" }, "economic_intelligence_ends_at": { "description": "When the account's committed Economic Intelligence period ends, as an ISO 8601 timestamp. Economic Intelligence can't be turned off before then. `null` when Economic Intelligence is off or renews automatically.", "type": [ "string", "null" ] }, "economic_intelligence_fee_percentage": { "description": "Percentage of volume charged while Economic Intelligence is on, such as `1.5` for 1.5%. `null` when Economic Intelligence is off.", "type": [ "number", "null" ] }, "economic_intelligence_first_renewal_at": { "description": "When auto-renew first renews, as an ISO 8601 timestamp. Turning auto-renew off before then charges the rest of that week at the `7_days` offer's fee. `null` when auto-renew is off.", "type": [ "string", "null" ] }, "economic_intelligence_offers": { "items": { "$ref": "#/components/schemas/AccountEconomicIntelligenceOffer", "description": "What the account can choose now to turn on Economic Intelligence, each with its fee. Every offer while Economic Intelligence is off; only the `weekly` auto-renew offer while a committed period is running, as an upgrade; empty while it renews automatically." }, "type": "array" }, "economic_intelligence_previous_period": { "description": "The account's last Economic Intelligence period, once it has ended. `null` while Economic Intelligence is on, or when it has never been on.", "oneOf": [ { "$ref": "#/components/schemas/AccountEconomicIntelligencePreviousPeriod" }, { "type": "null" } ] }, "feedback_options": { "items": { "$ref": "#/components/schemas/FeedbackOption", "description": "The account's own cancel reasons, in the order members see them when they cancel. Each is filed under a standard category, saved as the membership's `cancel_option`, so reports keep grouping cancellations. Empty when the account uses Whop's default reasons." }, "type": "array" }, "preferred_settlement_currency": { "description": "Lowercase ISO currency code every new sale settles into, regardless of the plan's currency or what the buyer paid in. Sales converted this way carry an additional 0.5% FX fee. `null` when the account settles each sale in its plan's currency.", "enum": [ "usd", "eur", "gbp", "cad", "aud", null ], "example": "usd", "type": [ "string", "null" ] }, "preferred_settlement_currency_changeable_at": { "description": "When `preferred_settlement_currency` may next be changed or turned off, as an ISO 8601 timestamp. It can change at most once a day. `null` when it may change now.", "type": [ "string", "null" ] }, "subscription_failure_behavior": { "description": "What happens to a subscription once every retry of a renewal payment has failed. `cancel` (the default) cancels it. `none` leaves it past due and keeps billing it each period; access follows the account's past-due access setting.", "enum": [ "cancel", "none" ], "example": "cancel", "type": "string" } }, "required": [ "ads_payment_methods", "ads_reporting_currency", "ads_scheduling_timezone", "ads_agreement", "ads_certifications", "ads_triple_whale_integration", "cards_auto_top_up", "cards_notifications", "covers_connected_account_negative_balances", "dispute_fighter_enabled", "feedback_options", "economic_intelligence", "economic_intelligence_auto_renew", "economic_intelligence_ends_at", "economic_intelligence_fee_percentage", "economic_intelligence_first_renewal_at", "economic_intelligence_offers", "economic_intelligence_previous_period", "preferred_settlement_currency", "preferred_settlement_currency_changeable_at", "subscription_failure_behavior", "customer_tracking" ], "type": "object" }, "AccountRecommendedAction": { "properties": { "action": { "description": "The recommendation; new values may be added, so handle unknown actions gracefully", "enum": [ "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" ], "example": "apply_for_financing", "type": "string" }, "blocked_capabilities": { "items": { "description": "Capabilities this would unlock, or empty", "example": "accept_bnpl_payments", "type": "string" }, "type": "array" }, "cta": { "description": "The URL the call-to-action links to", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/settings/payments/", "type": "string" }, "cta_label": { "description": "Button label", "example": "Apply", "type": "string" }, "description": { "description": "Supporting copy, or empty", "example": "Let customers pay over time with buy now, pay later.", "type": "string" }, "icon_url": { "description": "Illustration icon URL, or `null`", "example": "https://whop.com/illustrations/orange/piggy-bank.svg", "type": [ "string", "null" ] }, "impact_score": { "description": "Estimated impact from 0-100, or `null` when not ranked", "example": 86, "type": [ "integer", "null" ] }, "reasoning": { "description": "Why this action was recommended, or `null`", "example": "Financing lifts conversion on the $249 ceramic coating, the priciest job on the menu.", "type": [ "string", "null" ] }, "status": { "description": "Always optional — never blocking", "enum": [ "optional" ], "example": "optional", "type": "string" }, "title": { "description": "Headline for the recommendation", "example": "Offer financing at checkout", "type": "string" } }, "required": [ "action", "status", "title", "description", "cta_label", "cta", "icon_url", "blocked_capabilities", "reasoning", "impact_score" ], "type": "object" }, "AccountRequiredAction": { "properties": { "action": { "description": "What the holder must do; new values may be added, so handle unknown actions gracefully", "enum": [ "deposit_funds", "review_held_payments", "submit_information_request", "update_automatic_withdrawal_method", "reauthorize_payout_methods", "update_payout_profile", "card_usage_review", "verify_identity", "scale_account_setup", "sign_formation_documents", "configure_tax_remitter", "add_vat_registration", "accept_payout_terms", "enable_two_factor_authentication", "respond_to_abuse_report" ], "example": "verify_identity", "type": "string" }, "blocked_capabilities": { "items": { "description": "Capabilities gated until this is resolved", "example": "standard_payout", "type": "string" }, "type": "array" }, "cta": { "description": "The URL the call-to-action links to, or null when there is no button", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/balance/", "type": [ "string", "null" ] }, "cta_label": { "description": "Button label, or empty when there is no button", "example": "Verify now", "type": "string" }, "description": { "description": "Supporting copy, or empty", "example": "Complete verification to withdraw your earnings.", "type": "string" }, "icon_url": { "description": "The URL of the action's illustration icon, or null if it has none", "example": "https://whop.com/illustrations/orange/shield.svg", "type": [ "string", "null" ] }, "status": { "description": "required (act now) or pending (under review)", "enum": [ "required", "pending" ], "example": "required", "type": "string" }, "title": { "description": "Headline for the action", "example": "Complete your identity verification", "type": "string" } }, "required": [ "action", "status", "title", "description", "cta_label", "cta", "icon_url", "blocked_capabilities" ], "type": "object" }, "AccountReserve": { "properties": { "amount": { "description": "Total held in this currency, in native units, as a decimal string. All dollar holdings are reported as one `usd` entry, matching how the balance row groups them.", "example": "125.5", "type": "string" }, "by_type": { "items": { "$ref": "#/components/schemas/AccountReserveType", "description": "The total split by why each part is held. Only reasons holding a non-zero amount appear, so these can sum to less than `amount`, never more." }, "type": "array" }, "currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`.", "example": "usd", "type": "string" }, "unlocks_by_date": { "items": { "$ref": "#/components/schemas/AccountReserveUnlock", "description": "When the held money unlocks, one entry per day, earliest first. Money whose release depends on something other than a date is left out, so these can sum to less than `amount`, never more." }, "type": "array" } }, "required": [ "currency", "amount", "by_type", "unlocks_by_date" ], "type": "object" }, "AccountReserveControl": { "properties": { "hold_period_days": { "description": "Number of days reserved funds are held before release.", "example": 14, "type": "integer" }, "percentage": { "description": "Percentage of incoming payment volume held in reserve. `null` when no reserve is applied.", "example": 15.0, "type": [ "number", "null" ] } }, "required": [ "percentage", "hold_period_days" ], "type": "object" }, "AccountReserveType": { "properties": { "amount": { "description": "Amount held for this reason, in native units, as a decimal string.", "example": "100.0", "type": "string" }, "hold_period_days": { "description": "Days money is currently held for this reason before it unlocks, or `null` when release depends on something other than time. Money already held keeps the terms it was taken under.", "example": 90, "type": [ "integer", "null" ] }, "percentage": { "description": "Percentage of each incoming payment currently held for this reason, or `null` when the reason is not a percentage of anything. Money already held keeps the release date it was given, which `unlocks_by_date` reflects.", "example": 25.0, "type": [ "number", "null" ] }, "type": { "description": "Why this part of the balance is held. `regular` is the account's standing risk reserve; `bnpl` and `sequra` cover buy-now-pay-later settlement; `preshipment_hold` covers a physical order that has not shipped yet; `fraud_hold` is held while activity is reviewed.", "enum": [ "regular", "bnpl", "sequra", "fraud_hold", "preshipment_hold" ], "example": "regular", "type": "string" } }, "required": [ "type", "amount", "percentage", "hold_period_days" ], "type": "object" }, "AccountReserveUnlock": { "properties": { "amount": { "description": "Amount unlocking that day across every reason, in native units, as a decimal string.", "example": "100.0", "type": "string" }, "by_type": { "items": { "$ref": "#/components/schemas/AccountReserveUnlockType", "description": "That day's amount split by why it is held. Only reasons unlocking a non-zero amount appear, so these can sum to less than `amount`, never more." }, "type": "array" }, "date": { "description": "The day this money unlocks, as an ISO 8601 date.", "example": "2026-01-01", "type": "string" } }, "required": [ "date", "amount", "by_type" ], "type": "object" }, "AccountReserveUnlockType": { "properties": { "amount": { "description": "Amount unlocking that day for this reason, in native units, as a decimal string.", "example": "100.0", "type": "string" }, "type": { "description": "Why this part of the day's unlock is held, matching `type` on the reserve's `by_type`.", "enum": [ "regular", "bnpl", "sequra", "fraud_hold", "preshipment_hold" ], "example": "regular", "type": "string" } }, "required": [ "type", "amount" ], "type": "object" }, "AccountResolutionCenterAutoRefundControl": { "properties": { "card_threshold_usd": { "description": "Maximum card-funded resolution center case amount automatically refunded in USD. `null` when automatic refunds are disabled for cards.", "example": 50, "type": [ "number", "null" ] }, "financing_threshold_usd": { "description": "Maximum financing-funded resolution center case amount automatically refunded in USD. `null` when automatic refunds are disabled for financing.", "example": 25, "type": [ "number", "null" ] }, "locked": { "description": "Whether the account owner is prevented from changing these thresholds.", "example": false, "type": "boolean" }, "paypal_threshold_usd": { "description": "Maximum PayPal-funded resolution center case amount automatically refunded in USD. `null` when automatic refunds are disabled for PayPal.", "example": 40, "type": [ "number", "null" ] } }, "required": [ "card_threshold_usd", "financing_threshold_usd", "paypal_threshold_usd", "locked" ], "type": "object" }, "AccountSearchResult": { "properties": { "created_at": { "description": "When the account was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "Account public route identifier.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Account display name.", "example": "Shine Time Detailing", "type": "string" } }, "required": [ "id", "title", "route", "created_at" ], "type": "object" }, "AccountSocialLink": { "properties": { "id": { "description": "The ID of the social link", "example": "social_1", "type": "string" }, "title": { "description": "The optional display title for the social link", "example": "@shinetimedetail", "type": [ "string", "null" ] }, "url": { "description": "The social link URL", "example": "https://instagram.com/shinetimedetail", "type": "string" }, "website": { "description": "The social platform for this link", "enum": [ "x", "instagram", "facebook", "tiktok", "youtube", "linkedin", "twitch", "website", "custom" ], "example": "instagram", "type": "string" } }, "required": [ "id", "website", "url", "title" ], "type": "object" }, "AccountStorePageConfig": { "properties": { "accent_color": { "description": "Accent color used on the account store page.", "enum": [ "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", null ], "example": "red", "type": [ "string", "null" ] }, "layout": { "description": "Layout used on the account store page.", "enum": [ "featured", "compact", null ], "example": "compact", "type": [ "string", "null" ] }, "profile_variant": { "description": "Profile presentation used on the account store page.", "enum": [ "personal", "business", null ], "example": "business", "type": [ "string", "null" ] }, "whop_affiliate_link": { "description": "Whether the account store page shows a Whop affiliate link.", "example": true, "type": "boolean" } }, "required": [ "accent_color", "layout", "profile_variant", "whop_affiliate_link" ], "type": "object" }, "AccountSummary": { "properties": { "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Account display name.", "example": "Acme Bookkeeping", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "AccountTaxIdentifier": { "properties": { "id": { "description": "Tax identifier ID.", "example": "txid_xxxxxxxxxxxxxx", "type": "string" }, "tax_id_type": { "description": "Tax ID type.", "enum": [ "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" ], "example": "eu_vat", "type": "string" }, "tax_id_value": { "description": "Tax ID value.", "example": "DE123456789", "type": "string" } }, "required": [ "id", "tax_id_type", "tax_id_value" ], "type": "object" }, "AccountWallet": { "properties": { "address": { "description": "The on-chain address of the wallet", "example": "0xabc123", "type": "string" }, "id": { "description": "Wallet ID, prefixed `wallet_`.", "example": "cwal_xxxxxxxxxxxxxx", "type": "string" }, "network": { "description": "The blockchain network the wallet lives on", "enum": [ "solana", "ethereum", "bitcoin" ], "example": "ethereum", "type": "string" } }, "required": [ "id", "address", "network" ], "type": "object" }, "AccountWithdrawalScheduleControl": { "properties": { "day": { "description": "Day the automatic withdrawal runs on: 0-6 (Sunday-Saturday) for `weekly`, 1-31 for `monthly`. `null` for `manual` and `daily`.", "example": null, "type": [ "integer", "null" ] }, "frequency": { "description": "How often the account's balance automatically withdraws.", "enum": [ "manual", "daily", "weekly", "monthly" ], "example": "manual", "type": "string" }, "next_payout_date": { "description": "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.", "example": null, "type": [ "string", "null" ] } }, "required": [ "frequency", "day", "next_payout_date" ], "type": "object" }, "Ad": { "properties": { "ad_campaign": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad campaign this ad belongs to." }, "ad_group": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad group this ad belongs to." }, "added_to_cart_value": { "description": "USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1850.0, "type": "number" }, "added_to_carts": { "description": "Whop pixel-attributed add-to-cart events, last-click.", "example": 74, "type": "number" }, "call_to_action": { "description": "The call-to-action button shown on the ad.", "enum": [ "learn_more", "shop_now", "sign_up", "subscribe", "get_started", "book_now", "apply_now", "contact_us", "download", "order_now", "buy_now", "get_quote", "message_page", "whatsapp_message", "instagram_message", "call_now", "get_directions", "send_updates", "get_offer", "watch_more", "listen_now", "play_game", "open_link", "no_button", "get_offer_view", "get_event_tickets", "see_menu", "request_time", "event_rsvp", "see_details", "view_instagram_profile", "donate_now", "see_more", "visit_site", null ], "example": "learn_more", "type": [ "string", "null" ] }, "click_through_rate": { "description": "Clicks divided by impressions, between 0 and 1.", "example": 0.0261, "type": "number" }, "clicks": { "description": "The number of clicks.", "example": 1337, "type": "number" }, "completed_registration_value": { "description": "USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 95.0, "type": "number" }, "completed_registrations": { "description": "Whop pixel-attributed complete-registration events, last-click.", "example": 19, "type": "number" }, "contact_value": { "description": "USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 175.0, "type": "number" }, "contacts": { "description": "Whop pixel-attributed contact events, last-click.", "example": 27, "type": "number" }, "cost_per_added_to_cart": { "description": "Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.", "example": 6.515675675675676, "type": [ "number", "null" ] }, "cost_per_click": { "description": "Spend divided by clicks; 0 when there are no clicks.", "example": 0.36, "type": "number" }, "cost_per_completed_registration": { "description": "Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.", "example": 25.37684210526316, "type": [ "number", "null" ] }, "cost_per_contact": { "description": "Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.", "example": 17.85777777777778, "type": [ "number", "null" ] }, "cost_per_lead": { "description": "Spend divided by attributed leads; null when leads are not a goal and none are attributed.", "example": 3.984793388429752, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Spend per 1,000 impressions; 0 when there are no impressions.", "example": 9.42, "type": "number" }, "cost_per_purchase": { "description": "Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.", "example": 12.68842105263158, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.", "example": 7.653333333333333, "type": [ "number", "null" ] }, "cost_per_schedule": { "description": "Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.", "example": 10.48173913043478, "type": [ "number", "null" ] }, "cost_per_submitted_application": { "description": "Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.", "example": 40.18, "type": [ "number", "null" ] }, "cost_per_unique_click": { "description": "Spend divided by unique clicks; null when there are no unique clicks.", "example": 0.48, "type": [ "number", "null" ] }, "cost_per_viewed_content": { "description": "Spend divided by attributed view-content events; null when they are not the goal and none are attributed.", "example": 0.2253084112149533, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "creatives": { "items": { "$ref": "#/components/schemas/AdCreative", "description": "The creative assets used by this ad. The original asset has a null format; square, vertical, and horizontal entries are placement-specific variants. A carousel ad returns one format-null entry per attachment, in order." }, "type": "array" }, "custom_conversions": { "description": "Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.", "example": 63, "type": "number" }, "custom_event_counts": { "description": "Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom_conversions but omitted here, so these values sum to at most custom_conversions.", "example": { "booked_detail": 63 }, "type": "object" }, "custom_event_values": { "description": "Conversion value attributed to each custom event, keyed by event name like custom_event_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0.", "example": { "booked_detail": 4820.0 }, "type": "object" }, "delivery_status": { "description": "Whether the ad is delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.", "enum": [ "in_appeal", "rejected", "in_review", "draft", "campaign_paused", "ad_group_paused", "paused", "processing", "issues", "scheduled", "learning_limited", "learning", "active" ], "example": "paused", "type": "string" }, "descriptions": { "items": { "$ref": "#/components/schemas/AdText", "description": "The description shown on the ad. Entries with a null language are the ad's own copy; a Meta ad with translations also carries one entry per other language." }, "type": "array" }, "existing_post_id": { "description": "The post you pointed this ad at, when it promotes one you already published — a Facebook post, Instagram media, or TikTok video ID. `null` when the ad uses uploaded creatives.", "example": "xxxxxxxxxxxxxxxx_98765", "type": [ "string", "null" ] }, "external_accounts": { "items": { "$ref": "#/components/schemas/AdEntityReference", "description": "The external accounts the ad runs under — its Facebook page and Instagram profile — each referenced by ID, prefixed `sacc_`." }, "type": "array" }, "frequency": { "description": "Platform-reported impressions divided by reach.", "example": null, "type": [ "number", "null" ] }, "headlines": { "items": { "$ref": "#/components/schemas/AdText", "description": "The headline shown on the ad. Entries with a null language are the ad's own copy; a Meta ad with translations also carries one entry per other language." }, "type": "array" }, "id": { "description": "Unique identifier for the ad, prefixed `ad_`.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "The number of impressions.", "example": 51204, "type": "number" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting this ad. Empty when there are none." }, "type": "array" }, "lead_form": { "description": "The instant lead form shown when someone taps this ad. `null` when the ad group's conversion_location is not an instant-form destination.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadForm" }, { "type": "null" } ] }, "lead_form_id": { "description": "The ad platform's ID for the instant form the ad uses. Set when the ad references an existing form via `lead_form_id`, or once a form built from `lead_form` has been created on the platform.", "example": "1037724182084885", "type": [ "string", "null" ] }, "lead_value": { "description": "USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1180.0, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 121, "type": "number" }, "link_clicks": { "description": "Page views on your destination from people who clicked the ad, recorded by the Whop pixel. Counted the same way on every ad platform.", "example": 1071, "type": "number" }, "messaging_config": { "description": "Welcome message for click-to-message ads, shown when the conversation opens. `null` when the ad has none.", "oneOf": [ { "$ref": "#/components/schemas/AdMessagingConfig" }, { "type": "null" } ] }, "multi_advertiser_ads": { "description": "Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.", "example": true, "type": "boolean" }, "music": { "description": "The advertiser-uploaded MP3 a TikTok carousel ad plays. TikTok-only; `null` elsewhere and for non-carousel ads.", "oneOf": [ { "$ref": "#/components/schemas/AdMusic" }, { "type": "null" } ] }, "platform": { "description": "The ad platform this ad runs on.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" }, "post_id": { "description": "The post the ad network serves for this ad, as `pageID_postID` on Meta — the post Meta created for an uploaded creative, or the post being promoted. Use it to open the live post, or to promote the same post from another ad. `null` until the network has created the post.", "example": "xxxxxxxxxxxxxxxx_98765", "type": [ "string", "null" ] }, "post_source": { "description": "Identifies the network that owns `existing_post_id`; `null` when the ad uses uploaded creatives.", "enum": [ "facebook", "instagram", null ], "example": "facebook", "type": [ "string", "null" ] }, "post_thumbnail_url": { "description": "Preview image of the post named by `existing_post_id`. `null` for ads that use uploaded creatives, or until the post's media has been fetched from the network.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "primary_texts": { "items": { "$ref": "#/components/schemas/AdText", "description": "The primary text shown in the ad body. Entries with a null language are the ad's own copy (several make text variations); a Meta ad with translations also carries one entry per other language." }, "type": "array" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 9462.0, "type": "number" }, "purchases": { "description": "Whop pixel-attributed purchases, last-click.", "example": 38, "type": "number" }, "reach": { "description": "The number of unique people who saw this.", "example": 0, "type": "number" }, "result_event": { "description": "The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.", "enum": [ "purchase", "lead", "schedule", "submit_application", "contact", "complete_registration", "view_content", "add_to_cart", "custom", "messaging_conversation", null ], "example": "custom", "type": [ "string", "null" ] }, "result_event_name": { "description": "The merchant-defined event name when result_event is custom; null for the standard events.", "example": "booked_detail", "type": [ "string", "null" ] }, "results": { "description": "The Whop pixel-attributed count behind result_event. When a campaign's ad groups optimize different goals there is no single result_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for.", "example": 63, "type": [ "number", "null" ] }, "return_on_ad_spend": { "description": "Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.", "example": 19.62419113987058, "type": "number" }, "schedule_value": { "description": "USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 640.0, "type": "number" }, "schedules": { "description": "Whop pixel-attributed schedule events, last-click.", "example": 46, "type": "number" }, "spend": { "description": "The amount charged, in spend_currency.", "example": 482.16, "type": "number" }, "spend_currency": { "description": "The ISO 4217 currency code of all monetary metrics.", "example": "usd", "type": [ "string", "null" ] }, "status": { "description": "Whether the ad is enabled. `active` and `paused` are set by you; `in_review` and `rejected` come from ad review.", "enum": [ "active", "paused", "in_review", "rejected" ], "example": "paused", "type": "string" }, "submitted_application_value": { "description": "USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 300.0, "type": "number" }, "submitted_applications": { "description": "Whop pixel-attributed submit-application events, last-click.", "example": 12, "type": "number" }, "title": { "description": "Display title of the ad.", "example": "Ceramic coating — new ad group", "type": [ "string", "null" ] }, "translations": { "description": "The languages a Meta ad runs in besides its own. Each viewer sees the version for their language, or the ad's own copy. `null` when the ad runs in one language.", "oneOf": [ { "$ref": "#/components/schemas/AdTranslations" }, { "type": "null" } ] }, "unique_click_through_rate": { "description": "Unique clicks divided by impressions, between 0 and 1.", "example": null, "type": [ "number", "null" ] }, "unique_clicks": { "description": "People who clicked, reported by the Whop pixel, counted once per person.", "example": 1012, "type": "number" }, "updated_at": { "description": "When the ad was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "url": { "description": "The URL the ad links to, without its query string. Parameters belong in `url_parameters`; any you send on `url` are moved there.", "example": "https://shinetime.example/ceramic-coating", "type": [ "string", "null" ] }, "url_parameters": { "description": "Every query parameter appended to the URL, keyed by parameter name — including any you sent on `url` itself. Whop adds its own click-attribution parameters on top; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.", "example": {}, "type": "object" }, "viewed_content_value": { "description": "USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 0.0, "type": "number" }, "viewed_contents": { "description": "Whop pixel-attributed view-content events, last-click.", "example": 2140, "type": "number" } }, "required": [ "click_through_rate", "clicks", "cost_per_click", "cost_per_unique_click", "cost_per_lead", "cost_per_mille", "cost_per_purchase", "cost_per_schedule", "cost_per_submitted_application", "cost_per_contact", "cost_per_completed_registration", "cost_per_viewed_content", "cost_per_added_to_cart", "cost_per_result", "frequency", "impressions", "leads", "link_clicks", "purchase_value", "purchases", "reach", "result_event", "result_event_name", "results", "return_on_ad_spend", "spend", "spend_currency", "unique_click_through_rate", "unique_clicks", "schedules", "submitted_applications", "contacts", "completed_registrations", "viewed_contents", "added_to_carts", "custom_conversions", "custom_event_counts", "custom_event_values", "lead_value", "schedule_value", "submitted_application_value", "contact_value", "completed_registration_value", "viewed_content_value", "added_to_cart_value", "id", "title", "platform", "status", "delivery_status", "primary_texts", "headlines", "descriptions", "call_to_action", "url", "url_parameters", "post_id", "existing_post_id", "post_source", "post_thumbnail_url", "ad_group", "ad_campaign", "creatives", "external_accounts", "created_at", "updated_at", "issues" ], "type": "object" }, "AdCampaign": { "properties": { "added_to_cart_value": { "description": "USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 12650.0, "type": "number" }, "added_to_carts": { "description": "Whop pixel-attributed add-to-cart events, last-click.", "example": 165, "type": "number" }, "bid_type": { "description": "How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, and `maximum_target` never bids above a cap.", "enum": [ "minimum_cost", "average_target", "maximum_target", null ], "example": "average_target", "type": [ "string", "null" ] }, "budget_amount": { "description": "The campaign's budget in USD, which is what it is stored and billed in. `null` when each ad group sets its own budget instead.", "example": 50.0, "type": [ "number", "null" ] }, "budget_amount_local": { "description": "The same budget stated in `budget_currency` at today's exchange rate, for display in the account's ads reporting currency. `null` when `budget_amount` is.", "example": 50.0, "type": [ "number", "null" ] }, "budget_currency": { "description": "The ISO 4217 code `budget_amount_local` is in: the account's `ads_reporting_currency` preference. `usd` unless the account changed it.", "example": "usd", "type": "string" }, "budget_optimization": { "description": "Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`).", "enum": [ "ad_campaign", "ad_group", null ], "example": "ad_group", "type": [ "string", "null" ] }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the campaign's full run (`lifetime`).", "enum": [ "daily", "lifetime", null ], "example": "daily", "type": [ "string", "null" ] }, "campaign_type": { "description": "The kind of campaign, fixed at creation. `standard` is the ad network's standard campaign; `search` shows text ads on search results for the ad groups' keywords.", "enum": [ "standard", "search" ], "example": "standard", "type": "string" }, "click_through_rate": { "description": "Clicks divided by impressions, between 0 and 1.", "example": 0.025, "type": "number" }, "clicks": { "description": "The number of clicks.", "example": 5500, "type": "number" }, "completed_registration_value": { "description": "USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1650.0, "type": "number" }, "completed_registrations": { "description": "Whop pixel-attributed complete-registration events, last-click.", "example": 55, "type": "number" }, "contact_value": { "description": "USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 2640.0, "type": "number" }, "contacts": { "description": "Whop pixel-attributed contact events, last-click.", "example": 88, "type": "number" }, "cost_per_added_to_cart": { "description": "Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.", "example": 8.0, "type": [ "number", "null" ] }, "cost_per_click": { "description": "Spend divided by clicks; 0 when there are no clicks.", "example": 0.24, "type": "number" }, "cost_per_completed_registration": { "description": "Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.", "example": 24.0, "type": [ "number", "null" ] }, "cost_per_contact": { "description": "Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.", "example": 15.0, "type": [ "number", "null" ] }, "cost_per_lead": { "description": "Spend divided by attributed leads; null when leads are not a goal and none are attributed.", "example": 10.0, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Spend per 1,000 impressions; 0 when there are no impressions.", "example": 6.0, "type": "number" }, "cost_per_purchase": { "description": "Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.", "example": 30.0, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.", "example": 40.0, "type": [ "number", "null" ] }, "cost_per_schedule": { "description": "Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.", "example": 22.0, "type": [ "number", "null" ] }, "cost_per_submitted_application": { "description": "Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.", "example": 120.0, "type": [ "number", "null" ] }, "cost_per_unique_click": { "description": "Spend divided by unique clicks; null when there are no unique clicks.", "example": 0.4, "type": [ "number", "null" ] }, "cost_per_viewed_content": { "description": "Spend divided by attributed view-content events; null when they are not the goal and none are attributed.", "example": 1.1, "type": [ "number", "null" ] }, "created_at": { "description": "When the campaign was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "custom_conversions": { "description": "Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.", "example": 41, "type": "number" }, "custom_event_counts": { "description": "Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom_conversions but omitted here, so these values sum to at most custom_conversions.", "example": { "gift_card_purchased": 5, "quote_requested": 33 }, "type": "object" }, "custom_event_values": { "description": "Conversion value attributed to each custom event, keyed by event name like custom_event_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0.", "example": { "gift_card_purchased": 750.0, "quote_requested": 0.0 }, "type": "object" }, "delivery_status": { "description": "Whether the campaign's ads are delivering right now, and if not, why. Content review is in_review; a campaign waiting to start is processing. Account billing failures set payment_failed without changing the configured status. Successful payment retry clears that block and recalculates delivery. When several states apply at once, the highest-precedence one is returned.", "enum": [ "payment_failed", "in_appeal", "all_ads_rejected", "draft", "no_ad_groups", "no_ads", "paused", "in_review", "learning", "processing", "issues", "scheduled", "completed", "ad_groups_off", "active" ], "example": "issues", "type": "string" }, "desired_cost_per_result": { "description": "The cost per result, in USD, the advertiser wants this campaign to achieve. A target only: it is not a bid, cost cap, or bid cap, and doesn't change how the campaign's ads bid. `null` when no target is set.", "example": 4.5, "type": [ "number", "null" ] }, "ends_at": { "description": "Google only: when the campaign stops delivering, as an ISO 8601 timestamp. `null` runs it until paused.", "type": [ "string", "null" ] }, "frequency": { "description": "Platform-reported impressions divided by reach.", "example": null, "type": [ "number", "null" ] }, "id": { "description": "Unique identifier for the ad campaign, prefixed `adcamp_`.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "The number of impressions.", "example": 220000, "type": "number" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting the campaign and its descendant ad groups and ads." }, "type": "array" }, "lead_value": { "description": "USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 3960.0, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 132, "type": "number" }, "link_clicks": { "description": "Page views on your destination from people who clicked the ad, recorded by the Whop pixel. Counted the same way on every ad platform.", "example": 4400, "type": "number" }, "objective": { "description": "The goal the campaign optimizes toward.", "enum": [ "awareness", "traffic", "engagement", "leads", "sales", null ], "example": "leads", "type": [ "string", "null" ] }, "optimization_goal": { "description": "The event the campaign optimizes for when a single goal is set campaign-wide. `null` when each ad group sets its own optimization_goal.", "example": null, "type": [ "string", "null" ] }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 7920.0, "type": "number" }, "purchases": { "description": "Whop pixel-attributed purchases, last-click.", "example": 44, "type": "number" }, "reach": { "description": "The number of unique people who saw this.", "example": 0, "type": "number" }, "result_event": { "description": "The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.", "enum": [ "purchase", "lead", "schedule", "submit_application", "contact", "complete_registration", "view_content", "add_to_cart", "custom", "messaging_conversation", null ], "example": "custom", "type": [ "string", "null" ] }, "result_event_name": { "description": "The merchant-defined event name when result_event is custom; null for the standard events.", "example": "quote_requested", "type": [ "string", "null" ] }, "results": { "description": "The Whop pixel-attributed count behind result_event. When a campaign's ad groups optimize different goals there is no single result_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for.", "example": 33, "type": [ "number", "null" ] }, "return_on_ad_spend": { "description": "Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.", "example": 6.0, "type": "number" }, "schedule_value": { "description": "USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 5400.0, "type": "number" }, "schedules": { "description": "Whop pixel-attributed schedule events, last-click.", "example": 60, "type": "number" }, "special_ad_categories": { "items": { "description": "Regulated categories the campaign is declared under. Ads in these categories are subject to extra targeting restrictions. Empty when none apply.", "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "employment", "type": "string" }, "type": "array" }, "spend": { "description": "The amount charged, in spend_currency.", "example": 1320.0, "type": "number" }, "spend_currency": { "description": "The ISO 4217 currency code of all monetary metrics.", "example": "usd", "type": [ "string", "null" ] }, "starts_at": { "description": "Google only: when the campaign starts delivering, as an ISO 8601 timestamp. `null` starts it as soon as it launches.", "type": [ "string", "null" ] }, "status": { "description": "The configured lifecycle status of the ad campaign. Billing failures preserve active or paused here and set delivery_status to payment_failed.", "enum": [ "active", "paused", "inactive", "stale", "pending_refund", "payment_failed", "draft", "in_review", "flagged", "importing", "imported", "duplicating" ], "example": "active", "type": "string" }, "submitted_application_value": { "description": "USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1320.0, "type": "number" }, "submitted_applications": { "description": "Whop pixel-attributed submit-application events, last-click.", "example": 11, "type": "number" }, "title": { "description": "Display name of the ad campaign.", "example": "Ceramic coating — Austin leads", "type": "string" }, "unique_click_through_rate": { "description": "Unique clicks divided by impressions, between 0 and 1.", "example": null, "type": [ "number", "null" ] }, "unique_clicks": { "description": "People who clicked, reported by the Whop pixel, counted once per person.", "example": 3300, "type": "number" }, "updated_at": { "description": "When the campaign was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "viewed_content_value": { "description": "USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 8400.0, "type": "number" }, "viewed_contents": { "description": "Whop pixel-attributed view-content events, last-click.", "example": 1200, "type": "number" } }, "required": [ "click_through_rate", "clicks", "cost_per_click", "cost_per_unique_click", "cost_per_lead", "cost_per_mille", "cost_per_purchase", "cost_per_schedule", "cost_per_submitted_application", "cost_per_contact", "cost_per_completed_registration", "cost_per_viewed_content", "cost_per_added_to_cart", "cost_per_result", "frequency", "impressions", "leads", "link_clicks", "purchase_value", "purchases", "reach", "result_event", "result_event_name", "results", "return_on_ad_spend", "spend", "spend_currency", "unique_click_through_rate", "unique_clicks", "schedules", "submitted_applications", "contacts", "completed_registrations", "viewed_contents", "added_to_carts", "custom_conversions", "custom_event_counts", "custom_event_values", "lead_value", "schedule_value", "submitted_application_value", "contact_value", "completed_registration_value", "viewed_content_value", "added_to_cart_value", "id", "title", "status", "delivery_status", "platform", "campaign_type", "objective", "special_ad_categories", "optimization_goal", "budget_amount", "budget_amount_local", "budget_currency", "budget_type", "budget_optimization", "created_at", "updated_at", "issues" ], "type": "object" }, "AdConversionValueRule": { "properties": { "account_id": { "description": "Business that owns this shared, editable rule.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "adjustment_type": { "description": "Set a fixed amount or change the original value by a signed percentage.", "enum": [ "fixed", "percentage" ], "example": "fixed", "type": "string" }, "created_at": { "description": "When the rule was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/AdConversionValueRuleEvent", "description": "Events adjusted on every selected target." }, "type": "array" }, "fixed_value": { "description": "Amount sent for a fixed rule. Null for a percentage rule.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Conversion value rule ID, prefixed adcvr_.", "example": "adcvr_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Free-form string keys and values for the caller.", "example": {}, "type": "object" }, "percentage_change": { "description": "Signed percent change: 20 increases by 20%, negative 20 decreases by 20%. The sent value cannot go below zero. Null for a fixed rule.", "example": null, "type": [ "number", "null" ] }, "status": { "description": "Whether this rule is active or paused.", "enum": [ "active", "paused" ], "example": "active", "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/AdConversionValueRuleTarget", "description": "Targets covered by this rule. Every selected event applies to every target." }, "type": "array" }, "updated_at": { "description": "When the rule was edited, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "account_id", "status", "targets", "events", "adjustment_type", "fixed_value", "percentage_change", "metadata", "created_at", "updated_at" ], "type": "object" }, "AdConversionValueRuleEvent": { "properties": { "custom_name": { "description": "Exact custom event name. Null for standard events.", "example": null, "type": [ "string", "null" ] }, "event_name": { "description": "Event to adjust. Purchase includes Whop purchases and external purchase events.", "enum": [ "purchase", "subscribe", "start_trial", "lead", "complete_registration", "submit_application", "schedule", "contact", "view_content", "add_to_cart", "custom" ], "example": "lead", "type": "string" } }, "required": [ "event_name", "custom_name" ], "type": "object" }, "AdConversionValueRuleTarget": { "properties": { "platform": { "description": "Ad platform that receives the adjusted value.", "enum": [ "tiktok", "meta", "google" ], "example": "meta", "type": "string" }, "resource_id": { "description": "Selected campaign, ad group, or ad ID. Null for a business target.", "example": null, "type": [ "string", "null" ] }, "resource_title": { "description": "Name of the selected item. Null when it is no longer available.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "scope": { "description": "Business, campaign, ad group, or ad covered by this target.", "enum": [ "business", "campaign", "ad_group", "ad" ], "example": "business", "type": "string" } }, "required": [ "scope", "resource_id", "resource_title", "platform" ], "type": "object" }, "AdCreative": { "properties": { "crop": { "description": "The saved crop window for this creative, in source image pixels. Null for the original asset or a format that has not been cropped.", "oneOf": [ { "$ref": "#/components/schemas/AdCreativeCrop" }, { "type": "null" } ] }, "format": { "description": "The placement variant this asset covers, or null for the original asset.", "enum": [ "square", "vertical", "horizontal", null ], "example": "vertical", "type": [ "string", "null" ] }, "id": { "description": "The creative attachment's file id.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "language": { "description": "ISO 639 code of the language this image or video is shown for, such as `es`. On an ad with translations, the ad's own creative carries `translations.source_language`. It's `null` on an ad without translations.", "example": null, "type": [ "string", "null" ] }, "media_type": { "description": "The kind of asset, image or video.", "example": "image", "type": [ "string", "null" ] }, "url": { "description": "CDN url of the asset.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "format", "url", "media_type", "crop", "language" ], "type": "object" }, "AdCreativeCrop": { "properties": { "height": { "description": "Height of the crop window in source pixels.", "example": 1000, "type": "number" }, "width": { "description": "Width of the crop window in source pixels.", "example": 1000, "type": "number" }, "x": { "description": "Left edge of the crop window in source pixels.", "example": 40, "type": "number" }, "y": { "description": "Top edge of the crop window in source pixels.", "example": 0, "type": "number" } }, "required": [ "x", "y", "width", "height" ], "type": "object" }, "AdEntityReference": { "properties": { "id": { "description": "The referenced entity's id.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "AdGroup": { "properties": { "ad_campaign": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad campaign this ad group belongs to." }, "added_to_cart_value": { "description": "USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 12650.0, "type": "number" }, "added_to_carts": { "description": "Whop pixel-attributed add-to-cart events, last-click.", "example": 165, "type": "number" }, "audiences": { "$ref": "#/components/schemas/AdGroupAudiences", "description": "Saved audiences this ad group delivers to or excludes." }, "bid_type": { "description": "How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.", "enum": [ "minimum_cost", "average_target", "maximum_target", null ], "example": "average_target", "type": [ "string", "null" ] }, "budget_amount": { "description": "This ad group's budget in USD, which is what it is stored and billed in. `null` when the budget is set on the campaign instead.", "example": 60.0, "type": [ "number", "null" ] }, "budget_amount_local": { "description": "The same budget stated in `budget_currency` at today's exchange rate, for display in the account's ads reporting currency. `null` when `budget_amount` is.", "example": 60.0, "type": [ "number", "null" ] }, "budget_currency": { "description": "The ISO 4217 code `budget_amount_local` is in: the account's `ads_reporting_currency` preference. `usd` unless the account changed it.", "example": "usd", "type": "string" }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the ad group's full run (`lifetime`). A `lifetime` ad group also needs `ends_at`, at least 24 hours after it starts.", "enum": [ "daily", "lifetime", null ], "example": "daily", "type": [ "string", "null" ] }, "click_through_rate": { "description": "Clicks divided by impressions, between 0 and 1.", "example": 0.025, "type": "number" }, "clicks": { "description": "The number of clicks.", "example": 5500, "type": "number" }, "completed_registration_value": { "description": "USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1650.0, "type": "number" }, "completed_registrations": { "description": "Whop pixel-attributed complete-registration events, last-click.", "example": 55, "type": "number" }, "contact_value": { "description": "USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 2640.0, "type": "number" }, "contacts": { "description": "Whop pixel-attributed contact events, last-click.", "example": 88, "type": "number" }, "conversion_event": { "$ref": "#/components/schemas/ConversionEvent" }, "conversion_location": { "description": "Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission.", "enum": [ "website", "profile", "instagram_and_facebook", "instagram_profile", "messaging", "on_ad", "instant_forms", "instant_forms_and_messenger", "website_and_instant_forms", null ], "example": "website", "type": [ "string", "null" ] }, "cost_per_added_to_cart": { "description": "Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.", "example": 8.0, "type": [ "number", "null" ] }, "cost_per_click": { "description": "Spend divided by clicks; 0 when there are no clicks.", "example": 0.24, "type": "number" }, "cost_per_completed_registration": { "description": "Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.", "example": 24.0, "type": [ "number", "null" ] }, "cost_per_contact": { "description": "Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.", "example": 15.0, "type": [ "number", "null" ] }, "cost_per_lead": { "description": "Spend divided by attributed leads; null when leads are not a goal and none are attributed.", "example": 10.0, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Spend per 1,000 impressions; 0 when there are no impressions.", "example": 6.0, "type": "number" }, "cost_per_purchase": { "description": "Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.", "example": 30.0, "type": [ "number", "null" ] }, "cost_per_result": { "description": "Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.", "example": 40.0, "type": [ "number", "null" ] }, "cost_per_schedule": { "description": "Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.", "example": 22.0, "type": [ "number", "null" ] }, "cost_per_submitted_application": { "description": "Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.", "example": 120.0, "type": [ "number", "null" ] }, "cost_per_unique_click": { "description": "Spend divided by unique clicks; null when there are no unique clicks.", "example": 0.4, "type": [ "number", "null" ] }, "cost_per_viewed_content": { "description": "Spend divided by attributed view-content events; null when they are not the goal and none are attributed.", "example": 1.1, "type": [ "number", "null" ] }, "created_at": { "description": "When the ad group was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "custom_conversions": { "description": "Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.", "example": 41, "type": "number" }, "custom_event_counts": { "description": "Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom_conversions but omitted here, so these values sum to at most custom_conversions.", "example": { "gift_card_purchased": 5, "quote_requested": 33 }, "type": "object" }, "custom_event_values": { "description": "Conversion value attributed to each custom event, keyed by event name like custom_event_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0.", "example": { "gift_card_purchased": 750.0, "quote_requested": 0.0 }, "type": "object" }, "delivery_schedule": { "description": "Hours the ad group delivers in each week, keyed by day. Days it doesn't deliver are omitted. `null` when it delivers at every hour. Some platforms need a lifetime `budget_type` for a schedule, on the ad group or on its campaign when the campaign holds the budget.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupDeliverySchedule" }, { "type": "null" } ] }, "delivery_status": { "description": "Whether ads in this ad group are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.", "enum": [ "in_appeal", "all_ads_rejected", "rejected", "draft", "no_ads", "campaign_paused", "paused", "processing", "issues", "scheduled", "completed", "ads_off", "learning_limited", "learning", "active" ], "example": "no_ads", "type": "string" }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographics", "description": "Age, gender, and automatic-audience targeting." }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`). `null` for `minimum_cost` bidding.", "example": 40.0, "type": [ "number", "null" ] }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargeting", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. Can't be combined with automatic audience targeting. Special ad category campaigns are limited to approved interests." }, "devices": { "$ref": "#/components/schemas/AdGroupDevices", "description": "Device platforms and operating systems targeted." }, "dynamic_creative": { "description": "Whether the ad platform automatically mixes and matches this ad group's creatives and copy to find the best-performing combinations.", "example": false, "type": "boolean" }, "ends_at": { "description": "When the ad group stops delivering, as an ISO 8601 timestamp. `null` when it runs until paused.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "frequency": { "description": "Platform-reported impressions divided by reach.", "example": null, "type": [ "number", "null" ] }, "frequency_cap": { "description": "Cap on how often one person sees ads from this ad group, or from the whole campaign under a campaign budget, where every ad group shares it. Only available when the ad group optimizes for reach or ThruPlay; `null` when uncapped.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupFrequencyCap" }, { "type": "null" } ] }, "id": { "description": "Unique identifier for the ad group, prefixed `adgrp_`.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "impressions": { "description": "The number of impressions.", "example": 220000, "type": "number" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting this ad group and its ads. Empty when there are none." }, "type": "array" }, "keywords": { "items": { "$ref": "#/components/schemas/AdGroupKeyword", "description": "Search terms this ad group's ads can show for, and terms they never show for. Search campaigns only, where each ad group needs at least one before launch." }, "type": "array" }, "languages": { "items": { "description": "Languages targeted, as ISO 639 codes such as `en` or `es`. A region-specific locale with no ISO code appears as its numeric platform locale key. Empty targets all languages.", "example": "en", "type": "string" }, "type": "array" }, "lead_value": { "description": "USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 3960.0, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 132, "type": "number" }, "learning_progress": { "description": "Progress toward the ad platform's learning conversion threshold for this ad group. Null unless it is learning or learning limited and the platform reports valid counts. Reaching the threshold does not determine delivery status.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupLearningProgress" }, { "type": "null" } ] }, "link_clicks": { "description": "Page views on your destination from people who clicked the ad, recorded by the Whop pixel. Counted the same way on every ad platform.", "example": 4400, "type": "number" }, "message_apps": { "items": { "description": "Apps the conversation opens in when `conversion_location` is `messaging`. Empty for other conversion locations.", "enum": [ "messenger", "instagram", "whatsapp" ], "example": "instagram", "type": "string" }, "type": "array" }, "minimum_daily_spend": { "description": "Minimum the ad group tries to spend each day. `null` when no floor is set.", "example": 25.0, "type": [ "number", "null" ] }, "optimization_goal": { "description": "The result the ad group's delivery is optimized to get the most of.", "enum": [ "conversions", "link_clicks", "landing_page_views", "reach", "impressions", "engagement", "conversations", "video_views", "two_second_views", "page_likes", "social_profile", "ad_recall_lift", "event_responses", "reminders_set", "lead_generation", "quality_lead", "value", "profile_and_page_engagement", null ], "example": "conversions", "type": [ "string", "null" ] }, "placements": { "items": { "$ref": "#/components/schemas/AdGroupPlacement", "description": "Where ads can appear, per platform. Empty when placements are chosen automatically." }, "type": "array" }, "platform": { "description": "The ad platform this ad group runs on.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 7920.0, "type": "number" }, "purchases": { "description": "Whop pixel-attributed purchases, last-click.", "example": 44, "type": "number" }, "reach": { "description": "The number of unique people who saw this.", "example": 0, "type": "number" }, "regions": { "$ref": "#/components/schemas/AdGroupRegions", "description": "Locations targeted and excluded." }, "result_event": { "description": "The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.", "enum": [ "purchase", "lead", "schedule", "submit_application", "contact", "complete_registration", "view_content", "add_to_cart", "custom", "messaging_conversation", null ], "example": "custom", "type": [ "string", "null" ] }, "result_event_name": { "description": "The merchant-defined event name when result_event is custom; null for the standard events.", "example": "quote_requested", "type": [ "string", "null" ] }, "results": { "description": "The Whop pixel-attributed count behind result_event. When a campaign's ad groups optimize different goals there is no single result_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for.", "example": 33, "type": [ "number", "null" ] }, "return_on_ad_spend": { "description": "Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.", "example": 6.0, "type": "number" }, "schedule_value": { "description": "USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 5400.0, "type": "number" }, "schedules": { "description": "Whop pixel-attributed schedule events, last-click.", "example": 60, "type": "number" }, "spend": { "description": "The amount charged, in spend_currency.", "example": 1320.0, "type": "number" }, "spend_currency": { "description": "The ISO 4217 currency code of all monetary metrics.", "example": "usd", "type": [ "string", "null" ] }, "starts_at": { "description": "When the ad group starts delivering, as an ISO 8601 timestamp. `null` when it starts as soon as it's active.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Whether the ad group is enabled. `active` and `paused` are set by you; `rejected` means it failed ad review; `duplicating` is a copy still being filled in.", "enum": [ "active", "paused", "rejected", "duplicating" ], "example": "active", "type": "string" }, "submitted_application_value": { "description": "USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 1320.0, "type": "number" }, "submitted_applications": { "description": "Whop pixel-attributed submit-application events, last-click.", "example": 11, "type": "number" }, "title": { "description": "Display name of the ad group.", "example": "Austin ceramic coating — repeat customers", "type": [ "string", "null" ] }, "unique_click_through_rate": { "description": "Unique clicks divided by impressions, between 0 and 1.", "example": null, "type": [ "number", "null" ] }, "unique_clicks": { "description": "People who clicked, reported by the Whop pixel, counted once per person.", "example": 3300, "type": "number" }, "updated_at": { "description": "When the ad group was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "viewed_content_value": { "description": "USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.", "example": 8400.0, "type": "number" }, "viewed_contents": { "description": "Whop pixel-attributed view-content events, last-click.", "example": 1200, "type": "number" } }, "required": [ "click_through_rate", "clicks", "cost_per_click", "cost_per_unique_click", "cost_per_lead", "cost_per_mille", "cost_per_purchase", "cost_per_schedule", "cost_per_submitted_application", "cost_per_contact", "cost_per_completed_registration", "cost_per_viewed_content", "cost_per_added_to_cart", "cost_per_result", "frequency", "impressions", "leads", "link_clicks", "purchase_value", "purchases", "reach", "result_event", "result_event_name", "results", "return_on_ad_spend", "spend", "spend_currency", "unique_click_through_rate", "unique_clicks", "schedules", "submitted_applications", "contacts", "completed_registrations", "viewed_contents", "added_to_carts", "custom_conversions", "custom_event_counts", "custom_event_values", "lead_value", "schedule_value", "submitted_application_value", "contact_value", "completed_registration_value", "viewed_content_value", "added_to_cart_value", "id", "title", "platform", "status", "delivery_status", "learning_progress", "optimization_goal", "conversion_event", "budget_amount", "budget_amount_local", "budget_currency", "budget_type", "bid_type", "desired_cost_per_result", "starts_at", "ends_at", "delivery_schedule", "regions", "demographics", "detailed_targeting", "audiences", "languages", "devices", "frequency_cap", "placements", "ad_campaign", "created_at", "updated_at", "issues" ], "type": "object" }, "AdGroupAudiences": { "properties": { "exclude": { "items": { "description": "IDs of saved audiences excluded from delivery, prefixed `adaud_`.", "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "include": { "items": { "description": "IDs of saved audiences the ad group delivers to, prefixed `adaud_`.", "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "include", "exclude" ], "type": "object" }, "AdGroupAudiencesBody": { "description": "Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic.", "properties": { "exclude": { "description": "IDs of saved audiences to exclude from delivery, prefixed `adaud_`.", "items": { "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "include": { "description": "IDs of saved audiences to deliver to, prefixed `adaud_`.", "items": { "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "title": "Audiences", "type": "object" }, "AdGroupBehaviorCategory": { "properties": { "behavior_type": { "description": "On ad platforms that scope behavior categories, what this one is measured on. Send back the value the targeting_options endpoint returned alongside the id. Absent on platforms that don't scope them.", "enum": [ "video", "creator", "hashtag" ], "example": "video", "type": "string" }, "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6007101291578", "type": "string" }, "name": { "description": "Category name, such as `Frequent travelers`.", "example": "Recent vehicle purchase (30 days)", "type": "string" }, "period": { "description": "On ad platforms that scope behavior categories, how many days of activity the category covers. Absent on platforms that don't scope them.", "type": "number" } }, "required": [ "id" ], "type": "object" }, "AdGroupCity": { "properties": { "key": { "description": "The ad platform's key for the city in its location taxonomy.", "example": "2418046", "type": "string" }, "name": { "description": "City name, such as `Austin`. Absent when the platform doesn't return one.", "example": "Austin", "type": "string" } }, "required": [ "key" ], "type": "object" }, "AdGroupCustomLocation": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-2 country the point falls in. Send it under a special ad category, where the campaign must declare the countries its ad sets reach.", "type": "string" }, "distance_unit": { "description": "Unit for `radius`.", "enum": [ "mile", "kilometer" ], "example": "mile", "type": "string" }, "latitude": { "description": "Latitude of the center point.", "example": 30.2672, "type": "number" }, "longitude": { "description": "Longitude of the center point.", "example": -97.7431, "type": "number" }, "name": { "description": "Label for the location, such as a city or address. Absent when the location has no label.", "example": "4180 Burnet Rd, Austin TX 78756", "type": "string" }, "radius": { "description": "Radius around the center point, in `distance_unit`.", "example": 25.0, "type": "number" } }, "required": [ "latitude", "longitude", "radius", "distance_unit" ], "type": "object" }, "AdGroupDeliverySchedule": { "properties": { "friday": { "items": { "$ref": "#/components/schemas/AdGroupDeliveryWindow", "description": "Windows the ad group delivers in on Friday, in time order. Omitted when it doesn't deliver that day." }, "type": "array" }, "monday": { "items": { "$ref": "#/components/schemas/AdGroupDeliveryWindow", "description": "Windows the ad group delivers in on Monday, in time order. Omitted when it doesn't deliver that day." }, "type": "array" }, "saturday": { "items": { "$ref": "#/components/schemas/AdGroupDeliveryWindow", "description": "Windows the ad group delivers in on Saturday, in time order. Omitted when it doesn't deliver that day." }, "type": "array" }, "sunday": { "items": { "$ref": "#/components/schemas/AdGroupDeliveryWindow", "description": "Windows the ad group delivers in on Sunday, in time order. Omitted when it doesn't deliver that day." }, "type": "array" }, "thursday": { "items": { "$ref": "#/components/schemas/AdGroupDeliveryWindow", "description": "Windows the ad group delivers in on Thursday, in time order. Omitted when it doesn't deliver that day." }, "type": "array" }, "tuesday": { "items": { "$ref": "#/components/schemas/AdGroupDeliveryWindow", "description": "Windows the ad group delivers in on Tuesday, in time order. Omitted when it doesn't deliver that day." }, "type": "array" }, "wednesday": { "items": { "$ref": "#/components/schemas/AdGroupDeliveryWindow", "description": "Windows the ad group delivers in on Wednesday, in time order. Omitted when it doesn't deliver that day." }, "type": "array" } }, "required": [], "type": "object" }, "AdGroupDeliveryWindow": { "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`; a window past midnight is split across two days.", "example": "12:00", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "10:00", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "AdGroupDemographicCategory": { "properties": { "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6002714398172", "type": "string" }, "name": { "description": "Category name, such as `Recently moved`.", "example": "Recently moved", "type": "string" }, "type": { "description": "Kind of demographic the category belongs to.", "enum": [ "life_events", "industries", "income", "family_statuses", "work_employers", "work_positions", "education_schools", "education_majors" ], "example": "life_events", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "AdGroupDemographics": { "properties": { "automatic": { "description": "Whether automatic audience targeting is on (Advantage+ on Meta). When `true`, the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions.", "example": false, "type": "boolean" }, "gender": { "description": "Gender targeted.", "enum": [ "all", "male", "female" ], "example": "all", "type": "string" }, "maximum_age": { "description": "Oldest age targeted. `null` when no maximum is set.", "example": 64, "type": [ "number", "null" ] }, "minimum_age": { "description": "Youngest age targeted. `null` when no minimum is set.", "example": 21, "type": [ "number", "null" ] } }, "required": [ "automatic", "minimum_age", "maximum_age", "gender" ], "type": "object" }, "AdGroupDemographicsBody": { "description": "Age, gender, and automatic-audience targeting.", "properties": { "automatic": { "description": "Turn on automatic audience targeting (Advantage+ on Meta): the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions.", "example": false, "type": "boolean" }, "gender": { "description": "Gender to target.", "enum": [ "all", "male", "female" ], "example": "all", "type": "string" }, "maximum_age": { "description": "Oldest age to target.", "example": 64, "type": "integer" }, "minimum_age": { "description": "Youngest age to target.", "example": 21, "type": "integer" } }, "title": "Demographics", "type": "object" }, "AdGroupDetailedTargeting": { "properties": { "behaviors": { "items": { "$ref": "#/components/schemas/AdGroupBehaviorCategory", "description": "Behavior categories targeted, such as frequent travelers." }, "type": "array" }, "demographics": { "items": { "$ref": "#/components/schemas/AdGroupDemographicCategory", "description": "Demographic categories targeted, such as life events, industries, work employers, job titles, schools, or majors. OR'd with interests and behaviors." }, "type": "array" }, "interests": { "items": { "$ref": "#/components/schemas/AdGroupTargetingCategory", "description": "Interest categories targeted, such as an interest in movies." }, "type": "array" } }, "required": [ "interests", "behaviors", "demographics" ], "type": "object" }, "AdGroupDetailedTargetingBody": { "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories.", "properties": { "behaviors": { "description": "Behavior categories to target, such as frequent travelers.", "items": { "properties": { "behavior_type": { "description": "On ad platforms that scope behavior categories, what this one is measured on. Send back the value the targeting_options endpoint returned alongside the id.", "enum": [ "video", "creator", "hashtag" ], "example": "video", "type": "string" }, "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6007101291578", "type": "string" }, "name": { "description": "Category name, such as `Frequent travelers`.", "example": "Recent vehicle purchase (30 days)", "type": "string" }, "period": { "description": "On ad platforms that scope behavior categories, how many days of activity the category covers.", "type": "integer" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "demographics": { "description": "Demographic categories to target, such as life events, industries, work employers, job titles, schools, or majors.", "items": { "properties": { "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6002714398172", "type": "string" }, "name": { "description": "Category name, such as `Recently moved`.", "example": "Recently moved", "type": "string" }, "type": { "description": "Kind of demographic the category belongs to.", "enum": [ "life_events", "industries", "income", "family_statuses", "work_employers", "work_positions", "education_schools", "education_majors" ], "example": "life_events", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "type": "array" }, "interests": { "description": "Interest categories to target, such as an interest in movies.", "items": { "properties": { "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6003193685204", "type": "string" }, "name": { "description": "Category name, such as `Movies`.", "example": "Car wash", "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" } }, "title": "Detailed targeting", "type": "object" }, "AdGroupDevices": { "properties": { "operating_systems": { "items": { "$ref": "#/components/schemas/AdGroupOperatingSystem", "description": "Operating systems targeted. Empty targets all operating systems." }, "type": "array" }, "platforms": { "items": { "description": "Device types targeted. Empty targets all devices.", "enum": [ "mobile", "desktop" ], "example": "mobile", "type": "string" }, "type": "array" } }, "required": [ "platforms", "operating_systems" ], "type": "object" }, "AdGroupDevicesBody": { "description": "Device platforms and operating systems to target.", "properties": { "operating_systems": { "description": "Operating systems to target. Empty targets all operating systems.", "items": { "properties": { "minimum_version": { "description": "Lowest OS version to target, such as `18.0`. Omit to target any version.", "example": "18.0", "type": "string" }, "os": { "description": "Operating system to target.", "enum": [ "ios", "android" ], "example": "ios", "type": "string" } }, "required": [ "os" ], "type": "object" }, "type": "array" }, "platforms": { "description": "Device types to target. Empty targets all devices.", "items": { "enum": [ "mobile", "desktop" ], "example": "mobile", "type": "string" }, "type": "array" } }, "title": "Devices", "type": "object" }, "AdGroupFrequencyCap": { "properties": { "maximum_impressions": { "description": "Most times one person can be shown ads from this ad group within the window.", "example": 3, "type": "number" }, "per_days": { "description": "Length of the rolling window, in days.", "example": 7, "type": [ "number", "null" ] } }, "required": [ "maximum_impressions", "per_days" ], "type": "object" }, "AdGroupGeoLocations": { "properties": { "cities": { "items": { "$ref": "#/components/schemas/AdGroupCity", "description": "Cities, keyed by the ad platform's location taxonomy." }, "type": "array" }, "countries": { "items": { "description": "Countries, as ISO 3166-1 alpha-2 codes such as `US`.", "example": "US", "type": "string" }, "type": "array" }, "country_groups": { "items": { "description": "Multi-country groups such as `worldwide` or `europe`.", "example": "north_america", "type": "string" }, "type": "array" }, "custom_locations": { "items": { "$ref": "#/components/schemas/AdGroupCustomLocation", "description": "Circular areas, each a coordinate plus a radius." }, "type": "array" }, "regions": { "items": { "description": "US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`, `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through `countries`.", "example": "US-TX", "type": "string" }, "type": "array" }, "zips": { "items": { "description": "ZIP and postal codes, keyed by the ad platform's location taxonomy. Meta keys these `COUNTRY:CODE`, as `US:78756`.", "example": "US:78756", "type": "string" }, "type": "array" } }, "required": [ "countries", "country_groups", "regions", "cities", "zips", "custom_locations" ], "type": "object" }, "AdGroupGeoLocationsBody": { "properties": { "cities": { "description": "Cities, keyed by the ad platform's location taxonomy.", "items": { "properties": { "key": { "description": "The ad platform's key for the city in its location taxonomy.", "example": "2418046", "type": "string" }, "name": { "description": "City name, such as `Austin`.", "example": "Austin", "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "countries": { "description": "Countries, as ISO 3166-1 alpha-2 codes such as `US`.", "items": { "example": "US", "type": "string" }, "type": "array" }, "country_groups": { "description": "Multi-country groups such as `worldwide` or `europe`. Include-only — groups can't be excluded.", "items": { "example": "north_america", "type": "string" }, "type": "array" }, "custom_locations": { "description": "Circular areas, each a coordinate plus a radius. At most 200 across include and exclude.", "items": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-2 country the point falls in, as `DE`. Send it under a special ad category: the campaign must declare the countries its ad sets reach, and a coordinate names none.", "type": "string" }, "distance_unit": { "description": "Unit for `radius`. Defaults to `mile`.", "enum": [ "mile", "kilometer" ], "example": "mile", "type": "string" }, "latitude": { "description": "Latitude of the center point.", "example": 30.2672, "type": "number" }, "longitude": { "description": "Longitude of the center point.", "example": -97.7431, "type": "number" }, "name": { "description": "Label for the location, such as a city or address.", "example": "4180 Burnet Rd, Austin TX 78756", "type": "string" }, "radius": { "description": "Radius around the center point: 1-50 miles or 1-80 kilometers.", "example": 25, "type": "number" } }, "required": [ "latitude", "longitude", "radius" ], "type": "object" }, "type": "array" }, "regions": { "description": "US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`, `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through `countries`.", "items": { "example": "US-TX", "type": "string" }, "type": "array" }, "zips": { "description": "ZIP and postal codes, keyed by the ad platform's location taxonomy. Meta keys these `COUNTRY:CODE`, as `US:78756` — a bare code is ambiguous, because the same one exists in several countries. TikTok takes the bare code.", "items": { "anyOf": [ { "type": "string" }, { "properties": { "key": { "description": "The ad platform's key for the ZIP or postal code.", "type": "string" } }, "required": [ "key" ], "type": "object" } ], "example": "US:78756" }, "type": "array" } }, "title": "Geo locations", "type": "object" }, "AdGroupKeyword": { "properties": { "match_type": { "description": "How closely a search has to match: `broad` also reaches related searches, `phrase` needs the meaning of the phrase, and `exact` needs the same meaning as the term. Defaults to `broad`.", "enum": [ "broad", "phrase", "exact" ], "example": "broad", "type": "string" }, "negative": { "description": "Whether this term keeps the ads from showing instead of making them eligible. Defaults to `false`.", "type": "boolean" }, "text": { "description": "The search term, up to 80 characters and 10 words.", "type": "string" } }, "required": [ "text", "match_type", "negative" ], "type": "object" }, "AdGroupLearningProgress": { "properties": { "conversion_threshold": { "description": "The ad platform's dynamic conversion threshold for this ad group's learning phase.", "type": "integer" }, "conversions": { "description": "Conversions reported by the ad platform since the last significant edit during this ad group's learning phase.", "type": "integer" }, "progress_percent": { "description": "Conversions divided by the threshold, as a percentage clamped to 0–100. The platform's learning status remains authoritative.", "type": "number" } }, "required": [ "conversions", "conversion_threshold", "progress_percent" ], "type": "object" }, "AdGroupOperatingSystem": { "properties": { "minimum_version": { "description": "Lowest OS version targeted, such as `18.0`. Absent when any version qualifies.", "example": "18.0", "type": "string" }, "os": { "description": "Operating system targeted.", "enum": [ "ios", "android" ], "example": "ios", "type": "string" } }, "required": [ "os" ], "type": "object" }, "AdGroupPlacement": { "properties": { "platform": { "description": "Publisher platform where the ad is eligible to appear.", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads", "whatsapp" ], "example": "facebook", "type": "string" }, "positions": { "items": { "description": "Positions targeted within the platform, such as `feed` or `story`. Empty targets all of the platform's positions.", "example": "feed", "type": "string" }, "type": "array" } }, "required": [ "platform", "positions" ], "type": "object" }, "AdGroupRegions": { "properties": { "exclude": { "$ref": "#/components/schemas/AdGroupGeoLocations", "description": "Locations excluded from targeting. Country groups can't be excluded." }, "include": { "$ref": "#/components/schemas/AdGroupGeoLocations", "description": "Locations the ad group targets." } }, "required": [ "include", "exclude" ], "type": "object" }, "AdGroupRegionsBody": { "description": "Locations to target and exclude.", "properties": { "exclude": { "$ref": "#/components/schemas/AdGroupGeoLocationsBody", "description": "Locations excluded from targeting. Country groups can't be excluded." }, "include": { "$ref": "#/components/schemas/AdGroupGeoLocationsBody", "description": "Locations the ad group targets." } }, "title": "Regions", "type": "object" }, "AdGroupTargetingCategory": { "properties": { "id": { "description": "The ad platform's ID for the category in its targeting taxonomy.", "example": "6003193685204", "type": "string" }, "name": { "description": "Category name, such as `Movies`.", "example": "Car wash", "type": "string" } }, "required": [ "id" ], "type": "object" }, "AdLeadForm": { "properties": { "completion": { "description": "Screen shown after the form is submitted. `null` when the form uses the default.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormCompletion" }, { "type": "null" } ] }, "disclaimer": { "description": "Custom consent disclaimer shown before submission. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormDisclaimer" }, { "type": "null" } ] }, "form_type": { "description": "`more_volume` is quickest to submit; `higher_intent` adds a confirmation step before submission.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "intro": { "description": "Intro screen shown before the questions. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormIntro" }, { "type": "null" } ] }, "name": { "description": "Internal name of the form.", "example": "Ceramic coating quote requests", "type": [ "string", "null" ] }, "phone_verification": { "description": "Whether the phone number must be verified by SMS before submitting.", "example": true, "type": "boolean" }, "privacy_policy": { "description": "Your privacy policy, linked from the form. `null` when unset.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormPrivacyPolicy" }, { "type": "null" } ] }, "questions": { "items": { "$ref": "#/components/schemas/AdLeadFormQuestion", "description": "Questions on the form, in order." }, "type": "array" } }, "required": [ "name", "form_type", "intro", "questions", "privacy_policy", "completion", "disclaimer", "phone_verification" ], "type": "object" }, "AdLeadFormCompletion": { "properties": { "button_text": { "description": "Text of the follow-up button.", "example": "See our work", "type": [ "string", "null" ] }, "button_type": { "description": "What the follow-up button does. `null` on forms saved before the button was configurable.", "enum": [ "website", "call", "download", null ], "example": "website", "type": [ "string", "null" ] }, "description": { "description": "Body text under the headline.", "example": "We book coatings two days out, so pick a slot when we ring.", "type": [ "string", "null" ] }, "file_url": { "description": "File the follow-up button opens. Set when `button_type` is `download`.", "example": null, "type": [ "string", "null" ] }, "headline": { "description": "Headline of the completion screen.", "example": "Thanks — we will call you today", "type": [ "string", "null" ] }, "phone_number": { "description": "Number the follow-up button calls. Set when `button_type` is `call`.", "example": null, "type": [ "string", "null" ] }, "url": { "description": "Website the follow-up button opens. Set when `button_type` is `website`.", "example": "https://shinetime.example/gallery", "type": [ "string", "null" ] } }, "required": [ "headline", "description", "button_text", "button_type", "url", "phone_number", "file_url" ], "type": "object" }, "AdLeadFormDisclaimer": { "properties": { "body": { "description": "Disclaimer text.", "example": "Ceramic coating requires the vehicle for two days.", "type": [ "string", "null" ] }, "checkboxes": { "items": { "$ref": "#/components/schemas/AdLeadFormDisclaimerCheckbox", "description": "Consent checkboxes the person can tick. Empty when the disclaimer is text-only." }, "type": "array" }, "title": { "description": "Disclaimer title.", "example": "Before you submit", "type": [ "string", "null" ] } }, "required": [ "title", "body", "checkboxes" ], "type": "object" }, "AdLeadFormDisclaimerCheckbox": { "properties": { "checked_by_default": { "description": "Whether the checkbox starts ticked.", "example": false, "type": [ "boolean", "null" ] }, "key": { "description": "Stable identifier consent responses are stored under.", "example": "consent_1", "type": [ "string", "null" ] }, "required": { "description": "Whether the checkbox must be ticked to submit the form.", "example": true, "type": [ "boolean", "null" ] }, "text": { "description": "Consent text next to the checkbox.", "example": "I agree", "type": "string" } }, "required": [ "text", "key", "required", "checked_by_default" ], "type": "object" }, "AdLeadFormIntro": { "properties": { "description": { "description": "Body text under the headline.", "example": "Tell us about your vehicle and we will send a fixed price.", "type": [ "string", "null" ] }, "headline": { "description": "Headline of the intro screen.", "example": "Get a ceramic coating quote", "type": [ "string", "null" ] } }, "required": [ "headline", "description" ], "type": "object" }, "AdLeadFormOptionLogic": { "properties": { "action": { "description": "What happens when the choice is selected.", "enum": [ "go_to_question", "submit_form", "close_form" ], "example": "go_to_question", "type": "string" }, "target_end_page_index": { "description": "Zero-based index of the ending screen to jump to.", "example": 0, "type": "number" }, "target_question_index": { "description": "Zero-based index of the question to jump to, for `go_to_question`.", "example": 3, "type": "number" } }, "required": [ "action" ], "type": "object" }, "AdLeadFormPrivacyPolicy": { "properties": { "link_text": { "description": "Link text shown for the policy. `null` uses the platform default.", "example": "Shine Time privacy policy", "type": [ "string", "null" ] }, "url": { "description": "URL of your privacy policy.", "example": "https://shinetime.example/privacy", "type": "string" } }, "required": [ "url", "link_text" ], "type": "object" }, "AdLeadFormQuestion": { "properties": { "format": { "description": "Answer format for `custom` questions: `short_answer`, `multiple_choice`, or `appointment`. Absent otherwise.", "example": "multiple_choice", "type": "string" }, "label": { "description": "Question text for `custom` questions. Absent for standard prefill questions.", "example": "What vehicle are we detailing?", "type": "string" }, "options": { "items": { "$ref": "#/components/schemas/AdLeadFormQuestionOption", "description": "Choices for `multiple_choice` questions. Absent for other formats." }, "type": "array" }, "type": { "description": "Question type: a standard prefill type such as `email`, `phone`, or `full_name`, or `custom` for your own question.", "example": "custom", "type": "string" } }, "required": [ "type" ], "type": "object" }, "AdLeadFormQuestionOption": { "properties": { "key": { "description": "Stable identifier the choice's answers are stored under. Absent for simple choices.", "example": "ceramic_coating", "type": [ "string", "null" ] }, "logic": { "$ref": "#/components/schemas/AdLeadFormOptionLogic", "description": "Where the form goes when this choice is selected. Absent when the form just continues to the next question." }, "value": { "description": "Choice text shown to the person.", "example": "Ceramic coating", "type": "string" } }, "required": [ "value" ], "type": "object" }, "AdMessagingConfig": { "properties": { "keyword": { "description": "Suggested reply the person can tap to start the conversation.", "example": "Book an interior deep clean", "type": [ "string", "null" ] }, "message": { "description": "Greeting shown when the conversation opens.", "example": "Hi! Tell us your vehicle and ZIP and we will send an interior deep clean quote.", "type": [ "string", "null" ] } }, "required": [ "message", "keyword" ], "type": "object" }, "AdMusic": { "properties": { "id": { "description": "The music attachment's file id.", "type": "string" }, "name": { "description": "The uploaded file's name.", "type": [ "string", "null" ] }, "url": { "description": "CDN url of the MP3.", "type": [ "string", "null" ] } }, "required": [ "id", "url", "name" ], "type": "object" }, "AdPixel": { "properties": { "account_id": { "description": "The business whose claimed campaigns send conversions to this pixel, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "created_at": { "description": "When the pixel was added, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "error_message": { "description": "Why the ad platform rejected the last delivery. Null unless `status` is `errored`.", "example": null, "type": [ "string", "null" ] }, "external_id": { "description": "The pixel's ID on the ad platform: the Meta pixel or dataset ID, the TikTok pixel code, or the Google Ads customer ID.", "example": "111222001", "type": "string" }, "id": { "description": "Ad pixel ID, prefixed `adpx_`.", "example": "adpx_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The pixel's name on the ad platform. Null when the ad platform returned none.", "example": "Supplier pixel", "type": [ "string", "null" ] }, "platform": { "description": "The ad platform the pixel belongs to.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" }, "status": { "description": "`active` receives conversions. `errored` stopped because the ad platform rejected the access token; update the token to resume. `disabled` was turned off by Whop.", "enum": [ "active", "errored", "disabled" ], "example": "active", "type": "string" }, "updated_at": { "description": "When the pixel was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "account_id", "platform", "external_id", "name", "status", "error_message", "created_at", "updated_at" ], "type": "object" }, "AdPlatformIssue": { "properties": { "category": { "description": "The kind of issue: information about delivery, a warning, or an error requiring attention.", "enum": [ "information", "warning", "error" ], "example": "error", "type": "string" }, "id": { "description": "Unique identifier for the issue.", "example": "adiss_xxxxxxxxxxxxxx", "type": "string" }, "message": { "description": "A description of what the issue is and how it can be resolved.", "example": "Your ad didn't pass our content review. Update it to follow our ad guidelines and resubmit.", "type": "string" }, "resource_id": { "description": "The ID of the campaign, ad group, or ad the issue is attached to.", "example": "ad_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "resource_type": { "description": "The type of resource the issue is attached to.", "enum": [ "ad_campaign", "ad_group", "ad" ], "example": "ad", "type": "string" }, "title": { "description": "A short, creator-facing title for the issue.", "example": "Ad issue", "type": "string" } }, "required": [ "id", "category", "title", "message", "resource_id", "resource_type" ], "type": "object" }, "AdStat": { "properties": { "ad_campaign_id": { "description": "The ID of the ad's campaign, prefixed `adcamp_`.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "ad_group_id": { "description": "The ID of the ad's ad group, prefixed `adgrp_`.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "ad_id": { "description": "The ad's ID, prefixed `ad_`, as sent.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "clicks": { "description": "The ad's clicks in the hour.", "example": 150, "type": "integer" }, "hour_started_at": { "description": "Start of the hour, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "impressions": { "description": "The ad's impressions in the hour.", "example": 6000, "type": "integer" }, "spend": { "$ref": "#/components/schemas/Money", "description": "The spend recorded and paid for the ad in the hour, exactly as reported." } }, "required": [ "ad_id", "ad_campaign_id", "ad_group_id", "hour_started_at", "spend", "impressions", "clicks" ], "type": "object" }, "AdText": { "properties": { "language": { "description": "ISO 639 code of the language this text is in, such as `es`. On an ad with translations, the ad's own copy carries `translations.source_language`. It's `null` on an ad without translations.", "example": "en", "type": [ "string", "null" ] }, "text": { "description": "The text shown to viewers.", "example": "Austin's mobile detailers", "type": "string" } }, "required": [ "language", "text" ], "type": "object" }, "AdTranslations": { "properties": { "automatic_languages": { "items": { "description": "ISO 639 codes Meta translates the ad's own copy into automatically, such as `fr`.", "example": "fr", "type": "string" }, "type": "array" }, "source_language": { "description": "ISO 639 code of the language the ad's own copy is written in, such as `en`. Viewers whose language has no version of its own see the ad's own copy.", "example": "en", "type": "string" } }, "required": [ "source_language", "automatic_languages" ], "type": "object" }, "Affiliate": { "description": "An affiliate tracks a user's referral performance and commission earnings for a company, including retention rates, revenue metrics, and payout configurations.", "properties": { "active_members_count": { "description": "The total active members of the affiliate", "example": 42, "type": "integer" }, "company": { "description": "The company attached to this affiliate", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the affiliate was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "customer_retention_rate": { "description": "The percentage of referred customers who are still active members", "type": "string" }, "customer_retention_rate_ninety_days": { "description": "The percentage of referred customers who remained active over the last 90 days", "type": "string" }, "id": { "description": "The unique identifier for the affiliate.", "example": "aff_xxxxxxxxxxxxxx", "type": "string" }, "monthly_recurring_revenue_usd": { "description": "The monthly recurring revenue generated by this affiliate's referrals, formatted as a USD currency string", "type": "string" }, "status": { "description": "The status of the affiliate", "oneOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "null" } ] }, "total_overrides_count": { "description": "The total count of all overrides for this affiliate", "example": 42, "type": "integer" }, "total_referral_earnings_usd": { "description": "The total commission earnings paid to this affiliate, formatted as a USD currency string", "type": "string" }, "total_referrals_count": { "description": "The total referrals of the affiliate", "example": 42, "type": "integer" }, "total_revenue_usd": { "description": "The total revenue generated from this affiliate's referrals, formatted as a USD currency string", "type": "string" }, "updated_at": { "description": "The datetime the affiliate was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user attached to this affiliate", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name set on the user's Whop profile. Null if the user has not set a name.", "example": "Jane Smith", "type": [ "string", "null" ] }, "username": { "description": "The unique username chosen by the user for their Whop profile. Null if the user has not set a username.", "example": "janesmith", "type": [ "string", "null" ] } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "status", "created_at", "updated_at", "total_referrals_count", "total_referral_earnings_usd", "total_overrides_count", "customer_retention_rate", "customer_retention_rate_ninety_days", "monthly_recurring_revenue_usd", "total_revenue_usd", "active_members_count", "user", "company" ], "type": "object" }, "AffiliateAppliesToPayments": { "description": "Whether the affiliate commission applies to the first payment or all payments", "enum": [ "first_payment", "all_payments" ], "type": "string" }, "AffiliateAppliesToProducts": { "description": "Whether a rev-share override applies to a single product or all products", "enum": [ "single_product", "all_products" ], "type": "string" }, "AffiliateListItem": { "description": "An affiliate tracks a user's referral performance and commission earnings for a company, including retention rates, revenue metrics, and payout configurations.", "properties": { "active_members_count": { "description": "The total active members of the affiliate", "example": 42, "type": "integer" }, "company": { "description": "The company attached to this affiliate", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the affiliate was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "customer_retention_rate": { "description": "The percentage of referred customers who are still active members", "type": "string" }, "customer_retention_rate_ninety_days": { "description": "The percentage of referred customers who remained active over the last 90 days", "type": "string" }, "id": { "description": "The unique identifier for the affiliate.", "example": "aff_xxxxxxxxxxxxxx", "type": "string" }, "monthly_recurring_revenue_usd": { "description": "The monthly recurring revenue generated by this affiliate's referrals, formatted as a USD currency string", "type": "string" }, "status": { "description": "The status of the affiliate", "oneOf": [ { "$ref": "#/components/schemas/Status" }, { "type": "null" } ] }, "total_overrides_count": { "description": "The total count of all overrides for this affiliate", "example": 42, "type": "integer" }, "total_referral_earnings_usd": { "description": "The total commission earnings paid to this affiliate, formatted as a USD currency string", "type": "string" }, "total_referrals_count": { "description": "The total referrals of the affiliate", "example": 42, "type": "integer" }, "total_revenue_usd": { "description": "The total revenue generated from this affiliate's referrals, formatted as a USD currency string", "type": "string" }, "updated_at": { "description": "The datetime the affiliate was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user attached to this affiliate", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name set on the user's Whop profile. Null if the user has not set a name.", "example": "Jane Smith", "type": [ "string", "null" ] }, "username": { "description": "The unique username chosen by the user for their Whop profile. Null if the user has not set a username.", "example": "janesmith", "type": [ "string", "null" ] } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "status", "created_at", "updated_at", "total_referrals_count", "total_referral_earnings_usd", "total_overrides_count", "customer_retention_rate", "customer_retention_rate_ninety_days", "monthly_recurring_revenue_usd", "total_revenue_usd", "active_members_count", "user", "company" ], "type": "object" }, "AffiliateOverrideRoles": { "description": "The role of an affiliate override (standard or rev_share)", "enum": [ "standard", "rev_share" ], "type": "string" }, "AffiliatePayoutTypes": { "description": "The types of payouts an affiliate can have", "enum": [ "percentage", "flat_fee" ], "type": "string" }, "AffiliateRevenueBases": { "description": "The calculation method for affiliate rev-share percentages", "enum": [ "pre_fees", "post_fees" ], "type": "string" }, "AffiliatesSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "created_at", "cached_total_referrals", "cached_total_rewards" ], "type": "string" }, "AiChat": { "description": "An AI-powered chat conversation belonging to a user, with optional scheduled automation.", "properties": { "agent_identifier": { "$ref": "#/components/schemas/AiChatAgentIdentifiers", "description": "The AI agent that handles this chat. Set when the chat is created and fixed for its lifetime." }, "blended_token_usage": { "description": "The total number of tokens consumed across all messages in this conversation.", "example": "123.45", "type": "string" }, "created_at": { "description": "The datetime the ai chat was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the ai chat.", "example": "aich_xxxxxxxxxxxxx", "type": "string" }, "last_message_at": { "description": "The timestamp of the most recent message in this conversation. Null if no messages have been sent yet.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "message_count": { "description": "The total number of messages exchanged in this conversation.", "example": 42, "type": "integer" }, "notification_preference": { "$ref": "#/components/schemas/AiChatNotificationPreferences", "description": "The notification preference for this AI chat. `all` delivers AI chat notifications and badges, while `none` mutes them." }, "title": { "description": "A short descriptive title for this AI chat conversation. Null if no title has been set.", "example": "Weekly Revenue Analysis", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the ai chat was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who owns this AI chat conversation.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" } }, "required": [ "id", "title", "agent_identifier", "notification_preference", "message_count", "blended_token_usage", "created_at", "updated_at", "last_message_at", "user" ], "type": "object" }, "AiChatAgentIdentifiers": { "description": "The AI agent that handles an AI chat.", "enum": [ "general", "support" ], "type": "string" }, "AiChatListItem": { "description": "An AI-powered chat conversation belonging to a user, with optional scheduled automation.", "properties": { "agent_identifier": { "$ref": "#/components/schemas/AiChatAgentIdentifiers", "description": "The AI agent that handles this chat. Set when the chat is created and fixed for its lifetime." }, "blended_token_usage": { "description": "The total number of tokens consumed across all messages in this conversation.", "example": "123.45", "type": "string" }, "created_at": { "description": "The datetime the ai chat was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the ai chat.", "example": "aich_xxxxxxxxxxxxx", "type": "string" }, "last_message_at": { "description": "The timestamp of the most recent message in this conversation. Null if no messages have been sent yet.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "message_count": { "description": "The total number of messages exchanged in this conversation.", "example": 42, "type": "integer" }, "notification_preference": { "$ref": "#/components/schemas/AiChatNotificationPreferences", "description": "The notification preference for this AI chat. `all` delivers AI chat notifications and badges, while `none` mutes them." }, "title": { "description": "A short descriptive title for this AI chat conversation. Null if no title has been set.", "example": "Weekly Revenue Analysis", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the ai chat was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who owns this AI chat conversation.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" } }, "required": [ "id", "title", "agent_identifier", "notification_preference", "message_count", "blended_token_usage", "created_at", "updated_at", "last_message_at", "user" ], "type": "object" }, "AiChatMessageSourceTypes": { "description": "The source of an AI chat message", "enum": [ "manual", "suggestion", "link" ], "type": "string" }, "AiChatNotificationPreferences": { "description": "The notification preference for an AI chat", "enum": [ "all", "none" ], "type": "string" }, "ApiKey": { "properties": { "api_version_date": { "description": "Dated API version used when requests authenticated with this key omit the `Api-Version-Date` header.", "enum": [ "2025-01-01", "2026-06-08", "2026-06-09", "2026-06-20", "2026-07-01", "2026-07-08", "2026-07-08-1", "2026-07-18", "2026-07-20", "2026-07-22", "2026-07-23", "2026-07-25", "2026-07-26", "2026-07-27", "2026-07-29", "2026-07-29-1", "2026-07-31", "2026-08-03", "2026-08-05", "2026-08-05-1", "2026-08-10", "2026-08-12", "2026-08-13", "2026-08-14", "2026-08-21", "2026-08-21-1", "2026-08-25", "2026-08-25-1", "2026-08-25-2", "2026-08-31", "2026-09-02", "2026-09-02-1", "2026-09-02-2", "2026-09-04", "2026-09-06", "2026-09-09", "2026-09-09-1", "2026-09-11", "2026-09-11-1", "2026-09-13", "2026-09-15", "2026-09-22", "2026-09-22-1", "2026-09-22-2", "2026-09-22-3", "2026-09-22-4", "2026-09-23", "2026-09-24", "2026-09-24-1", "2026-09-25", "2026-09-28", "2026-09-29", "2026-10-05", "2026-10-05-1", "2026-10-06", "2026-10-06-1", "2026-10-06-2", "2026-10-07", "2026-10-07-1", "2026-10-07-2", "2026-10-08", "2026-10-09", "2026-10-09-1", "2026-10-09-2", "2026-10-13", "2026-10-13-1", "2026-10-14", "2026-10-14-1", "2026-10-15", "2026-10-15-1", "2026-10-24", "2026-10-27", "2026-10-27-1", "2026-10-27-2", "2026-10-27-3" ], "example": "2026-10-27-3", "type": "string" }, "created_at": { "description": "When the API key was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "expires_at": { "description": "When the API key stops working, as an ISO 8601 timestamp. `null` means it never expires.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "grants": { "items": { "$ref": "#/components/schemas/ApiKeyGrant", "description": "The key's effective permissions, grouped by resource. Present on retrieve, create, update, and rotate responses; omitted on list." }, "type": "array" }, "id": { "description": "API key ID, prefixed `apik_`.", "example": "apik_xxxxxxxxxxxxxx", "type": "string" }, "ip_allowlist": { "items": { "description": "IPv4/IPv6 CIDR ranges allowed to use this key. `null` or empty means requests are accepted from any IP.", "example": "203.0.113.0/24", "type": "string" }, "type": [ "array", "null" ] }, "is_default_for_resource": { "description": "Whether this is the resource's default API key. Default keys cannot be updated or deleted, only rotated.", "example": false, "type": "boolean" }, "name": { "description": "Human-readable name identifying the API key, or `null` when none was set.", "example": "Shine Time Booking (admin role)", "type": [ "string", "null" ] }, "obfuscated_secret_key": { "description": "Masked version of the secret key, so the key can be recognized without revealing the full secret.", "example": "apik_xxxx....xxxx", "type": "string" }, "secret_key": { "description": "The full secret used to authenticate requests. Returned only once, on create and rotate responses — store it immediately.", "example": "apik_xxxxxxxxxxxxxx_C0000_C_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "system_role": { "description": "System role the key inherits its permissions from, or `null` when it uses an explicit permissions policy. Only account API keys can use a system role.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser", null ], "example": "admin", "type": [ "string", "null" ] }, "updated_at": { "description": "When the API key was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "name", "obfuscated_secret_key", "is_default_for_resource", "system_role", "api_version_date", "expires_at", "ip_allowlist", "created_at", "updated_at" ], "type": "object" }, "ApiKeyGrant": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/ApiKeyGrantAction", "description": "The actions the grant covers on the resource, each marked granted or not." }, "type": "array" }, "resource_id": { "description": "ID of the resource the actions apply to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "resource_type": { "description": "The type of resource the actions apply to, such as `account`, `product`, or `app`.", "example": "account", "type": "string" } }, "required": [ "resource_id", "resource_type", "actions" ], "type": "object" }, "ApiKeyGrantAction": { "properties": { "action": { "description": "The permission action's identifier, for example `company:basic:read`.", "example": "ai_prompt:create", "type": "string" }, "granted": { "description": "Whether the key holds the action on the grant's resource.", "example": false, "type": "boolean" } }, "required": [ "action", "granted" ], "type": "object" }, "ApiVersion": { "description": "The different API versions", "enum": [ "v1", "v2", "v5" ], "type": "string" }, "App": { "properties": { "account": { "$ref": "#/components/schemas/AccountParent", "description": "The account that owns the app." }, "api_key": { "description": "Legacy app API key used to authenticate requests on the app's behalf. `null` when no key exists or the caller lacks the `developer:manage_api_key` permission.", "oneOf": [ { "$ref": "#/components/schemas/AppApiKey" }, { "type": "null" } ] }, "app_store_description": { "description": "Detailed description shown on the app store's in-depth app page, or `null` when none has been set.", "example": "Shine Time Booking turns a whop into a booking calendar. Members pick a package, choose a slot that fits the day's route, and pay up front. A reminder goes out the night before and the receipt lands as soon as the job is signed off.", "type": [ "string", "null" ] }, "app_type": { "description": "The type of end-user the app is built for.", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "example": "b2c_app", "type": "string" }, "banner_image": { "description": "Banner image from the app's product listing, or `null` when none is uploaded.", "oneOf": [ { "$ref": "#/components/schemas/AppBannerImage" }, { "type": "null" } ] }, "base_url": { "description": "The production base URL where the app is hosted. `null` if no base URL is configured, if the caller lacks the `developer:basic:read` permission on the app's account, or on list responses, which never expose it.", "example": "https://shine-time-booking.whop.site", "type": [ "string", "null" ] }, "businesses_created_count": { "description": "Website businesses created from this app as a template.", "example": 5, "type": "integer" }, "businesses_created_logo_urls": { "items": { "description": "Up to three logo image URLs from businesses created from this app as a template.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "type": "array" }, "businesses_with_recent_sales_count": { "description": "Website businesses created from this app as a template that processed a payment in the last 24 hours. Recounted hourly, so it can be up to an hour behind.", "example": 0, "type": "integer" }, "creator": { "$ref": "#/components/schemas/AppCreator", "description": "The user who owns the publishing account." }, "dashboard_path": { "description": "URL path for the account dashboard view, or `null` when not configured.", "example": "/dashboard/[companyId]", "type": [ "string", "null" ] }, "default_api_key": { "description": "The app's default API key. `null` when the app has no default key or the caller lacks the `developer:manage_api_key` permission; `secret_key` is additionally `null` unless the caller could have created the key themselves.", "oneOf": [ { "$ref": "#/components/schemas/AppDefaultApiKey" }, { "type": "null" } ] }, "deployment": { "description": "What the app has left to publish, and how a publish in flight is going — `status` is only ever `unpublished`, `publishing`, or `failed` here. `null` means there is nothing to report: the app is fully published, there is no working copy to publish from, or the caller cannot deploy this app. Tell those apart from the app's own `production_web_build`.", "oneOf": [ { "$ref": "#/components/schemas/AppDeployment" }, { "type": "null" } ] }, "description": { "description": "Short description shown in listings and search results, or `null` if none has been set.", "example": "Let members book a mobile detailing appointment without leaving your whop.", "type": [ "string", "null" ] }, "discover_path": { "description": "URL path for the discover view, or `null` when not configured.", "example": "/discover", "type": [ "string", "null" ] }, "domain_id": { "description": "Subdomain identifier for the app's proxied URL, forming https://{domain_id}.apps.whop.com.", "example": "whopappdomain0000001", "type": "string" }, "domains": { "items": { "$ref": "#/components/schemas/AppDomain", "description": "Domains this app is served at or assigned to, such as its whop.site address, excluding removed domains. Everyone sees the domains serving the app; callers with the account's `domain:read` permission also see the rest." }, "type": "array" }, "elements_used": { "items": { "description": "Whop Elements the app's production web build mounts, as `.` keys (sub-controller children take a third segment, e.g. `payments.cardFields.cardNumber`). A bare namespace means the build reaches that namespace but the individual elements could not be resolved. Empty when the build mounts none, when it has not been scanned yet, or when the app has no production web build.", "enum": [ "ads", "ads.billing-setup", "ads.campaign-creator", "ads.reporting", "ads.reporting.chart", "ads.reporting.table", "checkout", "checkout.checkout", "checkout.expressCheckout", "payments", "payments.address", "payments.branding", "payments.card", "payments.cardFields", "payments.cardFields.cardCvc", "payments.cardFields.cardExpiry", "payments.cardFields.cardNumber", "payments.email", "payments.payment", "payments.taxId", "tracking", "tracking.events", "tracking.people", "wallet", "wallet.activity", "wallet.balances", "wallet.balances.balance", "wallet.balances.list", "wallet.cards", "wallet.deposit", "wallet.send", "wallet.withdraw", "websites", "websites.pixel-setup", "websites.websites" ], "example": "ads", "type": "string" }, "type": "array" }, "experience_path": { "description": "URL path for the member-facing hub view, or `null` when not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "hosted_url": { "deprecated": true, "description": "Full URL where the app's hosted web build is served, or `null` if no route is claimed.\nDEPRECATED: Read `domains` instead.", "example": "https://shine-time-booking.whop.site", "type": [ "string", "null" ] }, "icon": { "$ref": "#/components/schemas/AppIcon", "description": "The app's icon. Falls back to the default app icon when none is uploaded." }, "id": { "description": "App ID, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "imported_from_url": { "description": "The address of the existing website this app was imported from, such as `https://shop.example.com`. `null` if the app was not imported from another site, or if the caller lacks the `developer:basic:read` permission on the app's account.", "example": "https://shinetime.example", "type": [ "string", "null" ] }, "marketplace_status": { "description": "Approval status of the app's product listing on the Whop app store, or `null` when the app has no associated product.", "enum": [ "not_available", "pending_review", "live_marketplace", null ], "example": "not_available", "type": [ "string", "null" ] }, "name": { "description": "Display name shown on the app store and in experience navigation.", "example": "Shine Time Booking", "type": "string" }, "oauth_client_type": { "description": "How the app authenticates at the OAuth token endpoint.", "enum": [ "public", "confidential" ], "example": "public", "type": "string" }, "openapi_path": { "description": "URL path to the app's OpenAPI spec file, or `null` when not configured.", "example": "/openapi.json", "type": [ "string", "null" ] }, "origin": { "description": "Full origin URL of the app's proxied domain, for example https://ab1c2d3e4f.apps.whop.com.", "example": "https://whopappdomain0000001.apps.whop.com", "type": [ "string", "null" ] }, "per_install_schedule": { "description": "Five-field cron expression, read in UTC, on which Whop runs the production web build's `scheduled()` export once for every installation, with the installation in `ctx.props.app_installation`, no more often than every 15 minutes. Slots are skipped while the app has no production web build with a server entry. `null` when the app has no per-install schedule, or if the caller lacks the `developer:basic:read` permission on the app's account.", "example": "*/15 * * * *", "type": [ "string", "null" ] }, "preview_token": { "description": "A short-lived signed pass scoping the caller to this app's gated preview hosts — every build preview and the live dev-server sandbox. Add it to a preview host as the `__whop_preview` query param (or `x-whop-preview-token` header). `null` unless the caller is a team member who can read the app's developer settings.", "example": "whop_preview_pass_example", "type": [ "string", "null" ] }, "product_id": { "description": "ID of the app's product listing on the Whop app store, or `null` when the app has no associated product.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "production_android_build": { "description": "The approved build currently served on Android, or `null` when none is deployed.", "oneOf": [ { "$ref": "#/components/schemas/AppProductionBuild" }, { "type": "null" } ] }, "production_ios_build": { "description": "The approved build currently served on iOS, or `null` when none is deployed.", "oneOf": [ { "$ref": "#/components/schemas/AppProductionBuild" }, { "type": "null" } ] }, "production_web_build": { "description": "The approved build currently served on web, or `null` when none is deployed.", "oneOf": [ { "$ref": "#/components/schemas/AppProductionBuild" }, { "type": "null" } ] }, "redirect_uris": { "items": { "description": "Whitelisted OAuth callback URLs users are redirected to after authorizing the app.", "example": "https://booking.shinetime.example/oauth/callback", "type": "string" }, "type": "array" }, "requested_permissions": { "items": { "$ref": "#/components/schemas/AppRequestedPermission", "description": "Permissions the app requests on install." }, "type": "array" }, "required_scopes": { "items": { "description": "Scopes the app asks a user to grant when they authorize it, shown on the consent screen.", "enum": [ "read_user" ], "example": "read_user", "type": "string" }, "type": "array" }, "route": { "deprecated": true, "description": "Claimed subdomain route where hosted web builds are served (`myapp` for myapp.whop.site), or `null` if no route is claimed.\nDEPRECATED: Read `domains` instead.", "example": "shine-time-booking", "type": [ "string", "null" ] }, "schedule": { "description": "Five-field cron expression, read in UTC, on which Whop runs the production web build's `scheduled()` export once per slot. Slots are skipped while the app has no production web build with a server entry. `null` when the app has no global schedule, or if the caller lacks the `developer:basic:read` permission on the app's account.", "example": "0 * * * *", "type": [ "string", "null" ] }, "secrets": { "description": "The app's production secrets as an object of string values, injected into the hosted server runtime. `null` when the caller lacks the `developer:update_app` permission.", "example": { "BOOKING_CALENDAR_ID": "cal_9f21" }, "type": [ "object", "null" ] }, "skills_path": { "description": "URL path to the app's skills directory, or `null` when not configured.", "example": "/skills", "type": [ "string", "null" ] }, "status": { "description": "Visibility on the Whop app store: `live` is publicly discoverable, `unlisted` is accessible only via direct link, `hidden` is not visible anywhere.", "enum": [ "live", "unlisted", "hidden" ], "example": "unlisted", "type": "string" }, "verified": { "description": "Whether the app has been verified by Whop and is eligible for the featured apps section.", "example": false, "type": "boolean" } }, "required": [ "id", "name", "description", "status", "base_url", "domain_id", "route", "hosted_url", "domains", "verified", "app_type", "origin", "experience_path", "discover_path", "dashboard_path", "skills_path", "openapi_path", "account", "icon", "banner_image", "creator", "businesses_created_count", "businesses_created_logo_urls", "businesses_with_recent_sales_count", "app_store_description", "requested_permissions", "api_key", "default_api_key", "production_web_build", "production_ios_build", "production_android_build", "redirect_uris", "required_scopes", "secrets", "product_id", "marketplace_status", "oauth_client_type", "schedule", "per_install_schedule", "deployment", "elements_used", "preview_token", "imported_from_url" ], "type": "object" }, "AppApiKey": { "properties": { "created_at": { "description": "When the key was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "token": { "description": "The key's secret token, sent as a bearer token to authenticate requests on the app's behalf.", "example": "eyJhbGciOiJFUzI1NiJ9.xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "token", "created_at" ], "type": "object" }, "AppBannerImage": { "properties": { "url": { "description": "Banner image URL, taken from the app's product listing.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "url" ], "type": "object" }, "AppBuild": { "properties": { "checksum": { "description": "Client-generated checksum of the build file, used to verify file integrity.", "example": "xxxxxxxxxxxxxxx", "type": "string" }, "created_at": { "description": "When the build was uploaded, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "file_url": { "description": "URL to download the uploaded build artifact.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "App build ID, prefixed `abld_`.", "example": "apbu_xxxxxxxxxxxxxx", "type": "string" }, "is_production": { "description": "Whether this build is the currently active production build for its platform.", "example": false, "type": "boolean" }, "platform": { "description": "The target platform for this build.", "enum": [ "ios", "android", "web" ], "example": "ios", "type": "string" }, "review_message": { "description": "Feedback from the reviewer explaining a rejection, or `null` if the build has not been reviewed or was approved.", "example": "The hub view crashes on launch when the member has no active membership. Fix and resubmit.", "type": [ "string", "null" ] }, "source_url": { "description": "URL to download the compressed source code archive that produced this build, or `null` when the build was uploaded without a source archive.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/zip/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "status": { "description": "The build's review status.", "enum": [ "draft", "pending", "approved", "rejected" ], "example": "rejected", "type": "string" }, "supported_app_view_types": { "items": { "description": "The view types this build supports, as declared by the developer.", "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "example": "hub", "type": "string" }, "type": "array" } }, "required": [ "id", "platform", "file_url", "source_url", "created_at", "status", "checksum", "supported_app_view_types", "review_message", "is_production" ], "type": "object" }, "AppBuildListItem": { "description": "A versioned build artifact for a Whop React Native App, submitted for review and deployment to a specific platform.", "properties": { "checksum": { "description": "A SHA-256 hash of the uploaded build file, generated by the client and used to verify file integrity.", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "type": "string" }, "created_at": { "description": "The datetime the app build was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "file_url": { "description": "A URL to download the app build as a .zip archive.", "example": "https://cdn.whop.com/builds/abc123.zip", "type": "string" }, "id": { "description": "The unique identifier for the app build.", "example": "apbu_xxxxxxxxxxxxx", "type": "string" }, "is_production": { "description": "Whether this build is the currently active production build for its platform.", "type": "boolean" }, "platform": { "$ref": "#/components/schemas/AppBuildPlatforms", "description": "The target platform for this build." }, "review_message": { "description": "Feedback from the reviewer explaining why the build was rejected. Null if the build has not been reviewed or was approved.", "example": "App crashes on launch. Please fix and resubmit.", "type": [ "string", "null" ] }, "source_url": { "description": "A URL to download the compressed source code archive that produced this build. Null if the build was uploaded without a source archive.", "example": "https://cdn.whop.com/builds/abc123-source.zip", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AppBuildStatuses", "description": "The current review status of this build." }, "supported_app_view_types": { "description": "The list of view types this build supports, as declared by the developer.", "items": { "$ref": "#/components/schemas/AppViewTypes" }, "type": "array" } }, "required": [ "id", "platform", "file_url", "source_url", "created_at", "status", "checksum", "supported_app_view_types", "review_message", "is_production" ], "type": "object" }, "AppBuildPlatforms": { "description": "The different platforms an app build can target.", "enum": [ "ios", "android", "web" ], "type": "string" }, "AppBuildStatuses": { "description": "The different statuses an AppBuild can be in.", "enum": [ "draft", "pending", "approved", "rejected" ], "type": "string" }, "AppCreator": { "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "Public username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "AppDefaultApiKey": { "properties": { "id": { "description": "API key ID, prefixed `apik_`.", "example": "apik_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Human-readable name identifying the API key, or `null` when none was set.", "example": "Default", "type": [ "string", "null" ] }, "obfuscated_secret_key": { "description": "Masked version of the secret key, so the key can be recognized without revealing the full secret.", "example": "apik_xxxx....xxxx", "type": "string" }, "secret_key": { "description": "The full secret used to authenticate requests. `null` unless the caller could have created the key themselves.", "example": "apik_xxxxxxxxxxxxxx_C0000_C_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "name", "obfuscated_secret_key", "secret_key" ], "type": "object" }, "AppDeployment": { "properties": { "app_id": { "description": "The app being deployed, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "build_id": { "description": "The build the deployment produced, prefixed `abld_`, or `null` until it succeeds.", "example": null, "type": [ "string", "null" ] }, "draft": { "description": "Whether the running or last deployment uploaded a build without making it live.", "example": false, "type": "boolean" }, "error": { "description": "Why the deployment failed, or `null` when it did not.", "example": null, "type": [ "string", "null" ] }, "estimated_duration_ms": { "description": "How long this deployment is expected to take in total, estimated from previous runs.", "example": 150000, "type": [ "integer", "null" ] }, "estimated_remaining_ms": { "description": "How much longer the deployment is expected to take. Held above zero until it actually finishes.", "example": 91000, "type": [ "integer", "null" ] }, "finished_at": { "description": "When the deployment ended, in milliseconds since the epoch, or `null` while it is still running.", "example": null, "type": [ "integer", "null" ] }, "phase": { "description": "The stage a running deployment has reached, or `null` when none is running. Later phases dominate the wall clock: `process_archive` waits on the upload pipeline and `promote` waits for the build to go live.", "enum": [ "install", "build", "typecheck", "upload_build", "upload_source", "process_archive", "create_build", "promote", null ], "example": "process_archive", "type": [ "string", "null" ] }, "progress": { "description": "Fraction of the deployment estimated to be complete, from 0 to 1. Stops just short of 1 until the run ends.", "example": 0.39, "type": [ "number", "null" ] }, "started_at": { "description": "When the deployment began, in milliseconds since the epoch, or `null` when none has run.", "example": 1767268800000, "type": [ "integer", "null" ] }, "status": { "description": "Whether the app has anything to publish, and what a publish in flight is doing. `unpublished` means publishing would ship something new; `no_source` means the sandbox holds no copy of this app, so there is nothing to publish from.", "enum": [ "published", "unpublished", "publishing", "failed", "no_source" ], "example": "publishing", "type": "string" }, "url": { "description": "Where the deployed site is served, or `null` unless the deployment went live.", "example": null, "type": [ "string", "null" ] } }, "required": [ "app_id", "status", "draft", "phase", "started_at", "finished_at", "estimated_duration_ms", "estimated_remaining_ms", "progress", "build_id", "url", "error" ], "type": "object" }, "AppDomain": { "properties": { "domain": { "description": "Normalized hostname assigned to this app.", "example": "from-template.whop.site", "type": "string" }, "id": { "description": "Domain ID, prefixed `dom_`.", "example": "dom_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Domain lifecycle status, matching the domain resource.", "enum": [ "idle", "pending", "ready", "action_required", "releasing" ], "example": "ready", "type": "string" } }, "required": [ "id", "domain", "status" ], "type": "object" }, "AppIcon": { "properties": { "url": { "description": "Icon image URL. Always present — the default app icon when none is uploaded.", "example": "https://pub-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.dev/custom-perk-icon.svg", "type": "string" } }, "required": [ "url" ], "type": "object" }, "AppInstallation": { "properties": { "account": { "$ref": "#/components/schemas/AccountSummary", "description": "Account the app is installed on." }, "app": { "$ref": "#/components/schemas/AppSummary", "description": "App that is installed." }, "created_at": { "description": "When the app was first installed on the account, as an ISO 8601 timestamp. Installing the app again later keeps the original time.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "external_id": { "description": "Your app's own identifier for this installation, such as the ID of the linked account in another system, or `null` when none is set. At most 255 characters and unique across your app's installations, so you can find an installation with `GET /app_installations?external_id=`; setting one another installation already has returns a `409`. Only the app and its developer see it; for the account the app is installed on it is always `null`.", "example": "acme-books", "type": [ "string", "null" ] }, "id": { "description": "App installation ID, prefixed `aag_`.", "example": "aag_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "String keys and values your app stores about this installation, such as a sync cursor or the ID of the linked account in another system. Empty until your app sets a key, and kept if the account removes the app and installs it again. At most 50 keys; keys are at most 100 characters and values at most 500. Only the app can change it. Only the app and its developer see it; for the account the app is installed on it is always `null`.", "example": { "last_synced_at": "2026-01-01T12:00:00.000Z", "quickbooks_realm_id": "9341452712" }, "type": [ "object", "null" ] }, "requesting_reauthorization": { "description": "Whether the app now asks for permissions the account hasn't approved yet.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the installation last changed, such as a `metadata` update or the account changing the app's permissions, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "app", "account", "external_id", "metadata", "requesting_reauthorization", "created_at", "updated_at" ], "type": "object" }, "AppListItem": { "properties": { "account": { "$ref": "#/components/schemas/AccountParent", "description": "The account that owns the app." }, "app_type": { "description": "The type of end-user the app is built for.", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "example": "b2c_app", "type": "string" }, "banner_image": { "description": "Banner image from the app's product listing, or `null` when none is uploaded.", "oneOf": [ { "$ref": "#/components/schemas/AppBannerImage" }, { "type": "null" } ] }, "base_url": { "description": "The production base URL where the app is hosted. `null` if no base URL is configured, if the caller lacks the `developer:basic:read` permission on the app's account, or on list responses, which never expose it.", "example": "https://shine-time-booking-store.whop.site", "type": [ "string", "null" ] }, "businesses_created_count": { "description": "Number of businesses created from this app as a template.", "example": 0, "type": "integer" }, "businesses_created_logo_urls": { "items": { "description": "Up to three logo image URLs from businesses created from this app as a template.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "type": "array" }, "businesses_with_recent_sales_count": { "description": "Number of businesses created from this app as a template that processed a payment in the last 24 hours. Recounted hourly, so it can be up to an hour behind.", "example": 0, "type": "integer" }, "creator": { "$ref": "#/components/schemas/AppCreator", "description": "The user who owns the publishing account." }, "dashboard_path": { "description": "URL path for the account dashboard view, or `null` when not configured.", "example": "/dashboard/[companyId]", "type": [ "string", "null" ] }, "description": { "description": "Short description shown in listings and search results, or `null` if none has been set.", "example": "Let members book a mobile detailing appointment without leaving your whop.", "type": [ "string", "null" ] }, "discover_path": { "description": "URL path for the discover view, or `null` when not configured.", "example": "/discover", "type": [ "string", "null" ] }, "domain_id": { "description": "Subdomain identifier for the app's proxied URL, forming https://{domain_id}.apps.whop.com.", "example": "whopappdomain0000001", "type": "string" }, "domains": { "items": { "$ref": "#/components/schemas/AppDomain", "description": "Domains this app is served at or assigned to, such as its whop.site address, excluding removed domains. Everyone sees the domains serving the app; callers with the account's `domain:read` permission also see the rest." }, "type": "array" }, "experience_path": { "description": "URL path for the member-facing hub view, or `null` when not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "hosted_url": { "deprecated": true, "description": "Full URL where the app's hosted web build is served, or `null` if no route is claimed.\nDEPRECATED: Read `domains` instead.", "example": "https://shine-time-booking-store.whop.site", "type": [ "string", "null" ] }, "icon": { "$ref": "#/components/schemas/AppIcon", "description": "The app's icon. Falls back to the default app icon when none is uploaded." }, "id": { "description": "App ID, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name shown on the app store and in experience navigation.", "example": "Shine Time Booking", "type": "string" }, "openapi_path": { "description": "URL path to the app's OpenAPI spec file, or `null` when not configured.", "example": "/openapi.json", "type": [ "string", "null" ] }, "origin": { "description": "Full origin URL of the app's proxied domain, for example https://ab1c2d3e4f.apps.whop.com.", "example": "https://whopappdomain0000001.apps.whop.com", "type": [ "string", "null" ] }, "route": { "deprecated": true, "description": "Claimed subdomain route where hosted web builds are served (`myapp` for myapp.whop.site), or `null` if no route is claimed.\nDEPRECATED: Read `domains` instead.", "example": "shine-time-booking-store", "type": [ "string", "null" ] }, "skills_path": { "description": "URL path to the app's skills directory, or `null` when not configured.", "example": "/skills", "type": [ "string", "null" ] }, "status": { "description": "Visibility on the Whop app store: `live` is publicly discoverable, `unlisted` is accessible only via direct link, `hidden` is not visible anywhere.", "enum": [ "live", "unlisted", "hidden" ], "example": "live", "type": "string" }, "verified": { "description": "Whether the app has been verified by Whop and is eligible for the featured apps section.", "example": true, "type": "boolean" } }, "required": [ "id", "name", "description", "status", "base_url", "domain_id", "route", "hosted_url", "domains", "verified", "app_type", "origin", "experience_path", "discover_path", "dashboard_path", "skills_path", "openapi_path", "account", "icon", "banner_image", "creator", "businesses_created_count", "businesses_created_logo_urls", "businesses_with_recent_sales_count" ], "type": "object" }, "AppOauthClientTypes": { "description": "How this app authenticates at the OAuth token endpoint.", "enum": [ "public", "confidential" ], "type": "string" }, "AppOrder": { "description": "The order to fetch the apps in for discovery.", "enum": [ "created_at", "discoverable_at", "total_installs_last_30_days", "total_installs_last_7_days", "time_spent", "time_spent_last_24_hours", "daily_active_users", "ai_prompt_count", "total_ai_cost_usd", "total_ai_tokens", "last_ai_prompt_at", "ai_average_rating" ], "type": "string" }, "AppProductionBuild": { "properties": { "checksum": { "description": "Client-generated checksum of the build file, used to verify file integrity.", "example": "xxxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "file_url": { "description": "URL to download the uploaded build artifact.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "App build ID, prefixed `abld_`.", "example": "apbu_xxxxxxxxxxxxxx", "type": "string" }, "source_url": { "description": "URL to download the compressed source code archive that produced this build, or `null` when the build was uploaded without a source archive.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "status": { "description": "The build's review status.", "enum": [ "draft", "pending", "approved", "rejected" ], "example": "approved", "type": "string" } }, "required": [ "id", "file_url", "source_url", "checksum", "status" ], "type": "object" }, "AppRequestedPermission": { "properties": { "is_required": { "description": "Whether the app requires the permission to be granted on install, as opposed to requesting it optionally.", "example": true, "type": "boolean" }, "justification": { "description": "The developer's explanation of why the app needs the permission, or `null` when none was provided.", "example": "Creates apps on behalf of the installing company.", "type": [ "string", "null" ] }, "permission_action": { "$ref": "#/components/schemas/AppRequestedPermissionAction", "description": "The permission action the app requests." } }, "required": [ "permission_action", "is_required", "justification" ], "type": "object" }, "AppRequestedPermissionAction": { "properties": { "action": { "description": "The permission action's identifier, for example `company:basic:read`.", "example": "company:basic:read", "type": "string" }, "name": { "description": "Human-readable name of the action.", "example": "company:basic:read", "type": "string" } }, "required": [ "action", "name" ], "type": "object" }, "AppStatuses": { "description": "The status of an experience interface", "enum": [ "live", "unlisted", "hidden" ], "type": "string" }, "AppSummary": { "properties": { "developer": { "$ref": "#/components/schemas/AccountSummary", "description": "Account that develops the app." }, "icon": { "$ref": "#/components/schemas/AppIcon", "description": "App icon. Falls back to the default app icon when none is uploaded." }, "id": { "description": "App ID, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "App display name.", "example": "Other App", "type": "string" } }, "required": [ "id", "name", "icon", "developer" ], "type": "object" }, "AppTypes": { "description": "The type of end-user an app is built for", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "type": "string" }, "AppUsageStats": { "properties": { "dau": { "description": "Daily active users.", "type": [ "integer", "null" ] }, "mau": { "description": "Monthly active users.", "type": [ "integer", "null" ] }, "time_spent_last24_hours": { "description": "Total time users spent in the app over the last 24 hours, in seconds.", "type": [ "integer", "null" ] }, "wau": { "description": "Weekly active users.", "type": [ "integer", "null" ] } }, "required": [ "dau", "wau", "mau", "time_spent_last24_hours" ], "type": "object" }, "AppValidScopes": { "const": "read_user", "description": "These are the scopes an app can request on behalf of a user", "type": "string" }, "AppViewTypes": { "description": "The different types of an app view", "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "type": "string" }, "Audience": { "properties": { "audience_type": { "description": "Whether the audience targets a defined group of people or people similar to an existing audience.", "enum": [ "custom", "lookalike" ], "example": "lookalike", "type": "string" }, "auto_refresh": { "description": "Whether Whop rebuilds membership from saved People filters twice a day. When `false`, People audiences keep the members matched at creation. Always `false` for uploaded lists, lookalikes, and engagement audiences. Engagement membership is maintained by Meta.", "example": false, "type": "boolean" }, "created_at": { "description": "When the audience was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "engagement": { "description": "Social engagement rules maintained by the ad platform. `null` for other audience sources.", "oneOf": [ { "$ref": "#/components/schemas/AudienceEngagement" }, { "type": "null" } ] }, "error_message": { "description": "Processing error message. `null` unless processing is partial or failed.", "example": "412 of 1,000 rows had no email or phone number, so the list could not be matched.", "type": [ "string", "null" ] }, "filters": { "description": "Saved Whop People filters that define membership, using the same keys as `GET /people`. `null` for uploaded lists, engagement audiences, and lookalikes.", "example": { "country": "US", "last_seen_within_days": 30 }, "type": [ "object", "null" ] }, "id": { "description": "Audience ID, prefixed `adaud_`.", "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "last_refreshed_at": { "description": "When the audience membership was last rebuilt, as an ISO 8601 timestamp. `null` until the first build completes.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "lookalike_ratio": { "description": "For lookalikes: the upper bound of the similarity band as a fraction (0.02 = top 2%). `null` for custom audiences.", "example": 0.04, "type": [ "number", "null" ] }, "lookalike_starting_ratio": { "description": "For lookalikes: the lower bound of the similarity band as a fraction. `null` for custom audiences and first-tier lookalikes.", "example": 0.02, "type": [ "number", "null" ] }, "match_rates": { "items": { "$ref": "#/components/schemas/AudienceMatchRate", "description": "Estimated match rates by ad platform. Empty for engagement audiences and audiences not sent to a supported platform." }, "type": "array" }, "matched_rows": { "description": "Members successfully uploaded to connected ad accounts. Always 0 for lookalikes and engagement audiences.", "example": 0, "type": "number" }, "name": { "description": "Audience display name.", "example": "Past purchasers Lookalike 2–4%", "type": "string" }, "platform_audience_ids": { "items": { "description": "External audience IDs created on connected ad platforms, such as Meta.", "example": "120246230799130687", "type": "string" }, "type": "array" }, "processed_rows": { "description": "Members processed from the source so far. Always 0 for lookalikes and engagement audiences.", "example": 0, "type": "number" }, "progress_percent": { "description": "Processing progress from 0 to 100.", "example": 0, "type": "number" }, "source_audience_id": { "description": "For lookalikes: the audience this lookalike was built from. `null` for custom audiences.", "example": "adaud_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source_type": { "description": "Membership source: an uploaded CSV, Whop People filters, or social engagement.", "enum": [ "csv_upload", "people_filter", "engagement" ], "example": "csv_upload", "type": "string" }, "status": { "description": "Current state of audience creation. For engagement audiences, `ready` means the rules were created on Meta; membership may still be populating. `syncing` means Whop is sending matched rows to connected ad accounts. When status is `partial` or `failed`, `error_message` explains what went wrong.", "enum": [ "pending", "processing", "syncing", "ready", "partial", "failed" ], "type": "string" }, "total_rows": { "description": "Total members detected in the source — CSV rows for uploaded lists, matching people for automatic audiences. Always 0 for lookalikes and engagement audiences.", "example": 0, "type": "number" }, "updated_at": { "description": "When the audience was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "name", "audience_type", "source_type", "status", "total_rows", "processed_rows", "matched_rows", "progress_percent", "error_message", "platform_audience_ids", "source_audience_id", "lookalike_ratio", "lookalike_starting_ratio", "engagement", "filters", "auto_refresh", "last_refreshed_at", "created_at", "updated_at", "match_rates" ], "type": "object" }, "AudienceEngagement": { "properties": { "exclude": { "description": "Exclude anyone matching any exclusion rule. Supply 0–10 rules. Video audiences do not support exclusions; use a separate audience in ad-group exclusions.", "items": { "$ref": "#/components/schemas/AudienceEngagementRule" }, "type": "array" }, "include": { "description": "Match any inclusion rule. Supply 1–10 rules. Video rules must share a retention window and cannot be combined with other sources.", "items": { "$ref": "#/components/schemas/AudienceEngagementRule" }, "type": "array" }, "platform": { "description": "Ad platform that maintains membership.", "enum": [ "meta" ], "example": "meta", "type": "string" } }, "required": [ "platform", "include", "exclude" ], "type": "object" }, "AudienceEngagementFacebookPageRule": { "properties": { "event": { "description": "Interaction that qualifies a person for this rule.", "enum": [ "engaged", "visited", "liked", "messaged", "cta_clicked", "saved", "post_interaction" ], "example": "engaged", "type": "string" }, "external_account_id": { "description": "Connected external account ID, prefixed `sacc_`, with advertising access.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "object": { "description": "Engagement source.", "enum": [ "facebook_page" ], "example": "facebook_page", "type": "string" }, "retention_days": { "description": "Rolling membership window in days, from 1 to 730. Use 0 for `liked`, which tracks current likes and cannot be combined with other events.", "example": 30, "type": "integer" } }, "required": [ "object", "external_account_id", "event", "retention_days" ], "type": "object" }, "AudienceEngagementInstagramProfileRule": { "properties": { "event": { "description": "Interaction that qualifies a person for this rule.", "enum": [ "all", "engaged", "visited", "messaged", "saved", "ad_liked", "ad_commented", "ad_shared", "ad_saved", "ad_cta_clicked", "ad_carousel_swiped", "organic_liked", "organic_commented", "organic_shared", "organic_saved", "organic_swiped", "organic_carousel_swiped" ], "example": "all", "type": "string" }, "external_account_id": { "description": "Connected external account ID, prefixed `sacc_`, with advertising access.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "object": { "description": "Engagement source.", "enum": [ "instagram_profile" ], "example": "instagram_profile", "type": "string" }, "retention_days": { "description": "Rolling membership window in days, from 1 to 730.", "example": 30, "type": "integer" } }, "required": [ "object", "external_account_id", "event", "retention_days" ], "type": "object" }, "AudienceEngagementLeadFormRule": { "properties": { "event": { "description": "Interaction that qualifies a person for this rule.", "enum": [ "opened", "submitted", "not_submitted" ], "example": "opened", "type": "string" }, "external_account_id": { "description": "Connected external account ID, prefixed `sacc_`, with advertising access.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "object": { "description": "Engagement source.", "enum": [ "lead_form" ], "example": "lead_form", "type": "string" }, "platform_form_ids": { "items": { "description": "Numeric platform lead form IDs belonging to the selected external account. Supply 1–50 IDs.", "example": "333", "type": "string" }, "type": "array" }, "retention_days": { "description": "Rolling membership window in days, from 1 to 90.", "example": 30, "type": "integer" } }, "required": [ "object", "external_account_id", "event", "retention_days", "platform_form_ids" ], "type": "object" }, "AudienceEngagementRule": { "discriminator": { "mapping": { "facebook_page": "#/components/schemas/AudienceEngagementFacebookPageRule", "instagram_profile": "#/components/schemas/AudienceEngagementInstagramProfileRule", "lead_form": "#/components/schemas/AudienceEngagementLeadFormRule", "video": "#/components/schemas/AudienceEngagementVideoRule" }, "propertyName": "object" }, "oneOf": [ { "$ref": "#/components/schemas/AudienceEngagementVideoRule" }, { "$ref": "#/components/schemas/AudienceEngagementLeadFormRule" }, { "$ref": "#/components/schemas/AudienceEngagementInstagramProfileRule" }, { "$ref": "#/components/schemas/AudienceEngagementFacebookPageRule" } ] }, "AudienceEngagementVideoRule": { "properties": { "event": { "description": "Interaction that qualifies a person for this rule.", "enum": [ "watched_3_seconds", "watched_10_seconds", "watched_15_seconds", "watched_25_percent", "watched_50_percent", "watched_75_percent", "watched_95_percent" ], "example": "watched_50_percent", "type": "string" }, "external_account_id": { "description": "Connected external account ID, prefixed `sacc_`, with advertising access.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "object": { "description": "Engagement source.", "enum": [ "video" ], "example": "video", "type": "string" }, "platform_video_ids": { "items": { "description": "Numeric platform video IDs belonging to the selected external account. Supply 1–50 IDs.", "example": "444", "type": "string" }, "type": "array" }, "retention_days": { "description": "Rolling membership window in days, from 1 to 365.", "example": 30, "type": "integer" } }, "required": [ "object", "external_account_id", "event", "retention_days", "platform_video_ids" ], "type": "object" }, "AudienceMatchRate": { "properties": { "lower_bound": { "description": "Lower bound of the estimated match rate percentage. `null` until available.", "example": 40.0, "type": [ "number", "null" ] }, "platform": { "description": "The ad platform that provided the match-rate estimate.", "enum": [ "meta" ], "example": "meta", "type": "string" }, "status": { "description": "Availability of the estimated match rate.", "enum": [ "calculating", "available", "unavailable", null ], "example": "available", "type": [ "string", "null" ] }, "upper_bound": { "description": "Upper bound of the estimated match rate percentage. `null` until available.", "example": 50.0, "type": [ "number", "null" ] } }, "required": [ "platform", "status", "lower_bound", "upper_bound" ], "type": "object" }, "AuthorizedUser": { "description": "A user who belongs to a company's team with access determined by their assigned role.", "properties": { "company": { "description": "The company this authorized user has access to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "id": { "description": "The unique identifier for the authorized user.", "example": "ausr_xxxxxxxxxxxxx", "type": "string" }, "role": { "$ref": "#/components/schemas/AuthorizedUserRoles", "description": "The permission role assigned to this authorized user within the company." }, "user": { "description": "The user account linked to this authorized user record.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": "object" } }, "required": [ "id", "role", "user", "company" ], "type": "object" }, "AuthorizedUserListItem": { "description": "A user who belongs to a company's team with access determined by their assigned role.", "properties": { "company": { "description": "The company this authorized user has access to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "id": { "description": "The unique identifier for the authorized user.", "example": "ausr_xxxxxxxxxxxxx", "type": "string" }, "role": { "$ref": "#/components/schemas/AuthorizedUserRoles", "description": "The permission role assigned to this authorized user within the company." }, "user": { "description": "The user account linked to this authorized user record.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": "object" } }, "required": [ "id", "role", "user", "company" ], "type": "object" }, "AuthorizedUserRoles": { "description": "Possible roles an authorized user can have", "enum": [ "owner", "admin", "partner", "sales_manager", "moderator", "advertiser", "app_manager", "support", "manager", "workforce", "custom" ], "type": "string" }, "BillingReasons": { "description": "The reason why a specific payment was billed", "enum": [ "subscription_create", "subscription_cycle", "subscription_update", "one_time", "manual", "subscription" ], "example": "subscription_create", "type": "string" }, "Bounty": { "properties": { "accepted_deliverable_types": { "items": { "description": "The deliverable shapes this bounty accepts. Every bounty accepts any combination of `content_url` (posted links) and `media` (uploaded files), except `data_capture` bounties, whose proof is clips recorded in the Whop app that accumulate on the attempt.", "enum": [ "content_url", "media", "data_capture" ], "example": "data_capture", "type": "string" }, "type": "array" }, "accepted_submissions_count": { "description": "Submissions accepted so far.", "example": 0, "type": "integer" }, "accepted_submissions_limit": { "description": "Number of submissions that can be accepted (winner slots).", "example": 3, "type": "integer" }, "accepted_submissions_per_user_limit": { "description": "How many winner slots one worker can win. Defaults to `1`. Wins plus proofs awaiting review never exceed this number, and a worker runs one attempt at a time. Cannot exceed `accepted_submissions_limit`.", "example": 1, "type": "integer" }, "active_proof_livestream_feeds": { "items": { "$ref": "#/components/schemas/BountyActiveLivestreamFeed", "description": "Proof livestreams live on this bounty right now, newest first — workers streaming their attempts. Empty when nothing is live." }, "type": "array" }, "affiliate_share_amount": { "description": "What a referrer earns per accepted submission when the worker arrived through their affiliate link, in whole currency units, at the standard platform fee rate. Taken out of the worker's post-fee reward rather than added on top. `0` when the bounty pays no affiliate share, including bounties tied to no account, which cannot record a referral.", "example": 5.6, "type": "number" }, "allowed_country_codes": { "items": { "description": "Countries whose residents can work the bounty, as ISO 3166 alpha-2 codes. Empty means worldwide.", "example": "US", "type": "string" }, "type": "array" }, "awaiting_review_submissions_count": { "description": "Submissions delivered and waiting on review. A subset of `unresolved_submissions_count`, which also counts attempts still in progress.", "example": 0, "type": "integer" }, "budget_amount": { "description": "Total gross budget committed to the bounty: `gross_reward_amount` times `accepted_submissions_limit`.", "example": 120.0, "type": "number" }, "business_goal_type": { "description": "What the poster wants the work to achieve, declared once at create. `null` for bounties created before the taxonomy rolled out.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other", null ], "example": "data_capture", "type": [ "string", "null" ] }, "cancel_requested_at": { "description": "When cancellation was requested, as an ISO 8601 timestamp. On a `closed` bounty this means the cancel is pending: submissions are stopped and the bounty cancels once in-flight submissions resolve. On a `canceled` bounty it records when the cancellation was requested. `null` when no cancellation was ever requested.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "capture_spec": { "description": "The technical contract footage must be recorded against. Present only on `data_capture` bounties; `null` for every other goal type.", "oneOf": [ { "$ref": "#/components/schemas/CaptureSpec" }, { "type": "null" } ] }, "created_at": { "description": "When the bounty was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency for all amounts on the bounty, as a lowercase ISO 4217 code.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "cny", "kzt", "awg" ], "example": "usd", "type": "string" }, "denied_submissions_count": { "description": "Submissions reviewed and turned down.", "example": 0, "type": "integer" }, "description": { "description": "Full task instructions shown to workers.", "example": "Record one continuous pass of a full interior detail, dash to trunk, on a customer vehicle.", "type": "string" }, "discussion_experience_id": { "description": "Experience the bounty's discussion thread lives in, prefixed `exp_`. Read this — not `experience_id` — to open the thread: a platform-wide bounty has no hosting experience of its own but its discussion still lives in one.", "example": null, "type": [ "string", "null" ] }, "discussion_feed_id": { "description": "Forum feed containing the bounty's discussion thread. `null` for a bounty with no forum post.", "example": null, "type": [ "string", "null" ] }, "discussion_post_id": { "description": "Forum post anchoring the bounty's discussion thread. Read together with `discussion_experience_id` to address the thread. `null` for a bounty with no forum post.", "example": null, "type": [ "string", "null" ] }, "experience_id": { "description": "Experience the bounty is hosted in, prefixed `exp_`. `null` for platform-wide bounties; may belong to a different account than the funder.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "funding_account": { "description": "Account whose balance funds the bounty pool, or `null` when a user funds it personally. May differ from the account hosting `experience_id`.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "gross_paid_out_amount": { "description": "Gross amount paid out from the bounty pool across accepted submissions — worker payouts, platform fees, and affiliate shares together. Tips and reviewer rewards are excluded.", "example": 0.0, "type": "number" }, "gross_reward_amount": { "description": "Gross bounty-pool amount allocated per accepted submission, in whole currency units.", "example": 40.0, "type": "number" }, "hosting_account": { "description": "Account hosting the bounty's forum — the one whose `route` and `experience_id` address its discussion thread, and where its submissions dashboard lives. `null` for a platform-wide bounty with no host. May differ from `funding_account`.", "oneOf": [ { "$ref": "#/components/schemas/StorefrontAccount" }, { "type": "null" } ] }, "id": { "description": "Bounty ID, prefixed `bnty_`.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "min_total_verified_duration_seconds": { "description": "Total verified footage a submission must accumulate before it can be submitted, in seconds. Always a whole number of hours. Present only on `data_capture` bounties — it is what `net_reward_amount` pays for, so rate displays divide by it. `null` for every other goal type.", "example": 14400, "type": [ "integer", "null" ] }, "net_reward_amount": { "description": "What a worker is quoted per accepted submission after the platform fee, in whole currency units. The exact post-fee figure, at the standard platform fee rate — a worker who locked a different rate, or who arrived through an affiliate link, is paid a different amount.", "example": 28.0, "type": "number" }, "poster": { "$ref": "#/components/schemas/UserSummary", "description": "User who posted the bounty — the account owner when created with an account API key." }, "scheduled_frequency": { "description": "How often the schedule creates a new bounty. Each occurrence is a separate bounty; the original is not republished.", "enum": [ "once", "hourly", "daily", "weekly", "monthly", null ], "example": "weekly", "type": [ "string", "null" ] }, "scheduled_publish_at": { "description": "When a scheduled bounty will publish, as an ISO 8601 timestamp. `null` once published, for bounties that were never scheduled, and for terminally failed drafts parked for manual rescheduling.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "spots_remaining": { "description": "Unfilled winner capacity: `accepted_submissions_limit` minus `accepted_submissions_count`, clamped to zero. Not on its own a signal that the bounty accepts new claims — read `status` for that: only an `open` bounty takes new submissions.", "example": 3, "type": "integer" }, "status": { "description": "Lifecycle state. `scheduled` bounties are unpublished drafts, visible to their poster and the account's authorized managers; `open` bounties accept new submissions; `closed` bounties are live but no longer accept new submissions; `completed` bounties paid out every winner slot; `canceled` bounties ended before filling their slots.", "enum": [ "scheduled", "open", "closed", "completed", "canceled" ], "example": "scheduled", "type": "string" }, "submissions_closed_at": { "description": "When new submissions stopped being accepted, as an ISO 8601 timestamp. Set when a cancellation is requested on a bounty with work in flight, so in-flight submissions can resolve before the bounty cancels. `null` when submissions were never stopped — including completed bounties that simply filled every winner slot.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "title": { "description": "Short name of the task shown to workers.", "example": "Record interior detailing passes", "type": "string" }, "unresolved_submissions_count": { "description": "Submissions still awaiting an outcome: in progress or pending review.", "example": 0, "type": "integer" }, "updated_at": { "description": "When the bounty was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "viewer_accepted_submissions_count": { "description": "How many winner slots the authenticated user has already won on this bounty. Read against `accepted_submissions_per_user_limit` to show a worker their remaining allowance. `0` when the request has no authenticated user.", "example": 0, "type": "integer" } }, "required": [ "id", "title", "description", "status", "currency", "gross_reward_amount", "net_reward_amount", "affiliate_share_amount", "budget_amount", "gross_paid_out_amount", "accepted_submissions_limit", "accepted_submissions_per_user_limit", "accepted_submissions_count", "unresolved_submissions_count", "viewer_accepted_submissions_count", "spots_remaining", "business_goal_type", "accepted_deliverable_types", "min_total_verified_duration_seconds", "allowed_country_codes", "submissions_closed_at", "cancel_requested_at", "scheduled_publish_at", "scheduled_frequency", "experience_id", "discussion_post_id", "discussion_feed_id", "discussion_experience_id", "created_at", "updated_at", "capture_spec", "awaiting_review_submissions_count", "denied_submissions_count", "poster", "funding_account", "hosting_account", "active_proof_livestream_feeds" ], "type": "object" }, "BountyActiveLivestreamFeed": { "properties": { "host": { "description": "User hosting the proof livestream — the worker streaming their attempt. `null` if the host account no longer exists.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] }, "id": { "description": "Livestream feed ID.", "type": "string" }, "title": { "description": "Display title for the proof livestream.", "type": "string" } }, "required": [ "id", "title", "host" ], "type": "object" }, "BountyCaptureClip": { "properties": { "bounty_submission_id": { "description": "The bounty submission (attempt) this clip belongs to, prefixed `btys_`.", "example": "btys_xxxxxxxxxxxxxx", "type": "string" }, "created_at": { "description": "When the clip was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "duration_seconds": { "description": "Server-validated clip duration in whole seconds. `null` until validation completes.", "example": 180, "type": [ "integer", "null" ] }, "failure_code": { "description": "Stable validation failure code. `null` unless `status` is `failed`.", "example": "upload_failed", "type": [ "string", "null" ] }, "failure_message": { "description": "Human-readable validation failure reason. `null` unless `status` is `failed`.", "example": "video: The video upload failed after 5 retries.", "type": [ "string", "null" ] }, "frames_url": { "description": "Temporary signed URL for the video frame timestamp log. Returned only on single-clip reads for an authorized viewer; `null` on list responses or until the artifact is attached.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "Capture clip ID, prefixed `bclip_`.", "example": "bclip_xxxxxxxxxxxxxx", "type": "string" }, "imu_url": { "description": "Temporary signed URL for the IMU (accelerometer + gyroscope) log. Returned only on single-clip reads for an authorized viewer; `null` on list responses or until the artifact is attached.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "manifest_url": { "description": "Temporary signed URL for the capture manifest. Returned only on single-clip reads for an authorized viewer; `null` on list responses or until the artifact is attached.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "ready_at": { "description": "When server-side validation completed successfully, as an ISO 8601 timestamp. `null` until then.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "sequence": { "description": "The clip's stable order within the attempt, starting at 1.", "example": 1, "type": "integer" }, "status": { "description": "Recording and validation state. `recording` is still capturing; `verifying` is running server-side validation; `ready` passed validation and counts toward the verified-duration payout gate; `failed` did not validate.", "enum": [ "recording", "verifying", "ready", "failed" ], "example": "ready", "type": "string" }, "updated_at": { "description": "When the clip was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "video_url": { "description": "Temporary signed URL for the synchronized MP4 video. Returned only on single-clip reads for an authorized viewer; `null` on list responses or until the artifact is attached.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "bounty_submission_id", "sequence", "status", "duration_seconds", "failure_code", "failure_message", "ready_at", "video_url", "imu_url", "frames_url", "manifest_url", "created_at", "updated_at" ], "type": "object" }, "BountyListItem": { "properties": { "accepted_deliverable_types": { "items": { "description": "The deliverable shapes this bounty accepts. Every bounty accepts any combination of `content_url` (posted links) and `media` (uploaded files), except `data_capture` bounties, whose proof is clips recorded in the Whop app that accumulate on the attempt.", "enum": [ "content_url", "media", "data_capture" ], "example": "content_url", "type": "string" }, "type": "array" }, "accepted_submissions_count": { "description": "Submissions accepted so far.", "example": 0, "type": "integer" }, "accepted_submissions_limit": { "description": "Number of submissions that can be accepted (winner slots).", "example": 1, "type": "integer" }, "accepted_submissions_per_user_limit": { "description": "How many winner slots one worker can win. Defaults to `1`. Wins plus proofs awaiting review never exceed this number, and a worker runs one attempt at a time. Cannot exceed `accepted_submissions_limit`.", "example": 1, "type": "integer" }, "affiliate_share_amount": { "description": "What a referrer earns per accepted submission when the worker arrived through their affiliate link, in whole currency units, at the standard platform fee rate. Taken out of the worker's post-fee reward rather than added on top. `0` when the bounty pays no affiliate share, including bounties tied to no account, which cannot record a referral.", "example": 2.1, "type": "number" }, "allowed_country_codes": { "items": { "description": "Countries whose residents can work the bounty, as ISO 3166 alpha-2 codes. Empty means worldwide.", "example": "US", "type": "string" }, "type": "array" }, "budget_amount": { "description": "Total gross budget committed to the bounty: `gross_reward_amount` times `accepted_submissions_limit`.", "example": 15.0, "type": "number" }, "business_goal_type": { "description": "What the poster wants the work to achieve, declared once at create. `null` for bounties created before the taxonomy rolled out.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other", null ], "example": "clipping", "type": [ "string", "null" ] }, "cancel_requested_at": { "description": "When cancellation was requested, as an ISO 8601 timestamp. On a `closed` bounty this means the cancel is pending: submissions are stopped and the bounty cancels once in-flight submissions resolve. On a `canceled` bounty it records when the cancellation was requested. `null` when no cancellation was ever requested.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "created_at": { "description": "When the bounty was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency for all amounts on the bounty, as a lowercase ISO 4217 code.", "example": "usd", "type": "string" }, "description": { "description": "Full task instructions shown to workers.", "example": "Bounty Description", "type": "string" }, "discussion_experience_id": { "description": "Experience the bounty's discussion thread lives in, prefixed `exp_`. Read this — not `experience_id` — to open the thread: a platform-wide bounty has no hosting experience of its own but its discussion still lives in one.", "example": null, "type": [ "string", "null" ] }, "discussion_feed_id": { "description": "Forum feed containing the bounty's discussion thread. `null` for a bounty with no forum post.", "example": null, "type": [ "string", "null" ] }, "discussion_post_id": { "description": "Forum post anchoring the bounty's discussion thread. Read together with `discussion_experience_id` to address the thread. `null` for a bounty with no forum post.", "example": null, "type": [ "string", "null" ] }, "experience_id": { "description": "Experience the bounty is hosted in, prefixed `exp_`. `null` for platform-wide bounties; may belong to a different account than the funder.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "funding_account": { "description": "Account whose balance funds the bounty pool, or `null` when a user funds it personally. May differ from the account hosting `experience_id`.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "gross_paid_out_amount": { "description": "Gross amount paid out from the bounty pool across accepted submissions — worker payouts, platform fees, and affiliate shares together. Tips and reviewer rewards are excluded.", "example": 0.0, "type": "number" }, "gross_reward_amount": { "description": "Gross bounty-pool amount allocated per accepted submission, in whole currency units.", "example": 15.0, "type": "number" }, "hosting_account": { "description": "Account hosting the bounty's forum — the one whose `route` and `experience_id` address its discussion thread, and where its submissions dashboard lives. `null` for a platform-wide bounty with no host. May differ from `funding_account`.", "oneOf": [ { "$ref": "#/components/schemas/StorefrontAccount" }, { "type": "null" } ] }, "id": { "description": "Bounty ID, prefixed `bnty_`.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "min_total_verified_duration_seconds": { "description": "Total verified footage a submission must accumulate before it can be submitted, in seconds. Always a whole number of hours. Present only on `data_capture` bounties — it is what `net_reward_amount` pays for, so rate displays divide by it. `null` for every other goal type.", "example": null, "type": [ "integer", "null" ] }, "net_reward_amount": { "description": "What a worker is quoted per accepted submission after the platform fee, in whole currency units. The exact post-fee figure, at the standard platform fee rate — a worker who locked a different rate, or who arrived through an affiliate link, is paid a different amount.", "example": 10.5, "type": "number" }, "poster": { "$ref": "#/components/schemas/UserSummary", "description": "User who posted the bounty — the account owner when created with an account API key." }, "scheduled_frequency": { "description": "How often the schedule creates a new bounty. Each occurrence is a separate bounty; the original is not republished.", "enum": [ "once", "hourly", "daily", "weekly", "monthly", null ], "example": "once", "type": [ "string", "null" ] }, "scheduled_publish_at": { "description": "When a scheduled bounty will publish, as an ISO 8601 timestamp. `null` once published, for bounties that were never scheduled, and for terminally failed drafts parked for manual rescheduling.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "spots_remaining": { "description": "Unfilled winner capacity: `accepted_submissions_limit` minus `accepted_submissions_count`, clamped to zero. Not on its own a signal that the bounty accepts new claims — read `status` for that: only an `open` bounty takes new submissions.", "example": 1, "type": "integer" }, "status": { "description": "Lifecycle state. `scheduled` bounties are unpublished drafts, visible to their poster and the account's authorized managers; `open` bounties accept new submissions; `closed` bounties are live but no longer accept new submissions; `completed` bounties paid out every winner slot; `canceled` bounties ended before filling their slots.", "enum": [ "scheduled", "open", "closed", "completed", "canceled" ], "example": "open", "type": "string" }, "submissions_closed_at": { "description": "When new submissions stopped being accepted, as an ISO 8601 timestamp. Set when a cancellation is requested on a bounty with work in flight, so in-flight submissions can resolve before the bounty cancels. `null` when submissions were never stopped — including completed bounties that simply filled every winner slot.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "title": { "description": "Short name of the task shown to workers.", "example": "Photograph the storefront", "type": "string" }, "unresolved_submissions_count": { "description": "Submissions still awaiting an outcome: in progress or pending review.", "example": 1, "type": "integer" }, "updated_at": { "description": "When the bounty was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "viewer_accepted_submissions_count": { "description": "How many winner slots the authenticated user has already won on this bounty. Read against `accepted_submissions_per_user_limit` to show a worker their remaining allowance. `0` when the request has no authenticated user.", "example": 0, "type": "integer" } }, "required": [ "id", "title", "description", "status", "currency", "gross_reward_amount", "net_reward_amount", "affiliate_share_amount", "budget_amount", "gross_paid_out_amount", "accepted_submissions_limit", "accepted_submissions_per_user_limit", "accepted_submissions_count", "unresolved_submissions_count", "viewer_accepted_submissions_count", "spots_remaining", "business_goal_type", "accepted_deliverable_types", "min_total_verified_duration_seconds", "allowed_country_codes", "submissions_closed_at", "cancel_requested_at", "scheduled_publish_at", "scheduled_frequency", "experience_id", "discussion_post_id", "discussion_feed_id", "discussion_experience_id", "created_at", "updated_at", "poster", "funding_account", "hosting_account" ], "type": "object" }, "BountySubmission": { "properties": { "bounty_id": { "description": "The bounty the work was submitted to, prefixed `bnty_`.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "capture_clips": { "example": null, "items": { "$ref": "#/components/schemas/BountyCaptureClip", "description": "The submission's capture clips in recording order, each carrying its own review `status` and temporary signed artifact URLs. The full deliverable when `deliverable_type` is `data_capture`, populated only on single-submission reads; `null` on list responses (use `captured_clip_count` and `captured_duration_seconds` for the summary) and for other deliverable types. An attempt still in progress lists every clip it has recorded, including failed ones; once submitted, only clips that passed validation are listed, since only those are evidence." }, "type": [ "array", "null" ] }, "capture_filename": { "description": "The vendor filename stem `Country_City_Site_Station_Operator`, derived from the capture metadata. `null` until every component is present.", "example": "US_Austin_BurnetRd_Bay2_mwebb", "type": [ "string", "null" ] }, "captured_clip_count": { "description": "Number of verified capture clips accepted for this submission so far. `0` for submissions whose deliverable doesn't accumulate clips.", "example": 0, "type": "integer" }, "captured_duration_seconds": { "description": "Total verified duration of accepted capture clips, in whole seconds. `0` for submissions whose deliverable doesn't accumulate clips.", "example": 0, "type": "integer" }, "city": { "description": "Capture metadata: city the footage was recorded in. `null` unless capture metadata was provided.", "example": "Austin", "type": [ "string", "null" ] }, "claimed_at": { "description": "When the worker claimed the submission, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "content": { "description": "Written proof the worker submitted with their work.", "example": "Ceramic coating reveal, shot at the Burnet Rd bay", "type": [ "string", "null" ] }, "country": { "description": "Capture metadata: country the footage was recorded in. `null` unless capture metadata was provided.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the submission was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "deliverable_type": { "description": "How the work arrived when it came in through the API in one shot, informational only — read the work from `deliverable_urls`, `files`, and `capture_clips` directly. `null` for submissions whose proof is a livestream recording, including ones that attached links or files on submit.", "enum": [ "content_url", "media", "data_capture", null ], "example": "media", "type": [ "string", "null" ] }, "deliverable_urls": { "items": { "description": "Links submitted as work, followed by temporary download URLs for the uploaded files. `null` when the submission carries neither.", "example": "https://tiktok.com/@shinetime/video/1", "type": "string" }, "type": [ "array", "null" ] }, "denial_reason": { "description": "Why the submission was denied, when a presentable reason exists. Always `null` unless `status` is `denied`.", "example": "The clip never shows the finished paint.", "type": [ "string", "null" ] }, "device": { "description": "Capture metadata: device the footage was recorded on. `null` unless capture metadata was provided.", "example": "iPhone 15 Pro", "type": [ "string", "null" ] }, "files": { "items": { "$ref": "#/components/schemas/BountySubmissionFile", "description": "Files uploaded as part of the work, in upload order. Empty when the submission has none." }, "type": "array" }, "fov": { "description": "Capture metadata: horizontal field of view in degrees. `null` when not reported.", "example": 120, "type": [ "integer", "null" ] }, "id": { "description": "Submission ID, prefixed `btys_`.", "example": "btys_xxxxxxxxxxxxxx", "type": "string" }, "latest_proof_livestream_feed": { "description": "Latest public proof livestream attached to the submission.", "oneOf": [ { "$ref": "#/components/schemas/BountySubmissionLivestreamFeed" }, { "type": "null" } ] }, "operator": { "description": "Capture metadata: identifier of the person who recorded the footage. `null` unless capture metadata was provided.", "example": "mwebb", "type": [ "string", "null" ] }, "resolved_at": { "description": "When the submission was approved or denied, as an ISO 8601 timestamp. `null` until then.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "site": { "description": "Capture metadata: site or venue the footage was recorded at. `null` unless capture metadata was provided.", "example": "BurnetRd", "type": [ "string", "null" ] }, "station": { "description": "Capture metadata: station or position within the site. `null` unless capture metadata was provided.", "example": "Bay2", "type": [ "string", "null" ] }, "status": { "description": "Lifecycle state. `in_progress` submissions are active attempts that have not submitted proof yet; `submitted` submissions await review; `approved` submissions were accepted and paid; `denied` submissions were rejected. `null` when the attempt ended without proof, taking it out of the public lifecycle — those attempts are absent from every public list and read.", "enum": [ "in_progress", "submitted", "approved", "denied", null ], "example": "submitted", "type": [ "string", "null" ] }, "submitted_at": { "description": "When proof was submitted for review, as an ISO 8601 timestamp. `null` while the attempt is in progress.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "updated_at": { "description": "When the submission was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "worker": { "$ref": "#/components/schemas/UserSummary", "description": "User who submitted the work." } }, "required": [ "id", "bounty_id", "status", "deliverable_type", "deliverable_urls", "files", "captured_clip_count", "captured_duration_seconds", "capture_clips", "content", "denial_reason", "claimed_at", "submitted_at", "resolved_at", "country", "city", "site", "station", "operator", "device", "fov", "capture_filename", "created_at", "updated_at", "latest_proof_livestream_feed", "worker" ], "type": "object" }, "BountySubmissionFile": { "properties": { "attachment_type": { "description": "Broad kind of file.", "enum": [ "image", "video", "audio", "other", null ], "example": "image", "type": [ "string", "null" ] }, "content_type": { "description": "MIME type of the file.", "example": "image/png", "type": [ "string", "null" ] }, "filename": { "description": "Name the file was uploaded with.", "example": "ceramic-coating-cut.png", "type": [ "string", "null" ] }, "id": { "description": "File ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "Temporary download URL for the file.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "url", "filename", "content_type", "attachment_type" ], "type": "object" }, "BountySubmissionLivestreamFeed": { "properties": { "ended_at": { "description": "When the proof livestream ended, as an ISO 8601 timestamp. `null` while it is still live — a feed with a `started_at` and no `ended_at` is streaming right now.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Livestream feed ID.", "example": "lfeed_1", "type": "string" }, "recording_status": { "description": "Recording lifecycle state.", "enum": [ "recording", "processing", "completed", "failed", null ], "example": "completed", "type": [ "string", "null" ] }, "recording_url": { "description": "Playback URL for a completed proof recording, when available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/video/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "started_at": { "description": "When the proof livestream went live, as an ISO 8601 timestamp. `null` before it starts.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "Current proof thumbnail URL, when available.", "example": "https://img.whop.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxx/resize:fit/width:1000/height:500/plain/https://cdn.whop.com/livestreams/paint-correction-proof-cover.jpg", "type": [ "string", "null" ] }, "title": { "description": "Display title for the proof livestream.", "example": "Untitled Livestream", "type": "string" } }, "required": [ "id", "title", "started_at", "ended_at", "thumbnail_url", "recording_status", "recording_url" ], "type": "object" }, "BountyTypes": { "description": "The available bounty implementation types.", "enum": [ "classic", "user_funded", "workforce" ], "type": "string" }, "BusinessGoalTypes": { "description": "What the poster is trying to accomplish with a workforce bounty. Used for product taxonomy and analytics, separate from the bounty's implementation type.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other" ], "type": "string" }, "CancelOptions": { "description": "The different reasons a user can choose for why they are canceling their membership.", "enum": [ "too_expensive", "switching", "missing_features", "technical_issues", "bad_experience", "unused", "other", "testing" ], "type": "string" }, "CancelationStatus": { "description": "The state of a membership after a customer provides a cancelation reason.", "enum": [ "won_back", "left", "canceling" ], "type": "string" }, "CaptureSpec": { "properties": { "filename_pattern": { "description": "The naming convention for uploaded files, built from the required metadata fields.", "example": "Country_City_Site_Station_Operator", "type": "string" }, "imu": { "$ref": "#/components/schemas/CaptureSpecImu", "description": "Inertial measurement unit (IMU) recording requirements." }, "manifest_schema_version": { "description": "Schema version the client must stamp on the capture manifest it uploads.", "example": 2, "type": "integer" }, "min_clip_duration_seconds": { "description": "Minimum length of a single clip, in seconds.", "example": 120, "type": "integer" }, "min_total_verified_duration_seconds": { "description": "Total verified footage a submission must accumulate across all its clips before it can be submitted, in seconds. Always a whole number of hours.", "example": 14400, "type": "integer" }, "required_metadata_fields": { "items": { "description": "Metadata fields a submission must provide, matching the `metadata` object on the submissions API.", "example": "country", "type": "string" }, "type": "array" }, "single_continuous_take": { "description": "Whether each clip must be one uninterrupted recording rather than stitched segments.", "example": true, "type": "boolean" }, "video": { "$ref": "#/components/schemas/CaptureSpecVideo", "description": "Video recording requirements." } }, "required": [ "manifest_schema_version", "video", "imu", "min_clip_duration_seconds", "min_total_verified_duration_seconds", "single_continuous_take", "required_metadata_fields", "filename_pattern" ], "type": "object" }, "CaptureSpecImu": { "properties": { "device_motion_units": { "description": "Units for the device-motion channels, as a compact key=unit string.", "example": "ua=m/s²,gv=g,r=rad/s,q=unit", "type": "string" }, "magnetometer_units": { "description": "Units for the magnetometer channel.", "example": "µT", "type": "string" }, "min_rate_hz": { "description": "Minimum sustained IMU sample rate in hertz for a clip to pass validation.", "example": 90.0, "type": "number" }, "target_rate_hz": { "description": "Target IMU sample rate in hertz.", "example": 100, "type": "integer" }, "warmup_min_rate_hz": { "description": "Minimum IMU sample rate in hertz tolerated during the warmup window.", "example": 45.0, "type": "number" }, "warmup_ns": { "description": "Startup window, in nanoseconds, during which the relaxed warmup rate applies.", "example": 3000000000, "type": "integer" } }, "required": [ "target_rate_hz", "min_rate_hz", "warmup_ns", "warmup_min_rate_hz", "device_motion_units", "magnetometer_units" ], "type": "object" }, "CaptureSpecVideo": { "properties": { "bitrate_ceiling_mbps": { "description": "Maximum acceptable average bitrate, in megabits per second.", "example": 50, "type": "integer" }, "bitrate_floor_mbps": { "description": "Minimum acceptable average bitrate, in megabits per second.", "example": 4, "type": "integer" }, "bitrate_target_mbps": { "description": "Recommended average bitrate to encode at, in megabits per second.", "example": 12, "type": "integer" }, "camera_lens": { "description": "Which physical lens to record with.", "example": "ultra_wide", "type": "string" }, "codecs": { "items": { "description": "Accepted video codecs, in preference order.", "example": "h264", "type": "string" }, "type": "array" }, "embed_camera_metadata": { "description": "Whether the client must also write the camera make and model into the video container's metadata. When `false`, the capture manifest and export CSV are the metadata carrier.", "example": false, "type": "boolean" }, "fps": { "description": "Target capture frame rate.", "example": 30, "type": "integer" }, "frame_gap_tolerance_ms": { "description": "Longest stall between consecutive frames a clip may contain before the client rejects it, in milliseconds. Every frame is timestamped in the frame log, so a stall stays alignable downstream — this bounds how broken a capture may be, not how evenly it must be paced.", "example": 1000, "type": "integer" }, "height": { "description": "Required frame height in pixels — recorded footage must match exactly.", "example": 1080, "type": "integer" }, "min_fov_degrees": { "description": "Minimum acceptable horizontal field of view, in degrees.", "example": 130, "type": "integer" }, "orientation": { "description": "Device orientation to record in.", "example": "landscapeRight", "type": "string" }, "preferred_fov_degrees": { "description": "Preferred horizontal field of view, in degrees.", "example": 140, "type": "integer" }, "stabilization_mode": { "description": "How the client must configure video stabilization: `off` disables EIS so raw motion is preserved for pose extraction, `on` requires it, `any` leaves the device default.", "enum": [ "off", "on", "any" ], "example": "off", "type": "string" }, "stabilization_required": { "description": "Whether hardware/software stabilization must be enabled. True exactly when stabilization_mode is `on`.", "example": false, "type": "boolean" }, "width": { "description": "Required frame width in pixels — recorded footage must match exactly.", "example": 1920, "type": "integer" } }, "required": [ "codecs", "width", "height", "fps", "bitrate_floor_mbps", "bitrate_ceiling_mbps", "bitrate_target_mbps", "min_fov_degrees", "preferred_fov_degrees", "camera_lens", "orientation", "stabilization_required", "stabilization_mode", "embed_camera_metadata", "frame_gap_tolerance_ms" ], "type": "object" }, "CardBrands": { "description": "Possible card brands that a payment token can have", "enum": [ "mastercard", "visa", "amex", "discover", "unionpay", "jcb", "diners", "link", "troy", "visadankort", "visabancontact", "china_union_pay", "rupay", "jcbrupay", "elo", "maestro", "tarjeta_naranja", "cirrus", "nspk_mir", "verve", "ebt", "private_label", "local_brand", "uatp", "wexcard", "uzcard", "meeza", "hrg_store_card", "girocard", "fuel_card", "dankort", "carnet", "atm_card", "china_union_payuzcard", "codensa", "cabal", "hipercard", "jcblankapay", "cmi", "aura", "accel", "culiance", "nyce", "pulse", "star", "eftpos", "alelo", "edenred", "sodexo", "unknown" ], "type": "string" }, "CardFundingTypes": { "description": "The funding types of a card", "enum": [ "credit", "debit", "prepaid" ], "type": "string" }, "CardIssuingTransactionStatus": { "description": "The lifecycle status of a card transaction.", "enum": [ "pending", "completed", "reversed", "declined" ], "type": "string" }, "CardTransaction": { "properties": { "card_id": { "description": "The card this transaction was charged to, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "cardholder_id": { "description": "The user the card is assigned to, prefixed `user_`. Null when the card has no assigned cardholder.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "cashback_usd_amount": { "description": "Cashback earned on this transaction as a USD amount. Zero for declined or ineligible transactions, and null when cashback has not been computed yet.", "example": 0.25, "type": [ "number", "null" ] }, "created_at": { "description": "When the transaction was authorized, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "ISO 4217 currency code the merchant charged in.", "example": "EUR", "type": [ "string", "null" ] }, "declined_reason": { "description": "Why the transaction was declined. Null unless `status` is `declined`.", "example": "account_credit_limit_exceeded", "type": [ "string", "null" ] }, "id": { "description": "Card transaction ID, prefixed `citx_`.", "example": "citx_xxxxxxxxxxxxxx", "type": "string" }, "international": { "description": "True when the merchant is outside the card's home country.", "example": true, "type": "boolean" }, "local_amount": { "description": "Amount the merchant charged in their own currency. Pair with `currency`.", "example": 22.5, "type": [ "number", "null" ] }, "merchant_category": { "description": "Merchant category label, enriched where available and otherwise as the card network reported it.", "example": "Car Care Supplies", "type": [ "string", "null" ] }, "merchant_category_code": { "description": "Four-digit ISO 18245 merchant category code (MCC).", "example": "5533", "type": [ "string", "null" ] }, "merchant_icon_url": { "description": "URL of the enriched merchant logo. Null when no logo was matched.", "example": "https://shinetime.example/icons/lone-star-detail-supply.png", "type": [ "string", "null" ] }, "merchant_name": { "description": "Merchant name, enriched where available and otherwise as the card network reported it.", "example": "Lone Star Detail Supply", "type": [ "string", "null" ] }, "posted_at": { "description": "When the card network settled the transaction, as an ISO 8601 timestamp. Null until it settles.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Current status of the transaction.", "enum": [ "pending", "completed", "reversed", "declined" ], "example": "completed", "type": "string" }, "transaction_type": { "description": "The kind of card transaction. Always `spend` today.", "enum": [ "spend" ], "example": "spend", "type": "string" }, "usd_amount": { "description": "Amount charged in USD. Negative when the merchant refunded the card.", "example": 24.99, "type": [ "number", "null" ] } }, "required": [ "id", "card_id", "cardholder_id", "status", "transaction_type", "usd_amount", "local_amount", "currency", "international", "merchant_name", "merchant_icon_url", "merchant_category", "merchant_category_code", "declined_reason", "cashback_usd_amount", "created_at", "posted_at" ], "type": "object" }, "CardTransactionLegacy": { "description": "A card transaction record.", "properties": { "authorization_method": { "description": "How the card was presented or authenticated for the purchase.", "example": "ecommerce", "type": [ "string", "null" ] }, "card_id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "cashback_usd_amount": { "description": "The cashback reward amount earned on this transaction, in USD.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "The datetime the card transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The ISO 4217 currency code for the transaction amount.", "example": "USD", "type": [ "string", "null" ] }, "declined_reason": { "description": "The issuer-provided reason the transaction was declined.", "example": "insufficient_funds", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the card transaction.", "type": "string" }, "international": { "description": "Whether the transaction was made with a merchant outside the card's home country.", "type": "boolean" }, "local_amount": { "description": "The transaction amount in the merchant's local currency before conversion.", "example": 6.9, "type": [ "number", "null" ] }, "memo": { "description": "A user-provided note attached to the transaction.", "example": "Team dinner", "type": [ "string", "null" ] }, "merchant_category": { "description": "The enriched or raw category label for the merchant.", "example": "Software", "type": [ "string", "null" ] }, "merchant_category_code": { "description": "The four-digit ISO 18245 merchant category code (MCC).", "example": "5734", "type": [ "string", "null" ] }, "merchant_icon_url": { "description": "A URL to the enriched merchant logo image.", "example": "https://logo.clearbit.com/example.com", "type": [ "string", "null" ] }, "merchant_name": { "description": "The enriched or raw name of the merchant where the purchase was made.", "example": "Acme Corporation", "type": [ "string", "null" ] }, "posted_at": { "description": "When the transaction was settled by the card network.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/CardIssuingTransactionStatus", "description": "The current lifecycle status of the transaction." }, "transaction_type": { "description": "The type of transaction.", "example": "spend", "type": "string" }, "usd_amount": { "description": "The transaction amount in USD.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "id", "usd_amount", "authorization_method", "created_at", "card_id", "cashback_usd_amount", "currency", "declined_reason", "international", "local_amount", "memo", "merchant_category", "merchant_category_code", "merchant_icon_url", "merchant_name", "posted_at", "status", "transaction_type" ], "type": "object" }, "CardTransactionListItem": { "description": "A card transaction record.", "properties": { "authorization_method": { "description": "How the card was presented or authenticated for the purchase.", "example": "ecommerce", "type": [ "string", "null" ] }, "card_id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "cashback_usd_amount": { "description": "The cashback reward amount earned on this transaction, in USD.", "example": 6.9, "type": [ "number", "null" ] }, "created_at": { "description": "The datetime the card transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The ISO 4217 currency code for the transaction amount.", "example": "USD", "type": [ "string", "null" ] }, "declined_reason": { "description": "The issuer-provided reason the transaction was declined.", "example": "insufficient_funds", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the card transaction.", "type": "string" }, "international": { "description": "Whether the transaction was made with a merchant outside the card's home country.", "type": "boolean" }, "local_amount": { "description": "The transaction amount in the merchant's local currency before conversion.", "example": 6.9, "type": [ "number", "null" ] }, "memo": { "description": "A user-provided note attached to the transaction.", "example": "Team dinner", "type": [ "string", "null" ] }, "merchant_category": { "description": "The enriched or raw category label for the merchant.", "example": "Software", "type": [ "string", "null" ] }, "merchant_category_code": { "description": "The four-digit ISO 18245 merchant category code (MCC).", "example": "5734", "type": [ "string", "null" ] }, "merchant_icon_url": { "description": "A URL to the enriched merchant logo image.", "example": "https://logo.clearbit.com/example.com", "type": [ "string", "null" ] }, "merchant_name": { "description": "The enriched or raw name of the merchant where the purchase was made.", "example": "Acme Corporation", "type": [ "string", "null" ] }, "posted_at": { "description": "When the transaction was settled by the card network.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/CardIssuingTransactionStatus", "description": "The current lifecycle status of the transaction." }, "transaction_type": { "description": "The type of transaction.", "example": "spend", "type": "string" }, "usd_amount": { "description": "The transaction amount in USD.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "id", "usd_amount", "authorization_method", "created_at", "card_id", "cashback_usd_amount", "currency", "declined_reason", "international", "local_amount", "memo", "merchant_category", "merchant_category_code", "merchant_icon_url", "merchant_name", "posted_at", "status", "transaction_type" ], "type": "object" }, "CashbackPayout": { "properties": { "account_id": { "description": "Connected account filter from the request, prefixed `biz_`. Omitted when not supplied.", "type": [ "string", "null" ] }, "cashback_rule_id": { "description": "Cashback rule filter from the request, prefixed `cicbr_`. Omitted when not supplied.", "type": [ "string", "null" ] }, "status": { "description": "Request status. `processing` means background processing was queued, not that payment completed. `failed`, returned with HTTP `200`, means the queue rejected the request. Subsequent transaction failures retry automatically.", "enum": [ "processing", "failed" ], "example": "failed", "type": "string" }, "transaction_id": { "description": "Card transaction filter from the request, prefixed `citx_`. Omitted when not supplied.", "example": "citx_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "status" ], "type": "object" }, "CashbackRule": { "properties": { "created_at": { "description": "When the rule was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "description": { "description": "Optional description of the cashback rule.", "example": "Cloud cashback", "type": [ "string", "null" ] }, "discarded_at": { "description": "When the rule was discarded, as an ISO 8601 timestamp. Null means it has not been discarded.", "example": null, "type": [ "string", "null" ] }, "expires_at": { "description": "Exclusive end of the eligibility window, as an ISO 8601 timestamp. Null means no expiration.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "funding_account_id": { "description": "Platform account designated to fund cashback, prefixed `biz_`. Derived from the authenticated credential.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "Cashback rule ID, prefixed `cicbr_`.", "example": "cicbr_xxxxxxxxxxxxxx", "type": "string" }, "merchant_category_code": { "description": "Four-digit merchant category code. Null matches any MCC. When both merchant filters are null, scoped_account_id is required.", "example": "7372", "type": [ "string", "null" ] }, "merchant_name": { "description": "Raw merchant name reported by the card provider. Null matches any merchant name. When set, matches together with any MCC filter; not a substring or enriched display-name match.", "example": "ACME CLOUD", "type": [ "string", "null" ] }, "rate_bps": { "description": "Cashback rate in basis points. 100 means 1%, and 10000 means 100%.", "example": 500, "type": "integer" }, "scoped_account_id": { "description": "Connected account ID, prefixed `biz_`. Null designates all direct connected accounts of the funding platform.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "starts_at": { "description": "Inclusive start of the rule's eligibility window, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "updated_at": { "description": "When the rule was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "merchant_name", "merchant_category_code", "rate_bps", "description", "funding_account_id", "scoped_account_id", "starts_at", "expires_at", "discarded_at", "created_at", "updated_at" ], "type": "object" }, "ChatChannel": { "description": "A real-time chat feed attached to an experience, with configurable moderation and posting permissions.", "properties": { "ban_media": { "description": "Whether media uploads such as images and videos are blocked in this chat.", "type": "boolean" }, "ban_urls": { "description": "Whether URL links are blocked from being posted in this chat.", "type": "boolean" }, "banned_words": { "description": "A list of words that are automatically filtered from messages in this chat. Empty unless the caller has permission to moderate this chat.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "experience": { "description": "The experience this chat feed is attached to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "user_posts_cooldown_seconds": { "description": "The minimum number of seconds a user must wait between consecutive messages. Null if no cooldown is enforced.", "example": 42, "type": [ "integer", "null" ] }, "who_can_post": { "$ref": "#/components/schemas/WhoCanPostTypes", "description": "The permission level controlling which users can send messages in this chat." }, "who_can_react": { "$ref": "#/components/schemas/WhoCanReactTypes", "description": "The permission level controlling which users can add reactions in this chat." } }, "required": [ "id", "experience", "ban_media", "ban_urls", "who_can_post", "who_can_react", "user_posts_cooldown_seconds", "banned_words" ], "type": "object" }, "ChatChannelListItem": { "description": "A real-time chat feed attached to an experience, with configurable moderation and posting permissions.", "properties": { "ban_media": { "description": "Whether media uploads such as images and videos are blocked in this chat.", "type": "boolean" }, "ban_urls": { "description": "Whether URL links are blocked from being posted in this chat.", "type": "boolean" }, "banned_words": { "description": "A list of words that are automatically filtered from messages in this chat. Empty unless the caller has permission to moderate this chat.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": "array" }, "experience": { "description": "The experience this chat feed is attached to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "user_posts_cooldown_seconds": { "description": "The minimum number of seconds a user must wait between consecutive messages. Null if no cooldown is enforced.", "example": 42, "type": [ "integer", "null" ] }, "who_can_post": { "$ref": "#/components/schemas/WhoCanPostTypes", "description": "The permission level controlling which users can send messages in this chat." }, "who_can_react": { "$ref": "#/components/schemas/WhoCanReactTypes", "description": "The permission level controlling which users can add reactions in this chat." } }, "required": [ "id", "experience", "ban_media", "ban_urls", "who_can_post", "who_can_react", "user_posts_cooldown_seconds", "banned_words" ], "type": "object" }, "CheckoutConfiguration": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "type": "string" }, "affiliate_code": { "description": "Affiliate code applied at checkout, or `null` when none is set.", "type": [ "string", "null" ] }, "created_at": { "description": "When the checkout configuration was created, as an ISO 8601 timestamp.", "type": "string" }, "currency": { "description": "Currency used for setup-mode payment method availability; defaults to `usd` when omitted.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau", null ], "example": "usd", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout mounted from this configuration, resolved through every layer (its own overrides, the variant's, and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays this configuration's own editable override.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutSessionPaymentMethodConfiguration" }, { "type": "null" } ] }, "id": { "type": "string" }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships. `null` without the `checkout_configuration:basic:read` scope.", "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later.", "enum": [ "payment", "setup" ], "example": "payment", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the variant or platform defaults.", "type": [ "object", "null" ] }, "purchase_url": { "description": "Checkout URL you can send to customers.", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout, or `null` when no redirect is configured.", "type": [ "string", "null" ] }, "three_ds_level": { "description": "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. Applies in setup mode; `null` uses frictionless 3DS. Payment mode uses the variant policy.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "updated_at": { "description": "When the checkout configuration was last updated, as an ISO 8601 timestamp.", "type": "string" }, "variant": { "description": "Variant used for payment checkout. `null` in setup mode.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutConfigurationVariant" }, { "type": "null" } ] } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode", "currency", "variant", "affiliate_code", "metadata", "redirect_url", "purchase_url", "three_ds_level", "payment_method_configuration", "effective_payment_method_configuration" ], "type": "object" }, "CheckoutConfigurationListItem": { "description": "A checkout configuration is a reusable configuration for a checkout, including the plan, affiliate, and custom metadata. Payments and memberships created from a checkout session inherit its metadata.", "properties": { "account_id": { "description": "The ID of the account to use for the checkout configuration", "type": "string" }, "affiliate_code": { "description": "The affiliate code to use for the checkout configuration", "type": [ "string", "null" ] }, "company_id": { "description": "The ID of the account to use for the checkout configuration", "type": "string" }, "currency": { "description": "The currency to use for the configuration when in 'setup' mode. This is used to target which currency specific payment methods are available. If not provided, it will default to 'usd' when in setup mode.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the checkout session.", "example": "ch_xxxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "The metadata to use for the checkout configuration", "type": [ "object", "null" ] }, "mode": { "$ref": "#/components/schemas/CheckoutModes", "description": "The mode of the checkout session." }, "payment_method_configuration": { "description": "The explicit payment method configuration for the session, if any. This currently only works in 'setup' mode. Use the plan's payment_method_configuration for payment method.", "properties": { "disabled": { "description": "An array of payment method identifiers that are explicitly disabled. Only applies if the include_platform_defaults is true.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.", "type": "boolean" } }, "required": [ "enabled", "disabled", "include_platform_defaults" ], "type": [ "object", "null" ] }, "plan": { "description": "The plan to use for the checkout configuration", "properties": { "adaptive_pricing_enabled": { "description": "Whether the creator has turned on adaptive pricing for this plan. Raw setting — does not check processor compatibility or feature flags.", "type": "boolean" }, "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 42, "type": [ "integer", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency." }, "expiration_days": { "description": "Access duration in days for expiration-based plans, such as 365 for a one-year pass.", "example": 42, "type": [ "integer", "null" ] }, "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "The initial purchase price in the plan's base_currency (e.g., 49.99 for $49.99). For one-time plans, this is the full price. For renewal plans, this is charged on top of the first renewal_price.", "example": 6.9, "type": "number" }, "plan_type": { "$ref": "#/components/schemas/PlanTypes", "description": "The billing model for this plan: 'renewal' for recurring subscriptions or 'one_time' for single payments." }, "release_method": { "$ref": "#/components/schemas/ReleaseMethod", "description": "Sales method for this plan: `buy_now` for immediate purchase or `waitlist` for waitlist-based access." }, "renewal_price": { "description": "The recurring price charged every billing_period in the plan's base_currency (e.g., 9.99 for $9.99/period). Zero for one-time plans.", "example": 6.9, "type": "number" }, "three_ds_level": { "description": "The 3D Secure behavior for this plan. Null means the plan inherits the account default.", "oneOf": [ { "$ref": "#/components/schemas/PlanThreeDsLevels" }, { "type": "null" } ] }, "trial_period_days": { "description": "Free trial days before first renewal charge. `null` if no trial is configured or the user has already used a trial for this plan.", "example": 42, "type": [ "integer", "null" ] }, "visibility": { "$ref": "#/components/schemas/Visibility", "description": "Controls whether the plan is visible to customers. When set to 'hidden', the plan is only accessible via direct link." } }, "required": [ "id", "visibility", "plan_type", "release_method", "currency", "billing_period", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "adaptive_pricing_enabled" ], "type": [ "object", "null" ] }, "purchase_url": { "description": "A URL you can send to customers to complete a checkout. It looks like `/checkout/ch_xxxx/`", "type": "string" }, "redirect_url": { "description": "The URL to redirect the user to after the checkout configuration is created", "type": [ "string", "null" ] } }, "required": [ "id", "company_id", "account_id", "mode", "currency", "plan", "affiliate_code", "metadata", "redirect_url", "purchase_url", "payment_method_configuration" ], "type": "object" }, "CheckoutConfigurationVariant": { "properties": { "adaptive_pricing_enabled": { "description": "Whether this variant accepts local currency payments via adaptive pricing.", "type": "boolean" }, "billing_period": { "description": "Recurring billing interval in days.", "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "currency": { "description": "Three-letter ISO currency code for the variant's prices.", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based variants.", "type": [ "integer", "null" ] }, "id": { "description": "Variant ID, prefixed `plan_`.", "type": "string" }, "initial_price": { "description": "Initial purchase price in the variant currency.", "type": "number" }, "release_method": { "description": "Sales method for the variant.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "type": "number" }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "visibility", "billing_type", "release_method", "currency", "billing_period", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "adaptive_pricing_enabled" ], "type": "object" }, "CheckoutFonts": { "description": "The different font families available for checkout pages.", "enum": [ "system", "roboto", "open_sans" ], "type": "string" }, "CheckoutModes": { "description": "The different modes a checkout can be set to.", "enum": [ "payment", "setup" ], "type": "string" }, "CheckoutSessionPaymentMethodConfiguration": { "properties": { "disabled": { "items": { "description": "Payment methods this checkout withholds, even when the defaults would offer them.", "example": "card", "type": "string" }, "type": "array" }, "enabled": { "items": { "description": "Payment methods this checkout offers on top of whatever the defaults provide.", "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether Whop's default set is the starting point. When `false`, only `enabled` is offered.", "example": true, "type": "boolean" } }, "required": [ "enabled", "disabled", "include_platform_defaults" ], "type": "object" }, "CheckoutShapes": { "description": "The different border-radius styles available for checkout pages.", "enum": [ "rounded", "pill", "rectangular" ], "type": "string" }, "CompanyTokenTransaction": { "description": "A token transaction records a credit or debit to a member's token balance within a company, including transfers between members.", "properties": { "amount": { "description": "The token amount for this transaction. Always a positive value regardless of transaction type.", "example": 6.9, "type": "number" }, "company": { "description": "The company whose token balance this transaction affects.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the company token transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "Free-text description explaining the reason for this token transaction. Null if no description was provided.", "example": "Reward for completing onboarding", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company token transaction.", "type": "string" }, "idempotency_key": { "description": "A unique key used to prevent duplicate transactions when retrying API requests. Null if no idempotency key was provided.", "example": "txn_reward_usr_123_2024", "type": [ "string", "null" ] }, "linked_transaction_id": { "description": "The ID of the corresponding transaction on the other side of a transfer. Null if this is not a transfer transaction.", "type": [ "string", "null" ] }, "member": { "description": "The member whose token balance was affected by this transaction.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "transaction_type": { "$ref": "#/components/schemas/CompanyTokenTransactionTypes", "description": "The direction of this token transaction (add, subtract, or transfer)." }, "user": { "description": "The user whose token balance was affected by this transaction.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "transaction_type", "amount", "description", "created_at", "linked_transaction_id", "idempotency_key", "user", "member", "company" ], "type": "object" }, "CompanyTokenTransactionListItem": { "description": "A token transaction records a credit or debit to a member's token balance within a company, including transfers between members.", "properties": { "amount": { "description": "The token amount for this transaction. Always a positive value regardless of transaction type.", "example": 6.9, "type": "number" }, "company": { "description": "The company whose token balance this transaction affects.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the company token transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "Free-text description explaining the reason for this token transaction. Null if no description was provided.", "example": "Reward for completing onboarding", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company token transaction.", "type": "string" }, "idempotency_key": { "description": "A unique key used to prevent duplicate transactions when retrying API requests. Null if no idempotency key was provided.", "example": "txn_reward_usr_123_2024", "type": [ "string", "null" ] }, "linked_transaction_id": { "description": "The ID of the corresponding transaction on the other side of a transfer. Null if this is not a transfer transaction.", "type": [ "string", "null" ] }, "member": { "description": "The member whose token balance was affected by this transaction.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "transaction_type": { "$ref": "#/components/schemas/CompanyTokenTransactionTypes", "description": "The direction of this token transaction (add, subtract, or transfer)." }, "user": { "description": "The user whose token balance was affected by this transaction.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "transaction_type", "amount", "description", "created_at", "linked_transaction_id", "idempotency_key", "user", "member", "company" ], "type": "object" }, "CompanyTokenTransactionTypes": { "description": "The type of token transaction", "enum": [ "add", "subtract", "transfer" ], "type": "string" }, "ConfirmationToken": { "properties": { "billing_address": { "description": "The collected billing address, including the name on the address. Null when not collected or without bearer authentication with payment:basic:read on the token’s account.", "oneOf": [ { "$ref": "#/components/schemas/PaymentAddress" }, { "type": "null" } ] }, "billing_details": { "description": "Billing preview supplied at collection: email, name, country and postal code.", "oneOf": [ { "$ref": "#/components/schemas/PaymentBillingDetailsPreview" }, { "type": "null" } ] }, "created_at": { "description": "When the token was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "expires_at": { "description": "When the token expires, as an ISO 8601 timestamp. Tokens are single-use and short-lived.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "example": "ctok_xxxxxxxxxxxxxx", "type": "string" }, "object": { "description": "Always `confirmation_token`.", "example": "confirmation_token", "type": "string" }, "payment_method_preview": { "$ref": "#/components/schemas/PaymentMethodDisplay", "description": "Display-only preview of the collected method — never the underlying token." }, "setup_future_usage": { "description": "Save-consent state the element displayed at collection: `off_session`, `on_session`, or `null`. Confirm may vault only if attested here.", "example": "off_session", "type": [ "string", "null" ] }, "status": { "description": "`pending` until it is used, then `consumed`; `expired` once its short lifetime elapses. Only a `pending` token can be charged.", "enum": [ "pending", "consumed", "expired" ], "example": "pending", "type": "string" } }, "required": [ "id", "object", "status", "payment_method_preview", "setup_future_usage", "billing_details", "billing_address", "created_at", "expires_at" ], "type": "object" }, "ConversionEvent": { "anyOf": [ { "enum": [ "purchase", "add_to_cart", "initiated_checkout", "add_payment_info", "complete_registration", "lead", "content_view", "search", "contact", "customize_product", "donate", "find_location", "schedule", "start_trial", "submit_application", "subscribe" ], "example": "purchase", "type": "string" }, { "type": "string" }, { "type": "null" } ], "description": "The pixel event optimized for. A standard event, or any custom pixel event name." }, "Course": { "description": "A structured learning module containing chapters and lessons, belonging to an experience.", "properties": { "certificate_after_completion_enabled": { "description": "Whether students receive a PDF certificate after completing all lessons in this course. Null if the setting has not been configured.", "type": [ "boolean", "null" ] }, "chapters": { "description": "An ordered list of all chapters in this course, sorted by their display position.", "items": { "description": "A grouping of related lessons within a course, used to organize content into sections.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "lessons": { "description": "An ordered list of lessons in this chapter, sorted by display position. Hidden lessons are excluded for non-admin users.", "items": { "description": "An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "lesson_type": { "$ref": "#/components/schemas/LessonTypes", "description": "The content format of this lesson. One of: text, video, pdf, multi, quiz, knowledge_check." }, "order": { "description": "The sort position of this lesson within its parent chapter, starting from zero.", "example": 42, "type": "integer" }, "thumbnail": { "description": "The thumbnail image displayed on lesson cards and previews. Null if no thumbnail has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" }, "video_asset": { "description": "The Mux video asset for video-type lessons, used for streaming playback. Null if this lesson has no hosted video.", "properties": { "duration_seconds": { "description": "The duration of the video in seconds", "example": 42, "type": [ "integer", "null" ] }, "signed_playback_id": { "description": "The signed playback ID of the Mux asset", "type": [ "string", "null" ] }, "signed_thumbnail_playback_token": { "description": "The signed thumbnail playback token of the Mux asset", "type": [ "string", "null" ] } }, "required": [ "signed_playback_id", "signed_thumbnail_playback_token", "duration_seconds" ], "type": [ "object", "null" ] } }, "required": [ "id", "lesson_type", "title", "order", "video_asset", "thumbnail" ], "type": "object" }, "type": "array" }, "order": { "description": "The sort position of this chapter within its parent course, starting from zero.", "example": 42, "type": "integer" }, "title": { "description": "The display name of the chapter shown to students. Maximum 150 characters.", "example": "Getting Started", "type": "string" } }, "required": [ "id", "title", "order", "lessons" ], "type": "object" }, "type": "array" }, "chapters_count": { "description": "The total number of chapters in this course, including chapters whose lessons are all hidden from the current user.", "example": 42, "type": "integer" }, "completed_lessons_count": { "description": "The number of lessons in this course that the current user has marked as completed. Zero when the request is not made on behalf of a user.", "example": 42, "type": "integer" }, "cover_image": { "description": "The URL of the course cover image shown on preview cards. Null if no cover image has been uploaded.", "example": "https://assets.whop.com/images/course-cover.jpg", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the course was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "A brief summary of the course content and objectives. Null if no description has been set.", "example": "Learn advanced trading strategies from industry experts.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the course.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "language": { "$ref": "#/components/schemas/Languages", "description": "The spoken language of the video content, used to generate accurate closed captions. One of: en, es, it, pt, de, fr, pl, ru, nl, ca, tr, sv, uk, no, fi, sk, el, cs, hr, da, ro, bg." }, "latest_lesson_created_at": { "description": "The creation timestamp of the most recently added lesson visible to the current user. Null if the course has no lessons.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "lesson_unlock_days": { "description": "The distinct drip schedules, in days after the course start, of lessons visible to the current user. Combine with startedAt to work out which have unlocked. Empty when the user has not started the course or no lesson is on a schedule.", "items": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": "integer" }, "type": "array" }, "order": { "description": "The sort position of this course within its parent experience, as a decimal for flexible ordering.", "example": "123.45", "type": "string" }, "require_completing_lessons_in_order": { "description": "Whether students must complete each lesson sequentially before advancing to the next one.", "type": "boolean" }, "resume_lesson": { "description": "The lesson the current user should continue from: their first incomplete lesson, or the first lesson when they have finished the course, have not started it, or can edit it. Null if the course has no lessons.", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "started_at": { "description": "The earliest time the current user is known to have started this course. Null if they have not started it. Drip unlock schedules are measured from this point.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "tagline": { "description": "A short marketing tagline displayed beneath the course title. Null if no tagline has been set.", "example": "Master the fundamentals in 30 days", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image displayed on course cards and previews. Null if no thumbnail has been uploaded.", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "optimized_url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] }, "source_url": { "description": "The original source URL of the attachment, such as a direct link to S3. This should never be displayed on the client and should always be passed through an Imgproxy transformer.", "example": "https://media.whop.com/abc123/original.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "optimized_url", "source_url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the course shown to students. Null if no title has been set.", "example": "Introduction to Technical Analysis", "type": [ "string", "null" ] }, "total_duration_seconds": { "description": "The combined duration in seconds of every hosted video across the lessons visible to the current user.", "example": 42, "type": "integer" }, "total_lessons_count": { "description": "The number of lessons in this course visible to the current user.", "example": 42, "type": "integer" }, "updated_at": { "description": "The datetime the course was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "visibility": { "$ref": "#/components/schemas/CourseVisibilities", "description": "The visibility setting that controls whether this course appears to students. One of: visible, hidden." } }, "required": [ "id", "title", "tagline", "cover_image", "thumbnail", "description", "language", "certificate_after_completion_enabled", "require_completing_lessons_in_order", "order", "visibility", "created_at", "updated_at", "chapters_count", "total_lessons_count", "completed_lessons_count", "total_duration_seconds", "latest_lesson_created_at", "started_at", "lesson_unlock_days", "resume_lesson", "chapters" ], "type": "object" }, "CourseChapter": { "description": "A grouping of related lessons within a course, used to organize content into sections.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "lessons": { "description": "An ordered list of lessons in this chapter, sorted by display position. Hidden lessons are excluded for non-admin users.", "items": { "description": "An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "order": { "description": "The sort position of this lesson within its parent chapter, starting from zero.", "example": 42, "type": "integer" }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" } }, "required": [ "id", "title", "order" ], "type": "object" }, "type": "array" }, "order": { "description": "The sort position of this chapter within its parent course, starting from zero.", "example": 42, "type": "integer" }, "title": { "description": "The display name of the chapter shown to students. Maximum 150 characters.", "example": "Getting Started", "type": "string" } }, "required": [ "id", "title", "order", "lessons" ], "type": "object" }, "CourseChapterListItem": { "description": "A grouping of related lessons within a course, used to organize content into sections.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "order": { "description": "The sort position of this chapter within its parent course, starting from zero.", "example": 42, "type": "integer" }, "title": { "description": "The display name of the chapter shown to students. Maximum 150 characters.", "example": "Getting Started", "type": "string" } }, "required": [ "id", "title", "order" ], "type": "object" }, "CourseLesson": { "description": "An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.", "properties": { "assessment_questions": { "description": "The list of questions for quiz or knowledge check lessons. Empty for non-assessment lesson types.", "items": { "description": "An assessment question in a course quiz or knowledge check", "properties": { "correct_answer": { "description": "The correct answer for the question. Used for short answer questions. Only visible to admins (users with courses:update permission)", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the assessment question was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the assessment question.", "example": "crsaq_xxxxxxxxxxxx", "type": "string" }, "image": { "description": "Optional image attachment for the question", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "options": { "description": "The answer options for multiple choice/select questions", "items": { "description": "An answer option for a multiple choice or multiple select assessment question", "properties": { "id": { "description": "The unique identifier for the assessment question option.", "example": "crsaqo_xxxxxxxxxxx", "type": "string" }, "is_correct": { "description": "Whether this option is a correct answer. Only visible to admins (users with courses:update permission)", "type": [ "boolean", "null" ] }, "option_text": { "description": "The text of the answer option", "type": "string" }, "order": { "description": "The order of this option within the question", "example": 42, "type": "integer" } }, "required": [ "id", "option_text", "is_correct", "order" ], "type": "object" }, "type": "array" }, "order": { "description": "The order of the question within its lesson", "example": 42, "type": "integer" }, "question_text": { "description": "The text of the question", "type": "string" }, "question_type": { "$ref": "#/components/schemas/CoursesAssessmentQuestionTypes", "description": "The type of the question" } }, "required": [ "id", "question_text", "question_type", "correct_answer", "order", "created_at", "image", "options" ], "type": "object" }, "type": "array" }, "attachments": { "description": "All supplementary files attached to this lesson returned as a flat array rather than a paginated connection.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "type": "array" }, "content": { "description": "The Markdown content body of the lesson. Null if the lesson has no text content.", "example": "In this lesson, we will cover the basics of technical analysis...", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the lesson was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "days_from_course_start_until_unlock": { "description": "The number of days after a student starts the course before this lesson becomes accessible. Null if the lesson is available immediately.", "example": 42, "type": [ "integer", "null" ] }, "embed_id": { "description": "The external video identifier for embedded video lessons, such as a YouTube video ID or Loom share ID. Null if the lesson has no embed.", "example": "dQw4w9WgXcQ", "type": [ "string", "null" ] }, "embed_type": { "description": "The platform type for the embedded video. One of: youtube, loom. Null if the lesson has no embed.", "oneOf": [ { "$ref": "#/components/schemas/EmbedTypes" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "lesson_type": { "$ref": "#/components/schemas/LessonTypes", "description": "The content format of this lesson. One of: text, video, pdf, multi, quiz, knowledge_check." }, "main_pdf": { "description": "The primary PDF document for PDF-type lessons. Null if this lesson is not a PDF lesson or no PDF has been uploaded.", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "order": { "description": "The sort position of this lesson within its parent chapter, starting from zero.", "example": 42, "type": "integer" }, "thumbnail": { "description": "The thumbnail image displayed on lesson cards and previews. Null if no thumbnail has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" }, "video_asset": { "description": "The Mux video asset for video-type lessons, used for streaming playback. Null if this lesson has no hosted video.", "properties": { "asset_id": { "description": "The Mux-provided ID of the asset", "type": [ "string", "null" ] }, "audio_only": { "description": "Whether this asset contains only audio", "type": "boolean" }, "created_at": { "description": "The datetime the mux asset was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "duration_seconds": { "description": "The duration of the video in seconds", "example": 42, "type": [ "integer", "null" ] }, "finished_uploading_at": { "description": "The time at which the video finished uploading", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the mux asset.", "example": "mux_xxxxxxxxxxxxxx", "type": "string" }, "playback_id": { "description": "The public playback ID of the Mux asset", "type": [ "string", "null" ] }, "signed_playback_id": { "description": "The signed playback ID of the Mux asset", "type": [ "string", "null" ] }, "signed_storyboard_playback_token": { "description": "The signed storyboard playback token of the Mux asset", "type": [ "string", "null" ] }, "signed_thumbnail_playback_token": { "description": "The signed thumbnail playback token of the Mux asset", "type": [ "string", "null" ] }, "signed_video_playback_token": { "description": "The signed video playback token of the Mux asset", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MuxAssetStatuses", "description": "The status of the Mux asset" }, "updated_at": { "description": "The datetime the mux asset was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "asset_id", "playback_id", "signed_playback_id", "status", "audio_only", "duration_seconds", "signed_video_playback_token", "signed_thumbnail_playback_token", "signed_storyboard_playback_token", "created_at", "updated_at", "finished_uploading_at" ], "type": [ "object", "null" ] }, "visibility": { "$ref": "#/components/schemas/LessonVisibilities", "description": "The visibility setting that controls whether this lesson appears to students. One of: visible, hidden." } }, "required": [ "id", "title", "order", "lesson_type", "visibility", "content", "days_from_course_start_until_unlock", "embed_type", "embed_id", "created_at", "thumbnail", "video_asset", "main_pdf", "assessment_questions", "attachments" ], "type": "object" }, "CourseLessonInteraction": { "description": "A record of a user's progress on a specific lesson, tracking whether they have completed it.", "properties": { "completed": { "description": "Whether the user has finished this lesson.", "type": "boolean" }, "course": { "description": "The course that contains the tracked lesson.", "properties": { "experience": { "description": "The parent experience that this course belongs to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "The unique identifier for the course.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the course shown to students. Null if no title has been set.", "example": "Introduction to Technical Analysis", "type": [ "string", "null" ] } }, "required": [ "id", "title", "experience" ], "type": "object" }, "created_at": { "description": "The datetime the lesson interaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the lesson interaction.", "example": "crsli_xxxxxxxxxxxx", "type": "string" }, "lesson": { "description": "The lesson that this progress record belongs to.", "properties": { "chapter": { "description": "The parent chapter that contains this lesson.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" } }, "required": [ "id", "title", "chapter" ], "type": "object" }, "user": { "description": "The user whose progress is being tracked.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "completed", "created_at", "lesson", "user", "course" ], "type": "object" }, "CourseLessonInteractionListItem": { "description": "A record of a user's progress on a specific lesson, tracking whether they have completed it.", "properties": { "completed": { "description": "Whether the user has finished this lesson.", "type": "boolean" }, "created_at": { "description": "The datetime the lesson interaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the lesson interaction.", "example": "crsli_xxxxxxxxxxxx", "type": "string" }, "lesson": { "description": "The lesson that this progress record belongs to.", "properties": { "chapter": { "description": "The parent chapter that contains this lesson.", "properties": { "id": { "description": "The unique identifier for the chapter.", "example": "chap_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" } }, "required": [ "id", "title", "chapter" ], "type": "object" }, "user": { "description": "The user whose progress is being tracked.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "completed", "created_at", "lesson", "user" ], "type": "object" }, "CourseLessonListItem": { "description": "An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.", "properties": { "content": { "description": "The Markdown content body of the lesson. Null if the lesson has no text content.", "example": "In this lesson, we will cover the basics of technical analysis...", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the lesson was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "days_from_course_start_until_unlock": { "description": "The number of days after a student starts the course before this lesson becomes accessible. Null if the lesson is available immediately.", "example": 42, "type": [ "integer", "null" ] }, "embed_id": { "description": "The external video identifier for embedded video lessons, such as a YouTube video ID or Loom share ID. Null if the lesson has no embed.", "example": "dQw4w9WgXcQ", "type": [ "string", "null" ] }, "embed_type": { "description": "The platform type for the embedded video. One of: youtube, loom. Null if the lesson has no embed.", "oneOf": [ { "$ref": "#/components/schemas/EmbedTypes" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "lesson_type": { "$ref": "#/components/schemas/LessonTypes", "description": "The content format of this lesson. One of: text, video, pdf, multi, quiz, knowledge_check." }, "order": { "description": "The sort position of this lesson within its parent chapter, starting from zero.", "example": 42, "type": "integer" }, "thumbnail": { "description": "The thumbnail image displayed on lesson cards and previews. Null if no thumbnail has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" }, "visibility": { "$ref": "#/components/schemas/LessonVisibilities", "description": "The visibility setting that controls whether this lesson appears to students. One of: visible, hidden." } }, "required": [ "id", "title", "order", "lesson_type", "visibility", "content", "days_from_course_start_until_unlock", "embed_type", "embed_id", "created_at", "thumbnail" ], "type": "object" }, "CourseListItem": { "description": "A structured learning module containing chapters and lessons, belonging to an experience.", "properties": { "certificate_after_completion_enabled": { "description": "Whether students receive a PDF certificate after completing all lessons in this course. Null if the setting has not been configured.", "type": [ "boolean", "null" ] }, "chapters_count": { "description": "The total number of chapters in this course, including chapters whose lessons are all hidden from the current user.", "example": 42, "type": "integer" }, "completed_lessons_count": { "description": "The number of lessons in this course that the current user has marked as completed. Zero when the request is not made on behalf of a user.", "example": 42, "type": "integer" }, "cover_image": { "description": "The URL of the course cover image shown on preview cards. Null if no cover image has been uploaded.", "example": "https://assets.whop.com/images/course-cover.jpg", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the course was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "description": { "description": "A brief summary of the course content and objectives. Null if no description has been set.", "example": "Learn advanced trading strategies from industry experts.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the course.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "language": { "$ref": "#/components/schemas/Languages", "description": "The spoken language of the video content, used to generate accurate closed captions. One of: en, es, it, pt, de, fr, pl, ru, nl, ca, tr, sv, uk, no, fi, sk, el, cs, hr, da, ro, bg." }, "latest_lesson_created_at": { "description": "The creation timestamp of the most recently added lesson visible to the current user. Null if the course has no lessons.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "lesson_unlock_days": { "description": "The distinct drip schedules, in days after the course start, of lessons visible to the current user. Combine with startedAt to work out which have unlocked. Empty when the user has not started the course or no lesson is on a schedule.", "items": { "description": "Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.", "example": 42, "type": "integer" }, "type": "array" }, "order": { "description": "The sort position of this course within its parent experience, as a decimal for flexible ordering.", "example": "123.45", "type": "string" }, "require_completing_lessons_in_order": { "description": "Whether students must complete each lesson sequentially before advancing to the next one.", "type": "boolean" }, "resume_lesson": { "description": "The lesson the current user should continue from: their first incomplete lesson, or the first lesson when they have finished the course, have not started it, or can edit it. Null if the course has no lessons.", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "started_at": { "description": "The earliest time the current user is known to have started this course. Null if they have not started it. Drip unlock schedules are measured from this point.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "tagline": { "description": "A short marketing tagline displayed beneath the course title. Null if no tagline has been set.", "example": "Master the fundamentals in 30 days", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image displayed on course cards and previews. Null if no thumbnail has been uploaded.", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "optimized_url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] }, "source_url": { "description": "The original source URL of the attachment, such as a direct link to S3. This should never be displayed on the client and should always be passed through an Imgproxy transformer.", "example": "https://media.whop.com/abc123/original.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "optimized_url", "source_url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the course shown to students. Null if no title has been set.", "example": "Introduction to Technical Analysis", "type": [ "string", "null" ] }, "total_duration_seconds": { "description": "The combined duration in seconds of every hosted video across the lessons visible to the current user.", "example": 42, "type": "integer" }, "total_lessons_count": { "description": "The number of lessons in this course visible to the current user.", "example": 42, "type": "integer" }, "updated_at": { "description": "The datetime the course was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "visibility": { "$ref": "#/components/schemas/CourseVisibilities", "description": "The visibility setting that controls whether this course appears to students. One of: visible, hidden." } }, "required": [ "id", "title", "tagline", "cover_image", "thumbnail", "description", "language", "certificate_after_completion_enabled", "require_completing_lessons_in_order", "order", "visibility", "created_at", "updated_at", "chapters_count", "total_lessons_count", "completed_lessons_count", "total_duration_seconds", "latest_lesson_created_at", "started_at", "lesson_unlock_days", "resume_lesson" ], "type": "object" }, "CourseStudent": { "description": "An enrollment record for a student in a course, including progress and completion metrics.", "properties": { "completed_lessons_count": { "description": "The total number of lessons this student has marked as completed in the course.", "example": 42, "type": "integer" }, "completion_rate": { "description": "The percentage of available lessons the student has completed, as a value from 0 to 100 rounded to two decimal places.", "example": 6.9, "type": "number" }, "course": { "description": "The course this student is enrolled in.", "properties": { "experience": { "description": "The parent experience that this course belongs to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "The unique identifier for the course.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the course shown to students. Null if no title has been set.", "example": "Introduction to Technical Analysis", "type": [ "string", "null" ] } }, "required": [ "id", "title", "experience" ], "type": "object" }, "first_interaction_at": { "description": "The timestamp when the student first interacted with this course, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the course student type.", "type": "string" }, "last_interaction_at": { "description": "The timestamp when the student most recently interacted with this course, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "total_lessons_count": { "description": "The total number of visible lessons available to this student in the course.", "example": 42, "type": "integer" }, "user": { "description": "The user profile of the enrolled student.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "completed_lessons_count", "completion_rate", "total_lessons_count", "first_interaction_at", "last_interaction_at", "user", "course" ], "type": "object" }, "CourseStudentListItem": { "description": "An enrollment record for a student in a course, including progress and completion metrics.", "properties": { "completed_lessons_count": { "description": "The total number of lessons this student has marked as completed in the course.", "example": 42, "type": "integer" }, "completion_rate": { "description": "The percentage of available lessons the student has completed, as a value from 0 to 100 rounded to two decimal places.", "example": 6.9, "type": "number" }, "first_interaction_at": { "description": "The timestamp when the student first interacted with this course, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the course student type.", "type": "string" }, "last_interaction_at": { "description": "The timestamp when the student most recently interacted with this course, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "total_lessons_count": { "description": "The total number of visible lessons available to this student in the course.", "example": 42, "type": "integer" }, "user": { "description": "The user profile of the enrolled student.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "completed_lessons_count", "completion_rate", "total_lessons_count", "first_interaction_at", "last_interaction_at", "user" ], "type": "object" }, "CourseVisibilities": { "description": "The available visibilities for a course. Determines how / whether a course is visible to users.", "enum": [ "visible", "hidden" ], "type": "string" }, "CoursesAssessmentQuestionTypes": { "description": "The available types for an assessment question", "enum": [ "short_answer", "true_false", "multiple_choice", "multiple_select" ], "type": "string" }, "Currencies": { "description": "The available currencies on the platform", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "CustomCtas": { "description": "The different types of custom CTAs that can be selected.", "enum": [ "get_access", "join", "order_now", "shop_now", "call_now", "donate_now", "contact_us", "sign_up", "subscribe", "purchase", "get_offer", "apply_now", "complete_order" ], "type": "string" }, "CustomFieldTypes": { "const": "text", "description": "The type of the custom field.", "type": "string" }, "CustomerTrackingPreferences": { "properties": { "accent_color": { "description": "Accent color, as a `#rrggbb` hex color. `null` uses the default.", "type": [ "string", "null" ] }, "enabled": { "description": "Whether the public tracking page and guest lookup are available. `null` is off.", "type": [ "boolean", "null" ] }, "show_business_name": { "description": "Whether to display the business name on the tracking page and Element. `null` shows it.", "type": [ "boolean", "null" ] }, "show_logo": { "description": "Whether to display the logo on the tracking page and Element. `null` shows it.", "type": [ "boolean", "null" ] }, "support_email": { "description": "Customer support email address.", "type": [ "string", "null" ] }, "support_url": { "description": "HTTPS customer support URL.", "type": [ "string", "null" ] } }, "required": [ "enabled", "show_logo", "show_business_name", "accent_color", "support_email", "support_url" ], "type": "object" }, "DetailedTargetingOption": { "properties": { "audience_size_lower_bound": { "description": "Low end of the ad platform's estimate of how many people this option can reach. Null when the platform doesn't publish one.", "example": 18400000, "type": [ "number", "null" ] }, "audience_size_upper_bound": { "description": "High end of the ad platform's estimate of how many people this option can reach. Null when the platform doesn't publish one.", "example": 21700000, "type": [ "number", "null" ] }, "behavior_type": { "description": "What a behavior category is measured on, on ad platforms that scope them. Send it back on the `detailed_targeting.behaviors` entry alongside the id. Null for options that aren't scoped.", "enum": [ "video", "creator", "hashtag", null ], "example": "video", "type": [ "string", "null" ] }, "description": { "description": "The ad platform's description of who the option covers, when it publishes one.", "example": "People who have expressed an interest in or like pages related to car washing and detailing.", "type": [ "string", "null" ] }, "id": { "description": "The ad platform's ID for the option in its targeting taxonomy. Use it as the `id` of a `detailed_targeting` entry.", "example": "6003193685204", "type": "string" }, "name": { "description": "Display name, such as `Movies`.", "example": "Car wash", "type": "string" }, "type": { "description": "Which detailed-targeting field the option belongs in: `interests` and `behaviors` go in the matching `detailed_targeting` field; demographic categories (`life_events`, `industries`, `income`, `family_statuses`, `work_employers`, `work_positions`, `education_schools`, `education_majors`) go in `detailed_targeting.demographics` with this value as the entry's `type`.", "enum": [ "interests", "behaviors", "life_events", "industries", "income", "family_statuses", "work_employers", "work_positions", "education_schools", "education_majors" ], "example": "interests", "type": "string" } }, "required": [ "type", "id", "name", "behavior_type", "audience_size_lower_bound", "audience_size_upper_bound", "description" ], "title": "Detailed targeting", "type": "object" }, "Direction": { "description": "The direction of the sort.", "enum": [ "asc", "desc" ], "type": "string" }, "Dispute": { "properties": { "acceptable": { "description": "Whether the dispute can be conceded to the customer with `POST /disputes/{id}/accept`. True only for a chargeback still awaiting a response, before `evidence_due_at`, whose payment processor supports accepting disputes. Inquiries are never acceptable.", "example": false, "type": "boolean" }, "account_id": { "description": "The account the dispute was filed against, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "amount": { "description": "The disputed amount, in whole units of `currency`.", "example": 150.0, "type": "number" }, "buyer": { "$ref": "#/components/schemas/DisputeBuyer", "description": "The customer who filed the dispute." }, "created_at": { "description": "When the dispute was opened, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code of the disputed amount.", "example": "usd", "type": "string" }, "evidence": { "$ref": "#/components/schemas/DisputeEvidence", "description": "The evidence packet sent to the processor to contest the dispute." }, "evidence_due_at": { "description": "The deadline to submit evidence, as an ISO 8601 timestamp. `null` when the network already auto-resolved the dispute (Visa RDR) with no evidence round, or when the processor hasn't reported a deadline for this dispute.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "evidence_editable": { "description": "Whether `evidence` can still be changed and submitted.", "example": false, "type": "boolean" }, "evidence_locked_reason": { "description": "Why evidence can no longer be edited. `null` while `evidence_editable` is true.", "enum": [ "submitted", "response_window_closed", "not_contestable", null ], "example": "submitted", "type": [ "string", "null" ] }, "evidence_submitted_at": { "description": "When the evidence was submitted to the processor, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "fee": { "description": "The dispute fee charged to the seller, in the currency it was collected in. `null` when no fee was charged, such as for an inquiry or a Visa RDR resolution.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Dispute ID, prefixed `dspt_`.", "example": "dspt_xxxxxxxxxxxxxx", "type": "string" }, "inquiry": { "description": "Whether this is a pre-dispute inquiry rather than a formal chargeback. Inquiries follow the same lifecycle but move no funds unless one escalates.", "example": false, "type": "boolean" }, "issuer_comments": { "items": { "$ref": "#/components/schemas/DisputeIssuerComment", "description": "What the card issuer said when filing the dispute. Only populated when the issuer provides them, and listed in the order they were received." }, "type": "array" }, "line_items": { "items": { "$ref": "#/components/schemas/ReceiptLineItem", "description": "Everything the disputed payment charged for, in purchase order. `product_id` and `variant_id` name the first of these; a cart's later items appear only here. A payment made before items were recorded lists the single item its variant implies. Empty when the payment is not linked to a variant." }, "type": "array" }, "payment": { "$ref": "#/components/schemas/DisputePayment", "description": "The payment being disputed." }, "product_id": { "description": "The product the disputed payment was for, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "reason": { "description": "Why the customer says they are disputing, normalized across processors and card networks. `other` covers a processor reason Whop has not categorized yet.", "enum": [ "fraudulent", "unrecognized", "declined_authorization", "product_not_received", "product_unacceptable", "subscription_canceled", "credit_not_processed", "duplicate", "processing_error", "documentation_request", "bank_cannot_process", "other" ], "example": "other", "type": "string" }, "reason_code": { "description": "The raw card-network or processor reason code, such as `10.4`. Informational only — `reason` is not derived from it.", "example": "13.1", "type": [ "string", "null" ] }, "status": { "description": "Where the dispute stands. `needs_response` is awaiting evidence, `under_review` is with the processor, `won` returned the funds to the seller, `lost` returned them to the customer, and `prevented` means the customer was refunded before any ruling, so it settles like `lost`. The `warning_` statuses are the same stages for an inquiry, which moves no funds. A dispute past its `evidence_due_at` reports `under_review` — the window to respond has closed.", "enum": [ "needs_response", "warning_needs_response", "under_review", "warning_under_review", "won", "lost", "prevented", "warning_closed" ], "example": "under_review", "type": "string" }, "updated_at": { "description": "When the dispute was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "variant_id": { "description": "The variant the disputed payment was made on, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "status", "inquiry", "amount", "currency", "fee", "reason", "reason_code", "issuer_comments", "account_id", "product_id", "variant_id", "line_items", "evidence_editable", "evidence_locked_reason", "evidence_due_at", "evidence_submitted_at", "acceptable", "buyer", "payment", "evidence", "created_at", "updated_at" ], "type": "object" }, "DisputeAlert": { "properties": { "account_id": { "description": "The account the alerted payment belongs to, prefixed `biz_`. `null` while the alert is unmatched.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "amount": { "description": "The alerted amount, in whole units of `currency`. This is what the issuer reported, which can differ from the payment's own amount.", "example": 25.0, "type": "number" }, "auto_refunded": { "description": "Whether Whop automatically refunded the alerted payment. Reflects the payment, so it can be `true` for a refund issued by another flow (RDR, resolution) on the same payment.", "example": false, "type": "boolean" }, "card_brand": { "description": "The card network as reported by the issuer, lowercased, such as `visa` or `mastercard`. `unknown` when the report carries neither a network nor a recognizable BIN.", "example": "visa", "type": [ "string", "null" ] }, "created_at": { "description": "When Whop received the alert, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code of the alerted amount.", "example": "usd", "type": "string" }, "fee": { "description": "The alert fee charged to the account, in the currency it was collected in. `null` when `fee_charged` is false.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "fee_charged": { "description": "Whether Whop charged the account an alert fee for this one. Always `false` for `early_fraud_warning`, which Whop is not billed for and never passes on.", "example": false, "type": "boolean" }, "id": { "description": "Dispute alert ID, prefixed `dspa_`.", "example": "dspa_xxxxxxxxxxxxxx", "type": "string" }, "issuer": { "deprecated": true, "description": "Deprecated: always `null` outside Whop's own dashboard. Name of the bank that issued the card and filed the report.\nDEPRECATED: Always null outside Whop's own dashboard.", "example": null, "type": [ "string", "null" ] }, "payment_id": { "description": "The payment the issuer reported, prefixed `pay_`. `null` when Whop could not match the report to a payment.", "example": "pay_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product the alerted payment was for, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "reported_at": { "description": "When the issuer filed the report, as an ISO 8601 timestamp. Earlier than `created_at`, which is when Whop received it.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "source": { "description": "The network program that sent the alert, which `type` alone doesn't tell apart. `ethoca` for Mastercard Ethoca, `cdrn` for Visa Verifi CDRN, `rdr` for Visa RDR, `tc40` / `safe` for a Visa / Mastercard fraud report, `paypal` for a PayPal alert. `null` when the network didn't say.", "enum": [ "ethoca", "cdrn", "rdr", "tc40", "safe", "paypal", null ], "example": "rdr", "type": [ "string", "null" ] }, "transaction_at": { "description": "When the reported transaction was made, as an ISO 8601 timestamp — falls back to when the matched payment was made if the issuer's own report didn't carry one. Should not be `null` in practice; treat one as a data issue rather than expected behavior.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "type": { "description": "What the issuer sent. `early_fraud_warning` is a fraud report on a settled payment (Visa TC40 / Mastercard SAFE) — refunding still avoids the chargeback, and Whop never charges a fee for one. `dispute_alert` is a pre-dispute notice from the issuer's alert network, which Whop pays for and passes on as a fee. `rapid_dispute_resolution` is a Visa RDR case the network already closed by refunding the payment — nothing is left to act on.", "enum": [ "early_fraud_warning", "dispute_alert", "rapid_dispute_resolution" ], "example": "rapid_dispute_resolution", "type": "string" }, "updated_at": { "description": "When the alert was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "type", "source", "amount", "currency", "card_brand", "issuer", "account_id", "payment_id", "product_id", "fee_charged", "fee", "auto_refunded", "reported_at", "transaction_at", "created_at", "updated_at" ], "type": "object" }, "DisputeAlertLegacy": { "description": "A dispute alert represents an early warning notification from a payment processor about a potential dispute or chargeback.", "properties": { "alert_type": { "$ref": "#/components/schemas/DisputeAlertTypes", "description": "The type of the dispute alert." }, "amount": { "description": "The alerted amount in the specified currency.", "example": 6.9, "type": "number" }, "charge_for_alert": { "description": "Whether this alert incurs a charge.", "type": "boolean" }, "created_at": { "description": "The time the dispute alert was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the alerted amount." }, "dispute": { "description": "The dispute associated with the dispute alert.", "properties": { "amount": { "description": "The disputed amount in the specified currency, formatted as a decimal.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the dispute was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the disputed amount." }, "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" }, "reason": { "description": "A human-readable reason for the dispute.", "example": "Product Not Received", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DisputeStatuses", "description": "The current status of the dispute lifecycle, such as needs_response, under_review, won, or lost." } }, "required": [ "id", "amount", "currency", "status", "reason", "created_at" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier of the dispute alert.", "example": "dspa_xxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The payment associated with the dispute alert.", "properties": { "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status" ], "type": [ "object", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "total", "subtotal", "usd_total", "currency", "created_at", "paid_at", "dispute_alerted_at", "payment_method_type", "billing_reason", "card_brand", "card_last4", "user", "member", "membership" ], "type": [ "object", "null" ] }, "transaction_date": { "description": "The date of the original transaction.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "alert_type", "amount", "currency", "created_at", "transaction_date", "charge_for_alert", "payment", "dispute" ], "type": "object" }, "DisputeAlertListItem": { "description": "A dispute alert represents an early warning notification from a payment processor about a potential dispute or chargeback.", "properties": { "alert_type": { "$ref": "#/components/schemas/DisputeAlertTypes", "description": "The type of the dispute alert." }, "amount": { "description": "The alerted amount in the specified currency.", "example": 6.9, "type": "number" }, "charge_for_alert": { "description": "Whether this alert incurs a charge.", "type": "boolean" }, "created_at": { "description": "The time the dispute alert was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the alerted amount." }, "dispute": { "description": "The dispute associated with the dispute alert.", "properties": { "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier of the dispute alert.", "example": "dspa_xxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The payment associated with the dispute alert.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "transaction_date": { "description": "The date of the original transaction.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "alert_type", "amount", "currency", "created_at", "transaction_date", "charge_for_alert", "payment", "dispute" ], "type": "object" }, "DisputeAlertTypes": { "description": "The type of dispute alert.", "enum": [ "dispute", "dispute_rdr", "fraud" ], "type": "string" }, "DisputeAttachment": { "properties": { "content_type": { "description": "The uploaded file's MIME type.", "example": "image/png", "type": [ "string", "null" ] }, "filename": { "description": "The uploaded file's name.", "example": "booking-confirmation-email.png", "type": [ "string", "null" ] }, "id": { "description": "The attachment's ID. `null` for a Whop-hosted policy, which is not an uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "platform": { "description": "Whether this is Whop's own hosted policy, standing in because the seller uploaded none. Sending it back on a PATCH changes nothing.", "example": false, "type": "boolean" }, "url": { "description": "A URL to download the attachment.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url", "platform" ], "type": "object" }, "DisputeBuyer": { "properties": { "email": { "description": "The customer's email address. Requires the `member:email:read` scope; `null` without it.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "member_id": { "description": "The customer's member row on the account, prefixed `mem_`.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "name": { "description": "The customer's display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "user_id": { "description": "The customer's user ID, prefixed `user_`. `null` for a guest checkout.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "username": { "description": "The customer's Whop username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "user_id", "member_id", "name", "username", "email" ], "type": "object" }, "DisputeEvidence": { "properties": { "access_activity_log": { "description": "Log of the customer's access to the product, such as sign-in or download activity.", "example": "Vehicle checked in 2026-01-04 09:02, released 2026-01-05 16:40. Signed release on file.", "type": [ "string", "null" ] }, "billing_address": { "description": "The billing address the customer provided at checkout.", "example": "4180 Burnet Rd, Austin, TX 78756, US", "type": [ "string", "null" ] }, "cancellation_policy_attachment": { "description": "The cancellation policy document. Defaults to the account's cancellation policy, then its terms of service, then its return policy, then Whop's platform policy.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] }, "cancellation_policy_disclosure": { "description": "How the cancellation policy was shown to the customer before purchase.", "example": "Shown at checkout and again in the booking confirmation email.", "type": [ "string", "null" ] }, "customer_communication_attachment": { "description": "Correspondence with the customer, or proof they used the product.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] }, "customer_email_address": { "description": "The email address the customer used at checkout.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "customer_name": { "description": "The customer's name as given at checkout.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "documents": { "items": { "$ref": "#/components/schemas/DisputeEvidenceDocument", "description": "Additional evidence documents, beyond the four fixed slots — set via `evidence.documents` on `PATCH /disputes/{id}`. Each rides into the submitted packet under its `document_type`." }, "type": "array" }, "notes": { "description": "Any additional context for the processor reviewing the dispute.", "example": "Two-day ceramic coating completed and collected. Before and after photos attached.", "type": [ "string", "null" ] }, "product_description": { "description": "What the customer purchased, in the seller's own words.", "example": "Two-stage paint correction with a three-year ceramic coating.", "type": [ "string", "null" ] }, "refund_policy_attachment": { "description": "The refund policy document. Defaults to the account's return policy, then its terms of service, then Whop's platform policy.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] }, "refund_policy_disclosure": { "description": "How the refund policy was shown to the customer before purchase.", "example": "Linked from the booking page and accepted at checkout.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "Why a refund was refused, when one was requested and denied.", "example": "Work was completed and the vehicle collected, so the deposit is non-refundable.", "type": [ "string", "null" ] }, "service_date": { "description": "When the product or service was delivered.", "example": "2026-01-01", "type": [ "string", "null" ] }, "uncategorized_attachment": { "description": "Supporting evidence that does not fit the other categories.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "type": "null" } ] } }, "required": [ "access_activity_log", "billing_address", "cancellation_policy_disclosure", "customer_email_address", "customer_name", "notes", "product_description", "refund_policy_disclosure", "refund_refusal_explanation", "service_date", "cancellation_policy_attachment", "customer_communication_attachment", "refund_policy_attachment", "uncategorized_attachment", "documents" ], "type": "object" }, "DisputeEvidenceDocument": { "properties": { "blurhash": { "description": "BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.", "example": "LA6bDXT$E3b:R6i+RibEIWbp%ej1", "type": [ "string", "null" ] }, "content_type": { "description": "The uploaded file's MIME type. Uploads are restricted to the types the processor accepts, and rejected without one — never null.", "enum": [ "application/pdf", "application/json", "image/jpeg", "image/png", "image/webp", null ], "example": "image/png", "type": [ "string", "null" ] }, "created_at": { "description": "When the file was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "document_type": { "description": "What this document proves, in the processor's own evidence vocabulary. `return_policy`, `cancellation_policy`, and `terms_of_service` are the seller's policy documents — uploading one overrides the account's copy for this dispute (`return_policy`, `cancellation_policy`, and `customer_communication` also override the matching fixed evidence slot). `shipping_policy` is the seller's shipping terms. `customer_communication` is correspondence with the buyer — a support thread or chat log. `product_image` is a photo of the product or service the buyer received. `physical_fulfillment` is proof a physical order shipped and arrived; `digital_fulfillment` is proof the buyer accessed a digital product. `customer_order_history` is the buyer's past orders with this seller; `prior_transactions` is their broader payment history across the platform, for a fraud defense. `customer_session` is checkout forensics — IP, device fingerprint, AVS/CVV, 3D Secure result. `subscription` is membership lifecycle evidence — renewals, cancellation, reminders sent.", "enum": [ "return_policy", "shipping_policy", "cancellation_policy", "terms_of_service", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription", "customer_communication" ], "example": "customer_order_history", "type": "string" }, "duration_seconds": { "description": "Audio or video duration in seconds. Null when unavailable or removed by moderation.", "example": null, "type": [ "number", "null" ] }, "filename": { "description": "The original filename, including its extension.", "example": "customer-order-history.png", "type": [ "string", "null" ] }, "height": { "description": "Image or video height in pixels. Null when unavailable or removed by moderation.", "example": 100, "type": [ "integer", "null" ] }, "id": { "description": "The file's ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "multipart_chunk_size": { "description": "The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.", "type": [ "integer", "null" ] }, "multipart_upload_id": { "description": "The ID of the multipart upload, passed back to `complete`. Present only on create, and only for multipart uploads.", "type": [ "string", "null" ] }, "multipart_upload_urls": { "items": { "$ref": "#/components/schemas/FileMultipartUrl", "description": "The presigned URL for each part. Present only on create, and only for multipart uploads." }, "type": [ "array", "null" ] }, "object": { "description": "The type of this object, always `file`.", "example": "file", "type": "string" }, "removed_by_moderation": { "description": "Whether moderation removed the file. When true, `url` serves a replacement image; filename, size, and content type still describe the original file.", "example": false, "type": "boolean" }, "size": { "description": "The file size in bytes. `null` until the upload has finished.", "example": 1024, "type": [ "integer", "null" ] }, "upload_headers": { "description": "Headers to send with the upload PUT. Present only on create.", "type": "object" }, "upload_status": { "description": "Where the file is in its upload lifecycle.", "enum": [ "pending", "processing", "ready", "failed" ], "example": "ready", "type": "string" }, "upload_url": { "description": "Presigned URL to PUT the file's bytes to. Present only on create, and only for single-part uploads.", "type": [ "string", "null" ] }, "url": { "description": "A URL to download the file: a permanent CDN URL for public files, a signed expiring URL for private ones. Null until the upload has finished; a replacement image URL when removed by moderation.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "visibility": { "description": "`public` files are served via an unsigned CDN URL; `private` files via a signed, expiring URL.", "enum": [ "public", "private" ], "example": "public", "type": "string" }, "waveform_url": { "description": "Audio waveform URL. Null when unavailable or removed by moderation.", "example": null, "type": [ "string", "null" ] }, "width": { "description": "Image or video width in pixels. Null when unavailable or removed by moderation.", "example": 100, "type": [ "integer", "null" ] } }, "required": [ "object", "id", "filename", "content_type", "size", "url", "removed_by_moderation", "upload_status", "visibility", "created_at", "width", "height", "blurhash", "duration_seconds", "waveform_url", "document_type" ], "type": "object" }, "DisputeIssuerComment": { "properties": { "received_at": { "description": "When the comment was received, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "text": { "description": "What the issuer wrote, as received.", "example": "Note: Cardholder states the ceramic coating appointment never took place\nCancellation method: By phone", "type": "string" } }, "required": [ "received_at", "text" ], "type": "object" }, "DisputeLegacy": { "description": "A dispute is a chargeback or payment challenge filed against a company, including evidence and response status.", "properties": { "access_activity_log": { "description": "A log of IP-based access activity for the customer on Whop, submitted as evidence in the dispute.", "example": "192.168.1.1 - 2024-01-15 12:00:00 UTC", "type": [ "string", "null" ] }, "amount": { "description": "The disputed amount in the specified currency, formatted as a decimal.", "example": 6.9, "type": "number" }, "billing_address": { "description": "The customer's billing address from their payment details, submitted as evidence in the dispute.", "example": "123 Main St, New York, NY 10001", "type": [ "string", "null" ] }, "cancellation_policy_attachment": { "description": "The cancellation policy document uploaded as dispute evidence. Null if no cancellation policy has been provided.", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "cancellation_policy_disclosure": { "description": "A text disclosure describing the company's cancellation policy, submitted as dispute evidence.", "example": "All sales are final. No refunds after 30 days.", "type": [ "string", "null" ] }, "company": { "description": "The company that the dispute was filed against.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the dispute was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the disputed amount." }, "customer_communication_attachment": { "description": "Evidence of customer communication or product usage, uploaded as a dispute attachment. Null if not provided.", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "customer_email_address": { "description": "The customer's email address from their payment details, included in the evidence packet sent to the payment processor. Editable before submission.", "example": "customer@example.com", "type": [ "string", "null" ] }, "customer_name": { "description": "The customer's full name from their payment details, included in the evidence packet sent to the payment processor. Editable before submission.", "example": "Jane Doe", "type": [ "string", "null" ] }, "editable": { "description": "Whether the dispute evidence can still be edited and submitted.", "type": [ "boolean", "null" ] }, "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" }, "needs_response_by": { "description": "The deadline by which dispute evidence must be submitted. Null if no response deadline is set.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "notes": { "description": "Additional freeform notes submitted by the company as part of the dispute evidence.", "example": "Customer used the product for 3 months before disputing.", "type": [ "string", "null" ] }, "payment": { "description": "The original payment that was disputed.", "properties": { "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status" ], "type": [ "object", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the receipt names no payment method.", "properties": { "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "type": "string" }, "icons": { "description": "The standard icon set: square and card shapes, each in light and dark colorways.", "properties": { "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square" ], "type": "object" }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "example": 42, "type": [ "integer", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "type": "string" } }, "required": [ "payment_method_type", "display_name", "installment_count", "icons" ], "type": [ "object", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "total", "subtotal", "usd_total", "currency", "created_at", "paid_at", "dispute_alerted_at", "payment_method_type", "billing_reason", "card_brand", "card_last4", "payment_instrument", "user", "member", "membership" ], "type": [ "object", "null" ] }, "plan": { "description": "The plan associated with the disputed payment. Null if the dispute is not linked to a specific plan.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "product": { "description": "The product associated with the disputed payment. Null if the dispute is not linked to a specific product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "product_description": { "description": "A description of the product or service provided, submitted as dispute evidence.", "example": "Monthly subscription to premium analytics dashboard.", "type": [ "string", "null" ] }, "reason": { "description": "A human-readable reason for the dispute.", "example": "Product Not Received", "type": [ "string", "null" ] }, "reason_code": { "description": "The card network reason code for the dispute. Null when the payment processor did not provide one.", "example": "10.4", "type": [ "string", "null" ] }, "refund_policy_attachment": { "description": "The refund policy document uploaded as dispute evidence. Null if no refund policy has been provided.", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "refund_policy_disclosure": { "description": "A text disclosure describing the company's refund policy, submitted as dispute evidence.", "example": "Refunds available within 14 days of purchase.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "An explanation from the company for why a refund was refused, submitted as dispute evidence.", "example": "The customer exceeded the refund window by 60 days.", "type": [ "string", "null" ] }, "service_date": { "description": "The date when the product or service was delivered to the customer, submitted as dispute evidence.", "example": "2024-01-15", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DisputeStatuses", "description": "The current status of the dispute lifecycle, such as needs_response, under_review, won, or lost." }, "uncategorized_attachment": { "description": "An additional attachment that does not fit into the standard evidence categories. Null if not provided.", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": [ "object", "null" ] }, "visa_rdr": { "description": "Whether the dispute was automatically resolved through Visa Rapid Dispute Resolution (RDR).", "type": "boolean" } }, "required": [ "id", "amount", "currency", "status", "editable", "created_at", "visa_rdr", "needs_response_by", "reason", "reason_code", "plan", "product", "company", "payment", "access_activity_log", "billing_address", "cancellation_policy_disclosure", "customer_email_address", "customer_name", "notes", "product_description", "refund_policy_disclosure", "refund_refusal_explanation", "service_date", "cancellation_policy_attachment", "customer_communication_attachment", "refund_policy_attachment", "uncategorized_attachment" ], "type": "object" }, "DisputeListItem": { "description": "A dispute is a chargeback or payment challenge filed against a company, including evidence and response status.", "properties": { "amount": { "description": "The disputed amount in the specified currency, formatted as a decimal.", "example": 6.9, "type": "number" }, "company": { "description": "The company that the dispute was filed against.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the dispute was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the disputed amount." }, "editable": { "description": "Whether the dispute evidence can still be edited and submitted.", "type": [ "boolean", "null" ] }, "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" }, "needs_response_by": { "description": "The deadline by which dispute evidence must be submitted. Null if no response deadline is set.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment": { "description": "The original payment that was disputed.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "payment_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the receipt names no payment method.", "properties": { "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "type": "string" }, "icons": { "description": "The standard icon set: square and card shapes, each in light and dark colorways.", "properties": { "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square" ], "type": "object" }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "example": 42, "type": [ "integer", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "type": "string" } }, "required": [ "payment_method_type", "display_name", "installment_count", "icons" ], "type": [ "object", "null" ] } }, "required": [ "id", "payment_instrument" ], "type": [ "object", "null" ] }, "plan": { "description": "The plan associated with the disputed payment. Null if the dispute is not linked to a specific plan.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "product": { "description": "The product associated with the disputed payment. Null if the dispute is not linked to a specific product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "reason": { "description": "A human-readable reason for the dispute.", "example": "Product Not Received", "type": [ "string", "null" ] }, "reason_code": { "description": "The card network reason code for the dispute. Null when the payment processor did not provide one.", "example": "10.4", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DisputeStatuses", "description": "The current status of the dispute lifecycle, such as needs_response, under_review, won, or lost." }, "visa_rdr": { "description": "Whether the dispute was automatically resolved through Visa Rapid Dispute Resolution (RDR).", "type": "boolean" } }, "required": [ "id", "amount", "currency", "status", "editable", "created_at", "visa_rdr", "needs_response_by", "reason", "reason_code", "plan", "product", "company", "payment" ], "type": "object" }, "DisputePayment": { "properties": { "amount": { "description": "What the customer was charged, in whole units of the payment's currency.", "example": 249.0, "type": [ "number", "null" ] }, "card_brand": { "description": "Card brand, when the customer paid by card.", "example": "visa", "type": [ "string", "null" ] }, "card_last4": { "description": "Last four digits of the card, when the customer paid by card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "When the payment was made, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code of the payment. Can differ from the dispute's currency when the processor settles in another currency.", "example": "usd", "type": [ "string", "null" ] }, "id": { "description": "Payment ID, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "payment_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the payment names no method.", "oneOf": [ { "$ref": "#/components/schemas/PaymentInstrument" }, { "type": "null" } ] }, "payment_method_type": { "description": "How the customer paid, such as `card` or `paypal`.", "example": "card", "type": [ "string", "null" ] }, "payment_processor": { "deprecated": true, "description": "Deprecated: no longer populated. Always `null`.\nDEPRECATED: No longer populated. Always null.", "example": null, "type": [ "string", "null" ] } }, "required": [ "id", "amount", "currency", "payment_method_type", "payment_processor", "card_brand", "card_last4", "payment_instrument", "created_at" ], "type": "object" }, "DisputeStatuses": { "description": "The possible statuses of a dispute", "enum": [ "warning_needs_response", "warning_under_review", "warning_closed", "needs_response", "under_review", "won", "lost", "closed", "other" ], "type": "string" }, "DmChannel": { "description": "A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.", "properties": { "created_at": { "description": "The time the entity was created (in milliseconds since Unix epoch)", "example": "123.45", "type": "string" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_message_at": { "description": "The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "A custom display name assigned to this channel by the user. Null if no custom name has been set.", "example": "Project Alpha Team", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "name", "last_message_at" ], "type": "object" }, "DmChannelListItem": { "description": "A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.", "properties": { "created_at": { "description": "The time the entity was created (in milliseconds since Unix epoch)", "example": "123.45", "type": "string" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_message_at": { "description": "The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "A custom display name assigned to this channel by the user. Null if no custom name has been set.", "example": "Project Alpha Team", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "name", "last_message_at" ], "type": "object" }, "DmMember": { "description": "A user's membership record in a messaging channel, including notification preferences and read state.", "properties": { "channel_id": { "description": "The unique identifier of the messaging channel this membership belongs to.", "type": "string" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_viewed_at": { "description": "The timestamp when this member last viewed the channel, as a Unix timestamp in milliseconds. Null if the member has never viewed the channel.", "example": "123.45", "type": [ "string", "null" ] }, "notification_preference": { "$ref": "#/components/schemas/DmsFeedMemberNotificationPreferences", "description": "The notification level for this channel: all, mentions, or none." }, "status": { "$ref": "#/components/schemas/DmsFeedMemberStatuses", "description": "The current state of this membership: requested, accepted, hidden, closed, or archived." }, "user_id": { "description": "The unique identifier of the user who holds this channel membership.", "type": "string" } }, "required": [ "id", "user_id", "channel_id", "status", "last_viewed_at", "notification_preference" ], "type": "object" }, "DmMemberListItem": { "description": "A user's membership record in a messaging channel, including notification preferences and read state.", "properties": { "channel_id": { "description": "The unique identifier of the messaging channel this membership belongs to.", "type": "string" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_viewed_at": { "description": "The timestamp when this member last viewed the channel, as a Unix timestamp in milliseconds. Null if the member has never viewed the channel.", "example": "123.45", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DmsFeedMemberStatuses", "description": "The current state of this membership: requested, accepted, hidden, closed, or archived." }, "user_id": { "description": "The unique identifier of the user who holds this channel membership.", "type": "string" } }, "required": [ "id", "user_id", "channel_id", "status", "last_viewed_at" ], "type": "object" }, "DmsFeedMemberNotificationPreferences": { "description": "The notification preferences for a DMs feed member", "enum": [ "all", "mentions", "none" ], "type": "string" }, "DmsFeedMemberStatuses": { "description": " The statuses of a DMs feed member", "enum": [ "requested", "accepted", "hidden", "closed", "archived" ], "type": "string" }, "DmsPostTypes": { "description": "The types of post", "enum": [ "regular", "system", "automated" ], "type": "string" }, "Domain": { "properties": { "account_id": { "description": "ID of the account the domain belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "apple_pay": { "description": "Offering Apple Pay at checkouts served from the domain. `null` when not enrolled or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainApplePay" }, { "type": "null" } ] }, "availability": { "description": "Whether you can register the hostname and what it costs. Set only when no domain on Whop has it.", "oneOf": [ { "$ref": "#/components/schemas/DomainAvailability" }, { "type": "null" } ] }, "created_at": { "description": "When the domain was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "domain": { "description": "Normalized hostname, such as checkout.example.com.", "example": "shop.com", "type": "string" }, "email": { "description": "Sending and receiving email on the domain through Whop. `null` when not wanted, or when the domain belongs to an account you can't read.", "oneOf": [ { "$ref": "#/components/schemas/DomainEmail" }, { "type": "null" } ] }, "id": { "description": "Domain ID, prefixed `dom_`. `null` when no domain on Whop has this hostname.", "example": "dom_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "issues": { "items": { "$ref": "#/components/schemas/DomainIssue", "description": "What needs attention, each tagged with its capability. Empty when nothing does or when the domain isn't yours." }, "type": "array" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Custom string keys and values attached to this domain. Empty when the domain isn't yours.", "example": { "project": "website" }, "type": "object" }, "owned_by": { "description": "The account that has proven it owns this hostname on Whop, which can be your own. `null` when no account has.", "oneOf": [ { "$ref": "#/components/schemas/DomainOwner" }, { "type": "null" } ] }, "pixel": { "description": "Tracking page views on the domain with the Whop pixel. `null` when not tracked or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainPixel" }, { "type": "null" } ] }, "platform": { "description": "An address on a zone Whop runs, such as example.whop.site, that follows its app's route. `null` for other domains or when not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainPlatform" }, { "type": "null" } ] }, "public_record": { "description": "The domain's public registration record (RDAP), read when you retrieve it by hostname. `null` for domains on Whop, available domains, or a record that couldn't be read.", "oneOf": [ { "$ref": "#/components/schemas/DomainPublicRecord" }, { "type": "null" } ] }, "registration": { "description": "Buying the domain through Whop, renewing it, and running its DNS. `null` when not wanted or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainRegistration" }, { "type": "null" } ] }, "stats": { "description": "Traffic on the domain. `null` when the domain isn't on Whop or isn't visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainStats" }, { "type": "null" } ] }, "status": { "description": "The most pressing state of the domain's capabilities: `releasing`, then `action_required`, then `pending`, then `ready`. `idle` when it wants nothing.", "enum": [ "idle", "pending", "ready", "action_required", "releasing", null ], "example": "pending", "type": [ "string", "null" ] }, "transfer": { "description": "Moving the domain to another Whop account. `null` when not turned on or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainTransfer" }, { "type": "null" } ] }, "updated_at": { "description": "When the domain was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "verification": { "description": "Proving you control the domain's DNS with a TXT record. `null` when not wanted or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainVerification" }, { "type": "null" } ] }, "website": { "description": "Serving a Whop website on the domain. `null` when not wanted.", "oneOf": [ { "$ref": "#/components/schemas/DomainWebsite" }, { "type": "null" } ] } }, "required": [ "id", "domain", "status", "account_id", "verification", "registration", "platform", "website", "apple_pay", "pixel", "email", "transfer", "owned_by", "issues", "stats", "metadata", "created_at", "updated_at", "availability", "public_record" ], "type": "object" }, "DomainApplePay": { "properties": { "state": { "description": "`pending` while Whop registers the domain with Apple, `ready` once Apple verified it, and `action_required` when Apple couldn't; its issue says how to fix it. `releasing` while Whop removes it from Apple.", "enum": [ "pending", "ready", "action_required", "releasing" ], "example": "pending", "type": "string" } }, "required": [ "state" ], "type": "object" }, "DomainAvailability": { "properties": { "available": { "description": "Whether the domain can be registered now.", "example": true, "type": "boolean" }, "premium": { "description": "Whether the registry charges more than its standard price for this domain.", "example": false, "type": "boolean" }, "price": { "description": "What the first year of registration costs. `null` when the domain is not available.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "renewal_price": { "description": "What each yearly renewal costs after the first year. `null` when the domain is not available.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "score": { "description": "How desirable the domain is, from 0 to 100. Short, real-word names on well-known extensions score highest.", "example": 75, "type": "integer" }, "transfer_price": { "description": "What moving the domain to Whop costs if it's registered elsewhere, including the year it adds to the domain's registration. `null` when it's available or can't be transferred.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "available", "premium", "price", "renewal_price", "transfer_price", "score" ], "type": "object" }, "DomainDnsRecord": { "properties": { "name": { "description": "Full hostname where the record must be published.", "example": "_whop.shop.example.com", "type": "string" }, "type": { "description": "DNS record type.", "enum": [ "TXT", "CNAME", "A", "AAAA" ], "example": "TXT", "type": "string" }, "value": { "description": "DNS record content.", "example": "whop-domain-verification=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "type", "name", "value" ], "type": "object" }, "DomainEmail": { "properties": { "state": { "description": "`pending` while Whop sets the domain up with its email provider and publishes its DNS records, `ready` once the provider verified them, and `action_required` when it couldn't; its issue says what happens next. `releasing` while Whop removes email from the domain.", "enum": [ "pending", "ready", "action_required", "releasing" ], "example": "pending", "type": "string" } }, "required": [ "state" ], "type": "object" }, "DomainIssue": { "properties": { "capability": { "description": "The capability the issue is about.", "enum": [ "verification", "registration", "platform", "website", "apple_pay", "pixel", "email", "transfer" ], "example": "verification", "type": "string" }, "code": { "description": "What needs attention, as a stable code.", "enum": [ "verification_required", "verification_expired", "ownership_conflict", "ownership_lost", "dns_required", "provider_validation", "certificate_pending", "expiring_soon", "account_unavailable", "check_failed", "purchase_expired", "domain_unavailable", "unsupported_tld", "registration_unavailable", "registration_failed", "renewal_failed", "payment_action_required", "domain_on_whop", "domain_transfer_unavailable", "transfer_locked", "transfer_auth_code_rejected", "transfer_rejected", "transfer_not_cancellable", "domain_transfer_failed", "apple_pay_unverified", "pixel_not_seen", "pixel_not_installed", "pixel_waiting", "pixel_unreachable", "pixel_quiet", "email_needs_whop_dns", "email_unreachable", "email_identity_in_use", "email_verification_failed" ], "example": "verification_required", "type": "string" }, "code_block": { "description": "Code to add to the site to fix the issue, ready to copy. `null` when the issue needs none.", "example": null, "type": [ "string", "null" ] }, "dns_records": { "items": { "$ref": "#/components/schemas/DomainDnsRecord", "description": "DNS records to publish to fix the issue. Empty when the issue needs no DNS change." }, "type": "array" }, "message": { "description": "What needs attention and how to fix it.", "example": "Publish this TXT record to prove you own the domain. Verification runs automatically.", "type": "string" } }, "required": [ "capability", "code", "message", "dns_records", "code_block" ], "type": "object" }, "DomainListItem": { "properties": { "account_id": { "description": "ID of the account the domain belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "apple_pay": { "description": "Offering Apple Pay at checkouts served from the domain. `null` when not enrolled or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainApplePay" }, { "type": "null" } ] }, "availability": { "description": "Whether you can register the hostname and what it costs. Set only when no domain on Whop has it.", "oneOf": [ { "$ref": "#/components/schemas/DomainAvailability" }, { "type": "null" } ] }, "created_at": { "description": "When the domain was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "domain": { "description": "Normalized hostname, such as checkout.example.com.", "example": "shop.example.com", "type": "string" }, "email": { "description": "Sending and receiving email on the domain through Whop. `null` when not wanted, or when the domain belongs to an account you can't read.", "oneOf": [ { "$ref": "#/components/schemas/DomainEmail" }, { "type": "null" } ] }, "id": { "description": "Domain ID, prefixed `dom_`. `null` when no domain on Whop has this hostname.", "example": "dom_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "issues": { "items": { "$ref": "#/components/schemas/DomainIssue", "description": "What needs attention, each tagged with its capability. Empty when nothing does or when the domain isn't yours." }, "type": "array" }, "metadata": { "description": "Custom string keys and values attached to this domain. Empty when the domain isn't yours.", "example": {}, "type": "object" }, "owned_by": { "description": "The account that has proven it owns this hostname on Whop, which can be your own. `null` when no account has.", "oneOf": [ { "$ref": "#/components/schemas/DomainOwner" }, { "type": "null" } ] }, "pixel": { "description": "Tracking page views on the domain with the Whop pixel. `null` when not tracked or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainPixel" }, { "type": "null" } ] }, "platform": { "description": "An address on a zone Whop runs, such as example.whop.site, that follows its app's route. `null` for other domains or when not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainPlatform" }, { "type": "null" } ] }, "registration": { "description": "Buying the domain through Whop, renewing it, and running its DNS. `null` when not wanted or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainRegistration" }, { "type": "null" } ] }, "stats": { "description": "Traffic on the domain. `null` when the domain isn't on Whop or isn't visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainStats" }, { "type": "null" } ] }, "status": { "description": "The most pressing state of the domain's capabilities: `releasing`, then `action_required`, then `pending`, then `ready`. `idle` when it wants nothing.", "enum": [ "idle", "pending", "ready", "action_required", "releasing", null ], "example": "pending", "type": [ "string", "null" ] }, "transfer": { "description": "Moving the domain to another Whop account. `null` when not turned on or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainTransfer" }, { "type": "null" } ] }, "updated_at": { "description": "When the domain was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "verification": { "description": "Proving you control the domain's DNS with a TXT record. `null` when not wanted or not visible to you.", "oneOf": [ { "$ref": "#/components/schemas/DomainVerification" }, { "type": "null" } ] }, "website": { "description": "Serving a Whop website on the domain. `null` when not wanted.", "oneOf": [ { "$ref": "#/components/schemas/DomainWebsite" }, { "type": "null" } ] } }, "required": [ "id", "domain", "status", "account_id", "verification", "registration", "platform", "website", "apple_pay", "pixel", "email", "transfer", "owned_by", "issues", "stats", "metadata", "created_at", "updated_at", "availability" ], "type": "object" }, "DomainOwner": { "properties": { "id": { "description": "ID of the account that owns the domain, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo image URL.", "example": null, "type": [ "string", "null" ] }, "route": { "description": "Account public route identifier.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Account display name.", "example": "Rival Shop", "type": "string" } }, "required": [ "id", "title", "route", "logo_url" ], "type": "object" }, "DomainPixel": { "properties": { "state": { "description": "`ready` while the Whop pixel recorded a page view on the domain in the last 7 days. `pending` until a pixel you asked for records its first one, and `action_required` once it goes 7 days without one; its issue says what to do.", "enum": [ "pending", "ready", "action_required" ], "example": "pending", "type": "string" } }, "required": [ "state" ], "type": "object" }, "DomainPlatform": { "properties": { "state": { "description": "Whether Whop holds this address for the account. A platform address is ready as soon as its route is claimed.", "enum": [ "pending", "ready", "action_required", "releasing" ], "example": "pending", "type": "string" } }, "required": [ "state" ], "type": "object" }, "DomainPublicRecord": { "properties": { "dnssec": { "description": "Whether the domain's delegation is signed with DNSSEC, or `null` when the registry doesn't say.", "example": false, "type": [ "boolean", "null" ] }, "expires_at": { "description": "When the current registration expires, as an ISO 8601 timestamp, or `null` when the record omits it.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "name_servers": { "items": { "description": "The name servers the domain delegates to, lowercase, such as `ns1.example.com`. Empty when the record lists none.", "example": "ns1.example.com", "type": "string" }, "type": "array" }, "registered_at": { "description": "When the domain was first registered, as an ISO 8601 timestamp, or `null` when the record omits it.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "registrant": { "description": "Who the domain is registered to, often a privacy service or `Redacted For Privacy`. `null` when the record publishes no registrant.", "oneOf": [ { "$ref": "#/components/schemas/DomainRegistrant" }, { "type": "null" } ] }, "registrar": { "description": "The registrar that manages the domain, or `null` when the record doesn't name one.", "oneOf": [ { "$ref": "#/components/schemas/DomainRegistrar" }, { "type": "null" } ] }, "statuses": { "items": { "description": "The domain's registry statuses in RDAP form, such as `client transfer prohibited`. Empty when the record lists none.", "example": "client transfer prohibited", "type": "string" }, "type": "array" }, "updated_at": { "description": "When the registration record last changed, as an ISO 8601 timestamp, or `null` when the record omits it.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "registrar", "registrant", "registered_at", "expires_at", "updated_at", "statuses", "name_servers", "dnssec" ], "type": "object" }, "DomainRegistrant": { "properties": { "address": { "description": "Registrant postal address as published, with lines separated by line breaks. Often only a state or region. `null` when withheld.", "example": "Burlington\nMA", "type": [ "string", "null" ] }, "contact_url": { "description": "A web form for contacting the registrant, published when the registrar withholds their email. `null` when there is none.", "example": "https://registrar.example/contact/example.com", "type": [ "string", "null" ] }, "country": { "description": "Registrant country as an ISO 3166-1 alpha-2 code, such as `US`, or `null` when withheld.", "example": "US", "type": [ "string", "null" ] }, "email": { "description": "Registrant email address, often a privacy forwarding address, or `null` when withheld.", "example": null, "type": [ "string", "null" ] }, "name": { "description": "Registrant name, or `null` when withheld.", "example": null, "type": [ "string", "null" ] }, "organization": { "description": "Registrant organization, often a privacy service, or `null` when withheld.", "example": "Privacy Protect, LLC", "type": [ "string", "null" ] }, "phone": { "description": "Registrant phone number, or `null` when withheld.", "example": null, "type": [ "string", "null" ] } }, "required": [ "name", "organization", "email", "phone", "address", "country", "contact_url" ], "type": "object" }, "DomainRegistrar": { "properties": { "iana_id": { "description": "The registrar's IANA registrar ID, or `null` when the record omits it.", "example": "9999", "type": [ "string", "null" ] }, "name": { "description": "Registrar name, such as `GoDaddy.com, LLC`.", "example": "Example Registrar, Inc.", "type": "string" }, "url": { "description": "The registrar's website, or `null` when the record omits it.", "example": "https://registrar.example", "type": [ "string", "null" ] } }, "required": [ "name", "iana_id", "url" ], "type": "object" }, "DomainRegistration": { "properties": { "amount_due": { "description": "What the domain owes now. `null` when nothing is owed.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "auto_renew": { "description": "Whether Whop charges the saved payment method to renew the domain before it expires.", "example": true, "type": "boolean" }, "expires_at": { "description": "When the registration expires unless renewed, as an ISO 8601 timestamp. `null` until it's registered.", "example": null, "type": [ "string", "null" ] }, "method": { "description": "How the domain came to Whop: `registration` when it was bought through Whop, `transfer` when it was moved from another registrar.", "enum": [ "registration", "transfer" ], "example": "transfer", "type": "string" }, "payment_method_id": { "description": "ID of the saved card charged for the domain, prefixed `payt_`. `null` when none is set.", "example": null, "type": [ "string", "null" ] }, "phase": { "description": "Where the registration is: awaiting payment, ordering at the registrar, transferring from another registrar, delegating DNS to Whop, held, expired, or releasing.", "enum": [ "awaiting_payment", "ordering", "transferring", "delegating", "held", "expired", "failed", "releasing" ], "example": "awaiting_payment", "type": "string" }, "purchase_url": { "description": "Link to pay what the domain owes now: its registration or transfer, or a yearly renewal. `null` when nothing is owed.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "renewal_price": { "description": "What each yearly renewal costs at the registrar's current price. Set when the response is a single domain; `null` in lists, while the domain is being released, or when the price can't be read right now.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "state": { "description": "How far registering and keeping the domain has got.", "enum": [ "pending", "ready", "action_required", "releasing" ], "example": "pending", "type": "string" } }, "required": [ "state", "phase", "expires_at", "auto_renew", "payment_method_id", "purchase_url", "amount_due", "renewal_price", "method" ], "type": "object" }, "DomainStats": { "properties": { "unique_visitors_last_7_days": { "description": "People who viewed a page on the domain with the Whop pixel in the last 7 days, refreshed hourly.", "example": 0, "type": "integer" } }, "required": [ "unique_visitors_last_7_days" ], "type": "object" }, "DomainTransfer": { "properties": { "code": { "description": "The code that takes the domain. For an `internal` move it starts `whop_dt_`, and the receiving Whop account enters it as `registration.auth_code` when it creates or updates the domain. Returned when the response is a single domain and you can manage it; `null` otherwise.", "type": [ "string", "null" ] }, "destination": { "description": "Where the domain is moving. `internal` is another Whop account.", "enum": [ "internal" ], "example": "internal", "type": "string" }, "state": { "description": "`ready` while the code waits to be used. `pending` once it has: Whop removes the domain's email, Apple Pay and pixel from this account, then moves the registration and removes the domain from this account.", "enum": [ "ready", "pending" ], "example": "ready", "type": "string" } }, "required": [ "destination", "state", "code" ], "type": "object" }, "DomainVerification": { "properties": { "state": { "description": "How far proving verification has got.", "enum": [ "pending", "ready", "action_required", "releasing" ], "example": "pending", "type": "string" }, "verification_expires_at": { "description": "When an unproven claim is removed, 48 hours after it was made, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "state", "verification_expires_at" ], "type": "object" }, "DomainWebsite": { "properties": { "app": { "description": "The app the domain serves. `null` until you choose one; the domain shows a placeholder page meanwhile.", "oneOf": [ { "$ref": "#/components/schemas/DomainWebsiteApp" }, { "type": "null" } ] }, "state": { "description": "How far serving the website has got.", "enum": [ "pending", "ready", "action_required", "releasing" ], "example": "pending", "type": "string" } }, "required": [ "state", "app" ], "type": "object" }, "DomainWebsiteApp": { "properties": { "base_url": { "description": "The production base URL where the app is hosted. `null` if no base URL is configured or the domain isn't yours.", "example": "https://domains-spec-site.whop.site", "type": [ "string", "null" ] }, "id": { "description": "App ID, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "base_url" ], "type": "object" }, "EconomicIntelligence": { "properties": { "account_id": { "description": "ID of the account this recommendation is for, prefixed `biz_`, or null for personal onboarding.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "acknowledged_at": { "description": "When the executed run was first marked as seen, as an ISO 8601 timestamp, or `null` if it has not been.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "action_type": { "description": "Type of action recommended, or `null` when no type is assigned. New values may be added; handle unknown types gracefully.", "example": "cut_losing_ad_spend", "type": [ "string", "null" ] }, "ai_chat_id": { "description": "The chat that ran the recommendation, shown only to the user who ran it, or `null` otherwise.", "example": "aich_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "created_at": { "description": "When the recommendation was created, as an ISO 8601 timestamp, or null for an unsaved recommendation.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "executed_at": { "description": "When the recommendation was carried out, as an ISO 8601 timestamp, or `null` if it has not been.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "expected_tool_calls": { "items": { "$ref": "#/components/schemas/EconomicIntelligenceOperation", "description": "Expected API operations or tools, in execution order, or null when no execution plan was recorded." }, "type": [ "array", "null" ] }, "id": { "description": "Recommendation ID, prefixed `reca_`, or `create_business` for an unsaved setup recommendation. Authenticate and list again before executing an unsaved recommendation.", "example": "reca_xxxxxxxxxxxxxx", "type": "string" }, "input": { "description": "What you requested, in your own words, or `null` for recommendations generated without your input.", "example": "more sales from ads", "type": [ "string", "null" ] }, "inputs": { "items": { "$ref": "#/components/schemas/EconomicIntelligenceInput", "description": "Decisions this recommendation leaves to you. Pick one option for each before it runs, or write your own for a `whop_ai` recommendation; empty when there is nothing to decide." }, "type": "array" }, "prompt": { "description": "Step-by-step instructions for Whop AI, or `null` when no instructions are available.", "example": "Create a 20% off promo code for my members.", "type": [ "string", "null" ] }, "reasoning": { "description": "Evidence and metrics supporting the recommendation, or `null` when no reasoning was provided.", "example": "Capped 9 of 14 days.", "type": [ "string", "null" ] }, "result_url": { "description": "Where to view what the run produced, such as the published website or created product, or `null` when the result is only in the chat.", "example": "https://atlas.whop.site/", "type": [ "string", "null" ] }, "run_by_user_id": { "description": "The user who started the run, prefixed `user_`, or `null` if it has not run or was started without a user, such as with an API key.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "run_ended_at": { "description": "When the run ended, whether executed or incomplete, as an ISO 8601 timestamp, or `null` if it has not ended.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "run_started_at": { "description": "When the run started, by Whop AI or the recommendation's API calls, as an ISO 8601 timestamp, or `null` if it has not run.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "sentiment": { "description": "How the user rated this recommendation, or `null` if they have not rated it", "enum": [ "positive", "negative", null ], "example": "negative", "type": [ "string", "null" ] }, "status": { "description": "`queued` when awaiting generation; `pending` while generating; `ready` when available to run; `running` while Whop AI or the recommendation's API calls carry it out; `executed` when carried out; `incomplete` when the run ended without carrying it out; `superseded` when rejected or replaced.", "enum": [ "queued", "pending", "ready", "running", "executed", "incomplete", "superseded" ], "example": "executed", "type": "string" }, "superseded_at": { "description": "When the recommendation was rejected or replaced, as an ISO 8601 timestamp, or `null` if neither has occurred.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "target_url": { "description": "Website URL selected for pixel setup, or `null` when no website was captured for this recommendation.", "example": "https://example.com/join", "type": [ "string", "null" ] }, "title": { "description": "Recommended action and its expected benefit, or `null` until generated.", "example": "Move $180 from 3 dead ad groups into BATCH#3, +1.7x return", "type": [ "string", "null" ] }, "user_feedback": { "description": "The user's written feedback, or `null` if they have not provided any.", "example": "They already do this", "type": [ "string", "null" ] } }, "required": [ "id", "account_id", "action_type", "title", "prompt", "reasoning", "expected_tool_calls", "inputs", "input", "status", "executed_at", "superseded_at", "run_started_at", "run_ended_at", "run_by_user_id", "result_url", "ai_chat_id", "created_at", "sentiment", "user_feedback", "acknowledged_at" ], "type": "object" }, "EconomicIntelligenceInput": { "properties": { "answer": { "description": "What the run used: one of the options, or your own text for a `whop_ai` recommendation. `null` until a run starts.", "example": null, "type": [ "string", "null" ] }, "id": { "description": "Identifies the input when you answer it.", "example": "audience", "type": "string" }, "label": { "description": "What you are choosing, such as the daily ad budget.", "example": "Guide audience", "type": "string" }, "options": { "items": { "description": "Three suggested values, strongest first. You can answer with one of them, or with your own text for a `whop_ai` recommendation.", "example": "Daily drivers", "type": "string" }, "type": "array" }, "template": { "description": "A plan sentence with one {answer} blank to fill with the selected answer.", "example": "Guide audience: {answer}", "type": "string" } }, "required": [ "id", "label", "template", "options", "answer" ], "type": "object" }, "EconomicIntelligenceOperation": { "properties": { "description": { "description": "Concise description of the operation and affected resource, or null for older recommendations.", "example": "Increase the summer campaign budget", "type": [ "string", "null" ] }, "tool_name": { "description": "API operation or assistant tool name.", "example": "updateAdCampaign", "type": "string" } }, "required": [ "tool_name", "description" ], "type": "object" }, "EmailAddress": { "properties": { "account_id": { "description": "ID of the account the address belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "address": { "description": "The full address in lowercase, such as support@example.com.", "example": "marcus@shinetime.example", "type": "string" }, "created_at": { "description": "When the address was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "domain_id": { "description": "ID of the domain the address is on, prefixed `dom_`.", "example": "whopappdomain0000001", "type": "string" }, "id": { "description": "Email address ID, prefixed `emaddr_`.", "example": "emaddr_xxxxxxxxxxxxxx", "type": "string" }, "password": { "description": "The password mail apps sign in to the mailbox with over IMAP and SMTP, using the address as the username. `null` unless you can use the mailbox: you own it, or nobody owns it and you have `email:read` and `email:send`.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "updated_at": { "description": "When the address was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user_id": { "description": "ID of the team member who owns the mailbox, prefixed `user_`. Only they can read it or send from it. `null` when the whole account shares it.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "address", "account_id", "domain_id", "user_id", "password", "created_at", "updated_at" ], "type": "object" }, "EmbedTypes": { "description": "The type of embed for a lesson", "enum": [ "youtube", "loom" ], "type": "string" }, "Entry": { "description": "An entry represents a user's signup for a waitlisted plan.", "properties": { "created_at": { "description": "The datetime the entry was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "custom_field_responses": { "description": "The list of responses collected from the user when submitting their waitlist entry.", "items": { "description": "The response from a custom field on checkout", "properties": { "answer": { "description": "The response a user gave to the specific question or field.", "type": "string" }, "id": { "description": "The unique identifier for the custom field response.", "example": "cfrp_xxxxxxxxxxxxx", "type": "string" }, "question": { "description": "The question asked by the custom field", "type": "string" } }, "required": [ "id", "question", "answer" ], "type": "object" }, "type": [ "array", "null" ] }, "id": { "description": "The unique identifier for the entry.", "example": "entry_xxxxxxxxxxxx", "type": "string" }, "plan": { "description": "The waitlisted plan that this entry is a signup for.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "product": { "description": "The product associated with this entry's waitlisted plan. Null if the plan is not tied to a product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "status": { "$ref": "#/components/schemas/EntryStatus", "description": "The current status of the waitlist entry (e.g., drafted, pending, approved, denied)." }, "user": { "description": "The user who submitted this waitlist entry.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": "object" } }, "required": [ "id", "plan", "product", "status", "user", "created_at", "custom_field_responses" ], "type": "object" }, "EntryStatus": { "description": "The status of an entry to a waitlist.", "enum": [ "drafted", "pending", "approved", "denied", "any" ], "type": "string" }, "Experience": { "description": "An experience is a feature or content module within a product, such as a chat, course, or custom app.", "properties": { "app": { "description": "The app that powers this experience, defining its interface and behavior.", "properties": { "icon": { "description": "The icon image for this app, displayed on the app store, product pages, checkout, and as the default icon for experiences using this app.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the app.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this app shown on the app store and in experience navigation. Maximum 30 characters.", "example": "Courses", "type": "string" } }, "required": [ "id", "name", "icon" ], "type": "object" }, "company": { "description": "The company that owns this experience.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the experience was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "The custom logo image for this experience. Null if no custom logo has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "is_public": { "description": "Whether this experience is publicly visible to all users, including those without a membership.", "type": "boolean" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" }, "order": { "description": "The sort position of this experience within its section. Lower values appear first. Null if no position has been set.", "example": "123.45", "type": [ "string", "null" ] }, "products": { "description": "The list of products this experience is attached to, which determines which customers have access. Empty if the experience is only visible to authorized company team members.", "items": { "description": "A product is a digital good or service sold on Whop. Products contain plans for pricing and experiences for content delivery.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "route": { "description": "URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "route", "title" ], "type": "object" }, "type": "array" } }, "required": [ "id", "name", "order", "is_public", "created_at", "app", "image", "company", "products" ], "type": "object" }, "ExperienceAccessLevels": { "description": "The different access levels for experiences (PUBLIC IS NEVER USED ANYMORE).", "enum": [ "public", "private" ], "type": "string" }, "ExperienceListItem": { "description": "An experience is a feature or content module within a product, such as a chat, course, or custom app.", "properties": { "app": { "description": "The app that powers this experience, defining its interface and behavior.", "properties": { "icon": { "description": "The icon image for this app, displayed on the app store, product pages, checkout, and as the default icon for experiences using this app.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the app.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of this app shown on the app store and in experience navigation. Maximum 30 characters.", "example": "Courses", "type": "string" } }, "required": [ "id", "name", "icon" ], "type": "object" }, "company": { "description": "The company that owns this experience.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "created_at": { "description": "The datetime the experience was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "The custom logo image for this experience. Null if no custom logo has been uploaded.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "is_public": { "description": "Whether this experience is publicly visible to all users, including those without a membership.", "type": "boolean" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" }, "order": { "description": "The sort position of this experience within its section. Lower values appear first. Null if no position has been set.", "example": "123.45", "type": [ "string", "null" ] } }, "required": [ "id", "name", "order", "is_public", "created_at", "app", "image", "company" ], "type": "object" }, "ExperienceNotificationPreference": { "properties": { "level": { "description": "What the user is notified about in the experience: `all` notifications, only `mentions`, or `nothing`.", "enum": [ "all", "mentions", "nothing" ], "example": "all", "type": "string" }, "object": { "description": "The type of object. Always `experience_notification_preference`.", "enum": [ "experience_notification_preference" ], "example": "experience_notification_preference", "type": "string" }, "scope": { "$ref": "#/components/schemas/NotificationPreferenceScope", "description": "What the preference applies to. Echo it back to `PATCH /users/me/preferences/notifications` to change this preference." } }, "required": [ "object", "scope", "level" ], "type": "object" }, "Experiment": { "properties": { "account_id": { "description": "Owning account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "assignment_seed": { "description": "Assignment hashes UTF-8 seed + subject ID with CRC32 modulo 100 and selects the stored end-exclusive range.", "example": "checkout_redesign_v21768435200", "type": "string" }, "bucket_by": { "description": "Randomization unit — `user` buckets each user independently, `account` buckets whole accounts (every user of an account gets the same arm). `null` for feature flags.", "enum": [ "user", "account", "anonymous" ], "example": "user", "nullable": true, "type": "string" }, "configuration_revision": { "description": "Revision of the serving configuration. Increments on every configuration change, so a cached definition with a lower revision is stale. Does not change the assignment seed.", "example": 1, "type": "integer" }, "control": { "properties": { "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "nullable": true } }, "type": "object" }, "created_at": { "description": "When the experiment was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "nullable": true, "type": "string" }, "created_by": { "description": "ID of the user who created the experiment, prefixed `user_`. `null` for experiments created before creators were recorded.", "example": "user_xxxxxxxxxxxxxx", "nullable": true, "type": "string" }, "ended_at": { "description": "When the experiment stopped collecting data, as an ISO 8601 timestamp. `null` while still running.", "example": "2026-01-01T12:00:00.000Z", "nullable": true, "type": "string" }, "feature_flag_only": { "description": "`true` when this was created as a feature flag rather than a full experiment. Feature flags share the same evaluation API but do not collect metric results.", "example": false, "nullable": true, "type": "boolean" }, "findings": { "description": "What was learned and why this outcome, recorded when the experiment was ended. `null` until then.", "example": "Treatment lifted conversion 8%", "nullable": true, "type": "string" }, "flag_key": { "description": "Developer-chosen handle referenced from code. Anywhere the API takes an experiment identifier, the `expt_` id and the flag_key are interchangeable.", "example": "checkout_redesign_v2", "type": "string" }, "hypothesis": { "description": "Hypothesis for this experiment. `null` when none is set, and always `null` for feature flags.", "example": "Users will convert more", "nullable": true, "type": "string" }, "id": { "description": "Unique identifier for the experiment, prefixed `expt_`.", "example": "expt_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Human-readable display name.", "example": "Checkout Redesign V2", "type": "string" }, "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "description": "Resource owned by the account that this experiment is bound to, such as an app or product. `null` when unbound. Fixed once the experiment first activates.", "nullable": true }, "started_at": { "description": "When the experiment began collecting data, as an ISO 8601 timestamp. `null` for drafts.", "example": "2026-01-01T12:00:00.000Z", "nullable": true, "type": "string" }, "status": { "description": "Lifecycle state. `draft` — not yet live; `active` — currently running; `paused` — traffic paused; `ended` — concluded.", "enum": [ "draft", "active", "paused", "ended" ], "example": "draft", "type": "string" }, "targeting_rules": { "description": "Rules gating who is in the experiment at all. Conditions within a rule are AND-ed, rules are OR-ed, and `exclude` rules always win. Empty means everyone qualifies.", "items": { "properties": { "conditions": { "description": "Conditions within this rule, all of which must match.", "items": { "properties": { "field": { "description": "Property name to read from the user context. Present when `type` is `property`.", "nullable": true, "type": "string" }, "operator": { "description": "Comparison to apply.", "enum": [ "any", "none", "eq", "neq", "gt", "gte", "lt", "lte" ], "example": "any", "type": "string" }, "type": { "description": "What the condition matches on: the user ID, the account ID, or a named user property.", "enum": [ "user_id", "account_id", "property" ], "example": "user_id", "type": "string" }, "value": { "description": "Value or list of values to match against." } }, "required": [ "type", "operator", "value" ], "type": "object" }, "type": "array" }, "type": { "description": "`include` — users matching this rule qualify; `exclude` — users matching this rule are always excluded, overriding any include rule.", "enum": [ "include", "exclude" ], "example": "include", "type": "string" } }, "required": [ "conditions" ], "type": "object" }, "type": "array" }, "updated_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date_time", "nullable": true, "type": "string" }, "variants": { "description": "Treatment arms. Users outside every arm's allocation form the implicit `control` group. Weights only ever grow and arms are never removed, so a user moves from control into a treatment at most once.", "items": { "properties": { "name": { "description": "Treatment identifier. `control` is reserved — it is the implicit remainder.", "example": "treatment", "type": "string" }, "ranges": { "description": "Granted bucket ranges (1% units, end-exclusive) recording this arm's allocation history. Server-managed; ranges are only ever appended, which is what keeps assignments permanent.", "items": { "example": [ 0, 50 ], "items": { "type": "integer" }, "maxItems": 2, "minItems": 2, "type": "array" }, "type": "array" }, "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "nullable": true }, "weight": { "description": "Percentage of all users assigned to this treatment, 1–100. All weights together sum to at most 100; the remainder is control.", "example": 50, "type": "integer" } }, "required": [ "name", "weight" ], "type": "object" }, "type": "array" }, "winning_arm": { "description": "The treatment that won, set when the experiment was ended. Once set, every evaluation returns this arm to every caller regardless of targeting or allocation, and no further exposures are recorded. `null` means control won — an ended experiment with no winning arm evaluates to `control` for everyone. Always `null` for feature flags, which simply evaluate to disabled once ended.", "example": "treatment", "nullable": true, "type": "string" } }, "required": [ "id", "account_id", "related_resource", "control", "configuration_revision", "assignment_seed", "updated_at", "flag_key", "name", "status", "variants", "targeting_rules" ], "type": "object" }, "ExperimentExposure": { "properties": { "configuration_revision": { "type": "integer" }, "enabled": { "description": "Whether the subject receives a treatment or enabled feature flag.", "example": true, "type": "boolean" }, "experiment_id": { "description": "Unique experiment ID, included for account experiments.", "type": "string" }, "flag_key": { "description": "Present when evaluating a single experiment.", "example": "checkout_redesign", "type": "string" }, "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "nullable": true }, "variant": { "description": "Treatment name, control, or null for an inactive flag or excluded subject.", "example": "treatment", "nullable": true, "type": "string" } }, "required": [ "enabled", "variant" ], "type": "object" }, "ExperimentExposureBatch": { "properties": { "exposures": { "additionalProperties": { "$ref": "#/components/schemas/ExperimentExposure" }, "type": "object" } }, "required": [ "exposures" ], "type": "object" }, "ExperimentResourceReference": { "properties": { "id": { "description": "Referenced resource tag, belonging to the experiment owner.", "type": "string" }, "object": { "enum": [ "app", "app_build", "product", "plan" ], "example": "app", "type": "string" } }, "required": [ "object", "id" ], "type": "object" }, "Export": { "properties": { "created_at": { "description": "When the export was requested, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "download_url": { "description": "A short-lived link to download the finished file. `null` until `status` is `completed`, and again once the export has expired.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "expires_at": { "description": "When the file is deleted and the export moves to `expired`, as an ISO 8601 timestamp. Exports are retained for 30 days.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Export ID, prefixed `exprt_`.", "example": "exprt_xxxxxxxxxxxxxx", "type": "string" }, "progress_percent": { "description": "Estimated completion percentage from 0 to 100.", "example": 0, "type": [ "integer", "null" ] }, "resource": { "description": "The resource that was exported, e.g. `receipts`, `members`, or `payouts`.", "enum": [ "ad_campaigns", "ad_groups", "ads", "apps", "audiences", "bounties", "bounty_submissions", "card_transactions", "checkout_configurations", "disputes", "events", "external_accounts", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "receipt_invoices", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "invoices", "cancelation_reasons", "child_companies", "ledger_lines", "withdrawal_lines" ], "example": "members", "type": "string" }, "status": { "description": "`pending` or `processing` while the file is generated, `completed` when the download is ready, `failed` if it errored, `expired` once the file has been deleted.", "enum": [ "pending", "processing", "completed", "failed", "expired" ], "example": "completed", "type": "string" }, "updated_at": { "description": "When the export last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "resource", "status", "progress_percent", "download_url", "expires_at", "created_at", "updated_at" ], "type": "object" }, "ExternalAccount": { "properties": { "error": { "description": "Why this external account currently can't be used for advertising — a failed share or a Meta-side restriction. Null when the account is healthy.", "example": "You don't have permission to share this account. Ask an admin of its Meta Business Portfolio to grant you full control, then share it again.", "type": [ "string", "null" ] }, "external_id": { "description": "The platform-specific ID for this external account.", "example": "1234567891", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the external account.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of the external account on the platform.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "parent_external_account": { "description": "The external account this one belongs to on the platform, such as the Facebook page that owns an Instagram account. Null when the external account stands on its own, or when it is a partner.", "oneOf": [ { "$ref": "#/components/schemas/ExternalAccountParent" }, { "type": "null" } ] }, "partnership_status": { "description": "Where a partner creator's permission to run partnership ads stands. `pending` until the creator approves it in the Instagram app, `approved` once they have, and `revoked` once it no longer holds. Null when the external account isn't a partner.", "enum": [ null, "pending", "approved", "revoked" ], "example": "pending", "type": [ "string", "null" ] }, "platform": { "description": "The platform the external account exists on.", "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "linkedin", "snapchat", "klaviyo" ], "example": "instagram", "type": "string" }, "profile_picture_url": { "description": "The URL where the profile picture of the external account can be accessed.", "example": "https://shinetime.example/logo.png", "type": [ "string", "null" ] }, "scopes": { "items": { "description": "Capabilities Whop retains specific to this external account. For example, Whop may request the ability to run advertisements that use this external account's identity, reflected by `advertise`. Personal profile connections have no additional Whop scopes.", "example": "advertise", "type": "string" }, "type": "array" }, "url": { "description": "The URL where the external account can be accessed on the platform. Null while a Whop-owned account is still being provisioned.", "example": "https://instagram.com/shinetimedetail", "type": [ "string", "null" ] }, "username": { "description": "The username of the external account on the platform. Null while a Whop-owned account is still being provisioned, and on platforms without usernames, such as Klaviyo.", "example": "shinetimedetail", "type": [ "string", "null" ] }, "verified": { "description": "Whether the external account is verified on the platform.", "example": true, "type": "boolean" } }, "required": [ "id", "platform", "username", "name", "url", "profile_picture_url", "verified", "external_id", "scopes", "partnership_status", "error", "parent_external_account" ], "type": "object" }, "ExternalAccountLeadForm": { "properties": { "completion": { "description": "Screen shown after the form is submitted. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormCompletion" }, { "type": "null" } ] }, "created_at": { "description": "When the form was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "disclaimer": { "description": "Custom consent disclaimer shown before submission. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormDisclaimer" }, { "type": "null" } ] }, "form_type": { "description": "`more_volume` is quickest to submit; `higher_intent` adds a confirmation step before submission.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "id": { "description": "The ad platform's identifier for the form. Use it as lead_gen_form_id on an ad to reuse the form.", "example": "24839", "type": "string" }, "intro": { "description": "Intro screen shown before the questions. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormIntro" }, { "type": "null" } ] }, "locale": { "description": "Language the form is shown in, such as en_US.", "example": "en_US", "type": [ "string", "null" ] }, "name": { "description": "Advertiser-facing form name.", "example": "Ceramic coating quote requests", "type": [ "string", "null" ] }, "privacy_policy_link_text": { "description": "Custom link text for the privacy policy. `null` when the default is used.", "example": "Shine Time privacy policy", "type": [ "string", "null" ] }, "privacy_policy_url": { "description": "Privacy policy URL configured on the form.", "example": "https://shinetime.example/privacy", "type": [ "string", "null" ] }, "question_labels": { "items": { "description": "Labels of the questions the form asks, for preview.", "example": "Email", "type": "string" }, "type": "array" }, "questions": { "items": { "$ref": "#/components/schemas/AdLeadFormQuestion", "description": "Questions on the form, in order." }, "type": "array" } }, "required": [ "id", "name", "locale", "created_at", "form_type", "privacy_policy_url", "privacy_policy_link_text", "question_labels", "questions", "intro", "completion", "disclaimer" ], "type": "object" }, "ExternalAccountParent": { "properties": { "external_id": { "description": "The platform-specific ID for the parent external account.", "example": "555111", "type": [ "string", "null" ] }, "id": { "description": "External account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of the parent external account on the platform.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "platform": { "description": "The platform the parent external account exists on.", "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "linkedin", "snapchat", "klaviyo" ], "example": "facebook", "type": "string" }, "profile_picture_url": { "description": "The URL where the profile picture of the parent external account can be accessed.", "example": "https://shinetime.example/logo.png", "type": [ "string", "null" ] }, "username": { "description": "The username of the parent external account on the platform.", "example": "shinetimedetailing", "type": [ "string", "null" ] }, "verified": { "description": "Whether the parent external account is verified on the platform.", "example": true, "type": "boolean" } }, "required": [ "id", "platform", "username", "name", "profile_picture_url", "verified", "external_id" ], "type": "object" }, "ExternalAccountPost": { "properties": { "call_to_action": { "description": "The post's call-to-action button, for example shop_now (Facebook only; null for Instagram and TikTok).", "enum": [ "learn_more", "shop_now", "sign_up", "subscribe", "get_started", "book_now", "apply_now", "contact_us", "download", "order_now", "buy_now", "get_quote", "message_page", "whatsapp_message", "instagram_message", "call_now", "get_directions", "send_updates", "get_offer", "watch_more", "listen_now", "play_game", "open_link", "no_button", "get_offer_view", "get_event_tickets", "see_menu", "request_time", "event_rsvp", "see_details", "view_instagram_profile", null ], "example": "shop_now", "type": [ "string", "null" ] }, "caption": { "description": "The text accompanying the post, when available.", "example": "Ceramic coating in action", "type": [ "string", "null" ] }, "destination_url": { "description": "The URL the post's call-to-action drives to (Facebook only; null for Instagram and TikTok).", "example": "https://shinetime.example/book", "type": [ "string", "null" ] }, "embed_url": { "description": "An iframe-embeddable URL for previewing the post inline (the platform's player or post embed). For TikTok this is the only preview, since media_url is null; for Facebook and Instagram it supplements media_url. Null when no public embed is available.", "example": "https://www.facebook.com/plugins/post.php", "type": [ "string", "null" ] }, "id": { "description": "The platform's own identifier for the post or media. Use it to reference the post on an ad.", "example": "media_1", "type": "string" }, "media_url": { "description": "The URL of the post's media — the image for image posts, the playable video file for video posts. Null for TikTok, which exposes no raw file (use embed_url). Meta URLs are signed and expire after roughly 24 hours, so don't store them.", "example": "https://shinetime.example/ceramic-coating-reel.mp4", "type": [ "string", "null" ] }, "restrictions": { "items": { "description": "Ways this post can't be used on an ad. `lead_form_ineligible`: post can't be used in lead form ads. `promotion_ineligible`: the platform won't promote this post at all — always present when that's true, alongside a reason code when one is identified. `copyrighted_music`: post uses music the platform does not allow for ads. `messenger_destination`, `instagram_destination`, `whatsapp_destination`: the post's own button opens that chat app, so the post can only run in an ad group that sends people to the same one — always accompanied by `lead_form_ineligible`. Empty when the post has no restrictions.", "enum": [ "lead_form_ineligible", "promotion_ineligible", "copyrighted_music", "messenger_destination", "instagram_destination", "whatsapp_destination" ], "example": "lead_form_ineligible", "type": "string" }, "type": "array" }, "thumbnail_url": { "description": "Poster image for video posts (always set for TikTok, which is video-only); null for image posts, where media_url is already the image.", "example": "https://shinetime.example/ceramic-coating-poster.jpg", "type": [ "string", "null" ] }, "video_id": { "description": "The platform video identifier for engagement audience rules. Null for non-video posts or when unavailable. Facebook video identifiers differ from post identifiers.", "example": "18000000000000000", "type": [ "string", "null" ] } }, "required": [ "video_id", "caption", "id", "media_url", "thumbnail_url", "embed_url", "call_to_action", "destination_url", "restrictions" ], "type": "object" }, "FeeMarkup": { "description": "A fee markup configuration that defines additional charges applied to transactions for a platform's connected accounts.", "properties": { "created_at": { "description": "The datetime the fee markup was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "fee_type": { "$ref": "#/components/schemas/FeeMarkupTypes", "description": "The category of fee this markup applies to." }, "fixed_fee_usd": { "description": "A flat fee charged per transaction, in USD. Ranges from 0 to 50. Null if no fixed fee is configured.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for the fee markup.", "type": "string" }, "notes": { "description": "Internal notes about this fee markup, visible only to administrators. Null if no notes have been added.", "example": "Approved by finance team on 2024-01-15", "type": [ "string", "null" ] }, "percentage_fee": { "description": "A percentage-based fee charged per transaction. Ranges from 0 to 25. Null if no percentage fee is configured.", "example": 6.9, "type": [ "number", "null" ] }, "updated_at": { "description": "The datetime the fee markup was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "fee_type", "percentage_fee", "fixed_fee_usd", "notes", "created_at", "updated_at" ], "type": "object" }, "FeeMarkupListItem": { "description": "A fee markup configuration that defines additional charges applied to transactions for a platform's connected accounts.", "properties": { "created_at": { "description": "The datetime the fee markup was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "fee_type": { "$ref": "#/components/schemas/FeeMarkupTypes", "description": "The category of fee this markup applies to." }, "fixed_fee_usd": { "description": "A flat fee charged per transaction, in USD. Ranges from 0 to 50. Null if no fixed fee is configured.", "example": 6.9, "type": [ "number", "null" ] }, "id": { "description": "The unique identifier for the fee markup.", "type": "string" }, "notes": { "description": "Internal notes about this fee markup, visible only to administrators. Null if no notes have been added.", "example": "Approved by finance team on 2024-01-15", "type": [ "string", "null" ] }, "percentage_fee": { "description": "A percentage-based fee charged per transaction. Ranges from 0 to 25. Null if no percentage fee is configured.", "example": 6.9, "type": [ "number", "null" ] }, "updated_at": { "description": "The datetime the fee markup was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "fee_type", "percentage_fee", "fixed_fee_usd", "notes", "created_at", "updated_at" ], "type": "object" }, "FeeMarkupTypes": { "description": "The types of fee markups that can be configured", "enum": [ "crypto_withdrawal_markup", "rtp_withdrawal_markup", "next_day_bank_withdrawal_markup", "bank_wire_withdrawal_markup", "digital_wallet_withdrawal_markup", "transfer_markup", "crypto_deposit_markup", "bank_deposit_markup", "crypto_swap_markup", "payment_markup" ], "type": "string" }, "FeedbackOption": { "properties": { "category": { "description": "The category saved as the membership's `cancel_option` when a member picks this option.", "enum": [ "too_expensive", "switching", "missing_features", "technical_issues", "bad_experience", "unused", "other" ], "example": "too_expensive", "type": "string" }, "id": { "description": "Feedback option ID, prefixed `fo_`. Pass it as `feedback_option_id` when canceling a membership, or back in `feedback_options` to keep the option when changing the list.", "type": "string" }, "label": { "description": "The cancel reason as members see it. Up to 100 characters.", "type": "string" } }, "required": [ "id", "label", "category" ], "type": "object" }, "File": { "properties": { "blurhash": { "description": "BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.", "example": null, "type": [ "string", "null" ] }, "content_type": { "description": "The original file's MIME type, preserved when removed by moderation, e.g. `application/pdf`.", "example": "application/pdf", "type": [ "string", "null" ] }, "created_at": { "description": "When the file was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "duration_seconds": { "description": "Audio or video duration in seconds. Null when unavailable or removed by moderation.", "example": null, "type": [ "number", "null" ] }, "filename": { "description": "The original filename, including its extension.", "example": "evidence.pdf", "type": [ "string", "null" ] }, "height": { "description": "Image or video height in pixels. Null when unavailable or removed by moderation.", "example": null, "type": [ "integer", "null" ] }, "id": { "description": "The file's ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "multipart_chunk_size": { "description": "The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.", "example": 5242880, "type": [ "integer", "null" ] }, "multipart_upload_id": { "description": "The ID of the multipart upload, passed back to `complete`. Present only on create, and only for multipart uploads.", "example": "upload-id", "type": [ "string", "null" ] }, "multipart_upload_urls": { "items": { "$ref": "#/components/schemas/FileMultipartUrl", "description": "The presigned URL for each part. Present only on create, and only for multipart uploads." }, "type": [ "array", "null" ] }, "object": { "description": "The type of this object, always `file`.", "example": "file", "type": "string" }, "removed_by_moderation": { "description": "Whether moderation removed the file. When true, `url` serves a replacement image; filename, size, and content type still describe the original file.", "example": false, "type": "boolean" }, "size": { "description": "The file size in bytes. `null` until the upload has finished.", "example": 9670, "type": [ "integer", "null" ] }, "upload_headers": { "description": "Headers to send with the upload PUT. Present only on create.", "example": {}, "type": "object" }, "upload_status": { "description": "Where the file is in its upload lifecycle.", "enum": [ "pending", "processing", "ready", "failed" ], "example": "pending", "type": "string" }, "upload_url": { "description": "Presigned URL to PUT the file's bytes to. Present only on create, and only for single-part uploads.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/application.pdf", "type": [ "string", "null" ] }, "url": { "description": "A URL to download the file: a permanent CDN URL for public files, a signed expiring URL for private ones. Null until the upload has finished; a replacement image URL when removed by moderation.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/audio/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "visibility": { "description": "`public` files are served via an unsigned CDN URL; `private` files via a signed, expiring URL.", "enum": [ "public", "private" ], "example": "private", "type": "string" }, "waveform_url": { "description": "Audio waveform URL. Null when unavailable or removed by moderation.", "example": null, "type": [ "string", "null" ] }, "width": { "description": "Image or video width in pixels. Null when unavailable or removed by moderation.", "example": null, "type": [ "integer", "null" ] } }, "required": [ "object", "id", "filename", "content_type", "size", "url", "removed_by_moderation", "upload_status", "visibility", "created_at", "width", "height", "blurhash", "duration_seconds", "waveform_url" ], "type": "object" }, "FileMultipartUrl": { "properties": { "part_number": { "description": "The 1-based index of this part within the multipart upload.", "example": 1, "type": "integer" }, "url": { "description": "The presigned URL to PUT this part's bytes to.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/application.pdf", "type": "string" } }, "required": [ "part_number", "url" ], "type": "object" }, "FileVisibility": { "description": "Controls whether an uploaded file is publicly accessible or requires authentication to access.", "enum": [ "public", "private" ], "type": "string" }, "FinancingAccessChange": { "properties": { "account_id": { "description": "The merchant account whose financing access changed, prefixed biz_.", "type": "string" }, "disabled_at": { "description": "When the payment methods were disabled, as an ISO 8601 timestamp.", "type": "string" }, "disabled_payment_methods": { "items": { "description": "BNPL payment methods disabled on this account.", "enum": [ "addi", "affirm", "afterpay_clearpay", "alma", "billie", "capchase_pay", "claritypay", "flex_pay", "klarna", "kriya", "kueski", "mondu", "oney", "oney_3x", "oney_4x", "scalapay", "sequra", "sezzle", "splitit", "sunbit", "tabby", "tamara", "zip" ], "example": "addi", "type": "string" }, "type": "array" }, "object": { "description": "The type of this object.", "enum": [ "financing_access_change" ], "example": "financing_access_change", "type": "string" }, "provider": { "description": "The BNPL provider whose dispute rate triggered enforcement. Other payment methods may also lose access.", "enum": [ "klarna", "splitit", "afterpay_clearpay", "zip", "sezzle" ], "example": "klarna", "type": "string" }, "reason": { "description": "Why financing access was removed.", "enum": [ "high_dispute_rate" ], "example": "high_dispute_rate", "type": "string" } }, "required": [ "object", "reason", "account_id", "provider", "disabled_payment_methods", "disabled_at" ], "type": "object" }, "FinancingApplication": { "properties": { "account_id": { "description": "The ID of the merchant account applying for payment financing, starting with biz_.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "created_at": { "description": "When the application was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "feedback": { "description": "Public review feedback when more information is requested or the application is denied. Internal notes are never included.", "example": null, "type": [ "string", "null" ] }, "id": { "description": "The financing application ID, starting with inrq_.", "example": "inrq_xxxxxxxxxxxxxx", "type": "string" }, "requirements": { "items": { "$ref": "#/components/schemas/FinancingRequirement", "description": "Merchant requirements and saved answers. Present on individual application responses, omitted from lists. Acceptance is collected separately on submit." }, "type": "array" }, "status": { "description": "The application's review state. Approval does not by itself indicate that financing payment methods are enabled on the account.", "enum": [ "requires_collection", "awaiting_review", "completed", "approved", "denied" ], "example": "requires_collection", "type": "string" }, "terms": { "$ref": "#/components/schemas/FinancingTerms", "description": "Current terms to present before submitting. Present on individual application responses." }, "updated_at": { "description": "When the application was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "account_id", "status", "created_at", "updated_at" ], "type": "object" }, "FinancingProvider": { "properties": { "action": { "description": "The merchant action that turns this provider on when `status` is `needs_action`; `null` otherwise.", "enum": [ "verify_business", "add_payout_account", null ], "example": "verify_business", "type": [ "string", "null" ] }, "currencies": { "items": { "$ref": "#/components/schemas/FinancingProviderCurrency", "description": "The currencies checkout charges this provider in for this account, each with its maximum payment." }, "type": "array" }, "details": { "description": "The dispute rates behind a `dispute_rate_near_limit` or `dispute_rate_exceeded` reason; `null` for every other reason.", "oneOf": [ { "$ref": "#/components/schemas/FinancingProviderDetails" }, { "type": "null" } ] }, "provider": { "description": "The financing provider.", "enum": [ "afterpay_clearpay", "zip", "sezzle", "tabby", "tamara", "kueski", "addi", "klarna", "oney", "splitit", "claritypay", "flex_pay" ], "example": "zip", "type": "string" }, "provider_reviewed_at": { "description": "When the provider received or decided on this account, as an ISO 8601 timestamp. Set only for providers that review merchants themselves (Splitit); `null` otherwise.", "example": null, "type": [ "string", "null" ] }, "reason": { "description": "Why the provider has this status, when known. On `active` it is `dispute_rate_near_limit` when the provider is close to being turned off. On `inactive` it names what keeps it off, including `not_included` when the account's approval doesn't cover it, `turned_off` when it was switched off after setup, `setup_failed`, and `declined` when the provider turned the account down without a reason Whop recognizes. More reasons may be added.", "enum": [ "account_not_supported", "payin_account_required", "payment_account_required", "processor_connection_required", "minimum_volume_not_met", "turned_off_in_checkout_settings", "provider_review", "dispute_rate_near_limit", "dispute_rate_exceeded", "whop_risk_control", "not_included", "turned_off", "declined", "setup_failed", "payout_account_country_unsupported", "seller_country_unsupported", "approved_dispute_rate_too_high", "restricted_industry", "income_claims", "missing_store_details", "duplicate_account", "invalid_website", "unspecified", null ], "example": "payin_account_required", "type": [ "string", "null" ] }, "status": { "description": "Where the provider stands for this account: `eligible` (included if the account applies), `needs_action` (waiting on the merchant, see `action`), `in_review` (waiting on Whop's review, or on the provider's own when `reason` is `provider_review`), `active` (offered at checkout), or `inactive` (not offered, see `reason`).", "enum": [ "eligible", "needs_action", "in_review", "active", "inactive" ], "example": "inactive", "type": "string" } }, "required": [ "provider", "status", "currencies", "reason", "action", "details", "provider_reviewed_at" ], "type": "object" }, "FinancingProviderCurrency": { "properties": { "currency": { "description": "A currency checkout charges this provider in, lowercase ISO 4217.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "aud", "type": "string" }, "max_amount": { "description": "The largest payment checkout offers this provider for in this currency. Null when checkout sets no maximum, or when the provider sets each merchant's limit itself (Splitit).", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "currency", "max_amount" ], "type": "object" }, "FinancingProviderDetails": { "properties": { "dispute_rate": { "description": "The account's dispute rate as a fraction, for example 0.012 for 1.2%.", "type": [ "number", "null" ] }, "dispute_rate_limit": { "description": "The dispute rate, as a fraction, at which the provider is turned off or held back.", "type": [ "number", "null" ] }, "source_provider": { "description": "The provider whose dispute rate caused this change, or `null` when it was this provider's own rate.", "enum": [ "klarna", "splitit", "afterpay_clearpay", "zip", "sezzle", null ], "example": "klarna", "type": [ "string", "null" ] } }, "required": [ "dispute_rate", "dispute_rate_limit", "source_provider" ], "type": "object" }, "FinancingRequirement": { "properties": { "accepted_file_formats": { "items": { "description": "Accepted document formats, such as pdf or jpeg.", "type": "string" }, "type": "array" }, "field": { "description": "The information requested, such as business_description or processing_statements.", "example": "business_description", "type": "string" }, "file_collection_type": { "description": "Whether the requirement accepts no file, one file, or multiple files.", "enum": [ "none", "single", "multi" ], "example": "none", "type": "string" }, "files": { "items": { "$ref": "#/components/schemas/File", "description": "Files attached to this requirement, including expiring download URLs." }, "type": "array" }, "id": { "description": "Requirement ID to use when updating this application's answers.", "example": "inrqi_xxxxxxxxxxxxxx", "type": "string" }, "max_file_size": { "description": "Maximum size in bytes for each uploaded document.", "example": 20971520, "type": "integer" }, "minimum_length": { "description": "Minimum characters per text answer, when specified.", "example": 100, "type": [ "integer", "null" ] }, "money": { "description": "Saved maximum product price in its original currency. Null when unanswered or the saved legacy answer is invalid.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "options": { "items": { "description": "Allowed dropdown values. Empty when the answer is not an enumeration.", "type": "string" }, "type": "array" }, "required": { "description": "Whether this requirement must be completed before submission.", "example": true, "type": "boolean" }, "text_collection_type": { "description": "Whether the requirement accepts no text, one value, or multiple values.", "enum": [ "none", "single", "multi" ], "example": "single", "type": "string" }, "text_format": { "description": "Expected text format. max_product_price uses money instead of values.", "enum": [ "plain", "url", "email", "phone", "number", "checkbox", "dropdown" ], "example": "plain", "type": "string" }, "values": { "items": { "description": "Saved text answers. Empty for money requirements; read money instead.", "example": "https://shop.example.com/shop", "type": "string" }, "type": "array" } }, "required": [ "id", "field", "required", "text_collection_type", "file_collection_type", "text_format", "values", "money", "files", "minimum_length", "options", "accepted_file_formats", "max_file_size" ], "type": "object" }, "FinancingTerms": { "properties": { "content": { "description": "The exact plain-text contract snapshot covered by this version. Present this content, the policies, and the disclosure before collecting acceptance.", "example": "https://whop.com/splitit-terms/ \n\nWe are a retailer of goods or services that you are seeking to purchase (“us“, “our”, “we” or “Merchant”). This Retail Installment Contract Terms & Conditions (“Agreement”) is between us and you, the cardholder, who is making the purchase (“Buyer”, “you“, “your”).\n\nThese terms are in addition to our normal terms of business, including our Return Policy. By choosing to make this purchase using installments, you agree to be bound by this agreement. These additional terms for payment by installment apply when you select the option of paying for your purchase by installments, using a payment card issued by a credit card issuer (“Issuer”). In order to process card payments by installment, we are using a third party technology service provided by Splitit USA Inc. (“Splitit” or “Service Provider”), but you have not entered into an agreement with Splitit.\n\nHow it Works. By selecting the “Splitit” payment option at the checkout page, you authorize us to put a hold on your payment card for the Total Sale Price (as defined below under xxxxxxxxxxxxxx), however we will only charge the eligible card provided to us over time in the number of payments and amounts that you selected at checkout (we call these payments “xxxxxxxxxxxx“). The date and amount of each Installment is shown at checkout before you complete your purchase and a complete record is emailed to you immediately after you complete your purchase. We will charge the initial payment to your card when your order is completed (or later, if shipment is later, in accordance with the payment schedule). Each subsequent Installment is charged monthly, on the dates shown in the payment schedule presented to you at checkout, until the entire amount due under this Agreement is paid. As further described under the xxxxxxxxxxxxxx section, your credit card is eligible if there is available credit (or balance, in the case of a debit card) to support an xxxxxxxxxxxxx for the Total Sale Price and you are authorized to use the payment card to make the transaction. If we are not able to renew an authorization for the amount you owe by your next Installment due date we may charge your card for the Total Sale Price, less the amount of any xxxxxxxxxxxx you have already paid.\n\nNeither we nor Splitit impose any interest or additional charges on you for selecting this payment option. However, we are required by law to warn you that you may have to pay other taxes or costs that are not imposed by us (such as internet charges, fees and interest imposed by the Issuer, or charges imposed by customs in your country). IN PARTICULAR, PLEASE NOTE, AS INSTALLMENT PAYMENTS ARE BEING CHARGED TO YOUR CARD, YOU MAY BE CHARGED INTEREST AND FEES OR OTHER CHARGES IMPOSED BY YOUR CARD ISSUER UNDER THEIR AGREEMENT WITH YOU. THIS COULD INCLUDE LATE PAYMENT FEES, OVERDRAFT FEES, PERIODIC INTEREST, OR OVER-THE-LIMIT FEES. YOU ARE SOLELY RESPONSIBLE FOR THESE FEES.\n\nxxxxxxxxxxxxxx. If you provide a credit card to make payments, we may obtain an authorization against your credit card for up to the total amount of your purchase (“Total Sale Price”). An “authorization” means that the available credit on your credit card will be reduced by an amount, up to the Total Sale Price, in order to ensure you have sufficient available credit to make future payments. You will likely not be able to use that amount of your credit line while the authorization remains in place, subject to rules imposed by your Issuer. Even if your Issuer does not restrict the available credit, you must ensure that you have enough available credit to cover the full outstanding amount owed under this Agreement for your purchase at all times.\n\nTo ensure we retain a valid authorization against your credit card, we may need to renew the authorization periodically using the credit card details provided at the time of purchase (or a subsequent credit card you provide). The amount of any new authorization or any reauthorization will equal the current outstanding value of your installment plan. It may take up to 5 days for the amount of the authorization to be reduced after you make a payment. We will notify you by email approximately 24 hours before the authorization is renewed.\n\nIf any authorization we seek to make against your credit card fails, we will contact you by email (using the email address you provided at checkout) to let you know. We may also contact you via SMS to the extent you have authorized us to do so. We will also keep attempting to get approval for the authorization by submitting a request to your payment card periodically for up to 7 days. You can provide us with a different eligible credit card to use for authorizations and xxxxxxxxxxxx via the consumer portal, using the unique link we email to you when you enter into this Agreement (“Portal“). By providing a new credit card, you authorize us to obtain authorizations for the remaining amounts owed under this Agreement, as set forth in this Agreement, and you further authorize us to charge this updated credit card for outstanding xxxxxxxxxxxx owed, when due under this Agreement. You also authorize us to charge or refund your credit card as necessary to correct any errors. If we are not able to renew an authorization for the amount you owe under this Agreement by your next Installment due date, and you do not make an Installment payment by the due date (subject to any applicable grace period) or successfully authorize those amounts on another eligible card, we may charge your credit card for the Total Sale Price, less the amount of any xxxxxxxxxxxx you have already paid.\n\nTHIS AGREEMENT INCLUDES AN ARBITRATION AGREEMENT. IT WILL HAVE A SUBSTANTIAL EFFECT ON YOUR RIGHTS IN THE EVENT OF A DISPUTE UNLESS YOU: (1) OPT OUT WITHIN 30 DAYS OF SIGNING THIS AGREEMENT; OR (2) ARE PROTECTED BY THE MILITARY LENDING ACT. YOU WILL NOT HAVE THE RIGHT TO A JURY TRIAL OR THE RIGHT TO PARTICIPATE IN A CLASS ACTION IN COURT OR IN ARBITRATION.\n\nRight to Stop Payment; Changing your Payment Method: You have a right to stop payment on your selected credit or debit card by writing to our Service Provider by email at support@splitit.com, or by providing a new eligible card in the Portal. You must tell our Service Provider in time for us to receive your request at least 3 business days before your next Installment due date. If you call, we may require you to confirm your request in writing within 14 days after your call. If your credit or debit card is replaced, cancelled, no longer valid, or you wish to use a different card, you must log on to the Portal and provide an eligible card at least 3 business days before your next Installment due date. We may not be able to process your request if we do not receive it in time. If you do not have sufficient available credit or available funds on the new card to process the authorization, we may not accept the card.\n\nIt is your responsibility to ensure that, until the last Installment is paid, the card you present for payment at the time of purchase, or anytime thereafter, remains valid, is not cancelled, and has sufficient available balance or available credit to pay all xxxxxxxxxxxx and to accept authorizations that may be made under this Agreement.\n\nPAYMENT AUTHORIZATION: BY ACCEPTING THIS AGREEMENT, YOU AUTHORIZE US OR OUR SERVICE PROVIDER TO (1) AUTHORIZE YOUR SELECTED CARD FOR UP TO THE TOTAL SALE PRICE AS DESCRIBED ABOVE; (2) CHARGE YOUR SELECTED CARD FOR THE AMOUNT OF YOUR FIRST INSTALLMENT ON OR AFTER THE DATE OF THIS AGREEMENT; (3) CHARGE YOUR SELECTED CARD IN THE AMOUNT OF EACH INSTALLMENT ON EACH INSTALLMENT DUE DATE AS DESCRIBED IN YOUR TRUTH IN LENDING DISCLOSURES AND PAYMENT SCHEDULE; (4) CHARGE YOUR SELECTED CARD FOR THE TOTAL SALE PRICE LESS ANY INSTALLMENTS YOU HAVE ALREADY PAID (A) IN AN EVENT OF DEFAULT (SUBJECT TO ANY NOTICE AND CURE RIGHTS YOU MAY HAVE BY LAW) OR (B) IF YOU CANCEL THIS AGREEMENT AFTER THE TIME PERMITTED BY THIS AGREEMENT; AND (5) CHARGE YOUR SELECTED CARD AS NECESSARY TO CORRECT ANY ERRORS. THIS PAYMENT AUTHORIZATION WILL REMAIN IN FULL FORCE AND EFFECT UNTIL ALL INSTALLMENTS ARE PAID IN FULL OR WE RECEIVE NOTICE THAT YOU REVOKE THIS AUTHORIZATION.\n\nHandling Card Payments and xxxxxxxxxxxxx. We use a third-party technology platform provided by Splitit to keep a record of payments you owe us and we use their platform to process authorizations and payments at the times we have agreed and to send notifications to you. You will see some of the emails say they are “powered by Splitit”. This should help you identify what payments we are contacting you about.\n\nReturns. You may return the goods to us as set forth in our Return Policy.\n\nxxxxxxxxxxxx. You have the right to cancel this Agreement to pay for your purchase using xxxxxxxxxxxx at any time, but once you cancel this Agreement, the Total Sale Price less any amounts already paid will become due in full. To request a cancellation, please contact our Service Provider by email at support@splitit.com. \n\nDefault. Subject to applicable law, which may require that we notify and/or give you a right to cure your default, we may declare you in default under this Agreement for any of the following reasons: (1) you fail to pay any Installment by the due date, and after any applicable grace period; (2) you violate any promise you make to us in this Agreement which significantly impairs your ability to pay or our ability to collect the amounts due under this Agreement; (3) you file for protection under the United States Bankruptcy Code, or become subject to a proceeding which seeks relief from debt; (4) you have made a false or misleading statement about an important matter in connection with this Agreement; (5) you revoke your consent to electronic communications; or (6) you die or become legally incompetent.\n\nxxxxxxxxxxxx of Default. If you are in default of this Agreement, we can require you to pay the remaining amount you owe us under this Agreement immediately, subject to any right you may have to notice of default and to cure such default. We may seek payment of this amount by charging your credit or debit card pursuant to any authorization you provided us under this Agreement. If we refer this Agreement to an attorney who is not our salaried employee for collection, we may require you to pay our reasonable attorneys’ fees and expenses, to the extent permitted by applicable law.\n\nAssignment. You are hereby notified and agree that we may transfer, sell, or assign this Agreement, the xxxxxxxxxxxx, or any associated rights, to a third party, including Splitit or one of its affiliates, without any further notification to you. If we do so, this Agreement will remain in effect and will be binding on and will inure to the benefit of our assign(s). You may not transfer your rights under this Agreement and any attempt to do so will be void.\n\nGoverning law; xxxxxxxxxxxx. This Agreement (and our dealing prior to this Agreement being made) shall be governed by federal law, and to the extent not pre-empted, the laws of the state in which you purchased the goods and services; provided that you are entitled to the benefit of any mandatory consumer protection rules of the country of your primary residence. If any provision of this Agreement or portion thereof is held to be unenforceable, this determination will not affect the remainder of this Agreement.\n\nIndemnity and Limitation of Liability. You agree to indemnify, defend, and hold us, our service providers, and our respective agents, officers, directors, employees and assigns (collectively, the “Indemnified Parties”) harmless from and against any liability, including reasonable attorneys’ fees, related to this Agreement. THE INDEMNIFIED PARTIES WILL NOT BE LIABLE FOR INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES REGARDLESS OF THE FORM OF ACTION AND EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IF WE FAIL TO STOP PAYMENT ON AN ITEM, OR PAY AN ITEM BEARING AN UNAUTHORIZED SIGNATURE, FORGED SIGNATURE, OR FORGED ENDORSEMENT OR ALTERATION, OUR LIABILITY, IF ANY, WILL BE LIMITED TO THE FACE AMOUNT OF THE ITEM. The foregoing limitation of liability will not apply where expressly prohibited by the laws governing this Agreement. This Limitation of Liability section will survive termination of this Agreement.\n\nArbitration Agreement. We are always interested in resolving disputes, claims, or controversies (“Claim”) amicably and efficiently, and most customer concerns can be resolved quickly and to the customer’s satisfaction by contacting us by email through our Service Provider at support@splitit.com or by mail at Splitit USA, Inc., 211 Perimeter Center Pkwy NW, Suite 240, Atlanta, GA 30346. If such efforts prove unsuccessful, you and we agree that all disputes shall be resolved by binding arbitration on an individual basis. A party who intends to seek arbitration must first send to the other, by certified mail, a written Notice of Dispute (“Notice”). The Notice must (a) describe the nature and basis of the Claim and (b) set forth the specific relief sought. If you do not resolve the Claim with us or the Indemnified Party within 60 calendar days after the Notice is received, you, we or the Indemnified Party, as applicable, may commence an arbitration proceeding, as set forth in this section. Arbitration will be conducted by a neutral arbitrator in accordance with the AAA rules and procedures, including the AAA’s Consumer Arbitration Rules (collectively, the “AAA Rules”), as modified by this Arbitration Agreement. The arbitrator must also follow the provisions of this Agreement as a court would. IF ANY PARTY COMMENCES ARBITRATION WITH RESPECT TO A CLAIM, NEITHER YOU, WE, OR THE INDEMNIFIED PARTY WILL HAVE THE RIGHT TO LITIGATE THAT CLAIM IN COURT OR HAVE A JURY TRIAL ON THAT CLAIM, OR TO ENGAGE IN PRE-ARBITRATION DISCOVERY, EXCEPT AS PROVIDED FOR IN THE APPLICABLE AAA RULES. FURTHER, YOU WILL NOT HAVE THE RIGHT TO PARTICIPATE AS A REPRESENTATIVE OR MEMBER OF ANY CLASS OF CLAIMANTS PERTAINING TO THAT CLAIM, AND YOU WILL HAVE ONLY THOSE RIGHTS THAT ARE AVAILABLE IN AN INDIVIDUAL ARBITRATION. THE ARBITRATOR’S DECISION SHALL BE FINAL AND BINDING ON ALL PARTIES, EXCEPT AS PROVIDED IN THE FEDERAL ARBITRATION ACT (the “FAA”). xxxxxxxxxxxxxxx the foregoing, you and we retain the right to pursue in small claims court (or an equivalent state court) any dispute that is within that court’s jurisdiction, so long as the disputes remain in such court and advance only an individual claim for relief. If either you or we fail to submit to binding arbitration of an arbitrable dispute following lawful demand, the party so failing shall bear all costs and expenses incurred by the other in compelling arbitration.\n\nRIGHT TO OPT OUT: If you do not want this Arbitration Agreement to apply, you must notify us within 30 calendar days after you sign the Agreement. You must send the notice in writing to our Service Provider at support@splitit.com. You must provide your name, address and state that you “opt out” of the Arbitration Agreement. Opting out will not affect the other provisions of this Agreement. If you opt out, it will apply only to this Agreement and not any other agreement you may have with us.\n\nTHIS ARBITRATION AGREEMENT DOES NOT APPLY TO YOU IF, AS OF THE DATE OF THIS AGREEMENT, YOU ARE A COVERED BORROWER UNDER THE FEDERAL MILITARY LENDING ACT. IF YOU WOULD LIKE MORE INFORMATION ABOUT WHETHER YOU ARE COVERED BY THE MILITARY LENDING ACT, IN WHICH CASE THIS ARBITRATION PROVISION DOES NOT APPLY TO YOU, PLEASE CONTACT OUR SERVICE PROVIDER AT SUPPORT@SPLITIT.COM\n\nProhibition of Class and xxxxxxxxxxxxxx Actions and Non-xxxxxxxxxxxxxx Relief. YOU AGREE THAT YOU MAY BRING CLAIMS AGAINST US OR INDEMNIFIED PARTY ONLY ON AN INDIVIDUAL BASIS AND NOT AS A PLAINTIFF OR CLASS MEMBER IN ANY PURPORTED CLASS OR REPRESENTATIVE ACTION OR PROCEEDING. UNLESS BOTH YOU AND THE INDEMNIFIED PARTY AGREE OTHERWISE, THE ARBITRATOR MAY NOT CONSOLIDATE OR JOIN MORE THAN ONE PERSON’S OR PARTY’S CLAIMS AND MAY NOT OTHERWISE PRESIDE OVER ANY FORM OF A CONSOLIDATED, REPRESENTATIVE, OR CLASS PROCEEDING. ALSO, THE ARBITRATOR MAY AWARD RELIEF (INCLUDING MONETARY, INJUNCTIVE, AND DECLARATORY RELIEF) ONLY IN FAVOR OF THE INDIVIDUAL PARTY SEEKING RELIEF AND ONLY TO THE EXTENT NECESSARY TO PROVIDE RELIEF NECESSITATED BY THAT PARTY’S INDIVIDUAL CLAIM(S), EXCEPT THAT YOU MAY PURSUE A CLAIM FOR AND THE ARBITRATOR MAY AWARD PUBLIC INJUNCTIVE RELIEF UNDER APPLICABLE LAW TO THE EXTENT REQUIRED FOR THE ENFORCEABILITY OF THIS PROVISION.\n\nNOTICE: ANY HOLDER OF THIS CONSUMER CREDIT CONTRACT IS SUBJECT TO ALL CLAIMS AND DEFENSES WHICH THE DEBTOR COULD ASSERT AGAINST THE SELLER OF GOODS OR SERVICES OBTAINED PURSUANT HERETO OR WITH THE PROCEEDS HEREOF. RECOVERY HEREUNDER BY THE DEBTOR SHALL NOT EXCEED AMOUNTS PAID BY THE DEBTOR HEREUNDER.\n\nUsing your information. You will find a copy of our privacy policy on our website that you can review in connection with your purchase. As Splitit handles our payment requests and instructions for us, they will handle your data and we will pass information between us. You may obtain a copy of Splitit’s Privacy Policy by visiting their website at http://splitit.localsite/legals/splitit-privacy-policy/english/.\n\nWe may share information about our transactions and interactions with you with Splitit and other affiliated companies. We may also share information about our transactions and interactions with unaffiliated third parties in connection with providing this service to you including fraud detection services.\n\nHowever, the law may permit you to instruct us not to share this information with certain third parties. If you do not want us to share this information, you must notify us in writing or by email through our Service Provider at: support@splitit.com. If you email us a notification, you must include your name, address, and the last four digits of your card number used in this transaction so that such a request can be honored. Do not include your full card details in this email.\n\nxxxxxxxxxxxxxx. After completing your purchase, you will see some communications from us saying they are “powered by Splitit”. Splitit will send you an email following the completion of your purchase with details of how you can access information on your payments in a secure, password protected Portal. You are responsible for obtaining and maintaining all telecommunications, mobile, broadband, computer, hardware, software, equipment and services needed to access information about this Agreement or your payment method; view, save and/or print your account documents online; receive any messages or documents you have consented to receive electronically pursuant to the Electronic xxxxxxxxxxxxxx Disclosures and Consent, which is incorporated herein by reference; and for paying all related charges. Some of the communications between you and us or any of our affiliates, agents, assigns and service providers, may be monitored and recorded. By completing this transaction, you consent to this monitoring and recording and you further agree that we and our service providers may from time to time make calls and/or send text messages to you at any telephone number associated with your account, including wireless telephone numbers that could result in charges to you. The manner in which these calls or text messages are made to you may include, but is not limited to, the use of pre-recorded/artificial voice messages and/or automatic telephone dialing system. Your consent may be revoked at any time and by any reasonable means. You further agree that we or our service providers may send e-mails to you at any e-mail address you provide us or use other electronic means of communication to the extent permitted by law. We are not required to act on any instruction or message from you provided by fax, SMS/text, telephone voice mail, message service or answering machine. Whenever this Agreement or applicable law requires or allows you to give us written notice, we will not consider SMS/text or fax to be written notice. You must notify us promptly of any changes to your e-mail address, phone number, mailing address, or other contact information by using the Platform or by emailing our Service Provider at support@splitit.com.\n\nWho to contact about this Agreement. xxxxxxxxxxxx, you may require additional assistance in connection with this Agreement (for example, replacing payment method, number of outstanding xxxxxxxxxxxx, etc.). You may obtain information about your Agreement, including your remaining xxxxxxxxxxxx and your selected payment method through the Portal. You may also contact us through our Service Provider at support@splitit.com for support and information about this Agreement. If you have any questions about the goods and services you purchased under this Agreement, please contact our customer services department through the information provided on our website. We clarify that we hired Splitit to provide certain services and you do not have any agreement with them. Splitit cannot agree to any alternative arrangements other than to allow you to use a different card for the payment of any unpaid Instalments. In addition, Splitit does not have information regarding your relationship with the Issuer and accordingly cannot handle questions related to that arrangement.\n\nState-Specific Disclosures. If you are a resident of any of the following states or jurisdictions, the following provisions for your state will apply, and will supersede any conflicting provisions set forth in this Agreement:\n\nDistrict of Columbia: We certify that the information contained in the Agreement complies with the District of Columbia Municipal Regulations, Title 16, Chapter 1, if applicable.\n\nFlorida: Florida documentary stamp tax required by law has been paid or will be paid directly by us to the Department of Revenue.\n\nHawaii: This contract is covered by Hawaii’s credit sale law, and you have the rights of a buyer under that law. You also may have rights under other state and federal laws.\n\nMaryland: This Agreement will be governed by the laws of the State of Maryland. This Agreement shall be subject to the Credit Grantor Closed End Credit Provisions (Subtitle 10) of the Commercial Law Article of the Maryland Code.\n\nArizona, Delaware, Maine, Minnesota, Nebraska, Ohio, Oklahoma, and Wyoming. No provisions in this Agreement providing for the payment of attorneys’ fees, court costs or collection costs by you shall apply.\n\nNew Hampshire: If you prevail in any action involving this Agreement, we will pay your reasonable attorney’s fees. If you successfully assert a partial defense or set-off, recoupment or counter-claim, the court may limit the fees we can recover.\n\nNew Jersey: (1) The section headings of the Agreement are a table of contents and not contract terms. (2) You agree to pay reasonable attorney’s fees incurred by us in collecting any amount due and payable under this Agreement, in an amount not to exceed 20% of the first $500 owed and 10% of any amount owed in excess of $500, at the time this Agreement is referred to an attorney for collection who is not our salaried employee. (3) Provisions of this Agreement that refer to acts or practices that apply as permitted by, or except as prohibited by, applicable law are applicable to New Jersey residents only to the extent that such acts or practices are permitted by New Jersey or Federal law.\n\nOhio: Ohio laws against discrimination require that all creditors make credit equally available to all creditworthy customers and that credit reporting agencies maintain separate credit histories on each individual upon request. The Ohio Civil Rights Commission administers compliance with this law.\n\nxxxxxxxxxxxx: You agree that reasonable attorney’s fees and costs will be awarded to the prevailing party in any action on this Agreement, regardless of whether the action is instituted by us or you.\n\nVirginia: The service charge does not exceed 0% per annum, computed monthly.\n\nWisconsin: No provision of a marital property agreement, a unilateral statement under Wis. Stat. Ann. §766.59 or a court decree under §786.70 adversely affects our interest unless we, prior to the time the credit is granted, are furnished a copy of the agreement, statement or decree or have actual knowledge of the adverse provision when the obligation to us is incurred.\n\nENTIRE AGREEMENT. Oral agreements or oral commitments to loan money, extend credit, or to forbear from enforcing repayment of a debt may not be enforceable under applicable law. To protect you (as the buyer) and us (as the seller) from misunderstanding or disappointment, you and we acknowledge and agree that this written Agreement is a final expression of the agreement between you and us, and this Agreement may not be contradicted by evidence of prior, contemporaneous, or subsequent oral agreements of the parties. The terms of this Agreement may not be changed except in a writing signed by you and us. No change shall release any party from liability unless otherwise expressly stated in writing.\n\nIMPORTANT: You acknowledge that you had a reasonable opportunity to examine these xxxxxxxxxxxx Terms and Conditions; and that a legible and complete copy was delivered to you. Please notify us within thirty (30) days of the day you accept this Agreement if a complete copy is not delivered to you.\n\nNOTICE TO SHOPPER: (1) DO NOT APPROVE THIS AGREEMENT BEFORE YOU READ IT. (2) DO NOT APPROVE THIS AGREEMENT IF IT CONTAINS ANY BLANK SPACES. (3) YOU ARE ENTITLED TO AN EXACT COPY OF ANY AGREEMENT YOU SIGN. KEEP IT TO PROTECT YOUR LEGAL RIGHTS. (4) YOU HAVE THE RIGHT AT ANY TIME TO PAY IN ADVANCE THE REMAINING INSTALLMENTS DUE UNDER THIS AGREEMENT WITHOUT PENALTY.\n", "type": "string" }, "disclosure": { "description": "Affirmative acceptance statement to present to the merchant.", "example": "I have read and agree to Splitit Retail Installment Contract Terms and Conditions.", "type": "string" }, "fees_url": { "description": "Additional financing fee information.", "example": "https://docs.whop.com/fees", "type": "string" }, "policies": { "items": { "description": "Financing policies to present alongside the contract before collecting acceptance.", "example": "All Resolution Center cases for financed transactions will be automatically refunded.", "type": "string" }, "type": "array" }, "url": { "description": "Source URL for the Splitit contract snapshot.", "example": "https://whop.com/splitit-terms/", "type": "string" }, "version": { "description": "Content fingerprint to pass as merchant_acceptance.terms_version when submitting.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "version", "url", "fees_url", "disclosure", "policies", "content" ], "type": "object" }, "Forum": { "description": "A discussion forum where members can create posts, comment, and react, belonging to an experience.", "properties": { "email_notification_preference": { "$ref": "#/components/schemas/ForumEmailNotificationPreferences", "description": "The email notification setting that controls which posts trigger email alerts. One of: all_admin_posts, only_weekly_summary, none." }, "experience": { "description": "The parent experience that this forum belongs to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "is_public": { "description": "Whether this experience is publicly visible to all users, including those without a membership.", "type": "boolean" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" } }, "required": [ "id", "name", "is_public" ], "type": "object" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "who_can_comment": { "$ref": "#/components/schemas/ForumWhoCanCommentTypes", "description": "The permission level controlling who can comment on posts. One of: everyone, admins." }, "who_can_post": { "$ref": "#/components/schemas/ForumWhoCanPostTypes", "description": "The permission level controlling who can create new posts. One of: everyone, admins." } }, "required": [ "id", "experience", "who_can_post", "who_can_comment", "email_notification_preference" ], "type": "object" }, "ForumEmailNotificationPreferences": { "description": "Email notification preference option for a forum feed", "enum": [ "all_admin_posts", "only_weekly_summary", "none" ], "type": "string" }, "ForumListItem": { "description": "A discussion forum where members can create posts, comment, and react, belonging to an experience.", "properties": { "email_notification_preference": { "$ref": "#/components/schemas/ForumEmailNotificationPreferences", "description": "The email notification setting that controls which posts trigger email alerts. One of: all_admin_posts, only_weekly_summary, none." }, "experience": { "description": "The parent experience that this forum belongs to.", "properties": { "id": { "description": "The unique identifier for the experience.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "is_public": { "description": "Whether this experience is publicly visible to all users, including those without a membership.", "type": "boolean" }, "name": { "description": "The display name of this experience shown to users in the product navigation. Maximum 255 characters.", "example": "Trading Signals Chat", "type": "string" } }, "required": [ "id", "name", "is_public" ], "type": "object" }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "who_can_comment": { "$ref": "#/components/schemas/ForumWhoCanCommentTypes", "description": "The permission level controlling who can comment on posts. One of: everyone, admins." }, "who_can_post": { "$ref": "#/components/schemas/ForumWhoCanPostTypes", "description": "The permission level controlling who can create new posts. One of: everyone, admins." } }, "required": [ "id", "experience", "who_can_post", "who_can_comment", "email_notification_preference" ], "type": "object" }, "ForumPost": { "description": "A post or comment in a forum feed, supporting rich text, attachments, polls, and reactions.", "properties": { "attachments": { "description": "All file attachments on this post, such as images, documents, and videos.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "type": "array" }, "comment_count": { "description": "The total number of direct comments on this post.", "example": 42, "type": "integer" }, "content": { "description": "The body of the forum post in Markdown format. Null if the post is paywalled and the current user does not have access.", "example": "## My Strategy\n\nHere are the key steps...", "type": [ "string", "null" ] }, "created_at": { "description": "The time this post was created, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "is_edited": { "description": "Whether this post has been edited after its initial creation.", "type": "boolean" }, "is_pinned": { "description": "Whether this post is pinned to the top of the forum feed.", "type": "boolean" }, "is_poster_admin": { "description": "Whether the author of this post is an admin of the company that owns the forum.", "type": "boolean" }, "like_count": { "description": "The total number of like reactions this post has received.", "example": 42, "type": [ "integer", "null" ] }, "parent_id": { "description": "The unique identifier of the parent post. Null if this is a top-level post.", "type": [ "string", "null" ] }, "title": { "description": "The headline of the forum post. Null if the post has no title.", "example": "Weekly Market Analysis - February 2025", "type": [ "string", "null" ] }, "updated_at": { "description": "The time this post was last updated, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who authored this forum post.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "view_count": { "description": "The total number of times this post has been viewed by users.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "title", "content", "created_at", "updated_at", "is_edited", "is_poster_admin", "is_pinned", "parent_id", "user", "attachments", "view_count", "like_count", "comment_count" ], "type": "object" }, "ForumPostListItem": { "description": "A post or comment in a forum feed, supporting rich text, attachments, polls, and reactions.", "properties": { "attachments": { "description": "All file attachments on this post, such as images, documents, and videos.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "type": "array" }, "comment_count": { "description": "The total number of direct comments on this post.", "example": 42, "type": "integer" }, "content": { "description": "The body of the forum post in Markdown format. Null if the post is paywalled and the current user does not have access.", "example": "## My Strategy\n\nHere are the key steps...", "type": [ "string", "null" ] }, "created_at": { "description": "The time this post was created, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "is_edited": { "description": "Whether this post has been edited after its initial creation.", "type": "boolean" }, "is_pinned": { "description": "Whether this post is pinned to the top of the forum feed.", "type": "boolean" }, "is_poster_admin": { "description": "Whether the author of this post is an admin of the company that owns the forum.", "type": "boolean" }, "like_count": { "description": "The total number of like reactions this post has received.", "example": 42, "type": [ "integer", "null" ] }, "parent_id": { "description": "The unique identifier of the parent post. Null if this is a top-level post.", "type": [ "string", "null" ] }, "title": { "description": "The headline of the forum post. Null if the post has no title.", "example": "Weekly Market Analysis - February 2025", "type": [ "string", "null" ] }, "updated_at": { "description": "The time this post was last updated, as a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who authored this forum post.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "view_count": { "description": "The total number of times this post has been viewed by users.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "title", "content", "created_at", "updated_at", "is_edited", "is_poster_admin", "is_pinned", "parent_id", "user", "attachments", "view_count", "like_count", "comment_count" ], "type": "object" }, "ForumPostVisibilityTypes": { "description": "The visibility types for forum posts", "enum": [ "members_only", "globally_visible" ], "type": "string" }, "ForumWhoCanCommentTypes": { "description": "Who can comment on a forum feed", "enum": [ "everyone", "admins" ], "type": "string" }, "ForumWhoCanPostTypes": { "description": "Who can post on a forum feed", "enum": [ "everyone", "admins" ], "type": "string" }, "FriendlyReceiptStatus": { "description": "The friendly status of a payment. This is a derived status that provides a human-readable summary of the payment state, combining the underlying status and substatus fields.", "enum": [ "succeeded", "requires_capture", "pending", "failed", "blocked", "past_due", "canceled", "price_too_low", "uncollectible", "refunded", "auto_refunded", "partially_refunded", "dispute_warning", "dispute_needs_response", "dispute_warning_needs_response", "resolution_needs_response", "dispute_under_review", "dispute_warning_under_review", "resolution_under_review", "dispute_won", "dispute_warning_closed", "resolution_won", "dispute_lost", "dispute_closed", "resolution_lost", "drafted", "incomplete", "unresolved", "open_dispute", "open_resolution" ], "example": "succeeded", "type": "string" }, "FunnelComparison": { "anyOf": [ { "properties": { "baseline": { "description": "The reference group's name.", "type": "string" }, "difference_confidence_interval": { "$ref": "#/components/schemas/FunnelConfidenceInterval", "description": "Adjusted Wald interval for the difference in percentage points, with Bonferroni correction across comparisons." }, "difference_percentage_points": { "description": "This group's conversion percentage minus the baseline's.", "type": "number" }, "relative_lift_percent": { "description": "Relative conversion improvement in percent; null if baseline conversion is zero.", "nullable": true, "type": "number" } }, "required": [ "baseline", "difference_percentage_points", "relative_lift_percent", "difference_confidence_interval" ], "type": "object" }, { "type": "null" } ], "description": "Funnel only. Present when compare_to is supplied; null on the baseline itself. Comparisons are descriptive and do not establish causation." }, "FunnelConfidenceInterval": { "anyOf": [ { "properties": { "lower": { "description": "The lower confidence bound, in percent or percentage points for a difference.", "type": "number" }, "upper": { "description": "The upper confidence bound, in percent or percentage points for a difference.", "type": "number" } }, "required": [ "lower", "upper" ], "type": "object" }, { "type": "null" } ] }, "FunnelStep": { "additionalProperties": false, "properties": { "app_build_id": { "description": "The Whop app build ID attached to the event. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "app_id": { "description": "The event's app id. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "browser": { "description": "The event's browser. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "city": { "description": "The event's city. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "country": { "description": "The event's country. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "custom_name": { "description": "The custom event name. Requires event=pixel.custom. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "device": { "description": "The event's device. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "event": { "description": "The event name, such as pixel.page, pixel.custom, experiment.exposure, or payment.completed. Exactly one event per step.", "maxLength": 1024, "type": "string" }, "experiment_id": { "description": "An experiment ID owned by account_id. Requires event=experiment.exposure. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "hostname": { "description": "The event's hostname. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "os": { "description": "The event's os. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "page": { "description": "The URL pathname. Use * to match zero or more characters, including slashes. Other characters match literally. Missing pages do not match. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "plan_id": { "description": "The plan ID attached to the event. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "product_id": { "description": "The product ID attached to the event. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "source": { "description": "The Whop ad-click source of this page view, not conversion attribution. Use whop:* for any Whop ad click, whop::* for a campaign, or whop::: for an exact ad. Only ad-click page-view events support source. With breakdown_by=source, trailing :* levels select campaign, ad-group, or ad detail. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "utm_source": { "description": "The event's utm source. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" }, "variant": { "description": "The exposed variant name. Requires event=experiment.exposure. Comma-separated alternatives are ORed; different filters are ANDed.", "maxLength": 1024, "type": "string" } }, "required": [ "event" ], "type": "object" }, "FunnelStepResult": { "properties": { "conversion_rate": { "description": "The percentage of first-step entrants reaching this step; null when there are no entrants.", "example": 100.0, "nullable": true, "type": "number" }, "count": { "description": "The number of distinct people reaching this step.", "example": 100, "type": "integer" }, "step": { "description": "The one-based step number.", "example": 1, "type": "integer" } }, "required": [ "step", "count", "conversion_rate" ], "type": "object" }, "FutureUsageTypes": { "description": "How a payment method will be charged after the buyer leaves — the same vocabulary as a confirmation token's setup_future_usage.", "enum": [ "off_session", "on_session" ], "type": "string" }, "GlobalAffiliateStatuses": { "description": "The different statuses of the global affiliate program for a product.", "enum": [ "enabled", "disabled" ], "type": "string" }, "GrantableAuthorizedUserRoles": { "description": "System roles accepted by legacy authorized-user mutations", "enum": [ "owner", "admin", "partner", "sales_manager", "moderator", "advertiser" ], "type": "string" }, "IdentityProfile": { "description": "A consolidated identity or business profile synced from verification provider data.", "properties": { "business_address": { "description": "Registered business address reported by the identity provider. Present on `business` profiles.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "business_name": { "description": "Business entity name. Present on `business` profiles.", "type": [ "string", "null" ] }, "business_structure": { "description": "Reported legal structure of a business profile (e.g. `corp`, `llc`). Provider-specific values; present on `business` profiles.", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code reported by the identity provider, such as `US` or `GB`. For individuals this is the country of citizenship or residence; for businesses, the country of incorporation.", "type": [ "string", "null" ] }, "created_at": { "description": "When the identity profile was first created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "date_of_birth": { "description": "ISO date (`YYYY-MM-DD`) reported by the identity provider. Present on `individual` profiles.", "type": [ "string", "null" ] }, "email": { "description": "Email address reported by the identity provider. Typically present on `individual` profiles.", "type": [ "string", "null" ] }, "first_name": { "description": "Individual's first name.", "type": [ "string", "null" ] }, "id": { "description": "The tag of the identity profile (idpf_xxx).", "example": "idpf_xxxxxxxxxxxxx", "type": "string" }, "last_name": { "description": "Individual's last name.", "type": [ "string", "null" ] }, "linked_companies": { "description": "The companies this identity profile is currently linked to. Only populated for direct Whop user sessions; always empty when authenticated via API key, app, or OAuth scope (a single identity can be linked to companies the calling platform is not entitled to see).", "items": { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "type": "array" }, "payout_status": { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses", "description": "Progress of payout-account setup for this profile, independent of holds. `connected` means onboarding is complete; a `connected` status paired with `payouts_enabled: false` indicates an active account restriction rather than incomplete setup." }, "payouts_enabled": { "description": "Whether this profile can receive payouts right now. True only when payout onboarding is complete and no payout holds are active on the linked account. Treat this as the single source of truth for payout readiness.", "type": "boolean" }, "personal_address": { "description": "Residential address reported by the identity provider. Present on `individual` profiles.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "phone": { "description": "Phone number reported by the identity provider. Typically present on `individual` profiles.", "type": [ "string", "null" ] }, "profile_type": { "description": "Whether this is an 'individual' or 'business' profile.", "type": "string" }, "status": { "$ref": "#/components/schemas/IdentityProfileStatuses", "description": "Derived verification status across all linked verifications. Returns `action_required` whenever the profile has an open request for information (whether a verification, payout, or audit RFI) — i.e. the merchant must submit something before it is in good standing." }, "updated_at": { "description": "When the identity profile was last synced from a verification.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verifications": { "description": "All verification attempts attached to this identity profile, ordered most-recent first.", "items": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "created_at": { "description": "When the verification record was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "session_url": { "description": "A URL the user can visit to complete the verification process. Null if the session does not require user interaction.", "example": "https://verify.stripe.com/session/abc123", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "session_url", "last_error_code", "last_error_reason", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "id", "profile_type", "status", "payout_status", "payouts_enabled", "first_name", "last_name", "date_of_birth", "email", "phone", "personal_address", "business_name", "business_structure", "business_address", "country", "linked_companies", "verifications", "created_at", "updated_at" ], "type": "object" }, "IdentityProfileKinds": { "description": "The kind of identity profile (individual vs business).", "enum": [ "individual", "business" ], "type": "string" }, "IdentityProfileListItem": { "description": "A consolidated identity or business profile synced from verification provider data.", "properties": { "business_address": { "description": "Registered business address reported by the identity provider. Present on `business` profiles.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "business_name": { "description": "Business entity name. Present on `business` profiles.", "type": [ "string", "null" ] }, "business_structure": { "description": "Reported legal structure of a business profile (e.g. `corp`, `llc`). Provider-specific values; present on `business` profiles.", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code reported by the identity provider, such as `US` or `GB`. For individuals this is the country of citizenship or residence; for businesses, the country of incorporation.", "type": [ "string", "null" ] }, "created_at": { "description": "When the identity profile was first created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "date_of_birth": { "description": "ISO date (`YYYY-MM-DD`) reported by the identity provider. Present on `individual` profiles.", "type": [ "string", "null" ] }, "email": { "description": "Email address reported by the identity provider. Typically present on `individual` profiles.", "type": [ "string", "null" ] }, "first_name": { "description": "Individual's first name.", "type": [ "string", "null" ] }, "id": { "description": "The tag of the identity profile (idpf_xxx).", "example": "idpf_xxxxxxxxxxxxx", "type": "string" }, "last_name": { "description": "Individual's last name.", "type": [ "string", "null" ] }, "linked_companies": { "description": "The companies this identity profile is currently linked to. Only populated for direct Whop user sessions; always empty when authenticated via API key, app, or OAuth scope (a single identity can be linked to companies the calling platform is not entitled to see).", "items": { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "type": "array" }, "payout_status": { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses", "description": "Progress of payout-account setup for this profile, independent of holds. `connected` means onboarding is complete; a `connected` status paired with `payouts_enabled: false` indicates an active account restriction rather than incomplete setup." }, "payouts_enabled": { "description": "Whether this profile can receive payouts right now. True only when payout onboarding is complete and no payout holds are active on the linked account. Treat this as the single source of truth for payout readiness.", "type": "boolean" }, "personal_address": { "description": "Residential address reported by the identity provider. Present on `individual` profiles.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "phone": { "description": "Phone number reported by the identity provider. Typically present on `individual` profiles.", "type": [ "string", "null" ] }, "profile_type": { "description": "Whether this is an 'individual' or 'business' profile.", "type": "string" }, "status": { "$ref": "#/components/schemas/IdentityProfileStatuses", "description": "Derived verification status across all linked verifications. Returns `action_required` whenever the profile has an open request for information (whether a verification, payout, or audit RFI) — i.e. the merchant must submit something before it is in good standing." }, "updated_at": { "description": "When the identity profile was last synced from a verification.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verifications": { "description": "All verification attempts attached to this identity profile, ordered most-recent first.", "items": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "created_at": { "description": "When the verification record was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "session_url": { "description": "A URL the user can visit to complete the verification process. Null if the session does not require user interaction.", "example": "https://verify.stripe.com/session/abc123", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "session_url", "last_error_code", "last_error_reason", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "id", "profile_type", "status", "payout_status", "payouts_enabled", "first_name", "last_name", "date_of_birth", "email", "phone", "personal_address", "business_name", "business_structure", "business_address", "country", "linked_companies", "verifications", "created_at", "updated_at" ], "type": "object" }, "IdentityProfileStatuses": { "description": "Derived verification status for an identity profile.", "enum": [ "not_started", "pending", "manual_review", "approved", "rejected", "action_required" ], "type": "string" }, "Invoice": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount_due": { "$ref": "#/components/schemas/Money" }, "billing_address": { "oneOf": [ { "$ref": "#/components/schemas/PaymentAddress" }, { "type": "null" } ] }, "buyer_fee_amount": { "$ref": "#/components/schemas/Money" }, "buyer_fee_percentage": { "example": 0.0, "type": "number" }, "checkout_link": { "description": "A signed link that opens this invoice in a checkout session so the buyer can pay it: pass it as `link` to `POST /checkout_sessions`. Present once the invoice is issued and open; null while it is a draft, once it is paid or void, for an invoice with no product, and when you lack `payment:charge`.", "example": "pay_xxxxxxxxxxxxxx.eyJfcmFpbHMiOnsiZGF0YSI6WzEsZmFsc2VdLCJwdXIiOiJSZWNlaXB0XG5jaGVja291dF9tb3VudFxuIn19--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "customer_name": { "example": "Dana", "type": [ "string", "null" ] }, "due_at": { "example": null, "type": [ "string", "null" ] }, "email_address": { "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "invoice_prefix": { "example": null, "type": [ "string", "null" ] }, "line_items": { "items": { "$ref": "#/components/schemas/InvoiceLineItem" }, "type": "array" }, "mailing_address_id": { "example": null, "type": [ "string", "null" ] }, "member_id": { "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "example": {}, "type": "object" }, "number": { "example": "#xxxxxxxx", "type": "string" }, "object": { "enum": [ "invoice" ], "example": "invoice", "type": "string" }, "overdue": { "example": false, "type": "boolean" }, "paid_at": { "example": null, "type": [ "string", "null" ] }, "payment_method_id": { "example": null, "type": [ "string", "null" ] }, "recipient_emails": { "items": { "description": "Invoice email recipients, independent of the billed customer.", "example": "marcus@shinetime.example", "type": "string" }, "type": "array" }, "scheduled_charge_at": { "description": "When the invoice's saved payment method will be charged, as an ISO 8601 timestamp. Set to `due_at` when an invoice with a `payment_method_id` is sent before it is due; `null` otherwise, once the charge starts, and once the invoice is paid, void, or uncollectible.", "example": null, "type": [ "string", "null" ] }, "scheduled_send_at": { "example": null, "type": [ "string", "null" ] }, "status": { "enum": [ "draft", "open", "authorized", "paid", "pending", "uncollectible", "unresolved", "void" ], "example": "open", "type": "string" }, "subtotal": { "$ref": "#/components/schemas/Money" }, "tax_amount": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "total": { "$ref": "#/components/schemas/Money" }, "totals_status": { "enum": [ "estimated", "final" ], "example": "final", "type": "string" }, "updated_at": { "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "object", "account_id", "member_id", "number", "invoice_prefix", "status", "overdue", "due_at", "scheduled_send_at", "scheduled_charge_at", "customer_name", "recipient_emails", "email_address", "payment_method_id", "mailing_address_id", "billing_address", "totals_status", "buyer_fee_percentage", "subtotal", "buyer_fee_amount", "tax_amount", "total", "amount_due", "checkout_link", "line_items", "metadata", "created_at", "updated_at", "paid_at" ], "type": "object" }, "InvoiceCollectionMethods": { "description": "The method of collection for an invoice.", "enum": [ "send_invoice", "charge_automatically" ], "type": "string" }, "InvoiceLegacy": { "description": "An invoice represents an itemized bill sent by a company to a customer for a specific product and plan, tracking the amount owed, due date, and payment status.", "properties": { "automatically_finalizes_at": { "description": "The date and time when the invoice will be automatically finalized. For charge_automatically, triggers an automatic charge. For send_invoice, sends the invoice email at the specified time.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "charge_buyer_fee": { "description": "Whether the invoice includes a buyer processing fee on top of the plan price.", "type": "boolean" }, "collection_method": { "$ref": "#/components/schemas/InvoiceCollectionMethods", "description": "The method used to collect payment for this invoice, such as automatic charging or manual payment." }, "company": { "description": "The company that issued this invoice.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo": { "description": "The company's logo.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title", "logo" ], "type": "object" }, "created_at": { "description": "The datetime the invoice was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "current_plan": { "description": "The plan that this invoice charges for.", "properties": { "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 42, "type": [ "integer", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency." }, "description": { "description": "A text description of the plan visible to customers. Maximum 1000 characters. Null if no description is set.", "example": "Monthly access to all premium analytics dashboards and data exports.", "type": [ "string", "null" ] }, "formatted_price": { "description": "The formatted price (including currency) for the plan.", "example": "$10.00", "type": "string" }, "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "The initial purchase price in the plan's base_currency (e.g., 49.99 for $49.99). For one-time plans, this is the full price. For renewal plans, this is charged on top of the first renewal_price.", "example": 6.9, "type": "number" }, "plan_type": { "$ref": "#/components/schemas/PlanTypes", "description": "The billing model for this plan: 'renewal' for recurring subscriptions or 'one_time' for single payments." }, "renewal_price": { "description": "The recurring price charged every billing_period in the plan's base_currency (e.g., 9.99 for $9.99/period). Zero for one-time plans.", "example": 6.9, "type": "number" }, "trial_period_days": { "description": "Free trial days before first renewal charge. `null` if no trial is configured or the user has already used a trial for this plan.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "formatted_price", "currency", "description", "plan_type", "billing_period", "initial_price", "renewal_price", "trial_period_days" ], "type": "object" }, "customer_name": { "description": "The full name of the customer this invoice is addressed to. Null if no name is on file.", "example": "Jane Doe", "type": [ "string", "null" ] }, "due_date": { "description": "The deadline by which payment is expected. Null if the invoice is collected automatically.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "The email address of the customer this invoice is addressed to. Null if no email is on file.", "example": "customer@example.com", "type": [ "string", "null" ] }, "fetch_invoice_token": { "description": "A signed token that allows fetching invoice data publicly without authentication.", "example": "eyJhbGciOiJIUzI1NiJ9...", "type": "string" }, "id": { "description": "The unique identifier for the invoice.", "example": "inv_xxxxxxxxxxxxxx", "type": "string" }, "line_items": { "description": "Optional line items that break down the invoice total into individual charges.", "items": { "description": "A line item on an invoice, representing a single charge with a label, quantity, and unit price.", "properties": { "label": { "description": "The label or description for this line item.", "example": "Platform subscription", "type": "string" }, "position": { "description": "The display order of this line item within the invoice.", "example": 42, "type": "integer" }, "quantity": { "description": "The quantity of this line item.", "example": 6.9, "type": "number" }, "total": { "description": "The computed total for this line item (quantity * unit_price).", "example": 6.9, "type": "number" }, "unit_price": { "description": "The unit price for this line item. Negative for a credit or deduction.", "example": 6.9, "type": "number" } }, "required": [ "label", "quantity", "unit_price", "total", "position" ], "type": "object" }, "type": "array" }, "mailing_address": { "description": "The billing/mailing address associated with this invoice, if one was provided at creation time.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "phone": { "description": "The phone number of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country", "phone" ], "type": [ "object", "null" ] }, "member": { "description": "The member that the invoice was created for. Null when the invoice is addressed to an email address with no member record behind it.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "number": { "description": "The sequential invoice number for display purposes.", "example": "#0001", "type": "string" }, "pay_online_url": { "description": "The checkout URL where the customer can pay this invoice online, with their email address pre-filled and locked.", "type": [ "string", "null" ] }, "payment": { "description": "The payment that settled this invoice. Null while the invoice is unpaid, when the invoice was marked paid manually, and on a subscription renewal invoice, where the settling payment cannot yet be identified.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "payment_processing": { "description": "Whether a payment on this invoice is still clearing. True while a delayed payment method such as ACH or SEPA settles, during which the invoice stays open and is not marked past due.", "type": "boolean" }, "product": { "description": "The product that this invoice was generated for.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "status": { "$ref": "#/components/schemas/InvoiceStatuses", "description": "The current payment status of the invoice, such as draft, open, paid, or void." }, "subscription_billing_anchor_at": { "description": "The date that defines when the subscription billing cycle starts. When set on a renewal plan invoice, all future billing periods anchor to this date.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the invoice was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user this invoice is addressed to. Null if the user account has been removed.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "status", "payment_processing", "number", "due_date", "email_address", "fetch_invoice_token", "line_items", "updated_at", "company", "user", "member", "payment", "automatically_finalizes_at", "subscription_billing_anchor_at", "collection_method", "charge_buyer_fee", "customer_name", "pay_online_url", "current_plan", "product", "mailing_address" ], "type": "object" }, "InvoiceLineItem": { "properties": { "discount_amount": { "description": "The promo discount applied to this item, in the payment's `currency`. Null when no discount was recorded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Line item ID, prefixed `li_`. Null when the payment predates item snapshots and the item is read from the payment's variant.", "example": "li_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "label": { "description": "The item's name as shown at checkout — the product title, else the variant title.", "example": "Ceramic Coating Package", "type": [ "string", "null" ] }, "product_id": { "description": "The product the variant belongs to, prefixed `prod_`. Null for a variant with no product.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "quantity": { "description": "How many units were bought.", "example": 1, "type": "number" }, "subtotal": { "description": "`unit_amount` times `quantity`, before discounts and tax, in the payment's `currency`.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "tax_amount": { "description": "The tax collected on this item, in the payment's `currency`. Null when no tax was recorded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "unit_amount": { "description": "The price of one unit before discounts, in the payment's `currency`. Null when the payment recorded no price.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "variant_id": { "description": "The variant bought, prefixed `plan_`. Null when the variant has since been deleted.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "variant_id", "product_id", "label", "quantity", "unit_amount", "subtotal", "discount_amount", "tax_amount" ], "type": "object" }, "InvoicePdf": { "properties": { "expires_at": { "description": "When the link stops working, as an ISO 8601 timestamp. Generate a new PDF for a fresh link.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "url": { "description": "A short-lived link to download the invoice as a PDF. Anyone holding the link can download the file until it expires.", "example": "https://content.whop.com/exports/2026-01-01/pdfs/receipt_pay_xxxxxxxxxxxxxx.pdf", "type": "string" } }, "required": [ "url", "expires_at" ], "type": "object" }, "InvoiceStatuses": { "description": "The different statuses an invoice can be in", "enum": [ "draft", "open", "paid", "past_due", "uncollectible", "void" ], "type": "string" }, "InvoicesSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "created_at", "due_date" ], "type": "string" }, "LanguageTargetingOption": { "properties": { "code": { "description": "ISO 639 code the ad-group `languages` field takes, such as `en`.", "example": "en", "type": "string" }, "name": { "description": "Display name, such as `English`.", "example": "English", "type": "string" }, "type": { "description": "Always `languages`. The option goes in the ad-group `languages` field.", "enum": [ "languages" ], "example": "languages", "type": "string" } }, "required": [ "type", "code", "name" ], "title": "Language", "type": "object" }, "Languages": { "description": "The available languages for a course", "enum": [ "en", "es", "it", "pt", "de", "fr", "pl", "ru", "nl", "ca", "tr", "sv", "uk", "no", "fi", "sk", "el", "cs", "hr", "da", "ro", "bg" ], "type": "string" }, "Lead": { "description": "A prospective customer who has expressed interest in a company or product but has not yet purchased.", "properties": { "created_at": { "description": "The datetime the lead was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the lead.", "example": "lead_xxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The company member record if this lead has converted into a paying customer. Null if the lead has not converted.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this lead. Null if no metadata was provided.", "type": [ "object", "null" ] }, "product": { "description": "The product the lead expressed interest in. Null if the lead is not associated with a specific product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "referrer": { "description": "The URL of the page that referred this lead to the company. Null if no referrer was captured.", "example": "https://twitter.com/whabormarket", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the lead was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user account associated with this lead.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": "object" } }, "required": [ "id", "created_at", "updated_at", "referrer", "metadata", "user", "product", "member" ], "type": "object" }, "LeadListItem": { "description": "A prospective customer who has expressed interest in a company or product but has not yet purchased.", "properties": { "created_at": { "description": "The datetime the lead was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the lead.", "example": "lead_xxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The company member record if this lead has converted into a paying customer. Null if the lead has not converted.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this lead. Null if no metadata was provided.", "type": [ "object", "null" ] }, "product": { "description": "The product the lead expressed interest in. Null if the lead is not associated with a specific product.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "referrer": { "description": "The URL of the page that referred this lead to the company. Null if no referrer was captured.", "example": "https://twitter.com/whabormarket", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the lead was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user account associated with this lead.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": "object" } }, "required": [ "id", "created_at", "updated_at", "referrer", "metadata", "user", "product", "member" ], "type": "object" }, "LedgerAccount": { "description": "A ledger account represents a financial account on Whop that can hold many balances.", "properties": { "balances": { "description": "The balances associated with the account.", "items": { "description": "A cached balance for a LedgerAccount in respect to a currency.", "properties": { "balance": { "description": "The amount of the balance.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the balance." }, "pending_balance": { "description": "The amount of the balance that is pending.", "example": 6.9, "type": "number" }, "reserve_balance": { "description": "The amount of the balance that is reserved.", "example": 6.9, "type": "number" } }, "required": [ "balance", "currency", "pending_balance", "reserve_balance" ], "type": "object" }, "type": "array" }, "id": { "description": "The unique identifier for the ledger account.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" }, "ledger_type": { "$ref": "#/components/schemas/LedgerTypes", "description": "The type of ledger account." }, "owner": { "description": "The owner of the ledger account.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "A user account on Whop. Contains profile information, identity details, and social connections.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "typename": { "const": "User", "description": "The typename of this object", "type": "string" }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "typename", "id", "name", "username" ], "title": "User", "type": [ "object", "null" ] }, { "description": "A company is a seller on Whop. Companies own products, manage members, and receive payouts.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" }, "typename": { "const": "Company", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "route", "title" ], "title": "Company", "type": [ "object", "null" ] } ], "type": "object" }, "payments_approval_status": { "description": "The status of payments approval for the ledger account.", "oneOf": [ { "$ref": "#/components/schemas/PaymentsApprovalStatuses" }, { "type": "null" } ] }, "payout_account_details": { "description": "The payout account associated with the LedgerAccount, if any.", "properties": { "address": { "description": "The physical address associated with this payout account", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "postal_code", "state", "country" ], "type": [ "object", "null" ] }, "business_name": { "description": "The company's legal name", "type": [ "string", "null" ] }, "business_representative": { "description": "The business representative for this payout account", "properties": { "date_of_birth": { "description": "The date of birth of the business representative in ISO 8601 format (YYYY-MM-DD).", "type": [ "string", "null" ] }, "first_name": { "description": "The first name of the business representative.", "type": [ "string", "null" ] }, "last_name": { "description": "The last name of the business representative.", "type": [ "string", "null" ] }, "middle_name": { "description": "The middle name of the business representative.", "type": [ "string", "null" ] } }, "required": [ "date_of_birth", "first_name", "middle_name", "last_name" ], "type": [ "object", "null" ] }, "email": { "description": "The email address of the representative", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payout account.", "example": "poact_xxxxxxxxxxxx", "type": "string" }, "latest_verification": { "description": "The latest verification for the connected account.", "properties": { "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "last_error_code", "last_error_reason" ], "type": [ "object", "null" ] }, "phone": { "description": "The business representative's phone", "type": [ "string", "null" ] }, "status": { "description": "The granular calculated status of the payout account reflecting its current KYC and payout readiness state.", "oneOf": [ { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses" }, { "type": "null" } ] } }, "required": [ "id", "status", "business_name", "phone", "email", "business_representative", "address", "latest_verification" ], "type": [ "object", "null" ] }, "payout_quote_required": { "description": "Whether a payout from this account must be confirmed against a provider-backed quote first. When true, create a quote with POST /payouts/quotes and send its quote_token when creating the payout.", "type": "boolean" }, "settlement_time_at": { "description": "The settlement batch most recently posted to this account's available balance, at midnight UTC. Every payment settling in that batch carries the same `settlement_time_at`.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "transfer_fee": { "description": "The fee for transfers, if applicable.", "example": 6.9, "type": [ "number", "null" ] }, "treasury_balance": { "description": "The balance cache associated with the account by currency.", "properties": { "balance": { "description": "The amount of the balance.", "example": 6.9, "type": "number" }, "balance_usd": { "description": "The balance converted to USD.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the balance." }, "pending_balance": { "description": "The amount of the balance that is pending.", "example": 6.9, "type": "number" }, "reserve_balance": { "description": "The amount of the balance that is reserved.", "example": 6.9, "type": "number" }, "total_withdrawable_balance": { "description": "The amount of the balance that is withdrawable.", "example": 6.9, "type": "number" } }, "required": [ "balance", "balance_usd", "currency", "pending_balance", "reserve_balance", "total_withdrawable_balance" ], "type": [ "object", "null" ] } }, "required": [ "id", "settlement_time_at", "balances", "treasury_balance", "transfer_fee", "payout_account_details", "payments_approval_status", "ledger_type", "payout_quote_required", "owner" ], "type": "object" }, "LedgerActivity": { "properties": { "account": { "description": "The viewer account that owns this row's ledger. Present only when the response aggregates owned accounts (include_owned_accounts=true); omitted otherwise.", "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "type": "object" } ] }, "amount": { "description": "Signed amount in the currency's smallest precision units.", "example": "2375000000", "type": "string" }, "available_at": { "description": "ISO 8601 timestamp when this activity affects available funds: 00:00:00 UTC on the scheduled release date for credits and debits in a pending good-funds release bucket; the posted time for credits and debits to settled available funds, including refunds, disputes and payouts. Null for activity outside these paths, including on-chain rows. The available_after/before filters use its UTC date; default activity excludes some movements, including opt-in reserves.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Currency for this ledger activity.", "properties": { "code": { "description": "Currency code.", "example": "usd", "type": "string" }, "precision": { "description": "Precision factor for the currency, for example `100000000` for USD.", "example": "100000000", "type": "string" } }, "required": [ "code", "precision" ], "type": "object" }, "id": { "description": "Ledger activity ID.", "example": "line_3", "type": "string" }, "ledger_account_id": { "description": "The ledger account (a ldgr_ identifier) this row belongs to. Present only when the response aggregates owned accounts (include_owned_accounts=true); omitted otherwise. Pair it with `account` to scope drawers and dashboard links to the owning business.", "example": "ldgr_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "line_type": { "description": "The ledger line category this activity was posted under.", "enum": [ "psp_payment_receivable", "payment_gross", "topup", "topup_fee", "payment_gross_reversal", "topup_reversal", "payment_refund", "payment_refund_reversal", "platform_balance_payment", "platform_balance_payment_refund", "ad_spend_purchase", "psp_refund_payable", "passthrough_gmv", "passthrough_gmv_offset", "installment_default", "aggregated_fee", "payment_processing_fixed_fee", "payment_processing_percentage_fee", "billing_percentage_fee", "cross_border_percentage_fee", "fx_percentage_fee", "orchestration_percentage_fee", "revshare_percentage_fee", "stripe_domestic_processing_fee", "stripe_international_processing_fee", "three_ds_fixed_fee", "whop_processing_fee", "economic_intelligence_percentage_fee", "high_risk_merchant_fee", "fraud_prevention_fee", "buyer_fee", "sales_tax_fee", "payout_fee", "affiliate_fee", "marketplace_affiliate_fee", "application_fee", "platform_markup_fee", "platform_markup_fee_payout", "sales_tax_remittance", "sales_tax_remittance_reversal", "sales_tax_collected", "sales_tax_collected_reversal", "sales_tax_remitted", "payment_dispute", "payment_dispute_adjustment", "payment_dispute_fee", "payment_dispute_reversal", "platform_covered_dispute", "dispute_alert_fee", "dispute_representment_fee", "payment_return_fee", "dispute_hold_adjustment", "dispute_hold_blocked", "psp_dispute_payable", "withdrawal", "withdrawal_payable", "withdrawal_payable_reversal", "withdrawal_fee", "withdrawal_fee_reversal", "withdrawal_markup_fee", "withdrawal_markup_fee_reversal", "withdrawal_markup_fee_payout", "withdrawal_markup_fee_payout_reversal", "withdrawal_reversal", "withdrawal_clawback", "withdrawal_clawback_reversal", "payout_receivable", "withdrawal_reclassification", "clawback_receivable", "clawback_receivable_reversal", "treasury_payin", "treasury_payin_receivable", "onchain_deposit", "onchain_deposit_offset", "onchain_withdrawal", "onchain_withdrawal_offset", "trading_account_withdrawal", "trading_account_withdrawal_offset", "trading_account_deposit", "trading_account_deposit_offset", "onchain_wallet_transfer_outgoing", "onchain_wallet_transfer_incoming", "onchain_platform_transfer_outgoing", "onchain_platform_transfer_incoming", "onchain_internal_transfer_outgoing", "onchain_internal_transfer_incoming", "onchain_swap_source", "onchain_swap_target", "onchain_swap_offset", "whop_swap_fee_received", "swap_fee", "internal_withdrawal", "internal_withdrawal_reversal", "internal_withdrawal_payable", "internal_withdrawal_payable_reversal", "internal_withdrawal_fee", "internal_withdrawal_fee_reversal", "internal_withdrawal_markup_fee", "internal_withdrawal_markup_fee_reversal", "internal_withdrawal_markup_fee_payout", "internal_withdrawal_markup_fee_payout_reversal", "internal_withdrawal_in_transit", "internal_withdrawal_complete", "internal_withdrawal_in_transit_reversal", "card_load_transfer", "card_load_deposit", "card_unload_transfer", "card_unload_deposit", "external_card_load_deposit", "external_card_load_offset", "card_spend_authorization", "card_spend_authorization_hold", "card_spend_capture", "card_spend_capture_offset", "card_spend_authorization_void", "card_spend_authorization_void_release", "card_spend_refund", "card_spend_refund_offset", "cashback", "cashback_expense", "cashback_funding", "card_interchange_receivable", "card_interchange", "account_settlement", "currency_conversion_outgoing", "currency_conversion_incoming", "balance_reservation", "balance_reservation_hold", "balance_reservation_reversal", "balance_reservation_release", "bad_debt_offset", "bad_debt_expense", "platform_credits_payment", "platform_credits_payment_refund", "platform_credits_granted", "platform_balance_transfer_outgoing", "platform_balance_transfer_incoming", "internal_balance_transfer_outgoing", "internal_balance_transfer_incoming", "platform_balance_transfer_fee", "connected_account_clawback", "connected_account_negative_balance", "ad_publisher_payout", "ad_publisher_payout_received", "company_referral", "platform_affiliate_payment", "platform_affiliate_payment_reversal", "onboarding_reward", "partner_grant_reward", "payment_revshare", "payment_revshare_payout", "payment_revshare_reversal", "payment_revshare_refund", "payment_referral", "payment_referral_payable", "payment_referral_reversal", "payment_referral_refund", "application_fee_payable", "application_fee_payout", "platform_earning", "airdrop", "airdrop_reversal", "airdrop_expense", "airdrop_expense_reversal", "airdrop_link_funded", "airdrop_link_canceled", "airdrop_link_returned", "airdrop_link_claimed", "airdrop_link_redeemed", "airdrop_link_created", "resolution_center_refund", "ad_funding_disbursement", "ad_campaign_budget", "ads_card_spread", "ad_spend_charge", "ad_network_cost", "ad_spend_margin", "ad_income_expense", "ad_income_receipt", "ad_budget_release", "ad_network_settlement", "ad_affiliate_payout", "ad_affiliate_payout_received", "ad_balance_funding_receipt", "misc_reversal", "fx_gain_loss", "fx_markup", "legacy_crypto_payment", "legacy_payment", "legacy_payment_refund", "license_sale", "license_sale_commission", "license_sale_revenue", "software_rental_revshare", "software_rental_transaction", "misc_purchase", "misc_refund", "referral_bonus", "promo_reversal", "payment_receivable_settlement", "platform_earning_settlement", "platform_earning_unreconciled_clearing", "payment_receivable_clearing", "payment_receivable_reversal", "payment_unreconciled_clearing", "payment_unreconciled_reversal", "settlement_shortfall_loss", "fx_settlement_gain_loss", "settlement_rounding_variance", "psp_payout_settlement", "psp_payout_deposit", "psp_payout_receivable", "psp_payout_receivable_clearing", "payout_unreconciled_clearing", "psp_currency_conversion_outgoing", "psp_currency_conversion_incoming", "psp_currency_conversion_receivable", "psp_currency_conversion_receivable_clearing", "psp_fx_adjustment", "refund_settlement", "refund_settlement_reversal", "refund_payable_clearing", "refund_payable_reversal", "refund_unreconciled_clearing", "refund_unreconciled_reversal", "psp_account_debit", "payment_refund_fee", "dispute_settlement", "dispute_settlement_reversal", "dispute_payable_clearing", "dispute_payable_reversal", "dispute_unreconciled_clearing", "dispute_unreconciled_reversal", "psp_reserve_hold", "psp_reserve_release", "psp_dispute_fee", "psp_dispute_alert_fee", "psp_refund_fee", "psp_account_updater_fee", "psp_adjusted_processing_fee", "psp_authentication_fee", "psp_commission_fee", "psp_fixed_fee", "psp_gateway_fee", "psp_interchange_fee", "psp_invoice_tax_fee", "psp_markup_fee", "psp_network_token_fee", "psp_optimization_fee", "psp_payment_method_fee", "psp_payout_fee", "psp_processing_fee", "psp_risk_fee", "psp_scheme_fee", "psp_variable_fee", "psp_billing_fee", "psp_tax_service_fee", "psp_connect_fee", "external_account_connection_fee", "psp_external_account_connection_fee", "psp_invoicing_fee", "psp_terminal_fee", "treasury_fee", "psp_treasury_fee", "accelerated_settlement_fee", "psp_accelerated_settlement_fee", "psp_receivable_pooled", "psp_pool_settlement", "psp_pool_clearing", "psp_pool_refund_settlement", "psp_pool_refund_clearing", "psp_correction", "psp_payin_settlement", "psp_payin_clearing", "psp_bank_pull_settlement", "psp_bank_pull_clearing", "psp_pool_dispute_settlement", "psp_payout_consolidation", "psp_withholding_tax", "psp_payout_settlement_reversal", "psp_transfer_settlement", "psp_transfer_settlement_reversal", "psp_collection_settlement", "payout_subsidy", "withdrawal_topup_adjustment", "withdrawal_payable_clearing", "withdrawal_payable_clearing_reversal", "identity_verification_fee", "psp_identity_verification_fee", "tax_filing_fee", "psp_tax_filing_fee", "psp_service_fee", "recipient_wallet_load", "psp_recipient_wallet_load", "dispute_management_fee", "psp_dispute_management_fee", "psp_clawback_settlement", "psp_clawback_settlement_reversal", "clawback_receivable_settlement", "clawback_receivable_settlement_reversal", "clawback_fee", "psp_clawback_fee", "bank_transfer", "deposit", "wallet_transfer_incoming", "wallet_transfer_outgoing", "swap_source", "swap_target" ], "example": "payment_gross", "type": "string" }, "object": { "enum": [ "ledger_activity" ], "example": "ledger_activity", "type": "string" }, "payment": { "description": "Payment related to this ledger activity. Included when rich resource hydration is enabled and the movement is tied to a payment.", "oneOf": [ { "properties": { "amount": { "description": "Total charged by the payment.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "card_brand": { "description": "Card brand, when the customer paid by card.", "type": [ "string", "null" ] }, "card_last4": { "description": "Last four digits of the card, when the customer paid by card.", "type": [ "string", "null" ] }, "created_at": { "description": "When the payment was created.", "format": "date-time", "type": "string" }, "id": { "description": "Payment ID, prefixed `pay_`.", "type": "string" }, "object": { "enum": [ "payment" ], "example": "payment", "type": "string" }, "payment_method_type": { "description": "How the customer paid, such as `card` or `paypal`.", "type": [ "string", "null" ] }, "payment_processor": { "description": "Processor that handled the payment, such as `stripe`.", "type": [ "string", "null" ] }, "plan": { "description": "Variant associated with the payment, when applicable.", "properties": { "id": { "description": "Variant ID, prefixed `plan_`.", "type": "string" }, "name": { "description": "Variant name.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "type": [ "object", "null" ] }, "product": { "description": "Product associated with the payment, when applicable.", "properties": { "id": { "description": "Product ID, prefixed `prod_`.", "type": "string" }, "name": { "description": "Product name.", "type": "string" } }, "required": [ "id", "name" ], "type": [ "object", "null" ] }, "user": { "description": "Customer associated with the payment. Email requires member:email:read.", "properties": { "email": { "description": "Customer email, or null without member:email:read.", "type": [ "string", "null" ] }, "id": { "description": "Customer ID, prefixed `user_`.", "type": "string" }, "name": { "description": "Customer display name.", "type": "string" } }, "required": [ "id", "name", "email" ], "type": [ "object", "null" ] } }, "required": [ "object", "id", "amount", "payment_method_type", "payment_processor", "card_brand", "card_last4", "user", "product", "plan", "created_at" ], "type": "object" }, { "type": "null" } ] }, "payment_id": { "description": "Payment ID for any payment-related activity, including refunds and disputes.", "type": [ "string", "null" ] }, "plan_id": { "description": "ID of the variant associated with the payment, when applicable.", "type": [ "string", "null" ] }, "plan_name": { "description": "Name of the variant associated with the payment, when applicable.", "type": [ "string", "null" ] }, "posted_at": { "description": "When the activity posted to the ledger.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "product_id": { "description": "ID of the product associated with the payment, when applicable.", "type": [ "string", "null" ] }, "product_name": { "description": "Name of the product associated with the payment, when applicable.", "type": [ "string", "null" ] }, "resource": { "description": "Resource associated with this ledger activity.", "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "type": "object" }, { "properties": { "id": { "description": "Bounty ID.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "bounty" ], "example": "bounty", "type": "string" }, "status": { "description": "Bounty lifecycle status.", "example": "published", "type": "string" }, "title": { "description": "Bounty title.", "example": "Film a 60-second ceramic coating time-lapse", "type": "string" } }, "required": [ "object", "id", "title", "status" ], "type": "object" }, { "properties": { "id": { "description": "Ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "ledger_account" ], "example": "ledger_account", "type": "string" }, "owner": { "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "object", "id", "owner" ], "type": "object" }, { "properties": { "bank": { "properties": { "account_name": { "description": "Bank account holder name.", "example": "Shine Time Auto Detailing LLC", "type": [ "string", "null" ] }, "account_type": { "description": "Bank account type.", "example": "checking", "type": [ "string", "null" ] }, "bank_name": { "description": "Bank name.", "example": "Frost Bank", "type": [ "string", "null" ] }, "last4": { "description": "Last four digits of the bank account.", "example": "3311", "type": [ "string", "null" ] } }, "required": [ "bank_name", "account_name", "last4", "account_type" ], "type": [ "object", "null" ] }, "card": { "properties": { "brand": { "description": "Card brand.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Card expiration month.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Card expiration year.", "example": 2031, "type": [ "integer", "null" ] }, "last4": { "description": "Last four digits of the card.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "email_identifier": { "description": "Email identifier for email-based payment methods.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "gateway_type": { "description": "Payment gateway type.", "example": "plaid", "type": [ "string", "null" ] }, "id": { "description": "Payment method ID.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "payment_method" ], "example": "payment_method", "type": "string" }, "payment_method_type": { "description": "Payment method type.", "example": "us_bank_account", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payment_method_type", "gateway_type", "card", "bank", "email_identifier" ], "type": "object" }, { "properties": { "account_reference": { "description": "Masked account reference.", "example": "••••0472", "type": [ "string", "null" ] }, "destination_currency_code": { "description": "Destination currency code.", "example": "usd", "type": [ "string", "null" ] }, "id": { "description": "Payout method ID.", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "Payout institution name.", "example": "Frost Bank", "type": [ "string", "null" ] }, "nickname": { "description": "Payout method nickname.", "example": "Ops checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "provider": { "description": "Payout provider.", "example": "masspay", "type": [ "string", "null" ] } }, "required": [ "object", "id", "nickname", "institution_name", "account_reference", "provider", "destination_currency_code" ], "type": "object" }, { "properties": { "authorized_at": { "description": "ISO 8601 timestamp the transaction was authorized.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "card_id": { "description": "Identifier of the card that the transaction was charged to.", "example": "icrd_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "cashback_usd": { "description": "Cashback earned on this transaction as a USD decimal string. Zero for declined or ineligible transactions; null when cashback has not been computed yet.", "example": "0.97", "type": [ "string", "null" ] }, "declined_reason": { "description": "Reason the transaction was declined (when status is declined).", "example": "Insufficient funds", "type": [ "string", "null" ] }, "id": { "description": "Card transaction ID.", "example": "citx_xxxxxxxxxxxxxx", "type": "string" }, "local_amount": { "description": "Amount the merchant charged in their local currency, as a decimal string. Pair with local_currency.", "example": "64.97", "type": [ "string", "null" ] }, "local_currency": { "description": "ISO 4217 currency code of the merchant-charged amount in local_amount.", "example": "usd", "type": [ "string", "null" ] }, "merchant_category": { "description": "Merchant category.", "example": "Car Care Supplies", "type": [ "string", "null" ] }, "merchant_icon_url": { "description": "Merchant icon URL.", "example": "https://icons.example.com/lone-star-detail-supply.png", "type": [ "string", "null" ] }, "merchant_name": { "description": "Merchant display name.", "example": "Lone Star Detail Supply", "type": [ "string", "null" ] }, "object": { "enum": [ "card_transaction" ], "example": "card_transaction", "type": "string" }, "posted_at": { "description": "ISO 8601 timestamp the transaction was settled by the card network.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "Current card transaction status.", "example": "completed", "type": [ "string", "null" ] }, "usd_amount": { "description": "The processor-settled USD amount as a decimal string.", "example": "64.97", "type": [ "string", "null" ] } }, "required": [ "object", "id", "card_id", "merchant_name", "merchant_icon_url", "merchant_category", "status", "usd_amount", "local_amount", "local_currency", "cashback_usd", "authorized_at", "posted_at", "declined_reason" ], "type": "object" }, { "type": "null" } ] }, "source": { "additionalProperties": true, "description": "Source of this ledger activity. Platform markup fees use object platform_fee and the ledger activity ID.", "properties": { "amount_float": { "description": "Payout amount as a decimal number in the destination currency (payout sources only; requires payout:withdrawal:read).", "example": 1500.0, "type": [ "number", "null" ] }, "card_brand": { "description": "Card brand used by the payment source.", "type": [ "string", "null" ] }, "chain": { "description": "Chain the deposit landed on, for example plasma (onchain_transaction sources only).", "example": "plasma", "type": [ "string", "null" ] }, "claim_url": { "description": "The airdrop's claim URL. Null unless the caller can manage claim links on the funding company or withdraw from the funding personal balance.", "example": "https://whop.com/claim", "type": [ "string", "null" ] }, "created_at": { "description": "Payout creation time as an ISO 8601 timestamp (payout sources only; requires payout:withdrawal:read).", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_by_user": { "description": "User who requested the withdrawal. Null for system-generated withdrawals or without payout:withdrawal:read.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] }, "estimated_arrival": { "description": "Estimated arrival as an ISO 8601 timestamp (payout sources only; requires payout:withdrawal:read).", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "fee_amount": { "description": "Total withdrawal fees, including markup fees. Requires payout:withdrawal:read.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "fee_kind": { "description": "Action that generated a platform markup fee: deposit, swap, transfer, card_spend, or payout. Present for platform_markup_fee and platform_markup_fee_payout, including when include_resource is false. Null when the originating action is unavailable; omitted on other source types.", "enum": [ "payout", "transfer", "deposit", "swap", "card_spend", null ], "example": "swap", "type": [ "string", "null" ] }, "fee_type": { "description": "Whether withdrawal fees are inclusive or exclusive. Requires payout:withdrawal:read.", "enum": [ "exclusive", "inclusive", null ], "example": "exclusive", "type": [ "string", "null" ] }, "from_amount": { "description": "Amount converted out of from_currency as a decimal string (swap sources only).", "example": "502.51", "type": [ "string", "null" ] }, "from_currency": { "description": "Lowercase currency code converted from (swap sources only).", "example": "usdt", "type": [ "string", "null" ] }, "id": { "example": "airdrp_xxxxxxxxxxxxxx", "type": "string" }, "notes": { "description": "Memo attached to the transfer, payout, or bank_deposit source, or null when none was provided (on payout sources requires payout:withdrawal:read).", "example": null, "type": [ "string", "null" ] }, "object": { "example": "airdrop_link", "type": "string" }, "payer_name": { "description": "On payout sources, the name of the entity processing the payout (requires payout:withdrawal:read). On bank_deposit sources, the name of the account that sent the deposit.", "example": "MassPay", "type": [ "string", "null" ] }, "payment_amount": { "description": "Total charged by the payment source.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "payment_method_type": { "description": "Payment method used by the payment source. On bank_deposit sources, the transfer rail: `wire`, `ach`, or `rtp`.", "type": [ "string", "null" ] }, "payment_processor": { "description": "Processor used by the payment source.", "type": [ "string", "null" ] }, "payout_amount": { "description": "Withdrawal principal sent to the destination, excluding fees, in the withdrawal currency. Requires payout:withdrawal:read.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "payout_destination": { "description": "Payout destination display info (payout sources only).", "properties": { "icon_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-activity-icon", "type": [ "string", "null" ] }, "payer_name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "payout_token_nickname": { "description": "Saved payout destination nickname (payout sources only).", "example": "Ops checking", "type": [ "string", "null" ] }, "reason": { "description": "Why the activity happened. On transfer sources this is the transfer reason, for example pool_top_up or bounty_return. On payout sources it explains why the payout was canceled, denied, or failed (requires payout:withdrawal:read); null while the payout is progressing normally.", "example": "bounty_payout", "type": [ "string", "null" ] }, "risk_review_hold": { "description": "Whether this payout is currently held for manual risk review (payout sources only; requires payout:withdrawal:read).", "example": true, "type": [ "boolean", "null" ] }, "sender_address": { "description": "On onchain_transaction sources, the sender wallet address or onramp provider identifier. On bank_deposit sources, the last four digits of the sending bank account, such as `••••1547`.", "example": "0x8a4de51b9c37f2e6a0d1b8c94e5f7a2d3c6b0e19", "type": [ "string", "null" ] }, "status": { "description": "Lifecycle status. On payout sources this is the payout status (requires payout:withdrawal:read); on airdrop_link sources it is the claim-link status (ungated); on payment and top-up sources it is the friendly payment status such as succeeded/pending/failed (ungated); on bank_deposit sources it is succeeded, reversal_in_progress or reversed (ungated).", "example": "fully_claimed", "type": [ "string", "null" ] }, "to_amount": { "description": "Amount received in to_currency as a decimal string (swap sources only).", "example": "500.0", "type": [ "string", "null" ] }, "to_currency": { "description": "Lowercase currency code converted to (swap sources only).", "example": "usd", "type": [ "string", "null" ] }, "trace_code": { "description": "Bank trace reference for the withdrawal. Requires payout:withdrawal:read.", "example": null, "type": [ "string", "null" ] }, "tx_hash": { "description": "On-chain transaction hash (onchain_transaction and swap sources only).", "example": "0x5d84a1c7e2f9b036d48c5a7e1b9f2d6c3a8e0b4f7c1d9e5a2b6f8c0d3e7a1b52", "type": [ "string", "null" ] } }, "required": [ "object", "id" ], "type": [ "object", "null" ] }, "usd_amount": { "description": "Dollar value of this movement as a decimal string, signed like `amount`. Converted from the posted amount at the rate that was live when the line posted — the same pricing the wallet balance chart and the financial reports use — so a crypto row carries its dollar value too. `null` for a currency Whop holds no exchange rate for.", "example": "23.75", "type": [ "string", "null" ] }, "user_email": { "description": "Email of the customer associated with the payment. Requires member:email:read.", "type": [ "string", "null" ] }, "user_id": { "description": "ID of the customer associated with the payment.", "type": [ "string", "null" ] }, "user_name": { "description": "Display name of the customer associated with the payment.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "line_type", "amount", "usd_amount", "currency", "posted_at", "available_at", "resource", "source" ], "type": "object" }, "LedgerTypes": { "description": "The types of ledgers that can be created.", "enum": [ "primary", "pool" ], "type": "string" }, "LegacyInvoice": { "description": "An invoice represents an itemized bill sent by a company to a customer for a specific product and plan, tracking the amount owed, due date, and payment status.", "properties": { "automatically_finalizes_at": { "description": "The date and time when the invoice will be automatically finalized. For charge_automatically, triggers an automatic charge. For send_invoice, sends the invoice email at the specified time.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "charge_buyer_fee": { "description": "Whether the invoice includes a buyer processing fee on top of the plan price.", "type": "boolean" }, "collection_method": { "$ref": "#/components/schemas/InvoiceCollectionMethods", "description": "The method used to collect payment for this invoice, such as automatic charging or manual payment." }, "company": { "description": "The company that issued this invoice.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo": { "description": "The company's logo.", "properties": { "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": [ "object", "null" ] }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title", "logo" ], "type": "object" }, "created_at": { "description": "The datetime the invoice was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "current_plan": { "description": "The plan that this invoice charges for.", "properties": { "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time plans.", "example": 42, "type": [ "integer", "null" ] }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency." }, "description": { "description": "A text description of the plan visible to customers. Maximum 1000 characters. Null if no description is set.", "example": "Monthly access to all premium analytics dashboards and data exports.", "type": [ "string", "null" ] }, "formatted_price": { "description": "The formatted price (including currency) for the plan.", "example": "$10.00", "type": "string" }, "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "The initial purchase price in the plan's base_currency (e.g., 49.99 for $49.99). For one-time plans, this is the full price. For renewal plans, this is charged on top of the first renewal_price.", "example": 6.9, "type": "number" }, "plan_type": { "$ref": "#/components/schemas/PlanTypes", "description": "The billing model for this plan: 'renewal' for recurring subscriptions or 'one_time' for single payments." }, "renewal_price": { "description": "The recurring price charged every billing_period in the plan's base_currency (e.g., 9.99 for $9.99/period). Zero for one-time plans.", "example": 6.9, "type": "number" }, "trial_period_days": { "description": "Free trial days before first renewal charge. `null` if no trial is configured or the user has already used a trial for this plan.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "formatted_price", "currency", "description", "plan_type", "billing_period", "initial_price", "renewal_price", "trial_period_days" ], "type": "object" }, "customer_name": { "description": "The full name of the customer this invoice is addressed to. Null if no name is on file.", "example": "Jane Doe", "type": [ "string", "null" ] }, "due_date": { "description": "The deadline by which payment is expected. Null if the invoice is collected automatically.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "The email address of the customer this invoice is addressed to. Null if no email is on file.", "example": "customer@example.com", "type": [ "string", "null" ] }, "fetch_invoice_token": { "description": "A signed token that allows fetching invoice data publicly without authentication.", "example": "eyJhbGciOiJIUzI1NiJ9...", "type": "string" }, "id": { "description": "The unique identifier for the invoice.", "example": "inv_xxxxxxxxxxxxxx", "type": "string" }, "line_items": { "description": "Optional line items that break down the invoice total into individual charges.", "items": { "description": "A line item on an invoice, representing a single charge with a label, quantity, and unit price.", "properties": { "label": { "description": "The label or description for this line item.", "example": "Platform subscription", "type": "string" }, "position": { "description": "The display order of this line item within the invoice.", "example": 42, "type": "integer" }, "quantity": { "description": "The quantity of this line item.", "example": 6.9, "type": "number" }, "total": { "description": "The computed total for this line item (quantity * unit_price).", "example": 6.9, "type": "number" }, "unit_price": { "description": "The unit price for this line item. Negative for a credit or deduction.", "example": 6.9, "type": "number" } }, "required": [ "label", "quantity", "unit_price", "total", "position" ], "type": "object" }, "type": "array" }, "mailing_address": { "description": "The billing/mailing address associated with this invoice, if one was provided at creation time.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "phone": { "description": "The phone number of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country", "phone" ], "type": [ "object", "null" ] }, "member": { "description": "The member that the invoice was created for. Null when the invoice is addressed to an email address with no member record behind it.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "number": { "description": "The sequential invoice number for display purposes.", "example": "#0001", "type": "string" }, "pay_online_url": { "description": "The checkout URL where the customer can pay this invoice online, with their email address pre-filled and locked.", "type": [ "string", "null" ] }, "payment": { "description": "The payment that settled this invoice. Null while the invoice is unpaid, when the invoice was marked paid manually, and on a subscription renewal invoice, where the settling payment cannot yet be identified.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "payment_processing": { "description": "Whether a payment on this invoice is still clearing. True while a delayed payment method such as ACH or SEPA settles, during which the invoice stays open and is not marked past due.", "type": "boolean" }, "product": { "description": "The product that this invoice was generated for.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "status": { "$ref": "#/components/schemas/InvoiceStatuses", "description": "The current payment status of the invoice, such as draft, open, paid, or void." }, "subscription_billing_anchor_at": { "description": "The date that defines when the subscription billing cycle starts. When set on a renewal plan invoice, all future billing periods anchor to this date.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "updated_at": { "description": "The datetime the invoice was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user this invoice is addressed to. Null if the user account has been removed.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "status", "payment_processing", "number", "due_date", "email_address", "fetch_invoice_token", "line_items", "updated_at", "company", "user", "member", "payment", "automatically_finalizes_at", "subscription_billing_anchor_at", "collection_method", "charge_buyer_fee", "customer_name", "pay_online_url", "current_plan", "product", "mailing_address" ], "type": "object" }, "LegacyInvoiceListItem": { "description": "An invoice represents an itemized bill sent by a company to a customer for a specific product and plan, tracking the amount owed, due date, and payment status.", "properties": { "created_at": { "description": "The datetime the invoice was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "current_plan": { "description": "The plan that this invoice charges for.", "properties": { "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency." }, "formatted_price": { "description": "The formatted price (including currency) for the plan.", "example": "$10.00", "type": "string" }, "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "formatted_price", "currency" ], "type": "object" }, "due_date": { "description": "The deadline by which payment is expected. Null if the invoice is collected automatically.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "The email address of the customer this invoice is addressed to. Null if no email is on file.", "example": "customer@example.com", "type": [ "string", "null" ] }, "fetch_invoice_token": { "description": "A signed token that allows fetching invoice data publicly without authentication.", "example": "eyJhbGciOiJIUzI1NiJ9...", "type": "string" }, "id": { "description": "The unique identifier for the invoice.", "example": "inv_xxxxxxxxxxxxxx", "type": "string" }, "line_items": { "description": "Optional line items that break down the invoice total into individual charges.", "items": { "description": "A line item on an invoice, representing a single charge with a label, quantity, and unit price.", "properties": { "label": { "description": "The label or description for this line item.", "example": "Platform subscription", "type": "string" }, "position": { "description": "The display order of this line item within the invoice.", "example": 42, "type": "integer" }, "quantity": { "description": "The quantity of this line item.", "example": 6.9, "type": "number" }, "total": { "description": "The computed total for this line item (quantity * unit_price).", "example": 6.9, "type": "number" }, "unit_price": { "description": "The unit price for this line item. Negative for a credit or deduction.", "example": 6.9, "type": "number" } }, "required": [ "label", "quantity", "unit_price", "total", "position" ], "type": "object" }, "type": "array" }, "number": { "description": "The sequential invoice number for display purposes.", "example": "#0001", "type": "string" }, "payment_processing": { "description": "Whether a payment on this invoice is still clearing. True while a delayed payment method such as ACH or SEPA settles, during which the invoice stays open and is not marked past due.", "type": "boolean" }, "status": { "$ref": "#/components/schemas/InvoiceStatuses", "description": "The current payment status of the invoice, such as draft, open, paid, or void." }, "user": { "description": "The user this invoice is addressed to. Null if the user account has been removed.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "status", "payment_processing", "number", "due_date", "email_address", "fetch_invoice_token", "current_plan", "line_items", "user" ], "type": "object" }, "LessonTypes": { "description": "The available types for a lesson", "enum": [ "text", "video", "pdf", "multi", "quiz", "knowledge_check" ], "type": "string" }, "LessonVisibilities": { "description": "The available visibilities for a lesson. Determines how / whether a lesson is visible to users.", "enum": [ "visible", "hidden" ], "type": "string" }, "Livestream": { "properties": { "created_at": { "description": "When the livestream was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "ended_at": { "description": "When the livestream ended, as an ISO 8601 timestamp. `null` while it is live or before it starts.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Livestream ID, prefixed `lfeed_`.", "example": "lfeed_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "pinned_at": { "description": "When a moderator pinned this livestream's recording, as an ISO 8601 timestamp. `null` when it is not pinned.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "recording_started_at": { "description": "When the recording's first frame was captured, as an ISO 8601 timestamp. Offsets into the recording count from here, not from `started_at`. `null` until recording starts.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "recording_status": { "description": "State of the recording. `null` when the livestream was not recorded.", "enum": [ "recording", "processing", "completed", "failed", null ], "example": "completed", "type": [ "string", "null" ] }, "recording_url": { "description": "A temporary link to the recording's video file. Retrieve the livestream again for a fresh link. `null` until the recording is ready, or when it was deleted.", "example": "https://whop-livestreams-example.s3.amazonaws.com/room/lfeed_xxxxxxxxxxxxxxxxxxxxxx.mp4", "type": [ "string", "null" ] }, "started_at": { "description": "When the livestream went live, as an ISO 8601 timestamp. `null` before it starts.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "A temporary link to a still frame from the livestream. `null` when none was captured.", "example": "https://img.whop.com/livestreams/lfeed_xxxxxxxxxxxxxxxxxxxxxx.jpg", "type": [ "string", "null" ] }, "title": { "description": "Display title of the livestream. `Untitled Livestream` when the host did not set one.", "example": "Live edit: blue hour", "type": "string" } }, "required": [ "id", "title", "started_at", "ended_at", "recording_status", "recording_started_at", "pinned_at", "thumbnail_url", "recording_url", "created_at" ], "type": "object" }, "LocationTargetingOption": { "properties": { "code": { "description": "The standardized code the ad-group `regions` field takes: an ISO 3166-1 code for countries (`US`) or an ISO 3166-2 code for states and provinces (`US-CA`, `CA-ON`). Null for a location that has no standard code, such as a city or a metro area — target those by `key` in the `regions` cities list instead.", "example": "US", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 code of the country the location sits in.", "example": "US", "type": [ "string", "null" ] }, "country_name": { "description": "Name of the country the location sits in.", "example": "United States", "type": [ "string", "null" ] }, "key": { "description": "The ad platform's key for the location in its location taxonomy. Use it as the `key` of a `regions` city or zip entry.", "example": "US", "type": "string" }, "location_type": { "description": "Granularity of the location. Which of these an ad platform reports depends on how finely it divides its location taxonomy.", "enum": [ "country", "region", "city", "zip", "neighborhood", "subcity", "medium_geo_area", "district", "dma" ], "example": "country", "type": "string" }, "name": { "description": "Display name, such as `California`.", "example": "United States", "type": "string" }, "region": { "description": "Name of the state or province a city sits in. Null for everything but cities.", "example": "Texas", "type": [ "string", "null" ] }, "type": { "description": "Always `locations`. The option goes in the ad-group `regions` field.", "enum": [ "locations" ], "example": "locations", "type": "string" } }, "required": [ "type", "location_type", "key", "name", "code", "country_code", "country_name", "region" ], "title": "Location", "type": "object" }, "Market": { "properties": { "id": { "description": "The market's name: a perpetual's Hyperliquid name such as `BTC`, which you send as `market` when you create a trade, or a spot asset's symbol such as `BTC` or `XAUT`. A perpetual and a spot market can share an `id`, so `id` and `instrument_type` together identify a market.", "example": "BTC", "type": "string" }, "instrument_type": { "description": "Whether this is a perpetual or a spot market. With `id`, it identifies the market.", "enum": [ "perpetual", "spot" ], "example": "perpetual", "type": "string" }, "max_leverage": { "description": "The highest cross leverage an order on this perpetual can use. `null` for a spot market, which trades without leverage.", "example": 40, "type": [ "integer", "null" ] }, "price": { "description": "The current price in USD: the midpoint between the best bid and ask. `null` when no price is available.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "size_decimals": { "description": "The most decimals an order's `size` can have on this market.", "example": 5, "type": "integer" } }, "required": [ "id", "instrument_type", "max_leverage", "size_decimals", "price" ], "type": "object" }, "MarketplaceStatuses": { "description": "The available marketplace statuses to choose from.", "enum": [ "not_available", "pending_review", "live_marketplace" ], "type": "string" }, "MediaAsset": { "properties": { "amount_charged": { "description": "USD amount charged to the account's balance for this generation. `null` if the generation wasn't billed.", "example": 2.5, "type": [ "number", "null" ] }, "completed_at": { "description": "ISO 8601 timestamp when the asset reached a terminal state. `null` while `processing`.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "created_at": { "description": "ISO 8601 timestamp when the generation was requested.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency of `amount_charged`. Always `usd`.", "example": "usd", "type": "string" }, "error_message": { "description": "Why generation failed. `null` unless status is `failed`.", "example": "The generation provider rejected the prompt. The charge was refunded.", "type": [ "string", "null" ] }, "file": { "description": "The produced file, usable anywhere attachments are accepted. `null` until the asset is `ready`.", "oneOf": [ { "$ref": "#/components/schemas/MediaAssetFile" }, { "type": "null" } ] }, "generation": { "$ref": "#/components/schemas/MediaAssetGeneration", "description": "The inputs the asset was generated from." }, "id": { "description": "Media asset ID, prefixed `media_`.", "example": "media_xxxxxxxxxxxxxx", "type": "string" }, "media_type": { "description": "The kind of media this asset holds.", "enum": [ "video", "image" ], "example": "video", "type": "string" }, "source": { "description": "How the asset was created. Always `generated`.", "enum": [ "generated" ], "example": "generated", "type": "string" }, "status": { "description": "Lifecycle state: `processing` while generation runs, `ready` when the file is available, `failed` when generation failed and the charge was refunded.", "enum": [ "processing", "ready", "failed" ], "example": "ready", "type": "string" } }, "required": [ "id", "media_type", "source", "status", "amount_charged", "currency", "error_message", "created_at", "completed_at", "generation", "file" ], "type": "object" }, "MediaAssetFile": { "properties": { "id": { "description": "File ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "CDN URL for downloading the file.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "url" ], "type": "object" }, "MediaAssetGeneration": { "properties": { "duration_seconds": { "description": "Requested video length in seconds. `null` for images.", "example": 5, "type": [ "number", "null" ] }, "prompt": { "description": "What the asset was generated from.", "example": "A 9:16 product showcase of a cordless power scrubber", "type": "string" }, "reference_media": { "items": { "description": "Reference image file IDs (`file_` prefixed) supplied at generation time.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "resolution": { "description": "Requested video resolution. `null` for images. `1080p` is not supported by Seedance 2.0 Fast or Mini; `4k` is only supported by Seedance 2.0.", "enum": [ "480p", "720p", "1080p", "4k", null ], "example": "1080p", "type": [ "string", "null" ] } }, "required": [ "prompt", "reference_media", "duration_seconds", "resolution" ], "type": "object" }, "Member": { "properties": { "access_level": { "description": "What the member can reach on the account: `customer` for paying members, `admin` for team members, `no_access` once every grant has lapsed.", "enum": [ "no_access", "admin", "customer" ], "example": "customer", "type": "string" }, "account_id": { "description": "The account this member belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "created_at": { "description": "When the member record was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "display_name": { "description": "The name to show for this member: the user's name, or their username when they have not set one. The buying business's name when `user` is `null`.", "example": "Dana Whitfield", "type": "string" }, "earnings_usd": { "description": "The user's gross income across Whop, in USD, refreshed periodically. `null` when the user hides their earnings or the buyer is another business.", "oneOf": [ { "$ref": "#/components/schemas/UserEarningsAmount" }, { "type": "null" } ] }, "email": { "description": "The user's email address. `null` without `member:email:read` on the account, when the buyer is another business, or when the user has no assigned email.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "Member ID, prefixed `mber_`.", "example": "mber_xxxxxxxxxxxxxx", "type": "string" }, "joined_at": { "description": "When the member first joined the account, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "last_accessed_at": { "description": "When the member last opened the account's content, as an ISO 8601 timestamp. `null` if they never have.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "most_recent_action": { "description": "The member's latest lifecycle state on the account, derived from their memberships, such as `paid_subscriber`, `canceling`, or `churned`. `null` until it is first computed.", "enum": [ "canceling", "churned", "finished_split_pay", "paused", "paid_subscriber", "paid_once", "expiring", "joined", "left", "trialing", "pending_entry", "renewing", "past_due", null ], "example": "paid_subscriber", "type": [ "string", "null" ] }, "most_recent_action_at": { "description": "When `most_recent_action` took effect, as an ISO 8601 timestamp. `null` when `most_recent_action` is `null`.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "phone_number": { "description": "The member's phone number: the most recent number collected (or verified) at checkout, otherwise their account number when they have shared one with this seller. `null` without `member:phone:read` on the account, or when there is neither.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "status": { "description": "`joined` while the member is part of the account, `left` after they leave.", "enum": [ "joined", "left" ], "example": "joined", "type": "string" }, "token_balance": { "description": "The member's current token balance for this account, computed from token transactions.", "example": 70.25, "type": "number" }, "usd_total_spent": { "$ref": "#/components/schemas/Money", "description": "How much the member has spent on the account's products, in USD." }, "user": { "description": "The user behind this member. `null` when the buyer is another business rather than a person.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] } }, "required": [ "id", "account_id", "access_level", "status", "display_name", "email", "most_recent_action", "most_recent_action_at", "usd_total_spent", "token_balance", "earnings_usd", "phone_number", "joined_at", "last_accessed_at", "created_at", "user" ], "type": "object" }, "MemberLegacy": { "description": "A member represents a user's relationship with a company on Whop, including their access level, status, and spending history.", "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel", "description": "The member's content access level. `admin` means their team role grants administrative content access, `customer` means they hold a valid product membership, and `no_access` means they cannot access company content." }, "company": { "description": "The company for the member.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "company_token_balance": { "description": "The member's token balance for this company. Computed live from the ledger, not from a cache.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the company member was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the company member.", "type": "string" }, "joined_at": { "description": "When the member joined the company", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "most_recent_action": { "description": "The most recent action the member has taken.", "oneOf": [ { "$ref": "#/components/schemas/MemberMostRecentActions" }, { "type": "null" } ] }, "most_recent_action_at": { "description": "The time for the most recent action, if applicable.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MemberStatuses", "description": "The status of the member" }, "updated_at": { "description": "The datetime the company member was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "usd_total_spent": { "description": "How much money this customer has spent on the company's products and plans", "example": 6.9, "type": "number" }, "user": { "description": "The user for this member, if any.", "properties": { "email": { "description": "The digital mailing address of the user.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company member user.", "type": "string" }, "name": { "description": "The user's full name.", "type": [ "string", "null" ] }, "username": { "description": "The whop username.", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "updated_at", "joined_at", "access_level", "status", "most_recent_action", "most_recent_action_at", "user", "phone", "usd_total_spent", "company_token_balance", "company" ], "type": "object" }, "MemberListItem": { "description": "A member represents a user's relationship with a company on Whop, including their access level, status, and spending history.", "properties": { "access_level": { "$ref": "#/components/schemas/AccessLevel", "description": "The member's content access level. `admin` means their team role grants administrative content access, `customer` means they hold a valid product membership, and `no_access` means they cannot access company content." }, "company_token_balance": { "description": "The member's token balance for this company. Computed live from the ledger, not from a cache.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the company member was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the company member.", "type": "string" }, "joined_at": { "description": "When the member joined the company", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "most_recent_action": { "description": "The most recent action the member has taken.", "oneOf": [ { "$ref": "#/components/schemas/MemberMostRecentActions" }, { "type": "null" } ] }, "most_recent_action_at": { "description": "The time for the most recent action, if applicable.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MemberStatuses", "description": "The status of the member" }, "updated_at": { "description": "The datetime the company member was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "usd_total_spent": { "description": "How much money this customer has spent on the company's products and plans", "example": 6.9, "type": "number" }, "user": { "description": "The user for this member, if any.", "properties": { "email": { "description": "The digital mailing address of the user.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company member user.", "type": "string" }, "name": { "description": "The user's full name.", "type": [ "string", "null" ] }, "username": { "description": "The whop username.", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "updated_at", "joined_at", "access_level", "status", "most_recent_action", "most_recent_action_at", "user", "phone", "usd_total_spent", "company_token_balance" ], "type": "object" }, "MemberMostRecentActions": { "description": "The different most recent actions a member can have.", "enum": [ "canceling", "churned", "finished_split_pay", "paused", "paid_subscriber", "paid_once", "expiring", "joined", "drafted", "left", "trialing", "pending_entry", "renewing", "past_due" ], "type": "string" }, "MemberNote": { "properties": { "author": { "description": "The user who wrote the note, or `null` when it was added by an API key or automatically by Whop.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] }, "content": { "description": "The note text.", "example": "Asked about annual billing.", "type": "string" }, "created_at": { "description": "When the note was added, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Member note ID, prefixed `note_`.", "example": "note_xxxxxxxxxxxxxx", "type": "string" }, "member_id": { "description": "The member the note is about, prefixed `mber_`.", "example": "mber_xxxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "The customer the note is about, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "content", "member_id", "user_id", "created_at", "author" ], "type": "object" }, "MemberStatuses": { "description": "The different statuses a Member can have.", "enum": [ "drafted", "joined", "left" ], "type": "string" }, "MembersSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "usd_total_spent", "created_at", "joined_at", "most_recent_action" ], "type": "string" }, "Membership": { "properties": { "account": { "$ref": "#/components/schemas/StorefrontAccount", "description": "The account (seller) this membership belongs to." }, "affiliate": { "description": "The membership's affiliate commission. `null` without an affiliate, without `affiliate:basic:read` on the account, and always in webhooks.", "oneOf": [ { "$ref": "#/components/schemas/MembershipAffiliate" }, { "type": "null" } ] }, "billing_period_days": { "description": "Number of days between recurring charges. `null` for non-renewing memberships or memberships with multiple renewal schedules.", "example": 30, "type": [ "integer", "null" ] }, "cancel_at_period_end": { "description": "Whether the membership is set to cancel when the current billing period ends. Only meaningful for recurring variants.", "example": true, "type": "boolean" }, "cancel_option": { "description": "The category the member picked for why they canceled. `null` when no category was picked.", "enum": [ "too_expensive", "switching", "missing_features", "technical_issues", "bad_experience", "unused", "other", "testing", null ], "example": "too_expensive", "type": [ "string", "null" ] }, "canceled_at": { "description": "When cancellation was requested, or when the membership was canceled if no request time is recorded, as an ISO 8601 timestamp. `null` when neither is recorded.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "cancellation_reason": { "description": "Free-text explanation provided when canceling. `null` when no reason was provided.", "example": "Too expensive", "type": [ "string", "null" ] }, "collection_method": { "description": "How renewals are collected. `charge_automatically` charges the saved payment method each period; `send_invoice` emails the buyer an invoice each period. `null` when not set.", "enum": [ "charge_automatically", "send_invoice", null ], "example": "send_invoice", "type": [ "string", "null" ] }, "created_at": { "description": "When the membership was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "current_period_end": { "description": "When the current billing period renews, or when a non-renewing membership expires, as an ISO 8601 timestamp. `null` for one-time purchases with no expiration.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "current_period_start": { "description": "When the current billing period started, as an ISO 8601 timestamp. `null` when no billing period is recorded.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "expires_at": { "description": "When access ends for a membership with a fixed expiration, as an ISO 8601 timestamp. `null` when the membership has no expiration, such as a renewing membership.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "feedback_option": { "description": "The account's own cancel reason the member picked, as they saw it. `null` when the member picked a default category or gave no reason.", "oneOf": [ { "$ref": "#/components/schemas/MembershipFeedbackOption" }, { "type": "null" } ] }, "id": { "description": "Membership ID, prefixed `mem_`.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "$ref": "#/components/schemas/Money", "description": "The variant's current up-front price, in the variant's currency. A list price, not necessarily what the buyer paid. `amount` is `\"0.00\"` when the first charge is free." }, "license_key": { "description": "The software license key for this membership. Only present when the product includes a software licensing experience.", "example": "WHOP-XXXX-XXXX-XXXX", "type": [ "string", "null" ] }, "manage_url": { "description": "URL where the buyer can sign in to manage billing. `null` without a member record or unless the caller is the buyer or has `member:manage` on the account.", "example": "https://whop.com/billing/manage/mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "member": { "description": "The caller's member row on the account. Present only when the membership belongs to the caller; `null` on seller-side reads.", "oneOf": [ { "$ref": "#/components/schemas/MembershipMember" }, { "type": "null" } ] }, "member_id": { "description": "The buyer's member record on the account, prefixed `mber_`. `null` when the membership has no member record, such as an unclaimed membership.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the membership, commonly used for software licensing.", "example": {}, "type": "object" }, "most_recent_action": { "description": "The membership's latest lifecycle event, such as `renewing_on` or `canceled_on`. Pair it with `most_recent_action_at`. `null` when none is recorded.", "enum": [ "canceled_on", "finished_split_pay_at", "canceling_on", "ending_on", "renewing_on", "past_due", "next_payment_attempt", "paused_at", "trial_ends_at", "unresolved_at", "trial_canceling_on", null ], "example": "renewing_on", "type": [ "string", "null" ] }, "most_recent_action_at": { "description": "When `most_recent_action` happened or is scheduled to happen, as an ISO 8601 timestamp. A future time for upcoming events such as `renewing_on`. `null` when no action is recorded.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "phone_number": { "description": "The buyer's phone number recorded for this membership, or `null`. The number collected (or verified) at checkout when the seller's phone collection is on; falls back to the buyer's account number when they have shared one with this seller.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "product": { "$ref": "#/components/schemas/MembershipProduct", "description": "The product this membership grants access to." }, "product_id": { "description": "The product this membership grants access to, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "promo_code_id": { "description": "The promo code discounting this membership, prefixed `promo_`. `null` when none is applied. Set at checkout or by Apply Promo Code to Membership.", "example": "promo_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "renewal_price": { "description": "What the next renewal charges, after any promo code that still applies. `null` for non-renewing memberships.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "split_pay_current_payments": { "description": "Paid installments counted so far on a split pay membership. `null` when the membership is not on split pay, or before its first installment is counted.", "example": null, "type": [ "integer", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the membership stops billing. `null` when the membership is not on split pay.", "example": null, "type": [ "integer", "null" ] }, "status": { "description": "Billing state of the membership. `active`/`trialing` memberships grant access; `past_due` is the grace period after a failed payment; `completed` one-time purchases keep access; `canceled`/`expired` do not.", "enum": [ "trialing", "active", "past_due", "completed", "canceled", "expired", "unresolved" ], "example": "active", "type": "string" }, "updated_at": { "description": "When the membership was last changed, as an ISO 8601 timestamp. Reflects the most recent change to the membership itself, so you can reconcile against webhook retries, replays, and backfills.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user_id": { "description": "The buyer, prefixed `user_`. `null` when the buyer is another business or the membership is unclaimed.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "variant_id": { "description": "The variant the buyer purchased, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "status", "user_id", "member_id", "product_id", "product", "variant_id", "promo_code_id", "billing_period_days", "initial_price", "renewal_price", "split_pay_current_payments", "split_pay_required_payments", "collection_method", "license_key", "phone_number", "cancel_at_period_end", "current_period_start", "current_period_end", "expires_at", "canceled_at", "cancel_option", "cancellation_reason", "feedback_option", "most_recent_action", "most_recent_action_at", "manage_url", "metadata", "created_at", "updated_at", "member", "affiliate", "account" ], "type": "object" }, "MembershipAffiliate": { "properties": { "applies_to_payments": { "description": "Whether the commission is paid on the membership's first payment only or on all its payments.", "enum": [ "first_payment", "all_payments" ], "example": "first_payment", "type": "string" }, "commission_amount": { "description": "The flat fee commission in the membership currency, or `null` for a percentage.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "commission_percentage": { "description": "The percentage commission in percentage points, so `20` means 20%, or `null` for a flat fee.", "type": [ "number", "null" ] }, "commission_source": { "description": "How the commission rate was set: `custom` for a rate set for this affiliate, `member` for the member affiliate rate of the plan or product, `global` for the product's global affiliate rate, or `marketplace` for a Whop marketplace referral.", "enum": [ "custom", "member", "marketplace", "global" ], "example": "custom", "type": "string" }, "commission_type": { "description": "Whether the commission is a percentage or a flat fee.", "enum": [ "flat_fee", "percentage" ], "example": "flat_fee", "type": "string" }, "enabled": { "description": "Whether this membership pays affiliate commissions. `false` means the affiliate is kept on the membership but is no longer paid.", "type": "boolean" }, "id": { "description": "Affiliate ID, prefixed `aff_`.", "type": "string" }, "user_id": { "description": "ID of the affiliate's user, prefixed `user_`.", "type": "string" } }, "required": [ "id", "user_id", "commission_source", "commission_type", "commission_percentage", "commission_amount", "enabled", "applies_to_payments" ], "type": "object" }, "MembershipCancellationModes": { "description": "The mode of cancellation for a membership", "enum": [ "at_period_end", "immediate" ], "type": "string" }, "MembershipFeedbackOption": { "properties": { "label": { "description": "The option's label when the member picked it. Renaming the option later does not change it.", "example": "The wash club costs more than I can spend", "type": "string" } }, "required": [ "label" ], "type": "object" }, "MembershipLegacy": { "description": "A membership represents an active relationship between a user and a product. It tracks the user's access, billing status, and renewal schedule.", "properties": { "cancel_at_period_end": { "description": "Whether this membership is set to cancel at the end of the current billing cycle. Only applies to memberships with a recurring plan.", "type": "boolean" }, "cancel_option": { "description": "The category selected for why the member canceled (e.g. too_expensive, switching, missing_features).", "oneOf": [ { "$ref": "#/components/schemas/CancelOptions" }, { "type": "null" } ] }, "cancelation_status": { "description": "Whether the customer is canceling, left, or was won back. Null if the membership has no cancellation reason or its cancellation state is indeterminate.", "oneOf": [ { "$ref": "#/components/schemas/CancelationStatus" }, { "type": "null" } ] }, "canceled_at": { "description": "The time the customer initiated cancellation of this membership. As a Unix timestamp. Null if the membership has not been canceled.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "cancellation_reason": { "description": "Free-text explanation provided by the customer when canceling. Null if the customer did not provide a reason.", "example": "I found a better alternative.", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The ID of the checkout session/configuration that produced this membership, if any. Use this to map memberships back to the checkout configuration that created them.", "example": "ch_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "company": { "description": "The company this membership belongs to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the membership was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code for this membership's billing. Null if the membership is free.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "custom_field_responses": { "description": "The customer's responses to custom checkout questions configured on the product at the time of purchase.", "items": { "description": "The response from a custom field on checkout", "properties": { "answer": { "description": "The response a user gave to the specific question or field.", "type": "string" }, "id": { "description": "The unique identifier for the custom field response.", "example": "cfrp_xxxxxxxxxxxxx", "type": "string" }, "question": { "description": "The question asked by the custom field", "type": "string" } }, "required": [ "id", "question", "answer" ], "type": "object" }, "type": "array" }, "feedback_option": { "description": "The account's own cancel reason the member picked, as they saw it. `null` when the member picked a default category or gave no reason.", "properties": { "label": { "description": "The option's label when the member picked it. Renaming the option later does not change it.", "type": "string" } }, "required": [ "label" ], "type": [ "object", "null" ] }, "formatted_renewal_price": { "description": "The recurring renewal price for this membership, formatted with currency symbol and billing interval. Null if the membership is not recurring.", "example": "$25.00 / month", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "initial_price_paid": { "description": "The amount the customer paid when first purchasing this membership, formatted with currency symbol.", "example": "$25.00", "type": "string" }, "joined_at": { "description": "The time the user first joined the company associated with this membership. As a Unix timestamp. Null if the member record does not exist.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "license_key": { "description": "The software license key associated with this membership. Only present if the product includes a Whop Software Licensing experience. Null otherwise.", "example": "A1B2C3-D4E5F6-G7H8I9", "type": [ "string", "null" ] }, "manage_url": { "description": "The URL where the customer can view and manage this membership, including cancellation and plan changes. Null if no member record exists.", "example": "https://whop.com/billing/manage/mem_abc123", "type": [ "string", "null" ] }, "member": { "description": "The member record linking the user to the company for this membership. Null if the member record has not been created yet.", "properties": { "id": { "description": "The unique identifier for the member.", "example": "mber_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs for the membership (commonly used for software licensing, e.g., HWID). Max 50 keys, 100 chars per key, 500 chars per string value.", "type": [ "object", "null" ] }, "payment_collection_paused": { "description": "Whether recurring payment collection for this membership is temporarily paused by the company.", "type": "boolean" }, "plan": { "description": "The plan the customer purchased to create this membership.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "type": [ "object", "null" ] } }, "required": [ "id", "metadata" ], "type": "object" }, "product": { "description": "The product this membership grants access to.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "type": [ "object", "null" ] }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title", "metadata" ], "type": "object" }, "promo_code": { "description": "The promotional code currently applied to this membership's billing. Null if no promo code is active.", "properties": { "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "renewal_period_end": { "description": "The end of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "renewal_period_start": { "description": "The start of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The current lifecycle status of the membership (e.g., active, trialing, past_due, canceled, expired, completed)." }, "updated_at": { "description": "The datetime the membership was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who owns this membership. Null if the user account has been deleted.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "profile_pic": { "description": "The URL of the user's profile picture. Use profilePicture for the full attachment object.", "type": "string" }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name", "email", "profile_pic" ], "type": [ "object", "null" ] } }, "required": [ "id", "status", "created_at", "joined_at", "updated_at", "manage_url", "member", "user", "renewal_period_start", "renewal_period_end", "cancel_at_period_end", "cancel_option", "cancelation_status", "cancellation_reason", "feedback_option", "canceled_at", "currency", "formatted_renewal_price", "initial_price_paid", "company", "plan", "promo_code", "product", "license_key", "metadata", "payment_collection_paused", "checkout_configuration_id", "custom_field_responses" ], "type": "object" }, "MembershipListItem": { "description": "A membership represents an active relationship between a user and a product. It tracks the user's access, billing status, and renewal schedule.", "properties": { "cancel_at_period_end": { "description": "Whether this membership is set to cancel at the end of the current billing cycle. Only applies to memberships with a recurring plan.", "type": "boolean" }, "cancel_option": { "description": "The category selected for why the member canceled (e.g. too_expensive, switching, missing_features).", "oneOf": [ { "$ref": "#/components/schemas/CancelOptions" }, { "type": "null" } ] }, "cancelation_status": { "description": "Whether the customer is canceling, left, or was won back. Null if the membership has no cancellation reason or its cancellation state is indeterminate.", "oneOf": [ { "$ref": "#/components/schemas/CancelationStatus" }, { "type": "null" } ] }, "canceled_at": { "description": "The time the customer initiated cancellation of this membership. As a Unix timestamp. Null if the membership has not been canceled.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "cancellation_reason": { "description": "Free-text explanation provided by the customer when canceling. Null if the customer did not provide a reason.", "example": "I found a better alternative.", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The ID of the checkout session/configuration that produced this membership, if any. Use this to map memberships back to the checkout configuration that created them.", "example": "ch_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "company": { "description": "The company this membership belongs to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "created_at": { "description": "The datetime the membership was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code for this membership's billing. Null if the membership is free.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "feedback_option": { "description": "The account's own cancel reason the member picked, as they saw it. `null` when the member picked a default category or gave no reason.", "properties": { "label": { "description": "The option's label when the member picked it. Renaming the option later does not change it.", "type": "string" } }, "required": [ "label" ], "type": [ "object", "null" ] }, "formatted_renewal_price": { "description": "The recurring renewal price for this membership, formatted with currency symbol and billing interval. Null if the membership is not recurring.", "example": "$25.00 / month", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "initial_price_paid": { "description": "The amount the customer paid when first purchasing this membership, formatted with currency symbol.", "example": "$25.00", "type": "string" }, "joined_at": { "description": "The time the user first joined the company associated with this membership. As a Unix timestamp. Null if the member record does not exist.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "license_key": { "description": "The software license key associated with this membership. Only present if the product includes a Whop Software Licensing experience. Null otherwise.", "example": "A1B2C3-D4E5F6-G7H8I9", "type": [ "string", "null" ] }, "manage_url": { "description": "The URL where the customer can view and manage this membership, including cancellation and plan changes. Null if no member record exists.", "example": "https://whop.com/billing/manage/mem_abc123", "type": [ "string", "null" ] }, "member": { "description": "The member record linking the user to the company for this membership. Null if the member record has not been created yet.", "properties": { "id": { "description": "The unique identifier for the member.", "example": "mber_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs for the membership (commonly used for software licensing, e.g., HWID). Max 50 keys, 100 chars per key, 500 chars per string value.", "type": [ "object", "null" ] }, "payment_collection_paused": { "description": "Whether recurring payment collection for this membership is temporarily paused by the company.", "type": "boolean" }, "plan": { "description": "The plan the customer purchased to create this membership.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "type": [ "object", "null" ] } }, "required": [ "id", "metadata" ], "type": "object" }, "product": { "description": "The product this membership grants access to.", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "type": [ "object", "null" ] }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title", "metadata" ], "type": "object" }, "promo_code": { "description": "The promotional code currently applied to this membership's billing. Null if no promo code is active.", "properties": { "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "renewal_period_end": { "description": "The end of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "renewal_period_start": { "description": "The start of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The current lifecycle status of the membership (e.g., active, trialing, past_due, canceled, expired, completed)." }, "updated_at": { "description": "The datetime the membership was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who owns this membership. Null if the user account has been deleted.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "profile_pic": { "description": "The URL of the user's profile picture. Use profilePicture for the full attachment object.", "type": "string" }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name", "email", "profile_pic" ], "type": [ "object", "null" ] } }, "required": [ "id", "status", "created_at", "joined_at", "updated_at", "manage_url", "member", "user", "renewal_period_start", "renewal_period_end", "cancel_at_period_end", "cancel_option", "cancelation_status", "cancellation_reason", "feedback_option", "canceled_at", "currency", "formatted_renewal_price", "initial_price_paid", "company", "plan", "promo_code", "product", "license_key", "metadata", "payment_collection_paused", "checkout_configuration_id" ], "type": "object" }, "MembershipMember": { "properties": { "access_level": { "description": "What the member can reach on the account: `customer` for paying members, `admin` for team members, `no_access` once every grant has lapsed.", "enum": [ "no_access", "admin", "customer" ], "example": "customer", "type": "string" }, "last_accessed_at": { "description": "When the member last opened the account's content, as an ISO 8601 timestamp. `null` if they never have.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "position": { "description": "The member's sort position in the buyer's own account list. `null` until they arrange it.", "example": 1767268800000.0, "type": [ "number", "null" ] } }, "required": [ "access_level", "last_accessed_at", "position" ], "type": "object" }, "MembershipProduct": { "properties": { "id": { "description": "Product ID, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Product logo image URL. `null` when the product has no logo.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Product display name.", "example": "Ceramic Coating Package", "type": "string" } }, "required": [ "id", "title", "logo_url" ], "type": "object" }, "MembershipStatus": { "description": "The status of a membership", "enum": [ "trialing", "active", "past_due", "completed", "canceled", "expired", "unresolved", "drafted", "canceling" ], "type": "string" }, "MembershipsSortableColumns": { "description": "Which columns can be used to sort.", "enum": [ "id", "created_at", "status", "canceled_at", "date_joined", "total_spend" ], "type": "string" }, "Message": { "description": "A message sent within an experience chat, direct message, or group chat.", "properties": { "content": { "description": "The message content formatted as Markdown. Null if the message has no text content.", "example": "Hey, are you available for a **quick call**?", "type": [ "string", "null" ] }, "created_at": { "description": "The timestamp when this message was originally created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "is_edited": { "description": "Whether the message content has been edited after it was originally sent.", "type": "boolean" }, "is_pinned": { "description": "Whether this message is pinned to the top of the channel for easy access.", "type": "boolean" }, "mentions": { "description": "A list of user IDs that are explicitly mentioned in this message.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": "array" }, "mentions_everyone": { "description": "Whether the message includes an @everyone mention that notifies all channel members.", "type": "boolean" }, "message_type": { "$ref": "#/components/schemas/DmsPostTypes", "description": "The classification of this message: regular, system, or automated." }, "poll": { "description": "A poll attached to this message. Null if the message does not contain a poll.", "properties": { "options": { "description": "The options for the poll", "items": { "description": "Represents a single poll option", "properties": { "id": { "description": "The unique identifier for the poll option.", "type": "string" }, "text": { "description": "The text of the poll option", "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "type": [ "array", "null" ] } }, "required": [ "options" ], "type": [ "object", "null" ] }, "poll_votes": { "description": "Aggregated reaction counts on this message, filtered to a specific reaction type.", "items": { "description": "Represents a reaction count for a feed post", "properties": { "count": { "description": "The number of users who reacted", "example": 42, "type": "integer" }, "option_id": { "description": "The reaction that was used", "type": [ "string", "null" ] } }, "required": [ "option_id", "count" ], "type": "object" }, "type": "array" }, "reaction_counts": { "description": "Aggregated reaction counts on this message, filtered to a specific reaction type.", "items": { "description": "Represents a reaction count for a feed post", "properties": { "count": { "description": "The number of users who reacted", "example": 42, "type": "integer" }, "emoji": { "description": "The emoji that was used in shortcode format (:heart:)", "type": [ "string", "null" ] } }, "required": [ "emoji", "count" ], "type": "object" }, "type": "array" }, "replying_to_message_id": { "description": "The unique identifier of the message this post is replying to. Null if this is not a reply.", "type": [ "string", "null" ] }, "updated_at": { "description": "The timestamp when this message was last modified.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who authored this message.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "view_count": { "description": "The number of unique views this message has received. Null if view tracking is not enabled for this channel.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "content", "created_at", "updated_at", "poll", "replying_to_message_id", "is_edited", "is_pinned", "message_type", "mentions", "mentions_everyone", "user", "view_count", "reaction_counts", "poll_votes" ], "type": "object" }, "MessageChannelOrder": { "description": "Sort options for message channels", "enum": [ "created_at", "last_post_sent_at" ], "type": "string" }, "MessageListItem": { "description": "A message sent within an experience chat, direct message, or group chat.", "properties": { "content": { "description": "The message content formatted as Markdown. Null if the message has no text content.", "example": "Hey, are you available for a **quick call**?", "type": [ "string", "null" ] }, "created_at": { "description": "The timestamp when this message was originally created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "is_edited": { "description": "Whether the message content has been edited after it was originally sent.", "type": "boolean" }, "is_pinned": { "description": "Whether this message is pinned to the top of the channel for easy access.", "type": "boolean" }, "mentions": { "description": "A list of user IDs that are explicitly mentioned in this message.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": "array" }, "mentions_everyone": { "description": "Whether the message includes an @everyone mention that notifies all channel members.", "type": "boolean" }, "message_type": { "$ref": "#/components/schemas/DmsPostTypes", "description": "The classification of this message: regular, system, or automated." }, "poll": { "description": "A poll attached to this message. Null if the message does not contain a poll.", "properties": { "options": { "description": "The options for the poll", "items": { "description": "Represents a single poll option", "properties": { "id": { "description": "The unique identifier for the poll option.", "type": "string" }, "text": { "description": "The text of the poll option", "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "type": [ "array", "null" ] } }, "required": [ "options" ], "type": [ "object", "null" ] }, "poll_votes": { "description": "Aggregated reaction counts on this message, filtered to a specific reaction type.", "items": { "description": "Represents a reaction count for a feed post", "properties": { "count": { "description": "The number of users who reacted", "example": 42, "type": "integer" }, "option_id": { "description": "The reaction that was used", "type": [ "string", "null" ] } }, "required": [ "option_id", "count" ], "type": "object" }, "type": "array" }, "reaction_counts": { "description": "Aggregated reaction counts on this message, filtered to a specific reaction type.", "items": { "description": "Represents a reaction count for a feed post", "properties": { "count": { "description": "The number of users who reacted", "example": 42, "type": "integer" }, "emoji": { "description": "The emoji that was used in shortcode format (:heart:)", "type": [ "string", "null" ] } }, "required": [ "emoji", "count" ], "type": "object" }, "type": "array" }, "replying_to_message_id": { "description": "The unique identifier of the message this post is replying to. Null if this is not a reply.", "type": [ "string", "null" ] }, "updated_at": { "description": "The timestamp when this message was last modified.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who authored this message.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "view_count": { "description": "The number of unique views this message has received. Null if view tracking is not enabled for this channel.", "example": 42, "type": [ "integer", "null" ] } }, "required": [ "id", "content", "created_at", "updated_at", "poll", "replying_to_message_id", "is_edited", "is_pinned", "message_type", "mentions", "mentions_everyone", "user", "view_count", "reaction_counts", "poll_votes" ], "type": "object" }, "Money": { "properties": { "amount": { "description": "The amount in major units, as an exact decimal string — `\"10.00\"` is ten dollars. A string so no float rounds it in transit.", "example": "-1234.56", "type": "string" }, "currency": { "description": "Three-letter ISO 4217 currency code, lowercase.", "example": "usd", "type": "string" }, "decimals": { "description": "How many decimal places the amount CARRIES — the precision the charge itself runs at.", "example": 2, "type": "integer" }, "display_decimals": { "description": "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.", "example": 2, "type": "integer" } }, "required": [ "currency", "amount", "decimals", "display_decimals" ], "type": "object" }, "MuxAssetStatuses": { "description": "Mux asset statuses", "enum": [ "uploading", "created", "ready" ], "type": "string" }, "Notification": { "properties": { "account": { "description": "Account the notification belongs to. `null` when the notification is not associated with an account.", "oneOf": [ { "$ref": "#/components/schemas/NotificationAccount" }, { "type": "null" } ] }, "attachment_url": { "description": "Image displayed alongside the notification — the sender's avatar, or the default notification image.", "example": "https://ui-avatars.com/api/", "type": "string" }, "content": { "description": "The body text of the notification displayed to the user.", "example": "Tuesday 9:00 AM, Bay 2", "type": "string" }, "created_at": { "description": "When the notification was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "experience": { "description": "Experience the notification is related to. `null` when not tied to a specific experience.", "oneOf": [ { "$ref": "#/components/schemas/NotificationExperience" }, { "type": "null" } ] }, "id": { "description": "Notification ID. Feed rows carry a composite id that doubles as the list cursor.", "example": "ntfr_xxxxxxxxxxxxxx:xxxxxxxxxxxxx", "type": "string" }, "iframe_link": { "description": "The same destination on the app's own domain, which the Whop web and mobile clients embed instead of navigating to it. Only relevant if you render Whop apps yourself. `null` when the notification carries its own `link`.", "example": "https://whopappdomain0000001.apps.whop.com/experiences/exp_xxxxxxxxxxxxxx/bookings/upcoming", "type": [ "string", "null" ] }, "link": { "description": "The whop.com page the notification opens, as a normal top-level navigation. This is the link to use unless you host Whop apps yourself. `null` when the notification has no click-through destination.", "example": "https://whop.com/joined/shine-time-auto-detailing/bookings-xxxxxxxxxxxxxx/app/bookings/upcoming/", "type": [ "string", "null" ] }, "mentions_me": { "description": "Whether the authenticated user was directly mentioned in this notification.", "example": false, "type": "boolean" }, "rest_path": { "description": "Additional path information appended to the notification's deep link, if any.", "example": "/bookings/upcoming", "type": [ "string", "null" ] }, "sender": { "description": "User who triggered the notification. `null` when it was system-generated.", "oneOf": [ { "$ref": "#/components/schemas/NotificationSender" }, { "type": "null" } ] }, "subject": { "description": "The title line of the notification displayed to the user.", "example": "Your ceramic coating is booked", "type": "string" }, "topic": { "description": "Topic category the notification belongs to, used for grouping and preference management. `null` when uncategorized.", "oneOf": [ { "$ref": "#/components/schemas/NotificationTopicSummary" }, { "type": "null" } ] } }, "required": [ "id", "subject", "content", "link", "iframe_link", "rest_path", "created_at", "attachment_url", "account", "experience", "topic", "sender", "mentions_me" ], "type": "object" }, "NotificationAccount": { "properties": { "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo image URL. `null` when the account has not uploaded one.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "URL slug of the account's store page on whop.com.", "example": "shine-time-auto-detailing", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": "string" } }, "required": [ "id", "title", "route", "logo_url" ], "type": "object" }, "NotificationBadge": { "properties": { "account_id": { "description": "Account the experience belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "experience_id": { "description": "Experience the badge counts, prefixed `exp_`.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "has_unread": { "description": "Whether the caller has unread notifications in this experience.", "example": false, "type": "boolean" }, "important_count": { "description": "Number of unread important (mention) notifications in this experience.", "example": 0, "type": "integer" }, "last_viewed_at": { "description": "When the caller last viewed the experience, as an ISO 8601 timestamp. `null` when never viewed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "account_id", "experience_id", "has_unread", "important_count", "last_viewed_at" ], "type": "object" }, "NotificationExperience": { "properties": { "app": { "description": "App the experience belongs to.", "oneOf": [ { "$ref": "#/components/schemas/NotificationExperienceApp" }, { "type": "null" } ] }, "id": { "description": "Experience ID, prefixed `exp_`.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name of the experience.", "example": "Bookings", "type": [ "string", "null" ] } }, "required": [ "id", "name", "app" ], "type": "object" }, "NotificationExperienceApp": { "properties": { "icon_url": { "description": "Icon image URL. Always present — the default app icon when none is uploaded.", "example": "https://pub-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.dev/custom-perk-icon.svg", "type": "string" }, "id": { "description": "App ID, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "icon_url" ], "type": "object" }, "NotificationPreferenceScope": { "properties": { "account_id": { "description": "Account the preference is scoped to (member notifications), prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "channel": { "description": "Delivery channel the preference applies to. `null` applies to every channel.", "enum": [ "in_app", "mobile", null ], "example": "in_app", "type": [ "string", "null" ] }, "experience_id": { "description": "Experience the preference is scoped to, prefixed `exp_`.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "team_account_id": { "description": "Account whose team notifications the preference is scoped to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "topic_id": { "description": "Notification topic the preference is scoped to, prefixed `topic_`.", "example": "topic_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "account_id", "team_account_id", "experience_id", "topic_id", "channel" ], "type": "object" }, "NotificationPreferenceState": { "properties": { "level": { "description": "What the user is now notified about in this scope, or `null` if the preference was cleared and the scope inherits its default again.", "enum": [ "all", "mentions", "nothing", null ], "example": "nothing", "type": [ "string", "null" ] }, "object": { "description": "Which kind of preference was written: `experience_notification_preference` for an experience level, `notification_preference` for a topic override.", "enum": [ "notification_preference", "experience_notification_preference" ], "example": "notification_preference", "type": "string" }, "scope": { "$ref": "#/components/schemas/NotificationPreferenceScope", "description": "The scope that was written, resolved. `null` on a dimension means the preference is not narrowed there." } }, "required": [ "object", "scope", "level" ], "type": "object" }, "NotificationSender": { "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "username": { "description": "Public username.", "example": "tanyacole", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "NotificationTopic": { "properties": { "default_preference_value": { "description": "Whether notifications for this topic are enabled by default when the user has not set a preference.", "example": false, "type": "boolean" }, "description": { "description": "Human-readable explanation of what notifications in this topic are about. `null` when no description has been set.", "example": "A customer books and pays for a detail", "type": [ "string", "null" ] }, "id": { "description": "Notification topic ID, prefixed `topic_`. This is the value the notification preference endpoints take as `topic_id`.", "example": "topic_xxxxxxxxxxxxxx", "type": "string" }, "identifier": { "description": "Stable, human-readable name for the category, such as `new-follower`. Unlike `id`, it is the same in every environment, which makes it the value to match on in code and to read in logs. Treat it as an opaque string: the set is open and the casing is historical rather than normalized.", "example": "notification_topic1_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "is_mention": { "description": "Whether this topic exclusively handles mention-based notifications.", "example": true, "type": "boolean" }, "name": { "description": "Display name shown in notification preference settings.", "example": "New sales", "type": "string" }, "topic_type": { "description": "Scope of the topic: whether it applies to an account, a user, or an account's team.", "enum": [ "account", "user", "account_team" ], "example": "account_team", "type": "string" } }, "required": [ "id", "identifier", "name", "description", "topic_type", "is_mention", "default_preference_value" ], "type": "object" }, "NotificationTopicSummary": { "properties": { "default_preference_value": { "description": "Whether notifications for this topic are enabled by default when the user has not set a preference.", "example": true, "type": "boolean" }, "id": { "description": "Notification topic ID, prefixed `topic_`.", "example": "topic_xxxxxxxxxxxxxx", "type": "string" }, "is_mention": { "description": "Whether this topic exclusively handles mention-based notifications.", "example": false, "type": "boolean" }, "topic_type": { "description": "Scope of the topic: whether it applies to an account, a user, or an account's team.", "enum": [ "account", "user", "account_team" ], "example": "user", "type": "string" } }, "required": [ "id", "topic_type", "is_mention", "default_preference_value" ], "type": "object" }, "OauthGrant": { "properties": { "account_id": { "description": "The account the grant is scoped to, prefixed `biz_`. `null` when the user authorized the app for themselves rather than for one of their accounts.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "app_id": { "description": "The app this grant authorizes, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "authorized_at": { "description": "When the user last authorized the app, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "created_at": { "description": "When the user first authorized the app, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Grant ID, prefixed `oag_`.", "example": "oag_xxxxxxxxxxxxxx", "type": "string" }, "redirect_url": { "description": "Where to send the user to finish the flow: the `redirect_uri` you supplied with the authorization `code` appended, and `state` when you supplied one. Its scheme, host, port, and path come back exactly as sent — never re-cased or re-encoded — because the client matches them against its registered URI. Returned only once, on create: the code is single-use and expires 10 minutes after it is issued, so redirect immediately.", "example": "https://Booking.Shinetime.example:8443/oauth/Callback/", "type": "string" }, "revoked_at": { "description": "When the grant was revoked, as an ISO 8601 timestamp, or `null` while it is still in force. A revoked grant authorizes nothing — treat its `scopes` as no longer granted.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "scopes": { "items": { "description": "Every permission the user has granted this app, accumulated across authorizations, for example `member:basic:read`. `GET /api_keys/permissions` names and describes each one.", "example": "email", "type": "string" }, "type": "array" } }, "required": [ "id", "app_id", "account_id", "scopes", "authorized_at", "revoked_at", "created_at" ], "type": "object" }, "OwnerLevel": { "properties": { "current": { "description": "Current level, from `0` before the first threshold up to `10`.", "example": 1, "type": "integer" }, "points": { "description": "Points earned this month across every account the owner owns.", "example": 41000, "type": "integer" }, "points_by_source": { "$ref": "#/components/schemas/OwnerLevelPoints", "description": "This month's points, split by where they were earned." }, "points_to_next": { "description": "Points still needed this month to reach the next level, or `null` at level `10`.", "example": 59000, "type": [ "integer", "null" ] }, "resets_at": { "description": "When this month's points reset to zero, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "current", "points", "points_by_source", "points_to_next", "resets_at" ], "type": "object" }, "OwnerLevelPoints": { "properties": { "ads": { "description": "Points from charged Whop Ads spend: 10 for every whole dollar.", "example": 0, "type": "integer" }, "cards": { "description": "Points from Whop Card spend: 10 for every whole dollar.", "example": 40000, "type": "integer" }, "trading": { "description": "Points from perpetual trading volume: 1 for every whole dollar traded.", "example": 1000, "type": "integer" } }, "required": [ "cards", "ads", "trading" ], "type": "object" }, "PageInfo": { "description": "Information about pagination in a connection.", "properties": { "end_cursor": { "description": "When paginating forwards, the cursor to continue.", "type": [ "string", "null" ] }, "has_next_page": { "description": "When paginating forwards, are there more items?", "type": "boolean" }, "has_previous_page": { "description": "When paginating backwards, are there more items?", "type": "boolean" }, "start_cursor": { "description": "When paginating backwards, the cursor to continue.", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" }, "Pagination": { "additionalProperties": false, "properties": { "current_page": { "description": "Current page number", "type": "number" }, "next_page": { "description": "Next page number", "type": [ "number", "null" ] }, "prev_page": { "description": "Previous page number", "type": [ "number", "null" ] }, "total_count": { "description": "Total number of records", "type": "number" }, "total_pages": { "description": "Total number of pages", "type": "number" } }, "required": [ "current_page", "total_pages", "next_page", "prev_page", "total_count" ], "type": "object" }, "Partner": { "properties": { "certification_complete": { "description": "Whether the user finished the partner certification course: every visible quiz and knowledge check has a passing result, or, when the course has none, every visible lesson is marked completed.", "example": false, "type": "boolean" }, "joined_at": { "description": "When the user joined the partner program, as an ISO 8601 timestamp. Null when they have not joined.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "payout_rates": { "items": { "$ref": "#/components/schemas/PartnerPayoutTier", "description": "Default payout percentages grouped by referral tier, with one earning duration per tier. Existing businesses can have individual terms." }, "type": "array" }, "referred_businesses_count": { "description": "Number of active first-tier business referrals attributed to the partner, excluding deleted businesses.", "example": 1, "type": "integer" }, "referring_partner": { "description": "The user currently attributed as this user's primary referrer. Null when there is no active primary referral.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] }, "user": { "$ref": "#/components/schemas/UserSummary", "description": "The authenticated partner's public profile." }, "verification_waitlist_joined": { "description": "Whether the user has a pending or approved personal entry on the Verified Partner waitlist.", "example": false, "type": "boolean" }, "whop_partner_verified_at": { "description": "When the user became a verified Whop Partner, as an ISO 8601 timestamp. `null` if not verified.", "example": null, "type": [ "string", "null" ] } }, "required": [ "joined_at", "whop_partner_verified_at", "verification_waitlist_joined", "certification_complete", "referred_businesses_count", "payout_rates", "referring_partner", "user" ], "type": "object" }, "PartnerAdvance": { "properties": { "activity_30_day": { "description": "Qualifying card and BNPL payment volume in the preceding 30 days, in USD. Available on business detail responses before acceptance.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "activity_60_day": { "description": "Actual payment volume (cards and BNPL) in the preceding 60 days, in USD. Null when unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "amount": { "description": "The offered or accepted upfront CPA payment in USD.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "annual_processing": { "$ref": "#/components/schemas/Money", "description": "Annual projected processing in USD." }, "clawed_back_at": { "description": "When low activity triggered reversal and normal partner terms resumed. No prior commissions are paid retroactively.", "example": null, "type": [ "string", "null" ] }, "deadline_at": { "description": "End of the nine-month CPA term. Normal commissions resume prospectively without backfill.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "estimated_amount": { "description": "Estimated advance using the current CPA formula and observed payout rates, or current reference card pricing when qualifying payment history is unavailable. Available for unqualified projections on business detail responses; not a final offer.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "funded_at": { "description": "When the CPA payment was funded.", "example": null, "type": [ "string", "null" ] }, "offer_token": { "description": "Signed offer valid for 15 minutes. Submit unchanged when accepting. Null unless the caller may accept this offer.", "example": null, "type": [ "string", "null" ] }, "processing_target": { "$ref": "#/components/schemas/Money", "description": "Processing required in a rolling 30-day period to qualify, in USD." }, "projected_60_day_activity": { "description": "Projected payment volume (cards and BNPL) over 60 days, in USD.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "projected_commissions": { "description": "Projected commissions over the remaining CPA term.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "projected_processing_commissions": { "description": "Processing commissions projected for the remaining CPA term, in USD.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "qualified_at": { "description": "First qualification timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "recovery_threshold": { "description": "20% of projected 60-day payment volume (cards and BNPL). Performance checks begin 60 days after funding.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "status": { "description": "The CPA payment lifecycle state.", "enum": [ "projected", "available", "accepted", "funded", "clawed_back", "completed", "expired", "withdrawn" ], "example": "accepted", "type": "string" }, "terms_version": { "description": "Terms version required for acceptance.", "example": "2026-01-01", "type": [ "string", "null" ] } }, "required": [ "estimated_amount", "activity_30_day", "activity_60_day", "projected_60_day_activity", "processing_target", "recovery_threshold", "projected_processing_commissions", "status", "annual_processing", "qualified_at", "deadline_at", "funded_at", "clawed_back_at", "terms_version", "amount", "projected_commissions", "offer_token" ], "type": "object" }, "PartnerPayoutDuration": { "properties": { "unit": { "description": "Unit of the earning window. Month means a calendar month; day means a day.", "enum": [ "day", "month" ], "example": "month", "type": "string" }, "value": { "description": "Number of units in the earning window.", "example": 600, "type": "integer" } }, "required": [ "unit", "value" ], "type": "object" }, "PartnerPayoutRate": { "properties": { "income_source": { "description": "Income source that generates this percentage payout.", "enum": [ "sales", "transfer", "card_interchange", "ad_spend", "withdrawal" ], "example": "card_interchange", "type": "string" }, "percentage": { "description": "Partner's default percentage for this tier and income source. For example, 30 means 30%.", "example": 10.0, "type": "number" } }, "required": [ "income_source", "percentage" ], "type": "object" }, "PartnerPayoutTier": { "properties": { "duration": { "$ref": "#/components/schemas/PartnerPayoutDuration", "description": "Default period during which a new referred business can generate commissions, measured from its attribution start. This is not a payout delay. Individual business terms can differ." }, "rates": { "items": { "$ref": "#/components/schemas/PartnerPayoutRate", "description": "Default payout percentages for each income source in this referral tier." }, "type": "array" }, "tier": { "description": "Referral tier: first for a directly referred business, or second for a business brought by a referred partner.", "enum": [ "first", "second" ], "example": "second", "type": "string" } }, "required": [ "tier", "duration", "rates" ], "type": "object" }, "PartnerReferralRequest": { "properties": { "account": { "description": "Business receiving the request, when one is assigned.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "authorized_user_id": { "description": "The partner's team membership this referral was created for, prefixed `ausr_`. `null` when the referral is personal.", "example": null, "type": [ "string", "null" ] }, "code": { "description": "Unique referral code, when assigned.", "example": null, "type": [ "string", "null" ] }, "created_at": { "description": "When the request was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Partner referral request ID, prefixed `prfr_`.", "example": "prfr_xxxxxxxxxxxxxx", "type": "string" }, "max_redemptions": { "description": "Maximum permitted redemptions, when limited.", "example": null, "type": [ "integer", "null" ] }, "member_id": { "description": "The partner's member record this referral was created for, prefixed `mber_`, when their role on that business is held on their member record. `null` otherwise.", "example": null, "type": [ "string", "null" ] }, "partner": { "$ref": "#/components/schemas/UserSummary", "description": "Public profile of the requesting partner." }, "request_type": { "description": "How the referral request was initiated.", "enum": [ "manual", "ownership_transfer", "link" ], "example": "manual", "type": "string" }, "rewards": { "items": { "$ref": "#/components/schemas/PartnerReferralReward", "description": "Rewards offered by this request." }, "type": "array" }, "status": { "description": "The approval state, or null for requests without an approval process.", "enum": [ "pending", "accepted", "denied", "cancelled", null ], "example": "accepted", "type": [ "string", "null" ] }, "updated_at": { "description": "When the request last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user": { "description": "User receiving the attribution request, or null for a business request or referral link.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] } }, "required": [ "id", "status", "request_type", "code", "max_redemptions", "authorized_user_id", "member_id", "created_at", "updated_at", "account", "user", "partner", "rewards" ], "type": "object" }, "PartnerReferralReward": { "properties": { "bot_qualification_type": { "description": "Activity that qualifies for this reward, when specified.", "enum": [ "sales", "ad_spend", null ], "example": "sales", "type": [ "string", "null" ] }, "id": { "description": "Partner reward ID, prefixed `prwd_`.", "type": "string" }, "qualification_amount": { "$ref": "#/components/schemas/Money", "description": "USD amount of qualifying activity required to earn the reward." }, "recipient": { "description": "Reward recipient's role, or null for a fixed user who is not the requesting partner.", "enum": [ "business", "partner", null ], "example": "business", "type": [ "string", "null" ] }, "recipient_id": { "description": "Concrete recipient's user or business ID, or null until a business redeems the offer.", "type": [ "string", "null" ] }, "reward_amount": { "$ref": "#/components/schemas/Money", "description": "USD amount granted after qualification." } }, "required": [ "id", "recipient", "recipient_id", "bot_qualification_type", "qualification_amount", "reward_amount" ], "type": "object" }, "Passkey": { "properties": { "created_at": { "description": "When the user registered this passkey, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "credential_id": { "description": "The WebAuthn credential ID as a base64url string. Pass it in `allowCredentials` when you run a ceremony against this specific passkey.", "example": "bGFwdG9wLWNyZWRlbnRpYWw", "type": "string" }, "id": { "description": "Passkey ID, prefixed `wcred_`. Use it to delete the passkey.", "example": "wcred_xxxxxxxxxxxxxx", "type": "string" }, "last_used_at": { "description": "When this passkey last completed a WebAuthn ceremony, as an ISO 8601 timestamp, or `null` if it never has.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "nickname": { "description": "The name the user gave this passkey, usually the device it lives on.", "example": "MacBook Pro", "type": "string" } }, "required": [ "id", "credential_id", "nickname", "last_used_at", "created_at" ], "type": "object" }, "PasskeyAuthenticatorSelection": { "properties": { "require_resident_key": { "description": "Always `true`. The older form of `resident_key`, for authenticators that predate it.", "example": true, "type": "boolean" }, "resident_key": { "description": "The authenticator must store a discoverable passkey, so it can sign in without a username.", "enum": [ "required" ], "example": "required", "type": "string" }, "user_verification": { "description": "The authenticator must verify the user, with a biometric or the device's screen lock.", "enum": [ "required" ], "example": "required", "type": "string" } }, "required": [ "resident_key", "require_resident_key", "user_verification" ], "type": "object" }, "PasskeyChallenge": { "properties": { "challenge": { "description": "The challenge to pass to the WebAuthn ceremony, base64url-encoded without padding. Also inside the options.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "creation_options": { "description": "The options for `navigator.credentials.create()` when `challenge_type` is `registration`, otherwise `null`. Convert the keys to camelCase before passing them to the browser.", "oneOf": [ { "$ref": "#/components/schemas/PasskeyCreationOptions" }, { "type": "null" } ] }, "request_options": { "description": "The options for `navigator.credentials.get()` when `challenge_type` is `deletion`, otherwise `null`. Convert the keys to camelCase before passing them to the browser.", "oneOf": [ { "$ref": "#/components/schemas/PasskeyRequestOptions" }, { "type": "null" } ] } }, "required": [ "challenge", "creation_options", "request_options" ], "type": "object" }, "PasskeyCreationExtensions": { "properties": { "cred_props": { "description": "Asks the authenticator to report whether it stored a discoverable passkey.", "example": true, "type": "boolean" } }, "required": [ "cred_props" ], "type": "object" }, "PasskeyCreationOptions": { "properties": { "attestation": { "description": "Whop does not ask for attestation.", "enum": [ "none" ], "example": "none", "type": "string" }, "authenticator_selection": { "$ref": "#/components/schemas/PasskeyAuthenticatorSelection", "description": "What the authenticator must support." }, "challenge": { "description": "The registration challenge, base64url-encoded without padding.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "exclude_credentials": { "items": { "$ref": "#/components/schemas/PasskeyCredentialDescriptor", "description": "The account's existing passkeys, so an authenticator that already holds one does not make a second." }, "type": "array" }, "extensions": { "$ref": "#/components/schemas/PasskeyCreationExtensions", "description": "The WebAuthn extensions to run." }, "pub_key_cred_params": { "items": { "$ref": "#/components/schemas/PasskeyCredentialParameter", "description": "The signature algorithms Whop accepts, most preferred first." }, "type": "array" }, "rp": { "$ref": "#/components/schemas/PasskeyRelyingParty", "description": "The site the passkey belongs to." }, "timeout": { "description": "How long the ceremony may take, in milliseconds. Matches the challenge's lifetime.", "example": 300000, "type": "integer" }, "user": { "$ref": "#/components/schemas/PasskeyUserEntity", "description": "The account the passkey signs in to." } }, "required": [ "challenge", "rp", "user", "pub_key_cred_params", "timeout", "exclude_credentials", "authenticator_selection", "attestation", "extensions" ], "type": "object" }, "PasskeyCredentialDescriptor": { "properties": { "id": { "description": "The WebAuthn credential ID, base64url-encoded.", "example": "bGFwdG9wLWNyZWRlbnRpYWw", "type": "string" }, "transports": { "items": { "description": "How the authenticator holding this passkey can be reached, as it reported at registration. Empty when unknown.", "enum": [ "ble", "hybrid", "internal", "nfc", "smart-card", "usb" ], "example": "ble", "type": "string" }, "type": "array" }, "type": { "description": "Always `public-key`.", "enum": [ "public-key" ], "example": "public-key", "type": "string" } }, "required": [ "type", "id", "transports" ], "type": "object" }, "PasskeyCredentialParameter": { "properties": { "alg": { "description": "A COSE algorithm identifier: `-7` is ES256, `-257` is RS256.", "enum": [ -7, -257 ], "example": -257, "type": "integer" }, "type": { "description": "Always `public-key`.", "enum": [ "public-key" ], "example": "public-key", "type": "string" } }, "required": [ "type", "alg" ], "type": "object" }, "PasskeyRelyingParty": { "properties": { "id": { "description": "The relying party ID, the domain passkeys are bound to.", "example": "localhost", "type": "string" }, "name": { "description": "The site name an authenticator may show.", "example": "Whop", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "PasskeyRequestOptions": { "properties": { "allow_credentials": { "items": { "$ref": "#/components/schemas/PasskeyCredentialDescriptor", "description": "The passkeys that may answer this ceremony." }, "type": "array" }, "challenge": { "description": "The assertion challenge, base64url-encoded without padding.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "rp_id": { "description": "The site the passkey belongs to.", "example": "localhost", "type": "string" }, "timeout": { "description": "How long the ceremony may take, in milliseconds. Matches the challenge's lifetime.", "example": 300000, "type": "integer" }, "user_verification": { "description": "The authenticator must verify the user, with a biometric or the device's screen lock.", "enum": [ "required" ], "example": "required", "type": "string" } }, "required": [ "challenge", "rp_id", "timeout", "allow_credentials", "user_verification" ], "type": "object" }, "PasskeyUserEntity": { "properties": { "display_name": { "description": "The account's name, or its email address when it has none, for passkey pickers that show one.", "example": "Jack Sharkey the 1st", "type": "string" }, "id": { "description": "The account's passkey user handle, base64url-encoded. Random, the same for every passkey on the account, and never a Whop ID. Send it back as `user_handle` when you register the passkey.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The account's email address, the identifier a passkey picker shows.", "example": "marcus@shinetime.example", "type": "string" } }, "required": [ "id", "name", "display_name" ], "type": "object" }, "Payment": { "properties": { "account_id": { "description": "The account that received the payment, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "amount_after_fees": { "$ref": "#/components/schemas/Money", "description": "What the account keeps: the total less Whop's fees." }, "auto_capture_at": { "description": "When Whop will capture this authorized card payment automatically unless it is voided first, as an ISO 8601 timestamp. Null when no automatic capture was requested.", "example": null, "type": [ "string", "null" ] }, "auto_refunded": { "description": "True when Whop refunded the payment automatically, for example on a dispute alert.", "example": false, "type": "boolean" }, "billing_address": { "description": "The billing address the buyer entered, or null.", "oneOf": [ { "$ref": "#/components/schemas/PaymentAddress" }, { "type": "null" } ] }, "billing_reason": { "description": "Why the charge was created: a first purchase, a renewal, a one-time payment, or a manual charge.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "capture_expires_at": { "description": "When the hold on this authorized card payment expires if it is not captured first, as an ISO 8601 timestamp. Null when the payment was not created for later capture.", "example": null, "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The checkout configuration the buyer paid through, prefixed `ch_`, or null.", "example": null, "type": [ "string", "null" ] }, "client_secret": { "description": "The credential a buyer's surface presents to poll this payment, set its return URL and resume it when the bank asked the customer to authenticate. Only on payments created from a confirmation token or waiting on that authentication, and always null in list responses — retrieve the payment for it.", "example": "pay_xxxxxxxxxxxxxx_secret_vdefault_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "created_at": { "description": "When the payment was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency the payment settles in, lowercase ISO 4217. Every money field below is stated in it unless it says otherwise." }, "customer_email": { "description": "The buyer's email address. Null without `member:email:read` on the account or when the buyer has no assigned email.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "customer_phone": { "description": "The phone number the buyer gave at checkout, when one was collected.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "decline_code": { "description": "The normalized decline reason of the most recent failed attempt, or null.", "oneOf": [ { "$ref": "#/components/schemas/PaymentDeclineCodes" }, { "type": "null" } ] }, "dispute_alerted_at": { "description": "When an issuer warned that this payment will be disputed, or null.", "example": null, "type": [ "string", "null" ] }, "dispute_created_at": { "description": "When the most recent dispute on this payment was opened, as an ISO 8601 timestamp. Null when the payment was never disputed, or without the payment:dispute:read permission.", "example": null, "type": [ "string", "null" ] }, "failure_message": { "description": "Why the most recent attempt failed, in plain words, or null.", "example": null, "type": [ "string", "null" ] }, "financing_installments_count": { "description": "For installment methods, how many payments the charge splits into.", "example": null, "type": [ "number", "null" ] }, "holds": { "items": { "$ref": "#/components/schemas/PaymentHold", "description": "The active holds on this payment. Each hold has its own release date, independent of `settlement_time_at`. Empty when nothing is held; released holds are omitted." }, "type": "array" }, "id": { "description": "Payment ID, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "ip_address": { "description": "The buyer's IP address at checkout, as identified by Whop's fraud screening. Null when the payment was not screened at checkout, such as a subscription renewal or a charge made without the buyer present.", "example": null, "type": [ "string", "null" ] }, "last_payment_attempt_at": { "description": "When the most recent charge attempt ran, or null.", "example": null, "type": [ "string", "null" ] }, "line_items": { "items": { "$ref": "#/components/schemas/ReceiptLineItem", "description": "Everything this payment charged for, in purchase order, with quantities and subtotals in the purchase currency. Payments made before item snapshots were recorded return the single item implied by their variant. Empty when no items or variant can be resolved." }, "type": "array" }, "member_id": { "description": "The buyer's member record on the account, prefixed `mber_`. Null without the member:basic:read permission.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "membership_id": { "description": "The membership this payment is billed against, prefixed `mem_`. Null for one-off purchases or without the member:basic:read permission.", "example": "mem_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "description": "Your own key-value data attached when the payment was created.", "example": { "order_ref": "SHINE-4417" }, "type": [ "object", "null" ] }, "needs_tracking": { "description": "True when funds are held until the order ships and no tracking number has been added yet. Null without the shipment:basic:read permission.", "example": false, "type": [ "boolean", "null" ] }, "next_payment_attempt_at": { "description": "When the next automatic retry is scheduled, or null.", "example": null, "type": [ "string", "null" ] }, "paid_at": { "description": "When the money was collected, or null while it has not been.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "payment_instrument": { "description": "The instrument shaped for display: a buyer-facing name, the standard icon set, and the card's brand, last four and issuer identification number when it was a card.", "oneOf": [ { "$ref": "#/components/schemas/PaymentInstrument" }, { "type": "null" } ] }, "payment_method_id": { "description": "The stored payment method that was charged, prefixed `payt_`. Null when the method was not saved.", "example": "payt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_method_type": { "description": "The kind of instrument used, for example `card`, `apple_pay`, `klarna`, or `us_bank_account`.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "payment_rule_matches": { "items": { "$ref": "#/components/schemas/PaymentRuleMatch", "description": "The account's own payment rules that decided this payment, recorded when they ran. Only one action is taken per payment, so a rule that matched but was skipped or outranked is not listed. Empty when none decided it, when the account had no rules, or when Whop blocked the payment before they ran." }, "type": "array" }, "payments_failed": { "description": "How many charge attempts have failed on this payment.", "example": 0, "type": "number" }, "presentment_refunded_amount": { "description": "How much has been refunded so far, in the currency presented to the buyer. Zero when nothing has been refunded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "presentment_tax_amount": { "description": "The sales tax or VAT collected, in the currency presented to the buyer. Null when no tax applied.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "presentment_total": { "description": "The account-facing total in the currency presented to the buyer, before conversion into the settlement currency. Excludes buyer fees.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "product_id": { "description": "The product the variant belongs to, prefixed `prod_`. Null for a variant with no product.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "promo_code_id": { "description": "The promo code applied at checkout, prefixed `promo_`, or null.", "example": null, "type": [ "string", "null" ] }, "quote_id": { "description": "The payment quote this payment charged, prefixed `pq_`: its purchase, promo code and `tax_amount` are the quote's. Null when the payment named no quote and tax was calculated at charge time.", "example": null, "type": [ "string", "null" ] }, "recovery_url": { "description": "Whop-hosted URL where the buyer can sign in and complete 3D Secure for an off-session charge the bank challenged — a subscription renewal or a saved-card payment. Null when recovery is unavailable, you lack `member:basic:read`, or in list responses. Retrieve the payment for it.", "example": null, "type": [ "string", "null" ] }, "refundable": { "description": "True when the payment is `paid`, not yet fully refunded, and its processor supports refunds.", "example": false, "type": "boolean" }, "refunded_amount": { "description": "How much has been refunded so far, as it settled — refunds convert at the rate in force when each one was issued, not the payment's original rate.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "refunded_at": { "description": "When the payment was refunded, or null.", "example": null, "type": [ "string", "null" ] }, "response_due_at": { "description": "When the earliest response is due on a dispute or Resolution Center case awaiting the account's response, as an ISO 8601 timestamp. Null when nothing awaits a response, or without the permission to read that dispute or case.", "example": null, "type": [ "string", "null" ] }, "retryable": { "description": "True when the payment is `open` and Whop can attempt the charge again — see `POST /payments/{id}/retry`.", "example": true, "type": "boolean" }, "risk_score": { "description": "Whop's published risk index from 0 (lowest) to 100 (highest), including enforced decision floors. This is not a fraud probability. Null when no score is available.", "example": null, "type": [ "number", "null" ] }, "risk_signals": { "deprecated": true, "description": "Deprecated. Risk score explanations are no longer provided; always null.\nDEPRECATED: Risk score explanations are no longer provided. Always null.", "example": null, "type": [ "object", "null" ] }, "settlement_time_at": { "description": "When the portion not listed in `holds` posts to the account's available balance, at midnight UTC. The `financial_activity.funds_available` webhook's `posted_at` carries the same value when the settlement that clears it posts. Null until the payment is paid, and always null in list responses — retrieve the payment for it.", "example": null, "type": [ "string", "null" ] }, "shipment_id": { "description": "The shipment fulfilling this payment, prefixed `ship_`. Null when nothing ships or without the shipment:basic:read permission.", "example": null, "type": [ "string", "null" ] }, "shipping_address": { "description": "The shipping address for physical goods, or null.", "oneOf": [ { "$ref": "#/components/schemas/PaymentAddress" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ReceiptStatus", "description": "The lifecycle state of the charge: `open` while collection is outstanding, `paid` once the money moved, `pending` while a settlement rail clears, `void`/`uncollectible` when it ended without collecting." }, "substatus": { "$ref": "#/components/schemas/FriendlyReceiptStatus", "description": "The dashboard's finer-grained reading of the payment, folding in refunds, disputes and Resolution Center cases." }, "subtotal": { "description": "The price before discounts, tax and fees.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "tax_amount": { "description": "The sales tax or VAT collected. Null when no tax applied.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "tax_behavior": { "description": "Whether `tax_amount` was added on top of the price (`exclusive`) or was already inside it (`inclusive`).", "oneOf": [ { "$ref": "#/components/schemas/ReceiptTaxBehaviors" }, { "type": "null" } ] }, "tax_refunded_amount": { "$ref": "#/components/schemas/Money", "description": "How much of the collected tax has been returned to the buyer so far. Zero when the payment carried no tax, or when nothing has been refunded." }, "three_ds_verified": { "description": "True when the buyer completed 3D Secure for this payment.", "example": false, "type": "boolean" }, "total": { "description": "The account-facing total: the price after discounts, plus any tax added on top. Excludes buyer fees, which the buyer pays above this amount — so this is not necessarily what the buyer's statement shows.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "updated_at": { "description": "When the payment last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "usd_total": { "description": "The total converted to USD at the time of the charge, for reporting across currencies. Excludes the adaptive pricing FX markup, which the account does not keep.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "user": { "description": "The buyer. Null when the payment belongs to a company buyer rather than a user.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] }, "variant_id": { "description": "The variant that was charged, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "verification_checks": { "description": "The Address Verification Service (AVS), cardholder name, and Card Verification Value (CVV/CVC) results, or null when the processor returned none.", "oneOf": [ { "$ref": "#/components/schemas/PaymentVerificationChecks" }, { "type": "null" } ] }, "voidable": { "description": "True when the payment can be voided or canceled. The request is rejected if the payment is no longer eligible — see `POST /payments/{id}/void`.", "example": false, "type": "boolean" } }, "required": [ "id", "status", "substatus", "billing_reason", "refundable", "retryable", "voidable", "account_id", "user", "member_id", "membership_id", "variant_id", "product_id", "line_items", "promo_code_id", "checkout_configuration_id", "shipment_id", "currency", "total", "subtotal", "tax_amount", "tax_behavior", "quote_id", "refunded_amount", "tax_refunded_amount", "auto_refunded", "amount_after_fees", "usd_total", "payment_method_type", "payment_method_id", "payment_instrument", "customer_email", "presentment_total", "presentment_tax_amount", "presentment_refunded_amount", "customer_phone", "billing_address", "shipping_address", "needs_tracking", "payments_failed", "failure_message", "decline_code", "recovery_url", "three_ds_verified", "verification_checks", "risk_score", "ip_address", "payment_rule_matches", "risk_signals", "financing_installments_count", "metadata", "created_at", "updated_at", "paid_at", "last_payment_attempt_at", "next_payment_attempt_at", "refunded_at", "dispute_alerted_at", "dispute_created_at", "auto_capture_at", "capture_expires_at", "response_due_at", "settlement_time_at", "holds", "client_secret" ], "type": "object" }, "PaymentAddress": { "properties": { "city": { "description": "The city.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "The ISO 3166-1 alpha-2 country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "The first street address line.", "example": "1114 Bouldin Ave", "type": [ "string", "null" ] }, "line2": { "description": "The second street address line.", "example": "Unit B", "type": [ "string", "null" ] }, "name": { "description": "The name on the address.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal or ZIP code.", "example": "78704", "type": [ "string", "null" ] }, "state": { "description": "The state, province or region.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": "object" }, "PaymentBankTransfer": { "properties": { "account_number": { "description": "The account to send to, in the local scheme's format — `account_number_label` says what to call it.", "example": "4411 0902 33", "type": "string" }, "account_number_label": { "description": "What to call `account_number` when showing it, in the local scheme's own terms — `CLABE` in Mexico, for example.", "example": "Account number", "type": "string" }, "amount": { "$ref": "#/components/schemas/Money", "description": "Exactly what the buyer must send, in the charged currency." }, "bank_account_type": { "description": "The kind of account receiving the transfer, such as a checking account, in the local system's own vocabulary.", "example": "checking", "type": "string" }, "bank_address": { "description": "The receiving bank's address.", "example": "401 Congress Avenue, Austin, TX 78701", "type": "string" }, "bank_branch": { "description": "The receiving branch, where the local system routes by branch.", "example": "Burnet Road, Austin", "type": "string" }, "bank_code": { "description": "The code that identifies the receiving bank — its code in the local clearing system, or its SWIFT/BIC on a transfer that crosses borders.", "example": "684", "type": "string" }, "bank_code_label": { "description": "What to call `bank_code` when showing it, in the scheme's own terms — `SWIFT / BIC` on an international wire, for example.", "type": "string" }, "bank_name": { "description": "The receiving bank's name.", "example": "Frost Bank", "type": "string" }, "beneficiary_document": { "description": "The account holder's tax or identity document number, where the local system needs it to send.", "example": "74-2210318", "type": "string" }, "beneficiary_document_type": { "description": "What kind of document `beneficiary_document` is, in the local system's own vocabulary.", "example": "EIN", "type": "string" }, "beneficiary_name": { "description": "Who the account belongs to — the name the buyer's bank may ask them to confirm.", "example": "Shine Time Auto Detailing LLC", "type": "string" }, "document_url": { "description": "A hosted page with the complete, printable instructions. If you would rather not render the details yourself, send the buyer here.", "example": "https://psp.example/instructions/bank-transfer/shine-8237", "type": "string" }, "expires_at": { "description": "When these details stop being payable, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "instructions": { "description": "The rail's own step-by-step payment text, when it supplies one.", "example": "Send the exact amount from your own bank account and include the reference SHINE-8237 so the transfer can be matched to your order.", "type": "string" }, "reference": { "description": "The reference the buyer must attach to the transfer so it can be matched to this payment.", "example": "SHINE-8237", "type": "string" }, "routing_number": { "description": "The receiving bank's routing number for US transfers.", "example": "111900659", "type": "string" }, "secondary_account_number": { "description": "A second account number, where the rail publishes the same destination in more than one format.", "example": "114-000-093", "type": "string" }, "secondary_account_number_label": { "description": "What to call `secondary_account_number` when showing it.", "example": "ACH routing number", "type": "string" } }, "required": [], "type": "object" }, "PaymentBankTransferInstructions": { "properties": { "bank_transfer": { "$ref": "#/components/schemas/PaymentBankTransfer", "description": "The account details to show." }, "kind": { "description": "Always `bank_transfer`: account details the buyer sends money to from their own bank.", "enum": [ "bank_transfer" ], "example": "bank_transfer", "type": "string" } }, "required": [ "kind", "bank_transfer" ], "title": "Bank transfer", "type": "object" }, "PaymentBillingDetailsPreview": { "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code.", "example": "AR", "type": [ "string", "null" ] }, "email": { "description": "Email supplied when the method was collected.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "name": { "description": "Name on the payment method.", "example": "Buyer Name", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "C1043", "type": [ "string", "null" ] } }, "required": [ "email", "name", "country", "postal_code" ], "type": "object" }, "PaymentDeclineCodes": { "description": "The reason a payment was declined.", "enum": [ "insufficient_funds", "lost_card", "stolen_card", "expired_card", "suspected_fraud", "invalid_card_number", "invalid_cvc", "invalid_cvc_or_expiration", "incorrect_pin", "authentication_required", "card_not_supported", "currency_not_supported", "duplicate_transaction", "generic_decline", "invalid_account", "invalid_amount", "processing_error", "restricted_card", "card_velocity_exceeded", "contact_issuer", "card_declined_by_issuer", "bank_declined", "regulatory_blocked", "transaction_not_permitted", "transaction_stopped", "card_type_not_supported", "issuer_not_found", "closed_account", "issuer_unavailable", "invalid_zip", "invalid_expiry_month", "invalid_expiry_year", "invalid_expiry", "invalid_transaction", "cannot_authorize", "pin_required", "pin_try_exceeded", "provider_declined", "high_risk", "test_mode_decline", "merchant_blacklist", "reenter_transaction", "invalid_pin", "pin_required_as", "withdrawal_count_limit_exceeded", "invalid_country", "issuer_error", "invalid_card_holder_name", "no_accounts", "transaction_cancelled", "three_d_secure_success", "three_d_secure_canceled", "three_d_secure_invalid_card_number", "three_d_secure_generic_error", "three_d_secure_timeout", "three_d_secure_failed", "three_d_secure_card_not_enrolled", "three_d_secure_fraud", "three_d_secure_too_many_attempts", "three_d_secure_rejected_by_bank", "three_d_secure_reported_lost_or_stolen", "blocked_by_cardholder", "test_mode_test_card", "try_again_later", "transaction_not_allowed", "bank_insufficient_funds", "bank_account_not_found", "bank_account_closed", "bank_account_frozen", "bank_invalid_routing_number", "bank_non_transaction_account", "bank_authorization_revoked", "bank_payment_stopped", "bank_not_authorized", "bank_account_holder_deceased", "bank_duplicate", "bank_amount_error", "bank_regulatory_blocked", "bank_details_invalid", "bank_processing_error", "bank_generic_decline", "sepa_invalid_iban", "sepa_no_mandate", "sepa_mandate_data_invalid", "sepa_disputed", "sepa_refused_by_customer", "sepa_generic_decline" ], "example": "insufficient_funds", "type": "string" }, "PaymentFee": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "The fee in the currency it was collected in." }, "collected_at": { "description": "When the fee was collected, as an ISO 8601 timestamp, or null when it has not been.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "description": { "description": "A longer explanation of the fee, when there is one.", "example": null, "type": [ "string", "null" ] }, "label": { "description": "The name the dashboard shows for this fee.", "example": "Processing fee", "type": "string" }, "origin": { "description": "The specific fee this line is, such as `payment_processing_percentage_fee` or `revshare_percentage_fee`.", "enum": [ "stripe_domestic_processing_fee", "stripe_international_processing_fee", "stripe_fixed_processing_fee", "stripe_billing_fee", "stripe_radar_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "stripe_sales_tax_fee", "whop_processing_fee", "marketplace_affiliate_fee", "affiliate_fee", "crypto_fee", "stripe_standard_processing_fee", "paypal_fee", "stripe_payout_fee", "dispute_fee", "dispute_alert_fee", "dispute_representment_fee", "apple_processing_fee", "buyer_fee", "sezzle_processing_fee", "splitit_processing_fee", "platform_balance_processing_fee", "payment_processing_percentage_fee", "payment_processing_fixed_fee", "cross_border_percentage_fee", "fx_percentage_fee", "orchestration_percentage_fee", "three_ds_fixed_fee", "billing_percentage_fee", "revshare_percentage_fee", "application_fee", "high_risk_merchant_fee", "economic_intelligence_percentage_fee", "payment_return_fee" ], "example": "whop_processing_fee", "type": "string" }, "settlement_amount": { "$ref": "#/components/schemas/Money", "description": "The fee converted to the payment's settlement currency, so lines can be totalled against the payment." }, "type": { "description": "The family the fee belongs to: `whop_fee`, `processing_fee`, `affiliate_program_fee`, or `other_fee`.", "enum": [ "whop_fee", "processing_fee", "affiliate_program_fee", "other_fee" ], "example": "whop_fee", "type": "string" } }, "required": [ "type", "origin", "label", "description", "amount", "settlement_amount", "collected_at" ], "type": "object" }, "PaymentHold": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "The amount currently held, in the hold's currency." }, "percentage": { "description": "The reserve percentage recorded when the hold was created, for example 3.5 for 3.5%. Null for other hold types or when no percentage was recorded.", "type": [ "number", "null" ] }, "release_at": { "description": "When the held funds are scheduled to become available, as an ISO 8601 timestamp. Never earlier than the payment's settlement date. Null when release depends on an event, such as shipment resolution, rather than a date.", "type": [ "string", "null" ] }, "type": { "description": "The reason funds are held: `reserve`, `bnpl`, `sequra`, `fraud_hold`, or `preshipment_hold`.", "enum": [ "reserve", "bnpl", "sequra", "fraud_hold", "preshipment_hold" ], "example": "reserve", "type": "string" } }, "required": [ "type", "amount", "percentage", "release_at" ], "type": "object" }, "PaymentInput": { "description": "The account, variant and promo code for a purchase.", "properties": { "account_id": { "description": "The account the purchase belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "promo_code": { "description": "The promo code as the buyer typed it, matched within the account regardless of case and surrounding spaces, as checkout matches it. It must be valid for the variant. Send it or `promo_code_id`, not both; an empty or whitespace-only string counts as not sent. A code the account does not have, or one that is no longer active, is refused before anything is written, with the error code `promo_invalid`. A code this purchase cannot use, such as one with no uses left or one restricted to other variants, products or buyers, is refused with `promo_invalid` too, and the error's message says why.", "example": "SHINE20", "type": [ "string", "null" ] }, "promo_code_id": { "description": "An active promo code to apply, prefixed `promo_`. It must belong to the account and be valid for the variant. Send it or `promo_code`, not both. A code this purchase cannot use is refused with the error code `promo_invalid`, and the error's message says why.", "example": "promo_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "variant": { "description": "The variant purchased, described by its attributes instead of an id: the variant with exactly these attributes is used, and one is created when none exists. Mutually exclusive with `variant_id` and `line_items`. Creating a variant requires `plan:create`; creating or updating a product requires the corresponding product permission.", "properties": { "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "type": [ "boolean", "null" ] }, "application_fee_amount": { "description": "Application fee the platform collects per unit, in the variant currency (5.00 means $5.00 for USD). Must be positive and below the initial price for one-time variants or renewal price for recurring variants. Paid to the parent account alongside other processing fees; collection is capped to remaining proceeds. Applies to subsequent payments on recurring variants. Only valid for connected accounts with a parent account.", "example": 2, "type": [ "number", "null" ] }, "billing_period": { "description": "Recurring billing interval in days.", "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ null, "renewal", "one_time" ], "example": "one_time", "type": [ "string", "null" ] }, "currency": { "description": "Currency code for the variant prices.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "description": { "description": "Variant description.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Days until access expires.", "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Create a new variant instead of reusing a matching variant.", "type": [ "boolean", "null" ] }, "initial_price": { "description": "Additional amount charged on the first purchase, in the variant currency. For recurring variants without a trial, the first charge includes this amount plus renewal_price.", "example": 31, "type": [ "number", "null" ] }, "internal_notes": { "description": "Internal notes for the account.", "type": [ "string", "null" ] }, "override_tax_type": { "description": "Whether the variant's price includes tax: `inclusive` (tax is included in the price), `exclusive` (tax is added on top), or `unspecified`. Omit it or pass `null` to use the account's tax setting. On an account enrolled in the Whop tax service, `inclusive` or `exclusive` replaces the account's setting and `unspecified` keeps it. Otherwise it applies only where the account is the merchant of record: `inclusive` or `exclusive` replaces the account's setting when the account collects tax, and `unspecified` means the variant collects no tax. Where Whop is the merchant of record, the account's setting applies. Variants that differ only in this value are different variants.", "enum": [ null, "exclusive", "inclusive", "unspecified" ], "example": "inclusive", "type": [ "string", "null" ] }, "product": { "description": "Find or create a product by external identifier. Mutually exclusive with product_id.", "properties": { "collect_shipping_address": { "description": "Whether to collect a shipping address at checkout.", "example": true, "type": [ "boolean", "null" ] }, "custom_statement_descriptor": { "description": "Custom card statement descriptor for the product, starting with WHOP*.", "example": "WHOP*INLINE", "type": [ "string", "null" ] }, "description": { "description": "Product description.", "example": "Quoted, then sent with the payment.", "type": [ "string", "null" ] }, "external_identifier": { "description": "Your unique identifier for the product.", "example": "quoted-again", "pattern": "\\S", "type": "string" }, "global_affiliate_percentage": { "description": "Percentage of revenue paid to global affiliates.", "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "Global affiliate program status.", "enum": [ null, "enabled", "disabled" ], "example": "enabled", "type": [ "string", "null" ] }, "headline": { "description": "Product headline.", "example": "Product headline", "type": [ "string", "null" ] }, "product_tax_code_id": { "description": "Product tax code identifier.", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "Where to redirect the buyer after purchase.", "example": "https://example.com/thanks", "type": [ "string", "null" ] }, "route": { "description": "Product route.", "type": [ "string", "null" ] }, "title": { "description": "Product title.", "example": "Quoted again", "pattern": "\\S", "type": "string" }, "visibility": { "default": "hidden", "description": "Product visibility. Defaults to hidden.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "external_identifier", "title" ], "type": [ "object", "null" ] }, "product_id": { "description": "Existing product ID belonging to the account, prefixed `prod_`. Mutually exclusive with `product`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "renewal_price": { "description": "Recurring price in the variant currency.", "type": [ "number", "null" ] }, "title": { "description": "Variant title.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before renewal.", "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers.", "enum": [ null, "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": [ "string", "null" ] } }, "required": [ "currency" ], "type": "object" }, "variant_id": { "description": "The variant purchased, prefixed `plan_`. It must belong to the account. Mutually exclusive with `variant` and `line_items`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id" ], "type": "object" }, "PaymentInstructions": { "description": "What to show the buyer so they can pay. `kind` picks the shape and the details sit under the key named for it, so switching on `kind` gives you exactly that kind's payload. Every detail field is optional — the rails behind these methods publish them unevenly — but a kind that arrives with `document_url` can always fall back to sending the buyer to that hosted copy of the instructions.", "discriminator": { "mapping": { "bank_transfer": "#/components/schemas/PaymentBankTransferInstructions", "qr": "#/components/schemas/PaymentQrInstructions", "voucher": "#/components/schemas/PaymentVoucherInstructions" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/PaymentVoucherInstructions" }, { "$ref": "#/components/schemas/PaymentQrInstructions" }, { "$ref": "#/components/schemas/PaymentBankTransferInstructions" } ] }, "PaymentInstrument": { "properties": { "card": { "description": "Card payments only: the card's network, last four, and issuer identification number.", "oneOf": [ { "$ref": "#/components/schemas/PaymentInstrumentCard" }, { "type": "null" } ] }, "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "example": "Visa •••• 4242", "type": "string" }, "icons": { "$ref": "#/components/schemas/PaymentMethodIcons", "description": "The standard icon set: square and card shapes, each in light and dark colorways." }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "example": null, "type": [ "number", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "example": "card", "type": "string" } }, "required": [ "payment_method_type", "display_name", "icons", "card", "installment_count" ], "type": "object" }, "PaymentInstrumentCard": { "properties": { "brand": { "description": "The network identifier (`visa`, `amex`, …), matching `card.networks` entries and saved card payment methods. Null when the vault did not record the network.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "The card's expiry month, 1 to 12. Null when the vault did not record it.", "example": 10, "type": [ "number", "null" ] }, "exp_year": { "description": "The card's four-digit expiry year. Null when the vault did not record it.", "example": 2031, "type": [ "number", "null" ] }, "issuer_identification_number": { "description": "The issuer identification number, also called the BIN: the card's leading six or eight digits, which identify the issuing bank. Null when the processor did not report it.", "example": "41111111", "type": [ "string", "null" ] }, "last4": { "description": "The card's last four digits, when captured.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "issuer_identification_number", "exp_month", "exp_year" ], "type": "object" }, "PaymentLastPaymentError": { "properties": { "code": { "description": "A machine-readable classification of the failure.", "example": "processing_error", "type": [ "string", "null" ] }, "decline_code": { "description": "The reason the payment was declined.", "enum": [ "insufficient_funds", "lost_card", "stolen_card", "expired_card", "suspected_fraud", "invalid_card_number", "invalid_cvc", "invalid_cvc_or_expiration", "incorrect_pin", "authentication_required", "card_not_supported", "currency_not_supported", "duplicate_transaction", "generic_decline", "invalid_account", "invalid_amount", "processing_error", "restricted_card", "card_velocity_exceeded", "contact_issuer", "card_declined_by_issuer", "bank_declined", "regulatory_blocked", "transaction_not_permitted", "transaction_stopped", "card_type_not_supported", "issuer_not_found", "closed_account", "issuer_unavailable", "invalid_zip", "invalid_expiry_month", "invalid_expiry_year", "invalid_expiry", "invalid_transaction", "cannot_authorize", "pin_required", "pin_try_exceeded", "provider_declined", "high_risk", "test_mode_decline", "merchant_blacklist", "reenter_transaction", "invalid_pin", "pin_required_as", "withdrawal_count_limit_exceeded", "invalid_country", "issuer_error", "invalid_card_holder_name", "no_accounts", "transaction_cancelled", "three_d_secure_success", "three_d_secure_canceled", "three_d_secure_invalid_card_number", "three_d_secure_generic_error", "three_d_secure_timeout", "three_d_secure_failed", "three_d_secure_card_not_enrolled", "three_d_secure_fraud", "three_d_secure_too_many_attempts", "three_d_secure_rejected_by_bank", "three_d_secure_reported_lost_or_stolen", "blocked_by_cardholder", "test_mode_test_card", "try_again_later", "transaction_not_allowed", "bank_insufficient_funds", "bank_account_not_found", "bank_account_closed", "bank_account_frozen", "bank_invalid_routing_number", "bank_non_transaction_account", "bank_authorization_revoked", "bank_payment_stopped", "bank_not_authorized", "bank_account_holder_deceased", "bank_duplicate", "bank_amount_error", "bank_regulatory_blocked", "bank_details_invalid", "bank_processing_error", "bank_generic_decline", "sepa_invalid_iban", "sepa_no_mandate", "sepa_mandate_data_invalid", "sepa_disputed", "sepa_refused_by_customer", "sepa_generic_decline", null ], "example": "insufficient_funds", "type": [ "string", "null" ] }, "message": { "description": "A human-readable explanation of the failure.", "example": "Your card was declined.", "type": [ "string", "null" ] } }, "required": [ "code", "decline_code", "message" ], "type": "object" }, "PaymentLegacy": { "description": "A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.", "properties": { "amount_after_fees": { "description": "How much the payment is for after fees", "example": 6.9, "type": "number" }, "application_fee": { "description": "The application fee charged on this payment.", "properties": { "amount": { "description": "The application fee amount.", "example": 6.9, "type": "number" }, "amount_captured": { "description": "The amount of the application fee that has been captured.", "example": 6.9, "type": "number" }, "amount_refunded": { "description": "The amount of the application fee that has been refunded.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the application fee was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the application fee." }, "id": { "description": "The unique identifier for the application fee.", "example": "apfee_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "amount", "amount_captured", "amount_refunded", "currency", "created_at" ], "type": [ "object", "null" ] }, "auto_refunded": { "description": "Whether this payment was auto refunded or not", "type": "boolean" }, "billing_address": { "description": "The address of the user who made the payment.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_exp_month": { "description": "The expiration month (1-12) of the card used for this payment. Falls back to the declined card on failed payments with no saved card. Null when the payment was not made with a card or the expiry is unavailable.", "example": 6, "type": [ "integer", "null" ] }, "card_exp_year": { "description": "The four-digit expiration year of the card used for this payment. Falls back to the declined card on failed payments with no saved card. Null when the payment was not made with a card or the expiry is unavailable.", "example": 2027, "type": [ "integer", "null" ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The ID of the checkout session/configuration that produced this payment, if any. Use this to map payments back to the checkout configuration that created them.", "example": "ch_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "company": { "description": "The company for the payment.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "customer_phone": { "description": "Phone number the customer provided at checkout, or their verified phone number when your checkout requires phone verification. `null` when no phone number was collected.", "type": [ "string", "null" ] }, "decline_code": { "description": "The reason the payment was declined. Null if the payment did not fail.", "oneOf": [ { "$ref": "#/components/schemas/PaymentDeclineCodes" }, { "type": "null" } ] }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "disputes": { "description": "The disputes attached to this payment. Null if the actor in context does not have the payment:dispute:read permission.", "items": { "description": "A dispute is a chargeback or payment challenge filed against a company, including evidence and response status.", "properties": { "amount": { "description": "The disputed amount in the specified currency, formatted as a decimal.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the disputed amount." }, "editable": { "description": "Whether the dispute evidence can still be edited and submitted.", "type": [ "boolean", "null" ] }, "id": { "description": "The unique identifier for the dispute.", "example": "dspt_xxxxxxxxxxxxx", "type": "string" }, "needs_response_by": { "description": "The deadline by which dispute evidence must be submitted. Null if no response deadline is set.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "notes": { "description": "Additional freeform notes submitted by the company as part of the dispute evidence.", "example": "Customer used the product for 3 months before disputing.", "type": [ "string", "null" ] }, "reason": { "description": "A human-readable reason for the dispute.", "example": "Product Not Received", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/DisputeStatuses", "description": "The current status of the dispute lifecycle, such as needs_response, under_review, won, or lost." } }, "required": [ "id", "amount", "currency", "status", "editable", "needs_response_by", "reason", "notes" ], "type": "object" }, "type": [ "array", "null" ] }, "failure_message": { "description": "If the payment failed, the reason for the failure.", "type": [ "string", "null" ] }, "fees": { "description": "The fees associated with this specific payment.", "items": { "description": "Represents a fee related to a payment", "properties": { "amount": { "description": "The value or amount to display for the fee.", "example": 6.9, "type": "number" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the fee." }, "name": { "description": "The label to display for the fee.", "type": "string" }, "type": { "$ref": "#/components/schemas/SpecificFeeOrigins", "description": "The specific origin of the fee, if applicable.", "example": "payment_processing_percentage_fee" } }, "required": [ "name", "amount", "currency", "type" ], "type": "object" }, "type": "array" }, "financing_installments_count": { "description": "The number of financing installments for the payment. Present if the payment is a financing payment (e.g. Splitit, Klarna, etc.).", "example": 42, "type": [ "integer", "null" ] }, "financing_transactions": { "description": "The financing transactions attached to this payment. Present if the payment is a financing payment (e.g. Splitit, Klarna, etc.).", "items": { "description": "A payment transaction.", "properties": { "amount": { "description": "The amount of the payment transaction.", "example": 6.9, "type": "number" }, "created_at": { "description": "The date and time the payment transaction was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment transaction.", "example": "ptx_xxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/PaymentTransactionStatuses", "description": "The status of the payment transaction." }, "transaction_type": { "$ref": "#/components/schemas/PaymentTransactionTypes", "description": "The type of the payment transaction." } }, "required": [ "id", "amount", "status", "created_at", "transaction_type" ], "type": "object" }, "type": "array" }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last_payment_attempt": { "description": "The time of the last payment attempt.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "phone_number": { "description": "The phone number associated with this membership.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status", "phone_number" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "The custom metadata stored on this payment. This will be copied over to the checkout configuration for which this payment was made", "type": [ "object", "null" ] }, "needs_tracking": { "description": "Whether this payment is holding funds until the order ships and has no tracking number yet.", "type": [ "boolean", "null" ] }, "next_payment_attempt": { "description": "The time of the next schedule payment retry.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the receipt names no payment method.", "properties": { "card": { "description": "Card payments only: the card's network and last four.", "properties": { "brand": { "description": "The network identifier (`visa`, `amex`, …), matching `card.networks` entries and saved card payment methods.", "type": "string" }, "last4": { "description": "The card's last four digits, when captured.", "type": [ "string", "null" ] } }, "required": [ "brand", "last4" ], "type": [ "object", "null" ] }, "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "type": "string" }, "icons": { "description": "The standard icon set: square and card shapes, each in light and dark colorways.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "example": 42, "type": [ "integer", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "type": "string" } }, "required": [ "payment_method_type", "display_name", "installment_count", "card", "icons" ], "type": [ "object", "null" ] }, "payment_method": { "description": "The tokenized payment method reference used for this payment. Null if no token was used.", "properties": { "card": { "description": "The card data associated with the payment method, if its a debit or credit card.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "fingerprint": { "description": "A stable identifier for the underlying card. Two payment methods with the same fingerprint are the same card. Null if not available.", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "fingerprint", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment token.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The payment method type of the payment method" } }, "required": [ "id", "created_at", "payment_method_type", "card" ], "type": [ "object", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "payments_failed": { "description": "The number of failed payment attempts for the payment.", "example": 42, "type": [ "integer", "null" ] }, "plan": { "description": "The plan attached to this payment.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "type": [ "object", "null" ] } }, "required": [ "id", "internal_notes", "metadata" ], "type": [ "object", "null" ] }, "product": { "description": "The product this payment was made for", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "type": [ "object", "null" ] }, "route": { "description": "URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title", "route", "metadata" ], "type": [ "object", "null" ] }, "promo_code": { "description": "The promo code used for this payment.", "properties": { "amount_off": { "description": "The discount amount. Interpretation depends on promo_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat_amount', this is dollars off (e.g., 10.00 means $10.00 off).", "example": 6.9, "type": "number" }, "base_currency": { "$ref": "#/components/schemas/Currencies", "description": "The monetary currency of the promo code." }, "code": { "description": "The specific code used to apply the promo at checkout.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" }, "number_of_intervals": { "description": "The number of months the promo is applied for.", "example": 42, "type": [ "integer", "null" ] }, "promo_type": { "$ref": "#/components/schemas/PromoTypes", "description": "The type (% or flat amount) of the promo." } }, "required": [ "id", "code", "amount_off", "base_currency", "promo_type", "number_of_intervals" ], "type": [ "object", "null" ] }, "recovery_url": { "description": "Whop-hosted URL where the buyer can sign in and complete 3D Secure for an off-session charge the bank challenged — a subscription renewal or a saved-card payment. `null` when recovery is unavailable or you lack `member:basic:read`.", "type": [ "string", "null" ] }, "refundable": { "description": "True only for payments that are `paid`, have not been fully refunded, and were processed by a payment processor that allows refunds.", "type": "boolean" }, "refunded_amount": { "description": "The payment refund amount(if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "refunded_at": { "description": "When the payment was refunded (if applicable).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "refunds": { "description": "The refunds issued against this payment, newest first, including failed and canceled refund attempts. Limited to the 100 most recent.", "items": { "description": "A refund represents a full or partial reversal of a payment, including the amount, status, and payment provider.", "properties": { "amount": { "description": "The refunded amount as a decimal in the specified currency, such as 10.43 for $10.43 USD.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the refund was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the refunded amount." }, "id": { "description": "The unique identifier for the refund.", "example": "rf_xxxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/RefundStatuses", "description": "The current processing status of the refund, such as pending, succeeded, or failed." } }, "required": [ "id", "status", "amount", "currency", "created_at" ], "type": "object" }, "type": "array" }, "resolutions": { "description": "The resolution center cases opened by the customer on this payment. Null if the actor in context does not have the payment:resolution_center_case:read permission.", "items": { "description": "A resolution center case is a dispute or support case between a user and a company, tracking the issue, status, and outcome.", "properties": { "customer_appealed": { "description": "Whether the customer has filed an appeal after the initial resolution decision.", "type": "boolean" }, "customer_response_actions": { "description": "The list of actions currently available to the customer.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseCustomerResponses" }, "type": "array" }, "due_date": { "description": "The deadline by which the next response is required. Null if no deadline is currently active. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the resolution.", "example": "reso_xxxxxxxxxxxxx", "type": "string" }, "issue": { "$ref": "#/components/schemas/ResolutionCenterCaseIssueTypes", "description": "The category of the dispute." }, "merchant_appealed": { "description": "Whether the merchant has filed an appeal after the initial resolution decision.", "type": "boolean" }, "merchant_response_actions": { "description": "The list of actions currently available to the merchant.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseMerchantResponses" }, "type": "array" }, "platform_response_actions": { "description": "The list of actions currently available to the Whop platform for moderating this resolution.", "items": { "$ref": "#/components/schemas/ResolutionCenterCasePlatformResponses" }, "type": "array" }, "status": { "$ref": "#/components/schemas/ResolutionCenterCaseStatuses", "description": "The current status of the resolution case, indicating which party needs to respond or if the case is closed." } }, "required": [ "id", "status", "due_date", "issue", "customer_appealed", "merchant_appealed", "customer_response_actions", "merchant_response_actions", "platform_response_actions" ], "type": "object" }, "type": [ "array", "null" ] }, "retryable": { "description": "True when the payment status is `open` and its membership is in one of the retry-eligible states (`active`, `trialing`, `completed`, or `past_due`), or when it is a failed initial billing-engine payment on a `drafted` membership with an unlimited-stock plan; otherwise false. Used to decide if Whop can attempt the charge again.", "type": "boolean" }, "risk_score": { "description": "Whop's in-house fraud risk score for this payment, from 0 (lowest risk) to 100 (highest risk). Null when the payment has not been scored or scoring has not yet completed.", "example": 42, "type": [ "integer", "null" ] }, "risk_signals": { "additionalProperties": true, "description": "Deprecated. Always null.", "type": [ "object", "null" ] }, "settlement_amount": { "description": "The total amount charged to the customer for this payment, including taxes and after any discounts. In the currency specified by the currency field.", "example": 6.9, "type": "number" }, "settlement_currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "settlement_exchange_rate": { "description": "Deprecated. Always returns null.", "example": 6.9, "type": [ "number", "null" ] }, "settlement_time_at": { "description": "When this payment's funds post to the company's available balance, at midnight UTC. Known at payment time and never changes. The `financial_activity.funds_available` webhook's `posted_at` carries the same value when the settlement that clears it posts — match them to know these funds are now withdrawable.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "shipment": { "description": "The shipment attached to this payment.", "properties": { "carrier": { "description": "The shipping carrier detected for this shipment. Null until a tracking update identifies it.", "example": "usps", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the shipment.", "example": "ship_xxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/ShipmentStatuses", "description": "The current delivery status of this shipment." }, "tracking_number": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "9400111899223456789012", "type": "string" }, "tracking_url": { "description": "A customer-facing URL to track this shipment's progress.", "example": "https://track.aftership.com/9400111899223456789012", "type": "string" } }, "required": [ "id", "status", "tracking_number", "carrier", "tracking_url" ], "type": [ "object", "null" ] }, "shipping_address": { "description": "The shipping address provided by the customer for physical goods. Null if no shipping address was collected.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "sku": { "description": "The stock keeping unit of the variant this payment charged for (the first item, on a cart), as set by the seller. Accounts with billing-reason SKU suffixes enabled receive it stamped with why the charge happened: `-S` for a first subscription charge, `-R` for a renewal, `-C` for a one-time purchase, `-U` when the payment's own metadata carries `upsell: true`, `-F` when nothing was charged. Other billing reasons carry the bare SKU. Null when the variant has no SKU.", "type": [ "string", "null" ] }, "status": { "description": "The current lifecycle state of this payment (e.g., 'draft', 'open', 'paid', 'void').", "oneOf": [ { "$ref": "#/components/schemas/ReceiptStatus" }, { "type": "null" } ] }, "substatus": { "$ref": "#/components/schemas/FriendlyReceiptStatus", "description": "The friendly status of the payment." }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "tax_amount": { "description": "The calculated amount of the sales/VAT tax (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "tax_behavior": { "description": "The type of tax inclusivity applied to the payment, for determining whether the tax is included in the final price, or paid on top.", "oneOf": [ { "$ref": "#/components/schemas/ReceiptTaxBehaviors" }, { "type": "null" } ] }, "tax_refunded_amount": { "description": "The amount of tax that has been refunded (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "three_ds_verified": { "description": "Whether 3D Secure authentication was completed for this payment.", "type": "boolean" }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "updated_at": { "description": "The datetime the payment was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] }, "verification_checks": { "description": "The issuer's address and card security code check results for this payment. Null when the processor returned none.", "properties": { "address_line1": { "description": "Whether the billing street address the customer entered matched the address the issuer has on file.", "type": [ "string", "null" ] }, "authorization_code": { "description": "The card issuer's authorization code for this charge. Null when the processor did not return one.", "type": [ "string", "null" ] }, "card_holder_name": { "description": "Whether the cardholder name the customer entered matched the name the issuer has on file.", "type": [ "string", "null" ] }, "card_security_code": { "description": "Whether the CVV / CVC the customer entered matched the card.", "type": [ "string", "null" ] }, "zip_code": { "description": "Whether the billing postal code the customer entered matched the postal code the issuer has on file.", "type": [ "string", "null" ] } }, "required": [ "address_line1", "zip_code", "card_holder_name", "card_security_code", "authorization_code" ], "type": [ "object", "null" ] }, "voidable": { "description": "True when the payment can be voided or canceled. The request is rejected if the payment is no longer eligible.", "type": "boolean" } }, "required": [ "id", "status", "substatus", "refundable", "retryable", "voidable", "created_at", "updated_at", "paid_at", "last_payment_attempt", "next_payment_attempt", "dispute_alerted_at", "refunded_at", "plan", "product", "user", "membership", "member", "customer_phone", "payment_instrument", "payment_method", "company", "promo_code", "currency", "settlement_currency", "total", "subtotal", "usd_total", "refunded_amount", "auto_refunded", "amount_after_fees", "application_fee", "card_brand", "card_last4", "billing_address", "shipping_address", "needs_tracking", "shipment", "payment_method_type", "billing_reason", "sku", "payments_failed", "tax_amount", "tax_behavior", "failure_message", "decline_code", "metadata", "checkout_configuration_id", "recovery_url", "settlement_time_at", "settlement_amount", "settlement_exchange_rate", "tax_refunded_amount", "fees", "card_exp_month", "card_exp_year", "financing_installments_count", "financing_transactions", "refunds", "disputes", "resolutions", "risk_score", "risk_signals", "three_ds_verified", "verification_checks" ], "type": "object" }, "PaymentListItem": { "description": "A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.", "properties": { "amount_after_fees": { "description": "How much the payment is for after fees", "example": 6.9, "type": "number" }, "application_fee": { "description": "The application fee charged on this payment.", "properties": { "amount": { "description": "The application fee amount.", "example": 6.9, "type": "number" }, "amount_captured": { "description": "The amount of the application fee that has been captured.", "example": 6.9, "type": "number" }, "amount_refunded": { "description": "The amount of the application fee that has been refunded.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the application fee was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency of the application fee." }, "id": { "description": "The unique identifier for the application fee.", "example": "apfee_xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "amount", "amount_captured", "amount_refunded", "currency", "created_at" ], "type": [ "object", "null" ] }, "auto_refunded": { "description": "Whether this payment was auto refunded or not", "type": "boolean" }, "billing_address": { "description": "The address of the user who made the payment.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The ID of the checkout session/configuration that produced this payment, if any. Use this to map payments back to the checkout configuration that created them.", "example": "ch_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "company": { "description": "The company for the payment.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "The slug/route of the company on the Whop site.", "type": "string" }, "title": { "description": "The written name of the company.", "type": "string" } }, "required": [ "id", "title", "route" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "customer_phone": { "description": "Phone number the customer provided at checkout, or their verified phone number when your checkout requires phone verification. `null` when no phone number was collected.", "type": [ "string", "null" ] }, "decline_code": { "description": "The reason the payment was declined. Null if the payment did not fail.", "oneOf": [ { "$ref": "#/components/schemas/PaymentDeclineCodes" }, { "type": "null" } ] }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "failure_message": { "description": "If the payment failed, the reason for the failure.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last_payment_attempt": { "description": "The time of the last payment attempt.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "phone_number": { "description": "The phone number associated with this membership.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status", "phone_number" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "The custom metadata stored on this payment. This will be copied over to the checkout configuration for which this payment was made", "type": [ "object", "null" ] }, "needs_tracking": { "description": "Whether this payment is holding funds until the order ships and has no tracking number yet.", "type": [ "boolean", "null" ] }, "next_payment_attempt": { "description": "The time of the next schedule payment retry.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_instrument": { "description": "The instrument this payment was made with, shaped for display: the method type, a buyer-facing name, the standard icon set, and the card facts when it was a card. Null when the receipt names no payment method.", "properties": { "card": { "description": "Card payments only: the card's network and last four.", "properties": { "brand": { "description": "The network identifier (`visa`, `amex`, …), matching `card.networks` entries and saved card payment methods.", "type": "string" }, "last4": { "description": "The card's last four digits, when captured.", "type": [ "string", "null" ] } }, "required": [ "brand", "last4" ], "type": [ "object", "null" ] }, "display_name": { "description": "Buyer-facing instrument name — \"Visa •••• 4242\" when the card surfaced, else the method's own name (\"Klarna\").", "type": "string" }, "icons": { "description": "The standard icon set: square and card shapes, each in light and dark colorways.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "installment_count": { "description": "Installment methods only: how many payments the charge splits into. Data, not copy — compose and translate the label client-side.", "example": 42, "type": [ "integer", "null" ] }, "payment_method_type": { "description": "The payment method type identifier, e.g. `card`, `klarna`, `apple_pay`.", "type": "string" } }, "required": [ "payment_method_type", "display_name", "installment_count", "card", "icons" ], "type": [ "object", "null" ] }, "payment_method": { "description": "The tokenized payment method reference used for this payment. Null if no token was used.", "properties": { "card": { "description": "The card data associated with the payment method, if its a debit or credit card.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "fingerprint": { "description": "A stable identifier for the underlying card. Two payment methods with the same fingerprint are the same card. Null if not available.", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "fingerprint", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment token.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The payment method type of the payment method" } }, "required": [ "id", "created_at", "payment_method_type", "card" ], "type": [ "object", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "payments_failed": { "description": "The number of failed payment attempts for the payment.", "example": 42, "type": [ "integer", "null" ] }, "plan": { "description": "The plan attached to this payment.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "internal_notes": { "description": "A personal description or notes section for the business.", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "type": [ "object", "null" ] } }, "required": [ "id", "internal_notes", "metadata" ], "type": [ "object", "null" ] }, "product": { "description": "The product this payment was made for", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "type": [ "object", "null" ] }, "route": { "description": "URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" } }, "required": [ "id", "title", "route", "metadata" ], "type": [ "object", "null" ] }, "promo_code": { "description": "The promo code used for this payment.", "properties": { "amount_off": { "description": "The discount amount. Interpretation depends on promo_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat_amount', this is dollars off (e.g., 10.00 means $10.00 off).", "example": 6.9, "type": "number" }, "base_currency": { "$ref": "#/components/schemas/Currencies", "description": "The monetary currency of the promo code." }, "code": { "description": "The specific code used to apply the promo at checkout.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the promo code.", "example": "promo_xxxxxxxxxxxx", "type": "string" }, "number_of_intervals": { "description": "The number of months the promo is applied for.", "example": 42, "type": [ "integer", "null" ] }, "promo_type": { "$ref": "#/components/schemas/PromoTypes", "description": "The type (% or flat amount) of the promo." } }, "required": [ "id", "code", "amount_off", "base_currency", "promo_type", "number_of_intervals" ], "type": [ "object", "null" ] }, "refundable": { "description": "True only for payments that are `paid`, have not been fully refunded, and were processed by a payment processor that allows refunds.", "type": "boolean" }, "refunded_amount": { "description": "The payment refund amount(if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "refunded_at": { "description": "When the payment was refunded (if applicable).", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "retryable": { "description": "True when the payment status is `open` and its membership is in one of the retry-eligible states (`active`, `trialing`, `completed`, or `past_due`), or when it is a failed initial billing-engine payment on a `drafted` membership with an unlimited-stock plan; otherwise false. Used to decide if Whop can attempt the charge again.", "type": "boolean" }, "settlement_currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "shipment": { "description": "The shipment attached to this payment.", "properties": { "carrier": { "description": "The shipping carrier detected for this shipment. Null until a tracking update identifies it.", "example": "usps", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the shipment.", "example": "ship_xxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/ShipmentStatuses", "description": "The current delivery status of this shipment." }, "tracking_number": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "9400111899223456789012", "type": "string" }, "tracking_url": { "description": "A customer-facing URL to track this shipment's progress.", "example": "https://track.aftership.com/9400111899223456789012", "type": "string" } }, "required": [ "id", "status", "tracking_number", "carrier", "tracking_url" ], "type": [ "object", "null" ] }, "shipping_address": { "description": "The shipping address provided by the customer for physical goods. Null if no shipping address was collected.", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "sku": { "description": "The stock keeping unit of the variant this payment charged for (the first item, on a cart), as set by the seller. Accounts with billing-reason SKU suffixes enabled receive it stamped with why the charge happened: `-S` for a first subscription charge, `-R` for a renewal, `-C` for a one-time purchase, `-U` when the payment's own metadata carries `upsell: true`, `-F` when nothing was charged. Other billing reasons carry the bare SKU. Null when the variant has no SKU.", "type": [ "string", "null" ] }, "status": { "description": "The current lifecycle state of this payment (e.g., 'draft', 'open', 'paid', 'void').", "oneOf": [ { "$ref": "#/components/schemas/ReceiptStatus" }, { "type": "null" } ] }, "substatus": { "$ref": "#/components/schemas/FriendlyReceiptStatus", "description": "The friendly status of the payment." }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "tax_amount": { "description": "The calculated amount of the sales/VAT tax (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "tax_behavior": { "description": "The type of tax inclusivity applied to the payment, for determining whether the tax is included in the final price, or paid on top.", "oneOf": [ { "$ref": "#/components/schemas/ReceiptTaxBehaviors" }, { "type": "null" } ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "updated_at": { "description": "The datetime the payment was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] }, "voidable": { "description": "True when the payment can be voided or canceled. The request is rejected if the payment is no longer eligible.", "type": "boolean" } }, "required": [ "id", "status", "substatus", "refundable", "retryable", "voidable", "created_at", "updated_at", "paid_at", "last_payment_attempt", "next_payment_attempt", "dispute_alerted_at", "refunded_at", "plan", "product", "user", "membership", "member", "customer_phone", "payment_instrument", "payment_method", "company", "promo_code", "currency", "settlement_currency", "total", "subtotal", "usd_total", "refunded_amount", "auto_refunded", "amount_after_fees", "application_fee", "card_brand", "card_last4", "billing_address", "shipping_address", "needs_tracking", "shipment", "payment_method_type", "billing_reason", "sku", "payments_failed", "tax_amount", "tax_behavior", "failure_message", "decline_code", "metadata", "checkout_configuration_id" ], "type": "object" }, "PaymentMethod": { "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "A saved payment method with no type-specific details available.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "BasePaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons" ], "title": "BasePaymentMethod", "type": "object" }, { "description": "A saved card payment method, including brand, last four digits, and expiration details.", "properties": { "card": { "description": "The card-specific details for this payment method, including brand, last four digits, and expiration.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "expired": { "description": "Whether the card is past its expiration month. An expired card cannot take a new charge.", "type": "boolean" }, "fingerprint": { "description": "A stable identifier for the underlying card. Two payment methods with the same fingerprint are the same card. Null if not available.", "type": [ "string", "null" ] }, "funding_type": { "description": "How the card is funded by the issuer. Null if the funding type could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardFundingTypes" }, { "type": "null" } ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] }, "three_ds_verified": { "description": "Whether this card was verified with 3D Secure, either when it was saved or on a payment that used it.", "type": "boolean" } }, "required": [ "brand", "fingerprint", "last4", "exp_month", "exp_year", "funding_type", "expired", "three_ds_verified" ], "type": "object" }, "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "has_payer_document": { "description": "Whether this card has the payer identity document required by its payment provider.", "type": "boolean" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "CardPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "has_payer_document", "card" ], "title": "CardPaymentMethod", "type": "object" }, { "description": "A saved US bank account payment method, including bank name, last four digits, and account type.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "UsBankAccountPaymentMethod", "description": "The typename of this object", "type": "string" }, "us_bank_account": { "description": "The bank account-specific details for this payment method, including bank name and last four digits.", "properties": { "account_type": { "description": "The type of bank account (e.g., checking, savings).", "example": "checking", "type": [ "string", "null" ] }, "bank_name": { "description": "The name of the financial institution holding the account.", "example": "Chase", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the bank account number.", "example": "6789", "type": [ "string", "null" ] } }, "required": [ "bank_name", "last4", "account_type" ], "type": "object" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "us_bank_account" ], "title": "UsBankAccountPaymentMethod", "type": "object" }, { "description": "A saved Cash App payment method, including the buyer's cashtag and unique identifier.", "properties": { "cashapp": { "description": "The Cash App-specific details for this payment method, including cashtag and buyer ID.", "properties": { "buyer_id": { "description": "The unique and immutable identifier assigned by Cash App to the buyer. Null if not available.", "example": "BUYER_abc123", "type": [ "string", "null" ] }, "cashtag": { "description": "The public cashtag handle of the buyer on Cash App. Null if not available.", "example": "$jacksmith", "type": [ "string", "null" ] } }, "required": [ "buyer_id", "cashtag" ], "type": "object" }, "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "CashappPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "cashapp" ], "title": "CashappPaymentMethod", "type": "object" }, { "description": "A saved iDEAL payment method, including the customer's bank name and BIC code.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "ideal": { "description": "The iDEAL-specific details for this payment method, including bank name and BIC.", "properties": { "bank": { "description": "The name of the customer's bank used for the iDEAL transaction. Null if not available.", "example": "ing", "type": [ "string", "null" ] }, "bic": { "description": "The Bank Identifier Code (BIC/SWIFT) of the customer's bank. Null if not available.", "example": "INGBNL2A", "type": [ "string", "null" ] } }, "required": [ "bank", "bic" ], "type": "object" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "IdealPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "ideal" ], "title": "IdealPaymentMethod", "type": "object" }, { "description": "A saved SEPA Direct Debit payment method, including the bank code, country, and last four IBAN digits.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "sepa_debit": { "description": "The SEPA Direct Debit-specific details for this payment method, including bank code and last four IBAN digits.", "properties": { "bank_code": { "description": "The bank code of the financial institution associated with this SEPA account. Null if not available.", "example": "37040044", "type": [ "string", "null" ] }, "branch_code": { "description": "The branch code of the financial institution associated with this SEPA account. Null if not available.", "example": "0532", "type": [ "string", "null" ] }, "country": { "description": "The two-letter ISO country code where the bank account is located. Null if not available.", "example": "DE", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the IBAN associated with this SEPA account. Null if not available.", "example": "3000", "type": [ "string", "null" ] } }, "required": [ "bank_code", "branch_code", "country", "last4" ], "type": "object" }, "typename": { "const": "SepaDebitPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "sepa_debit" ], "title": "SepaDebitPaymentMethod", "type": "object" } ], "type": "object" }, "PaymentMethodDisplay": { "properties": { "bank_debit": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Present when the category is `bank_debit`. Empty until the account is charged." }, "card": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Details of the card, when the category is `card`." }, "category": { "description": "The family the type belongs to.", "enum": [ "card", "wallet", "bank_debit", "bank_transfer", "voucher", "redirect", "crypto", "balance", "in_app_purchase", "card_present", "saved" ], "example": "saved", "type": "string" }, "display_name": { "description": "Human-readable label for the method, e.g. `Visa •••• 4242`.", "example": "Visa •••• 4242", "type": "string" }, "id": { "description": "The saved payment method this preview came from, or `null` when the buyer supplied a new one.", "example": "payt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "saved": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Details of the stored card, when the category is `saved`. Absent for a balance." }, "type": { "description": "The payment method type, e.g. `card`, `apple_pay`, `klarna`.", "example": "card", "type": "string" }, "wallet": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Details of the network token the wallet supplied, when the category is `wallet`." } }, "required": [ "id", "type", "category", "display_name" ], "type": "object" }, "PaymentMethodDisplayPreview": { "properties": { "brand": { "description": "Lowercase card brand, such as `visa` or `mastercard`.", "example": "visa", "type": "string" }, "fingerprint": { "description": "Uniquely identifies this particular card number. Matches the `fingerprint` on any payment method saved from this token, so you can recognize a card across attempts. For a wallet, this identifies the network token rather than the underlying card.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "The last four digits of the card.", "example": "4242", "type": "string" } }, "required": [], "type": "object" }, "PaymentMethodDomain": { "properties": { "account_id": { "description": "ID of the account the domain is registered for, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "created_at": { "description": "When the domain was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "hostname": { "description": "Hostname the checkout is served from (e.g. `checkout.example.com`).", "example": "checkout.shinetime.com", "type": "string" }, "id": { "description": "Payment method domain ID: the ID of the account's domain for the hostname, prefixed `dom_`, or `pmd_` for some older domains.", "example": "dom_xxxxxxxxxxxxxx", "type": "string" }, "provider": { "description": "Wallet provider the domain is registered with.", "enum": [ "apple" ], "example": "apple", "type": "string" }, "status": { "description": "Verification status. `pending` means the provider could not fetch the domain-association file yet; only `verified` domains show wallet payment methods at checkout.", "enum": [ "pending", "verified" ], "example": "verified", "type": "string" }, "updated_at": { "description": "When the domain was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "account_id", "hostname", "provider", "status", "created_at", "updated_at" ], "type": "object" }, "PaymentMethodIconFiles": { "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "example": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "example": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "example": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "example": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "PaymentMethodIconVariants": { "properties": { "dark": { "$ref": "#/components/schemas/PaymentMethodIconFiles", "description": "The colorway for dark surfaces." }, "light": { "$ref": "#/components/schemas/PaymentMethodIconFiles", "description": "The colorway for light surfaces." } }, "required": [ "light", "dark" ], "type": "object" }, "PaymentMethodIcons": { "properties": { "card": { "$ref": "#/components/schemas/PaymentMethodIconVariants", "description": "The credit-card-proportioned tile (48x30)." }, "square": { "$ref": "#/components/schemas/PaymentMethodIconVariants", "description": "The square tile (32x32)." } }, "required": [ "square", "card" ], "type": "object" }, "PaymentMethodListItem": { "discriminator": { "propertyName": "typename" }, "oneOf": [ { "description": "A saved payment method with no type-specific details available.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "BasePaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons" ], "title": "BasePaymentMethod", "type": "object" }, { "description": "A saved card payment method, including brand, last four digits, and expiration details.", "properties": { "card": { "description": "The card-specific details for this payment method, including brand, last four digits, and expiration.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "expired": { "description": "Whether the card is past its expiration month. An expired card cannot take a new charge.", "type": "boolean" }, "fingerprint": { "description": "A stable identifier for the underlying card. Two payment methods with the same fingerprint are the same card. Null if not available.", "type": [ "string", "null" ] }, "funding_type": { "description": "How the card is funded by the issuer. Null if the funding type could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardFundingTypes" }, { "type": "null" } ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] }, "three_ds_verified": { "description": "Whether this card was verified with 3D Secure, either when it was saved or on a payment that used it.", "type": "boolean" } }, "required": [ "brand", "fingerprint", "last4", "exp_month", "exp_year", "funding_type", "expired", "three_ds_verified" ], "type": "object" }, "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "has_payer_document": { "description": "Whether this card has the payer identity document required by its payment provider.", "type": "boolean" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "CardPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "has_payer_document", "card" ], "title": "CardPaymentMethod", "type": "object" }, { "description": "A saved US bank account payment method, including bank name, last four digits, and account type.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "UsBankAccountPaymentMethod", "description": "The typename of this object", "type": "string" }, "us_bank_account": { "description": "The bank account-specific details for this payment method, including bank name and last four digits.", "properties": { "account_type": { "description": "The type of bank account (e.g., checking, savings).", "example": "checking", "type": [ "string", "null" ] }, "bank_name": { "description": "The name of the financial institution holding the account.", "example": "Chase", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the bank account number.", "example": "6789", "type": [ "string", "null" ] } }, "required": [ "bank_name", "last4", "account_type" ], "type": "object" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "us_bank_account" ], "title": "UsBankAccountPaymentMethod", "type": "object" }, { "description": "A saved Cash App payment method, including the buyer's cashtag and unique identifier.", "properties": { "cashapp": { "description": "The Cash App-specific details for this payment method, including cashtag and buyer ID.", "properties": { "buyer_id": { "description": "The unique and immutable identifier assigned by Cash App to the buyer. Null if not available.", "example": "BUYER_abc123", "type": [ "string", "null" ] }, "cashtag": { "description": "The public cashtag handle of the buyer on Cash App. Null if not available.", "example": "$jacksmith", "type": [ "string", "null" ] } }, "required": [ "buyer_id", "cashtag" ], "type": "object" }, "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "CashappPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "cashapp" ], "title": "CashappPaymentMethod", "type": "object" }, { "description": "A saved iDEAL payment method, including the customer's bank name and BIC code.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "ideal": { "description": "The iDEAL-specific details for this payment method, including bank name and BIC.", "properties": { "bank": { "description": "The name of the customer's bank used for the iDEAL transaction. Null if not available.", "example": "ing", "type": [ "string", "null" ] }, "bic": { "description": "The Bank Identifier Code (BIC/SWIFT) of the customer's bank. Null if not available.", "example": "INGBNL2A", "type": [ "string", "null" ] } }, "required": [ "bank", "bic" ], "type": "object" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "typename": { "const": "IdealPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "ideal" ], "title": "IdealPaymentMethod", "type": "object" }, { "description": "A saved SEPA Direct Debit payment method, including the bank code, country, and last four IBAN digits.", "properties": { "created_at": { "description": "The time of the event in ISO 8601 UTC format with millisecond precision", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "icons": { "description": "Every rendition of the icon to display this payment method with. A saved card carries its brand's icon (Visa, Mastercard, ...) rather than the generic card art.", "properties": { "card": { "description": "The credit-card-proportioned tile (48x30).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" }, "square": { "description": "The square tile (32x32).", "properties": { "dark": { "description": "The colorway for dark surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" }, "light": { "description": "The colorway for light surfaces.", "properties": { "png_1x": { "description": "Raster fallback at the shape's native size.", "type": "string" }, "png_2x": { "description": "Raster fallback at double density.", "type": "string" }, "png_4x": { "description": "Raster fallback at quadruple density.", "type": "string" }, "svg": { "description": "The vector file. Prefer this everywhere SVG renders.", "type": "string" } }, "required": [ "svg", "png_1x", "png_2x", "png_4x" ], "type": "object" } }, "required": [ "light", "dark" ], "type": "object" } }, "required": [ "square", "card" ], "type": "object" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The type of payment instrument stored on file (e.g., card, us_bank_account, cashapp, ideal, sepa_debit)." }, "sepa_debit": { "description": "The SEPA Direct Debit-specific details for this payment method, including bank code and last four IBAN digits.", "properties": { "bank_code": { "description": "The bank code of the financial institution associated with this SEPA account. Null if not available.", "example": "37040044", "type": [ "string", "null" ] }, "branch_code": { "description": "The branch code of the financial institution associated with this SEPA account. Null if not available.", "example": "0532", "type": [ "string", "null" ] }, "country": { "description": "The two-letter ISO country code where the bank account is located. Null if not available.", "example": "DE", "type": [ "string", "null" ] }, "last4": { "description": "The last four digits of the IBAN associated with this SEPA account. Null if not available.", "example": "3000", "type": [ "string", "null" ] } }, "required": [ "bank_code", "branch_code", "country", "last4" ], "type": "object" }, "typename": { "const": "SepaDebitPaymentMethod", "description": "The typename of this object", "type": "string" } }, "required": [ "typename", "id", "created_at", "payment_method_type", "icons", "sepa_debit" ], "title": "SepaDebitPaymentMethod", "type": "object" } ], "type": "object" }, "PaymentMethodTypes": { "description": "The different types of payment methods that can be used.", "enum": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alipay", "alipayhk", "alma", "amazon_pay", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_present", "card_installments_three", "card_installments_six", "card_installments_twelve", "cashapp", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "duitnow_qr", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "giropay", "google_pay", "gopay", "grabpay", "id_bank_transfer", "ideal", "interac", "kakao_pay", "klarna", "klarna_pay_now", "konbini", "kr_card", "kr_market", "kriya", "kueski", "link", "mb_way", "m_pesa", "mercado_pago", "mercado_pago_ar", "mercado_pago_mx", "mobilepay", "modo", "mondu", "multibanco", "naver_pay", "nequi", "netbanking", "ng_bank", "ng_bank_transfer", "ng_card", "ng_market", "ng_ussd", "ng_wallet", "nupay", "nz_bank_account", "oney", "oney_3x", "oney_4x", "opay", "oxxo", "p24", "pago_efectivo", "pse", "pay_by_bank", "payco", "paynow", "paypal", "paypal_express", "paypay", "payto", "payto_email", "payto_phone", "payto_bank_account", "pix", "platform_balance", "promptpay", "qris", "rapipago", "rechnung", "revolut_pay", "samsung_pay", "satispay", "scalapay", "sencillito", "sepa_debit", "sequra", "servipag", "sezzle", "shop_pay", "shopeepay", "sofort", "south_korea_market", "spei", "splitit", "sunbit", "swish", "tabby", "tamara", "touch_n_go", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "verve", "vipps", "webpay", "wechat_pay", "whop_pay", "yape", "zip", "coinflow", "unknown" ], "example": "acss_debit", "type": "string" }, "PaymentNextAction": { "description": "What the buyer must do to finish. `type` picks the shape and each type carries only its own `data`, so switching on `type` gives you exactly that step's payload.", "discriminator": { "mapping": { "await_confirmation": "#/components/schemas/PaymentNextActionAwaitConfirmation", "collect_card_present": "#/components/schemas/PaymentNextActionCollectCardPresent", "display_instructions": "#/components/schemas/PaymentNextActionDisplayInstructions", "redirect": "#/components/schemas/PaymentNextActionRedirect" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/PaymentNextActionRedirect" }, { "$ref": "#/components/schemas/PaymentNextActionDisplayInstructions" }, { "$ref": "#/components/schemas/PaymentNextActionAwaitConfirmation" }, { "$ref": "#/components/schemas/PaymentNextActionCollectCardPresent" } ] }, "PaymentNextActionAwaitConfirmation": { "properties": { "data": { "$ref": "#/components/schemas/PaymentNextActionAwaitConfirmationData", "description": "How long the wait can last." }, "render": { "items": { "description": "Where this step can be presented: `inline` inside your own page, `full_page` as a top-level navigation. Pick whichever listed mode suits your surface.", "enum": [ "inline", "full_page" ], "example": "inline", "type": "string" }, "type": "array" }, "type": { "description": "Always `await_confirmation`: nothing to show — the buyer has done their part and the rail settles out of band. Poll `status` until it moves.", "enum": [ "await_confirmation" ], "example": "await_confirmation", "type": "string" } }, "required": [ "type", "render", "data" ], "title": "Await confirmation", "type": "object" }, "PaymentNextActionAwaitConfirmationData": { "properties": { "expires_at": { "description": "When the confirmation window closes, as an ISO 8601 timestamp. A payment still unconfirmed by then will not succeed — watch `status` for the failed attempt.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "expires_at" ], "type": "object" }, "PaymentNextActionCollectCardPresent": { "properties": { "data": { "$ref": "#/components/schemas/PaymentNextActionCollectCardPresentData", "description": "What the Terminal SDK needs to collect this payment." }, "type": { "description": "Always `collect_card_present`: the buyer taps on the seller's reader. Hand `data.client_secret` to the Terminal SDK to collect and confirm the payment, then poll `status` until it moves.", "enum": [ "collect_card_present" ], "example": "collect_card_present", "type": "string" } }, "required": [ "type", "data" ], "title": "Collect card present", "type": "object" }, "PaymentNextActionCollectCardPresentData": { "properties": { "client_secret": { "description": "The Stripe PaymentIntent client secret the Terminal SDK retrieves, collects and confirms this payment with. Treat it as a credential: together with a card-present connection token it is what a device needs to take the payment.", "example": "pi_secret", "type": "string" } }, "required": [ "client_secret" ], "type": "object" }, "PaymentNextActionDisplayInstructions": { "properties": { "data": { "$ref": "#/components/schemas/PaymentInstructions", "description": "The instructions. `kind` picks the shape, and the details sit under the key named for it: `voucher`, `qr`, or `bank_transfer`." }, "render": { "items": { "description": "Where this step can be presented: `inline` inside your own page, `full_page` as a top-level navigation. Pick whichever listed mode suits your surface.", "enum": [ "inline", "full_page" ], "example": "inline", "type": "string" }, "type": "array" }, "type": { "description": "Always `display_instructions`: show the buyer `data` — what to pay, where, and by when. The payment completes once they pay and the rail confirms it, so keep polling `status`.", "enum": [ "display_instructions" ], "example": "display_instructions", "type": "string" } }, "required": [ "type", "render", "data" ], "title": "Display instructions", "type": "object" }, "PaymentNextActionRedirect": { "properties": { "data": { "$ref": "#/components/schemas/PaymentNextActionRedirectData", "description": "Where to send the buyer." }, "render": { "items": { "description": "Where this step can be presented: `inline` inside your own page, `full_page` as a top-level navigation. Pick whichever listed mode suits your surface.", "enum": [ "inline", "full_page" ], "example": "inline", "type": "string" }, "type": "array" }, "type": { "description": "Always `redirect`: send the buyer to `data.url`. The provider hands them back to `return_url` when they are done.", "enum": [ "redirect" ], "example": "redirect", "type": "string" } }, "required": [ "type", "render", "data" ], "title": "Redirect", "type": "object" }, "PaymentNextActionRedirectData": { "properties": { "frame_max_width": { "description": "The widest the provider's page lays out usefully, in CSS pixels — cap a frame or dialog presenting it at this width. `null` when the page fills whatever width it is given.", "example": 500, "type": [ "integer", "null" ] }, "url": { "description": "The provider's page for this payment, as an absolute URL — take the buyer there.", "example": "https://psp.example/3ds/challenge", "type": "string" } }, "required": [ "url", "frame_max_width" ], "type": "object" }, "PaymentPdf": { "properties": { "expires_at": { "description": "When the link stops working, as an ISO 8601 timestamp. Generate a new PDF for a fresh link.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "url": { "description": "A short-lived link to download the payment's receipt as a PDF. Anyone holding the link can download the file until it expires.", "example": "https://content.whop.com/exports/2026-01-01/pdfs/receipt_pay_xxxxxxxxxxxxxx.pdf", "type": "string" } }, "required": [ "url", "expires_at" ], "type": "object" }, "PaymentProcessingDetails": { "properties": { "expected_by": { "description": "When the payment is expected to settle, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "expected_by" ], "type": "object" }, "PaymentProviders": { "description": "The different payment providers.", "enum": [ "stripe", "coinbase", "paypal", "apple", "sezzle", "splitit", "platform_balance", "multi_psp", "adyen", "claritypay", "flex_pay", "checkout_dot_com", "airwallex", "coinflow", "sequra", "dlocal", "masspay", "braintree" ], "type": "string" }, "PaymentQr": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Exactly what the buyer must pay, in the charged currency." }, "document_url": { "description": "A hosted page with the complete, printable instructions. If you would rather not render the details yourself, send the buyer here.", "example": "https://psp.example/qr/shine-4417", "type": "string" }, "expires_at": { "description": "When the code stops being payable, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "key": { "description": "An account key the buyer can pay to directly (Colombia's Bre-B llave), for apps that take a key instead of a scan.", "example": "marcus@shinetime.example", "type": "string" }, "qr_code": { "description": "The QR code's contents, ready to render as a scannable image — `qr_format` says how it is encoded.", "example": "pix.shinetime.example/qr/dana-4417", "type": "string" }, "qr_format": { "description": "How `qr_code` is encoded.", "example": "url", "type": "string" } }, "required": [], "type": "object" }, "PaymentQrInstructions": { "properties": { "kind": { "description": "Always `qr`: a code the buyer scans with their banking app.", "enum": [ "qr" ], "example": "qr", "type": "string" }, "qr": { "$ref": "#/components/schemas/PaymentQr", "description": "The code to show." } }, "required": [ "kind", "qr" ], "title": "QR", "type": "object" }, "PaymentQuote": { "properties": { "account_id": { "description": "The account the purchase is priced for, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "address": { "description": "The billing address the purchase was priced with, or null. Where tax was calculated when no shipping address was given, and the address the registration belongs to.", "oneOf": [ { "$ref": "#/components/schemas/PaymentAddress" }, { "type": "null" } ] }, "base_currency": { "description": "Three-letter ISO 4217 code of the variants' own currency, lowercase. Equal to `currency` when nothing was converted.", "example": "usd", "type": "string" }, "base_total": { "$ref": "#/components/schemas/Money", "description": "`total` in `base_currency` at `exchange_rate`: the variants' own prices after the promo code, plus `tax_amount` converted at `exchange_rate` when tax is added on top. Equal to `total` when nothing was converted. The payment charges `total`, in `currency`." }, "created_at": { "description": "When the quote was priced, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO 4217 currency code the purchase is priced and charged in, lowercase: the variants' own currency, or the `presentment_currency` it was converted into.", "example": "usd", "type": "string" }, "discount": { "$ref": "#/components/schemas/Money", "description": "What the promo code takes off. Zero without a code." }, "exchange_rate": { "description": "How many units of `currency` one unit of `base_currency` buys, as a decimal string such as `\"5.4321\"`: the rate the variants' prices were converted at, fixed until `expires_at`, and the rate a payment consuming the quote is charged at. A string, like money amounts, so no float rounds it in transit. Null when nothing was converted.", "example": "0.918", "type": [ "string", "null" ] }, "expires_at": { "description": "When the quote stops being chargeable, as an ISO 8601 timestamp. Quote again after it.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Payment quote ID, prefixed `pq_`.", "example": "pq_xxxxxxxxxxxxxx", "type": "string" }, "line_items": { "items": { "$ref": "#/components/schemas/PaymentQuoteLineItem", "description": "One entry per variant, in the order given, each carrying its own tax." }, "type": "array" }, "located_by": { "description": "Which location tax was calculated for: `shipping_address` when it carries a country, else the billing `address` when it does, else the `presentment_country` sent, else the buyer's `ip_address`. A quote located by `presentment_country` or `ip_address` is a preview that estimates tax: a payment cannot use it, so quote again with the buyer's address to pay. Null when nothing in the request located the buyer, which only a seller that collects no tax on this purchase is quoted without; `tax_status` is then `not_applicable`.", "enum": [ "shipping_address", "address", "presentment_country", "ip_address", null ], "example": "address", "type": [ "string", "null" ] }, "payment_id": { "description": "The payment holding this quote, prefixed `pay_`, or null while it is unspent. A declined payment keeps its quote and can be retried; check that payment's `status`.", "example": "pay_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "promo_code_id": { "description": "The promo code the quote applied, prefixed `promo_`, or null.", "example": null, "type": [ "string", "null" ] }, "recommended_currencies": { "items": { "description": "Lowercase ISO 4217 codes to offer the buyer in a currency picker, most relevant first: the currency of the `presentment_country` sent, else of the country the buyer's `ip_address` is in, when this purchase can be converted into it and a payment method can collect it, then `base_currency`. Quote again with one as `presentment_currency` to price in it. Only `base_currency` when the quote was priced without `presentment_currency` or `presentment_country`.", "example": "usd", "type": "string" }, "type": "array" }, "shipping_address": { "description": "The shipping address the purchase was priced with, or null. When present it is where tax was calculated.", "oneOf": [ { "$ref": "#/components/schemas/PaymentAddress" }, { "type": "null" } ] }, "subtotal": { "$ref": "#/components/schemas/Money", "description": "The price of every line before the promo code, tax and fees." }, "tax_amount": { "$ref": "#/components/schemas/Money", "description": "The tax a payment consuming this quote charges. Zero unless `tax_status` is `calculated`." }, "tax_behavior": { "description": "Whether tax is added on top of the price (`exclusive`) or already inside it (`inclusive`). Null when no tax was calculated.", "enum": [ "inclusive", "exclusive", null ], "example": "exclusive", "type": [ "string", "null" ] }, "tax_ids": { "items": { "$ref": "#/components/schemas/TaxId", "description": "The buyer's tax registration the quote priced as a business purchase. Empty for a consumer purchase." }, "type": "array" }, "tax_status": { "description": "`calculated`: every line was priced and a payment may consume the quote. `not_applicable`: this seller collects no tax on this purchase, so the quote owes none and may still be consumed. `unavailable`: tax could not be priced — the provider did not answer, or this seller's tax setup cannot price a purchase here — so a payment refuses the quote; quote again, or charge without `quote_id` to have tax calculated at charge time.", "enum": [ "calculated", "not_applicable", "unavailable" ], "example": "calculated", "type": "string" }, "total": { "$ref": "#/components/schemas/Money", "description": "What the buyer pays: the subtotal less the discount, plus `tax_amount` when tax is added on top." } }, "required": [ "id", "account_id", "currency", "base_currency", "exchange_rate", "recommended_currencies", "tax_status", "tax_behavior", "subtotal", "discount", "tax_amount", "total", "base_total", "line_items", "promo_code_id", "located_by", "address", "shipping_address", "tax_ids", "payment_id", "expires_at", "created_at" ], "type": "object" }, "PaymentQuoteLineItem": { "properties": { "discount": { "$ref": "#/components/schemas/Money", "description": "The promo code's share on this line. Zero without a code." }, "quantity": { "description": "How many units of the variant the line covers.", "example": 1, "type": "integer" }, "subtotal": { "$ref": "#/components/schemas/Money", "description": "The line's price before the promo code's share and tax; `subtotal` minus `discount` is what the line comes to after the discount. The lines' subtotals sum to the quote's `subtotal`." }, "tax_amount": { "$ref": "#/components/schemas/Money", "description": "The tax on this line. Zero when `tax_status` is not `calculated`." }, "total": { "$ref": "#/components/schemas/Money", "description": "`subtotal` minus `discount`, plus `tax_amount` when tax is added on top, or without it when the price already includes it." }, "variant_id": { "description": "The variant this line prices, prefixed `plan_`. Null when the purchase describes the variant by `variant` and no variant with those attributes exists yet: the payment that consumes the quote creates it, and the line names it from then on.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "variant_id", "quantity", "subtotal", "discount", "tax_amount", "total" ], "type": "object" }, "PaymentRule": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "action": { "description": "What this account's rule requests when every condition matches. One applicable account-rule action wins, in this order: `allow`, `block`, `review`, `enforce_3ds`. An `allow` overrides this account's other rules, never Whop's own fraud controls. A `review` requests authorization without capture for an eligible on-session card payment through Whop Payments. Automatic capture is scheduled for 48 hours after authorization; capture or void the payment before then to decide sooner. Capture may complete later or fail. Review is skipped for unsupported methods, off-session payments, and payments already configured for manual capture. An `enforce_3ds` is skipped when the account rule cannot apply a challenge. Other 3DS requirements still apply.", "enum": [ "allow", "block", "review", "enforce_3ds" ], "example": "block", "type": "string" }, "conditions": { "$ref": "#/components/schemas/PaymentRuleConditions", "description": "The conditions a payment is matched against. Up to 10 conditions, and 8 KiB once serialized." }, "created_at": { "description": "When the rule was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "deleted_at": { "description": "When the rule was deleted, as an ISO 8601 timestamp. `null` unless `status` is `deleted`.", "example": null, "type": [ "string", "null" ] }, "id": { "description": "Payment rule ID, prefixed `prule_`.", "example": "prule_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom string-to-string values for your integration. Maximum 50 keys, 40 characters per key, 500 characters per value.", "example": {}, "type": "object" }, "name": { "description": "A name for this rule. Up to 255 characters.", "example": "Block high risk", "type": "string" }, "status": { "description": "Whether the rule is applied to payments. A `deleted` rule is kept so the payments it already decided still name it.", "enum": [ "active", "inactive", "deleted" ], "example": "active", "type": "string" }, "updated_at": { "description": "When the rule was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "account_id", "name", "status", "action", "conditions", "metadata", "created_at", "updated_at", "deleted_at" ], "type": "object" }, "PaymentRuleCondition": { "properties": { "field": { "description": "The payment attribute this condition reads.", "enum": [ "risk_score", "amount_in_usd", "card_country", "card_brand", "card_funding", "card_bin", "billing_country", "billing_postal_code", "billing_city", "customer_email", "email_domain", "ip_address", "ip_country" ], "example": "amount_in_usd", "type": "string" }, "operator": { "description": "How the payment attribute is compared to the value.", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "starts_with", "contains", "ends_with", "in_cidr" ], "example": "gte", "type": "string" }, "value": { "$ref": "#/components/schemas/PaymentRuleConditionValue", "description": "The value to compare against." } }, "required": [ "field", "operator", "value" ], "type": "object" }, "PaymentRuleConditionValue": { "description": "The value to compare against. A whole number from 0 to 100 for `risk_score`, a number of at least 0 for `amount_in_usd`, a string for the other fields, and an array of strings for the `in` and `not_in` operators.", "oneOf": [ { "minimum": 0, "type": "number" }, { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ] }, "PaymentRuleConditions": { "properties": { "all": { "items": { "$ref": "#/components/schemas/PaymentRuleCondition", "description": "Conditions that must all match for the rule to apply. A payment attribute the rule cannot read does not match." }, "type": "array" } }, "required": [ "all" ], "type": "object" }, "PaymentRuleField": { "properties": { "field": { "description": "The payment attribute this condition reads.", "enum": [ "risk_score", "amount_in_usd", "card_country", "card_brand", "card_funding", "card_bin", "billing_country", "billing_postal_code", "billing_city", "customer_email", "email_domain", "ip_address", "ip_country" ], "example": "risk_score", "type": "string" }, "maximum": { "description": "The largest value this field accepts, or `null` when the field is not numeric.", "example": 100, "type": [ "integer", "null" ] }, "minimum": { "description": "The smallest value this field accepts, or `null` when the field is not numeric.", "example": 0, "type": [ "integer", "null" ] }, "operators": { "items": { "description": "The operators this field accepts. Any other operator is rejected.", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "starts_with", "contains", "ends_with", "in_cidr" ], "example": "eq", "type": "string" }, "type": "array" }, "options": { "items": { "$ref": "#/components/schemas/PaymentRuleFieldOption", "description": "The values this field accepts, or `null` when the field is free-form." }, "type": [ "array", "null" ] }, "type": { "description": "The type of value this field compares against.", "enum": [ "integer", "number", "string" ], "example": "integer", "type": "string" } }, "required": [ "field", "type", "operators", "minimum", "maximum", "options" ], "type": "object" }, "PaymentRuleFieldOption": { "properties": { "label": { "description": "The name to display for this value.", "example": "Abkhazia", "type": "string" }, "value": { "description": "The value to send in a condition.", "example": "AB", "type": "string" } }, "required": [ "value", "label" ], "type": "object" }, "PaymentRuleMatch": { "properties": { "action": { "description": "What the rule asked for.", "enum": [ "allow", "block", "review", "enforce_3ds" ], "example": "allow", "type": "string" }, "id": { "description": "Payment rule ID, prefixed `prule_`.", "type": "string" }, "name": { "description": "The rule's name when it matched. Renaming the rule afterwards does not rewrite this.", "type": [ "string", "null" ] } }, "required": [ "id", "name", "action" ], "type": "object" }, "PaymentStatus": { "properties": { "account": { "description": "The account receiving this payment, or `null` when the payment has no associated account.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "auto_capture_at": { "description": "When Whop will capture this authorization automatically, as an ISO 8601 timestamp. `null` when no automatic capture was requested.", "example": null, "type": [ "string", "null" ] }, "capture_expires_at": { "description": "When the card authorization must be captured, as an ISO 8601 timestamp. `null` when this payment was not authorized for later capture.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "The payment this status describes, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last_payment_error": { "description": "Details of the most recent failed attempt, or `null` when the payment has not failed.", "oneOf": [ { "$ref": "#/components/schemas/PaymentLastPaymentError" }, { "type": "null" } ] }, "next_action": { "description": "What the buyer must do next while `status` is `requires_action`, otherwise `null`. `type` picks the shape and each variant carries only its own `data`, so switching on `type` gives you exactly that step's payload. The `collect_card_present` step is served only to a credential holding `payment:charge` on the account; any other reader sees `null` while the tap is outstanding.", "oneOf": [ { "$ref": "#/components/schemas/PaymentNextAction" }, { "type": "null" } ] }, "object": { "description": "Always `payment_status`.", "example": "payment_status", "type": "string" }, "processing_details": { "description": "Present while `status` is `processing` on a settlement rail, otherwise `null`. A `processing` status without it has not been decided yet — keep polling.", "oneOf": [ { "$ref": "#/components/schemas/PaymentProcessingDetails" }, { "type": "null" } ] }, "return_url": { "description": "Where to send the buyer once the payment reaches a resting state, or `null` to leave them where they are. Editable until they return — see the return_url operation.", "example": "https://shinetime.example/checkout/done", "type": [ "string", "null" ] }, "status": { "description": "How far the payment has got. `requires_confirmation` — nothing attempted yet, or the last attempt failed and can be retried. `requires_action` — the buyer has a step outstanding; see `next_action`. `requires_capture` — the card authorization is holding funds and must be captured. `confirming` — the buyer has done their part and the processor is deciding. `processing` — with `processing_details`, the money is moving; without them, the charge is still being decided and the status should be read again. `succeeded` — collected. `canceled` — voided or written off.", "enum": [ "requires_confirmation", "requires_action", "requires_capture", "confirming", "processing", "succeeded", "canceled" ], "example": "succeeded", "type": "string" } }, "required": [ "id", "object", "account", "status", "next_action", "processing_details", "last_payment_error", "return_url", "capture_expires_at", "auto_capture_at" ], "type": "object" }, "PaymentTransactionStatuses": { "description": "The different statuses a payment transaction can be in.", "enum": [ "succeeded", "declined", "error", "pending", "created", "expired", "won", "rejected", "lost", "prevented", "canceled" ], "type": "string" }, "PaymentTransactionTypes": { "description": "The different types of payment transactions.", "enum": [ "purchase", "authorize", "capture", "refund", "canceled", "verify", "chargeback", "pre_chargeback", "three_d_secure", "fraud_screening", "authorization", "installment", "deposit" ], "type": "string" }, "PaymentVerificationChecks": { "properties": { "address_line1": { "description": "The Address Verification Service (AVS) result for the billing street address.", "example": "PASS", "type": [ "string", "null" ] }, "arn": { "description": "The Acquirer Reference Number (ARN) that traces this charge through the card network, or null when the processor did not return one.", "example": "74123456789", "type": [ "string", "null" ] }, "authorization_code": { "description": "The card issuer's authorization code for this charge, or null when the processor did not return one.", "example": "A1B2C3", "type": [ "string", "null" ] }, "card_holder_name": { "description": "Whether the cardholder name matched the issuer's records.", "example": "PASS", "type": [ "string", "null" ] }, "card_security_code": { "description": "The Card Verification Value (CVV/CVC) result.", "example": "PASS", "type": [ "string", "null" ] }, "zip_code": { "description": "The Address Verification Service (AVS) result for the billing postal code.", "example": "PASS", "type": [ "string", "null" ] } }, "required": [ "address_line1", "zip_code", "card_holder_name", "card_security_code", "authorization_code", "arn" ], "type": "object" }, "PaymentVoucher": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Exactly what the buyer must pay, in the charged currency." }, "barcode": { "description": "The barcode's contents, when the voucher carries one — render it in the symbology named by `barcode_format`.", "example": "2379 1234 0560 0512 3401", "type": "string" }, "barcode_format": { "description": "The symbology `barcode` is encoded in, such as `CODE_128`.", "example": "CODE_128", "type": "string" }, "company_name": { "description": "Who the payment is made out to.", "example": "Shine Time Auto Detailing", "type": "string" }, "document_url": { "description": "A hosted page with the complete, printable instructions. If you would rather not render the details yourself, send the buyer here.", "example": "https://psp.example/vouchers/shine-0021-4479", "type": "string" }, "expires_at": { "description": "When the voucher stops being payable, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "provider_logo": { "description": "URL of that network's logo.", "example": "https://psp.example/logos/boleto.png", "type": "string" }, "provider_name": { "description": "The network the buyer pays at, such as OXXO.", "example": "Boleto Bancário", "type": "string" }, "reference": { "description": "The voucher's number — what the buyer reads out or types at the counter to pay.", "example": "0021-4479-8830-55", "type": "string" } }, "required": [], "type": "object" }, "PaymentVoucherInstructions": { "properties": { "kind": { "description": "Always `voucher`: a code the buyer pays in person, at a convenience store or bank counter.", "enum": [ "voucher" ], "example": "voucher", "type": "string" }, "voucher": { "$ref": "#/components/schemas/PaymentVoucher", "description": "The voucher to show." } }, "required": [ "kind", "voucher" ], "title": "Voucher", "type": "object" }, "PaymentsApprovalStatuses": { "description": "The different approval statuses an account can have.", "enum": [ "pending", "approved", "monitoring", "rejected" ], "type": "string" }, "PayoutAccount": { "description": "An object representing an account used for payouts.", "properties": { "address": { "description": "The physical address associated with this payout account", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "postal_code", "state", "country" ], "type": [ "object", "null" ] }, "business_name": { "description": "The company's legal name", "type": [ "string", "null" ] }, "business_representative": { "description": "The business representative for this payout account", "properties": { "date_of_birth": { "description": "The date of birth of the business representative in ISO 8601 format (YYYY-MM-DD).", "type": [ "string", "null" ] }, "first_name": { "description": "The first name of the business representative.", "type": [ "string", "null" ] }, "last_name": { "description": "The last name of the business representative.", "type": [ "string", "null" ] }, "middle_name": { "description": "The middle name of the business representative.", "type": [ "string", "null" ] } }, "required": [ "date_of_birth", "first_name", "middle_name", "last_name" ], "type": [ "object", "null" ] }, "email": { "description": "The email address of the representative", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payout account.", "example": "poact_xxxxxxxxxxxx", "type": "string" }, "latest_verification": { "description": "The latest verification for the connected account.", "properties": { "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "last_error_code", "last_error_reason" ], "type": [ "object", "null" ] }, "phone": { "description": "The business representative's phone", "type": [ "string", "null" ] }, "status": { "description": "The granular calculated status of the payout account reflecting its current KYC and payout readiness state.", "oneOf": [ { "$ref": "#/components/schemas/PayoutAccountCalculatedStatuses" }, { "type": "null" } ] } }, "required": [ "id", "status", "business_name", "phone", "email", "business_representative", "address", "latest_verification" ], "type": "object" }, "PayoutAccountCalculatedStatuses": { "description": "The granular calculated statuses reflecting payout account KYC and payout readiness.", "enum": [ "connected", "disabled", "action_required", "pending_verification", "verification_failed", "manual_review", "denied", "not_started", "blocked_by_parent" ], "type": "string" }, "PayoutDestinationCategory": { "description": "The category of a payout destination.", "enum": [ "crypto", "rtp", "next_day_bank", "bank_wire", "digital_wallet", "unknown" ], "type": "string" }, "PayoutMethod": { "description": "A configured payout destination where a user receives earned funds, such as a bank account or digital wallet.", "properties": { "account_reference": { "description": "A masked identifier for the payout destination, such as the last four digits of a bank account or an email address. Null if no reference is available.", "example": "****1234", "type": [ "string", "null" ] }, "company": { "description": "The company associated with this payout destination. Null if not linked to a specific company.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payout token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code that payouts are delivered in for this destination.", "example": "USD", "type": "string" }, "destination": { "description": "The payout destination configuration linked to this token. Null if not yet configured.", "properties": { "category": { "$ref": "#/components/schemas/PayoutDestinationCategory", "description": "The category of the payout destination" }, "country_code": { "description": "The country code of the payout destination", "type": "string" }, "name": { "description": "The name of the payer associated with the payout destination", "type": "string" } }, "required": [ "country_code", "category", "name" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the payout token.", "example": "potk_xxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "The name of the bank or financial institution receiving payouts. Null if not applicable or not provided.", "example": "Frost Bank", "type": [ "string", "null" ] }, "is_default": { "description": "Whether this is the default payout destination for the associated payout account.", "type": "boolean" }, "nickname": { "description": "A user-defined label to help identify this payout destination. Not sent to the provider. Null if no nickname has been set.", "example": "Ops checking", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "company", "nickname", "currency", "is_default", "account_reference", "institution_name", "destination" ], "type": "object" }, "PayoutMethodListItem": { "description": "A configured payout destination where a user receives earned funds, such as a bank account or digital wallet.", "properties": { "account_reference": { "description": "A masked identifier for the payout destination, such as the last four digits of a bank account or an email address. Null if no reference is available.", "example": "****1234", "type": [ "string", "null" ] }, "company": { "description": "The company associated with this payout destination. Null if not linked to a specific company.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payout token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code that payouts are delivered in for this destination.", "example": "USD", "type": "string" }, "destination": { "description": "The payout destination configuration linked to this token. Null if not yet configured.", "properties": { "category": { "$ref": "#/components/schemas/PayoutDestinationCategory", "description": "The category of the payout destination" }, "country_code": { "description": "The country code of the payout destination", "type": "string" }, "name": { "description": "The name of the payer associated with the payout destination", "type": "string" } }, "required": [ "country_code", "category", "name" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the payout token.", "example": "potk_xxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "The name of the bank or financial institution receiving payouts. Null if not applicable or not provided.", "example": "Frost Bank", "type": [ "string", "null" ] }, "is_default": { "description": "Whether this is the default payout destination for the associated payout account.", "type": "boolean" }, "nickname": { "description": "A user-defined label to help identify this payout destination. Not sent to the provider. Null if no nickname has been set.", "example": "Ops checking", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "company", "nickname", "currency", "is_default", "account_reference", "institution_name", "destination" ], "type": "object" }, "Permission": { "properties": { "action": { "description": "The permission action's identifier, for example `company:basic:read`.", "example": "waitlist_entry:cancel", "type": "string" }, "allowed_on_api_key": { "description": "Whether an API key can be granted the permission.", "example": true, "type": "boolean" }, "allowed_on_app": { "description": "Whether an app can request and be granted the permission.", "example": true, "type": "boolean" }, "allowed_on_user": { "description": "Whether the permission can be granted to user tokens.", "example": true, "type": "boolean" }, "category": { "description": "The category the action is grouped under, or `null` when uncategorized.", "example": null, "type": [ "string", "null" ] }, "description": { "description": "What granting the action allows.", "example": "", "type": "string" }, "granted_to_system_roles": { "items": { "description": "System roles that include the permission.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser", "partner" ], "example": "owner", "type": "string" }, "type": "array" }, "name": { "description": "Human-readable name of the action.", "example": "waitlist_entry:cancel", "type": "string" } }, "required": [ "action", "name", "description", "category", "allowed_on_user", "allowed_on_app", "allowed_on_api_key", "granted_to_system_roles" ], "type": "object" }, "PermissionAction": { "description": "A permission action identifier, such as `company:basic:read`.", "enum": [ "waitlist_entry:read", "waitlist_entry:create", "waitlist_entry:cancel", "review:delete", "experiment:manage", "experiment:read", "domain:manage", "domain:read", "email:manage", "email:read", "email:send", "ai_prompt:create", "access_pass:basic:export", "access_pass:basic:read", "access_pass:control_center", "access_pass:create", "access_pass:delete", "access_pass:stats:export", "access_pass:stats:read", "access_pass:update", "ad_campaign:basic:export", "ad_campaign:basic:read", "ad_campaign:conversion:create", "ad_campaign:create", "ad_campaign:credit:create", "ad_campaign:delete", "ad_campaign:read", "ad_campaign:stats:read", "ad_campaign:update", "ad_pixel:manage", "audience:basic:read", "audience:update", "ad_publisher:read", "affiliate:basic:read", "affiliate:create", "affiliate:update", "authorized_user:create", "authorized_user:delete", "authorized_user:update", "authorized_role:create", "authorized_role:update", "authorized_role:delete", "authorized_role:attach", "authorized_role:detach", "app_authorization:create", "app_authorization:read", "app_authorization:update", "app_authorization:delete", "bounty:basic:read", "bounty:create", "bounty:capture_clip:create", "bounty:capture_clip:complete", "bounty:capture_clip:discard", "bounty:update", "bounty:submission:create", "bounty:submission:delete", "bounty:submission:vote", "chat:manage_webhook", "chat:moderate", "chat:message:create", "chat:read", "dms:read", "dms:message:manage", "dms:channel:manage", "forum:post:create", "forum:read", "forum:moderate", "company:authorized_user:read", "company:authorized_user:email:read", "company:balance:read", "company:balance:export", "company_token_transaction:read", "company_token_transaction:create", "company:log:read", "company:manage_checkout", "company:manage_legal", "company:basic:read", "company:update", "company:transfer_ownership", "company:create", "company:create_child", "company:suspend_child", "company:delete", "company:delete_child", "company:update_child_fees", "child_company:basic:export", "social_account:create", "social_account:delete", "social_account:read", "social_link:update", "custom_emoji:update", "content_rewards:basic:export", "content_rewards:basic:read", "content_rewards:create", "content_rewards:delete", "content_rewards:moderate_submission", "content_rewards:update", "developer:basic:read", "developer:create_app", "developer:manage_api_key", "developer:manage_oauth", "developer:manage_webhook", "developer:logs:read", "developer:manage_builds", "developer:app_installation:read", "developer:app_installation:update", "developer:update_app", "developer:update_app_authorization", "event:create", "experience:attach", "experience:create", "experience:delete", "experience:detach", "experience:hidden_experience:read", "experience:update", "iap:read", "identity:read", "identity:write", "incorporation:read", "incorporation:write", "livestream:create", "livestream:delete", "livestream:manage_recording", "livestream:chat:read", "livestream:chat:write", "livestream:moderate", "media:generate", "media:read", "member:basic:export", "member:basic:read", "member:email:read", "member:phone:read", "member:payment_methods:read", "member:payment_methods:use", "member:payment_methods:manage", "member:manage", "membership:cancel", "membership:resync_access", "membership:create", "membership:update", "membership:transfer", "member:moderate", "member:stats:export", "member:stats:read", "member:journey:read", "payment:basic:export", "payment:basic:read", "payment:charge", "payment:dispute", "payment:dispute:export", "payment:dispute:read", "payment:dispute_alert:read", "payment:setup_intent:read", "payment:setup_intent:manage", "payment:manage", "payment:resolution_center", "payment:resolution_center_case:export", "payment:resolution_center_case:read", "payment:resolution_center_case:manage", "payout:create_destination", "payout:delete_destination", "payout:destination:read", "payout:transfer_funds", "payout:transfer:read", "payout:transfer:export", "payout:update_destination", "payout:withdraw_funds", "payout:withdrawal:read", "payout:withdrawal:export", "payout:account:read", "payout:account:update", "plan:basic:export", "plan:basic:read", "plan:create", "plan:delete", "plan:stats:export", "plan:stats:read", "plan:update", "plan:waitlist:manage", "plan:waitlist:export", "plan:waitlist:read", "promo_code:basic:export", "promo_code:basic:read", "promo_code:create", "promo_code:delete", "promo_code:update", "referral:basic:read", "referral:partner:create", "partner:basic:read", "partner:email:read", "partner:invite:create", "partner:fees:update", "partner:commission_advance:update", "partner:commission_advance:accept", "partner:referral_request:read", "partner:referral_request:create", "partner:referral_request:accept", "partner:referral_request:decline", "partner:referral_request:cancel", "partner:handoff", "partner:create", "stats:read", "support_chat:read", "support_chat:create", "support_chat:message:create", "tracking_link:basic:export", "tracking_link:basic:read", "tracking_link:create", "tracking_link:delete", "tracking_link:stats:export", "tracking_link:stats:read", "tracking_link:update", "courses:read", "courses:update", "course_lesson_interaction:read", "course_analytics:read", "lead:basic:read", "lead:basic:export", "invoice:create", "invoice:basic:read", "invoice:basic:export", "invoice:update", "webhook_receive:invoices", "webhook_receive:setup_intents", "webhook_receive:withdrawals", "webhook_receive:swaps", "webhook_receive:ledger_accounts", "webhook_receive:accounts", "webhook_receive:deposits", "webhook_receive:financial_activity", "webhook_receive:transfers", "webhook_receive:card_transactions", "webhook_receive:cards", "webhook_receive:card_applications", "webhook_receive:payout_methods", "webhook_receive:verifications", "webhook_receive:identity_profiles", "webhook_receive:payout_accounts", "webhook_receive:chat", "webhook_receive:entries", "webhook_receive:ad_campaigns", "webhook_receive:ad_groups", "webhook_receive:ads", "webhook_receive:products", "webhook_receive:plans", "webhook_receive:domains", "webhook_receive:shipments", "webhook_receive:members", "webhook_receive:exports", "webhook_receive:courses", "webhook_receive:memberships", "webhook_receive:payments", "webhook_receive:refunds", "webhook_receive:disputes", "webhook_receive:resolutions", "webhook_receive:app_payments", "webhook_receive:app_installations", "webhook_receive:app_memberships", "shipment:create", "shipment:basic:read", "checkout_configuration:basic:read", "checkout_configuration:create", "checkout_configuration:delete", "checkout_request:create", "checkout_request:basic:read", "crypto_wallet:manage", "crypto_wallet:swap", "crypto_wallet:trade", "crypto_wallet:trade:read", "airdrop_link:basic:read", "airdrop_link:manage", "lead:manage", "notification:create", "user:balance:read", "user:email:read", "user:payment:charge", "user:staff:read", "oauth:token_exchange", "openid", "profile", "email", "ai_chat:read", "ai_chat:create", "ai_chat:delete", "ai_chat:update", "user:notifications:read", "user:abuse_report:create", "user:abuse_report:read", "user:notifications:update", "user:profile:update" ], "example": "waitlist_entry:read", "type": "string", "x-enumNames": [ "WaitlistEntryRead", "WaitlistEntryCreate", "WaitlistEntryCancel", "ReviewDelete", "ExperimentManage", "ExperimentRead", "DomainManage", "DomainRead", "EmailManage", "EmailRead", "EmailSend", "AiPromptCreate", "AccessPassBasicExport", "AccessPassBasicRead", "AccessPassControlCenter", "AccessPassCreate", "AccessPassDelete", "AccessPassStatsExport", "AccessPassStatsRead", "AccessPassUpdate", "AdCampaignBasicExport", "AdCampaignBasicRead", "AdCampaignConversionCreate", "AdCampaignCreate", "AdCampaignCreditCreate", "AdCampaignDelete", "AdCampaignRead", "AdCampaignStatsRead", "AdCampaignUpdate", "AdPixelManage", "AudienceBasicRead", "AudienceUpdate", "AdPublisherRead", "AffiliateBasicRead", "AffiliateCreate", "AffiliateUpdate", "AuthorizedUserCreate", "AuthorizedUserDelete", "AuthorizedUserUpdate", "AuthorizedRoleCreate", "AuthorizedRoleUpdate", "AuthorizedRoleDelete", "AuthorizedRoleAttach", "AuthorizedRoleDetach", "AppAuthorizationCreate", "AppAuthorizationRead", "AppAuthorizationUpdate", "AppAuthorizationDelete", "BountyBasicRead", "BountyCreate", "BountyCaptureClipCreate", "BountyCaptureClipComplete", "BountyCaptureClipDiscard", "BountyUpdate", "BountySubmissionCreate", "BountySubmissionDelete", "BountySubmissionVote", "ChatManageWebhook", "ChatModerate", "ChatMessageCreate", "ChatRead", "DmsRead", "DmsMessageManage", "DmsChannelManage", "ForumPostCreate", "ForumRead", "ForumModerate", "CompanyAuthorizedUserRead", "CompanyAuthorizedUserEmailRead", "CompanyBalanceRead", "CompanyBalanceExport", "CompanyTokenTransactionRead", "CompanyTokenTransactionCreate", "CompanyLogRead", "CompanyManageCheckout", "CompanyManageLegal", "CompanyBasicRead", "CompanyUpdate", "CompanyTransferOwnership", "CompanyCreate", "CompanyCreateChild", "CompanySuspendChild", "CompanyDelete", "CompanyDeleteChild", "CompanyUpdateChildFees", "ChildCompanyBasicExport", "SocialAccountCreate", "SocialAccountDelete", "SocialAccountRead", "SocialLinkUpdate", "CustomEmojiUpdate", "ContentRewardsBasicExport", "ContentRewardsBasicRead", "ContentRewardsCreate", "ContentRewardsDelete", "ContentRewardsModerateSubmission", "ContentRewardsUpdate", "DeveloperBasicRead", "DeveloperCreateApp", "DeveloperManageApiKey", "DeveloperManageOauth", "DeveloperManageWebhook", "DeveloperLogsRead", "DeveloperManageBuilds", "DeveloperAppInstallationRead", "DeveloperAppInstallationUpdate", "DeveloperUpdateApp", "DeveloperUpdateAppAuthorization", "EventCreate", "ExperienceAttach", "ExperienceCreate", "ExperienceDelete", "ExperienceDetach", "ExperienceHiddenExperienceRead", "ExperienceUpdate", "IapRead", "IdentityRead", "IdentityWrite", "IncorporationRead", "IncorporationWrite", "LivestreamCreate", "LivestreamDelete", "LivestreamManageRecording", "LivestreamChatRead", "LivestreamChatWrite", "LivestreamModerate", "MediaGenerate", "MediaRead", "MemberBasicExport", "MemberBasicRead", "MemberEmailRead", "MemberPhoneRead", "MemberPaymentMethodsRead", "MemberPaymentMethodsUse", "MemberPaymentMethodsManage", "MemberManage", "MembershipCancel", "MembershipResyncAccess", "MembershipCreate", "MembershipUpdate", "MembershipTransfer", "MemberModerate", "MemberStatsExport", "MemberStatsRead", "MemberJourneyRead", "PaymentBasicExport", "PaymentBasicRead", "PaymentCharge", "PaymentDispute", "PaymentDisputeExport", "PaymentDisputeRead", "PaymentDisputeAlertRead", "PaymentSetupIntentRead", "PaymentSetupIntentManage", "PaymentManage", "PaymentResolutionCenter", "PaymentResolutionCenterCaseExport", "PaymentResolutionCenterCaseRead", "PaymentResolutionCenterCaseManage", "PayoutCreateDestination", "PayoutDeleteDestination", "PayoutDestinationRead", "PayoutTransferFunds", "PayoutTransferRead", "PayoutTransferExport", "PayoutUpdateDestination", "PayoutWithdrawFunds", "PayoutWithdrawalRead", "PayoutWithdrawalExport", "PayoutAccountRead", "PayoutAccountUpdate", "PlanBasicExport", "PlanBasicRead", "PlanCreate", "PlanDelete", "PlanStatsExport", "PlanStatsRead", "PlanUpdate", "PlanWaitlistManage", "PlanWaitlistExport", "PlanWaitlistRead", "PromoCodeBasicExport", "PromoCodeBasicRead", "PromoCodeCreate", "PromoCodeDelete", "PromoCodeUpdate", "ReferralBasicRead", "ReferralPartnerCreate", "PartnerBasicRead", "PartnerEmailRead", "PartnerInviteCreate", "PartnerFeesUpdate", "PartnerCommissionAdvanceUpdate", "PartnerCommissionAdvanceAccept", "PartnerReferralRequestRead", "PartnerReferralRequestCreate", "PartnerReferralRequestAccept", "PartnerReferralRequestDecline", "PartnerReferralRequestCancel", "PartnerHandoff", "PartnerCreate", "StatsRead", "SupportChatRead", "SupportChatCreate", "SupportChatMessageCreate", "TrackingLinkBasicExport", "TrackingLinkBasicRead", "TrackingLinkCreate", "TrackingLinkDelete", "TrackingLinkStatsExport", "TrackingLinkStatsRead", "TrackingLinkUpdate", "CoursesRead", "CoursesUpdate", "CourseLessonInteractionRead", "CourseAnalyticsRead", "LeadBasicRead", "LeadBasicExport", "InvoiceCreate", "InvoiceBasicRead", "InvoiceBasicExport", "InvoiceUpdate", "WebhookReceiveInvoices", "WebhookReceiveSetupIntents", "WebhookReceiveWithdrawals", "WebhookReceiveSwaps", "WebhookReceiveLedgerAccounts", "WebhookReceiveAccounts", "WebhookReceiveDeposits", "WebhookReceiveFinancialActivity", "WebhookReceiveTransfers", "WebhookReceiveCardTransactions", "WebhookReceiveCards", "WebhookReceiveCardApplications", "WebhookReceivePayoutMethods", "WebhookReceiveVerifications", "WebhookReceiveIdentityProfiles", "WebhookReceivePayoutAccounts", "WebhookReceiveChat", "WebhookReceiveEntries", "WebhookReceiveAdCampaigns", "WebhookReceiveAdGroups", "WebhookReceiveAds", "WebhookReceiveProducts", "WebhookReceivePlans", "WebhookReceiveDomains", "WebhookReceiveShipments", "WebhookReceiveMembers", "WebhookReceiveExports", "WebhookReceiveCourses", "WebhookReceiveMemberships", "WebhookReceivePayments", "WebhookReceiveRefunds", "WebhookReceiveDisputes", "WebhookReceiveResolutions", "WebhookReceiveAppPayments", "WebhookReceiveAppInstallations", "WebhookReceiveAppMemberships", "ShipmentCreate", "ShipmentBasicRead", "CheckoutConfigurationBasicRead", "CheckoutConfigurationCreate", "CheckoutConfigurationDelete", "CheckoutRequestCreate", "CheckoutRequestBasicRead", "CryptoWalletManage", "CryptoWalletSwap", "CryptoWalletTrade", "CryptoWalletTradeRead", "AirdropLinkBasicRead", "AirdropLinkManage", "LeadManage", "NotificationCreate", "UserBalanceRead", "UserEmailRead", "UserPaymentCharge", "UserStaffRead", "OauthTokenExchange", "Openid", "Profile", "Email", "AiChatRead", "AiChatCreate", "AiChatDelete", "AiChatUpdate", "UserNotificationsRead", "UserAbuseReportCreate", "UserAbuseReportRead", "UserNotificationsUpdate", "UserProfileUpdate" ] }, "PixelValidation": { "properties": { "affiliate_tracking_detected": { "description": "Whether an affiliate tracking SDK was found on the page at `url`. Supported platforms: Everflow.", "example": false, "type": "boolean" }, "firing_data_ok": { "description": "False when the event lookup failed, meaning `host_events` and `last_seen_days` are incomplete.", "example": true, "type": "boolean" }, "host_events": { "items": { "description": "Conversion event names detected on the requested page or fired recently anywhere on its hostname or final redirect hostname.", "example": "lead", "type": "string" }, "type": "array" }, "installed": { "description": "Whether the pixel was seen. Without a `url` this answers for the whole account: true when it has sent events recently. With a `url` it answers for THAT page only — true when the page is hosted on Whop, when the page itself has sent events recently, or when the pixel was found in its source. Events the account sent from other pages do not make a given `url` installed.", "example": false, "type": "boolean" }, "last_fired_days": { "description": "Event name to whole days since that event last fired, e.g. `{ \"lead\": 3 }`. Carries events that fired too long ago to count as installed, so you can prompt to re-check rather than report them missing.", "example": { "lead": 2 }, "type": "object" }, "last_seen_days": { "description": "Days since the pixel last sent an event, within a 30-day window. `null` when it hasn't sent one in that window — which includes a pixel installed moments ago.", "example": 2, "type": [ "number", "null" ] }, "native_tracking": { "description": "True when `url` is hosted on Whop, so no pixel snippet is required.", "example": false, "type": "boolean" }, "page_events": { "items": { "description": "Conversion event names detected on the requested page, from its recent events or its source and linked scripts.", "example": "lead", "type": "string" }, "type": "array" }, "reachable": { "description": "Whether the page could be loaded. `null` when the request included no URL, and `true` when events settled the answer without a fetch.", "example": true, "type": [ "boolean", "null" ] }, "url": { "description": "The URL that was checked, after normalization. `null` when the request didn't include one.", "example": "https://shinetime.example/", "type": [ "string", "null" ] } }, "required": [ "installed", "url", "reachable", "last_seen_days", "page_events", "host_events", "native_tracking", "last_fired_days", "firing_data_ok", "affiliate_tracking_detected" ], "type": "object" }, "Plan": { "properties": { "account": { "description": "Account that sells this variant; `null` for standalone invoice variants.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "adaptive_pricing_enabled": { "description": "Whether adaptive pricing is enabled for this variant. Raw setting — does not check processor compatibility or feature flags.", "example": true, "type": "boolean" }, "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "example": false, "type": "boolean" }, "attributes": { "additionalProperties": { "type": "string" }, "description": "Attribute values that distinguish this variant within its product, as a map of attribute name to value, e.g. `{\"color\": \"Blue\", \"size\": \"Large\"}`. Names are snake_case identifiers and come back in alphabetical order. Every attributed variant on a product carries the same attribute names and a distinct set of values; the product lists the full option set as `variant_attributes`. `null` when the variant has no attributes.", "example": null, "type": [ "object", "null" ] }, "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "number", "null" ] }, "billing_type": { "description": "Billing model for this variant.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "cancel_discount_intervals": { "description": "How long the cancellation discount lasts: `0` forever, `1` the next payment only, or a number of calendar months from when the customer accepts it. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": null, "type": [ "number", "null" ] }, "cancel_discount_percentage": { "description": "Cancellation discount as a whole-number percentage. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": null, "type": [ "number", "null" ] }, "checkout_styling": { "description": "Variant-level checkout styling (`background_color`, `button_color`, `font_family`, `border_style`); `null` inherits the account default.", "example": null, "type": [ "object", "null" ] }, "collect_tax": { "description": "Whether tax is collected on purchases of this variant, based on the account's tax configuration.", "example": true, "type": "boolean" }, "created_at": { "description": "When the variant was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO 4217 code of the currency every price on this variant is stated in, lowercase: the variant's own currency, or the `presentment_currency` the read asked for when the variant can be converted into it.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "custom_fields": { "items": { "$ref": "#/components/schemas/PlanCustomField", "description": "Custom input fields collected on the checkout form." }, "type": "array" }, "deletable": { "description": "Whether the variant can be deleted (it has no memberships or waitlist entries). `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": true, "type": [ "boolean", "null" ] }, "description": { "description": "Customer-visible variant description. Maximum 1000 characters. `null` if no description is set.", "example": null, "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout for this variant, resolved through every layer (the variant's own and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays the variant's own editable override.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutSessionPaymentMethodConfiguration" }, { "type": "null" } ] }, "expiration_days": { "description": "Access duration in days for expiration-based variants, such as 365 for a one-year pass. `null` for variants without an expiration.", "example": null, "type": [ "number", "null" ] }, "formatted_price": { "description": "Human-readable price for display (currency + interval) in `currency`, e.g. \"$10 / month\".", "example": "$59.00 / month", "type": "string" }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "Pricing-tier image (`url`, `blurhash`) shown on the product page; `null` when no image is set.", "example": null, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial purchase price, in `currency`.", "example": 0.0, "type": "number" }, "initial_price_due": { "$ref": "#/components/schemas/Money", "description": "Total charged at checkout for one unit, before promo codes and tax: `initial_price` plus the first `renewal_price` for recurring variants, or `initial_price` alone while a free trial applies. The trial does not apply when the viewing user has already used one for this variant. Stated in `currency`." }, "internal_notes": { "description": "Private notes not shown to customers. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "invoice": { "description": "Invoice this variant was generated for; `null` unless created for an invoice.", "example": null, "type": [ "object", "null" ] }, "member_count": { "description": "Active memberships through this variant. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": 0, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the variant. Included in webhook payloads for payment and membership events. Maximum 50 keys, 100 characters per key, 500 characters per value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this variant.", "example": { "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether a cancellation discount is offered. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": false, "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "Payment method configuration (`enabled`, `disabled`, `include_platform_defaults`); `null` when variant uses default settings.", "example": null, "type": [ "object", "null" ] }, "product": { "description": "Product this variant belongs to; `null` for standalone variants.", "example": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "type": [ "object", "null" ] }, "purchase_url": { "description": "URL where customers can purchase this variant directly.", "example": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this variant.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged every billing period, in `currency`.", "example": 59.0, "type": "number" }, "sku": { "description": "Stock keeping unit, free text set by the seller (e.g. `TSHIRT-LARGE-BLUE`). Not enforced unique. `null` when unset.", "example": null, "type": [ "string", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses. Must be greater than 1. `null` if split pay is not configured.", "example": null, "type": [ "number", "null" ] }, "stock": { "description": "Units available for purchase. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": 0, "type": [ "number", "null" ] }, "strike_through_initial_price": { "description": "Original initial price shown with a strikethrough, in `currency`. `null` when no strikethrough is set.", "example": null, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "Original renewal price shown with a strikethrough, in `currency`. `null` when no strikethrough is set.", "example": null, "type": [ "number", "null" ] }, "tax_type": { "description": "How tax is handled for this variant, including whether tax is included in the price, added at checkout, or not configured.", "enum": [ "inclusive", "exclusive", "unspecified" ], "example": "exclusive", "type": "string" }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "title": { "description": "Variant display name shown to customers. Maximum 30 characters. A variant created without one defaults to its attribute values joined with ` / `. `null` if no title has been set.", "example": "Deprecated plan update", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge. `null` if no trial is configured or the user has already used a trial for this variant.", "example": null, "type": [ "number", "null" ] }, "unlimited_stock": { "description": "Whether the variant has unlimited stock. When `true`, the `stock` field is ignored; waitlist variants always report `true`.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the variant was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visibility": { "description": "Controls where this variant can be seen. When `hidden`, the variant is reachable only by its direct link.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "visibility", "billing_type", "release_method", "currency", "account", "product", "invoice", "billing_period", "title", "description", "purchase_url", "expiration_days", "initial_price", "renewal_price", "initial_price_due", "formatted_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "sku", "attributes", "stock", "unlimited_stock", "allow_multiple_quantity", "split_pay_required_payments", "adaptive_pricing_enabled", "strike_through_initial_price", "strike_through_renewal_price", "checkout_styling", "offer_cancel_discount", "cancel_discount_percentage", "cancel_discount_intervals", "payment_method_configuration", "image", "tax_type", "collect_tax", "deletable", "effective_payment_method_configuration", "custom_fields" ], "type": "object" }, "PlanCustomField": { "properties": { "field_type": { "description": "Custom field input type.", "enum": [ "text" ], "example": "text", "type": "string" }, "id": { "description": "Custom field ID, prefixed `field_`.", "example": "field_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Field label shown to customer at checkout.", "example": "Vehicle make and model", "type": "string" }, "order": { "description": "Field position on checkout form.", "example": 0, "type": "number" }, "placeholder": { "description": "Placeholder text shown in the empty field. `null` if none is set.", "example": "2021 Audi S5", "type": [ "string", "null" ] }, "required": { "description": "Whether the customer must complete this field to check out.", "example": true, "type": "boolean" } }, "required": [ "id", "field_type", "name", "order", "placeholder", "required" ], "type": "object" }, "PlanListItem": { "properties": { "account": { "description": "Account that sells this variant; `null` for standalone invoice variants.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "adaptive_pricing_enabled": { "description": "Whether adaptive pricing is enabled for this variant. Raw setting — does not check processor compatibility or feature flags.", "example": true, "type": "boolean" }, "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "example": false, "type": "boolean" }, "attributes": { "additionalProperties": { "type": "string" }, "description": "Attribute values that distinguish this variant within its product, as a map of attribute name to value, e.g. `{\"color\": \"Blue\", \"size\": \"Large\"}`. Names are snake_case identifiers and come back in alphabetical order. Every attributed variant on a product carries the same attribute names and a distinct set of values; the product lists the full option set as `variant_attributes`. `null` when the variant has no attributes.", "example": null, "type": [ "object", "null" ] }, "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "number", "null" ] }, "billing_type": { "description": "Billing model for this variant.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "cancel_discount_intervals": { "description": "How long the cancellation discount lasts: `0` forever, `1` the next payment only, or a number of calendar months from when the customer accepts it. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": null, "type": [ "number", "null" ] }, "cancel_discount_percentage": { "description": "Cancellation discount as a whole-number percentage. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": null, "type": [ "number", "null" ] }, "checkout_styling": { "description": "Variant-level checkout styling (`background_color`, `button_color`, `font_family`, `border_style`); `null` inherits the account default.", "example": null, "type": [ "object", "null" ] }, "created_at": { "description": "When the variant was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO 4217 code of the currency every price on this variant is stated in, lowercase: the variant's own currency, or the `presentment_currency` the read asked for when the variant can be converted into it.", "example": "usd", "type": "string" }, "custom_fields": { "items": { "$ref": "#/components/schemas/PlanCustomField", "description": "Custom input fields collected on the checkout form." }, "type": "array" }, "description": { "description": "Customer-visible variant description. Maximum 1000 characters. `null` if no description is set.", "example": null, "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days for expiration-based variants, such as 365 for a one-year pass. `null` for variants without an expiration.", "example": null, "type": [ "number", "null" ] }, "formatted_price": { "description": "Human-readable price for display (currency + interval) in `currency`, e.g. \"$10 / month\".", "example": "$59.00 / month", "type": "string" }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "Pricing-tier image (`url`, `blurhash`) shown on the product page; `null` when no image is set.", "example": null, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial purchase price, in `currency`.", "example": 0.0, "type": "number" }, "initial_price_due": { "$ref": "#/components/schemas/Money", "description": "Total charged at checkout for one unit, before promo codes and tax: `initial_price` plus the first `renewal_price` for recurring variants, or `initial_price` alone while a free trial applies. The trial does not apply when the viewing user has already used one for this variant. Stated in `currency`." }, "internal_notes": { "description": "Private notes not shown to customers. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "invoice": { "description": "Invoice this variant was generated for; `null` unless created for an invoice.", "example": null, "type": [ "object", "null" ] }, "member_count": { "description": "Active memberships through this variant. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": 0, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the variant. Included in webhook payloads for payment and membership events. Maximum 50 keys, 100 characters per key, 500 characters per value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this variant.", "example": { "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether a cancellation discount is offered. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": false, "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "Payment method configuration (`enabled`, `disabled`, `include_platform_defaults`); `null` when variant uses default settings.", "example": null, "type": [ "object", "null" ] }, "product": { "description": "Product this variant belongs to; `null` for standalone variants.", "example": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "type": [ "object", "null" ] }, "purchase_url": { "description": "URL where customers can purchase this variant directly.", "example": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this variant.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged every billing period, in `currency`.", "example": 59.0, "type": "number" }, "sku": { "description": "Stock keeping unit, free text set by the seller (e.g. `TSHIRT-LARGE-BLUE`). Not enforced unique. `null` when unset.", "example": null, "type": [ "string", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses. Must be greater than 1. `null` if split pay is not configured.", "example": null, "type": [ "number", "null" ] }, "stock": { "description": "Units available for purchase. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": 0, "type": [ "number", "null" ] }, "strike_through_initial_price": { "description": "Original initial price shown with a strikethrough, in `currency`. `null` when no strikethrough is set.", "example": null, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "Original renewal price shown with a strikethrough, in `currency`. `null` when no strikethrough is set.", "example": null, "type": [ "number", "null" ] }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "title": { "description": "Variant display name shown to customers. Maximum 30 characters. A variant created without one defaults to its attribute values joined with ` / `. `null` if no title has been set.", "example": "Unlimited Wash Club", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge. `null` if no trial is configured or the user has already used a trial for this variant.", "example": null, "type": [ "number", "null" ] }, "unlimited_stock": { "description": "Whether the variant has unlimited stock. When `true`, the `stock` field is ignored; waitlist variants always report `true`.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the variant was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visibility": { "description": "Controls where this variant can be seen. When `hidden`, the variant is reachable only by its direct link.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "visibility", "billing_type", "release_method", "currency", "account", "product", "invoice", "billing_period", "title", "description", "purchase_url", "expiration_days", "initial_price", "renewal_price", "initial_price_due", "formatted_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "sku", "attributes", "stock", "unlimited_stock", "allow_multiple_quantity", "split_pay_required_payments", "adaptive_pricing_enabled", "strike_through_initial_price", "strike_through_renewal_price", "checkout_styling", "offer_cancel_discount", "cancel_discount_percentage", "cancel_discount_intervals", "payment_method_configuration", "image", "custom_fields" ], "type": "object" }, "PlanThreeDsLevels": { "description": "The 3D Secure behavior for a plan.", "enum": [ "mandate_challenge", "frictionless" ], "type": "string" }, "PlanTypes": { "description": "The type of plan that can be attached to a product", "enum": [ "renewal", "one_time" ], "type": "string" }, "Product": { "properties": { "account": { "description": "Account that sells this product.", "example": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "type": [ "object", "null" ] }, "average_review_rating": { "description": "Average star rating across published reviews for this product, from `1.0` to `5.0`. Returns `0.0` when no published-review rating is available.", "example": 0.0, "type": "number" }, "created_at": { "description": "When the product was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "custom_cta": { "description": "Call-to-action button label shown on the product purchase page.", "enum": [ "get_access", "join", "order_now", "shop_now", "call_now", "donate_now", "contact_us", "sign_up", "subscribe", "purchase", "get_offer", "apply_now", "complete_order", null ], "example": "order_now", "type": [ "string", "null" ] }, "custom_cta_url": { "description": "URL the call-to-action button links to instead of checkout.", "example": "https://shinetime.example/book", "type": [ "string", "null" ] }, "custom_statement_descriptor": { "description": "Custom text label on customer's bank statement.", "example": "WHOP*SHINETIME", "type": [ "string", "null" ] }, "default_variant": { "description": "Buyable variant to show and check out with. The configured default when that variant is buyable, otherwise the first buyable variant in product-page order. `null` when none is buyable.", "oneOf": [ { "$ref": "#/components/schemas/ProductPublicVariant" }, { "type": "null" } ] }, "description": { "description": "Written description displayed on the product page. `null` if none is set.", "example": "Full interior extraction, leather conditioning, and an ozone odor treatment.", "type": [ "string", "null" ] }, "external_identifier": { "description": "External identifier stored on the product for your own reference.", "example": "SHINE-CERAMIC-01", "type": [ "string", "null" ] }, "gallery_images": { "items": { "$ref": "#/components/schemas/ProductGalleryImage", "description": "Gallery images for this product, ordered by position." }, "type": "array" }, "global_affiliate_percentage": { "description": "Commission rate affiliates earn through the global affiliate program.", "example": 10.0, "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "Enrollment status in the global affiliate program.", "enum": [ "enabled", "disabled", null ], "example": "enabled", "type": [ "string", "null" ] }, "headline": { "description": "Short marketing headline displayed on product page.", "example": "Steam, shampoo, and odor removal in one visit", "type": [ "string", "null" ] }, "id": { "description": "Product ID, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "labels": { "items": { "description": "Lowercased labels used to group products into collections. Filter the list endpoint by `labels` to fetch one collection.", "example": "interior", "type": "string" }, "type": "array" }, "marketplace_status": { "description": "Listing state on the whop.com marketplace. `pending_review` means submitted and awaiting review; `live_marketplace` means approved and discoverable.", "enum": [ "not_available", "pending_review", "live_marketplace" ], "example": "not_available", "type": "string" }, "member_affiliate_percentage": { "description": "Commission rate members earn through the member affiliate program.", "example": 5.0, "type": [ "number", "null" ] }, "member_affiliate_status": { "description": "Enrollment status in the member affiliate program.", "enum": [ "enabled", "disabled", null ], "example": "enabled", "type": [ "string", "null" ] }, "member_count": { "description": "Active memberships for this product; 0 if public member counts are disabled.", "example": 0, "type": "number" }, "metadata": { "description": "Custom key-value pairs stored on the product.", "example": { "bay": "1", "duration_hours": "4" }, "type": [ "object", "null" ] }, "owner_user": { "description": "User who owns the account selling this product.", "example": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "type": [ "object", "null" ] }, "product_tax_code": { "description": "Tax classification code for this product, or `null` if no tax code is set.", "example": { "id": "ptc_xxxxxxxxxxxxxx", "name": "General - Digital Goods", "product_type": "digital" }, "type": [ "object", "null" ] }, "published_reviews_count": { "description": "Published customer reviews for this product.", "example": 0, "type": "number" }, "route": { "description": "URL slug for the product's public link.", "example": "interior-deep-clean", "type": "string" }, "title": { "description": "Product display name shown to customers.", "example": "Interior Deep Clean", "type": "string" }, "updated_at": { "description": "When the product was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "variant_attributes": { "description": "The option set the product's variants span, as a map of attribute name to the values in use, e.g. `{\"color\": [\"Blue\", \"Red\"], \"size\": [\"S\", \"M\", \"L\"]}`. Derived from the visible, non-invoice variants that carry `attributes`: keys alphabetical, values in the order the variants were created. Read-only. `null` when the product has no variants.", "example": { "color": [ "Red", "Blue" ], "size": [ "M", "S" ] }, "type": [ "object", "null" ] }, "variants": { "items": { "$ref": "#/components/schemas/VariantListItem", "description": "The product's variants whose `visibility` is `visible` and that were not generated for an invoice, in creation order. Plain pricing options are included with `attributes: null`. Hidden, archived, quick-link, and invoice variants stay reachable through `GET /variants`. `null` when the product has more than 1000 variants (page them through `GET /variants?product_ids=`) and in webhook payloads." }, "type": [ "array", "null" ] }, "verified": { "description": "Whether the product has been verified by Whop.", "example": false, "type": "boolean" }, "visibility": { "description": "Whether the product is publicly visible, hidden, or archived.", "example": "visible", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "updated_at", "title", "visibility", "headline", "description", "verified", "member_count", "route", "published_reviews_count", "average_review_rating", "external_identifier", "metadata", "labels", "account", "default_variant", "variant_attributes", "custom_cta", "custom_cta_url", "custom_statement_descriptor", "global_affiliate_percentage", "global_affiliate_status", "member_affiliate_percentage", "member_affiliate_status", "product_tax_code", "owner_user", "marketplace_status", "variants", "gallery_images" ], "type": "object" }, "ProductAffiliate": { "properties": { "created_at": { "description": "When the affiliate enrollment was created, as an ISO 8601 timestamp. Includes automatically created enrollments.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Product affiliate ID, prefixed `apaf_`.", "example": "apaf_xxxxxxxxxxxxxx", "type": "string" }, "product": { "$ref": "#/components/schemas/PromoCodeProduct", "description": "The product the affiliate is enrolled to promote." }, "referred_users_count": { "description": "Number of distinct users referred by the affiliate to this product.", "example": 3, "type": "integer" }, "status": { "description": "Whether the affiliate's enrollment is active or archived.", "enum": [ "active", "archived" ], "example": "active", "type": "string" }, "total_reward_amount_usd": { "$ref": "#/components/schemas/Money", "description": "Net rewards earned by the affiliate for this product after fees and reversals, in USD." }, "user": { "$ref": "#/components/schemas/ProductAffiliateUser", "description": "The user enrolled as an affiliate." } }, "required": [ "id", "status", "created_at", "referred_users_count", "total_reward_amount_usd", "user", "product" ], "type": "object" }, "ProductAffiliateUser": { "properties": { "email": { "description": "The affiliate's email address. Requires the `member:email:read` scope; `null` without it.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name.", "example": "Jack Sharkey the 2nd", "type": [ "string", "null" ] }, "profile_picture": { "$ref": "#/components/schemas/UserProfilePicture", "description": "Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture." }, "username": { "description": "Public username.", "example": "random-username-2-xxxxxxxx", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture", "email" ], "type": "object" }, "ProductGalleryImage": { "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg.", "example": "image/png", "type": [ "string", "null" ] }, "id": { "description": "Gallery image ID.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "Pre-optimized URL for rendering this image on the client.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "url", "content_type" ], "type": "object" }, "ProductLegacy": { "description": "A product is a digital good or service sold on Whop. Products contain plans for pricing and experiences for content delivery.", "properties": { "company": { "description": "The company this product belongs to.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.", "example": "pickaxe", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "route", "title" ], "type": "object" }, "created_at": { "description": "The datetime the product was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "custom_cta": { "$ref": "#/components/schemas/CustomCtas", "description": "Call-to-action button label shown on the product purchase page." }, "custom_cta_url": { "description": "An optional URL that the call-to-action button links to instead of the default checkout flow. Null if no custom URL is set.", "example": "https://example.com/signup", "type": [ "string", "null" ] }, "custom_statement_descriptor": { "description": "Custom bank statement descriptor for product purchases. Maximum 22 characters, including required `WHOP*` prefix.", "example": "PICKAXE", "type": [ "string", "null" ] }, "description": { "description": "A brief summary of what the product offers, displayed on product pages and search results.", "example": "Track your revenue, members, and growth in real time.", "type": [ "string", "null" ] }, "external_identifier": { "description": "External identifier for the product. Providing it on a product creation endpoint updates the existing product with this identifier instead of creating a new one.", "example": "ext_prod_12345", "type": [ "string", "null" ] }, "gallery_images": { "description": "The gallery images for this product, ordered by position.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://media.whop.com/abc123/optimized.jpg", "type": [ "string", "null" ] } }, "required": [ "id", "url", "content_type" ], "type": "object" }, "type": "array" }, "global_affiliate_percentage": { "description": "Marketplace affiliate commission percentage for this product, or `null` if program is inactive.", "example": 6.9, "type": [ "number", "null" ] }, "global_affiliate_status": { "$ref": "#/components/schemas/GlobalAffiliateStatuses", "description": "The enrollment status of this product in the Whop marketplace global affiliate program." }, "headline": { "description": "A short marketing headline displayed prominently on the product's product page.", "example": "Real-time data analytics for creators", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "member_affiliate_percentage": { "description": "Member referral commission percentage for this product, or `null` if program is inactive.", "example": 6.9, "type": [ "number", "null" ] }, "member_affiliate_status": { "$ref": "#/components/schemas/GlobalAffiliateStatuses", "description": "The enrollment status of this product in the member affiliate program." }, "member_count": { "description": "Active memberships for this product. Returns `0` if the account has disabled public member counts.", "example": 42, "type": "integer" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "type": [ "object", "null" ] }, "owner_user": { "description": "The user who owns the company that sells this product.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "product_tax_code": { "description": "The tax classification code applied to purchases of this product for sales tax calculation. Null if no tax code is assigned.", "properties": { "id": { "description": "The unique identifier for the product tax code.", "example": "ptc_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Human-readable name of this tax classification, such as 'Digital - SaaS'.", "example": "Digital - SaaS", "type": "string" }, "product_type": { "$ref": "#/components/schemas/ProductTaxCodeProductTypes", "description": "Broad product category this tax code covers, such as physical goods or digital services." } }, "required": [ "id", "name", "product_type" ], "type": [ "object", "null" ] }, "published_reviews_count": { "description": "The total number of published customer reviews for this product's company.", "example": 42, "type": "integer" }, "route": { "description": "URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.", "example": "pickaxe-analytics", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Pickaxe Analytics", "type": "string" }, "updated_at": { "description": "The datetime the product was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "verified": { "description": "Whether this company has been verified by Whop's trust and safety team.", "type": "boolean" }, "visibility": { "$ref": "#/components/schemas/Visibility", "description": "Controls whether the product is visible to customers. When set to 'hidden', the product is only accessible via direct link." } }, "required": [ "id", "title", "visibility", "headline", "verified", "created_at", "updated_at", "member_count", "route", "published_reviews_count", "external_identifier", "metadata", "gallery_images", "description", "custom_cta", "custom_cta_url", "custom_statement_descriptor", "global_affiliate_percentage", "global_affiliate_status", "member_affiliate_percentage", "member_affiliate_status", "product_tax_code", "owner_user", "company" ], "type": "object" }, "ProductListItem": { "properties": { "account": { "description": "Account that sells this product.", "example": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "type": [ "object", "null" ] }, "average_review_rating": { "description": "Average star rating across published reviews for this product, from `1.0` to `5.0`. Returns `0.0` when no published-review rating is available.", "example": 0.0, "type": "number" }, "created_at": { "description": "When the product was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "default_variant": { "description": "Buyable variant to show and check out with. The configured default when that variant is buyable, otherwise the first buyable variant in product-page order. `null` when none is buyable.", "oneOf": [ { "$ref": "#/components/schemas/ProductPublicVariant" }, { "type": "null" } ] }, "description": { "description": "Written description displayed on the product page. `null` if none is set.", "example": "empower rich infrastructures", "type": [ "string", "null" ] }, "external_identifier": { "description": "External identifier stored on the product for your own reference.", "example": "SHINE-CERAMIC-01", "type": [ "string", "null" ] }, "gallery_images": { "items": { "$ref": "#/components/schemas/ProductGalleryImage", "description": "Gallery images for this product, ordered by position." }, "type": "array" }, "headline": { "description": "Short marketing headline displayed on product page.", "example": "thought leadership", "type": [ "string", "null" ] }, "id": { "description": "Product ID, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "labels": { "items": { "description": "Lowercased labels used to group products into collections. Filter the list endpoint by `labels` to fetch one collection.", "example": "courses", "type": "string" }, "type": "array" }, "member_count": { "description": "Active memberships for this product; 0 if public member counts are disabled.", "example": 0, "type": "number" }, "metadata": { "description": "Custom key-value pairs stored on the product.", "example": {}, "type": [ "object", "null" ] }, "published_reviews_count": { "description": "Published customer reviews for this product.", "example": 0, "type": "number" }, "route": { "description": "URL slug for the product's public link.", "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "title": { "description": "Product display name shown to customers.", "example": "Wash Club Tee", "type": "string" }, "updated_at": { "description": "When the product was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "variant_attributes": { "description": "The option set the product's variants span, as a map of attribute name to the values in use, e.g. `{\"color\": [\"Blue\", \"Red\"], \"size\": [\"S\", \"M\", \"L\"]}`. Derived from the visible, non-invoice variants that carry `attributes`: keys alphabetical, values in the order the variants were created. Read-only. `null` when the product has no variants.", "example": { "color": [ "Blue", "Red" ], "size": [ "L", "S" ] }, "type": [ "object", "null" ] }, "verified": { "description": "Whether the product has been verified by Whop.", "example": false, "type": "boolean" }, "visibility": { "description": "Whether the product is publicly visible, hidden, or archived.", "example": "visible", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "updated_at", "title", "visibility", "headline", "description", "verified", "member_count", "route", "published_reviews_count", "average_review_rating", "external_identifier", "metadata", "labels", "account", "default_variant", "variant_attributes", "gallery_images" ], "type": "object" }, "ProductPublicVariant": { "properties": { "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "number", "null" ] }, "billing_type": { "description": "Billing model for this variant: `one_time` or `renewal`.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based variants. `null` for variants without an expiration.", "example": null, "type": [ "number", "null" ] }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "$ref": "#/components/schemas/Money", "description": "What checkout charges up front. `amount` is `\"0.00\"` when the first charge is free, such as a trial." }, "renewal_price": { "$ref": "#/components/schemas/Money", "description": "The recurring charge every `billing_period` days. `amount` is `\"0.00\"` for one-time variants." }, "title": { "description": "Variant display name shown to customers. `null` if no title has been set.", "example": null, "type": [ "string", "null" ] }, "unlimited_stock": { "description": "Whether the variant has unlimited stock.", "example": true, "type": "boolean" }, "visibility": { "description": "Where this variant can be seen. `visible` variants appear on the product page.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "title", "billing_type", "billing_period", "initial_price", "renewal_price", "visibility", "unlimited_stock", "expiration_days" ], "type": "object" }, "ProductTaxCodeProductTypes": { "description": "The product_type of the ProductTaxCode", "enum": [ "physical", "digital", "services" ], "type": "string" }, "PromoCode": { "properties": { "account": { "$ref": "#/components/schemas/AccountSummary", "description": "Account that owns the promo code." }, "affiliate": { "description": "Affiliate credited with referrals that use the promo code, or `null` when no affiliate is attached.", "oneOf": [ { "$ref": "#/components/schemas/PromoCodeAffiliate" }, { "type": "null" } ] }, "amount_off": { "description": "Discount amount. Percentage discounts are represented as a decimal fraction.", "example": 0.25, "type": "number" }, "churned_users_only": { "description": "Whether the promo code is restricted to churned customers.", "example": false, "type": "boolean" }, "code": { "description": "Code entered at checkout.", "example": "affiliate25", "type": [ "string", "null" ] }, "created_at": { "description": "When the promo code was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for a fixed-amount discount.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "duration": { "description": "How long the discount applies.", "enum": [ "forever", "once", "repeating" ], "example": "repeating", "type": "string" }, "existing_memberships_only": { "description": "Whether the promo code applies only to existing memberships.", "example": false, "type": "boolean" }, "expires_at": { "description": "When the promo code expires, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Promo code ID, prefixed `promo_`.", "example": "promo_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata stored on the promo code.", "example": {}, "type": "object" }, "new_users_only": { "description": "Whether the promo code is restricted to new customers.", "example": true, "type": "boolean" }, "one_per_customer": { "description": "Whether each customer may redeem the promo code only once.", "example": true, "type": "boolean" }, "product": { "description": "Product the promo code is restricted to, or `null` when it is not product-scoped.", "oneOf": [ { "$ref": "#/components/schemas/PromoCodeProduct" }, { "type": "null" } ] }, "promo_duration_months": { "description": "Billing intervals the discount applies to.", "example": 3, "type": [ "integer", "null" ] }, "promo_type": { "description": "Whether the discount is percentage-based or a fixed amount.", "enum": [ "percentage", "flat_amount" ], "example": "percentage", "type": "string" }, "status": { "description": "Promo code lifecycle status.", "enum": [ "active", "inactive", "archived" ], "example": "active", "type": "string" }, "stock": { "description": "Maximum uses when stock is limited.", "example": 200, "type": "integer" }, "unlimited_stock": { "description": "Whether the promo code has no redemption limit.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the promo code was updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "uses": { "description": "Memberships that used the promo code.", "example": 0, "type": "integer" } }, "required": [ "id", "code", "amount_off", "currency", "promo_type", "duration", "promo_duration_months", "uses", "stock", "status", "expires_at", "created_at", "updated_at", "new_users_only", "churned_users_only", "unlimited_stock", "one_per_customer", "existing_memberships_only", "product", "metadata", "affiliate", "account" ], "type": "object" }, "PromoCodeAffiliate": { "properties": { "id": { "description": "Affiliate ID, prefixed `aff_`.", "example": "aff_xxxxxxxxxxxxxx", "type": "string" }, "user": { "$ref": "#/components/schemas/PromoCodeAffiliateUser", "description": "User who is the affiliate." } }, "required": [ "id", "user" ], "type": "object" }, "PromoCodeAffiliateUser": { "properties": { "id": { "description": "Affiliate user ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name of the affiliate.", "example": "Jack Sharkey the 3rd", "type": [ "string", "null" ] }, "profile_pic": { "description": "Affiliate avatar URL, including the generated fallback when no avatar is set.", "example": "https://ui-avatars.com/api/", "type": "string" }, "username": { "description": "Public username of the affiliate.", "example": "newpromoaffiliate", "type": [ "string", "null" ] } }, "required": [ "id", "username", "name", "profile_pic" ], "type": "object" }, "PromoCodeListItem": { "properties": { "affiliate": { "description": "Affiliate credited with referrals that use the promo code, or `null` when no affiliate is attached.", "oneOf": [ { "$ref": "#/components/schemas/PromoCodeAffiliate" }, { "type": "null" } ] }, "amount_off": { "description": "Discount amount. Percentage discounts are represented as a decimal fraction.", "example": 0.1, "type": "number" }, "churned_users_only": { "description": "Whether the promo code is restricted to churned customers.", "example": false, "type": "boolean" }, "code": { "description": "Code entered at checkout.", "example": "welcome", "type": [ "string", "null" ] }, "created_at": { "description": "When the promo code was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for a fixed-amount discount.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "duration": { "description": "How long the discount applies.", "enum": [ "forever", "once", "repeating" ], "example": "repeating", "type": "string" }, "existing_memberships_only": { "description": "Whether the promo code applies only to existing memberships.", "example": false, "type": "boolean" }, "expires_at": { "description": "When the promo code expires, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Promo code ID, prefixed `promo_`.", "example": "promo_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata stored on the promo code.", "example": {}, "type": "object" }, "new_users_only": { "description": "Whether the promo code is restricted to new customers.", "example": true, "type": "boolean" }, "one_per_customer": { "description": "Whether each customer may redeem the promo code only once.", "example": true, "type": "boolean" }, "product": { "description": "Product the promo code is restricted to, or `null` when it is not product-scoped.", "oneOf": [ { "$ref": "#/components/schemas/PromoCodeProduct" }, { "type": "null" } ] }, "promo_duration_months": { "description": "Billing intervals the discount applies to.", "example": 1, "type": [ "integer", "null" ] }, "promo_type": { "description": "Whether the discount is percentage-based or a fixed amount.", "enum": [ "percentage", "flat_amount" ], "example": "percentage", "type": "string" }, "status": { "description": "Promo code lifecycle status.", "enum": [ "active", "inactive", "archived" ], "example": "active", "type": "string" }, "stock": { "description": "Maximum uses when stock is limited.", "example": 25, "type": "integer" }, "unlimited_stock": { "description": "Whether the promo code has no redemption limit.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the promo code was updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "uses": { "description": "Memberships that used the promo code.", "example": 1, "type": "integer" } }, "required": [ "id", "code", "amount_off", "currency", "promo_type", "duration", "promo_duration_months", "uses", "stock", "status", "expires_at", "created_at", "updated_at", "new_users_only", "churned_users_only", "unlimited_stock", "one_per_customer", "existing_memberships_only", "product", "metadata", "affiliate" ], "type": "object" }, "PromoCodeProduct": { "properties": { "id": { "description": "Product ID, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Product display name.", "example": "Ceramic Coating Package", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "PromoCodeStatus": { "description": "Statuses for promo codes", "enum": [ "active", "inactive", "archived" ], "type": "string" }, "PromoCodeUpdateStatus": { "description": "Statuses that can be applied to promo codes through update operations.", "enum": [ "active", "inactive" ], "type": "string" }, "PromoDurations": { "description": "The duration setting for the promo code", "enum": [ "forever", "once", "repeating" ], "type": "string" }, "PromoTypes": { "description": "The type of promo code used to discount a plan", "enum": [ "percentage", "flat_amount" ], "type": "string" }, "PublicBountySubmission": { "properties": { "bounty_id": { "description": "The bounty the work was submitted to, prefixed `bnty_`.", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "claimed_at": { "description": "When the worker claimed the submission, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "created_at": { "description": "When the submission was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "denial_reason": { "description": "Why the submission was denied, when a presentable reason exists. Always `null` unless `status` is `denied`.", "example": "The wheels were never shown in the finished clip.", "type": [ "string", "null" ] }, "id": { "description": "Submission ID, prefixed `btys_`.", "example": "btys_xxxxxxxxxxxxxx", "type": "string" }, "latest_proof_livestream_feed": { "description": "Latest public proof livestream attached to the submission.", "oneOf": [ { "$ref": "#/components/schemas/BountySubmissionLivestreamFeed" }, { "type": "null" } ] }, "resolved_at": { "description": "When the submission was approved or denied, as an ISO 8601 timestamp. `null` until then.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Lifecycle state. `submitted` submissions await review; `approved` submissions were accepted and paid; `denied` submissions were rejected. In-progress attempts never appear on the public list.", "enum": [ "submitted", "approved", "denied" ], "example": "approved", "type": "string" }, "submitted_at": { "description": "When proof was submitted for review, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "updated_at": { "description": "When the submission was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "worker": { "$ref": "#/components/schemas/UserSummary", "description": "User who submitted the work." } }, "required": [ "id", "bounty_id", "status", "denial_reason", "claimed_at", "submitted_at", "resolved_at", "latest_proof_livestream_feed", "created_at", "updated_at", "worker" ], "type": "object" }, "ReachEstimate": { "properties": { "users_lower_bound": { "description": "Low end of how many people the targeting can reach. Null when the platform couldn't produce an estimate.", "example": 1500000, "type": [ "number", "null" ] }, "users_upper_bound": { "description": "High end of how many people the targeting can reach. Null when the platform couldn't produce an estimate.", "example": 1800000, "type": [ "number", "null" ] } }, "required": [ "users_lower_bound", "users_upper_bound" ], "type": "object" }, "Reaction": { "description": "A single reaction left by a user on a feed post, such as a like or emoji.", "properties": { "emoji": { "description": "The emoji used for this reaction in shortcode format. Null if the reaction type is not emoji.", "example": ":heart:", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the entity", "example": "reac_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "resource_id": { "description": "The unique identifier of the post this reaction was left on.", "type": "string" }, "user": { "description": "The user who left this reaction on the post.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" } }, "required": [ "id", "resource_id", "user", "emoji" ], "type": "object" }, "ReactionListItem": { "description": "A single reaction left by a user on a feed post, such as a like or emoji.", "properties": { "emoji": { "description": "The emoji used for this reaction in shortcode format. Null if the reaction type is not emoji.", "example": ":heart:", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the entity", "example": "reac_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "resource_id": { "description": "The unique identifier of the post this reaction was left on.", "type": "string" }, "user": { "description": "The user who left this reaction on the post.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" } }, "required": [ "id", "resource_id", "user", "emoji" ], "type": "object" }, "ReceiptLineItem": { "properties": { "id": { "description": "Line item ID, prefixed `li_`. Null when the payment predates item snapshots and the item is read from the payment's variant.", "example": "li_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "label": { "description": "The item's name as shown at checkout — the product title, else the variant title.", "example": "Ceramic Coating Package", "type": [ "string", "null" ] }, "product_id": { "description": "The product the variant belongs to, prefixed `prod_`. On a payment that predates item snapshots this falls back to the variant's product, so it can be set where the parent's own `product_id` is null. Null for a variant with no product.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_title": { "description": "The product's current title, or `null` when the item has no product.", "example": "Ceramic Coating Package", "type": [ "string", "null" ] }, "quantity": { "description": "How many units were bought.", "example": 1, "type": "number" }, "sku": { "description": "The variant's stock keeping unit, free text set by the seller (e.g. `TSHIRT-LARGE-BLUE`). Accounts with billing-reason SKU suffixes enabled receive it stamped with why the charge happened: `-S` for a first subscription charge, `-R` for a renewal, `-C` for a one-time purchase, `-U` when the payment's own metadata carries `upsell: true`, `-F` when nothing was charged. Other billing reasons carry the bare SKU. `null` when the variant has no SKU or has been deleted.", "example": null, "type": [ "string", "null" ] }, "subtotal": { "description": "The recorded amount for this item's full quantity, before discounts, tax, and fees, in its purchase currency. Returns `null` when no item amount was recorded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "variant_id": { "description": "The variant bought, prefixed `plan_`. Null when the variant has since been deleted.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "variant_title": { "description": "The variant's current title, or `null` when the variant has been deleted or has no title.", "example": "Ceramic Coating — Full Vehicle", "type": [ "string", "null" ] } }, "required": [ "id", "variant_id", "variant_title", "product_id", "product_title", "label", "quantity", "subtotal", "sku" ], "type": "object" }, "ReceiptStatus": { "description": "The status of a receipt", "enum": [ "draft", "open", "authorized", "paid", "pending", "uncollectible", "unresolved", "void" ], "example": "draft", "type": "string" }, "ReceiptTaxBehaviors": { "description": "The type of tax inclusivity applied to the receipt, for determining whether the tax is included in the final price, or paid on top.", "enum": [ "exclusive", "inclusive", "unspecified", "unable_to_collect" ], "example": "exclusive", "type": "string" }, "ReceiptV2Order": { "description": "The order to sort the results by.", "enum": [ "final_amount", "created_at", "paid_at" ], "type": "string" }, "Refund": { "properties": { "account_id": { "description": "The account that issued the refund, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "amount": { "description": "The refunded amount as it settled, in the payment's settlement currency, so pages of refunds net against the payment's `refunded_amount`. Converted at the rate in force when the refund was issued, not the payment's original rate. Null only when no exchange rate is recorded for a legacy multi-currency payment.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "created_at": { "description": "When the refund was requested, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "failure_message": { "description": "A merchant-facing explanation of why the refund failed, in the request's language. Null unless the refund failed or was canceled.", "example": "The customer's card is expired or was canceled.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Why the refund failed, normalized across providers. Null unless the refund failed or was canceled.", "enum": [ "bank_declined", "expired_or_canceled_card", "lost_or_stolen_card", "insufficient_funds", "charge_disputed", "not_refundable", "merchant_request", "unknown", null ], "example": "expired_or_canceled_card", "type": [ "string", "null" ] }, "id": { "description": "Refund ID, prefixed `rf_`.", "example": "rf_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Your own key-value data attached when the refund was requested.", "example": null, "type": [ "object", "null" ] }, "original_amount": { "$ref": "#/components/schemas/Money", "description": "The refunded amount in the currency the processor moved." }, "payment_id": { "description": "The payment this refund reverses, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "provider": { "description": "The payment provider that processed the refund, such as `paypal` or `coinbase`.", "example": "stripe", "type": "string" }, "provider_created_at": { "description": "When the provider created the refund, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "reason": { "description": "Why the refund was issued, when recorded.", "enum": [ "duplicate", "fraudulent", "requested_by_customer", "expired_uncaptured_charge", "dispute_alert", null ], "example": "duplicate", "type": [ "string", "null" ] }, "reference_status": { "description": "Whether a banking-network tracking reference is available for this refund.", "enum": [ "available", "pending", "unavailable", null ], "example": "available", "type": [ "string", "null" ] }, "reference_type": { "description": "The kind of tracking reference, such as an acquirer reference number.", "enum": [ "acquirer_reference_number", "retrieval_reference_number", "system_trace_audit_number", null ], "example": "acquirer_reference_number", "type": [ "string", "null" ] }, "reference_value": { "description": "The tracking reference the buyer's bank can trace the refund by.", "example": null, "type": [ "string", "null" ] }, "status": { "description": "Where the refund stands with the processor: `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`.", "enum": [ "pending", "requires_action", "succeeded", "failed", "canceled" ], "example": "failed", "type": "string" }, "updated_at": { "description": "When the refund last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visa_rdr": { "description": "True when the card network initiated the refund through Rapid Dispute Resolution.", "example": false, "type": "boolean" } }, "required": [ "id", "payment_id", "account_id", "status", "amount", "original_amount", "provider", "reason", "failure_reason", "failure_message", "reference_status", "reference_type", "reference_value", "visa_rdr", "metadata", "provider_created_at", "created_at", "updated_at" ], "type": "object" }, "RefundLegacy": { "description": "A refund represents a full or partial reversal of a payment, including the amount, status, and payment provider.", "properties": { "amount": { "description": "The refunded amount as a decimal in the specified currency, such as 10.43 for $10.43 USD.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the refund was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the refunded amount." }, "id": { "description": "The unique identifier for the refund.", "example": "rf_xxxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "The custom metadata attached when this refund was requested.", "type": [ "object", "null" ] }, "payment": { "description": "The original payment that this refund was issued against. Null if the payment is no longer available.", "properties": { "billing_reason": { "description": "The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.", "oneOf": [ { "$ref": "#/components/schemas/BillingReasons" }, { "type": "null" } ] }, "card_brand": { "description": "Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "card_last4": { "description": "The last four digits of the card used to make this payment. Null if the payment was not made with a card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur')." }, "dispute_alerted_at": { "description": "When an alert came in that this transaction will be disputed", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The member attached to this payment.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "phone": { "description": "The phone number for the member, if available.", "type": [ "string", "null" ] } }, "required": [ "id", "phone" ], "type": [ "object", "null" ] }, "membership": { "description": "The membership attached to this payment.", "properties": { "id": { "description": "The unique identifier for the membership.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/MembershipStatus", "description": "The state of the membership." } }, "required": [ "id", "status" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "The custom metadata stored on this payment. This will be copied over to the checkout configuration for which this payment was made", "type": [ "object", "null" ] }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "payment_method_type": { "description": "The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "plan": { "description": "The plan attached to this payment.", "properties": { "id": { "description": "The unique identifier for the plan.", "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this plan.", "type": [ "object", "null" ] } }, "required": [ "id", "metadata" ], "type": [ "object", "null" ] }, "product": { "description": "The product this payment was made for", "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs stored on the product and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.", "type": [ "object", "null" ] } }, "required": [ "id", "metadata" ], "type": [ "object", "null" ] }, "subtotal": { "description": "The subtotal to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "tax_amount": { "description": "The calculated amount of the sales/VAT tax (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "tax_behavior": { "description": "The type of tax inclusivity applied to the payment, for determining whether the tax is included in the final price, or paid on top.", "oneOf": [ { "$ref": "#/components/schemas/ReceiptTaxBehaviors" }, { "type": "null" } ] }, "tax_refunded_amount": { "description": "The amount of tax that has been refunded (if applicable).", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "usd_total": { "description": "The total in USD to show to the creator (excluding buyer fees).", "example": 6.9, "type": [ "number", "null" ] }, "user": { "description": "The user that made this payment.", "properties": { "email": { "description": "The user's email address. Requires the member:email:read permission to access. Null if not authorized.", "example": "john.doe@example.com", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username", "email" ], "type": [ "object", "null" ] } }, "required": [ "id", "total", "subtotal", "usd_total", "currency", "created_at", "paid_at", "dispute_alerted_at", "payment_method_type", "billing_reason", "card_brand", "card_last4", "tax_amount", "tax_behavior", "tax_refunded_amount", "metadata", "plan", "product", "user", "member", "membership" ], "type": [ "object", "null" ] }, "provider": { "$ref": "#/components/schemas/PaymentProviders", "description": "The payment provider that processed the refund." }, "provider_created_at": { "description": "The timestamp when the refund was created in the payment provider's system. Null if not available from the provider.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "reference_status": { "description": "The availability status of the refund tracking reference from the payment processor. Null if no reference was provided.", "oneOf": [ { "$ref": "#/components/schemas/RefundReferenceStatuses" }, { "type": "null" } ] }, "reference_type": { "description": "The type of tracking reference provided by the payment processor, such as an acquirer reference number. Null if no reference was provided.", "oneOf": [ { "$ref": "#/components/schemas/RefundReferenceTypes" }, { "type": "null" } ] }, "reference_value": { "description": "The tracking reference value from the payment processor, used to trace the refund through banking networks. Null if no reference was provided.", "example": "74850120752", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/RefundStatuses", "description": "The current processing status of the refund, such as pending, succeeded, or failed." } }, "required": [ "id", "amount", "currency", "status", "created_at", "metadata", "provider", "provider_created_at", "reference_status", "reference_type", "reference_value", "payment" ], "type": "object" }, "RefundListItem": { "description": "A refund represents a full or partial reversal of a payment, including the amount, status, and payment provider.", "properties": { "amount": { "description": "The refunded amount as a decimal in the specified currency, such as 10.43 for $10.43 USD.", "example": 6.9, "type": "number" }, "created_at": { "description": "The datetime the refund was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The three-letter ISO currency code for the refunded amount." }, "id": { "description": "The unique identifier for the refund.", "example": "rf_xxxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "The custom metadata attached when this refund was requested.", "type": [ "object", "null" ] }, "payment": { "description": "The original payment that this refund was issued against. Null if the payment is no longer available.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "provider": { "$ref": "#/components/schemas/PaymentProviders", "description": "The payment provider that processed the refund." }, "provider_created_at": { "description": "The timestamp when the refund was created in the payment provider's system. Null if not available from the provider.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "reference_status": { "description": "The availability status of the refund tracking reference from the payment processor. Null if no reference was provided.", "oneOf": [ { "$ref": "#/components/schemas/RefundReferenceStatuses" }, { "type": "null" } ] }, "reference_type": { "description": "The type of tracking reference provided by the payment processor, such as an acquirer reference number. Null if no reference was provided.", "oneOf": [ { "$ref": "#/components/schemas/RefundReferenceTypes" }, { "type": "null" } ] }, "reference_value": { "description": "The tracking reference value from the payment processor, used to trace the refund through banking networks. Null if no reference was provided.", "example": "74850120752", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/RefundStatuses", "description": "The current processing status of the refund, such as pending, succeeded, or failed." } }, "required": [ "id", "amount", "currency", "status", "created_at", "metadata", "provider", "provider_created_at", "reference_status", "reference_type", "reference_value", "payment" ], "type": "object" }, "RefundReferenceStatuses": { "description": "The status of the refund reference.", "enum": [ "available", "pending", "unavailable" ], "type": "string" }, "RefundReferenceTypes": { "description": "The type of refund reference that was made available by the payment provider.", "enum": [ "acquirer_reference_number", "retrieval_reference_number", "system_trace_audit_number" ], "type": "string" }, "RefundStatuses": { "description": "The different statuses for a Refund object", "enum": [ "pending", "requires_action", "succeeded", "failed", "canceled" ], "type": "string" }, "ReleaseMethod": { "description": "The methods of how a plan can be released.", "enum": [ "buy_now", "waitlist" ], "type": "string" }, "ResolutionAttachment": { "properties": { "content_type": { "description": "The file's MIME type.", "example": "image/png", "type": [ "string", "null" ] }, "filename": { "description": "The original file name.", "example": "booking-confirmation.png", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the attachment, prefixed `att_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "A URL to view or download the file.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "ResolutionBuyer": { "properties": { "email": { "description": "The customer's email address. Requires the `member:email:read` scope; `null` without it.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "member_id": { "description": "The customer's member row on the account, prefixed `mem_`.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "name": { "description": "The customer's display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "user_id": { "description": "The customer's user ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "username": { "description": "The customer's Whop username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "user_id", "member_id", "name", "username", "email" ], "type": "object" }, "ResolutionCenterCase": { "properties": { "account": { "description": "The account the case was filed against.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "amount": { "description": "The amount in question, in whole units of `currency`.", "example": 249.0, "type": "number" }, "available_actions": { "items": { "description": "What you can do to this case right now, named for the endpoint that does it. Resolved for the calling credential, so a merchant and a customer reading the same case see their own options.", "enum": [ "accept", "deny", "request_info", "reply", "appeal", "withdraw" ], "example": "accept", "type": "string" }, "type": "array" }, "buyer": { "$ref": "#/components/schemas/ResolutionBuyer", "description": "The customer who opened the case." }, "created_at": { "description": "When the case was opened, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code of the amount.", "example": "usd", "type": [ "string", "null" ] }, "customer_appealed": { "description": "Whether the customer has appealed a decision on this case.", "example": false, "type": "boolean" }, "escalated": { "description": "Whether Whop is involved — either reviewing the case, or waiting on the side named by `status` for something it asked for while reviewing.", "example": false, "type": "boolean" }, "id": { "description": "Resolution center case ID, prefixed `reso_`.", "example": "reso_xxxxxxxxxxxxxx", "type": "string" }, "line_items": { "items": { "$ref": "#/components/schemas/ReceiptLineItem", "description": "Everything the disputed payment charged for, in purchase order. `product_id` and `variant_id` name the first of these; a cart's later items appear only here. A payment made before items were recorded lists the single item its variant implies. Empty when the payment is not linked to a variant." }, "type": "array" }, "outcome": { "description": "Who prevailed on the claim. `null` until the case closes. Read `refund` for whether any money actually moved.", "enum": [ "customer_won", "merchant_won", "withdrawn", null ], "example": "merchant_won", "type": [ "string", "null" ] }, "payment": { "$ref": "#/components/schemas/ResolutionPayment", "description": "The payment the case was opened against." }, "product_id": { "description": "The product the payment was for, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "reason": { "description": "What the customer says went wrong. Shares the `/disputes` vocabulary, so a case that later becomes a chargeback reports the same complaint.", "enum": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "example": "product_not_received", "type": "string" }, "refund": { "description": "Whether money moved and off whose balance: `none`, `merchant`, or `platform` (Whop refunded the customer and the merchant kept the funds). Independent of `outcome` — a case the merchant won can still carry a platform refund. `null` while the case is open, and on older closed cases that predate this being recorded.", "enum": [ "none", "merchant", "platform", null ], "example": "none", "type": [ "string", "null" ] }, "response_due_at": { "description": "When the next response is due, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Who the case is waiting on. `awaiting_merchant` and `awaiting_customer` name the side that owes a response, `under_review` means Whop is deciding, and `closed` means it is settled — read `outcome` for how.", "enum": [ "awaiting_merchant", "awaiting_customer", "under_review", "closed" ], "example": "closed", "type": "string" }, "updated_at": { "description": "When the case was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "variant_id": { "description": "The variant the payment was made on, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "status", "escalated", "outcome", "refund", "reason", "amount", "currency", "account", "product_id", "variant_id", "line_items", "customer_appealed", "available_actions", "response_due_at", "buyer", "payment", "created_at", "updated_at" ], "type": "object" }, "ResolutionCenterCaseActions": { "description": "The different types of actions for a resolution event", "enum": [ "created", "responded", "accepted", "denied", "appealed", "withdrew", "requested_more_info", "escalated", "dispute_opened", "dispute_customer_won", "dispute_merchant_won" ], "type": "string" }, "ResolutionCenterCaseCustomerResponses": { "description": "The types of responses a customer can make to a resolution.", "enum": [ "respond", "appeal", "withdraw" ], "type": "string" }, "ResolutionCenterCaseIssueTypes": { "description": "The different types of issues a resolution can be", "enum": [ "forgot_to_cancel", "item_not_received", "significantly_not_as_described", "unauthorized_transaction", "product_unacceptable" ], "type": "string" }, "ResolutionCenterCaseLegacy": { "description": "A resolution center case is a dispute or support case between a user and a company, tracking the issue, status, and outcome.", "properties": { "company": { "description": "The company involved in this resolution case. Null if the company no longer exists.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the resolution was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "customer_appealed": { "description": "Whether the customer has filed an appeal after the initial resolution decision.", "type": "boolean" }, "customer_response_actions": { "description": "The list of actions currently available to the customer.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseCustomerResponses" }, "type": "array" }, "due_date": { "description": "The deadline by which the next response is required. Null if no deadline is currently active. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the resolution.", "example": "reso_xxxxxxxxxxxxx", "type": "string" }, "issue": { "$ref": "#/components/schemas/ResolutionCenterCaseIssueTypes", "description": "The category of the dispute." }, "member": { "description": "The membership record associated with the disputed payment. Null if the membership no longer exists.", "properties": { "id": { "description": "The unique identifier for the extra public member.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "merchant_appealed": { "description": "Whether the merchant has filed an appeal after the initial resolution decision.", "type": "boolean" }, "merchant_response_actions": { "description": "The list of actions currently available to the merchant.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseMerchantResponses" }, "type": "array" }, "payment": { "description": "The payment record that is the subject of this resolution case.", "properties": { "created_at": { "description": "The datetime the payment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "description": "The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "paid_at": { "description": "The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "subtotal": { "description": "The payment amount before taxes and discounts are applied. In the currency specified by the currency field.", "example": 6.9, "type": [ "number", "null" ] }, "total": { "description": "The total amount charged to the customer for this payment, including taxes and after any discounts. In the currency specified by the currency field.", "example": 6.9, "type": "number" } }, "required": [ "id", "currency", "created_at", "paid_at", "total", "subtotal" ], "type": "object" }, "platform_response_actions": { "description": "The list of actions currently available to the Whop platform for moderating this resolution.", "items": { "$ref": "#/components/schemas/ResolutionCenterCasePlatformResponses" }, "type": "array" }, "resolution_events": { "description": "The most recent 50 messages, actions, and status changes that have occurred during this resolution case.", "items": { "description": "A resolution event is a message or action within a resolution case, such as a response, escalation, or status change.", "properties": { "action": { "$ref": "#/components/schemas/ResolutionCenterCaseActions", "description": "The type of action recorded in this event." }, "created_at": { "description": "The datetime the resolution event was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "details": { "description": "The message body or additional context provided with this resolution event. Null if no details were included.", "example": "I did not authorize this purchase.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the resolution event.", "example": "revt_xxxxxxxxxxxxx", "type": "string" }, "reporter_type": { "$ref": "#/components/schemas/ResolutionCenterCaseReporters", "description": "The party who performed this action." } }, "required": [ "id", "action", "reporter_type", "details", "created_at" ], "type": "object" }, "type": "array" }, "status": { "$ref": "#/components/schemas/ResolutionCenterCaseStatuses", "description": "The current status of the resolution case, indicating which party needs to respond or if the case is closed." }, "updated_at": { "description": "The datetime the resolution was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The customer (buyer) who filed this resolution case.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "status", "issue", "created_at", "updated_at", "due_date", "customer_appealed", "merchant_appealed", "customer_response_actions", "merchant_response_actions", "company", "user", "platform_response_actions", "payment", "member", "resolution_events" ], "type": "object" }, "ResolutionCenterCaseListItem": { "description": "A resolution center case is a dispute or support case between a user and a company, tracking the issue, status, and outcome.", "properties": { "company": { "description": "The company involved in this resolution case. Null if the company no longer exists.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the company shown to customers.", "example": "Pickaxe", "type": "string" } }, "required": [ "id", "title" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the resolution was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "customer_appealed": { "description": "Whether the customer has filed an appeal after the initial resolution decision.", "type": "boolean" }, "customer_response_actions": { "description": "The list of actions currently available to the customer.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseCustomerResponses" }, "type": "array" }, "due_date": { "description": "The deadline by which the next response is required. Null if no deadline is currently active. As a Unix timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the resolution.", "example": "reso_xxxxxxxxxxxxx", "type": "string" }, "issue": { "$ref": "#/components/schemas/ResolutionCenterCaseIssueTypes", "description": "The category of the dispute." }, "merchant_appealed": { "description": "Whether the merchant has filed an appeal after the initial resolution decision.", "type": "boolean" }, "merchant_response_actions": { "description": "The list of actions currently available to the merchant.", "items": { "$ref": "#/components/schemas/ResolutionCenterCaseMerchantResponses" }, "type": "array" }, "payment": { "description": "The payment record that is the subject of this resolution case.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "status": { "$ref": "#/components/schemas/ResolutionCenterCaseStatuses", "description": "The current status of the resolution case, indicating which party needs to respond or if the case is closed." }, "updated_at": { "description": "The datetime the resolution was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The customer (buyer) who filed this resolution case.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "status", "issue", "created_at", "updated_at", "due_date", "customer_appealed", "merchant_appealed", "customer_response_actions", "merchant_response_actions", "company", "user", "payment" ], "type": "object" }, "ResolutionCenterCaseMerchantResponses": { "description": "The types of responses a merchant can make to a resolution.", "enum": [ "accept", "deny", "request_more_info", "appeal", "respond" ], "type": "string" }, "ResolutionCenterCasePlatformResponses": { "description": "The types of responses the platform can make to a resolution.", "enum": [ "request_buyer_info", "request_merchant_info", "merchant_wins", "merchant_refund" ], "type": "string" }, "ResolutionCenterCaseReporters": { "description": "The different types of reporters for a resolution event", "enum": [ "merchant", "customer", "platform", "system" ], "type": "string" }, "ResolutionCenterCaseStatuses": { "description": "The statuses a resolution object can have", "enum": [ "merchant_response_needed", "customer_response_needed", "merchant_info_needed", "customer_info_needed", "under_platform_review", "customer_won", "merchant_won", "customer_withdrew" ], "type": "string" }, "ResolutionEvent": { "properties": { "action": { "description": "The action recorded in this event.", "enum": [ "created", "responded", "accepted", "denied", "appealed", "withdrew", "requested_more_info", "escalated", "dispute_opened", "dispute_customer_won", "dispute_merchant_won" ], "example": "created", "type": "string" }, "attachments": { "items": { "$ref": "#/components/schemas/ResolutionAttachment", "description": "Files attached to this event, such as screenshots or documents." }, "type": "array" }, "created_at": { "description": "When the event occurred, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "details": { "description": "The message body or additional context provided with the event.", "example": "Booked the Ceramic Coating Package for 2026-01-05; nobody arrived.", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the event, prefixed `revt_`.", "example": "revt_xxxxxxxxxxxxxx", "type": "string" }, "reporter_type": { "description": "The party that performed the action.", "enum": [ "merchant", "customer", "platform", "system" ], "example": "customer", "type": "string" }, "viewable_by_customer": { "description": "Whether the customer can see this event in the timeline.", "example": true, "type": "boolean" }, "viewable_by_merchant": { "description": "Whether the merchant can see this event in the timeline.", "example": true, "type": "boolean" } }, "required": [ "id", "action", "reporter_type", "details", "viewable_by_customer", "viewable_by_merchant", "created_at", "attachments" ], "type": "object" }, "ResolutionPayment": { "properties": { "card_brand": { "description": "Card brand, when the customer paid by card.", "example": "visa", "type": [ "string", "null" ] }, "card_last4": { "description": "Last four digits of the card, when the customer paid by card.", "example": "4242", "type": [ "string", "null" ] }, "created_at": { "description": "When the payment was made, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Payment ID, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "payment_method_type": { "description": "How the customer paid, such as `card` or `paypal`.", "example": "card", "type": [ "string", "null" ] } }, "required": [ "id", "payment_method_type", "card_brand", "card_last4", "created_at" ], "type": "object" }, "Review": { "properties": { "account": { "$ref": "#/components/schemas/ReviewAccount", "description": "The account that this review was written for." }, "attachments": { "items": { "$ref": "#/components/schemas/ReviewAttachment", "description": "A list of files and media attached to the review." }, "type": "array" }, "created_at": { "description": "When the review was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "description": { "description": "The body text of the review containing the user's detailed feedback. Returns an empty string if no description was provided.", "example": "Two years on and the paint still beads like the day it was coated.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the review.", "example": "rev_xxxxxxxxxxxxxx", "type": "string" }, "joined_at": { "description": "When the reviewer first joined the product, as an ISO 8601 timestamp. Null if unknown.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "paid_for_product": { "description": "Whether the reviewer paid for the product. Null if the payment status is unknown.", "example": true, "type": [ "boolean", "null" ] }, "product": { "$ref": "#/components/schemas/ReviewProduct", "description": "The product that this review was written for." }, "published_at": { "description": "When the review was published, as an ISO 8601 timestamp. Null if unknown.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "stars": { "description": "The star rating given by the reviewer, from 1 to 5.", "example": 4, "type": "integer" }, "status": { "description": "The moderation status of the review. Only published reviews are returned.", "enum": [ "published" ], "example": "published", "type": "string" }, "title": { "description": "A short summary title for the review. Null if the reviewer did not provide one.", "example": "Worth every penny", "type": [ "string", "null" ] }, "updated_at": { "description": "When the review was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user": { "$ref": "#/components/schemas/ReviewUser", "description": "The user account of the person who wrote this review." } }, "required": [ "id", "title", "description", "stars", "status", "paid_for_product", "created_at", "updated_at", "published_at", "joined_at", "user", "attachments", "account", "product" ], "type": "object" }, "ReviewAccount": { "properties": { "id": { "description": "The unique identifier for the account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "route": { "description": "URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.", "example": "shine-time-auto-detailing", "type": "string" }, "title": { "description": "The display name of the account shown to customers.", "example": "Shine Time Auto Detailing", "type": "string" } }, "required": [ "id", "title", "route" ], "type": "object" }, "ReviewAttachment": { "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/png", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "coated-hood.png", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.", "example": "https://img.whop.com/xxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx/mb:180000/plain/https://assets-2-rough.whop.com/uploads/image/2026-01-01/review-coated-hood", "type": [ "string", "null" ] } }, "required": [ "id", "filename", "content_type", "url" ], "type": "object" }, "ReviewListItem": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/ReviewAttachment", "description": "A list of files and media attached to the review." }, "type": "array" }, "created_at": { "description": "When the review was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "description": { "description": "The body text of the review containing the user's detailed feedback. Returns an empty string if no description was provided.", "example": "Two years on and the paint still beads like the day it was coated.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the review.", "example": "rev_xxxxxxxxxxxxxx", "type": "string" }, "joined_at": { "description": "When the reviewer first joined the product, as an ISO 8601 timestamp. Null if unknown.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "paid_for_product": { "description": "Whether the reviewer paid for the product. Null if the payment status is unknown.", "example": true, "type": [ "boolean", "null" ] }, "published_at": { "description": "When the review was published, as an ISO 8601 timestamp. Null if unknown.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "stars": { "description": "The star rating given by the reviewer, from 1 to 5.", "example": 4, "type": "integer" }, "status": { "description": "The moderation status of the review. Only published reviews are returned.", "enum": [ "published" ], "example": "published", "type": "string" }, "title": { "description": "A short summary title for the review. Null if the reviewer did not provide one.", "example": "Worth every penny", "type": [ "string", "null" ] }, "updated_at": { "description": "When the review was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user": { "$ref": "#/components/schemas/ReviewUser", "description": "The user account of the person who wrote this review." } }, "required": [ "id", "title", "description", "stars", "status", "paid_for_product", "created_at", "updated_at", "published_at", "joined_at", "user", "attachments" ], "type": "object" }, "ReviewProduct": { "properties": { "id": { "description": "The unique identifier for the product.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the product shown to customers on the product page and in search results.", "example": "Ceramic Coating Package", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "ReviewStatus": { "description": "The statuses a review can have", "enum": [ "pending", "published", "removed" ], "type": "string" }, "ReviewUser": { "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "danawhitfield", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" }, "ScheduleFrequencies": { "description": "How often a scheduled bounty republishes a new bounty.", "enum": [ "once", "hourly", "daily", "weekly", "monthly" ], "type": "string" }, "SetupIntent": { "properties": { "account_id": { "description": "The account the payment method is saved for, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "checkout_configuration_id": { "description": "The checkout configuration this setup was created through, prefixed `ch_`. Null for a setup created through this API rather than a hosted checkout.", "example": null, "type": [ "string", "null" ] }, "client_secret": { "description": "The credential a buyer's surface presents to poll this setup and set its return URL — hand it to the elements' `handleNextAction`. Only on setups created through this API, and always null in list responses — retrieve the setup intent for it.", "example": "sint_xxxxxxxxxxxxxx_secret_vdefault_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "created_at": { "description": "When the setup intent was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Setup intent ID, prefixed `sint_`.", "example": "sint_xxxxxxxxxxxxxx", "type": "string" }, "last_setup_error": { "description": "Why the setup ended where it did, or `null` when nothing has failed. Present on `canceled` — a buyer who abandoned carries no code, one refused by the provider does. Dropped once the setup succeeds.", "oneOf": [ { "$ref": "#/components/schemas/SetupLastSetupError" }, { "type": "null" } ] }, "member_id": { "description": "The buyer's member record on the account, prefixed `mber_`. Null without the member:basic:read permission, unless the caller is the buyer.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "description": "Your own key-value data attached when the setup intent was created.", "example": { "customer_id": "cus_4417" }, "type": [ "object", "null" ] }, "payment_instrument": { "description": "The method behind this setup shaped for display: a buyer-facing name, the standard icon set, and the card's brand, last four, issuer identification number, and expiry when it was a card. Null until a method was collected.", "oneOf": [ { "$ref": "#/components/schemas/PaymentInstrument" }, { "type": "null" } ] }, "payment_method_id": { "description": "The saved payment method, prefixed `payt_`, ready to charge with Create Payment. Null until the setup has `succeeded`.", "example": "payt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_method_type": { "description": "The kind of instrument being saved, for example `card` or `us_bank_account`.", "oneOf": [ { "$ref": "#/components/schemas/PaymentMethodTypes" }, { "type": "null" } ] }, "return_url": { "description": "Where the buyer lands after completing an off-site step, or `null` to leave them where they are.", "example": "https://shinetime.example/billing/saved", "type": [ "string", "null" ] }, "status": { "description": "How far the setup has got. **A 201 or 200 means we answered, not that the method was saved — always branch on this.** `requires_action` — the buyer has a step outstanding; hand `client_secret` to the elements or poll Retrieve setup status. `processing` — the processor is deciding. `succeeded` — the method is saved, and only this one means saved. `canceled` — abandoned or refused; see `last_setup_error`.", "enum": [ "processing", "succeeded", "canceled", "requires_action" ], "example": "requires_action", "type": "string" }, "three_ds_level": { "description": "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. The setting requested for this setup, or `null` when unset.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "three_ds_verified": { "description": "True when the buyer completed 3D Secure while saving this payment method.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the setup intent was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user": { "description": "The user saving the payment method. Null when the buyer is a company rather than a user.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] } }, "required": [ "id", "status", "account_id", "member_id", "user", "payment_method_type", "payment_method_id", "payment_instrument", "checkout_configuration_id", "return_url", "last_setup_error", "three_ds_verified", "three_ds_level", "metadata", "created_at", "updated_at", "client_secret" ], "type": "object" }, "SetupIntentLegacy": { "description": "A setup intent allows a user to save a payment method for future use without making an immediate purchase.", "properties": { "checkout_configuration": { "description": "The checkout session configuration associated with this setup intent. Null if no checkout session was used.", "properties": { "id": { "description": "The unique identifier for the checkout session.", "example": "ch_xxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "company": { "description": "The company that initiated this setup intent. Null if the company has been deleted.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the setup intent was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "error_message": { "description": "A human-readable error message explaining why the setup intent failed. Null if no error occurred.", "example": "Your card was declined.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the setup intent.", "example": "sint_xxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The company member associated with this setup intent. Null if the user is not a member.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "user": { "description": "The user for this member, if any.", "properties": { "email": { "description": "The digital mailing address of the user.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company member user.", "type": "string" }, "name": { "description": "The user's full name.", "type": [ "string", "null" ] }, "username": { "description": "The whop username.", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "user" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this setup intent. Null if no metadata was provided.", "type": [ "object", "null" ] }, "payment_method": { "description": "The saved payment method created by this setup intent. Null if the setup has not completed successfully.", "properties": { "card": { "description": "The card data associated with the payment method, if its a debit or credit card.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment token.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "mailing_address": { "description": "The mailing address associated with the payment method's user", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The payment method type of the payment method" } }, "required": [ "id", "created_at", "payment_method_type", "card", "mailing_address" ], "type": [ "object", "null" ] }, "status": { "$ref": "#/components/schemas/SetupIntentStatuses", "description": "The current status of the setup intent." }, "three_ds_verified": { "description": "Whether 3D Secure authentication was completed when this payment method was set up.", "type": "boolean" } }, "required": [ "id", "status", "created_at", "error_message", "company", "checkout_configuration", "member", "payment_method", "metadata", "three_ds_verified" ], "type": "object" }, "SetupIntentListItem": { "description": "A setup intent allows a user to save a payment method for future use without making an immediate purchase.", "properties": { "checkout_configuration": { "description": "The checkout session configuration associated with this setup intent. Null if no checkout session was used.", "properties": { "id": { "description": "The unique identifier for the checkout session.", "example": "ch_xxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "company": { "description": "The company that initiated this setup intent. Null if the company has been deleted.", "properties": { "id": { "description": "The unique identifier for the company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the setup intent was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "error_message": { "description": "A human-readable error message explaining why the setup intent failed. Null if no error occurred.", "example": "Your card was declined.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the setup intent.", "example": "sint_xxxxxxxxxxxxx", "type": "string" }, "member": { "description": "The company member associated with this setup intent. Null if the user is not a member.", "properties": { "id": { "description": "The unique identifier for the company member.", "type": "string" }, "user": { "description": "The user for this member, if any.", "properties": { "email": { "description": "The digital mailing address of the user.", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the company member user.", "type": "string" }, "name": { "description": "The user's full name.", "type": [ "string", "null" ] }, "username": { "description": "The whop username.", "type": "string" } }, "required": [ "id", "email", "name", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "user" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to this setup intent. Null if no metadata was provided.", "type": [ "object", "null" ] }, "payment_method": { "description": "The saved payment method created by this setup intent. Null if the setup has not completed successfully.", "properties": { "card": { "description": "The card data associated with the payment method, if its a debit or credit card.", "properties": { "brand": { "description": "The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.", "oneOf": [ { "$ref": "#/components/schemas/CardBrands" }, { "type": "null" } ] }, "exp_month": { "description": "The two-digit expiration month of the card (1-12). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "exp_year": { "description": "The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.", "example": 42, "type": [ "integer", "null" ] }, "last4": { "description": "The last four digits of the card number. Null if not available.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "created_at": { "description": "The datetime the payment token was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the payment token.", "example": "payt_xxxxxxxxxxxxx", "type": "string" }, "mailing_address": { "description": "The mailing address associated with the payment method's user", "properties": { "city": { "description": "The city of the address.", "type": [ "string", "null" ] }, "country": { "description": "The country of the address.", "type": [ "string", "null" ] }, "line1": { "description": "The line 1 of the address.", "type": [ "string", "null" ] }, "line2": { "description": "The line 2 of the address.", "type": [ "string", "null" ] }, "name": { "description": "The name of the customer.", "type": [ "string", "null" ] }, "postal_code": { "description": "The postal code of the address.", "type": [ "string", "null" ] }, "state": { "description": "The state of the address.", "type": [ "string", "null" ] } }, "required": [ "name", "line1", "line2", "city", "state", "postal_code", "country" ], "type": [ "object", "null" ] }, "payment_method_type": { "$ref": "#/components/schemas/PaymentMethodTypes", "description": "The payment method type of the payment method" } }, "required": [ "id", "created_at", "payment_method_type", "card", "mailing_address" ], "type": [ "object", "null" ] }, "status": { "$ref": "#/components/schemas/SetupIntentStatuses", "description": "The current status of the setup intent." } }, "required": [ "id", "status", "created_at", "error_message", "company", "checkout_configuration", "member", "payment_method", "metadata" ], "type": "object" }, "SetupIntentStatuses": { "description": "The status of the setup intent.", "enum": [ "processing", "succeeded", "canceled", "requires_action" ], "type": "string" }, "SetupLastSetupError": { "properties": { "code": { "description": "A machine-readable classification of the failure, e.g. `enrollment_declined`. Absent when the buyer simply abandoned the setup.", "example": "enrollment_declined", "type": [ "string", "null" ] }, "message": { "description": "A human-readable explanation of the failure.", "example": "The bank declined the enrollment.", "type": [ "string", "null" ] } }, "required": [ "code", "message" ], "type": "object" }, "SetupStatus": { "properties": { "id": { "description": "The setup this status describes, prefixed `sint_`.", "example": "sint_xxxxxxxxxxxxxx", "type": "string" }, "last_setup_error": { "description": "Why the setup ended where it did, or `null` when nothing has failed. Present on `canceled` — a buyer who abandoned carries no code, one refused by the provider does.", "oneOf": [ { "$ref": "#/components/schemas/SetupLastSetupError" }, { "type": "null" } ] }, "next_action": { "description": "What the buyer must do next while `status` is `requires_action`, otherwise `null`. `type` picks the shape and each variant carries only its own `data`, so switching on `type` gives you exactly that step's payload.", "oneOf": [ { "$ref": "#/components/schemas/PaymentNextAction" }, { "type": "null" } ] }, "object": { "description": "Always `setup_status`.", "example": "setup_status", "type": "string" }, "return_url": { "description": "Where to send the buyer once the setup reaches a resting state, or `null` to leave them where they are.", "example": "https://shinetime.example/billing/saved", "type": [ "string", "null" ] }, "status": { "description": "How far the setup has got. **A 200 means we answered, not that the method was saved — always branch on this.** `requires_action` — the buyer has a step outstanding; see `next_action`. `processing` — the buyer has done their part and the processor is deciding. `succeeded` — the payment method is saved, and only this one means saved. `canceled` — abandoned or refused; see `last_setup_error` to tell which.", "enum": [ "processing", "succeeded", "canceled", "requires_action" ], "example": "canceled", "type": "string" } }, "required": [ "id", "object", "status", "next_action", "last_setup_error", "return_url" ], "type": "object" }, "Shipment": { "properties": { "account_id": { "description": "The account that owns this shipment, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "carrier": { "description": "The shipping carrier detected for this shipment. Null until a tracking update identifies it.", "example": "ups", "type": [ "string", "null" ] }, "checkpoints": { "items": { "$ref": "#/components/schemas/ShipmentCheckpoint", "description": "Carrier scan history for this shipment, oldest scan first. Empty until the carrier reports its first scan." }, "type": "array" }, "created_at": { "description": "The datetime the shipment was created (ISO 8601).", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Shipment ID, prefixed `ship_`.", "example": "ship_xxxxxxxxxxxxxx", "type": "string" }, "payment_id": { "description": "The payment this shipment fulfills, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "The current delivery status of this shipment.", "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error" ], "example": "in_transit", "type": "string" }, "tracking_number": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "1Z999AA10123456784", "type": "string" }, "tracking_url": { "description": "A customer-facing URL to track this shipment's progress.", "example": "https://track.aftership.com/xxxxxxxxxxxxxxxxxx", "type": "string" }, "updated_at": { "description": "The datetime the shipment was last updated (ISO 8601).", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "account_id", "status", "tracking_number", "carrier", "tracking_url", "checkpoints", "payment_id", "created_at", "updated_at" ], "type": "object" }, "ShipmentCheckpoint": { "properties": { "location": { "description": "Where the carrier recorded the scan, such as `PHILADELPHIA, PA`. Null when the carrier sent none.", "example": "PHILADELPHIA, PA", "type": [ "string", "null" ] }, "message": { "description": "Carrier's description of the scan, such as `Departed USPS Regional Facility`. Null when the carrier sent none.", "example": "Picked up", "type": [ "string", "null" ] }, "status": { "description": "Delivery status this carrier scan maps to.", "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error" ], "example": "in_transit", "type": "string" }, "timestamp": { "description": "When the carrier recorded the scan, as an ISO 8601 timestamp. Null when the carrier sent no scan time.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "status", "message", "location", "timestamp" ], "type": "object" }, "ShipmentLegacy": { "description": "A physical shipment associated with a payment, including carrier details and tracking information.", "properties": { "created_at": { "description": "The datetime the shipment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "delivery_estimate": { "description": "The estimated delivery date for this shipment. Null if the carrier has not provided an estimate.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the shipment.", "example": "ship_xxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The payment associated with this shipment. Null if the payment has been deleted or is inaccessible.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "service": { "description": "The shipping service level used for this shipment. Null if the carrier does not specify a service tier.", "example": "Priority", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ShipmentStatuses", "description": "The current delivery status of this shipment." }, "substatus": { "description": "A more granular status providing additional detail about the shipment's current state. Null if no substatus applies.", "oneOf": [ { "$ref": "#/components/schemas/ShipmentSubstatuses" }, { "type": "null" } ] }, "tracking_code": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "9400111899223456789012", "type": "string" }, "updated_at": { "description": "The datetime the shipment was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "created_at", "status", "substatus", "tracking_code", "updated_at", "service", "delivery_estimate", "payment" ], "type": "object" }, "ShipmentListItem": { "description": "A physical shipment associated with a payment, including carrier details and tracking information.", "properties": { "created_at": { "description": "The datetime the shipment was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "delivery_estimate": { "description": "The estimated delivery date for this shipment. Null if the carrier has not provided an estimate.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The unique identifier for the shipment.", "example": "ship_xxxxxxxxxxxxx", "type": "string" }, "payment": { "description": "The payment associated with this shipment. Null if the payment has been deleted or is inaccessible.", "properties": { "id": { "description": "The unique identifier for the payment.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "service": { "description": "The shipping service level used for this shipment. Null if the carrier does not specify a service tier.", "example": "Priority", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ShipmentStatuses", "description": "The current delivery status of this shipment." }, "substatus": { "description": "A more granular status providing additional detail about the shipment's current state. Null if no substatus applies.", "oneOf": [ { "$ref": "#/components/schemas/ShipmentSubstatuses" }, { "type": "null" } ] }, "tracking_code": { "description": "The carrier-assigned tracking number used to look up shipment progress.", "example": "9400111899223456789012", "type": "string" }, "updated_at": { "description": "The datetime the shipment was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" } }, "required": [ "id", "created_at", "status", "substatus", "tracking_code", "updated_at", "service", "delivery_estimate", "payment" ], "type": "object" }, "ShipmentLookup": { "properties": { "payment_id": { "description": "The matching payment, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "shipment": { "description": "The payment's latest shipment, or `null` when a paid physical purchase has no tracking yet.", "oneOf": [ { "$ref": "#/components/schemas/Shipment" }, { "type": "null" } ] } }, "required": [ "payment_id", "shipment" ], "type": "object" }, "ShipmentStatuses": { "description": "The status of a shipment", "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error" ], "type": "string" }, "ShipmentSubstatuses": { "description": "The substatus of a shipment", "enum": [ "address_correction", "arrived_at_destination", "arrived_at_facility", "arrived_at_pickup_location", "awaiting_information", "substatus_cancelled", "damaged", "delayed", "delivery_exception", "departed_facility", "departed_origin_facility", "expired", "substatus_failure", "held", "substatus_in_transit", "label_created", "lost", "missorted", "substatus_out_for_delivery", "received_at_destination_facility", "received_at_origin_facility", "refused", "return", "status_update", "transferred_to_destination_carrier", "transit_exception", "substatus_unknown", "weather_delay" ], "type": "string" }, "SocialAccount": { "properties": { "error": { "description": "Why this social account currently can't be used for advertising — a failed share or a Meta-side restriction. Null when the account is healthy.", "example": null, "type": [ "string", "null" ] }, "external_id": { "description": "The platform-specific ID for this social account.", "example": "17841479809129315", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the social account.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of the social account on the platform.", "example": "Shine Time Detail", "type": [ "string", "null" ] }, "parent_social_account": { "description": "The social account this one belongs to on the platform, such as the Facebook page that owns an Instagram account. Null when the social account stands on its own, or when it is a partner.", "oneOf": [ { "$ref": "#/components/schemas/SocialAccountParent" }, { "type": "null" } ] }, "partnership_status": { "description": "Where a partner creator's permission to run partnership ads stands. `pending` until the creator approves it in the Instagram app, `approved` once they have, and `revoked` once it no longer holds. Null when the social account isn't a partner.", "enum": [ null, "pending", "approved", "revoked" ], "example": "pending", "type": [ "string", "null" ] }, "platform": { "description": "The platform the social account exists on.", "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram", "linkedin", "snapchat", "klaviyo" ], "example": "instagram", "type": "string" }, "profile_picture_url": { "description": "The URL where the profile picture of the social account can be accessed.", "example": "https://shinetime.example/instagram.png", "type": [ "string", "null" ] }, "scopes": { "items": { "description": "Capabilities Whop retains specific to this social account. For example, Whop may request the ability to run advertisements that use this social account's identity, reflected by `advertise`. Personal profile connections have no additional Whop scopes.", "example": "advertise", "type": "string" }, "type": "array" }, "url": { "description": "The URL where the social account can be accessed on the platform. Null while a Whop-owned account is still being provisioned.", "example": "https://instagram.com/shinetimedetail", "type": [ "string", "null" ] }, "username": { "description": "The username of the social account on the platform. Null while a Whop-owned account is still being provisioned, and on platforms without usernames, such as Klaviyo.", "example": "shinetimedetail", "type": [ "string", "null" ] }, "verified": { "description": "Whether the social account is verified on the platform.", "example": true, "type": "boolean" } }, "required": [ "id", "platform", "username", "name", "url", "profile_picture_url", "verified", "external_id", "scopes", "partnership_status", "error", "parent_social_account" ], "type": "object" }, "SocialAccountLeadForm": { "properties": { "completion": { "description": "Screen shown after the form is submitted. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormCompletion" }, { "type": "null" } ] }, "created_at": { "description": "When the form was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "disclaimer": { "description": "Custom consent disclaimer shown before submission. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormDisclaimer" }, { "type": "null" } ] }, "form_type": { "description": "`more_volume` is quickest to submit; `higher_intent` adds a confirmation step before submission.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "id": { "description": "The ad platform's identifier for the form. Use it as lead_gen_form_id on an ad to reuse the form.", "example": "24839", "type": "string" }, "intro": { "description": "Intro screen shown before the questions. `null` when the form has none.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadFormIntro" }, { "type": "null" } ] }, "locale": { "description": "Language the form is shown in, such as en_US.", "example": "en_US", "type": [ "string", "null" ] }, "name": { "description": "Advertiser-facing form name.", "example": "Ceramic coating quote requests", "type": [ "string", "null" ] }, "privacy_policy_link_text": { "description": "Custom link text for the privacy policy. `null` when the default is used.", "example": "Shine Time privacy policy", "type": [ "string", "null" ] }, "privacy_policy_url": { "description": "Privacy policy URL configured on the form.", "example": "https://shinetime.example/privacy", "type": [ "string", "null" ] }, "question_labels": { "items": { "description": "Labels of the questions the form asks, for preview.", "example": "Email", "type": "string" }, "type": "array" }, "questions": { "items": { "$ref": "#/components/schemas/AdLeadFormQuestion", "description": "Questions on the form, in order." }, "type": "array" } }, "required": [ "id", "name", "locale", "created_at", "form_type", "privacy_policy_url", "privacy_policy_link_text", "question_labels", "questions", "intro", "completion", "disclaimer" ], "type": "object" }, "SocialAccountParent": { "properties": { "external_id": { "description": "The platform-specific ID for the parent social account.", "example": "page_1", "type": [ "string", "null" ] }, "id": { "description": "Social account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The display name of the parent social account on the platform.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "platform": { "description": "The platform the parent social account exists on.", "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram", "linkedin", "snapchat", "klaviyo" ], "example": "facebook", "type": "string" }, "profile_picture_url": { "description": "The URL where the profile picture of the parent social account can be accessed.", "example": "https://shinetime.example/logo.png", "type": [ "string", "null" ] }, "username": { "description": "The username of the parent social account on the platform.", "example": "shinetimedetailing", "type": [ "string", "null" ] }, "verified": { "description": "Whether the parent social account is verified on the platform.", "example": true, "type": "boolean" } }, "required": [ "id", "platform", "username", "name", "profile_picture_url", "verified", "external_id" ], "type": "object" }, "SocialAccountPost": { "properties": { "call_to_action": { "description": "The post's call-to-action button, for example shop_now (Facebook only; null for Instagram and TikTok).", "enum": [ "learn_more", "shop_now", "sign_up", "subscribe", "get_started", "book_now", "apply_now", "contact_us", "download", "order_now", "buy_now", "get_quote", "message_page", "whatsapp_message", "instagram_message", "call_now", "get_directions", "send_updates", "get_offer", "watch_more", "listen_now", "play_game", "open_link", "no_button", "get_offer_view", "get_event_tickets", "see_menu", "request_time", "event_rsvp", "see_details", "view_instagram_profile", null ], "example": "shop_now", "type": [ "string", "null" ] }, "caption": { "description": "The text accompanying the post, when available.", "example": "Ceramic coating in action", "type": [ "string", "null" ] }, "destination_url": { "description": "The URL the post's call-to-action drives to (Facebook only; null for Instagram and TikTok).", "example": "https://shinetime.example/book", "type": [ "string", "null" ] }, "embed_url": { "description": "An iframe-embeddable URL for previewing the post inline (the platform's player or post embed). For TikTok this is the only preview, since media_url is null; for Facebook and Instagram it supplements media_url. Null when no public embed is available.", "example": "https://www.facebook.com/plugins/post.php", "type": [ "string", "null" ] }, "id": { "description": "The platform's own identifier for the post or media. Use it to reference the post on an ad.", "example": "media_1", "type": "string" }, "media_url": { "description": "The URL of the post's media — the image for image posts, the playable video file for video posts. Null for TikTok, which exposes no raw file (use embed_url). Meta URLs are signed and expire after roughly 24 hours, so don't store them.", "example": "https://shinetime.example/ceramic-coating-reel.mp4", "type": [ "string", "null" ] }, "restrictions": { "items": { "description": "Ways this post can't be used on an ad. `lead_form_ineligible`: post can't be used in lead form ads. `promotion_ineligible`: the platform won't promote this post at all — always present when that's true, alongside a reason code when one is identified. `copyrighted_music`: post uses music the platform does not allow for ads. `messenger_destination`, `instagram_destination`, `whatsapp_destination`: the post's own button opens that chat app, so the post can only run in an ad group that sends people to the same one — always accompanied by `lead_form_ineligible`. Empty when the post has no restrictions.", "enum": [ "lead_form_ineligible", "promotion_ineligible", "copyrighted_music", "messenger_destination", "instagram_destination", "whatsapp_destination" ], "example": "lead_form_ineligible", "type": "string" }, "type": "array" }, "thumbnail_url": { "description": "Poster image for video posts (always set for TikTok, which is video-only); null for image posts, where media_url is already the image.", "example": "https://shinetime.example/ceramic-coating-poster.jpg", "type": [ "string", "null" ] }, "video_id": { "description": "The platform video identifier for engagement audience rules. Null for non-video posts or when unavailable. Facebook video identifiers differ from post identifiers.", "example": "18000000000000000", "type": [ "string", "null" ] } }, "required": [ "video_id", "caption", "id", "media_url", "thumbnail_url", "embed_url", "call_to_action", "destination_url", "restrictions" ], "type": "object" }, "SpecificFeeOrigins": { "description": "The origin of the specific fee", "enum": [ "stripe_domestic_processing_fee", "stripe_international_processing_fee", "stripe_fixed_processing_fee", "stripe_billing_fee", "stripe_radar_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "stripe_sales_tax_fee", "whop_processing_fee", "marketplace_affiliate_fee", "affiliate_fee", "crypto_fee", "stripe_standard_processing_fee", "paypal_fee", "stripe_payout_fee", "dispute_fee", "dispute_alert_fee", "dispute_representment_fee", "apple_processing_fee", "buyer_fee", "sezzle_processing_fee", "splitit_processing_fee", "platform_balance_processing_fee", "payment_processing_percentage_fee", "payment_processing_fixed_fee", "cross_border_percentage_fee", "fx_percentage_fee", "orchestration_percentage_fee", "three_ds_fixed_fee", "billing_percentage_fee", "revshare_percentage_fee", "application_fee", "high_risk_merchant_fee", "economic_intelligence_percentage_fee", "payment_return_fee" ], "type": "string" }, "Status": { "description": "Statuses for resources", "enum": [ "active", "archived", "deleted" ], "type": "string" }, "Statuses": { "description": "The available bounty statuses to choose from.", "enum": [ "published", "archived", "scheduled" ], "type": "string" }, "StorefrontAccount": { "properties": { "id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo image URL. `null` when the account has not set one.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Account public route identifier — the `whop.com/{route}` storefront path.", "example": "shine-time-auto-detailing", "type": "string" }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": "string" } }, "required": [ "id", "title", "route", "logo_url" ], "type": "object" }, "SupportChannel": { "description": "A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.", "properties": { "account_id": { "description": "The unique identifier of the account associated with this channel. Null if this is not a support or account-scoped conversation.", "type": [ "string", "null" ] }, "company_id": { "description": "The unique identifier of the account associated with this channel. Null if this is not a support or account-scoped conversation.", "type": [ "string", "null" ] }, "custom_name": { "description": "A custom display name assigned to this channel by the user. Null if no custom name has been set.", "example": "Project Alpha Team", "type": [ "string", "null" ] }, "customer_user": { "description": "The customer who initiated this support conversation. Null if this is not a support chat.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_message": { "description": "The most recent message in this channel. Null if no messages have been sent, or when listing support channels without `include_last_message`.", "properties": { "attachments": { "description": "A list of all attachments on this message, including files and media.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] } }, "required": [ "filename", "content_type" ], "type": "object" }, "type": "array" }, "content": { "description": "The message content formatted as Markdown. Null if the message has no text content.", "example": "Hey, are you available for a **quick call**?", "type": [ "string", "null" ] }, "created_at": { "description": "The timestamp when this message was originally created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "gifs": { "description": "A list of GIF animations attached to this message.", "items": { "description": "Represents a GIF attachment in a feed post", "properties": { "slug": { "description": "The unique identifier of the GIF", "type": "string" } }, "required": [ "slug" ], "type": "object" }, "type": "array" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "poll": { "description": "A poll attached to this message. Null if the message does not contain a poll.", "properties": { "options": { "description": "The options for the poll", "items": { "description": "Represents a single poll option", "properties": { "id": { "description": "The unique identifier for the poll option.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": [ "array", "null" ] } }, "required": [ "options" ], "type": [ "object", "null" ] }, "user_id": { "description": "The unique identifier of the user who authored this message.", "type": "string" } }, "required": [ "id", "content", "created_at", "user_id", "attachments", "gifs", "poll" ], "type": [ "object", "null" ] }, "last_message_at": { "description": "The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "needs_reply": { "description": "Whether the customer sent the latest message and the linked support ticket is unresolved. Null if not a support chat.", "type": [ "boolean", "null" ] }, "participated": { "description": "Whether the authenticated user has joined this channel as a participant. Null when the caller is not a user, or when listing support channels without `include_participated`.", "type": [ "boolean", "null" ] }, "resolved_at": { "description": "The timestamp when the linked support ticket was marked as resolved. Null if unresolved or not a support chat.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "unread": { "description": "Whether this channel has a message from someone else that the authenticated user has not viewed yet. Null when the caller is not a user, or when listing support channels without `include_last_message`.", "type": [ "boolean", "null" ] } }, "required": [ "id", "company_id", "account_id", "custom_name", "customer_user", "resolved_at", "last_message_at", "last_message", "needs_reply", "unread", "participated" ], "type": "object" }, "SupportChannelListItem": { "description": "A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.", "properties": { "account_id": { "description": "The unique identifier of the account associated with this channel. Null if this is not a support or account-scoped conversation.", "type": [ "string", "null" ] }, "company_id": { "description": "The unique identifier of the account associated with this channel. Null if this is not a support or account-scoped conversation.", "type": [ "string", "null" ] }, "custom_name": { "description": "A custom display name assigned to this channel by the user. Null if no custom name has been set.", "example": "Project Alpha Team", "type": [ "string", "null" ] }, "customer_user": { "description": "The customer who initiated this support conversation. Null if this is not a support chat.", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": [ "object", "null" ] }, "id": { "description": "The unique identifier for the entity", "type": "string" }, "last_message": { "description": "The most recent message in this channel. Null if no messages have been sent, or when listing support channels without `include_last_message`.", "properties": { "attachments": { "description": "A list of all attachments on this message, including files and media.", "items": { "description": "Represents an image attachment", "properties": { "content_type": { "description": "Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.", "example": "image/jpeg", "type": [ "string", "null" ] }, "filename": { "description": "The original filename of the uploaded attachment, including its file extension.", "example": "document.pdf", "type": [ "string", "null" ] } }, "required": [ "filename", "content_type" ], "type": "object" }, "type": "array" }, "content": { "description": "The message content formatted as Markdown. Null if the message has no text content.", "example": "Hey, are you available for a **quick call**?", "type": [ "string", "null" ] }, "created_at": { "description": "The timestamp when this message was originally created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "gifs": { "description": "A list of GIF animations attached to this message.", "items": { "description": "Represents a GIF attachment in a feed post", "properties": { "slug": { "description": "The unique identifier of the GIF", "type": "string" } }, "required": [ "slug" ], "type": "object" }, "type": "array" }, "id": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "poll": { "description": "A poll attached to this message. Null if the message does not contain a poll.", "properties": { "options": { "description": "The options for the poll", "items": { "description": "Represents a single poll option", "properties": { "id": { "description": "The unique identifier for the poll option.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": [ "array", "null" ] } }, "required": [ "options" ], "type": [ "object", "null" ] }, "user_id": { "description": "The unique identifier of the user who authored this message.", "type": "string" } }, "required": [ "id", "content", "created_at", "user_id", "attachments", "gifs", "poll" ], "type": [ "object", "null" ] }, "last_message_at": { "description": "The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "needs_reply": { "description": "Whether the customer sent the latest message and the linked support ticket is unresolved. Null if not a support chat.", "type": [ "boolean", "null" ] }, "participated": { "description": "Whether the authenticated user has joined this channel as a participant. Null when the caller is not a user, or when listing support channels without `include_participated`.", "type": [ "boolean", "null" ] }, "resolved_at": { "description": "The timestamp when the linked support ticket was marked as resolved. Null if unresolved or not a support chat.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "unread": { "description": "Whether this channel has a message from someone else that the authenticated user has not viewed yet. Null when the caller is not a user, or when listing support channels without `include_last_message`.", "type": [ "boolean", "null" ] } }, "required": [ "id", "company_id", "account_id", "custom_name", "customer_user", "resolved_at", "last_message_at", "last_message", "needs_reply", "unread", "participated" ], "type": "object" }, "SupportChannelView": { "description": "The perspective to filter support channels by.", "enum": [ "all", "admin", "customer" ], "type": "string" }, "TargetingOption": { "description": "One result from the ad-group targeting-options search. `type` picks the shape: detailed-targeting taxonomy options carry the ad platform's `id`, languages carry an ISO 639 `code`, and locations carry the platform `key` plus geographic context.", "discriminator": { "mapping": { "behaviors": "#/components/schemas/DetailedTargetingOption", "education_majors": "#/components/schemas/DetailedTargetingOption", "education_schools": "#/components/schemas/DetailedTargetingOption", "family_statuses": "#/components/schemas/DetailedTargetingOption", "income": "#/components/schemas/DetailedTargetingOption", "industries": "#/components/schemas/DetailedTargetingOption", "interests": "#/components/schemas/DetailedTargetingOption", "languages": "#/components/schemas/LanguageTargetingOption", "life_events": "#/components/schemas/DetailedTargetingOption", "locations": "#/components/schemas/LocationTargetingOption", "work_employers": "#/components/schemas/DetailedTargetingOption", "work_positions": "#/components/schemas/DetailedTargetingOption" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/DetailedTargetingOption" }, { "$ref": "#/components/schemas/LanguageTargetingOption" }, { "$ref": "#/components/schemas/LocationTargetingOption" } ] }, "TaxId": { "properties": { "type": { "description": "The registration's type, such as `eu_vat`.", "enum": [ "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" ], "example": "us_ein", "type": "string" }, "value": { "description": "The registration number as the buyer entered it, whitespace removed (`eu_vat` values also drop dots and dashes).", "example": "12-3456789", "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "TaxIdentifierTypes": { "description": "The type of tax identifier", "enum": [ "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" ], "type": "string" }, "TaxTypes": { "description": "Whether or not the tax is included in a plan's price (or if it hasn't been set up)", "enum": [ "inclusive", "exclusive", "unspecified" ], "type": "string" }, "TeamMember": { "properties": { "account_id": { "description": "The account this membership belongs to, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "authorized_role": { "description": "Custom role assigned to this member, or `null` when the member has a system role.", "oneOf": [ { "$ref": "#/components/schemas/TeamMemberAuthorizedRole" }, { "type": "null" } ] }, "created_at": { "description": "When the member joined or the invite was sent, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "direct_reports_count": { "description": "How many team members report directly to this member. `null` for invites.", "example": 0, "type": [ "integer", "null" ] }, "email": { "description": "The member's email address. For an invite sent to an email with no Whop account yet, the invited address; for accepted members and invites to an existing Whop account, `null` unless the caller holds the `company:authorized_user:email:read` scope.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "Team member ID — `ausr_` for accepted members, `mber_` for members whose role is held on their member record, `ausri_` for pending invites.", "example": "ausr_xxxxxxxxxxxxxx", "type": "string" }, "is_agent": { "description": "Whether this member is an agent (app-controlled account) rather than a human team member. Always `false` for invites.", "example": false, "type": "boolean" }, "reports_to_id": { "description": "The team member this member reports to, prefixed `ausr_`, or `mber_` when that manager's role is held on their member record. `null` when the member reports to the business directly, and for invites.", "example": "ausr_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "role": { "description": "The member's role on the account. `custom` means a bespoke dashboard-managed role; the API can read but not grant it.", "enum": [ "owner", "admin", "partner", "sales_manager", "moderator", "advertiser", "app_manager", "support", "manager", "workforce", "custom" ], "example": "admin", "type": "string" }, "status": { "description": "`joined` for accepted members, `pending` while the invite is pending.", "enum": [ "joined", "pending" ], "example": "joined", "type": "string" }, "updated_at": { "description": "When the membership was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user": { "description": "The user behind this team membership. `null` for an invite sent to an email with no Whop account yet.", "oneOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ] } }, "required": [ "id", "status", "role", "is_agent", "account_id", "email", "created_at", "updated_at", "authorized_role", "reports_to_id", "direct_reports_count", "user" ], "type": "object" }, "TeamMemberAuthorizedRole": { "properties": { "id": { "description": "Custom role ID, prefixed `aurl_`.", "example": "aurl_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Custom role name.", "example": "community-moderators", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "Trade": { "properties": { "account_id": { "description": "The account that owns the trading wallet, prefixed `biz_`. `null` when a user owns it.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "amount": { "description": "The USDT0 that a deposit, or an order short of trading balance, sends from the wallet, or the USDC that a withdraw sends back, in native units, as a decimal string. A withdraw of `all` shows what it sent once it finishes. `null` otherwise.", "example": "25", "type": [ "string", "null" ] }, "average_price": { "description": "The average fill price of the order, in USD, as a decimal string. `null` when it is not known.", "example": null, "type": [ "string", "null" ] }, "client_order_id": { "description": "The caller's own ID for the trade, unique for the account. `null` when none was sent.", "example": null, "type": [ "string", "null" ] }, "completed_at": { "description": "When the trade ended as completed or failed, as an ISO 8601 timestamp. `null` before that.", "example": null, "type": [ "string", "null" ] }, "created_at": { "description": "When the trade was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "failure_code": { "description": "Why the trade failed, or `null`.", "enum": [ "market_unavailable", "leverage_too_high", "amount_too_small", "isolated_position_open", "trading_paused", "funding_failed", "margin_unavailable", "builder_fee_unapproved", "leverage_rejected", "leverage_unconfirmed", "order_rejected", "close_rejected", "return_failed", "withdraw_failed", null ], "example": "market_unavailable", "type": [ "string", "null" ] }, "filled_size": { "description": "The size the order filled, in units of the market, as a decimal string. `null` until it fills.", "example": null, "type": [ "string", "null" ] }, "funds_location": { "description": "Where the money is when the trade did not complete as asked: `wallet`, `trading_account`, or `unknown` while a person checks it. `null` otherwise.", "enum": [ "wallet", "trading_account", "unknown", null ], "example": "wallet", "type": [ "string", "null" ] }, "id": { "description": "Trade ID, prefixed `tint_`.", "example": "tint_xxxxxxxxxxxxxx", "type": "string" }, "instrument_type": { "description": "`perpetual` or `spot` for an order, `perpetual` for a close. `null` for a deposit or withdraw.", "enum": [ "perpetual", "spot", null ], "example": "perpetual", "type": [ "string", "null" ] }, "leverage": { "description": "The cross leverage set before an opening perpetual order. `null` for a spot order, close, deposit, withdraw or reduce-only order.", "example": 10, "type": [ "integer", "null" ] }, "market": { "description": "The market, for example `BTC` for a perpetual or `HYPE/USDC` for spot. `null` for a deposit or withdraw.", "example": "BTC", "type": [ "string", "null" ] }, "metadata": { "description": "Free-form string-to-string annotations stored on the trade.", "example": {}, "type": "object" }, "object": { "enum": [ "trade" ], "example": "trade", "type": "string" }, "order_type": { "description": "`market` or `limit` for an order. `null` otherwise.", "enum": [ "market", "limit", null ], "example": "market", "type": [ "string", "null" ] }, "price": { "description": "The limit price of the order in USD. A market order's price is the mid price moved by `slippage_bps`. `null` for other types.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "reduce_only": { "description": "Whether the order can only reduce a position. `null` for other types.", "example": null, "type": [ "boolean", "null" ] }, "side": { "description": "`buy` or `sell` for an order. `null` otherwise.", "enum": [ "buy", "sell", null ], "example": "buy", "type": [ "string", "null" ] }, "size": { "description": "The order size in units of the market, as a decimal string. `null` for other types.", "example": null, "type": [ "string", "null" ] }, "status": { "description": "`pending` until the trade starts. `processing` while it runs, also while an order that did not fill sends the money it bridged in back to the wallet. `completed` when it did what was asked. `failed` when it did not; `funds_location` says where the money is. `in_review` when the outcome is unknown and a person checks it.", "enum": [ "pending", "processing", "in_review", "completed", "failed" ], "example": "pending", "type": "string" }, "status_detail": { "description": "`partial_fill` when the order filled only part of its size. `null` otherwise.", "enum": [ "partial_fill", null ], "example": "partial_fill", "type": [ "string", "null" ] }, "type": { "description": "`order` places one order from the trading balance. `deposit` bridges USDT0 from the wallet to the trading balance. `withdraw` sends USDC from the trading balance back to the wallet. `close` closes the whole position in one market with a market reduce-only order; when the account is then flat, a `withdraw` trade sends the trading balance back to the wallet.", "enum": [ "close", "order", "deposit", "withdraw" ], "example": "order", "type": "string" }, "updated_at": { "description": "When the trade last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user_id": { "description": "The user who owns the trading wallet, prefixed `user_`. `null` when an account owns it.", "example": null, "type": [ "string", "null" ] } }, "required": [ "id", "type", "status", "status_detail", "account_id", "user_id", "instrument_type", "market", "side", "order_type", "size", "price", "reduce_only", "leverage", "amount", "filled_size", "average_price", "funds_location", "failure_code", "client_order_id", "metadata", "created_at", "updated_at", "completed_at", "object" ], "type": "object" }, "TradingAccount": { "properties": { "account_id": { "description": "The account that owns this trading account, prefixed `biz_`. `null` when a user owns it.", "type": [ "string", "null" ] }, "hyperliquid": { "description": "Hyperliquid-specific state. Present when `provider` is `hyperliquid`, otherwise `null`.", "oneOf": [ { "$ref": "#/components/schemas/TradingHyperliquidAccount" }, { "type": "null" } ] }, "id": { "description": "The Whop wallet ID backing this trading account, prefixed `cwal_`.", "type": "string" }, "object": { "enum": [ "trading_account" ], "example": "trading_account", "type": "string" }, "provider": { "description": "Trading venue that holds the positions and orders.", "enum": [ "hyperliquid" ], "example": "hyperliquid", "type": "string" }, "user_id": { "description": "The user who owns this trading account, prefixed `user_`. `null` when an account owns it.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "account_id", "user_id", "provider", "hyperliquid" ], "type": "object" }, "TradingCumulativeFunding": { "properties": { "all_time": { "description": "Funding paid on this market across the account's history, in USD, or `null` when unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "since_change": { "description": "Funding paid since the position size last changed, in USD, or `null` when unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "since_open": { "description": "Funding paid since the position opened, in USD, or `null` when unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "all_time", "since_open", "since_change" ], "type": "object" }, "TradingHyperliquidAccount": { "properties": { "address": { "description": "Lowercase wallet address that holds the Hyperliquid account.", "type": "string" }, "websocket_subscriptions": { "items": { "$ref": "#/components/schemas/TradingWebsocketSubscription", "description": "Subscriptions for live account updates. Send each `message` unchanged after connecting to `websocket_url`." }, "type": "array" }, "websocket_url": { "description": "Hyperliquid WebSocket URL to connect to directly for live updates.", "type": "string" } }, "required": [ "address", "websocket_url", "websocket_subscriptions" ], "type": "object" }, "TradingHyperliquidOrder": { "properties": { "reduce_only": { "description": "Whether the order can only reduce an existing position, or `null` when Hyperliquid omits it.", "type": [ "boolean", "null" ] }, "trigger_price": { "description": "Trigger price in USD for take-profit and stop-loss orders, or `null` for orders without a trigger.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "required": [ "reduce_only", "trigger_price" ], "type": "object" }, "TradingHyperliquidPosition": { "properties": { "cumulative_funding": { "$ref": "#/components/schemas/TradingCumulativeFunding", "description": "Funding paid on the position over several windows, in USD." }, "leverage": { "$ref": "#/components/schemas/TradingPositionLeverage", "description": "Margin mode and multiplier for the position." }, "liquidation_price": { "description": "Estimated liquidation price in USD, or `null` when Hyperliquid reports none.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "margin_used": { "$ref": "#/components/schemas/Money", "description": "Margin allocated to the position, in USD." }, "return_on_equity": { "description": "Return on equity as a decimal ratio string, such as `0.1` for 10%.", "type": "string" } }, "required": [ "leverage", "liquidation_price", "margin_used", "return_on_equity", "cumulative_funding" ], "type": "object" }, "TradingMarginSummary": { "properties": { "account_value": { "$ref": "#/components/schemas/Money", "description": "Total account value in USD, including unrealized profit and loss." }, "total_margin_used": { "$ref": "#/components/schemas/Money", "description": "Margin allocated across open positions, in USD." }, "total_position_notional": { "$ref": "#/components/schemas/Money", "description": "Combined notional value of open positions, in USD." }, "total_raw_usd": { "$ref": "#/components/schemas/Money", "description": "Raw USD balance as Hyperliquid reports it, excluding position value." }, "withdrawable": { "$ref": "#/components/schemas/Money", "description": "USD that can be withdrawn now without closing positions." } }, "required": [ "account_value", "total_position_notional", "total_raw_usd", "total_margin_used", "withdrawable" ], "type": "object" }, "TradingOrder": { "properties": { "client_order_id": { "description": "Client order ID, prefixed `trdcloid_`, or `null` when the order was placed without one.", "type": [ "string", "null" ] }, "created_at": { "description": "When the order was placed, as an ISO 8601 timestamp, or `null` when the provider omits it.", "type": [ "string", "null" ] }, "hyperliquid": { "description": "Hyperliquid-specific order details. Present on Hyperliquid orders, otherwise `null`.", "oneOf": [ { "$ref": "#/components/schemas/TradingHyperliquidOrder" }, { "type": "null" } ] }, "id": { "description": "Trading order ID, prefixed `trdord_`.", "type": "string" }, "market": { "description": "Market symbol on the provider, such as `ETH`.", "type": "string" }, "object": { "enum": [ "trading_order" ], "example": "trading_order", "type": "string" }, "order_type": { "enum": [ "limit", "market", "take_profit", "stop_loss" ], "example": "limit", "type": "string" }, "original_size": { "description": "Size when the order was placed, as a decimal string, or `null` when the provider omits it.", "type": [ "string", "null" ] }, "price": { "$ref": "#/components/schemas/Money", "description": "Limit price in USD." }, "provider_order_id": { "description": "The provider's own order ID, as a string.", "type": [ "string", "null" ] }, "side": { "enum": [ "buy", "sell" ], "example": "buy", "type": "string" }, "size": { "description": "Remaining order size as a decimal string.", "type": "string" }, "status": { "enum": [ "open", "filled", "canceled", "triggered", "rejected" ], "example": "open", "type": "string" }, "status_updated_at": { "description": "When the status last changed, as an ISO 8601 timestamp, or `null` when the provider omits it.", "type": [ "string", "null" ] }, "time_in_force": { "description": "How long the order stays active. `null` when the provider omits it or reports a policy outside the supported values.", "enum": [ "add_liquidity_only", "good_til_canceled", "immediate_or_cancel", null ], "example": "add_liquidity_only", "type": [ "string", "null" ] } }, "required": [ "object", "id", "client_order_id", "provider_order_id", "market", "side", "size", "original_size", "price", "order_type", "time_in_force", "status", "created_at", "status_updated_at", "hyperliquid" ], "type": "object" }, "TradingPosition": { "properties": { "entry_price": { "description": "Average entry price in USD, or `null` when the provider omits it.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "hyperliquid": { "description": "Hyperliquid perpetual details. Present on Hyperliquid positions, otherwise `null`.", "oneOf": [ { "$ref": "#/components/schemas/TradingHyperliquidPosition" }, { "type": "null" } ] }, "id": { "description": "Trading position ID, prefixed `trdpos_`. Stable for a market within one trading account.", "type": "string" }, "market": { "description": "Market symbol on the provider, such as `ETH`.", "type": "string" }, "object": { "enum": [ "trading_position" ], "example": "trading_position", "type": "string" }, "position_value": { "$ref": "#/components/schemas/Money", "description": "Current position value in USD." }, "side": { "enum": [ "long", "short" ], "example": "long", "type": "string" }, "size": { "description": "Absolute position size as a decimal string.", "type": "string" }, "unrealized_pnl": { "$ref": "#/components/schemas/Money", "description": "Unrealized profit or loss in USD. Negative for a loss." } }, "required": [ "object", "id", "market", "side", "size", "entry_price", "position_value", "unrealized_pnl", "hyperliquid" ], "type": "object" }, "TradingPositionLeverage": { "properties": { "type": { "description": "`cross` shares margin across positions; `isolated` limits margin to this position.", "enum": [ "cross", "isolated" ], "example": "cross", "type": "string" }, "value": { "description": "Multiplier applied to the position's margin, such as `10` for 10x.", "type": "integer" } }, "required": [ "type", "value" ], "type": "object" }, "TradingWebsocketSubscription": { "properties": { "channel": { "description": "The live update stream this subscription opens.", "enum": [ "clearinghouse_state", "open_orders", "order_updates", "user_fills", "user_events" ], "example": "clearinghouse_state", "type": "string" }, "message": { "description": "JSON subscription message to send unchanged over the Hyperliquid WebSocket.", "type": "string" } }, "required": [ "channel", "message" ], "type": "object" }, "UploadStatuses": { "description": "The upload status of a file", "enum": [ "pending", "processing", "ready", "failed" ], "type": "string" }, "User": { "properties": { "balance": { "description": "The user's balance: personal cash + other holdings + deposits still in flight, plus account balances for accounts they own. Computed only on the self view (retrieved with the reserved id `me`) for callers with balance-read scope; `null` otherwise, or when `include_balance=false`.", "oneOf": [ { "$ref": "#/components/schemas/UserBalance" }, { "type": "null" } ] }, "balance_history": { "description": "The user's cumulative wallet balance over time (USD `{ t, v }` points plus last/min/max), for the balance chart. Opt in with `include_balance_history=true` when retrieving yourself with the reserved id `me`; populated only for callers with balance-read scope and `null` otherwise. A user with no wallet activity returns an empty series.", "oneOf": [ { "$ref": "#/components/schemas/UserBalanceHistory" }, { "type": "null" } ] }, "balances": { "items": { "$ref": "#/components/schemas/AccountBalanceToken", "description": "The user's personal holdings, each with its USD value and breakdown, in the same shape as an account's `balances`. Empty when `total_usd` is `null`." }, "type": "array" }, "banner": { "description": "The user's profile banner wrapper. `null` when the user has no banner.", "oneOf": [ { "$ref": "#/components/schemas/UserBanner" }, { "type": "null" } ] }, "bio": { "description": "The user's biography", "example": "Ceramic coating specialist. Detailing cars in Austin since 2016.", "type": [ "string", "null" ] }, "cards": { "description": "Where the user's personal card application stands. Populated only on the self view (retrieved with the reserved id `me`) for callers with balance-read scope; `null` otherwise, or when the user has never applied for a card.", "oneOf": [ { "$ref": "#/components/schemas/AccountCards" }, { "type": "null" } ] }, "created_at": { "description": "When the user was created, as an ISO 8601 timestamp", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "earnings_usd": { "description": "The user's gross USD income over time, including a Partner commission breakdown. Populated only on single-user self reads for callers with balance-read scope; `null` otherwise.", "oneOf": [ { "$ref": "#/components/schemas/UserEarnings" }, { "type": "null" } ] }, "email": { "description": "The user's email address. Populated only on the self view (retrieved with the reserved id `me`) for callers with email-read scope; `null` otherwise, or while the account has no confirmed email yet.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "level": { "description": "The user's Whop Levels progress, counted across every account they own. Populated only on the self view (retrieved with the reserved id `me`) for callers with balance-read scope; `null` otherwise, and when none of their accounts are in Whop Levels.", "oneOf": [ { "$ref": "#/components/schemas/OwnerLevel" }, { "type": "null" } ] }, "name": { "description": "The user's display name", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "$ref": "#/components/schemas/UserProfilePicture", "description": "Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture." }, "social_links": { "items": { "$ref": "#/components/schemas/UserSocialLink", "description": "The social accounts and websites on the user's public profile. Empty when the user has none." }, "type": "array" }, "total_usd": { "description": "Total USD value of the user's personal holdings in `balances`, across those with known exchange rates. Computed only on the self view (retrieved with the reserved id `me`) for callers with balance-read scope; `null` otherwise, when `include_balance=false`, or when the balance source is unavailable.", "example": "6320.75", "type": [ "string", "null" ] }, "trading": { "description": "The trading account address and its WebSocket subscriptions. Opt in with `include_trading=true` when retrieving `me`. `null` otherwise, without trading permission, or without an Ethereum wallet.", "oneOf": [ { "$ref": "#/components/schemas/TradingAccount" }, { "type": "null" } ] }, "username": { "description": "The user's unique username", "example": "marcuswebb", "type": "string" }, "verification": { "description": "Identity verification status for the user's `individual` (KYC) and `business` (KYB) profiles. Each is `null` until created, otherwise a `status` of `not_started`, `pending`, `approved`, or `rejected`.", "example": { "business": null, "individual": null }, "type": "object" }, "whop_partner_enabled_at": { "description": "When the user became an enrolled Whop Partner, as an ISO 8601 timestamp. `null` if never enrolled.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "whop_partner_onboarded_accounts_count": { "description": "Number of accounts the user referred to Whop as a Whop Partner that have processed more than $1 in volume attributed to the user. Populated only when retrieving a single user who is a Verified Whop Partner; `null` otherwise.", "example": 1, "type": [ "integer", "null" ] }, "whop_partner_verified_at": { "description": "When the user became a Verified Whop Partner, as an ISO 8601 timestamp. `null` for users who are not Verified Whop Partners, including partners who left the program and suspended users.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "id", "username", "name", "bio", "created_at", "profile_picture", "banner", "email", "balance", "total_usd", "balances", "earnings_usd", "balance_history", "cards", "trading", "level", "verification", "whop_partner_enabled_at", "whop_partner_verified_at", "whop_partner_onboarded_accounts_count", "social_links" ], "type": "object" }, "UserBalance": { "properties": { "businesses": { "items": { "$ref": "#/components/schemas/UserBalanceBusiness", "description": "Account balances for accounts the user owns, highest balance first. Excludes accounts with no balance." }, "type": "array" }, "businesses_total_usd": { "description": "Combined USD balance across every account the user owns.", "example": "18940.25", "type": "string" }, "cash": { "items": { "$ref": "#/components/schemas/UserBalanceCash", "description": "Per-currency fiat cash balances." }, "type": "array" }, "cash_usd": { "description": "Fiat cash in USD, including pending, in-transit, and reserve.", "example": "4820.75", "type": "string" }, "crypto": { "items": { "$ref": "#/components/schemas/UserBalanceToken", "description": "Per-token crypto holdings in the ledger's own wallet." }, "type": "array" }, "crypto_usd": { "description": "Crypto holdings in USD.", "example": "1500.00", "type": "string" }, "pending_usd": { "description": "Fiat pending and in-transit balances, plus in-flight treasury deposits, in USD.", "example": "310.00", "type": "string" }, "total_usd": { "description": "The user's personal balance in USD: cash (available + pending + in-transit + reserve) + other holdings + deposits still in flight. Excludes account balances (see businesses_total_usd).", "example": "6320.75", "type": "string" }, "treasury_pending_usd": { "description": "Balance moves into the user's wallet still in flight, in USD.", "example": "0.00", "type": "string" } }, "required": [ "total_usd", "cash_usd", "crypto_usd", "treasury_pending_usd", "pending_usd", "cash", "crypto", "businesses_total_usd", "businesses" ], "type": "object" }, "UserBalanceBusiness": { "properties": { "balance_usd": { "description": "The account's total balance in USD.", "example": "18940.25", "type": "string" }, "id": { "description": "The account ID, which looks like biz_*************.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "The account's logo URL.", "example": "https://assets.whop.com/logos/shine-time-auto-detailing.png", "type": [ "string", "null" ] }, "name": { "description": "The account's display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "id", "name", "logo_url", "balance_usd" ], "type": "object" }, "UserBalanceCash": { "properties": { "balance": { "description": "Available balance in the native currency.", "example": 4385.75, "type": "number" }, "balance_usd": { "description": "Available balance converted to USD.", "example": 4385.75, "type": "number" }, "currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`.", "example": "usd", "type": "string" }, "in_transit_balance_usd": { "description": "Balance moving to the user's own wallet or card, converted to USD.", "example": 0.0, "type": "number" }, "pending_balance_usd": { "description": "Pending balance converted to USD.", "example": 310.0, "type": "number" }, "price_usd": { "description": "USD price per native currency unit, or `null` when no exchange rate is available.", "example": null, "type": [ "number", "null" ] }, "reserve_balance_usd": { "description": "Reserved balance converted to USD.", "example": 125.0, "type": "number" }, "total_withdrawable_balance": { "description": "Withdrawable amount in the native currency.", "example": 4385.75, "type": "number" } }, "required": [ "currency", "balance", "balance_usd", "pending_balance_usd", "in_transit_balance_usd", "reserve_balance_usd", "price_usd", "total_withdrawable_balance" ], "type": "object" }, "UserBalanceHistory": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UserBalanceHistoryPoint", "description": "Cumulative balance points over the requested window, oldest first." }, "type": "array" }, "last": { "description": "Value of the most recent point, in USD.", "example": 6320.75, "type": "number" }, "max": { "description": "Maximum value across the window, in USD.", "example": 6320.75, "type": "number" }, "min": { "description": "Minimum value across the window, in USD.", "example": 2400.0, "type": "number" } }, "required": [ "data", "last", "min", "max" ], "type": "object" }, "UserBalanceHistoryPoint": { "properties": { "t": { "description": "Point timestamp, in Unix seconds.", "example": 1767268800, "type": "integer" }, "v": { "description": "Cumulative wallet balance at this point, in USD.", "example": 2400.0, "type": "number" } }, "required": [ "t", "v" ], "type": "object" }, "UserBalanceToken": { "properties": { "balance": { "description": "Amount held in native token units, as a decimal string.", "example": "1500.0", "type": "string" }, "breakdown": { "$ref": "#/components/schemas/AccountBalanceBreakdown", "description": "Balance split into available, pending, in-transit, and reserve amounts, as native-unit decimal strings. Transfers between the user's own wallet and card are reported in `in_transit` until they arrive." }, "icon_url": { "description": "Token icon URL.", "example": "https://assets.whop.com/tokens/usdt.png", "type": [ "string", "null" ] }, "name": { "description": "The token's display name.", "example": "Tether USD", "type": [ "string", "null" ] }, "price_usd": { "description": "USD price per token, or `null` when unknown.", "example": 1.0, "type": [ "number", "null" ] }, "symbol": { "description": "Token display symbol, such as `USDT`, `XAUT`, or `cbBTC`.", "example": "USDT", "type": "string" }, "value_usd": { "description": "Holding USD value.", "example": 1500.0, "type": "number" } }, "required": [ "symbol", "name", "balance", "value_usd", "price_usd", "icon_url", "breakdown" ], "type": "object" }, "UserBanner": { "properties": { "url": { "description": "Profile banner image URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "url" ], "type": "object" }, "UserEarnings": { "properties": { "first_earned_at": { "description": "The first time the user earned gross income, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "owned_accounts": { "$ref": "#/components/schemas/UserEarningsAmount", "description": "Gross income from accounts the user owns or is owner-authorized on." }, "partners": { "$ref": "#/components/schemas/UserEarningsAmount", "description": "Partner commissions posted to the user's wallet. Pending Partner payouts are excluded until they post; later reversals do not reduce gross income." }, "personal": { "$ref": "#/components/schemas/UserEarningsAmount", "description": "Gross income from the user's personal wallet." }, "total": { "$ref": "#/components/schemas/UserEarningsAmount", "description": "Gross income from the user's personal wallet plus accounts they own or are owner-authorized on." } }, "required": [ "total", "personal", "owned_accounts", "partners", "first_earned_at" ], "type": "object" }, "UserEarningsAmount": { "properties": { "last_24_hours": { "description": "Gross income in USD over the last 24 hours.", "example": "0.00", "type": "string" }, "last_30_days": { "description": "Gross income in USD over the last 30 days.", "example": "0.00", "type": "string" }, "last_7_days": { "description": "Gross income in USD over the last 7 days.", "example": "0.00", "type": "string" }, "lifetime": { "description": "All-time gross income in USD.", "example": "0.00", "type": "string" } }, "required": [ "lifetime", "last_30_days", "last_7_days", "last_24_hours" ], "type": "object" }, "UserFees": { "properties": { "bank_deposit": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on bank deposits into the user's balance." }, "payouts": { "additionalProperties": { "$ref": "#/components/schemas/AccountFee" }, "description": "Fees on withdrawals, keyed by payout method: `bank_wire`, `same_day_bank`, `next_day_bank`, `rtp`, `crypto`, and `digital_wallet`.", "example": { "bank_wire": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "30.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "ends_at": null, "fixed": { "amount": "30.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": null, "region": null, "regions": {}, "reset": { "fixed": { "amount": "30.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "source": "default", "unadjustable_reason": "not_permitted" }, "crypto": { "adjustable": false, "category": "payouts", "default": { "fixed": null, "percentage": 0.0 }, "ends_at": null, "fixed": null, "maximum": null, "minimum": null, "percentage": 0.0, "region": null, "regions": {}, "reset": { "fixed": null, "percentage": 0.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "digital_wallet": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "ends_at": null, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 0.0, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "next_day_bank": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "ends_at": null, "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": null, "region": null, "regions": {}, "reset": { "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "source": "default", "unadjustable_reason": "not_permitted" }, "rtp": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "ends_at": null, "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": 0.0, "region": null, "regions": {}, "reset": { "fixed": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": 0.0 }, "source": "default", "unadjustable_reason": "not_permitted" }, "same_day_bank": { "adjustable": false, "category": "payouts", "default": { "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "ends_at": null, "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "maximum": null, "minimum": null, "percentage": null, "region": null, "regions": {}, "reset": { "fixed": { "amount": "2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "percentage": null }, "source": "default", "unadjustable_reason": "not_permitted" } }, "type": "object" }, "pending_auto_topup": { "$ref": "#/components/schemas/AccountFee", "description": "Charged when pending, not-yet-settled balance is advanced to fund the user's cards balance." }, "transfers": { "$ref": "#/components/schemas/AccountFee", "description": "Charged on transfers from the user's balance to another Whop balance." }, "user_id": { "description": "The user these fees are charged to, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "user_id", "payouts", "transfers", "pending_auto_topup", "bank_deposit" ], "type": "object" }, "UserNotificationPreference": { "properties": { "created_at": { "description": "When the preference was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "id": { "description": "Notification preference ID, prefixed `unpf_`.", "example": "unpf_xxxxxxxxxxxxxx", "type": "string" }, "level": { "description": "What the user is notified about in this scope: `all` or `nothing`.", "enum": [ "all", "nothing" ], "example": "all", "type": "string" }, "object": { "description": "The type of object. Always `notification_preference`.", "enum": [ "notification_preference" ], "example": "notification_preference", "type": "string" }, "scope": { "$ref": "#/components/schemas/NotificationPreferenceScope", "description": "What the preference applies to. Echo it back to `PATCH /users/me/preferences/notifications` to change this preference." }, "updated_at": { "description": "When the preference was last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "object", "id", "scope", "level", "created_at", "updated_at" ], "type": "object" }, "UserPreferences": { "properties": { "bounty_worker_onboarding_dismissed": { "description": "Whether the user has dismissed the first-time bounty worker onboarding. Set to `false` to show it again.", "example": false, "type": "boolean" }, "cards_auto_top_up": { "description": "Whether incoming funds, including pending balance, are automatically moved to the user's personal cards balance. `false` when the user has no cards balance.", "example": false, "type": "boolean" }, "investigation_enabled": { "description": "Whether investigation mode is enabled for the user. Only meaningful for staff users with investigation access.", "example": true, "type": "boolean" }, "terms_accepted": { "description": "Whether the user has accepted Whop's terms and policies. `false` until recorded via `PATCH` with `terms_accepted: true`.", "example": true, "type": "boolean" }, "terms_accepted_at": { "description": "When the user most recently accepted Whop's terms and policies, as an ISO 8601 timestamp. `null` until accepted.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] } }, "required": [ "investigation_enabled", "bounty_worker_onboarding_dismissed", "terms_accepted", "terms_accepted_at", "cards_auto_top_up" ], "type": "object" }, "UserProfilePicture": { "properties": { "url": { "description": "Avatar image URL. Always present — a generated placeholder when the user set no picture.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "UserRecommendedAction": { "properties": { "account_id": { "description": "The account (`biz_`) a business recommendation is for, or `null` for personal recommendations", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "account_name": { "description": "The account's display name, or `null` for personal recommendations", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "action": { "description": "The recommendation; new values may be added, so handle unknown actions gracefully", "enum": [ "create_business", "become_affiliate", "become_whop_partner", "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" ], "example": "apply_for_financing", "type": "string" }, "blocked_capabilities": { "items": { "description": "Capabilities this would unlock, or empty", "example": "accept_bnpl_payments", "type": "string" }, "type": "array" }, "cta": { "description": "The URL the call-to-action links to", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/settings/payments/", "type": "string" }, "cta_label": { "description": "Button label", "example": "Apply", "type": "string" }, "description": { "description": "Supporting copy, or empty", "example": "Let detailing customers split a $249 ceramic coating over four payments.", "type": "string" }, "icon_url": { "description": "Illustration icon URL, or `null`", "example": "https://whop.com/illustrations/orange/piggy-bank.svg", "type": [ "string", "null" ] }, "impact_score": { "description": "Estimated impact from 0-100, or `null` when not ranked", "example": 82, "type": [ "integer", "null" ] }, "reasoning": { "description": "Why this action was recommended, or `null`", "example": "Ceramic coating is the priciest job on the menu, so financing lifts conversion most.", "type": [ "string", "null" ] }, "status": { "description": "Always optional — never blocking", "enum": [ "optional" ], "example": "optional", "type": "string" }, "title": { "description": "Headline for the recommendation", "example": "Offer financing at checkout", "type": "string" } }, "required": [ "action", "status", "title", "description", "cta_label", "cta", "icon_url", "blocked_capabilities", "reasoning", "impact_score", "account_id", "account_name" ], "type": "object" }, "UserSocialLink": { "properties": { "url": { "description": "The link's URL.", "example": "https://www.instagram.com/tanyacole.details", "type": "string" }, "username": { "description": "The user's handle on the platform, as entered or as reported by the connected account. `null` for links without a handle, such as a personal site.", "example": "tanyacole.details", "type": [ "string", "null" ] }, "verified": { "description": "Whether Whop verified that the user owns the account.", "example": true, "type": "boolean" }, "website": { "description": "The platform the link points to. `website` is a personal site rather than a social platform.", "enum": [ "x", "instagram", "facebook", "tiktok", "youtube", "linkedin", "twitch", "website" ], "example": "instagram", "type": "string" } }, "required": [ "website", "username", "url", "verified" ], "type": "object" }, "UserSummary": { "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "profile_picture": { "$ref": "#/components/schemas/UserProfilePicture", "description": "Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture." }, "username": { "description": "Public username.", "example": "danawhitfield", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": "object" }, "V1ErrorResponse": { "properties": { "error": { "properties": { "code": { "description": "Machine-readable reason for this specific refusal, such as `bank_warning_not_acknowledged`. Only present when the error carries one.", "type": "string" }, "message": { "description": "Human-readable error message.", "example": "account_id is required", "type": "string" }, "type": { "description": "Machine-readable error code.", "example": "bad_request", "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "Variant": { "properties": { "account": { "description": "Account that sells this variant; `null` for standalone invoice variants.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "adaptive_pricing_enabled": { "description": "Whether adaptive pricing is enabled for this variant. Raw setting — does not check processor compatibility or feature flags.", "example": true, "type": "boolean" }, "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "example": false, "type": "boolean" }, "attributes": { "additionalProperties": { "type": "string" }, "description": "Attribute values that distinguish this variant within its product, as a map of attribute name to value, e.g. `{\"color\": \"Blue\", \"size\": \"Large\"}`. Names are snake_case identifiers and come back in alphabetical order. Every attributed variant on a product carries the same attribute names and a distinct set of values; the product lists the full option set as `variant_attributes`. `null` when the variant has no attributes.", "example": { "color": "Blue", "size": "Large" }, "type": [ "object", "null" ] }, "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "number", "null" ] }, "billing_type": { "description": "Billing model for this variant.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "cancel_discount_intervals": { "description": "How long the cancellation discount lasts: `0` forever, `1` the next payment only, or a number of calendar months from when the customer accepts it. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": 3, "type": [ "number", "null" ] }, "cancel_discount_percentage": { "description": "Cancellation discount as a whole-number percentage. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": 20, "type": [ "number", "null" ] }, "checkout_styling": { "description": "Variant-level checkout styling (`background_color`, `button_color`, `font_family`, `border_style`); `null` inherits the account default.", "example": { "background_color": "#0f172a", "border_style": "rounded", "button_color": "#f59e0b", "font_family": "roboto" }, "type": [ "object", "null" ] }, "collect_tax": { "description": "Whether tax is collected on purchases of this variant, based on the account's tax configuration.", "example": false, "type": "boolean" }, "created_at": { "description": "When the variant was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO 4217 code of the currency every price on this variant is stated in, lowercase: the variant's own currency, or the `presentment_currency` the read asked for when the variant can be converted into it.", "example": "usd", "type": "string" }, "custom_fields": { "items": { "$ref": "#/components/schemas/PlanCustomField", "description": "Custom input fields collected on the checkout form." }, "type": "array" }, "deletable": { "description": "Whether the variant can be deleted (it has no memberships or waitlist entries). `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": true, "type": [ "boolean", "null" ] }, "description": { "description": "Customer-visible variant description. Maximum 1000 characters. `null` if no description is set.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout for this variant, resolved through every layer (the variant's own and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays the variant's own editable override.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutSessionPaymentMethodConfiguration" }, { "type": "null" } ] }, "expiration_days": { "description": "Access duration in days for expiration-based variants, such as 365 for a one-year pass. `null` for variants without an expiration.", "example": 365, "type": [ "number", "null" ] }, "formatted_price": { "description": "Human-readable price for display (currency + interval) in `currency`, e.g. \"$10 / month\".", "example": "$59.00 / month", "type": "string" }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "Pricing-tier image (`url`, `blurhash`) shown on the product page; `null` when no image is set.", "example": { "blurhash": "LA6bDXT$E3b:R6i+RibEIWbp%ej1", "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial purchase price, in `currency`.", "example": 0.0, "type": "number" }, "initial_price_due": { "$ref": "#/components/schemas/Money", "description": "Total charged at checkout for one unit, before promo codes and tax: `initial_price` plus the first `renewal_price` for recurring variants, or `initial_price` alone while a free trial applies. The trial does not apply when the viewing user has already used one for this variant. Stated in `currency`." }, "internal_notes": { "description": "Private notes not shown to customers. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "invoice": { "description": "Invoice this variant was generated for; `null` unless created for an invoice.", "example": { "id": "inv_xxxxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "member_count": { "description": "Active memberships through this variant. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": 0, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the variant. Included in webhook payloads for payment and membership events. Maximum 50 keys, 100 characters per key, 500 characters per value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this variant.", "example": { "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether a cancellation discount is offered. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": true, "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "Payment method configuration (`enabled`, `disabled`, `include_platform_defaults`); `null` when variant uses default settings.", "example": { "disabled": [ "crypto" ], "enabled": [ "card" ], "include_platform_defaults": true }, "type": [ "object", "null" ] }, "product": { "description": "Product this variant belongs to; `null` for standalone variants.", "example": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "type": [ "object", "null" ] }, "purchase_url": { "description": "URL where customers can purchase this variant directly.", "example": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this variant.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged every billing period, in `currency`.", "example": 59.0, "type": "number" }, "sku": { "description": "Stock keeping unit, free text set by the seller (e.g. `TSHIRT-LARGE-BLUE`). Not enforced unique. `null` when unset.", "example": "WASH-CLUB-TEE-LARGE-BLUE", "type": [ "string", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses. Must be greater than 1. `null` if split pay is not configured.", "example": 4, "type": [ "number", "null" ] }, "stock": { "description": "Units available for purchase. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": 0, "type": [ "number", "null" ] }, "strike_through_initial_price": { "description": "Original initial price shown with a strikethrough, in `currency`. `null` when no strikethrough is set.", "example": 99.0, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "Original renewal price shown with a strikethrough, in `currency`. `null` when no strikethrough is set.", "example": 79.0, "type": [ "number", "null" ] }, "tax_type": { "description": "How tax is handled for this variant, including whether tax is included in the price, added at checkout, or not configured.", "enum": [ "inclusive", "exclusive", "unspecified" ], "example": "unspecified", "type": "string" }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "title": { "description": "Variant display name shown to customers. Maximum 30 characters. A variant created without one defaults to its attribute values joined with ` / `. `null` if no title has been set.", "example": "Unlimited Wash Club", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge. `null` if no trial is configured or the user has already used a trial for this variant.", "example": 7, "type": [ "number", "null" ] }, "unlimited_stock": { "description": "Whether the variant has unlimited stock. When `true`, the `stock` field is ignored; waitlist variants always report `true`.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the variant was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visibility": { "description": "Controls where this variant can be seen. When `hidden`, the variant is reachable only by its direct link.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "visibility", "billing_type", "release_method", "currency", "account", "product", "invoice", "billing_period", "title", "description", "purchase_url", "expiration_days", "initial_price", "renewal_price", "initial_price_due", "formatted_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "sku", "attributes", "stock", "unlimited_stock", "allow_multiple_quantity", "split_pay_required_payments", "adaptive_pricing_enabled", "strike_through_initial_price", "strike_through_renewal_price", "checkout_styling", "offer_cancel_discount", "cancel_discount_percentage", "cancel_discount_intervals", "payment_method_configuration", "image", "tax_type", "collect_tax", "deletable", "effective_payment_method_configuration", "custom_fields" ], "type": "object" }, "VariantListItem": { "properties": { "account": { "description": "Account that sells this variant; `null` for standalone invoice variants.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "adaptive_pricing_enabled": { "description": "Whether adaptive pricing is enabled for this variant. Raw setting — does not check processor compatibility or feature flags.", "example": true, "type": "boolean" }, "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "example": false, "type": "boolean" }, "attributes": { "additionalProperties": { "type": "string" }, "description": "Attribute values that distinguish this variant within its product, as a map of attribute name to value, e.g. `{\"color\": \"Blue\", \"size\": \"Large\"}`. Names are snake_case identifiers and come back in alphabetical order. Every attributed variant on a product carries the same attribute names and a distinct set of values; the product lists the full option set as `variant_attributes`. `null` when the variant has no attributes.", "example": { "color": "Blue", "size": "S" }, "type": [ "object", "null" ] }, "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "number", "null" ] }, "billing_type": { "description": "Billing model for this variant.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "cancel_discount_intervals": { "description": "How long the cancellation discount lasts: `0` forever, `1` the next payment only, or a number of calendar months from when the customer accepts it. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": 3, "type": [ "number", "null" ] }, "cancel_discount_percentage": { "description": "Cancellation discount as a whole-number percentage. `null` when none is offered or the actor lacks the `plan:basic:read` scope.", "example": 20, "type": [ "number", "null" ] }, "checkout_styling": { "description": "Variant-level checkout styling (`background_color`, `button_color`, `font_family`, `border_style`); `null` inherits the account default.", "example": { "background_color": "#0f172a", "border_style": "rounded", "button_color": "#f59e0b", "font_family": "roboto" }, "type": [ "object", "null" ] }, "created_at": { "description": "When the variant was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO 4217 code of the currency every price on this variant is stated in, lowercase: the variant's own currency, or the `presentment_currency` the read asked for when the variant can be converted into it.", "example": "usd", "type": "string" }, "custom_fields": { "items": { "$ref": "#/components/schemas/PlanCustomField", "description": "Custom input fields collected on the checkout form." }, "type": "array" }, "description": { "description": "Customer-visible variant description. Maximum 1000 characters. `null` if no description is set.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days for expiration-based variants, such as 365 for a one-year pass. `null` for variants without an expiration.", "example": 365, "type": [ "number", "null" ] }, "formatted_price": { "description": "Human-readable price for display (currency + interval) in `currency`, e.g. \"$10 / month\".", "example": "$59.00 / month", "type": "string" }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "image": { "description": "Pricing-tier image (`url`, `blurhash`) shown on the product page; `null` when no image is set.", "example": { "blurhash": "LA6bDXT$E3b:R6i+RibEIWbp%ej1", "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial purchase price, in `currency`.", "example": 0.0, "type": "number" }, "initial_price_due": { "$ref": "#/components/schemas/Money", "description": "Total charged at checkout for one unit, before promo codes and tax: `initial_price` plus the first `renewal_price` for recurring variants, or `initial_price` alone while a free trial applies. The trial does not apply when the viewing user has already used one for this variant. Stated in `currency`." }, "internal_notes": { "description": "Private notes not shown to customers. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "invoice": { "description": "Invoice this variant was generated for; `null` unless created for an invoice.", "example": { "id": "inv_xxxxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "member_count": { "description": "Active memberships through this variant. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": 0, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the variant. Included in webhook payloads for payment and membership events. Maximum 50 keys, 100 characters per key, 500 characters per value. The reserved keys `custom_cta` and `custom_cta_url`, when set, override the product's checkout call to action for this variant.", "example": { "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether a cancellation discount is offered. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": true, "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "Payment method configuration (`enabled`, `disabled`, `include_platform_defaults`); `null` when variant uses default settings.", "example": { "disabled": [ "crypto" ], "enabled": [ "card" ], "include_platform_defaults": true }, "type": [ "object", "null" ] }, "product": { "description": "Product this variant belongs to; `null` for standalone variants.", "example": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "type": [ "object", "null" ] }, "purchase_url": { "description": "URL where customers can purchase this variant directly.", "example": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this variant.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged every billing period, in `currency`.", "example": 59.0, "type": "number" }, "sku": { "description": "Stock keeping unit, free text set by the seller (e.g. `TSHIRT-LARGE-BLUE`). Not enforced unique. `null` when unset.", "example": "CERAMIC-COATING-S-BLUE", "type": [ "string", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses. Must be greater than 1. `null` if split pay is not configured.", "example": 4, "type": [ "number", "null" ] }, "stock": { "description": "Units available for purchase. `null` unless the actor has the `plan:basic:read` scope on the variant's account.", "example": 0, "type": [ "number", "null" ] }, "strike_through_initial_price": { "description": "Original initial price shown with a strikethrough, in `currency`. `null` when no strikethrough is set.", "example": 99.0, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "Original renewal price shown with a strikethrough, in `currency`. `null` when no strikethrough is set.", "example": 79.0, "type": [ "number", "null" ] }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "title": { "description": "Variant display name shown to customers. Maximum 30 characters. A variant created without one defaults to its attribute values joined with ` / `. `null` if no title has been set.", "example": "Unlimited Wash Club", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge. `null` if no trial is configured or the user has already used a trial for this variant.", "example": 7, "type": [ "number", "null" ] }, "unlimited_stock": { "description": "Whether the variant has unlimited stock. When `true`, the `stock` field is ignored; waitlist variants always report `true`.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the variant was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visibility": { "description": "Controls where this variant can be seen. When `hidden`, the variant is reachable only by its direct link.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "visibility", "billing_type", "release_method", "currency", "account", "product", "invoice", "billing_period", "title", "description", "purchase_url", "expiration_days", "initial_price", "renewal_price", "initial_price_due", "formatted_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "sku", "attributes", "stock", "unlimited_stock", "allow_multiple_quantity", "split_pay_required_payments", "adaptive_pricing_enabled", "strike_through_initial_price", "strike_through_renewal_price", "checkout_styling", "offer_cancel_discount", "cancel_discount_percentage", "cancel_discount_intervals", "payment_method_configuration", "image", "custom_fields" ], "type": "object" }, "Verification": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "last_error_code", "last_error_reason" ], "type": "object" }, "VerificationErrorCodes": { "description": "An error code for a verification attempt.", "enum": [ "abandoned", "consent_declined", "country_not_supported", "device_not_supported", "document_expired", "document_type_not_supported", "document_unverified_other", "email_unverified_other", "email_verification_declined", "id_number_insufficient_document_data", "id_number_mismatch", "id_number_unverified_other", "phone_unverified_other", "phone_verification_declined", "selfie_document_missing_photo", "selfie_face_mismatch", "selfie_manipulated", "selfie_unverified_other", "under_supported_age" ], "type": "string" }, "VerificationListItem": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "last_error_code", "last_error_reason" ], "type": "object" }, "VerificationStatuses": { "description": "A status for a verification.", "enum": [ "requires_input", "processing", "verified", "canceled", "created", "started", "submitted", "approved", "declined", "resubmission_requested", "expired", "abandoned", "review", "action_required", "manual_review" ], "type": "string" }, "Visibility": { "description": "Visibility of a resource", "enum": [ "visible", "hidden", "archived", "quick_link" ], "type": "string" }, "VisibilityFilter": { "description": "The different levels of visibility for resources", "enum": [ "visible", "hidden", "archived", "quick_link", "all", "not_quick_link", "not_archived" ], "type": "string" }, "WaitlistEntry": { "properties": { "account_id": { "description": "The seller account, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "approval_failure_reason": { "description": "Why the last approval attempt failed, or `null` when none has. `plan_unavailable` — the variant, product, or seller account was deleted. `already_member` — the user already has a membership on a one-per-user product. `checkout_failed` — checkout failed, usually a declined payment, and the signup was denied. `unknown` — another failure; retry. Cleared when approval is requeued.", "enum": [ "plan_unavailable", "already_member", "checkout_failed", "unknown", null ], "example": "plan_unavailable", "type": [ "string", "null" ] }, "buyer_account": { "description": "The account the signup was submitted on behalf of, or `null` when the user signed up for themselves.", "oneOf": [ { "$ref": "#/components/schemas/StorefrontAccount" }, { "type": "null" } ] }, "buyer_account_id": { "description": "The account the signup was submitted on behalf of, prefixed `biz_`, or `null` when the user signed up for themselves.", "example": null, "type": [ "string", "null" ] }, "created_at": { "description": "When this signup was submitted, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "custom_field_responses": { "items": { "$ref": "#/components/schemas/WaitlistEntryCustomFieldResponse", "description": "The buyer's answers to checkout questions." }, "type": "array" }, "id": { "description": "The waitlist signup ID, prefixed `entry_`.", "example": "entry_xxxxxxxxxxxxxx", "type": "string" }, "membership_id": { "description": "The membership created for this signup, prefixed `mem_`, or `null` when there is none. Check the membership's status to determine access.", "example": null, "type": [ "string", "null" ] }, "metadata": { "description": "Custom key-value metadata associated with this signup.", "example": {}, "type": "object" }, "product": { "description": "The product this signup belongs to, or `null` when the variant has no product.", "oneOf": [ { "$ref": "#/components/schemas/WaitlistEntryProduct" }, { "type": "null" } ] }, "product_id": { "description": "The product this signup belongs to, prefixed `prod_`, or `null` when the variant has no product.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "status": { "description": "The signup's current state. Approval runs asynchronously, so a signup stays `pending` until processing completes. `approved` alone does not prove an active membership; check `membership_id`.", "enum": [ "pending", "approved", "denied", "canceled" ], "example": "canceled", "type": "string" }, "updated_at": { "description": "When this signup last changed, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "user": { "$ref": "#/components/schemas/UserSummary", "description": "The user who submitted this signup. For a signup an account's own credential submitted, the account's owner." }, "user_id": { "description": "The user who submitted this signup, prefixed `user_`. For a signup an account's own credential submitted, the account's owner.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "variant": { "$ref": "#/components/schemas/WaitlistEntryVariant", "description": "The variant this signup belongs to." }, "variant_id": { "description": "The variant this signup belongs to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "status", "approval_failure_reason", "variant_id", "account_id", "product_id", "user_id", "buyer_account_id", "membership_id", "custom_field_responses", "metadata", "created_at", "updated_at", "user", "buyer_account", "product", "variant" ], "type": "object" }, "WaitlistEntryCustomFieldResponse": { "properties": { "answer": { "description": "The buyer's answer.", "type": "string" }, "id": { "description": "The answer's ID, prefixed `cfrp_`.", "type": "string" }, "question": { "description": "The question shown when the signup was submitted.", "type": "string" } }, "required": [ "id", "question", "answer" ], "type": "object" }, "WaitlistEntryProduct": { "properties": { "id": { "description": "Product ID, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Product display name.", "example": "Persevering actuating local...", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "WaitlistEntryVariant": { "properties": { "billing_period": { "description": "Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "number", "null" ] }, "billing_type": { "description": "Billing model for this variant: `one_time` or `renewal`.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "description": { "description": "Customer-visible variant description. Maximum 1000 characters. `null` if no description is set.", "example": null, "type": [ "string", "null" ] }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "$ref": "#/components/schemas/Money", "description": "What checkout charges up front. `amount` is `\"0.00\"` when the first charge is free, such as a trial." }, "renewal_price": { "$ref": "#/components/schemas/Money", "description": "The recurring charge every `billing_period` days. `amount` is `\"0.00\"` for one-time variants." }, "title": { "description": "Variant display name shown to customers. `null` if no title has been set.", "example": null, "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days configured before the first renewal charge. `null` if no trial is configured.", "example": null, "type": [ "number", "null" ] } }, "required": [ "id", "title", "description", "billing_type", "billing_period", "initial_price", "renewal_price", "trial_period_days" ], "type": "object" }, "Webhook": { "properties": { "api_version": { "description": "The API version used to format payloads sent to this webhook endpoint.", "enum": [ "v1", "v2", "v5" ], "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) that v1 payloads for this endpoint are pinned to: events serialize exactly like a REST read at this version (the native serializer where the resource has one). Null when unpinned — legacy (v2/v5) webhooks, and v1 webhooks on the legacy payload shape.", "example": "2026-10-27-3", "type": [ "string", "null" ] }, "child_resource_events": { "description": "Whether events are sent for child resources. For example, if the webhook is on an account, enabling this sends events only from its connected accounts.", "example": false, "type": "boolean" }, "consecutive_failures": { "description": "Number of consecutive deliveries whose first attempt to this endpoint failed since it last accepted one. Later retries of the same delivery do not increment it. Resets to `0` when a delivery succeeds or the webhook is re-enabled.", "example": 9, "type": "integer" }, "created_at": { "description": "When the webhook was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "disabled_at": { "description": "When Whop automatically disabled this webhook, as an ISO 8601 timestamp. `null` unless the webhook was disabled by Whop; a webhook you disabled yourself has `enabled: false` and a `null` `disabled_at`.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "disabled_reason": { "description": "Why Whop disabled this webhook. `delivery_failures` means every delivery failed for 3 days straight. `null` when `disabled_at` is `null`.", "enum": [ "delivery_failures", null ], "example": "delivery_failures", "type": [ "string", "null" ] }, "enabled": { "description": "Whether this webhook endpoint is currently active and receiving events.", "example": false, "type": "boolean" }, "events": { "items": { "description": "Event types this webhook is subscribed to, in dot form (for example `payment.succeeded`).", "enum": [ "account.updated", "account.financing_approved", "account.financing_denied", "account.financing_disabled", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "membership.updated", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "financial_activity.funds_available", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "course_lesson_interaction.completed", "domain.created", "domain.updated", "domain.deleted", "payout_method.created", "verification.succeeded", "identity_profile.approved", "identity_profile.rejected", "identity_profile.needs_action", "identity_profile.updated", "payout_account.status_updated", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "member.updated", "ad_campaign.created", "ad_campaign.payment_failed", "ad_campaign.updated", "ad_campaign.events", "ad_group.created", "ad_group.updated", "ad.created", "ad.updated", "app_installation.created", "app_installation.deleted", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "payment.requires_action", "dispute.created", "dispute.updated", "refund.created", "refund.updated", "dispute_alert.created", "membership.cancel_at_period_end_changed", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_payment.requires_action", "app_membership.cancel_at_period_end_changed" ], "example": "payment.succeeded", "type": "string" }, "type": "array" }, "failing_since": { "description": "When the current failure streak began, as an ISO 8601 timestamp. Unlike `last_failure_at`, this is set on the streak's first failed attempt, so it shows an endpoint that is failing right now. `null` when the endpoint is healthy.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Webhook ID, prefixed `hook_`.", "example": "hook_xxxxxxxxxxxxxx", "type": "string" }, "last_failure_at": { "description": "When a delivery to this endpoint most recently failed after exhausting retries, as an ISO 8601 timestamp. `null` if no delivery has ever failed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "resource_id": { "description": "ID of the resource (account or app) this webhook is attached to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "testable_events": { "items": { "description": "The subset of subscribed event types that support sending test payloads, in dot form.", "enum": [ "account.updated", "account.financing_approved", "account.financing_denied", "account.financing_disabled", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "membership.updated", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "financial_activity.funds_available", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "course_lesson_interaction.completed", "domain.created", "domain.updated", "domain.deleted", "payout_method.created", "verification.succeeded", "identity_profile.approved", "identity_profile.rejected", "identity_profile.needs_action", "identity_profile.updated", "payout_account.status_updated", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "member.updated", "ad_campaign.created", "ad_campaign.payment_failed", "ad_campaign.updated", "ad_campaign.events", "ad_group.created", "ad_group.updated", "ad.created", "ad.updated", "app_installation.created", "app_installation.deleted", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "payment.requires_action", "dispute.created", "dispute.updated", "refund.created", "refund.updated", "dispute_alert.created", "membership.cancel_at_period_end_changed", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_payment.requires_action", "app_membership.cancel_at_period_end_changed" ], "example": "account.updated", "type": "string" }, "type": "array" }, "title": { "description": "A label for this webhook endpoint, such as `Production`, shown in the dashboard. `null` if no title was set.", "example": "Production", "type": [ "string", "null" ] }, "url": { "description": "Destination URL where webhook payloads are delivered via HTTP POST.", "example": "https://example.com/hooks", "type": "string" }, "webhook_secret": { "description": "Secret key used to sign webhook payloads for verification. Include this in your HMAC validation logic. Returned on the create response and to interactive dashboard sessions; `null` for API-key and OAuth callers on later reads.", "example": "ws_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "title", "url", "enabled", "events", "api_version", "api_version_date", "created_at", "child_resource_events", "webhook_secret", "resource_id", "consecutive_failures", "failing_since", "last_failure_at", "disabled_at", "disabled_reason", "testable_events" ], "type": "object" }, "WebhookDelivery": { "properties": { "event": { "description": "The event type this delivery carried, for example `payment.succeeded`.", "example": "payment.succeeded", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for this delivery attempt. Pass it to the replay endpoint to re-send this exact payload.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "replayed_from": { "description": "The id of the delivery attempt this one replayed. `null` for an original delivery.", "example": "whdel_MTcwMDAwMDAwMDAwMHx0ZXN0", "type": [ "string", "null" ] }, "request_body": { "description": "The JSON event payload sent to the webhook endpoint.", "example": { "data": { "id": "pay_123" }, "id": "msg_original", "type": "payment.succeeded" }, "type": "object" }, "resource_id": { "description": "ID of the resource that triggered the webhook.", "example": "pay_123", "type": "string" }, "response_body": { "description": "The endpoint's JSON response. A non-JSON response is stored as `{ error, raw_body }` with the first 100 bytes.", "example": { "ok": true }, "type": [ "object", "null" ] }, "response_code": { "description": "HTTP response code received from the webhook endpoint.", "example": 200, "type": "number" }, "sent_at": { "description": "When the webhook was sent, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "Outcome of this delivery attempt: `success` when the endpoint returned a 2xx response, `error` otherwise.", "enum": [ "success", "error" ], "example": "success", "type": "string" }, "success": { "description": "Whether the endpoint acknowledged this attempt with a 2xx response.", "example": true, "type": "boolean" }, "total_time": { "description": "Total time taken to send the webhook request, in seconds.", "example": 0.31, "type": "number" } }, "required": [ "id", "event", "replayed_from", "request_body", "resource_id", "response_body", "response_code", "sent_at", "status", "success", "total_time" ], "type": "object" }, "WebhookEvent": { "description": "The different event types available", "enum": [ "account.updated", "account.financing_approved", "account.financing_denied", "account.financing_disabled", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "membership.updated", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "financial_activity.funds_available", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "course_lesson_interaction.completed", "domain.created", "domain.updated", "domain.deleted", "payout_method.created", "verification.succeeded", "identity_profile.approved", "identity_profile.rejected", "identity_profile.needs_action", "identity_profile.updated", "payout_account.status_updated", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "member.updated", "ad_campaign.created", "ad_campaign.payment_failed", "ad_campaign.updated", "ad_campaign.events", "ad_group.created", "ad_group.updated", "ad.created", "ad.updated", "app_installation.created", "app_installation.deleted", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "payment.requires_action", "dispute.created", "dispute.updated", "refund.created", "refund.updated", "dispute_alert.created", "membership.cancel_at_period_end_changed" ], "type": "string" }, "WebhookListItem": { "properties": { "api_version": { "description": "The API version used to format payloads sent to this webhook endpoint.", "enum": [ "v1", "v2", "v5" ], "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) that v1 payloads for this endpoint are pinned to: events serialize exactly like a REST read at this version (the native serializer where the resource has one). Null when unpinned — legacy (v2/v5) webhooks, and v1 webhooks on the legacy payload shape.", "example": "2026-10-27-3", "type": [ "string", "null" ] }, "child_resource_events": { "description": "Whether events are sent for child resources. For example, if the webhook is on an account, enabling this sends events only from its connected accounts.", "example": false, "type": "boolean" }, "consecutive_failures": { "description": "Number of consecutive deliveries whose first attempt to this endpoint failed since it last accepted one. Later retries of the same delivery do not increment it. Resets to `0` when a delivery succeeds or the webhook is re-enabled.", "example": 0, "type": "integer" }, "created_at": { "description": "When the webhook was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "disabled_at": { "description": "When Whop automatically disabled this webhook, as an ISO 8601 timestamp. `null` unless the webhook was disabled by Whop; a webhook you disabled yourself has `enabled: false` and a `null` `disabled_at`.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "disabled_reason": { "description": "Why Whop disabled this webhook. `delivery_failures` means every delivery failed for 3 days straight. `null` when `disabled_at` is `null`.", "enum": [ "delivery_failures", null ], "example": "delivery_failures", "type": [ "string", "null" ] }, "enabled": { "description": "Whether this webhook endpoint is currently active and receiving events.", "example": false, "type": "boolean" }, "events": { "items": { "description": "Event types this webhook is subscribed to, in dot form (for example `payment.succeeded`).", "enum": [ "account.updated", "account.financing_approved", "account.financing_denied", "account.financing_disabled", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "membership.updated", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "financial_activity.funds_available", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "course_lesson_interaction.completed", "domain.created", "domain.updated", "domain.deleted", "payout_method.created", "verification.succeeded", "identity_profile.approved", "identity_profile.rejected", "identity_profile.needs_action", "identity_profile.updated", "payout_account.status_updated", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "member.updated", "ad_campaign.created", "ad_campaign.payment_failed", "ad_campaign.updated", "ad_campaign.events", "ad_group.created", "ad_group.updated", "ad.created", "ad.updated", "app_installation.created", "app_installation.deleted", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "payment.requires_action", "dispute.created", "dispute.updated", "refund.created", "refund.updated", "dispute_alert.created", "membership.cancel_at_period_end_changed", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_payment.requires_action", "app_membership.cancel_at_period_end_changed" ], "example": "payment.succeeded", "type": "string" }, "type": "array" }, "failing_since": { "description": "When the current failure streak began, as an ISO 8601 timestamp. Unlike `last_failure_at`, this is set on the streak's first failed attempt, so it shows an endpoint that is failing right now. `null` when the endpoint is healthy.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "id": { "description": "Webhook ID, prefixed `hook_`.", "example": "hook_xxxxxxxxxxxxxx", "type": "string" }, "last_failure_at": { "description": "When a delivery to this endpoint most recently failed after exhausting retries, as an ISO 8601 timestamp. `null` if no delivery has ever failed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "resource_id": { "description": "ID of the resource (account or app) this webhook is attached to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "A label for this webhook endpoint, such as `Production`, shown in the dashboard. `null` if no title was set.", "example": null, "type": [ "string", "null" ] }, "url": { "description": "Destination URL where webhook payloads are delivered via HTTP POST.", "example": "https://example.com/shine-time/whop", "type": "string" }, "webhook_secret": { "description": "Secret key used to sign webhook payloads for verification. Include this in your HMAC validation logic. Returned on the create response and to interactive dashboard sessions; `null` for API-key and OAuth callers on later reads.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "id", "title", "url", "enabled", "events", "api_version", "api_version_date", "created_at", "child_resource_events", "webhook_secret", "resource_id", "consecutive_failures", "failing_since", "last_failure_at", "disabled_at", "disabled_reason" ], "type": "object" }, "WhoCanPostTypes": { "description": "Who can post on a chat feed", "enum": [ "everyone", "admins" ], "type": "string" }, "WhoCanReactTypes": { "description": "Who can react on a chat feed", "enum": [ "everyone", "no_one" ], "type": "string" }, "WorkforceBounty": { "description": "A privately accessible bounty.", "properties": { "bounty_type": { "$ref": "#/components/schemas/BountyTypes", "description": "The underlying bounty implementation type." }, "created_at": { "description": "The datetime the bounty was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for the bounty funds." }, "description": { "description": "The description of the bounty.", "type": "string" }, "id": { "description": "The unique identifier for the bounty.", "example": "bnty_xxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/Statuses", "description": "The current lifecycle status of the bounty." }, "title": { "description": "The title of the bounty.", "type": "string" }, "total_available": { "description": "The total amount currently funded in the bounty pool for payout.", "example": 6.9, "type": "number" }, "total_paid": { "description": "The total amount paid out for this bounty.", "example": 6.9, "type": "number" }, "updated_at": { "description": "The datetime the bounty was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "vote_threshold": { "description": "The number of watcher votes required before the submission can resolve.", "example": 42, "type": "integer" } }, "required": [ "id", "title", "description", "status", "total_available", "total_paid", "currency", "bounty_type", "vote_threshold", "created_at", "updated_at" ], "type": "object" }, "WorkforceBountyListItem": { "description": "A privately accessible bounty.", "properties": { "bounty_type": { "$ref": "#/components/schemas/BountyTypes", "description": "The underlying bounty implementation type." }, "created_at": { "description": "The datetime the bounty was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "currency": { "$ref": "#/components/schemas/Currencies", "description": "The currency used for the bounty funds." }, "description": { "description": "The description of the bounty.", "type": "string" }, "id": { "description": "The unique identifier for the bounty.", "example": "bnty_xxxxxxxxxxxxx", "type": "string" }, "status": { "$ref": "#/components/schemas/Statuses", "description": "The current lifecycle status of the bounty." }, "title": { "description": "The title of the bounty.", "type": "string" }, "total_available": { "description": "The total amount currently funded in the bounty pool for payout.", "example": 6.9, "type": "number" }, "total_paid": { "description": "The total amount paid out for this bounty.", "example": 6.9, "type": "number" }, "updated_at": { "description": "The datetime the bounty was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "vote_threshold": { "description": "The number of watcher votes required before the submission can resolve.", "example": 42, "type": "integer" } }, "required": [ "id", "title", "description", "status", "total_available", "total_paid", "currency", "bounty_type", "vote_threshold", "created_at", "updated_at" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "auth-scheme", "description": "An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with `Bearer`, for example `Bearer ***************************`.", "scheme": "bearer", "type": "http" }, "scopedSessionCookie": { "description": "The scoped session credential a session-intent verify installs on first-party (whop.com) pages — HttpOnly, so a page never handles it; the browser simply carries it. It names the intent it was minted by, which is what authorizes that intent's own upgrade when no Bearer is presented.", "in": "cookie", "name": "whop-core.scoped-access-token", "type": "apiKey" } } }, "info": { "description": "The Whop REST API. Please see https://docs.whop.com/developer/api/getting-started for more details.", "termsOfService": "https://whop.com/tos-developer-api/", "title": "Whop API", "version": "1.0.0", "x-api-version-date": "2026-10-27-3" }, "openapi": "3.1.0", "paths": { "/access_tokens": { "post": { "description": "Creates a short-lived access token for Whop's web and mobile embedded components. With API key authentication, pass `account_id` or `user_id`; with OAuth, the token is issued for the OAuth user.", "operationId": "createAccessToken", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAccessToken", "properties": { "account_id": { "description": "The unique identifier of the company to generate the token for, starting with 'biz_'. The API key must have permission to access this company.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "expires_at": { "description": "The expiration timestamp for the access token. Defaults to 1 hour from now, with a maximum of 3 hours.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "scoped_actions": { "description": "An array of permission scopes to grant to the access token. If empty or omitted, all permissions from the authenticating credential are inherited. Must be a subset of the credential's permissions.", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "user_id": { "description": "The unique identifier of the user to generate the token for, starting with 'user_'. The API key must have permission to access this user.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessToken" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create access token", "tags": [ "Access tokens" ], "x-group-title": "Developer" } }, "/account_links": { "post": { "description": "Generates a URL that sends a sub-merchant to a hosted Whop page, such as the payouts dashboard or the KYC onboarding flow. Requires an API key.", "operationId": "createAccountLink", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAccountLink", "properties": { "account_id": { "description": "The unique identifier of the company to generate the link for, starting with 'biz_'. Must be a sub-merchant of the API key's company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "refresh_url": { "description": "The URL to redirect the user to if the session expires and needs to be re-authenticated, such as 'https://example.com/refresh'.", "type": "string" }, "return_url": { "description": "The URL to redirect the user to when they want to return to your site, such as 'https://example.com/return'.", "type": "string" }, "use_case": { "$ref": "#/components/schemas/AccountLinkUseCases", "description": "The purpose of the account link, such as hosted payouts portal or hosted KYC onboarding." } }, "required": [ "account_id", "refresh_url", "return_url", "use_case" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLink" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create account link", "tags": [ "Account links" ], "x-group-title": "Developer" } }, "/accounts": { "get": { "description": "Lists accounts visible to the credential. User tokens return the user's business accounts; Account API keys return the requesting account and its connected accounts.", "operationId": "listAccounts", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 10, "maximum": 50, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 50, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort accounts by. `volume` requires `stats:read` on the parent account.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "volume" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Return only accounts with this status: `active` (includes accounts that have not entered payments review) or `suspended`.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "suspended" ], "type": "string" } }, { "description": "Free-text filter on account title or ID. `%` and `_` match literally.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Return only accounts created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Return only accounts created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Return only accounts whose lifetime USD volume is at least this value. Requires `stats:read` on the parent account.", "in": "query", "name": "volume_min", "required": false, "schema": { "type": "number" } }, { "description": "Return only accounts whose lifetime USD volume is at most this value. Requires `stats:read` on the parent account.", "in": "query", "name": "volume_max", "required": false, "schema": { "type": "number" } }, { "description": "For platforms: the parent account ID whose direct connected accounts to return. Requires `payout:account:read` on the parent account.", "in": "query", "name": "parent_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Return only accounts owned by this user (`user_...`), the account's `owner`. Cannot be combined with `parent_account_id`.", "in": "query", "name": "owner_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Account" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "accounts listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [ "company:balance:read" ] } ], "summary": "List Accounts", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an account. User tokens create business accounts; Account API keys create connected accounts. Tax fields (`tax_remitted_by`, `tax_type`, `product_tax_code_id`, `business_address`, `tax_identifiers`) are configured with Update Account, not at creation.", "operationId": "createAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "affiliate_code": { "description": "A saved partner referral link code for this new business account. An existing primary user referral takes priority. Used with user tokens creating top-level accounts.", "example": "account-partner-link", "type": [ "string", "null" ] }, "blueprint_id": { "description": "The blueprint App ID, prefixed `app_`. Creates a hosted website for the account and queues its deployment asynchronously; the Account response does not report deployment completion.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "country": { "description": "The ISO 3166-1 alpha-2 country code where the account's business is located (e.g. `US`). Defaults to the parent account's country for connected accounts.", "example": "US", "type": "string" }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files dispute evidence for this account. Enabling it opts into the success fee charged on disputes it wins. Requires payment:dispute. Omit to preserve the existing setting or creation default.", "type": "boolean" }, "email": { "description": "The email address of the account owner. Required when creating a connected account.", "example": "marcus@shinetime.example", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key/value metadata to store on the account.", "example": { "external_id": "user_12345" }, "type": "object" }, "orchestration_enabled": { "description": "Whether payment orchestration is enabled for this account. Requires payout:account:update. Omit to preserve the existing setting or creation default.", "type": "boolean" }, "send_customer_emails": { "default": false, "description": "Whether Whop sends transactional emails to customers on behalf of the connected account.", "example": true, "type": "boolean" }, "title": { "description": "The display name of the account. Defaults to `metadata.external_id` or the owner's email when omitted.", "example": "Referred Studio", "type": "string" }, "website": { "description": "The account's business website, as an `http` or `https` URL of at most 255 characters. Also added to the account's `social_links` as a `website` entry.", "example": "https://shinetimedetail.com", "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "account created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required connected-account creation scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:create" ] }, { "bearerAuth": [ "company:create_child" ] } ], "summary": "Create Account", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "x-whop-surface": "native" }, "/accounts/me": { "get": { "description": "Retrieves the account associated with the current Account API key.", "operationId": "retrieveRequestingAccount", "parameters": [ { "description": "Also return the trading account under `trading`: its address and its Hyperliquid WebSocket subscriptions. Requires crypto_wallet:trade:read, crypto_wallet:trade, or crypto_wallet:manage permission and an Ethereum wallet; null otherwise.", "in": "query", "name": "include_trading", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "requesting account retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Retrieve Requesting Account", "tags": [ "Accounts" ], "x-whop-docs": "hidden" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/accounts/search": { "get": { "deprecated": true, "description": "Finds accounts by name among the accounts the credential can list. Support searches cover every company and return only the 50 best matches.", "operationId": "searchAccounts", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 10, "maximum": 50, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 50, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The account name to search for.", "in": "query", "name": "query", "required": true, "schema": { "type": "string" } }, { "description": "Sort field. Without it, support searches return the best match first and other searches return the newest account first.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AccountSearchResult" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "accounts found" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing query" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Search Accounts", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ], "x-whop-deprecated-since": "2026-10-15", "x-whop-docs": "hidden" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/accounts/{account_id}/customer_tracking": { "get": { "description": "Retrieves the branding and support contacts the account's hosted customer tracking page and tracking Element display. Public by design, so no authentication is required. Returns 404 unless the account has turned customer tracking on in its preferences. Responses are never cached.", "operationId": "retrieveAccountCustomerTracking", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCustomerTracking" } } }, "description": "customer tracking retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "customer tracking unavailable" } }, "security": [], "summary": "Retrieve Account Customer Tracking", "tags": [ "Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/accounts/{account_id}/fees": { "get": { "description": "Retrieves the account's fees as a single document keyed by fee, with any markups its platform adds. Connected accounts see the rates in effect for them. `adjustable` on each fee says what you may change with Update Account Fees.", "operationId": "retrieveAccountFees", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountFees" } } }, "description": "fees retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "company:update_child_fees" ] } ], "summary": "Retrieve Account Fees", "tags": [ "Accounts" ], "x-whop-docs-subgroup": "Fees" }, "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates the account's fees. Each key present in the body is replaced; omitted keys are left untouched. Only fees that Retrieve Account Fees reports as `adjustable` can be changed.", "operationId": "updateAccountFees", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ach_dispute": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "ach_return": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "bank_deposit": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "billing": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "buyer": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "card_processing": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "child_markups": { "description": "Default markups for connected accounts. Available on accounts without a parent, even before any accounts connect.", "properties": { "card_spend": { "description": "The markup on card purchases settled by the connected account. `null` clears the custom markup.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "crypto_swaps": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "deposits": { "additionalProperties": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "description": "Markups on deposits, keyed by rail: `bank` or `crypto`.", "example": { "bank": { "percentage": 1 } }, "type": "object" }, "payments": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "payouts": { "additionalProperties": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "description": "Markups on withdrawals, keyed by payout method.", "example": { "bank_wire": { "fixed": 7 } }, "type": "object" }, "transfers": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] } }, "type": "object" }, "covered_payout_fees": { "description": "Changes to the payout fees this account covers for connected accounts. Send either all or individual category keys. Omitted categories stay unchanged; category changes have no effect while all is true.", "properties": { "all": { "example": true, "type": "boolean" }, "bank_wire": { "example": true, "type": "boolean" }, "crypto": { "example": true, "type": "boolean" }, "digital_wallet": { "type": "boolean" }, "next_day_bank": { "type": "boolean" }, "rtp": { "type": "boolean" } }, "type": "object" }, "cross_border": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "dispute": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "dispute_alert": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "dispute_alert_cdrn": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "dispute_alert_ethoca": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "dispute_alert_rdr": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "dispute_representment": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "foreign_exchange": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "fraud_screening": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "high_risk": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "marketplace": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "markups": { "description": "Markups on this connected account, set by the platform it is connected to.", "properties": { "card_spend": { "description": "The markup on card purchases settled by the connected account. `null` clears the custom markup.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "crypto_swaps": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "deposits": { "additionalProperties": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "description": "Markups on deposits, keyed by rail: `bank` or `crypto`.", "example": { "bank": { "percentage": 1 } }, "type": "object" }, "payments": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "payouts": { "additionalProperties": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] }, "description": "Markups on withdrawals, keyed by payout method.", "example": { "bank_wire": { "fixed": 7 } }, "type": "object" }, "transfers": { "description": "The new markup. Fields left out keep their current value; `null` clears the row so the markup returns to its default.", "properties": { "fixed": { "description": "The amount the platform adds per event, in US dollars.", "example": 0.25, "type": "number" }, "percentage": { "description": "The percentage of the transaction the platform adds, where `2` means 2%.", "example": 1, "type": "number" } }, "type": [ "object", "null" ] } }, "type": "object" }, "notes": { "description": "Why the fees are changing, recorded with the change. Required when a Whop Verified Partner edits the fee schedule; ignored for markups.", "example": "Lower fees", "type": "string" }, "orchestration": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "payment_methods": { "additionalProperties": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "description": "Changes to non-card payment method fees, keyed by payment method type.", "type": "object" }, "payouts": { "additionalProperties": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "description": "Changes to withdrawal fees, keyed by payout method.", "type": "object" }, "pending_auto_topup": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "platform_processing": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "pool_payout": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "revshare": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "sepa_dispute": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "sepa_return": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "tax_calculation": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "tax_service": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "three_ds": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" }, "transfers": { "description": "The fields of a fee the caller may change. Only the keys sent are replaced.", "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] }, "regions": { "additionalProperties": { "properties": { "fixed": { "description": "The new amount per event in US dollars. `null` clears the custom amount.", "example": 25, "type": [ "number", "null" ] }, "percentage": { "description": "The new percentage, where `2` means 2%. `null` clears the custom rate so the fee returns to its default or inherited rate.", "example": 0.5, "type": [ "number", "null" ] } }, "type": "object" }, "description": "Changes for the other regions the fee varies by, keyed by region. Only accepted on a fee whose `regions` is non-empty.", "type": "object" } }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountFees" } } }, "description": "fees updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid fee change" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "forbidden" } }, "security": [ { "bearerAuth": [ "company:update_child_fees" ] }, { "bearerAuth": [ "partner:basic:read", "partner:fees:update" ] } ], "summary": "Update Account Fees", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ], "x-whop-docs-subgroup": "Fees" }, "x-whop-surface": "native" }, "/accounts/{account_id}/financing_providers": { "get": { "description": "Lists every financing provider and where it stands for an account: whether checkout offers it, what the merchant can do to turn it on, and why it is off.", "operationId": "listFinancingProviders", "parameters": [ { "description": "Only providers with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "eligible", "needs_action", "in_review", "active", "inactive" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/FinancingProvider" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Financing providers returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid status" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Read permission required" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Account not found" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "List Financing Providers", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the account, prefixed `biz_`.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/accounts/{account_id}/preferences": { "get": { "description": "Retrieves the account's preferences: a singleton settings document keyed by preference name.", "operationId": "retrieveAccountPreferences", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "ads_agreement": { "description": "The account's Whop Ads services and payment authorization agreement. While `pending_signature`, campaign launch is blocked; sign by answering `requested_information` via `PATCH /verifications/{id}`.", "properties": { "accepted_at": { "description": "When the agreement was signed, as an ISO 8601 timestamp. `null` until signed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "agreement_version": { "description": "The agreement version signed or awaiting signature, as an ISO date. `null` when no signature is required.", "example": "2026-01-01", "type": [ "string", "null" ] }, "printed_name": { "description": "The signer's printed full name. `null` until signed.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "status": { "description": "Where the account's ads services agreement stands.", "enum": [ "not_required", "pending_signature", "signed" ], "example": "not_required", "type": "string" } }, "required": [ "status", "agreement_version", "printed_name", "accepted_at" ], "type": "object" }, "ads_certifications": { "description": "The account's advertising certifications, one entry per certification type Whop offers. Start an application by setting a type's `status` to `pending_information` via `PATCH`, then answer the fields it requests via `GET`/`PATCH /verifications/{id}`.", "items": { "properties": { "approved_countries": { "description": "Countries every approved application of this type covers, as ISO 3166-1 alpha-2 codes. Ads targeting only these countries are exempt from the category's restrictions.", "items": { "type": "string" }, "type": "array" }, "business_name": { "description": "The business name on the latest application.", "example": null, "type": [ "string", "null" ] }, "business_type": { "description": "The kind of business on the latest application. `null` until the account applies.", "enum": [ "online_pharmacy", "pharmaceutical_manufacturer", "telehealth_provider", null ], "example": "online_pharmacy", "type": [ "string", "null" ] }, "certification_type": { "description": "The certification this entry describes.", "enum": [ "prescription_drug_ads" ], "example": "prescription_drug_ads", "type": "string" }, "countries": { "description": "Countries the latest application covers, as ISO 3166-1 alpha-2 codes.", "items": { "type": "string" }, "type": "array" }, "denial_reason": { "description": "Why the latest application was denied. `null` unless `status` is `denied`.", "example": null, "type": [ "string", "null" ] }, "request_id": { "description": "The latest application's request ID, prefixed `inrq_`. `null` until the account applies.", "example": null, "type": [ "string", "null" ] }, "status": { "description": "`not_started` until the account applies; `pending_information` while an application waits for answers; `in_review` once submitted; then `approved` or `denied`.", "enum": [ "not_started", "pending_information", "in_review", "approved", "denied" ], "example": "not_started", "type": "string" }, "url": { "description": "The website on the latest application.", "example": null, "type": [ "string", "null" ] } }, "required": [ "certification_type", "status", "request_id", "business_name", "url", "business_type", "countries", "approved_countries", "denial_reason" ], "type": "object" }, "type": "array" }, "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when the primary fails. `null` until ads billing has been configured.", "properties": { "backup": { "properties": { "card_brand": { "description": "Card brand, present for `card` entries.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Expiration month, present for `card` entries.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Expiration year, present for `card` entries.", "example": 2031, "type": [ "integer", "null" ] }, "icon_url": { "description": "Balance owner icon URL, present for `platform_balance` entries.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits, present for `card` entries.", "example": "4242", "type": [ "string", "null" ] }, "title": { "description": "Balance name, present for account `platform_balance` entries (null for a personal balance).", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "type": { "description": "The funding source kind: a Whop balance or a saved card.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type", "id" ], "type": [ "object", "null" ] }, "primary": { "properties": { "card_brand": { "description": "Card brand, present for `card` entries.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Expiration month, present for `card` entries.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Expiration year, present for `card` entries.", "example": 2031, "type": [ "integer", "null" ] }, "icon_url": { "description": "Balance owner icon URL, present for `platform_balance` entries.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits, present for `card` entries.", "example": "4242", "type": [ "string", "null" ] }, "title": { "description": "Balance name, present for account `platform_balance` entries (null for a personal balance).", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "type": { "description": "The funding source kind: a Whop balance or a saved card.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type", "id" ], "type": [ "object", "null" ] } }, "required": [ "primary", "backup" ], "type": [ "object", "null" ] }, "ads_reporting_currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`.", "example": "usd", "type": "string" }, "ads_scheduling_timezone": { "description": "IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Defaults to `America/New_York` until explicitly overridden.", "example": "America/New_York", "type": "string" }, "ads_triple_whale_integration": { "description": "The account's Triple Whale integration, which pushes Whop ad spend to Triple Whale's Data-In API so it reports as a `whop` channel. Available to any Triple Whale customer — Shopify, WooCommerce, or a custom checkout — by setting `shop_domain`. Requires the `ad_campaign:create` scope. Once connected, ad click-through URLs Whop serves carry `tw_source=whop` and `tw_adid=` query parameters so Triple Whale's pixel attributes conversions back to the originating ad — no destination URL changes are needed.", "properties": { "masked_api_key": { "description": "The leading characters of the stored Data-In API key, followed by asterisks. The full key is never returned. `null` when no key is stored.", "example": "tw_live_********", "type": [ "string", "null" ] }, "shop_domain": { "description": "The shop domain spend is reported for, such as `acme.myshopify.com` or a custom domain for a non-Shopify store. `null` when none is set.", "example": "shinetime.myshopify.com", "type": [ "string", "null" ] }, "status": { "description": "Where the integration stands. `requires_shop_domain` means no shop domain is configured — set `shop_domain` before spend can be reported.", "enum": [ "connected", "not_connected", "requires_shop_domain" ], "example": "requires_shop_domain", "type": "string" } }, "required": [ "status", "masked_api_key", "shop_domain" ], "type": "object" }, "cards_auto_top_up": { "description": "Whether incoming funds are automatically moved to the account's cards balance. `false` when the account has no cards balance.", "example": false, "type": "boolean" }, "cards_notifications": { "description": "Whether Whop Card notifications reach this account's team. `true` by default, including when the account has no cards balance. Set it to `false` to stop every card email and push notification for the account — application status, verification and action-required alerts, card-ready alerts, declines, large charges, and cashback summaries. Cardholder onboarding invitations still send, because they carry the only link an invited cardholder can onboard with. Requesting a card is rejected while notifications are off, since the request reaches nobody. Cards on personal accounts are unaffected.", "example": true, "type": "boolean" }, "covers_connected_account_negative_balances": { "description": "Whether this account covers its connected accounts' negative balances. When a connected account's balance drops below zero (from refunds, disputes, or fees), this account's available balance in the same currency pays it back, up to what is available. Refunds on its connected accounts may also take them negative by up to this account's available balance. `null` when the account has no connected accounts.", "example": null, "type": [ "boolean", "null" ] }, "customer_tracking": { "description": "The saved customer tracking settings for the hosted tracking page and Element, exactly as saved. `null` until set; tracking is off unless `enabled` is `true`.", "oneOf": [ { "$ref": "#/components/schemas/CustomerTrackingPreferences" }, { "example": null, "type": "null" } ] }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files the evidence response when this account's payments are disputed. Off by default; enabling it also opts the account into the success fee charged only on disputes it wins.", "example": false, "type": "boolean" }, "economic_intelligence": { "description": "Whether Economic Intelligence is on for the account. It turns off automatically at `economic_intelligence_ends_at`.", "example": false, "type": "boolean" }, "economic_intelligence_auto_renew": { "description": "Whether Economic Intelligence renews itself every week, with no end date. Turn it on with the `weekly` offer. Set it to `false` to stop renewing, which keeps Economic Intelligence on until the end of the current week, shown in `economic_intelligence_ends_at`; stopping before the first renewal charges the rest of that week at the `7_days` offer's fee. Set it back to `true` before then to keep renewing at the weekly fee.", "example": false, "type": "boolean" }, "economic_intelligence_ends_at": { "description": "When the account's committed Economic Intelligence period ends, as an ISO 8601 timestamp. Economic Intelligence can't be turned off before then. `null` when Economic Intelligence is off or renews automatically.", "example": null, "type": [ "string", "null" ] }, "economic_intelligence_fee_percentage": { "description": "Percentage of volume charged while Economic Intelligence is on, such as `1.5` for 1.5%. `null` when Economic Intelligence is off.", "example": null, "type": [ "number", "null" ] }, "economic_intelligence_first_renewal_at": { "description": "When auto-renew first renews, as an ISO 8601 timestamp. Turning auto-renew off before then charges the rest of that week at the `7_days` offer's fee. `null` when auto-renew is off.", "example": null, "type": [ "string", "null" ] }, "economic_intelligence_offers": { "description": "What the account can choose now to turn on Economic Intelligence, each with its fee. Every offer while Economic Intelligence is off; only the `weekly` auto-renew offer while a committed period is running, as an upgrade; empty while it renews automatically.", "items": { "properties": { "auto_renew": { "description": "Whether this offer renews every period until auto-renew is turned off, rather than ending after one.", "example": true, "type": "boolean" }, "duration": { "description": "What period of time Economic Intelligence stays on. For an auto-renew offer, the length of each period it renews for.", "example": 7, "type": "integer" }, "duration_unit": { "description": "The unit of time the duration is in (hours or days)", "enum": [ "hours", "days" ], "example": "days", "type": "string" }, "fee_percentage": { "description": "Percentage of volume charged while Economic Intelligence is on, such as `1.5` for 1.5%.", "example": 1.0, "type": "number" }, "key": { "description": "The unique identifier for this offer. Pass this value as `economic_intelligence_duration_key` to turn it on.", "enum": [ "weekly", "7_days", "1_day", "1_hour" ], "example": "weekly", "type": "string" }, "recommended": { "description": "Whether Whop recommends this offer. At most one offer is recommended.", "example": true, "type": "boolean" } }, "required": [ "key", "duration", "duration_unit", "fee_percentage", "auto_renew", "recommended" ], "type": "object" }, "type": "array" }, "economic_intelligence_previous_period": { "description": "The account's last Economic Intelligence period, once it has ended. `null` while Economic Intelligence is on, or when it has never been on.", "properties": { "ended_at": { "description": "When the period ended, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "fee_percentage": { "description": "Percentage of volume charged during the period, such as `3` for 3%.", "example": 3.0, "type": "number" } }, "required": [ "ended_at", "fee_percentage" ], "type": [ "object", "null" ] }, "feedback_options": { "description": "The account's own cancel reasons, in the order members see them when they cancel. Each is filed under a standard category, saved as the membership's `cancel_option`, so reports keep grouping cancellations. Empty when the account uses Whop's default reasons.", "items": { "properties": { "category": { "description": "The category saved as the membership's `cancel_option` when a member picks this option.", "enum": [ "too_expensive", "switching", "missing_features", "technical_issues", "bad_experience", "unused", "other" ], "example": "unused", "type": "string" }, "id": { "description": "Feedback option ID, prefixed `fo_`. Pass it as `feedback_option_id` when canceling a membership, or back in `feedback_options` to keep the option when changing the list.", "example": "fo_xxxxxxxxxxxxxx", "type": "string" }, "label": { "description": "The cancel reason as members see it. Up to 100 characters.", "example": "I don't get my car detailed often enough", "type": "string" } }, "required": [ "id", "label", "category" ], "type": "object" }, "type": "array" }, "preferred_settlement_currency": { "description": "Lowercase ISO currency code every new sale settles into, regardless of the plan's currency or what the buyer paid in. Sales converted this way carry an additional 0.5% FX fee. `null` when the account settles each sale in its plan's currency.", "enum": [ "usd", "eur", "gbp", "cad", "aud", null ], "example": "usd", "type": [ "string", "null" ] }, "preferred_settlement_currency_changeable_at": { "description": "When `preferred_settlement_currency` may next be changed or turned off, as an ISO 8601 timestamp. It can change at most once a day. `null` when it may change now.", "example": null, "type": [ "string", "null" ] }, "subscription_failure_behavior": { "description": "What happens to a subscription once every retry of a renewal payment has failed. `cancel` (the default) cancels it. `none` leaves it past due and keeps billing it each period; access follows the account's past-due access setting.", "enum": [ "cancel", "none" ], "example": "cancel", "type": "string" } }, "required": [ "ads_payment_methods", "ads_reporting_currency", "ads_scheduling_timezone", "ads_agreement", "ads_certifications", "ads_triple_whale_integration", "cards_auto_top_up", "cards_notifications", "covers_connected_account_negative_balances", "dispute_fighter_enabled", "feedback_options", "economic_intelligence", "economic_intelligence_auto_renew", "economic_intelligence_ends_at", "economic_intelligence_fee_percentage", "economic_intelligence_first_renewal_at", "economic_intelligence_offers", "economic_intelligence_previous_period", "preferred_settlement_currency", "preferred_settlement_currency_changeable_at", "subscription_failure_behavior", "customer_tracking" ], "type": "object" } } }, "description": "preferences retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] }, { "bearerAuth": [ "payout:account:update" ] }, { "bearerAuth": [ "payment:dispute" ] }, { "bearerAuth": [ "company:update" ] } ], "summary": "Retrieve Account Preferences", "tags": [ "Accounts" ] }, "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates the account's preferences. Each top-level key present in the body is replaced as a whole; omitted keys are left untouched.\n\nRequired scopes depend on the preferences being updated:\n\n| Preferences | Required scope |\n| --- | --- |\n| `ads_payment_methods`, `ads_reporting_currency`, `ads_scheduling_timezone`, `ads_triple_whale_integration`, `ads_certifications` | `ad_campaign:create` |\n| `cards_auto_top_up`, `cards_notifications`, `covers_connected_account_negative_balances` | `payout:account:update` |\n| `dispute_fighter_enabled` | `payment:dispute` |\n| `economic_intelligence_duration_key`, `economic_intelligence_auto_renew` | `company:update` |\n| `feedback_options`, `customer_tracking` | `company:manage_checkout` |\n\nWhen updating preferences from multiple rows, all corresponding scopes are required for the account.\n", "operationId": "updateAccountPreferences", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ads_certifications": { "additionalProperties": { "properties": { "status": { "description": "Must be `pending_information`.", "enum": [ "pending_information" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "description": "Opens an advertising certification application. Keyed by certification type (`prescription_drug_ads`); set the entry's `status` to `pending_information` to start, then answer the requested fields via `PATCH /verifications/{id}`. Only one application per type can be open at a time; every other status is set by Whop's review. Requires the `ad_campaign:create` scope on your API key.", "example": { "prescription_drug_ads": { "status": "pending_information" } }, "type": "object" }, "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. Requires `primary`; `backup` is optional and covers the charge when the primary fails. Requires the `ad_campaign:create` scope on your API key. Configuring a `card` requires a user token; account API keys can configure only `platform_balance` sources.", "properties": { "backup": { "description": "Optional second method charged if the primary fails. Any pairing is allowed (two cards, card+balance, balance+card); omit it to run on a single method. Must differ from the primary.", "properties": { "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`. Optional for `platform_balance` — defaults to the account's default Whop balance. Required for `card`.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" }, "type": { "description": "The funding source kind.", "enum": [ "platform_balance", "card" ], "example": "card", "type": "string" } }, "required": [ "type" ], "type": "object" }, "primary": { "properties": { "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`. Optional for `platform_balance` — defaults to the account's default Whop balance. Required for `card`.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" }, "type": { "description": "The funding source kind.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type" ], "type": "object" } }, "required": [ "primary" ], "type": "object" }, "ads_reporting_currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`. Requires the `ad_campaign:create` scope on your API key.", "example": "eur", "type": "string" }, "ads_scheduling_timezone": { "description": "IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Cannot be cleared once set — pass a new value to change it. Requires the `ad_campaign:create` scope on your API key.", "example": "PST8PDT", "type": "string" }, "ads_triple_whale_integration": { "description": "Connects or disconnects the Triple Whale integration, or changes the shop it reports to. Requires the `ad_campaign:create` scope on your API key. Connecting requires a `shop_domain` to report spend against.", "properties": { "api_key": { "description": "A Triple Whale Data-In API key with the `Ads: Write` scope, validated against Triple Whale before it is stored. Pass `null` to disconnect. Connecting for the first time backfills the account's existing ad spend. Required unless you are only changing `shop_domain` on an already connected integration, in which case the stored key is reused.", "example": "tw_live_key_1234", "type": [ "string", "null" ] }, "shop_domain": { "description": "The exact shop domain configured in Triple Whale's Settings → Store (for Shopify this is the `.myshopify.com` domain; for a custom sales platform it's whatever domain Triple Whale assigned when the shop was set up there). A leading `https://` and trailing `/` are stripped, and what remains must be a bare hostname with no path or spaces. Validated against Triple Whale — the API key must have access to it — before it is stored. Changing it on a connected integration backfills the account's ad spend onto the new shop. Omit to keep the stored domain; there is no way to clear a stored value, only to overwrite it with a new domain.", "example": "custom-store.example.com", "type": "string" } }, "type": "object" }, "cards_auto_top_up": { "description": "Whether incoming funds are automatically moved to the account's cards balance. Requires a cards balance on the account and the `payout:account:update` scope on your API key.", "example": true, "type": "boolean" }, "cards_notifications": { "description": "Whether Whop Card notifications reach this account's team. Set it to `false` to stop every card email and push notification for the account — application status, verification and action-required alerts, card-ready alerts, declines, large charges, and cashback summaries. Cardholder onboarding invitations still send, because they carry the only link an invited cardholder can onboard with. Requesting a card is rejected while notifications are off, since the request reaches nobody. Cards on personal accounts are unaffected. Requires a cards balance on the account and the `payout:account:update` scope on your API key.", "example": true, "type": "boolean" }, "covers_connected_account_negative_balances": { "description": "Whether this account covers its connected accounts' negative balances. When a connected account's balance drops below zero (from refunds, disputes, or fees), this account's available balance in the same currency pays it back, up to what is available. Only accounts with connected accounts can set it. Requires the `payout:account:update` scope on your API key.", "example": true, "type": "boolean" }, "customer_tracking": { "additionalProperties": false, "description": "Customer tracking settings for the hosted tracking page and Element, replaced as a whole: fields left out are saved as unset. Pass null to clear them, which turns tracking off. Tracking is off unless `enabled` is `true`. Requires the `company:manage_checkout` scope on your API key.", "properties": { "accent_color": { "description": "Accent color, as a `#rrggbb` hex color. Unset uses the default.", "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "enabled": { "description": "Turns the public tracking page and guest lookup on. Unset is off.", "type": [ "boolean", "null" ] }, "show_business_name": { "description": "Show the business name on the tracking page and Element. Unset shows it.", "type": [ "boolean", "null" ] }, "show_logo": { "description": "Show the account logo on the tracking page and Element. Unset shows it.", "type": [ "boolean", "null" ] }, "support_email": { "description": "Customer support email address.", "maxLength": 254, "type": [ "string", "null" ] }, "support_url": { "description": "HTTPS customer support URL.", "maxLength": 2048, "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files the evidence response when this account's payments are disputed. Off by default; enabling it also opts the account into the success fee charged only on disputes it wins. Requires the `payment:dispute` scope on your API key.", "example": true, "type": "boolean" }, "economic_intelligence_auto_renew": { "description": "`false` stops renewing: Economic Intelligence stays on until the end of the current week, and stopping before the first renewal charges the rest of that week at the `7_days` offer's fee. `true` keeps it renewing again before then, or turns it on like the `weekly` offer. Can't be combined with `economic_intelligence_duration_key`. Requires the `company:update` scope on your API key.", "example": false, "type": "boolean" }, "economic_intelligence_duration_key": { "description": "Turns on Economic Intelligence with the offer that has this `key` in `economic_intelligence_offers`, at that offer's fee. A committed duration can't be changed or turned off until `economic_intelligence_ends_at`, except to upgrade to `weekly`, which switches to auto-renew right away. Requires the `company:update` scope on your API key.", "enum": [ "weekly", "7_days", "1_day", "1_hour" ], "example": "weekly", "type": "string" }, "feedback_options": { "description": "Replaces the account's own cancel reasons, shown to members in this order when they cancel. Pass an option's `id` to keep it, for example when renaming it; options without an `id` are added, and options left out are removed. Pass an empty array to go back to Whop's default reasons. Members who already picked an option keep the label they saw. Requires the `company:manage_checkout` scope on your API key.", "items": { "properties": { "category": { "description": "The category saved as the membership's `cancel_option` when a member picks this option, so reports keep grouping cancellations.", "enum": [ "too_expensive", "switching", "missing_features", "technical_issues", "bad_experience", "unused", "other" ], "example": "unused", "type": "string" }, "id": { "description": "The ID of an option to keep. Omit it to add a new option.", "example": "fo_xxxxxxxxxxxxxx", "type": "string" }, "label": { "description": "The cancel reason as members see it.", "example": "I don't get my car detailed often enough", "maxLength": 100, "type": "string" } }, "required": [ "label", "category" ], "type": "object" }, "maxItems": 10, "type": "array" }, "preferred_settlement_currency": { "description": "Settle every new sale into this currency, regardless of the plan's currency or what the buyer paid in; sales converted this way carry an additional 0.5% FX fee. Pass `null` to go back to settling each sale in its plan's currency. Changing it never converts money already in your balances, and it can change at most once a day (see `preferred_settlement_currency_changeable_at`). Requires the `payout:account:update` scope on your API key.", "enum": [ "usd", "eur", "gbp", "cad", "aud", null ], "example": "eur", "type": [ "string", "null" ] }, "subscription_failure_behavior": { "description": "What happens to a subscription once every retry of a renewal payment has failed. `cancel` (the default) cancels it. `none` leaves it past due and keeps billing it each period; access follows the account's past-due access setting. Requires company:manage_checkout permission.", "enum": [ "cancel", "none" ], "example": "none", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "ads_agreement": { "description": "The account's Whop Ads services and payment authorization agreement. While `pending_signature`, campaign launch is blocked; sign by answering `requested_information` via `PATCH /verifications/{id}`.", "properties": { "accepted_at": { "description": "When the agreement was signed, as an ISO 8601 timestamp. `null` until signed.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "agreement_version": { "description": "The agreement version signed or awaiting signature, as an ISO date. `null` when no signature is required.", "example": "2026-01-01", "type": [ "string", "null" ] }, "printed_name": { "description": "The signer's printed full name. `null` until signed.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "status": { "description": "Where the account's ads services agreement stands.", "enum": [ "not_required", "pending_signature", "signed" ], "example": "not_required", "type": "string" } }, "required": [ "status", "agreement_version", "printed_name", "accepted_at" ], "type": "object" }, "ads_certifications": { "description": "The account's advertising certifications, one entry per certification type Whop offers. Start an application by setting a type's `status` to `pending_information` via `PATCH`, then answer the fields it requests via `GET`/`PATCH /verifications/{id}`.", "items": { "properties": { "approved_countries": { "description": "Countries every approved application of this type covers, as ISO 3166-1 alpha-2 codes. Ads targeting only these countries are exempt from the category's restrictions.", "items": { "type": "string" }, "type": "array" }, "business_name": { "description": "The business name on the latest application.", "example": null, "type": [ "string", "null" ] }, "business_type": { "description": "The kind of business on the latest application. `null` until the account applies.", "enum": [ "online_pharmacy", "pharmaceutical_manufacturer", "telehealth_provider", null ], "example": "online_pharmacy", "type": [ "string", "null" ] }, "certification_type": { "description": "The certification this entry describes.", "enum": [ "prescription_drug_ads" ], "example": "prescription_drug_ads", "type": "string" }, "countries": { "description": "Countries the latest application covers, as ISO 3166-1 alpha-2 codes.", "items": { "type": "string" }, "type": "array" }, "denial_reason": { "description": "Why the latest application was denied. `null` unless `status` is `denied`.", "example": null, "type": [ "string", "null" ] }, "request_id": { "description": "The latest application's request ID, prefixed `inrq_`. `null` until the account applies.", "example": "inrq_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "status": { "description": "`not_started` until the account applies; `pending_information` while an application waits for answers; `in_review` once submitted; then `approved` or `denied`.", "enum": [ "not_started", "pending_information", "in_review", "approved", "denied" ], "example": "not_started", "type": "string" }, "url": { "description": "The website on the latest application.", "example": null, "type": [ "string", "null" ] } }, "required": [ "certification_type", "status", "request_id", "business_name", "url", "business_type", "countries", "approved_countries", "denial_reason" ], "type": "object" }, "type": "array" }, "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when the primary fails. `null` until ads billing has been configured.", "properties": { "backup": { "properties": { "card_brand": { "description": "Card brand, present for `card` entries.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Expiration month, present for `card` entries.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Expiration year, present for `card` entries.", "example": 2031, "type": [ "integer", "null" ] }, "icon_url": { "description": "Balance owner icon URL, present for `platform_balance` entries.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits, present for `card` entries.", "example": "4242", "type": [ "string", "null" ] }, "title": { "description": "Balance name, present for account `platform_balance` entries (null for a personal balance).", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "type": { "description": "The funding source kind: a Whop balance or a saved card.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type", "id" ], "type": [ "object", "null" ] }, "primary": { "properties": { "card_brand": { "description": "Card brand, present for `card` entries.", "example": "visa", "type": [ "string", "null" ] }, "exp_month": { "description": "Expiration month, present for `card` entries.", "example": 10, "type": [ "integer", "null" ] }, "exp_year": { "description": "Expiration year, present for `card` entries.", "example": 2031, "type": [ "integer", "null" ] }, "icon_url": { "description": "Balance owner icon URL, present for `platform_balance` entries.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "description": "The funding source ID: a Whop balance (`ldgr_`) for `platform_balance`, or a payment method (`payt_`) for `card`.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits, present for `card` entries.", "example": "4242", "type": [ "string", "null" ] }, "title": { "description": "Balance name, present for account `platform_balance` entries (null for a personal balance).", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "type": { "description": "The funding source kind: a Whop balance or a saved card.", "enum": [ "platform_balance", "card" ], "example": "platform_balance", "type": "string" } }, "required": [ "type", "id" ], "type": [ "object", "null" ] } }, "required": [ "primary", "backup" ], "type": [ "object", "null" ] }, "ads_reporting_currency": { "description": "Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`.", "example": "usd", "type": "string" }, "ads_scheduling_timezone": { "description": "IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Defaults to `America/New_York` until explicitly overridden.", "example": "America/New_York", "type": "string" }, "ads_triple_whale_integration": { "description": "The account's Triple Whale integration, which pushes Whop ad spend to Triple Whale's Data-In API so it reports as a `whop` channel. Available to any Triple Whale customer — Shopify, WooCommerce, or a custom checkout — by setting `shop_domain`. Requires the `ad_campaign:create` scope. Once connected, ad click-through URLs Whop serves carry `tw_source=whop` and `tw_adid=` query parameters so Triple Whale's pixel attributes conversions back to the originating ad — no destination URL changes are needed.", "properties": { "masked_api_key": { "description": "The leading characters of the stored Data-In API key, followed by asterisks. The full key is never returned. `null` when no key is stored.", "example": "tw_live_********", "type": [ "string", "null" ] }, "shop_domain": { "description": "The shop domain spend is reported for, such as `acme.myshopify.com` or a custom domain for a non-Shopify store. `null` when none is set.", "example": "shinetime.myshopify.com", "type": [ "string", "null" ] }, "status": { "description": "Where the integration stands. `requires_shop_domain` means no shop domain is configured — set `shop_domain` before spend can be reported.", "enum": [ "connected", "not_connected", "requires_shop_domain" ], "example": "requires_shop_domain", "type": "string" } }, "required": [ "status", "masked_api_key", "shop_domain" ], "type": "object" }, "cards_auto_top_up": { "description": "Whether incoming funds are automatically moved to the account's cards balance. `false` when the account has no cards balance.", "example": false, "type": "boolean" }, "cards_notifications": { "description": "Whether Whop Card notifications reach this account's team. `true` by default, including when the account has no cards balance. Set it to `false` to stop every card email and push notification for the account — application status, verification and action-required alerts, card-ready alerts, declines, large charges, and cashback summaries. Cardholder onboarding invitations still send, because they carry the only link an invited cardholder can onboard with. Requesting a card is rejected while notifications are off, since the request reaches nobody. Cards on personal accounts are unaffected.", "example": true, "type": "boolean" }, "covers_connected_account_negative_balances": { "description": "Whether this account covers its connected accounts' negative balances. When a connected account's balance drops below zero (from refunds, disputes, or fees), this account's available balance in the same currency pays it back, up to what is available. Refunds on its connected accounts may also take them negative by up to this account's available balance. `null` when the account has no connected accounts.", "example": true, "type": [ "boolean", "null" ] }, "customer_tracking": { "description": "The saved customer tracking settings for the hosted tracking page and Element, exactly as saved. `null` until set; tracking is off unless `enabled` is `true`.", "oneOf": [ { "$ref": "#/components/schemas/CustomerTrackingPreferences" }, { "example": null, "type": "null" } ] }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files the evidence response when this account's payments are disputed. Off by default; enabling it also opts the account into the success fee charged only on disputes it wins.", "example": false, "type": "boolean" }, "economic_intelligence": { "description": "Whether Economic Intelligence is on for the account. It turns off automatically at `economic_intelligence_ends_at`.", "example": false, "type": "boolean" }, "economic_intelligence_auto_renew": { "description": "Whether Economic Intelligence renews itself every week, with no end date. Turn it on with the `weekly` offer. Set it to `false` to stop renewing, which keeps Economic Intelligence on until the end of the current week, shown in `economic_intelligence_ends_at`; stopping before the first renewal charges the rest of that week at the `7_days` offer's fee. Set it back to `true` before then to keep renewing at the weekly fee.", "example": false, "type": "boolean" }, "economic_intelligence_ends_at": { "description": "When the account's committed Economic Intelligence period ends, as an ISO 8601 timestamp. Economic Intelligence can't be turned off before then. `null` when Economic Intelligence is off or renews automatically.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "economic_intelligence_fee_percentage": { "description": "Percentage of volume charged while Economic Intelligence is on, such as `1.5` for 1.5%. `null` when Economic Intelligence is off.", "example": 1.5, "type": [ "number", "null" ] }, "economic_intelligence_first_renewal_at": { "description": "When auto-renew first renews, as an ISO 8601 timestamp. Turning auto-renew off before then charges the rest of that week at the `7_days` offer's fee. `null` when auto-renew is off.", "example": null, "type": [ "string", "null" ] }, "economic_intelligence_offers": { "description": "What the account can choose now to turn on Economic Intelligence, each with its fee. Every offer while Economic Intelligence is off; only the `weekly` auto-renew offer while a committed period is running, as an upgrade; empty while it renews automatically.", "items": { "properties": { "auto_renew": { "description": "Whether this offer renews every period until auto-renew is turned off, rather than ending after one.", "example": true, "type": "boolean" }, "duration": { "description": "What period of time Economic Intelligence stays on. For an auto-renew offer, the length of each period it renews for.", "example": 7, "type": "integer" }, "duration_unit": { "description": "The unit of time the duration is in (hours or days)", "enum": [ "hours", "days" ], "example": "days", "type": "string" }, "fee_percentage": { "description": "Percentage of volume charged while Economic Intelligence is on, such as `1.5` for 1.5%.", "example": 1.0, "type": "number" }, "key": { "description": "The unique identifier for this offer. Pass this value as `economic_intelligence_duration_key` to turn it on.", "enum": [ "weekly", "7_days", "1_day", "1_hour" ], "example": "weekly", "type": "string" }, "recommended": { "description": "Whether Whop recommends this offer. At most one offer is recommended.", "example": true, "type": "boolean" } }, "required": [ "key", "duration", "duration_unit", "fee_percentage", "auto_renew", "recommended" ], "type": "object" }, "type": "array" }, "economic_intelligence_previous_period": { "description": "The account's last Economic Intelligence period, once it has ended. `null` while Economic Intelligence is on, or when it has never been on.", "properties": { "ended_at": { "description": "When the period ended, as an ISO 8601 timestamp.", "type": "string" }, "fee_percentage": { "description": "Percentage of volume charged during the period, such as `3` for 3%.", "type": "number" } }, "required": [ "ended_at", "fee_percentage" ], "type": [ "object", "null" ] }, "feedback_options": { "description": "The account's own cancel reasons, in the order members see them when they cancel. Each is filed under a standard category, saved as the membership's `cancel_option`, so reports keep grouping cancellations. Empty when the account uses Whop's default reasons.", "items": { "properties": { "category": { "description": "The category saved as the membership's `cancel_option` when a member picks this option.", "enum": [ "too_expensive", "switching", "missing_features", "technical_issues", "bad_experience", "unused", "other" ], "example": "bad_experience", "type": "string" }, "id": { "description": "Feedback option ID, prefixed `fo_`. Pass it as `feedback_option_id` when canceling a membership, or back in `feedback_options` to keep the option when changing the list.", "example": "fo_xxxxxxxxxxxxxx", "type": "string" }, "label": { "description": "The cancel reason as members see it. Up to 100 characters.", "example": "The detail missed spots", "type": "string" } }, "required": [ "id", "label", "category" ], "type": "object" }, "type": "array" }, "preferred_settlement_currency": { "description": "Lowercase ISO currency code every new sale settles into, regardless of the plan's currency or what the buyer paid in. Sales converted this way carry an additional 0.5% FX fee. `null` when the account settles each sale in its plan's currency.", "enum": [ "usd", "eur", "gbp", "cad", "aud", null ], "example": "eur", "type": [ "string", "null" ] }, "preferred_settlement_currency_changeable_at": { "description": "When `preferred_settlement_currency` may next be changed or turned off, as an ISO 8601 timestamp. It can change at most once a day. `null` when it may change now.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "subscription_failure_behavior": { "description": "What happens to a subscription once every retry of a renewal payment has failed. `cancel` (the default) cancels it. `none` leaves it past due and keeps billing it each period; access follows the account's past-due access setting.", "enum": [ "cancel", "none" ], "example": "cancel", "type": "string" } }, "required": [ "ads_payment_methods", "ads_reporting_currency", "ads_scheduling_timezone", "ads_agreement", "ads_certifications", "ads_triple_whale_integration", "cards_auto_top_up", "cards_notifications", "covers_connected_account_negative_balances", "dispute_fighter_enabled", "feedback_options", "economic_intelligence", "economic_intelligence_auto_renew", "economic_intelligence_ends_at", "economic_intelligence_fee_percentage", "economic_intelligence_first_renewal_at", "economic_intelligence_offers", "economic_intelligence_previous_period", "preferred_settlement_currency", "preferred_settlement_currency_changeable_at", "subscription_failure_behavior", "customer_tracking" ], "type": "object" } } }, "description": "preferences updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid preferences" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "forbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "an application for that certification is already open" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] }, { "bearerAuth": [ "payout:account:update" ] }, { "bearerAuth": [ "payment:dispute" ] }, { "bearerAuth": [ "company:update" ] } ], "summary": "Update Account Preferences", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "/accounts/{account_id}/reserves": { "get": { "description": "Lists what the account's held balance is made of, one entry per currency: the total held, why each part is held, and the days it unlocks.", "operationId": "listAccountReserves", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AccountReserve" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "empty when nothing is held" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" }, "503": { "$ref": "#/components/responses/ServiceUnavailable", "description": "reserves could not be read right now" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "List Account Reserves", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/accounts/{id}": { "delete": { "description": "Deletes a connected account directly owned by the authenticated platform account. The account must have no settled, pending, or reserved balance in any currency and no active, trialing, or past-due memberships. The account stops resolving immediately, and its products, plans, and team access are removed in the background; payment history is retained. Deletion cannot be undone through the API. This cannot delete the platform account itself or an account owned by another platform.", "operationId": "deleteAccount", "parameters": [ { "description": "Connected account ID, prefixed `biz_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted connected account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "Connected account deleted." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Connected account still has active memberships or a balance." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "API key lacks the child-account deletion scope." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Connected account not found." } }, "security": [ { "bearerAuth": [ "company:delete_child" ] } ], "summary": "Delete a Connected Account", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_user_token" ] }, "get": { "description": "Retrieves an account visible to the credential by ID or public route, including its crypto wallet.", "operationId": "retrieveAccount", "parameters": [ { "description": "Also return the trading account under `trading`: its address and its Hyperliquid WebSocket subscriptions. Requires crypto_wallet:trade:read, crypto_wallet:trade, or crypto_wallet:manage permission and an Ethereum wallet; null otherwise.", "in": "query", "name": "include_trading", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Account ID, prefixed `biz_`, its public route, or `me` for the account associated with the current Account API key. User tokens have no single account, so they cannot use `me`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "account with an individual card application" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no account with that ID is visible to the credential" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Retrieve Account", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates an account. User tokens can update business accounts; Account API keys can update connected accounts.", "operationId": "updateAccount", "parameters": [ { "description": "Account ID, prefixed `biz_`. The reserved id `me` resolves to the requesting account, which an Account API key cannot edit.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "affiliate_application_required": { "description": "Whether prospective affiliates must submit an application before promoting this account.", "example": true, "type": "boolean" }, "affiliate_instructions": { "description": "Guidelines shown to affiliates promoting this account.", "example": "Send us your detailing content before promoting. No paid search on our brand terms.", "type": [ "string", "null" ] }, "banner_image": { "additionalProperties": true, "description": "Account banner image, used as the cover photo when creating a Whop-managed Facebook page. Image files up to 10 MB, except `image/gif`. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file).", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "business_address": { "description": "Account business address used to calculate tax. A complete address in a supported country is required when `tax_remitted_by` is `self`.", "properties": { "city": { "description": "City name.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "business_name": { "description": "The legal business name used with the account's tax address.", "example": " Shine Time Auto Detailing, LLC ", "maxLength": 255, "type": [ "string", "null" ] }, "cancellation_policy": { "additionalProperties": true, "description": "The account's cancellation policy document. Attached to new disputes as the cancellation policy evidence, with the terms of service as the fallback. PDF only. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file), or `null` to remove it.", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "collect_vat_id": { "description": "Whether checkout shows a VAT/tax ID field for buyers to optionally enter. Does not require a VAT ID to purchase.", "example": true, "type": "boolean" }, "country": { "description": "Country where the account is located.", "example": "US", "type": [ "string", "null" ] }, "description": { "description": "Account promotional description. When creating a Whop-managed Facebook page, it is truncated to 155 characters and used as the About text.", "example": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "type": [ "string", "null" ] }, "dispute_fighter_enabled": { "description": "Whether Whop assembles and files dispute evidence for this account. Enabling it opts into the success fee charged on disputes it wins. Requires payment:dispute. Omit to preserve the existing setting or creation default.", "type": "boolean" }, "eula": { "additionalProperties": true, "description": "The account's end-user license agreement document. PDF only. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file), or `null` to remove it.", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "featured_affiliate_product_id": { "description": "The ID of the product to feature for affiliates. Pass `null` to clear.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "home_preferences": { "description": "Public account home page preferences.", "items": { "enum": [ "hide_member_count", "hide_members_card" ], "example": "hide_member_count", "type": "string" }, "type": "array" }, "invoice_prefix": { "description": "Prefix used for account invoices.", "example": "SHINE", "type": [ "string", "null" ] }, "logo": { "additionalProperties": true, "description": "Account logo, used as the profile picture when creating a Whop-managed Facebook page. Image files up to 5 MB. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file).", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "metadata": { "additionalProperties": true, "description": "Arbitrary key/value metadata to store on the account.", "example": { "external_id": "shop_4417", "region": "austin" }, "type": "object" }, "onboarding_type": { "description": "The type of onboarding the account has completed.", "enum": [ "platform", "seller", null ], "example": "seller", "type": [ "string", "null" ] }, "opengraph_image": { "additionalProperties": true, "description": "Open Graph preview media used when the account is shared. Image and video files up to 5 MB. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file).", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "opengraph_image_variant": { "description": "The account Open Graph image variant.", "enum": [ "white", "black", "orange", null ], "example": "black", "type": [ "string", "null" ] }, "orchestration_enabled": { "description": "Whether payment orchestration is enabled for this account. Requires payout:account:update. Omit to preserve the existing setting or creation default.", "type": "boolean" }, "other_business_description": { "description": "The description of the business type when business_type is other.", "type": [ "string", "null" ] }, "other_industry_description": { "description": "The description of the industry type when industry_type is other.", "type": [ "string", "null" ] }, "privacy_policy": { "additionalProperties": true, "description": "The account's privacy policy document. PDF only. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file), or `null` to remove it.", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "product_tax_code_id": { "description": "ID of the tax classification code applied by default to the account's products. See the available [product categories](https://docs.numeral.com/essentials/product-categories).", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "require_2fa": { "description": "Whether the account requires authorized users to have two-factor authentication enabled.", "example": true, "type": "boolean" }, "return_policy": { "additionalProperties": true, "description": "The account's return and refund policy document. Attached to new disputes as the refund policy evidence, with the terms of service as the fallback. PDF only. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file), or `null` to remove it.", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "route": { "description": "The unique URL slug for the account.", "example": "shine-time-detailing", "type": [ "string", "null" ] }, "send_customer_emails": { "description": "Whether Whop sends transactional emails to customers on behalf of this account.", "example": false, "type": "boolean" }, "shipping_policy": { "additionalProperties": true, "description": "The account's shipping policy document. Sent with physical-goods dispute evidence. PDF only. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file), or `null` to remove it.", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "show_joined_whops": { "description": "Whether the account appears in joined whops on other accounts.", "example": false, "type": "boolean" }, "show_reviews_dtc": { "description": "Whether reviews are displayed on direct-to-consumer product pages.", "example": false, "type": "boolean" }, "show_user_directory": { "description": "Whether the account shows users in the user directory.", "example": false, "type": "boolean" }, "social_links": { "description": "The full list of social links to display for the account.", "items": { "additionalProperties": true, "example": { "url": "https://instagram.com/shinetimedetail", "website": "instagram" }, "type": "object" }, "type": "array" }, "store_page_config": { "description": "Account store page display configuration.", "properties": { "accent_color": { "description": "Accent color used on the account store page.", "enum": [ "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", null ], "example": "red", "type": [ "string", "null" ] }, "layout": { "description": "Layout used on the account store page.", "enum": [ "featured", "compact", null ], "example": "compact", "type": [ "string", "null" ] }, "profile_variant": { "description": "Profile presentation used on the account store page.", "enum": [ "personal", "business", null ], "example": "business", "type": [ "string", "null" ] }, "whop_affiliate_link": { "description": "Whether the account store page shows a Whop affiliate link.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "target_audience": { "description": "The target audience for this account.", "example": "Owners of new and enthusiast vehicles in Austin, TX", "type": [ "string", "null" ] }, "tax_collection_enabled_states": { "description": "US state codes (50 states plus `DC`) where the account collects tax. Replaces the full set on update. Only settable when `tax_remitted_by` is `self`.", "items": { "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "example": "TX", "type": "string" }, "type": "array" }, "tax_identifiers": { "description": "Account tax/VAT registrations to add or update. When `tax_remitted_by` is `self`, tax is calculated and collected only in the countries where the account holds a registration.", "items": { "properties": { "tax_id_type": { "description": "Tax ID type, for example `eu_vat`, `gb_vat`, or `us_ein`.", "enum": [ "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", "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" ], "example": "eu_vat", "type": "string" }, "tax_id_value": { "description": "Tax ID value, for example `DE123456789`.", "example": "DE123456789", "type": "string" } }, "required": [ "tax_id_type", "tax_id_value" ], "type": "object" }, "type": "array" }, "tax_remitted_by": { "description": "Determines whether Whop or the account calculates and remits tax. The account must provide a supported-country business address when it self-remits.", "enum": [ "whop", "self", "none" ], "example": "self", "type": "string" }, "tax_type": { "description": "Determines whether tax is included in the listed price or added at checkout.", "enum": [ "inclusive", "exclusive" ], "example": "inclusive", "type": "string" }, "terms_of_service": { "additionalProperties": true, "description": "The account's terms of service document. Attached to new disputes as the cancellation policy evidence when no cancellation policy is set. PDF only. Pass a JSON object containing an `id` from [Create File](/api-reference/files/create-file), or `null` to remove it.", "properties": { "id": { "description": "ID of a file from [Create File](/api-reference/files/create-file), prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "three_ds_level": { "description": "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.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "title": { "description": "The display name of the account.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "use_logo_as_opengraph_image_fallback": { "description": "Whether the account uses its logo as the fallback Open Graph image.", "example": true, "type": "boolean" }, "website": { "description": "The account's business website, as an `http` or `https` URL of at most 255 characters. Also added to the account's `social_links` as a `website` entry. Pass `null` to clear the website; existing social links are left unchanged.", "example": "https://shinetimedetail.com", "type": [ "string", "null" ] }, "whop_partner_enabled": { "description": "Set to `true` to turn on Whop Partner mode for the account, so its team can refer businesses and the account is paid partner commission on their sales. Recorded once; `false` is rejected.", "example": true, "type": "boolean" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "account updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "store page config has an unsupported enum value" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no account with that ID is visible to the credential" } }, "security": [ { "bearerAuth": [ "company:update" ] } ], "summary": "Update Account", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/accounts/{id}/form_company": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Starts an LLC or C-Corp formation for a business account. The application is validated and the response returns a hosted checkout URL; once paid, the filing is submitted. Track progress through the account's [`company_formation`](/api-reference/beta/accounts/retrieve-account) field on Retrieve Account.", "operationId": "formCompany", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "business_address": { "city": "Austin", "country": "US", "line1": "4180 Burnet Rd", "line2": "Suite 2", "postal_code": "78756", "state": "TX" }, "business_name": "Shine Time Auto Detailing", "business_phone": "+15125550142", "business_website": "https://shinetime.example", "entity_suffix": "LLC", "entity_type": "llc", "expedite_ein": true, "formation_state": "WY", "founders": [ { "address": { "city": "Austin", "country": "US", "line1": "907 Ridgemont Dr", "line2": "Apt 4", "postal_code": "78704", "state": "TX" }, "date_of_birth": "1988-03-14", "email": "marcus@shinetime.example", "first_name": "Marcus", "is_primary": true, "last_name": "Webb", "ownership_percentage": 100, "phone": "+15125550142", "roles": [ "president" ], "ssn": "123-45-6789" } ], "share_structure": { "number_of_shares": 123, "value": 123 }, "use_registered_agent": true }, "properties": { "business_address": { "description": "Company mailing address. Required unless `use_registered_agent` is `true`.", "properties": { "city": { "example": "Austin", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`.", "example": "US", "type": "string" }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": "string" }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": "string" }, "state": { "description": "State or region code, for example `CA`.", "example": "TX", "type": "string" } }, "required": [ "line1", "city", "state", "postal_code", "country" ], "type": "object" }, "business_name": { "description": "Legal name for the new company.", "example": "Shine Time Auto Detailing", "type": "string" }, "business_phone": { "description": "Business phone number in E.164 format, for example `+12125550100`. Required unless `use_registered_agent` is `true`.", "example": "+xxxxxxxxxxx", "type": "string" }, "business_website": { "description": "Company website URL.", "example": "https://shinetime.example", "type": "string" }, "entity_suffix": { "description": "Legal entity ending appended to `business_name`. LLC formations accept `LLC`, `L.L.C`, `L.L.C.` or `Limited Liability Company` and default to `LLC`; C-Corp formations accept `Inc`, `Inc.`, `Incorporated`, `Corp.`, `Corporation`, `C Corp`, `C Corporation`, `CCorp` or `Company` and default to `Inc.`. Unrecognized values fall back to the default for the entity type.", "enum": [ "LLC", "L.L.C", "L.L.C.", "Limited Liability Company", "Inc", "Inc.", "Incorporated", "Corp.", "Corporation", "C Corp", "C Corporation", "CCorp", "Company" ], "example": "Limited Liability Company", "type": "string", "x-enumNames": [ "LLC", "L_L_C", "L_L_C_", "Limited_Liability_Company", "Inc", "Inc_", "Incorporated", "Corp_", "Corporation", "C_Corp", "C_Corporation", "CCorp", "Company" ] }, "entity_type": { "description": "Legal entity type to form. Defaults to `llc`.", "enum": [ "llc", "c_corp" ], "example": "c_corp", "type": "string" }, "expedite_ein": { "description": "Request expedited EIN processing for an additional fee. Available only when no founder supplies an SSN.", "example": true, "type": "boolean" }, "formation_state": { "description": "Two-letter code of the US state (or `DC`) to form the company in. We recommend `WY` because Wyoming formations are completed the same day.", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "example": "WY", "type": "string" }, "founders": { "description": "The company's founders. Exactly one must be marked `is_primary` — the responsible party for the filing.", "items": { "properties": { "address": { "description": "Founder's personal address.", "properties": { "city": { "example": "Austin", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`.", "example": "US", "type": "string" }, "line1": { "description": "First line of the street address.", "example": "907 Ridgemont Dr", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Apt 4", "type": "string" }, "postal_code": { "description": "Postal or ZIP code.", "example": "78704", "type": "string" }, "state": { "description": "State or region code, for example `CA`.", "example": "TX", "type": "string" } }, "required": [ "line1", "city", "state", "postal_code", "country" ], "type": "object" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "email": { "example": "marcus@shinetime.example", "type": "string" }, "first_name": { "example": "Marcus", "type": "string" }, "is_primary": { "description": "Marks the responsible party for the filing. Exactly one founder must be primary.", "example": true, "type": "boolean" }, "last_name": { "example": "Webb", "type": "string" }, "ownership_percentage": { "description": "The founder's ownership share: greater than `0`, at most `100`. Shares across founders must total `100`. Required when `entity_type` is `llc`; ignored for C-Corps.", "example": 100, "type": "number" }, "phone": { "description": "Phone number in E.164 format, for example `+12125550100`.", "example": "+xxxxxxxxxxx", "type": "string" }, "roles": { "description": "Officer roles held by the member — one member can hold several. Required (at least one role) for every member when `entity_type` is `c_corp`; ignored for LLCs. Across all members every role must be covered; `president`, `secretary` and `treasurer` may each be held by only one member, while `director` may repeat.", "items": { "enum": [ "president", "secretary", "treasurer", "director" ], "example": "treasurer", "type": "string" }, "type": "array" }, "ssn": { "description": "The founder's US Social Security Number. Leave empty if the founder is not a US resident. Non-US founders can request expedited EIN processing via the `expedite_ein` option.", "example": "123-45-6789", "type": "string" } }, "required": [ "is_primary", "first_name", "last_name", "email", "phone", "address" ], "type": "object" }, "type": "array" }, "share_structure": { "description": "Authorized share structure. Required when `entity_type` is `c_corp`; ignored for LLCs.", "properties": { "number_of_shares": { "description": "Number of shares the company authorizes. Must be greater than `0`.", "example": 1000, "type": "integer" }, "value": { "description": "Par value per share, in USD. Must be greater than `0`; fractional values like `0.01` are allowed.", "example": 100, "type": "number" } }, "required": [ "number_of_shares", "value" ], "type": "object" }, "use_registered_agent": { "description": "Use the registered agent's address as the company address instead of `business_address`.", "example": true, "type": "boolean" } }, "required": [ "business_name", "formation_state", "founders" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "checkout_session_id": { "description": "Checkout session ID, prefixed `ch_`.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" }, "checkout_url": { "description": "Hosted checkout URL. Send the buyer here to pay for the formation; the filing is submitted once payment completes.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": "string" }, "currency": { "description": "Always `usd`.", "example": "usd", "type": "string" }, "total": { "description": "Total due at checkout in USD cents.", "example": 40000, "type": "integer" } }, "required": [ "checkout_url", "checkout_session_id", "total", "currency" ], "type": "object" } } }, "description": "application accepted and checkout created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid submission" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential cannot manage the account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "incorporation:write" ] } ], "summary": "Form Company", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/accounts/{id}/retry_ads_payment": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Queues one background retry of the account's failed ads payments across its campaigns, using the account's configured ads payment methods. A queued response does not mean payment succeeded; read each campaign's `delivery_status` and `issues` for the outcome. Successful settlement clears the payment block without changing a configured `active` or `paused` status; a legacy `payment_failed` status becomes `paused`. Returns an error when the account has no failed ads payments, or while a previous retry for the account is queued or running.", "operationId": "retryAccountAdsPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account whose ads payments will be retried.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "queued": { "description": "Whether the retry was accepted for background processing.", "example": true, "type": "boolean" } }, "required": [ "account_id", "queued" ], "type": "object" } } }, "description": "payment retry queued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "no failed ads payments" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing ads write permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Retry Failed Ads Payments", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "/accounts/{id}/suspend": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Connected account ID, prefixed `biz_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Suspends a connected account directly owned by the authenticated platform account. This cannot suspend the platform account itself or an account owned by another platform.", "operationId": "suspendAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "Connected account suspended." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "API key lacks the child-account suspension scope." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Connected account not found." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:suspend_child" ] } ], "summary": "Suspend a Connected Account", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "account_user_token" ] }, "x-whop-surface": "native" }, "/accounts/{id}/transfer_ownership": { "post": { "description": "Transfers ownership of the account to another user, identified by user ID or email address. If the recipient already holds the owner role, ownership moves immediately; otherwise they get an invite and ownership moves when they accept. The Whop CLI and MCP can hand off a business their user owns as a partner (`as_partner: true`) with the `partner:handoff` scope; other OAuth apps cannot transfer ownership.", "operationId": "transferAccountOwnership", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "as_partner": { "description": "If true, the current owner is credited as the account's Whop partner, earning partner commission on its sales. Requires the current owner to already be an enrolled Whop partner. Skipped if the account already has an active partner.", "example": true, "type": "boolean" }, "authorized_user_id": { "description": "Your team membership on the business this referral is made for, prefixed `ausr_`. The referral then credits that team instead of you personally. Requires `as_partner`.", "example": "ausr_xxxxxxxxxxxxxx", "type": "string" }, "identifier": { "description": "The user to transfer ownership to: a user ID (`user_*`) or an email address. An email address with no Whop account yet is sent an invite to create one.", "example": "marcus@shinetime.example", "type": "string" }, "member_id": { "description": "Your member record on the business this referral is made for, prefixed `mber_`, when your role there is held on your member record. Send this or `authorized_user_id`, not both. Requires `as_partner`.", "example": "mber_xxxxxxxxxxxxxx", "type": "string" }, "message": { "description": "A note from the partner, shown as a quote in the invite email and signed with their name. Requires `as_partner`; sending it on an ordinary transfer is a 400. Omit it and the email sends without a note.", "example": "Hey — set this up after our call on Tuesday. Ping me anytime.", "maxLength": 500, "type": "string" } }, "required": [ "identifier" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Ownership transferred." }, "201": { "content": { "application/json": { "schema": { "properties": { "invitation_sent": { "example": true, "type": "boolean" }, "object": { "enum": [ "team_member_invite" ], "example": "team_member_invite", "type": "string" } }, "required": [ "object", "invitation_sent" ], "type": "object" } } }, "description": "Ownership transfer invite sent — the recipient must accept before ownership moves." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "API key lacks the ownership transfer scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:transfer_ownership" ] }, { "bearerAuth": [ "partner:handoff" ] } ], "summary": "Transfer Account Ownership", "tags": [ "Accounts" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "x-whop-surface": "native" }, "/ad_campaigns": { "get": { "description": "Lists the ad campaigns for an account, with stats over the requested window.", "operationId": "listAdCampaigns", "parameters": [ { "description": "The account the campaigns belong to. Defaults to the account-scoped key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return campaigns with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "draft", "active", "paused", "payment_failed" ], "type": "string" } }, { "description": "Filter campaigns by a title or ID substring.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by. Defaults to created_at. Stat columns (spend, impressions, …) rank over the stats_from/stats_to window across the whole list, not just the current page. results, cost_per_result and return_on_ad_spend rank by the same Whop pixel-attributed values the response reports, and link_clicks by the same Whop pixel page views.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "updated_at", "spend", "impressions", "reach", "clicks", "link_clicks", "unique_clicks", "frequency", "click_through_rate", "results", "cost_per_mille", "cost_per_click", "cost_per_result", "return_on_ad_spend" ], "type": "string" } }, { "description": "The sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return campaigns of this type.", "in": "query", "name": "campaign_type", "required": false, "schema": { "enum": [ "standard", "search" ], "type": "string" } }, { "description": "Only return campaigns created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return campaigns created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Start of the stats window. Defaults to all-time.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window. Defaults to now.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare stats_from/stats_to dates resolve to day boundaries on this clock. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdCampaign" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "ad campaigns listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id missing and unresolvable" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List Ad Campaigns", "tags": [ "Ad Campaigns" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an ad campaign in `draft` status for an account. Nothing runs until you launch it by setting `status` to `active` with `PATCH /ad_campaigns/:id`.", "operationId": "createAdCampaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to create the campaign under. Defaults to the account-scoped key's own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "bid_type": { "description": "How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, `maximum_target` never bids above a cap. Only for campaigns that own the budget.", "enum": [ "minimum_cost", "average_target", "maximum_target" ], "example": "average_target", "type": "string" }, "budget_amount": { "description": "The campaign's budget in USD, which is what it is stored and billed in. Required when budget_optimization is `ad_campaign` (or send budget_amount_local instead); omit when each ad group sets its own budget.", "example": 25.0, "type": "number" }, "budget_amount_local": { "description": "The campaign's budget stated in the account's ads reporting currency (`budget_currency` on the response) instead of USD. Converted to USD at the current exchange rate and stored as budget_amount. Provide this or budget_amount, not both.", "type": "number" }, "budget_optimization": { "description": "Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`). Defaults to `ad_group`.", "enum": [ "ad_campaign", "ad_group" ], "example": "ad_campaign", "type": "string" }, "budget_type": { "description": "Whether the budget is spent per day (`daily`) or over the campaign's full run (`lifetime`). Defaults to `daily`.", "enum": [ "daily", "lifetime" ], "example": "daily", "type": "string" }, "campaign_type": { "description": "The kind of campaign to create. `standard` is the ad network's standard campaign; `search` shows text ads on search results for the ad groups' keywords. Defaults to `standard`. Can't be changed after creation.", "enum": [ "standard", "search" ], "example": "standard", "type": "string" }, "desired_cost_per_result": { "description": "The cost per result, in USD, you want this campaign to achieve. A target only: it is not a bid, cost cap, or bid cap, and doesn't change how the campaign's ads bid. Ad groups set cost and bid caps with their own `desired_cost_per_result`. Omit or send `null` for no target.", "example": 4.5, "type": [ "number", "null" ] }, "ends_at": { "description": "When the campaign stops delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "objective": { "description": "The goal the campaign optimizes toward.", "enum": [ "awareness", "traffic", "engagement", "leads", "sales" ], "example": "leads", "type": "string" }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "whop" ], "example": "whop", "type": "string" }, "special_ad_categories": { "description": "Regulated categories the campaign falls under. Ads in these categories are subject to extra targeting restrictions.", "items": { "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "employment", "type": "string" }, "type": "array" }, "starts_at": { "description": "When the campaign starts delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "title": { "description": "The title of the campaign.", "example": "Now hiring mobile detailers — Austin", "type": "string" } }, "required": [ "title", "platform", "objective" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unsupported platform" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Create an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}": { "delete": { "description": "Deletes an ad campaign and archives it on the ad platform (cascades to ad groups and ads).", "operationId": "deleteAdCampaign", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted ad campaign.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "ad campaign deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Delete an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "get": { "description": "Retrieves a single ad campaign with stats over the requested window.", "operationId": "retrieveAdCampaign", "parameters": [ { "description": "Start of the stats window.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone the stats window is interpreted in. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an ad campaign's settings, or launches a draft campaign by setting `status` to `active`. The objective is fixed at creation and cannot be changed.", "operationId": "updateAdCampaign", "parameters": [ { "$ref": "#/components/parameters/AdsPlatform" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bid_type": { "description": "How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, `maximum_target` never bids above a cap. Switching to `minimum_cost` clears the cap amounts stored on the campaign's ad groups. Only for campaigns that own the budget.", "enum": [ "minimum_cost", "average_target", "maximum_target" ], "example": "average_target", "type": "string" }, "budget_amount": { "description": "The campaign budget in USD, which is what it is stored and billed in. Interpreted as daily or lifetime per the campaign's budget type, including a budget_type sent in the same request.", "example": 40.0, "type": "number" }, "budget_amount_local": { "description": "The campaign budget stated in the account's ads reporting currency (`budget_currency` on the response) instead of USD. Converted to USD at the current exchange rate and stored as budget_amount; an amount equal to the current budget_amount_local keeps the stored USD budget as is. Provide this or budget_amount, not both.", "type": "number" }, "budget_optimization": { "description": "Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`). Only changeable before the campaign is live on the ad network; switching to `ad_campaign` requires budget_amount in the same request, and switching to `ad_group` clears the campaign budget.", "enum": [ "ad_campaign", "ad_group" ], "example": "ad_campaign", "type": "string" }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the campaign's full run (`lifetime`). Only changeable while the campaign is a draft; send budget_amount in the same request so the amount lands on the new type.", "enum": [ "daily", "lifetime" ], "example": "daily", "type": "string" }, "campaign_type": { "description": "Accepted only when it matches the campaign's current type, so a read can be sent back unchanged. The type is fixed at creation.", "enum": [ "standard", "search" ], "example": "standard", "type": "string" }, "desired_cost_per_result": { "description": "The cost per result, in USD, you want this campaign to achieve. A target only: it is not a bid, cost cap, or bid cap, and doesn't change how the campaign's ads bid. Ad groups set cost and bid caps with their own `desired_cost_per_result`. `null` clears it.", "type": [ "number", "null" ] }, "ends_at": { "description": "When the campaign stops delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "special_ad_categories": { "description": "Regulated categories the campaign falls under. Editable on any campaign, draft or launched; pass an empty array to clear.", "items": { "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "employment", "type": "string" }, "type": "array" }, "starts_at": { "description": "When the campaign starts delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "Set to active to launch a draft campaign (moderates and pushes it live). Live-campaign pause and resume use the pause and unpause actions.", "enum": [ "active" ], "example": "active", "type": "string" }, "title": { "description": "The name of the campaign.", "example": "Now hiring mobile detailers — Austin & Round Rock", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign updated" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}/duplicate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Creates copies of the campaign in `duplicating` status and returns them; each copy transitions to `draft` once duplication completes. Poll each returned campaign until it leaves `duplicating` — a copy that could not be completed is deleted and returns 404.", "operationId": "duplicateAdCampaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "Number of copies to create (1-10). Defaults to 1.", "example": 2, "type": "integer" }, "preserve_engagement": { "description": "Whether the copied ads keep the original posts' engagement (likes, comments, shares). Defaults to false.", "example": true, "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdCampaign" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "ad campaign duplication started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "a duplication is already running for this campaign" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Duplicate an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses an active ad campaign.", "operationId": "pauseAdCampaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign paused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Pause an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_campaigns/{id}/retry_payment": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "deprecated": true, "description": "Queues a background payment retry for the campaign's entire account, including other campaigns with failed payments. The returned campaign does not confirm payment success; read `delivery_status` and `issues` for the outcome. Deprecated: API versions 2026-09-22 and later return `410 Gone`; use `POST /accounts/:id/retry_ads_payment` instead.", "operationId": "retryAdCampaignPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "payment retry queued on earlier API versions" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "campaign is not in payment_failed status" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing campaign update permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "campaign payment retries are deprecated" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Retry a Failed Ad Campaign Payment", "tags": [ "Ad Campaigns" ], "x-whop-deprecated-since": "2026-09-22", "x-whop-removed-in": "2026-09-22", "x-whop-successor": "POST /accounts/{account_id}/retry_ads_payment" }, "x-whop-surface": "native" }, "/ad_campaigns/{id}/unpause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad campaign ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes a paused ad campaign. Requires an ads payment method on the account.", "operationId": "unpauseAdCampaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "ad campaign unpaused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Unpause an Ad Campaign", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "/ad_conversion_value_rules": { "get": { "description": "Lists the conversion value rules you can read.", "operationId": "listAdConversionValueRules", "parameters": [ { "description": "Only rules belonging to this account, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "paused" ], "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "tiktok", "meta", "google" ], "type": "string" } }, { "description": "Campaign, ad group, or ad ID. Return rules covering this item, its ancestors, or its descendants.", "in": "query", "name": "resource_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdConversionValueRule" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": null, "nullable": true, "type": "string" } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Rules" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List conversion value rules", "tags": [ "Ad Conversion Value Rules" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates one rule covering every selected target and event combination. Active rules cannot overlap for the same platform and event. Customer prices and Whop revenue stay unchanged.", "operationId": "createAdConversionValueRule", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Business that owns the rule.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "adjustment_type": { "enum": [ "fixed", "percentage" ], "example": "fixed", "type": "string" }, "events": { "description": "Events adjusted on every selected target. Every platform must support every selected event.", "items": { "properties": { "custom_name": { "description": "Exact custom event name. Required for custom events; `null` for standard events. Google does not support named custom events.", "nullable": true, "type": "string" }, "event_name": { "enum": [ "purchase", "subscribe", "start_trial", "lead", "complete_registration", "submit_application", "schedule", "contact", "view_content", "add_to_cart", "custom" ], "example": "lead", "type": "string" } }, "required": [ "event_name" ], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" }, "fixed_value": { "nullable": true, "properties": { "amount": { "description": "Decimal amount with at most 2 decimal places. Fixed values must be greater than 0 and at most 99999999.99.", "example": "60.00", "pattern": "^-?(?:[0-9]+(?:\\.[0-9]{1,2})?|\\.[0-9]{1,2})$", "type": "string" }, "currency": { "example": "usd", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "percentage_change": { "description": "Signed percent change from negative 100 to 10000. The sent value cannot go below zero.", "maximum": 10000, "minimum": -100, "multipleOf": 0.01, "nullable": true, "type": "number" }, "replace_rule_ids": { "description": "Exact IDs of active rules whose overlapping selections will be replaced. Other selections keep their values; remaining selections may split into separate rules. Broader rules remain as fallbacks for other items. Rules left with no selections are paused. Stale or incomplete conflict selections fail.", "items": { "type": "string" }, "maxItems": 1000, "type": "array", "uniqueItems": true }, "status": { "description": "Initial rule status. Defaults to active.", "enum": [ "active", "paused" ], "example": "active", "type": "string" }, "targets": { "description": "Targets sharing one scope. Every selected event applies to every target. At most 500 target and event combinations.", "items": { "properties": { "platform": { "enum": [ "tiktok", "meta", "google" ], "example": "meta", "type": "string" }, "resource_id": { "description": "Campaign, ad group, or ad ID. Null for a business target.", "nullable": true, "type": "string" }, "scope": { "enum": [ "business", "campaign", "ad_group", "ad" ], "example": "business", "type": "string" } }, "required": [ "scope", "platform" ], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "account_id", "adjustment_type", "targets", "events" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdConversionValueRule" } } }, "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Create a conversion value rule", "tags": [ "Ad Conversion Value Rules" ] }, "x-whop-surface": "native" }, "/ad_conversion_value_rules/{id}": { "delete": { "description": "Deletes a rule and deactivates all its coverage. The rule's stored settings are preserved.", "operationId": "deleteAdConversionValueRule", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "adcvr_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "Deleted" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Delete a conversion value rule", "tags": [ "Ad Conversion Value Rules" ] }, "get": { "description": "Retrieves a conversion value rule with its targets, events, and value adjustment.", "operationId": "retrieveAdConversionValueRule", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdConversionValueRule" } } }, "description": "Rule" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve a conversion value rule", "tags": [ "Ad Conversion Value Rules" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Conversion value rule ID, prefixed `adcvr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Edits a rule without changing its status. Supplied `targets` or `events` replace that selection in full, and omitted fields stay unchanged. All changes succeed or fail together.", "operationId": "updateAdConversionValueRule", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "adjustment_type": { "enum": [ "fixed", "percentage" ], "example": "fixed", "type": "string" }, "events": { "description": "Events adjusted on every selected target. Every platform must support every selected event.", "items": { "properties": { "custom_name": { "description": "Exact custom event name. Required for custom events; `null` for standard events. Google does not support named custom events.", "nullable": true, "type": "string" }, "event_name": { "enum": [ "purchase", "subscribe", "start_trial", "lead", "complete_registration", "submit_application", "schedule", "contact", "view_content", "add_to_cart", "custom" ], "example": "lead", "type": "string" } }, "required": [ "event_name" ], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" }, "fixed_value": { "nullable": true, "properties": { "amount": { "description": "Decimal amount with at most 2 decimal places. Fixed values must be greater than 0 and at most 99999999.99.", "example": "60.00", "pattern": "^-?(?:[0-9]+(?:\\.[0-9]{1,2})?|\\.[0-9]{1,2})$", "type": "string" }, "currency": { "example": "usd", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "percentage_change": { "description": "Signed percent change from negative 100 to 10000. The sent value cannot go below zero.", "maximum": 10000, "minimum": -100, "multipleOf": 0.01, "nullable": true, "type": "number" }, "replace_rule_ids": { "description": "Exact IDs of active rules whose overlapping selections will be replaced. Other selections keep their values; remaining selections may split into separate rules. Broader rules remain as fallbacks for other items. Rules left with no selections are paused. Stale or incomplete conflict selections fail.", "items": { "type": "string" }, "maxItems": 1000, "type": "array", "uniqueItems": true }, "targets": { "description": "Targets sharing one scope. Every selected event applies to every target. At most 500 target and event combinations.", "items": { "properties": { "platform": { "enum": [ "tiktok", "meta", "google" ], "example": "meta", "type": "string" }, "resource_id": { "description": "Campaign, ad group, or ad ID. Null for a business target.", "nullable": true, "type": "string" }, "scope": { "enum": [ "business", "campaign", "ad_group", "ad" ], "example": "business", "type": "string" } }, "required": [ "scope", "platform" ], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdConversionValueRule" } } }, "description": "Updated" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update a conversion value rule", "tags": [ "Ad Conversion Value Rules" ] }, "x-whop-surface": "native" }, "/ad_conversion_value_rules/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Conversion value rule ID, prefixed `adcvr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses the rule across all selected targets and events.", "operationId": "pauseAdConversionValueRule", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdConversionValueRule" } } }, "description": "Rule" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Pause a conversion value rule", "tags": [ "Ad Conversion Value Rules" ] }, "x-whop-surface": "native" }, "/ad_conversion_value_rules/{id}/unpause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Conversion value rule ID, prefixed `adcvr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes the rule and automatically replaces overlapping selections in the same transaction. Other selections keep their values, and broader rules remain as defaults. Rules with no remaining selections are paused. Resuming an already-active rule makes no changes.", "operationId": "unpauseAdConversionValueRule", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdConversionValueRule" } } }, "description": "Rule" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Unpause a conversion value rule", "tags": [ "Ad Conversion Value Rules" ] }, "x-whop-surface": "native" }, "/ad_groups": { "get": { "description": "Lists ad groups for the account, newest first.", "operationId": "listAdGroups", "parameters": [ { "description": "Account whose ad groups to list. Defaults to the authenticated account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to ad groups in this campaign.", "in": "query", "name": "ad_campaign_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to ad groups in these campaigns (max 100). Repeat the parameter for each id (ad_campaign_ids=a&ad_campaign_ids=b).", "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "items": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Filter to ad groups with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "paused", "rejected", "duplicating" ], "type": "string" } }, { "description": "Filter ad groups by a title or ID substring.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by. Defaults to created_at. Stat columns (spend, impressions, …) rank over the stats_from/stats_to window across the whole list, not just the current page. results, cost_per_result and return_on_ad_spend rank by the same Whop pixel-attributed values the response reports, and link_clicks by the same Whop pixel page views.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "updated_at", "spend", "impressions", "reach", "clicks", "link_clicks", "unique_clicks", "frequency", "click_through_rate", "results", "cost_per_mille", "cost_per_click", "cost_per_result", "return_on_ad_spend" ], "type": "string" } }, { "description": "The sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return ad groups created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return ad groups created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Start of the stats window. Defaults to all-time.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window. Defaults to now.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare stats_from/stats_to dates resolve to day boundaries on this clock. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdGroup" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "ad groups listed" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List Ad Groups", "tags": [ "Ad Groups" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an ad group (ad set) in a campaign.", "operationId": "createAdGroup", "parameters": [ { "$ref": "#/components/parameters/AdsPlatform" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ad_campaign_id": { "description": "The ad campaign to create the ad group in, prefixed `adcamp_`.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "audiences": { "$ref": "#/components/schemas/AdGroupAudiencesBody", "description": "Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic." }, "bid_type": { "description": "How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.", "enum": [ "minimum_cost", "average_target", "maximum_target" ], "example": "average_target", "type": "string" }, "budget_amount": { "description": "This ad group's budget in USD, which is what it is stored and billed in. Omit when the budget is set on the campaign instead.", "example": 40.0, "type": "number" }, "budget_amount_local": { "description": "This ad group's budget stated in the account's ads reporting currency (`budget_currency` on the response) instead of USD. Converted to USD at the current exchange rate and stored as budget_amount; on an update, an amount equal to the current budget_amount_local keeps the stored USD budget as is. Provide this or budget_amount, not both.", "type": "number" }, "budget_type": { "description": "Whether budget_amount is spent per day (`daily`) or over the ad group's full run (`lifetime`).", "enum": [ "daily", "lifetime" ], "example": "daily", "type": "string" }, "conversion_event": { "$ref": "#/components/schemas/ConversionEvent" }, "conversion_location": { "description": "Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission. The lead form itself is set on the ad.", "enum": [ "website", "profile", "instagram_and_facebook", "instagram_profile", "messaging", "on_ad", "instant_forms", "instant_forms_and_messenger", "website_and_instant_forms" ], "example": "website", "type": "string" }, "delivery_schedule": { "additionalProperties": false, "description": "Hours the ad group delivers in each week, keyed by day. Each window runs from `start` to `end` on the hour, with `24:00` for midnight, and a day's windows can't overlap or touch. A day that's empty or left out doesn't deliver. Replaces the whole schedule; `null` delivers at every hour. Some platforms need a lifetime `budget_type` for a schedule, on the ad group or on its campaign when the campaign holds the budget.", "example": { "saturday": [ { "end": "24:00", "start": "00:00" } ], "sunday": [ { "end": "24:00", "start": "00:00" } ], "thursday": [ { "end": "14:00", "start": "05:00" } ], "tuesday": [ { "end": "12:00", "start": "10:00" }, { "end": "20:00", "start": "16:00" } ] }, "properties": { "friday": { "description": "Windows the ad group delivers in on Friday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "monday": { "description": "Windows the ad group delivers in on Monday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "saturday": { "description": "Windows the ad group delivers in on Saturday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "example": "24:00", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "00:00", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "sunday": { "description": "Windows the ad group delivers in on Sunday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "example": "24:00", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "00:00", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "thursday": { "description": "Windows the ad group delivers in on Thursday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "example": "14:00", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "05:00", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "tuesday": { "description": "Windows the ad group delivers in on Tuesday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "example": "20:00", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "16:00", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "wednesday": { "description": "Windows the ad group delivers in on Wednesday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" } }, "type": [ "object", "null" ] }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographicsBody", "description": "Age, gender, and automatic-audience targeting." }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`).", "example": 35.0, "type": "number" }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargetingBody", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories. Send the complete intended state — a section you omit is cleared." }, "devices": { "$ref": "#/components/schemas/AdGroupDevicesBody", "description": "Device platforms and operating systems to target." }, "dynamic_creative": { "description": "Whether the ad platform automatically mixes and matches this ad group's creatives and copy to find the best-performing combinations. Meta has deprecated it and rejects `true`; ad groups already using it keep it, and it can't be changed afterward.", "example": false, "type": "boolean" }, "ends_at": { "description": "When the ad group stops delivering, as an ISO 8601 timestamp. Omit to run until paused.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "frequency_cap": { "description": "Cap on how often one person sees ads from this ad group. Only available when the ad group optimizes for reach or ThruPlay. Under a campaign budget every ad group must use the same cap, which applies across the whole campaign, and only with the awareness objective (reach or ThruPlay ad groups) or engagement (ThruPlay). Fixed once the campaign launches; `null` clears it before then.", "properties": { "maximum_impressions": { "description": "Most times one person can be shown ads from this ad group within the window.", "example": 3, "type": "integer" }, "per_days": { "description": "Length of the rolling window, in days.", "example": 7, "type": "integer" } }, "type": [ "object", "null" ] }, "keywords": { "description": "Search terms the ad group's ads can show for, and terms they never show for. Only search campaigns take keywords, and each of their ad groups needs at least one before launch. Replaces the stored list; omit to keep it.", "items": { "properties": { "match_type": { "description": "How closely a search has to match: `broad` also reaches related searches, `phrase` needs the meaning of the phrase, and `exact` needs the same meaning as the term. Defaults to `broad`.", "enum": [ "broad", "phrase", "exact" ], "example": "broad", "type": "string" }, "negative": { "description": "Set to `true` to keep the ads from showing for this term instead. Defaults to `false`.", "type": "boolean" }, "text": { "description": "The search term, up to 80 characters and 10 words. Symbols such as ! @ % , * = ^ ; ~ | < > ? ( ) { } and quotes aren't allowed: set the match with match_type instead.", "type": "string" } }, "required": [ "text" ], "type": "object" }, "type": "array" }, "languages": { "description": "Languages to target, as ISO 639 codes such as `en` or `es`. Empty or omitted targets all languages.", "items": { "example": "en", "type": "string" }, "type": "array" }, "message_apps": { "description": "Apps the conversation opens in. Required when setting `conversion_location` to `messaging`, and rejected unless the ad group's conversion location is `messaging`.", "items": { "enum": [ "messenger", "instagram", "whatsapp" ], "example": "whatsapp", "type": "string" }, "type": "array" }, "minimum_daily_spend": { "description": "Minimum the ad group tries to spend each day.", "example": 20.0, "type": "number" }, "optimization_goal": { "description": "The result the ad group's delivery is optimized to get the most of.", "enum": [ "conversions", "link_clicks", "landing_page_views", "reach", "impressions", "engagement", "conversations", "video_views", "two_second_views", "page_likes", "social_profile", "ad_recall_lift", "event_responses", "reminders_set", "lead_generation", "quality_lead", "value", "profile_and_page_engagement" ], "example": "reach", "type": "string" }, "placements": { "anyOf": [ { "enum": [ "automatic" ], "example": "automatic", "type": "string" }, { "items": { "properties": { "platform": { "description": "Platform the ads run on.", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads", "whatsapp" ], "example": "instagram", "type": "string" }, "positions": { "description": "Positions to target within the platform, such as `feed` or `story`. Omit to target all of the platform's positions.", "items": { "example": "stream", "type": "string" }, "type": "array" } }, "required": [ "platform" ], "type": "object" }, "type": "array" } ], "description": "`automatic` to let the ad platform choose placements, or the list of platforms and positions to target. Omit a platform's positions to target all of them.\n\nValid positions per platform:\n\n- `facebook`: `feed`, `right_hand_column`, `marketplace`, `search`, `profile_feed`, `notification`, `story`, `instream_video`, `facebook_reels`, `facebook_reels_overlay`, `biz_disco_feed`\n- `instagram`: `stream`, `story`, `explore`, `explore_home`, `reels`, `profile_feed`, `profile_reels`, `ig_search`\n- `messenger`: `story`\n- `audience_network`: `classic`, `rewarded_video`\n- `threads`: `threads_stream`\n- `whatsapp`: `status`" }, "regions": { "$ref": "#/components/schemas/AdGroupRegionsBody", "description": "Locations to target and exclude." }, "starts_at": { "description": "When the ad group starts delivering, as an ISO 8601 timestamp. Omit to start as soon as it's active.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "Initial status (default: `active`).", "enum": [ "active", "paused" ], "example": "paused", "type": "string" }, "title": { "description": "The display name of the ad group.", "example": "North America — brand prospecting", "type": "string" } }, "required": [ "ad_campaign_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group created" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad campaign not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Create an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/estimate_reach": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Estimates how many people a draft targeting spec can reach, before an ad group is created. The body takes the same targeting fields as creating an ad group, and nothing is persisted.", "operationId": "estimateAdGroupReach", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account to estimate on behalf of. Defaults to the authenticated account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "audiences": { "$ref": "#/components/schemas/AdGroupAudiencesBody", "description": "Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic." }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographicsBody", "description": "Age, gender, and automatic-audience targeting." }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargetingBody", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. At most 100 entries per section." }, "devices": { "$ref": "#/components/schemas/AdGroupDevicesBody", "description": "Device platforms and operating systems to target." }, "languages": { "description": "Languages to target, as ISO 639 codes such as `en` or `es`. Empty or omitted targets all languages.", "items": { "example": "en", "type": "string" }, "type": "array" }, "platform": { "description": "The ad network the estimate runs on.", "enum": [ "meta" ], "example": "meta", "type": "string" }, "regions": { "$ref": "#/components/schemas/AdGroupRegionsBody", "description": "Locations to target and exclude." } }, "required": [ "platform" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachEstimate" } } }, "description": "reach estimated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "no ad account is available for estimates" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "key lacks the required scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Estimate Ad Group Reach", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/targeting_options": { "get": { "description": "Searches the ad platform's targeting taxonomy for options to target an ad group with. Each result comes back in the exact shape the ad-group body accepts for its `type`, so it can be used in `detailed_targeting`, `regions`, or `languages` as-is.", "operationId": "searchAdGroupTargetingOptions", "parameters": [ { "description": "Account to search on behalf of. Defaults to the authenticated account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The ad network whose targeting taxonomy to search.", "in": "query", "name": "platform", "required": true, "schema": { "enum": [ "meta" ], "type": "string" } }, { "description": "The search term. Blank browses the small fixed lists (behaviors, browse demographic categories, and languages); interests, work employers, job titles, schools, majors, and locations return nothing without one.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Kinds of targeting options to search. Defaults to all of them.", "explode": true, "in": "query", "name": "types", "required": false, "schema": { "items": { "enum": [ "interests", "behaviors", "life_events", "industries", "income", "family_statuses", "work_employers", "work_positions", "education_schools", "education_majors", "languages", "locations" ], "example": "interests", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Narrow location results to these kinds of places. Only applies when `types` includes `locations`.", "explode": true, "in": "query", "name": "location_types", "required": false, "schema": { "items": { "enum": [ "country", "region", "city", "zip", "neighborhood", "subcity", "medium_geo_area" ], "example": "country", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Narrow location results to one country, as an ISO 3166-1 code such as `US`. Only applies when `types` includes `locations`.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "Maximum number of results per requested type.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 500, "type": "integer" } }, { "description": "The campaign's declared special ad categories. Under `housing`, `employment`, or `financial_products` the ad platform allows interests only, drawn from a short approved list, so results are narrowed to what such a campaign can launch with and other kinds return nothing. Blank `query` browses that approved list instead of the usual fixed lists.", "explode": true, "in": "query", "name": "special_ad_categories", "required": false, "schema": { "items": { "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "housing", "type": "string" }, "type": "array" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TargetingOption" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "types narrows the search and accepts a comma-separated list" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "location filters need locations in types" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "key lacks the required scope" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Search Targeting Options", "tags": [ "Ad Groups" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/ad_groups/{id}": { "delete": { "description": "Deletes an ad group, removing it from the ad platform so it stops delivering.", "operationId": "deleteAdGroup", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted ad group.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "ad group deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad group not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Delete an Ad Group", "tags": [ "Ad Groups" ] }, "get": { "description": "Retrieves an ad group, with performance stats for the window set by `stats_from` and `stats_to`.", "operationId": "retrieveAdGroup", "parameters": [ { "description": "Start of the stats window.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone the stats window is interpreted in. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad group not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve an Ad Group", "tags": [ "Ad Groups" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad group ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an ad group's editable fields. Only the keys you send are changed.", "operationId": "updateAdGroup", "parameters": [ { "$ref": "#/components/parameters/AdsPlatform" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "audiences": { "$ref": "#/components/schemas/AdGroupAudiencesBody", "description": "Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic." }, "bid_type": { "description": "How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.", "enum": [ "minimum_cost", "average_target", "maximum_target" ], "example": "average_target", "type": "string" }, "budget_amount": { "description": "This ad group's budget in USD, which is what it is stored and billed in. Omit when the budget is set on the campaign instead.", "example": 40.0, "type": "number" }, "budget_amount_local": { "description": "This ad group's budget stated in the account's ads reporting currency (`budget_currency` on the response) instead of USD. Converted to USD at the current exchange rate and stored as budget_amount; on an update, an amount equal to the current budget_amount_local keeps the stored USD budget as is. Provide this or budget_amount, not both.", "type": "number" }, "budget_type": { "description": "Whether budget_amount is spent per day (`daily`) or over the ad group's full run (`lifetime`).", "enum": [ "daily", "lifetime" ], "example": "daily", "type": "string" }, "conversion_event": { "$ref": "#/components/schemas/ConversionEvent" }, "conversion_location": { "description": "Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission. The lead form itself is set on the ad.", "enum": [ "website", "profile", "instagram_and_facebook", "instagram_profile", "messaging", "on_ad", "instant_forms", "instant_forms_and_messenger", "website_and_instant_forms" ], "example": "website", "type": "string" }, "delivery_schedule": { "additionalProperties": false, "description": "Hours the ad group delivers in each week, keyed by day. Each window runs from `start` to `end` on the hour, with `24:00` for midnight, and a day's windows can't overlap or touch. A day that's empty or left out doesn't deliver. Replaces the whole schedule; `null` delivers at every hour. Some platforms need a lifetime `budget_type` for a schedule, on the ad group or on its campaign when the campaign holds the budget.", "example": { "saturday": [ { "end": "24:00", "start": "00:00" } ], "sunday": [ { "end": "24:00", "start": "00:00" } ], "thursday": [ { "end": "14:00", "start": "05:00" } ], "tuesday": [ { "end": "12:00", "start": "10:00" }, { "end": "20:00", "start": "16:00" } ] }, "properties": { "friday": { "description": "Windows the ad group delivers in on Friday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "monday": { "description": "Windows the ad group delivers in on Monday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "saturday": { "description": "Windows the ad group delivers in on Saturday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "example": "24:00", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "00:00", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "sunday": { "description": "Windows the ad group delivers in on Sunday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "example": "24:00", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "00:00", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "thursday": { "description": "Windows the ad group delivers in on Thursday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "example": "14:00", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "05:00", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "tuesday": { "description": "Windows the ad group delivers in on Tuesday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "example": "20:00", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "example": "16:00", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" }, "wednesday": { "description": "Windows the ad group delivers in on Wednesday.", "items": { "additionalProperties": false, "properties": { "end": { "description": "When delivery stops, as a 24-hour `HH:00` time up to `24:00` for midnight. Later than `start`.", "pattern": "^(0[1-9]|1[0-9]|2[0-4]):00$", "type": "string" }, "start": { "description": "When delivery starts, as a 24-hour `HH:00` time from `00:00` to `23:00`.", "pattern": "^([01][0-9]|2[0-3]):00$", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "type": "array" } }, "type": [ "object", "null" ] }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographicsBody", "description": "Age, gender, and automatic-audience targeting." }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`).", "example": 35.0, "type": "number" }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargetingBody", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories. Send the complete intended state — a section you omit is cleared." }, "devices": { "$ref": "#/components/schemas/AdGroupDevicesBody", "description": "Device platforms and operating systems to target." }, "ends_at": { "description": "When the ad group stops delivering, as an ISO 8601 timestamp. Omit to run until paused.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "frequency_cap": { "description": "Cap on how often one person sees ads from this ad group. Only available when the ad group optimizes for reach or ThruPlay. Under a campaign budget every ad group must use the same cap, which applies across the whole campaign, and only with the awareness objective (reach or ThruPlay ad groups) or engagement (ThruPlay). Fixed once the campaign launches; `null` clears it before then.", "properties": { "maximum_impressions": { "description": "Most times one person can be shown ads from this ad group within the window.", "example": 3, "type": "integer" }, "per_days": { "description": "Length of the rolling window, in days.", "example": 7, "type": "integer" } }, "type": [ "object", "null" ] }, "keywords": { "description": "Search terms the ad group's ads can show for, and terms they never show for. Only search campaigns take keywords, and each of their ad groups needs at least one before launch. Replaces the stored list; omit to keep it.", "items": { "properties": { "match_type": { "description": "How closely a search has to match: `broad` also reaches related searches, `phrase` needs the meaning of the phrase, and `exact` needs the same meaning as the term. Defaults to `broad`.", "enum": [ "broad", "phrase", "exact" ], "example": "broad", "type": "string" }, "negative": { "description": "Set to `true` to keep the ads from showing for this term instead. Defaults to `false`.", "type": "boolean" }, "text": { "description": "The search term, up to 80 characters and 10 words. Symbols such as ! @ % , * = ^ ; ~ | < > ? ( ) { } and quotes aren't allowed: set the match with match_type instead.", "type": "string" } }, "required": [ "text" ], "type": "object" }, "type": "array" }, "languages": { "description": "Languages to target, as ISO 639 codes such as `en` or `es`. Empty or omitted targets all languages.", "items": { "example": "en", "type": "string" }, "type": "array" }, "message_apps": { "description": "Apps the conversation opens in. Required when setting `conversion_location` to `messaging`, and rejected unless the ad group's conversion location is `messaging`.", "items": { "enum": [ "messenger", "instagram", "whatsapp" ], "example": "whatsapp", "type": "string" }, "type": "array" }, "minimum_daily_spend": { "description": "Minimum the ad group tries to spend each day.", "example": 20.0, "type": "number" }, "optimization_goal": { "description": "The result the ad group's delivery is optimized to get the most of.", "enum": [ "conversions", "link_clicks", "landing_page_views", "reach", "impressions", "engagement", "conversations", "video_views", "two_second_views", "page_likes", "social_profile", "ad_recall_lift", "event_responses", "reminders_set", "lead_generation", "quality_lead", "value", "profile_and_page_engagement" ], "example": "reach", "type": "string" }, "placements": { "anyOf": [ { "enum": [ "automatic" ], "example": "automatic", "type": "string" }, { "items": { "properties": { "platform": { "description": "Platform the ads run on.", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads", "whatsapp" ], "example": "instagram", "type": "string" }, "positions": { "description": "Positions to target within the platform, such as `feed` or `story`. Omit to target all of the platform's positions.", "items": { "example": "stream", "type": "string" }, "type": "array" } }, "required": [ "platform" ], "type": "object" }, "type": "array" } ], "description": "`automatic` to let the ad platform choose placements, or the list of platforms and positions to target. Omit a platform's positions to target all of them.\n\nValid positions per platform:\n\n- `facebook`: `feed`, `right_hand_column`, `marketplace`, `search`, `profile_feed`, `notification`, `story`, `instream_video`, `facebook_reels`, `facebook_reels_overlay`, `biz_disco_feed`\n- `instagram`: `stream`, `story`, `explore`, `explore_home`, `reels`, `profile_feed`, `profile_reels`, `ig_search`\n- `messenger`: `story`\n- `audience_network`: `classic`, `rewarded_video`\n- `threads`: `threads_stream`\n- `whatsapp`: `status`" }, "regions": { "$ref": "#/components/schemas/AdGroupRegionsBody", "description": "Locations to target and exclude." }, "starts_at": { "description": "When the ad group starts delivering, as an ISO 8601 timestamp. Omit to start as soon as it's active.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "status": { "description": "Initial status (default: `active`).", "enum": [ "active", "paused" ], "example": "paused", "type": "string" }, "title": { "description": "The display name of the ad group.", "example": "North America — brand prospecting", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "a delivery schedule on an ad group without a lifetime budget" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/{id}/duplicate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad group ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Starts copying an ad group and returns the copies in `duplicating` status. Poll each returned ad group until it leaves `duplicating`: it then takes the source's `active` or `paused` status, or, if the copy could not be completed, is deleted and returns 404.", "operationId": "duplicateAdGroup", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "Number of copies to create (1-10). Defaults to 1.", "example": 2, "type": "integer" }, "preserve_engagement": { "description": "Whether the copied ads keep the original posts' engagement (likes, comments, shares). Defaults to false.", "example": true, "type": "boolean" }, "target_ad_campaign_id": { "description": "Campaign to duplicate into. Must belong to the same account and be compatible with the ad group's targeting and goals. Defaults to the ad group's own campaign.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdGroup" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "ad group duplication started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "a duplication is already running for this ad group" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad group not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Duplicate an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad group ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses delivery of an ad group.", "operationId": "pauseAdGroup", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group paused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Pause an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_groups/{id}/unpause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad group ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes delivery of a paused ad group.", "operationId": "unpauseAdGroup", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroup" } } }, "description": "ad group unpaused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Unpause an Ad Group", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "/ad_pixels": { "get": { "description": "List the pixels you added for businesses whose campaigns you claimed.", "operationId": "listAdPixels", "parameters": [ { "description": "Only return the pixels for this business, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AdPixel" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Ad pixels" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearerAuth": [ "ad_pixel:manage" ] } ], "summary": "List ad pixels", "tags": [ "Ad Pixels" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Add your pixel for a business whose campaigns you claimed. Whop checks the access token with the ad platform, then sends the pixel the conversions credited to your claimed campaigns for that business. Each business takes one pixel per ad platform, and each pixel can serve one business. On Google, the pixel is your Google Ads account, which can serve several businesses, and Whop creates its conversion actions there with your service account key.", "operationId": "createAdPixel", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "access_token": { "description": "A credential that can send events to the pixel on the ad platform: a Meta Conversions API access token, a TikTok Events API access token, or for `google`, the JSON key of a Google Cloud service account. The service account needs Standard access to the Google Ads account, and its project needs the Google Ads API and the Data Manager API turned on and Explorer access or higher to the Google Ads API. Use a service account made only for Whop, with no roles in its project. Whop never returns it.", "example": "new-token", "type": "string", "writeOnly": true }, "account_id": { "description": "The business whose claimed campaigns send conversions to this pixel, prefixed `biz_`. You must have claimed at least one of its campaigns.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "external_id": { "description": "The pixel's ID on the ad platform: the Meta pixel or dataset ID, the TikTok pixel code, or the Google Ads customer ID.", "example": "998877665544", "type": "string" }, "platform": { "description": "The ad platform the pixel belongs to.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" } }, "required": [ "account_id", "platform", "external_id", "access_token" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdPixel" } } }, "description": "Created" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "409": { "description": "Conflict" } }, "security": [ { "bearerAuth": [ "ad_pixel:manage" ] } ], "summary": "Create an ad pixel", "tags": [ "Ad Pixels" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/ad_pixels/{id}": { "delete": { "description": "Remove the pixel and its access token. Whop stops sending it conversions.", "operationId": "deleteAdPixel", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "adpx_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "Deleted" } }, "security": [ { "bearerAuth": [ "ad_pixel:manage" ] } ], "summary": "Delete an ad pixel", "tags": [ "Ad Pixels" ], "x-whop-credentials": [ "oauth_token" ] }, "get": { "operationId": "retrieveAdPixel", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdPixel" } } }, "description": "Ad pixel" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [ "ad_pixel:manage" ] } ], "summary": "Retrieve an ad pixel", "tags": [ "Ad Pixels" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Ad pixel ID, prefixed `adpx_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Replace the pixel's access token. Whop checks the new token with the ad platform and resumes deliveries to an `errored` pixel.", "operationId": "updateAdPixel", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "access_token": { "description": "A credential that can send events to the pixel on the ad platform: a Meta Conversions API access token, a TikTok Events API access token, or for `google`, the JSON key of a Google Cloud service account. The service account needs Standard access to the Google Ads account, and its project needs the Google Ads API and the Data Manager API turned on and Explorer access or higher to the Google Ads API. Use a service account made only for Whop, with no roles in its project. Whop never returns it.", "example": "new-token", "type": "string", "writeOnly": true } }, "required": [ "access_token" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdPixel" } } }, "description": "Updated" }, "400": { "description": "Bad request" } }, "security": [ { "bearerAuth": [ "ad_pixel:manage" ] } ], "summary": "Update an ad pixel", "tags": [ "Ad Pixels" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/ad_stats": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Records a runner's stats for one of their ads in one hour, and pays them for the spend. Send the ad's totals so far for an hour that started in the last 24 hours; they replace what the ad held for that hour, and its ad group's and campaign's hours are rebuilt from their ads. The spend can go up but never down. Reporting on a campaign starts with the hour of its first recorded report; earlier hours are refused. Spend over what is left of a budget (the runner's share of the day, the campaign's daily budget or the ad group's budget) is refused with the most the ad can record. Takes the runner's Whop session or a user OAuth token with `ad_campaign:update`. A token without that scope gets a 403, and anyone not holding the ad's campaign gets a 404.", "operationId": "createAdStats", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ad_id": { "description": "The ad's ID, prefixed `ad_`: the campaign's ad or the runner's copy of it.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "clicks": { "description": "The ad's clicks in the hour so far, at most `impressions`. Zero when left out.", "example": 150, "type": [ "integer", "string" ] }, "hour_started_at": { "description": "Start of the hour, on the hour, within the last 24 hours.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "impressions": { "description": "The ad's impressions in the hour so far. Zero when left out.", "example": 6000, "type": [ "integer", "string" ] }, "spend": { "description": "USD spent on the ad in the hour so far, to the cent.", "example": 75.5, "type": [ "number", "string" ] } }, "required": [ "ad_id", "hour_started_at", "spend" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdStat" } } }, "description": "stats recorded" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "spend over the budget" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "a token without ad_campaign:update" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "an ad the runner doesn't report on" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Create ad stats", "tags": [ "Ads" ], "x-whop-credentials": [ "oauth_token" ], "x-whop-docs": "gated", "x-whop-docs-groups": [ "oasp" ] }, "x-whop-surface": "native" }, "/ads": { "get": { "description": "Lists the ads for an account, with stats over the requested window.", "operationId": "listAds", "parameters": [ { "description": "The account the ads belong to. Defaults to the account-scoped key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return ads in this ad campaign.", "in": "query", "name": "ad_campaign_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return ads in these ad campaigns (max 100). Repeat the parameter for each id (ad_campaign_ids=a&ad_campaign_ids=b).", "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "items": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return ads in this ad group.", "in": "query", "name": "ad_group_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return ads in these ad groups (max 100). Repeat the parameter for each id (ad_group_ids=a&ad_group_ids=b).", "in": "query", "name": "ad_group_ids", "required": false, "schema": { "items": { "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return ads with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "paused", "in_review", "rejected" ], "type": "string" } }, { "description": "Filter ads by a title or ID substring.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by. Defaults to created_at. Stat columns (spend, impressions, …) rank over the stats_from/stats_to window across the whole list, not just the current page. results, cost_per_result and return_on_ad_spend rank by the same Whop pixel-attributed values the response reports, and link_clicks by the same Whop pixel page views.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "updated_at", "spend", "impressions", "reach", "clicks", "link_clicks", "unique_clicks", "frequency", "click_through_rate", "results", "cost_per_mille", "cost_per_click", "cost_per_result", "return_on_ad_spend" ], "type": "string" } }, { "description": "The sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return ads created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return ads created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Start of the stats window. Defaults to all-time.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window. Defaults to now.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare stats_from/stats_to dates resolve to day boundaries on this clock. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "ads listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id missing and unresolvable" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "List Ads", "tags": [ "Ads" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an ad in an ad group. Any campaign status other than `draft` launches the campaign, which requires an ads payment method on the account.", "operationId": "createAd", "parameters": [ { "$ref": "#/components/parameters/AdsPlatform" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ad_group": { "description": "An inline ad group to create (same shape as POST /ad_groups, including ad_campaign_id). Creates the ad group and the ad together. Provide this OR ad_group_id.", "example": { "ad_campaign_id": "adcamp_xxxxxxxxxxxxxx", "budget_amount": 60.0, "budget_type": "daily", "optimization_goal": "conversions", "title": "Austin — ceramic coating buyers" }, "type": "object" }, "ad_group_id": { "description": "The existing ad group to create the ad in. Provide this OR ad_group, not both.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "call_to_action": { "description": "The call-to-action button shown on the ad.", "enum": [ "apply_now", "book_now", "call_now", "contact_us", "donate_now", "download", "get_directions", "get_offer", "get_quote", "learn_more", "listen_now", "message_page", "no_button", "open_link", "order_now", "request_time", "see_details", "see_menu", "see_more", "send_updates", "shop_now", "sign_up", "subscribe", "visit_site", "watch_more" ], "example": "message_page", "type": "string" }, "creatives": { "description": "The ad's creative assets. Each entry is an uploaded file id with an optional format; omit format for the original asset. Entries with no format become a carousel's ordered cards, sharing the ad's copy — 2-10 of them on Meta, while TikTok runs even a single image as a one-card carousel.", "items": { "properties": { "crop": { "description": "The saved crop window for this creative, in source image pixels. Omit it for the original asset or for a format that has not been cropped.", "properties": { "height": { "example": 1000, "type": "number" }, "width": { "example": 1000, "type": "number" }, "x": { "example": 40, "type": "number" }, "y": { "example": 0, "type": "number" } }, "type": "object" }, "format": { "enum": [ "square", "vertical", "horizontal" ], "example": "square", "type": "string" }, "id": { "description": "Uploaded file ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "language": { "description": "ISO 639 code of the language this image or video is shown for, such as `es`. Required on every entry of an ad with `translations`, where the ad's own creative uses `translations.source_language`. Another language's creative is the same type as the ad's own, with no format. Leave it out on an ad without translations.", "type": "string" } }, "type": "object" }, "type": "array" }, "descriptions": { "description": "The description shown on the ad. Entries without a language are the ad's own copy; add one entry per other language on a Meta ad with `translations`.", "items": { "properties": { "language": { "description": "ISO 639 code of the language this text is in, such as `es`. Required on every entry of an ad with `translations`, where the ad's own copy uses `translations.source_language`. Leave it out on an ad without translations.", "nullable": true, "type": "string" }, "text": { "description": "The text shown to viewers.", "example": "Two-stage paint correction included", "type": "string" } }, "required": [ "text" ], "type": "object" }, "type": "array" }, "existing_post_id": { "description": "Promote a post you already published instead of uploading creatives — a Facebook post or Instagram media id. Mutually exclusive with creatives. Pair with post_source.", "example": "1784512345678901", "type": "string" }, "external_accounts": { "description": "The external accounts the ad runs under — a connected Facebook page and, optionally, an Instagram profile.", "items": { "properties": { "id": { "description": "External account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "headlines": { "description": "The headline shown on the ad. Entries without a language are the ad's own copy; add one entry per other language on a Meta ad with `translations`.", "items": { "properties": { "language": { "description": "ISO 639 code of the language this text is in, such as `es`. Required on every entry of an ad with `translations`, where the ad's own copy uses `translations.source_language`. Leave it out on an ad without translations.", "nullable": true, "type": "string" }, "text": { "description": "The text shown to viewers.", "example": "Showroom shine, guaranteed", "type": "string" } }, "required": [ "text" ], "type": "object" }, "type": "array" }, "lead_form": { "description": "Instant lead form for the ad. Only allowed when the ad group's conversion_location is an instant-form destination (instant_forms, instant_forms_and_messenger, website_and_instant_forms). Mutually exclusive with lead_form_id.", "properties": { "completion": { "description": "Optional completion screen shown after submission. Its button needs a destination: url for button_type website (the default), phone_number for call, file_url for download.", "properties": { "button_text": { "example": "See our work", "type": "string" }, "button_type": { "enum": [ "website", "call", "download" ], "example": "website", "type": "string" }, "description": { "example": "We book coatings two days out, so pick a slot when we ring.", "type": "string" }, "file_url": { "type": "string" }, "headline": { "example": "Thanks — we will call you today", "type": "string" }, "phone_number": { "type": "string" }, "url": { "example": "https://shinetime.example/gallery", "type": "string" } }, "type": "object" }, "disclaimer": { "description": "Optional custom consent disclaimer with checkboxes.", "properties": { "body": { "example": "Ceramic coating requires the vehicle for two days.", "type": "string" }, "checkboxes": { "items": { "properties": { "checked_by_default": { "example": false, "type": "boolean" }, "key": { "example": "two_days", "type": "string" }, "required": { "example": true, "type": "boolean" }, "text": { "example": "I can leave my vehicle for two days", "type": "string" } }, "type": "object" }, "type": "array" }, "title": { "example": "Before you submit", "type": "string" } }, "type": "object" }, "form_type": { "description": "more_volume (default) is quickest to submit; higher_intent adds a confirmation step.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "intro": { "description": "Optional intro screen shown before the questions.", "properties": { "description": { "example": "Tell us about your vehicle and we will send a fixed price.", "type": "string" }, "headline": { "example": "Get a ceramic coating quote", "type": "string" } }, "type": "object" }, "name": { "description": "Internal name for the form. Auto-generated if omitted.", "example": "Ceramic coating quote requests", "type": "string" }, "phone_verification": { "description": "Require SMS verification of the phone number (higher_intent forms).", "example": true, "type": "boolean" }, "privacy_policy": { "description": "Your privacy policy. url is required by the ad platform.", "properties": { "link_text": { "example": "Shine Time privacy policy", "type": "string" }, "url": { "example": "https://shinetime.example/privacy", "type": "string" } }, "type": "object" }, "questions": { "description": "The questions on the form. Standard prefill types need only a type; a custom question needs a label and a format (plus options for multiple_choice). Options carry an optional key and answer-routing logic.", "items": { "properties": { "format": { "enum": [ "short_answer", "multiple_choice", "appointment" ], "example": "multiple_choice", "type": "string" }, "label": { "example": "What vehicle are we detailing?", "type": "string" }, "options": { "items": { "properties": { "key": { "example": "sedan", "type": "string" }, "logic": { "properties": { "action": { "enum": [ "go_to_question", "submit_form", "close_form" ], "example": "go_to_question", "type": "string" }, "target_end_page_index": { "example": 0, "type": "integer" }, "target_question_index": { "example": 3, "type": "integer" } }, "type": "object" }, "value": { "example": "Sedan or coupe", "type": "string" } }, "type": "object" }, "type": "array" }, "type": { "enum": [ "email", "phone", "full_name", "first_name", "last_name", "city", "state", "zip", "country", "street_address", "job_title", "company_name", "work_email", "work_phone_number", "dob", "gender", "marital_status", "relationship_status", "military_status", "date_time", "custom" ], "example": "phone", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "lead_form_id": { "description": "Use an existing instant form instead of creating one — the form's platform ID, from a form already on the ad's Facebook page. Only allowed when the ad group's conversion_location is an instant-form destination. Mutually exclusive with lead_form.", "example": "1037724182084885", "type": "string" }, "messaging_config": { "description": "Click-to-message welcome copy: the greeting (message) and the ice-breaker prompt (keyword).", "properties": { "keyword": { "example": "Book an interior deep clean", "type": "string" }, "message": { "example": "Hi! Tell us your vehicle and ZIP and we will send an interior deep clean quote.", "type": "string" } }, "type": "object" }, "multi_advertiser_ads": { "description": "Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.", "example": false, "type": "boolean" }, "music": { "description": "The looping track a TikTok carousel ad plays — an MP3 you uploaded, no larger than 10MB. Required for TikTok carousels (image creatives); TikTok-only.", "nullable": true, "properties": { "id": { "description": "Uploaded MP3 file ID, prefixed `file_`.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "post_source": { "description": "Identifies the network that owns `existing_post_id`. The source is inferred from the ID shape when omitted.", "enum": [ "facebook", "instagram" ], "example": "instagram", "type": "string" }, "primary_texts": { "description": "The primary text shown in the ad body. Entries without a language are the ad's own copy (several make text variations); add one entry per other language on a Meta ad with `translations`.", "items": { "properties": { "language": { "description": "ISO 639 code of the language this text is in, such as `es`. Required on every entry of an ad with `translations`, where the ad's own copy uses `translations.source_language`. Leave it out on an ad without translations.", "nullable": true, "type": "string" }, "text": { "description": "The text shown to viewers.", "example": "Three-year ceramic coating, booked online in under a minute.", "type": "string" } }, "required": [ "text" ], "type": "object" }, "type": "array" }, "title": { "description": "The display name of the ad.", "example": "Interior deep clean — DM us", "type": "string" }, "translations": { "description": "Shows a Meta ad in other languages. Each viewer sees the version for their language; everyone else sees the ad's own copy. Tag every copy and creatives entry with its language: the ad's own with `source_language`, and give every other language a `primary_texts` and `headlines` entry (a `descriptions` entry and a `creatives` entry are optional), or list it in `automatic_languages`. Needs a website destination, one image or video, and exactly one primary text and headline of the ad's own (and at most one description), with no Dynamic Creative or crops. Replaced as a whole when sent, so send `automatic_languages` with `source_language`. null turns translations off and deletes their media. Meta-only.", "nullable": true, "properties": { "automatic_languages": { "description": "ISO 639 codes Meta translates the ad's own copy into automatically. English copy translates into `es`, `fr`, `de`, `pt`, `it`, `ar`, `nl`, `ms`, `sv`, `id`, `pl`, `hi`, `da`, `tr`, `fil`, and `ro`; `de`, `ar`, `he`, `es`, `ja`, `no`, `fr`, `nl`, and `sv` copy translate into `en`.", "items": { "example": "fr", "type": "string" }, "type": "array" }, "source_language": { "description": "ISO 639 code the ad's own copy is written in, such as `en`.", "example": "en", "type": "string" } }, "required": [ "source_language" ], "type": "object" }, "url": { "description": "The URL the ad links to. Query parameters are merged into url_parameters, so the stored URL is always bare.", "example": "https://shinetime.example/ceramic-coating", "type": "string" }, "url_parameters": { "description": "Query parameters to append to the destination URL, keyed by parameter name. Merged with any query string on `url`. Whop adds its own click-attribution parameters; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.", "example": { "ref": "spring" }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad created from an existing post" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Whop pixel not installed on the destination" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad group not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Create an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/ads/{id}": { "delete": { "description": "Deletes an ad.", "operationId": "deleteAd", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted ad.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "ad deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Delete an Ad", "tags": [ "Ads" ] }, "get": { "description": "Retrieves a single ad with stats over the requested window.", "operationId": "retrieveAd", "parameters": [ { "description": "Start of the stats window.", "in": "query", "name": "stats_from", "required": false, "schema": { "type": "string" } }, { "description": "End of the stats window.", "in": "query", "name": "stats_to", "required": false, "schema": { "type": "string" } }, { "description": "IANA timezone the stats window is interpreted in. Defaults to UTC.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad not found" } }, "security": [ { "bearerAuth": [ "ad_campaign:basic:read" ] } ], "summary": "Retrieve an Ad", "tags": [ "Ads" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an ad's editable fields.", "operationId": "updateAd", "parameters": [ { "$ref": "#/components/parameters/AdsPlatform" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "call_to_action": { "description": "The call-to-action button shown on the ad.", "enum": [ "apply_now", "book_now", "call_now", "contact_us", "donate_now", "download", "get_directions", "get_offer", "get_quote", "learn_more", "listen_now", "message_page", "no_button", "open_link", "order_now", "request_time", "see_details", "see_menu", "see_more", "send_updates", "shop_now", "sign_up", "subscribe", "visit_site", "watch_more" ], "example": "learn_more", "type": "string" }, "creatives": { "description": "The ad's creative assets. Each entry is an uploaded file id with an optional format; omit format for the original asset. Replaces a live ad's creative on the platform. Entries with no format replace it with a carousel's ordered cards — 2-10 of them on Meta, while TikTok runs even a single image as a one-card carousel.", "items": { "properties": { "crop": { "description": "The saved crop window for this creative, in source image pixels. Omit it for the original asset or for a format that has not been cropped.", "properties": { "height": { "example": 1920, "type": "number" }, "width": { "example": 1080, "type": "number" }, "x": { "example": 0, "type": "number" }, "y": { "example": 120, "type": "number" } }, "type": "object" }, "format": { "enum": [ "square", "vertical", "horizontal" ], "example": "vertical", "type": "string" }, "id": { "description": "Uploaded file ID, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "language": { "description": "ISO 639 code of the language this image or video is shown for, such as `es`. Required on every entry of an ad with `translations`, where the ad's own creative uses `translations.source_language`. Another language's creative is the same type as the ad's own, with no format. Leave it out on an ad without translations.", "type": "string" } }, "type": "object" }, "type": "array" }, "descriptions": { "description": "The description shown on the ad. Entries without a language are the ad's own copy; add one entry per other language on a Meta ad with `translations`.", "items": { "properties": { "language": { "description": "ISO 639 code of the language this text is in, such as `es`. Required on every entry of an ad with `translations`, where the ad's own copy uses `translations.source_language`. Leave it out on an ad without translations.", "nullable": true, "type": "string" }, "text": { "description": "The text shown to viewers.", "example": "Paint correction included", "type": "string" } }, "required": [ "text" ], "type": "object" }, "type": "array" }, "existing_post_id": { "description": "Promote a post you already published instead of uploading creatives — a Facebook post or Instagram media id. Mutually exclusive with creatives. Pair with post_source.", "example": "xxxxxxxxxxxxxxxx_98765", "type": "string" }, "external_accounts": { "description": "The external accounts the ad runs under — a connected Facebook page and, optionally, an Instagram profile.", "items": { "properties": { "id": { "description": "External account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "headlines": { "description": "The headline shown on the ad. Entries without a language are the ad's own copy; add one entry per other language on a Meta ad with `translations`.", "items": { "properties": { "language": { "description": "ISO 639 code of the language this text is in, such as `es`. Required on every entry of an ad with `translations`, where the ad's own copy uses `translations.source_language`. Leave it out on an ad without translations.", "example": "es", "nullable": true, "type": "string" }, "text": { "description": "The text shown to viewers.", "example": "Austin's mobile detailers", "type": "string" } }, "required": [ "text" ], "type": "object" }, "type": "array" }, "lead_form": { "description": "Instant lead form for the ad. Only allowed when the ad group's conversion_location is an instant-form destination (instant_forms, instant_forms_and_messenger, website_and_instant_forms). Mutually exclusive with lead_form_id.", "properties": { "completion": { "description": "Optional completion screen shown after submission. Its button needs a destination: url for button_type website (the default), phone_number for call, file_url for download.", "properties": { "button_text": { "example": "See our work", "type": "string" }, "button_type": { "enum": [ "website", "call", "download" ], "example": "website", "type": "string" }, "description": { "example": "We book coatings two days out, so pick a slot when we ring.", "type": "string" }, "file_url": { "type": "string" }, "headline": { "example": "Thanks — we will call you today", "type": "string" }, "phone_number": { "type": "string" }, "url": { "example": "https://shinetime.example/gallery", "type": "string" } }, "type": "object" }, "disclaimer": { "description": "Optional custom consent disclaimer with checkboxes.", "properties": { "body": { "example": "Ceramic coating requires the vehicle for two days.", "type": "string" }, "checkboxes": { "items": { "properties": { "checked_by_default": { "example": false, "type": "boolean" }, "key": { "example": "two_days", "type": "string" }, "required": { "example": true, "type": "boolean" }, "text": { "example": "I can leave my vehicle for two days", "type": "string" } }, "type": "object" }, "type": "array" }, "title": { "example": "Before you submit", "type": "string" } }, "type": "object" }, "form_type": { "description": "more_volume (default) is quickest to submit; higher_intent adds a confirmation step.", "enum": [ "more_volume", "higher_intent" ], "example": "higher_intent", "type": "string" }, "intro": { "description": "Optional intro screen shown before the questions.", "properties": { "description": { "example": "Tell us about your vehicle and we will send a fixed price.", "type": "string" }, "headline": { "example": "Get a ceramic coating quote", "type": "string" } }, "type": "object" }, "name": { "description": "Internal name for the form. Auto-generated if omitted.", "example": "Ceramic coating quote requests", "type": "string" }, "phone_verification": { "description": "Require SMS verification of the phone number (higher_intent forms).", "example": true, "type": "boolean" }, "privacy_policy": { "description": "Your privacy policy. url is required by the ad platform.", "properties": { "link_text": { "example": "Shine Time privacy policy", "type": "string" }, "url": { "example": "https://shinetime.example/privacy", "type": "string" } }, "type": "object" }, "questions": { "description": "The questions on the form. Standard prefill types need only a type; a custom question needs a label and a format (plus options for multiple_choice). Options carry an optional key and answer-routing logic.", "items": { "properties": { "format": { "enum": [ "short_answer", "multiple_choice", "appointment" ], "example": "multiple_choice", "type": "string" }, "label": { "example": "What vehicle are we detailing?", "type": "string" }, "options": { "items": { "properties": { "key": { "example": "sedan", "type": "string" }, "logic": { "properties": { "action": { "enum": [ "go_to_question", "submit_form", "close_form" ], "example": "go_to_question", "type": "string" }, "target_end_page_index": { "example": 0, "type": "integer" }, "target_question_index": { "example": 3, "type": "integer" } }, "type": "object" }, "value": { "example": "Sedan or coupe", "type": "string" } }, "type": "object" }, "type": "array" }, "type": { "enum": [ "email", "phone", "full_name", "first_name", "last_name", "city", "state", "zip", "country", "street_address", "job_title", "company_name", "work_email", "work_phone_number", "dob", "gender", "marital_status", "relationship_status", "military_status", "date_time", "custom" ], "example": "phone", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "lead_form_id": { "description": "Use an existing instant form instead of creating one — the form's platform ID, from a form already on the ad's Facebook page. Only allowed when the ad group's conversion_location is an instant-form destination. Mutually exclusive with lead_form. Replaces a stored lead_form.", "example": "1037724182084885", "type": "string" }, "messaging_config": { "description": "Click-to-message welcome copy: the greeting (message) and the ice-breaker prompt (keyword).", "properties": { "keyword": { "example": "Get a ceramic coating quote", "type": "string" }, "message": { "example": "Hi! Which vehicle are we coating?", "type": "string" } }, "type": "object" }, "multi_advertiser_ads": { "description": "Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.", "example": false, "type": "boolean" }, "music": { "description": "The looping track a TikTok carousel ad plays — an MP3 you uploaded, no larger than 10MB. Omitted leaves the ad's music untouched. Null removes it before launch; a submitted carousel takes a replacement track instead. TikTok-only.", "nullable": true, "properties": { "id": { "description": "Uploaded MP3 file ID, prefixed `file_`.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "post_source": { "description": "Identifies the network that owns `existing_post_id`. The source is inferred from the ID shape when omitted.", "enum": [ "facebook", "instagram" ], "example": "facebook", "type": "string" }, "primary_texts": { "description": "The primary text shown in the ad body. Entries without a language are the ad's own copy (several make text variations); add one entry per other language on a Meta ad with `translations`.", "items": { "properties": { "language": { "description": "ISO 639 code of the language this text is in, such as `es`. Required on every entry of an ad with `translations`, where the ad's own copy uses `translations.source_language`. Leave it out on an ad without translations.", "example": "es", "nullable": true, "type": "string" }, "text": { "description": "The text shown to viewers.", "example": "Book a two-day ceramic coating and keep the shine for three years.", "type": "string" } }, "required": [ "text" ], "type": "object" }, "type": "array" }, "title": { "description": "The display name of the ad.", "example": "Ceramic coating — spring hook v2", "type": "string" }, "translations": { "description": "Shows a Meta ad in other languages. Each viewer sees the version for their language; everyone else sees the ad's own copy. Tag every copy and creatives entry with its language: the ad's own with `source_language`, and give every other language a `primary_texts` and `headlines` entry (a `descriptions` entry and a `creatives` entry are optional), or list it in `automatic_languages`. Needs a website destination, one image or video, and exactly one primary text and headline of the ad's own (and at most one description), with no Dynamic Creative or crops. Replaced as a whole when sent, so send `automatic_languages` with `source_language`. null turns translations off and deletes their media. Meta-only.", "nullable": true, "properties": { "automatic_languages": { "description": "ISO 639 codes Meta translates the ad's own copy into automatically. English copy translates into `es`, `fr`, `de`, `pt`, `it`, `ar`, `nl`, `ms`, `sv`, `id`, `pl`, `hi`, `da`, `tr`, `fil`, and `ro`; `de`, `ar`, `he`, `es`, `ja`, `no`, `fr`, `nl`, and `sv` copy translate into `en`.", "items": { "example": "fr", "type": "string" }, "type": "array" }, "source_language": { "description": "ISO 639 code the ad's own copy is written in, such as `en`.", "example": "en", "type": "string" } }, "required": [ "source_language" ], "type": "object" }, "url": { "description": "The URL the ad links to. Query parameters are merged into url_parameters, so the stored URL is always bare.", "example": "https://shinetime.example/ceramic-coating", "type": "string" }, "url_parameters": { "description": "Query parameters to append to the destination URL, keyed by parameter name. Merged with any query string on `url`. Whop adds its own click-attribution parameters; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.", "example": { "placement": "{{placement}}", "ref": "spring" }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad switched to an existing post" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/ads/{id}/duplicate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Copies an ad into its own ad group or into another one. Copies keep the source ad's active or paused state.", "operationId": "duplicateAd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "Number of copies to create (1-10). Defaults to 1.", "example": 2, "type": "integer" }, "preserve_engagement": { "description": "Whether the copies keep the original post's engagement (likes, comments, shares). Defaults to false.", "example": true, "type": "boolean" }, "target_ad_group_id": { "description": "Ad group to duplicate into, which must belong to the same account and be compatible with the ad. Defaults to the ad's own ad group.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "ad duplicated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "target ad group on a different ad account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "ad not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Duplicate an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/ads/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses an active ad.", "operationId": "pauseAd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad paused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Pause an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/ads/{id}/unpause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes a paused ad.", "operationId": "unpauseAd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ad" } } }, "description": "ad unpaused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Unpause an Ad", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "/affiliates": { "get": { "description": "Lists the affiliates of an account.\n\nRequired permissions:\n - `affiliate:basic:read`", "operationId": "listAffiliate", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for results. Defaults to descending." }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/AffiliatesSortableColumns", "description": "The field to sort results by." }, "style": "form" }, { "explode": true, "in": "query", "name": "query", "required": false, "schema": { "description": "Search affiliates by username.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/Status", "description": "Filter by affiliate status (active or archived)." }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": true, "schema": { "description": "The unique identifier of the company to list affiliates for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Affiliate.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AffiliateListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "List affiliates", "tags": [ "Affiliates" ], "x-group-title": "CRM" }, "post": { "description": "Creates an affiliate for a user on an account. If the user is already an affiliate of the account, returns that affiliate, reactivating it if it was archived.\n\nRequired permissions:\n - `affiliate:create`", "operationId": "createAffiliate", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAffiliateRecord", "properties": { "account_id": { "description": "The ID of the company to create the affiliate for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "user_identifier": { "description": "The user identifier (username, email, user ID, or Discord ID).", "type": "string" } }, "required": [ "account_id", "user_identifier" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Affiliate" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:create" ] } ], "summary": "Create affiliate", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}": { "get": { "description": "Retrieves the details of an existing affiliate.\n\nRequired permissions:\n - `affiliate:basic:read`", "operationId": "retrieveAffiliate", "parameters": [ { "description": "The unique identifier of the affiliate.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Affiliate" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "Retrieve affiliate", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}/archive": { "post": { "description": "Archives an affiliate. The affiliate that handles Whop marketplace referrals cannot be archived.\n\nRequired permissions:\n - `affiliate:update`", "operationId": "archiveAffiliate", "parameters": [ { "description": "The internal ID of the affiliate to archive.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:update" ] } ], "summary": "Archive affiliate", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}/overrides": { "get": { "description": "Returns a paginated list of overrides for an affiliate.\n\nRequired permissions:\n - `affiliate:basic:read`", "operationId": "listOverridesAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "override_type", "required": false, "schema": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "Filter by override type (standard or rev_share)." }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for AffiliateOverride.", "properties": { "data": { "description": "A list of nodes.", "items": { "description": "A commission configuration for an affiliate, defining payout terms for a specific plan or revenue share", "properties": { "applies_to_payments": { "description": "Whether the commission applies to the first payment only or all payments (standard overrides only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "applies_to_products": { "description": "Whether this rev-share override applies to a single product or all products (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToProducts" }, { "type": "null" } ] }, "checkout_direct_link": { "description": "The checkout direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "commission_type": { "$ref": "#/components/schemas/AffiliatePayoutTypes", "description": "The type of commission (percentage or flat_fee)." }, "commission_value": { "description": "The commission amount. A percentage (1-100) when commission_type is percentage, or a dollar amount when flat_fee.", "example": 6.9, "type": "number" }, "id": { "description": "The unique identifier for the affiliate override.", "example": "affov_xxxxxxxxxxxx", "type": "string" }, "override_type": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "The type of override (standard or rev_share)." }, "plan_id": { "description": "The plan ID (for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_direct_link": { "description": "The product page direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "product_id": { "description": "The product ID (for rev-share overrides).", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (pre_fees or post_fees).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] }, "total_referral_earnings_usd": { "description": "The total earnings paid to this affiliate for referrals to this specific plan, in USD.", "example": 6.9, "type": "number" } }, "required": [ "id", "override_type", "commission_type", "commission_value", "applies_to_payments", "plan_id", "product_id", "applies_to_products", "revenue_basis", "product_direct_link", "checkout_direct_link", "total_referral_earnings_usd" ], "type": "object" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "List overrides", "tags": [ "Affiliates" ], "x-group-title": "CRM" }, "post": { "description": "Creates a commission override for an affiliate.\n\nRequired permissions:\n - `affiliate:create`", "operationId": "createOverrideAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAffiliateOverride", "oneOf": [ { "description": "Autogenerated input type of CreateAffiliateOverride", "properties": { "applies_to_payments": { "description": "Whether commission applies to first payment or all payments (standard only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "commission_type": { "description": "The commission type (percentage or flat_fee).", "oneOf": [ { "$ref": "#/components/schemas/AffiliatePayoutTypes" }, { "type": "null" } ] }, "commission_value": { "description": "The commission value (percentage 1-100 or flat fee).", "example": 6.9, "type": "number" }, "id": { "description": "The affiliate ID.", "type": "string" }, "override_type": { "const": "standard", "type": "string" }, "plan_id": { "description": "The plan ID (required for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "commission_value", "id", "override_type", "plan_id" ], "title": "CreateAffiliateOverrideInputOverrideTypeStandard", "type": "object" }, { "description": "Autogenerated input type of CreateAffiliateOverride", "properties": { "commission_type": { "description": "The commission type (percentage or flat_fee).", "oneOf": [ { "$ref": "#/components/schemas/AffiliatePayoutTypes" }, { "type": "null" } ] }, "commission_value": { "description": "The commission value (percentage 1-100 or flat fee).", "example": 6.9, "type": "number" }, "id": { "description": "The affiliate ID.", "type": "string" }, "override_type": { "const": "rev_share", "type": "string" }, "product_id": { "description": "The product ID (for rev-share overrides, omit for company-wide).", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis for rev-share overrides. Defaults to post_fees.", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] } }, "required": [ "commission_value", "id", "override_type" ], "title": "CreateAffiliateOverrideInputOverrideTypeRevShare", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A commission configuration for an affiliate, defining payout terms for a specific plan or revenue share", "properties": { "applies_to_payments": { "description": "Whether the commission applies to the first payment only or all payments (standard overrides only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "applies_to_products": { "description": "Whether this rev-share override applies to a single product or all products (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToProducts" }, { "type": "null" } ] }, "checkout_direct_link": { "description": "The checkout direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "commission_type": { "$ref": "#/components/schemas/AffiliatePayoutTypes", "description": "The type of commission (percentage or flat_fee)." }, "commission_value": { "description": "The commission amount. A percentage (1-100) when commission_type is percentage, or a dollar amount when flat_fee.", "example": 6.9, "type": "number" }, "id": { "description": "The unique identifier for the affiliate override.", "example": "affov_xxxxxxxxxxxx", "type": "string" }, "override_type": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "The type of override (standard or rev_share)." }, "plan_id": { "description": "The plan ID (for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_direct_link": { "description": "The product page direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "product_id": { "description": "The product ID (for rev-share overrides).", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (pre_fees or post_fees).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] }, "total_referral_earnings_usd": { "description": "The total earnings paid to this affiliate for referrals to this specific plan, in USD.", "example": 6.9, "type": "number" } }, "required": [ "id", "override_type", "commission_type", "commission_value", "applies_to_payments", "plan_id", "product_id", "applies_to_products", "revenue_basis", "product_direct_link", "checkout_direct_link", "total_referral_earnings_usd" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:create" ] } ], "summary": "Create override", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}/overrides/{override_id}": { "delete": { "description": "Deletes an affiliate override.\n\nRequired permissions:\n - `affiliate:update`", "operationId": "deleteOverrideAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } }, { "description": "The override ID.", "in": "path", "name": "override_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:update" ] } ], "summary": "Delete override", "tags": [ "Affiliates" ], "x-group-title": "CRM" }, "get": { "description": "Retrieves the details of a specific affiliate override.\n\nRequired permissions:\n - `affiliate:basic:read`", "operationId": "retrieveOverrideAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } }, { "description": "The override ID.", "in": "path", "name": "override_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A commission configuration for an affiliate, defining payout terms for a specific plan or revenue share", "properties": { "applies_to_payments": { "description": "Whether the commission applies to the first payment only or all payments (standard overrides only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "applies_to_products": { "description": "Whether this rev-share override applies to a single product or all products (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToProducts" }, { "type": "null" } ] }, "checkout_direct_link": { "description": "The checkout direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "commission_type": { "$ref": "#/components/schemas/AffiliatePayoutTypes", "description": "The type of commission (percentage or flat_fee)." }, "commission_value": { "description": "The commission amount. A percentage (1-100) when commission_type is percentage, or a dollar amount when flat_fee.", "example": 6.9, "type": "number" }, "id": { "description": "The unique identifier for the affiliate override.", "example": "affov_xxxxxxxxxxxx", "type": "string" }, "override_type": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "The type of override (standard or rev_share)." }, "plan_id": { "description": "The plan ID (for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_direct_link": { "description": "The product page direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "product_id": { "description": "The product ID (for rev-share overrides).", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (pre_fees or post_fees).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] }, "total_referral_earnings_usd": { "description": "The total earnings paid to this affiliate for referrals to this specific plan, in USD.", "example": 6.9, "type": "number" } }, "required": [ "id", "override_type", "commission_type", "commission_value", "applies_to_payments", "plan_id", "product_id", "applies_to_products", "revenue_basis", "product_direct_link", "checkout_direct_link", "total_referral_earnings_usd" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "Retrieve override", "tags": [ "Affiliates" ], "x-group-title": "CRM" }, "patch": { "description": "Updates an existing affiliate override.\n\nRequired permissions:\n - `affiliate:update`", "operationId": "updateOverrideAffiliate", "parameters": [ { "description": "The affiliate ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } }, { "description": "The override ID.", "in": "path", "name": "override_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateAffiliateOverride", "properties": { "applies_to_payments": { "description": "Whether commission applies to first payment or all payments (standard only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "commission_type": { "description": "The commission type (percentage or flat_fee).", "oneOf": [ { "$ref": "#/components/schemas/AffiliatePayoutTypes" }, { "type": "null" } ] }, "commission_value": { "description": "The commission value (percentage 1-100 or flat fee in dollars).", "example": 6.9, "type": [ "number", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A commission configuration for an affiliate, defining payout terms for a specific plan or revenue share", "properties": { "applies_to_payments": { "description": "Whether the commission applies to the first payment only or all payments (standard overrides only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToPayments" }, { "type": "null" } ] }, "applies_to_products": { "description": "Whether this rev-share override applies to a single product or all products (rev-share only).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateAppliesToProducts" }, { "type": "null" } ] }, "checkout_direct_link": { "description": "The checkout direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "commission_type": { "$ref": "#/components/schemas/AffiliatePayoutTypes", "description": "The type of commission (percentage or flat_fee)." }, "commission_value": { "description": "The commission amount. A percentage (1-100) when commission_type is percentage, or a dollar amount when flat_fee.", "example": 6.9, "type": "number" }, "id": { "description": "The unique identifier for the affiliate override.", "example": "affov_xxxxxxxxxxxx", "type": "string" }, "override_type": { "$ref": "#/components/schemas/AffiliateOverrideRoles", "description": "The type of override (standard or rev_share)." }, "plan_id": { "description": "The plan ID (for standard overrides).", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_direct_link": { "description": "The product page direct link for referrals (standard overrides only).", "type": [ "string", "null" ] }, "product_id": { "description": "The product ID (for rev-share overrides).", "type": [ "string", "null" ] }, "revenue_basis": { "description": "The revenue calculation basis (pre_fees or post_fees).", "oneOf": [ { "$ref": "#/components/schemas/AffiliateRevenueBases" }, { "type": "null" } ] }, "total_referral_earnings_usd": { "description": "The total earnings paid to this affiliate for referrals to this specific plan, in USD.", "example": 6.9, "type": "number" } }, "required": [ "id", "override_type", "commission_type", "commission_value", "applies_to_payments", "plan_id", "product_id", "applies_to_products", "revenue_basis", "product_direct_link", "checkout_direct_link", "total_referral_earnings_usd" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:update" ] } ], "summary": "Update override", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/affiliates/{id}/unarchive": { "post": { "description": "Unarchives an archived affiliate.\n\nRequired permissions:\n - `affiliate:update`", "operationId": "unarchiveAffiliate", "parameters": [ { "description": "The internal ID of the affiliate to archive.", "in": "path", "name": "id", "required": true, "schema": { "example": "aff_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "affiliate:update" ] } ], "summary": "Unarchive affiliate", "tags": [ "Affiliates" ], "x-group-title": "CRM" } }, "/ai_chats": { "get": { "description": "Returns a paginated list of AI chat threads for the current authenticated user.", "operationId": "listAiChat", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "agent_identifier", "required": false, "schema": { "$ref": "#/components/schemas/AiChatAgentIdentifiers", "description": "Only return chats handled by this agent." }, "style": "form" }, { "explode": true, "in": "query", "name": "only_active_crons", "required": false, "schema": { "description": "When true, returns only chats with an active cron schedule", "type": "boolean" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for AiChat.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AiChatListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List ai chats", "tags": [ "Ai chats" ], "x-group-title": "AI" }, "post": { "description": "Create a new AI chat thread and send the first message to the AI agent.\n\nRequired permissions:\n - `ai_chat:create`", "operationId": "createAiChat", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAiChat", "properties": { "agent_identifier": { "description": "The AI agent that handles the chat. Defaults to `support`.", "oneOf": [ { "$ref": "#/components/schemas/AiChatAgentIdentifiers" }, { "type": "null" } ] }, "current_account_id": { "description": "The unique identifier of the account to set as context for the AI chat (e.g., \"biz_XXXXX\").", "type": [ "string", "null" ] }, "message_attachments": { "description": "A list of previously uploaded file attachments to include with the first message.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "message_source": { "description": "The source of the message.", "oneOf": [ { "$ref": "#/components/schemas/AiChatMessageSourceTypes" }, { "type": "null" } ] }, "message_text": { "description": "The text content of the first message to send to the AI agent.", "type": "string" }, "suggestion_type": { "description": "The type of suggestion prompt that was clicked, when message_source is 'suggestion'.", "type": [ "string", "null" ] }, "title": { "description": "An optional display title for the AI chat thread (e.g., \"Help with billing\").", "type": [ "string", "null" ] } }, "required": [ "message_text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiChat" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ai_chat:create" ] } ], "summary": "Create ai chat", "tags": [ "Ai chats" ], "x-group-title": "AI" } }, "/ai_chats/{id}": { "delete": { "description": "Delete an AI chat thread so it no longer appears in the user's chat list.\n\nRequired permissions:\n - `ai_chat:delete`", "operationId": "deleteAiChat", "parameters": [ { "description": "The unique identifier of the AI chat to delete (e.g., \"ai_chat_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "aich_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ai_chat:delete" ] } ], "summary": "Delete ai chat", "tags": [ "Ai chats" ], "x-group-title": "AI" }, "get": { "description": "Retrieves the details of an existing AI chat.", "operationId": "retrieveAiChat", "parameters": [ { "description": "The unique identifier of the AI chat to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "aich_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiChat" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve ai chat", "tags": [ "Ai chats" ], "x-group-title": "AI" }, "patch": { "description": "Update an AI chat's title, notification preferences, or associated account context.\n\nRequired permissions:\n - `ai_chat:update`", "operationId": "updateAiChat", "parameters": [ { "description": "The unique identifier of the AI chat to update (e.g., \"ai_chat_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "aich_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateAiChat", "properties": { "current_account_id": { "description": "The unique identifier of the account to set as context for the AI chat (e.g., \"biz_XXXXX\").", "type": [ "string", "null" ] }, "notification_preference": { "description": "The notification preference for the AI chat.", "oneOf": [ { "$ref": "#/components/schemas/AiChatNotificationPreferences" }, { "type": "null" } ] }, "title": { "description": "The new display title for the AI chat thread (e.g., \"Help with billing\").", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiChat" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "ai_chat:update" ] } ], "summary": "Update ai chat", "tags": [ "Ai chats" ], "x-group-title": "AI" } }, "/api_keys": { "get": { "description": "Lists the API keys of an account or app, newest first. Responses never include the full secret — only its obfuscated form.", "operationId": "listApiKeys", "parameters": [ { "description": "The account (`biz_`) or app (`app_`) tag to list API keys for.", "in": "query", "name": "resource_id", "required": true, "schema": { "type": "string" } }, { "description": "The type of resource that owns the API keys.", "in": "query", "name": "resource_type", "required": true, "schema": { "enum": [ "account", "app" ], "type": "string" } }, { "description": "Only return API keys created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": [ "integer", "string" ] } }, { "description": "Only return API keys created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": [ "integer", "string" ] } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort API keys by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApiKey" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "api keys listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the resource type is not supported" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no resource with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "List API Keys", "tags": [ "API Keys" ], "x-whop-credentials": [] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an API key for an account or app. The response is the only place the full `secret_key` is returned — store it immediately. Requires a user session; API keys cannot manage API keys.", "operationId": "createApiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version_date": { "description": "Dated API version used when requests authenticated with this key omit the `Api-Version-Date` header. New keys default to the latest version.", "enum": [ "2025-01-01", "2026-06-08", "2026-06-09", "2026-06-20", "2026-07-01", "2026-07-08", "2026-07-08-1", "2026-07-18", "2026-07-20", "2026-07-22", "2026-07-23", "2026-07-25", "2026-07-26", "2026-07-27", "2026-07-29", "2026-07-29-1", "2026-07-31", "2026-08-03", "2026-08-05", "2026-08-05-1", "2026-08-10", "2026-08-12", "2026-08-13", "2026-08-14", "2026-08-21", "2026-08-21-1", "2026-08-25", "2026-08-25-1", "2026-08-25-2", "2026-08-31", "2026-09-02", "2026-09-02-1", "2026-09-02-2", "2026-09-04", "2026-09-06", "2026-09-09", "2026-09-09-1", "2026-09-11", "2026-09-11-1", "2026-09-13", "2026-09-15", "2026-09-22", "2026-09-22-1", "2026-09-22-2", "2026-09-22-3", "2026-09-22-4", "2026-09-23", "2026-09-24", "2026-09-24-1", "2026-09-25", "2026-09-28", "2026-09-29", "2026-10-05", "2026-10-05-1", "2026-10-06", "2026-10-06-1", "2026-10-06-2", "2026-10-07", "2026-10-07-1", "2026-10-07-2", "2026-10-08", "2026-10-09", "2026-10-09-1", "2026-10-09-2", "2026-10-13", "2026-10-13-1", "2026-10-14", "2026-10-14-1", "2026-10-15", "2026-10-15-1", "2026-10-24", "2026-10-27", "2026-10-27-1", "2026-10-27-2", "2026-10-27-3" ], "example": "2026-10-27-3", "type": "string" }, "expires_at": { "description": "When the API key should stop working, as an ISO 8601 timestamp. Omit (or pass `null` on update) for a key that never expires.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "ip_allowlist": { "description": "IPv4/IPv6 CIDR ranges allowed to use this key, for example `[\"203.0.113.0/24\"]`. Empty or `null` allows any IP.", "items": { "example": "203.0.113.0/24", "type": "string" }, "type": [ "array", "null" ] }, "name": { "description": "A human-readable name for the API key, such as 'Production API Key'.", "example": "Shine Time Booking (production)", "type": "string" }, "permissions": { "description": "The permissions policy for the API key: explicit permission statements, or a system role to inherit from. Statements without a `resources` array default to the owning account (Account API keys) or every key-addressable resource (App API keys).", "properties": { "statements": { "description": "Explicit permission statements. Required unless `system_role` is set.", "items": { "properties": { "actions": { "description": "Permission actions covered by this statement, for example `company:basic:read`.", "items": { "example": "company:basic:read", "type": "string" }, "type": "array" }, "grant": { "description": "Whether the actions are granted (`true`) or denied (`false`).", "example": true, "type": "boolean" }, "resources": { "description": "Resource identifiers the statement applies to, for example `biz_xxx` or `biz_xxx|pass_*`. Defaults to the key's owning resource when omitted.", "items": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "actions", "grant" ], "type": "object" }, "type": "array" }, "system_role": { "description": "A system role to inherit permissions from. Only Account API keys can use a system role.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser", null ], "example": "admin", "type": [ "string", "null" ] } }, "type": "object" }, "resource_id": { "description": "The account (`biz_`) or app (`app_`) tag to create the API key for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "resource_type": { "description": "The type of resource that will own this API key.", "enum": [ "account", "app" ], "example": "account", "type": "string" } }, "required": [ "resource_id", "resource_type", "name", "permissions" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "api key created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Create API Key", "tags": [ "API Keys" ], "x-whop-credentials": [] }, "x-whop-surface": "native" }, "/api_keys/permissions": { "get": { "description": "Lists the catalog of permission actions that can be granted to users, apps, and API keys. Use it to choose the `permissions` for an API key or to build a permission picker. Small and returned in full on one page.", "operationId": "listApiKeyPermissions", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Permission" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": null, "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "permission catalog listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List the Permission Catalog", "tags": [ "API Keys" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/api_keys/{id}": { "delete": { "description": "Permanently revokes an API key; requests using its secret stop authenticating immediately. Default and agent-backend keys cannot be deleted.", "operationId": "deleteApiKey", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always `true`: the key was revoked.", "example": true, "type": "boolean" }, "id": { "description": "The ID of the revoked key.", "example": "apik_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "deleted", "id" ], "type": "object" } } }, "description": "api key deleted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the api key cannot be deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no api key with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Delete API Key", "tags": [ "API Keys" ], "x-whop-credentials": [] }, "get": { "description": "Retrieves an API key with its effective permission grants. The full secret is never returned — rotate the key if it was lost.", "operationId": "retrieveApiKey", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "api key retrieved with grants but never the secret" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no api key with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Retrieve API Key", "tags": [ "API Keys" ], "x-whop-credentials": [] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "API key ID, prefixed `apik_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an API key's name, permissions, API version, expiration, or IP allowlist. Fields that are omitted keep their current value; default keys cannot be modified.", "operationId": "updateApiKey", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version_date": { "description": "Dated API version used when requests authenticated with this key omit the `Api-Version-Date` header. New keys default to the latest version.", "enum": [ "2025-01-01", "2026-06-08", "2026-06-09", "2026-06-20", "2026-07-01", "2026-07-08", "2026-07-08-1", "2026-07-18", "2026-07-20", "2026-07-22", "2026-07-23", "2026-07-25", "2026-07-26", "2026-07-27", "2026-07-29", "2026-07-29-1", "2026-07-31", "2026-08-03", "2026-08-05", "2026-08-05-1", "2026-08-10", "2026-08-12", "2026-08-13", "2026-08-14", "2026-08-21", "2026-08-21-1", "2026-08-25", "2026-08-25-1", "2026-08-25-2", "2026-08-31", "2026-09-02", "2026-09-02-1", "2026-09-02-2", "2026-09-04", "2026-09-06", "2026-09-09", "2026-09-09-1", "2026-09-11", "2026-09-11-1", "2026-09-13", "2026-09-15", "2026-09-22", "2026-09-22-1", "2026-09-22-2", "2026-09-22-3", "2026-09-22-4", "2026-09-23", "2026-09-24", "2026-09-24-1", "2026-09-25", "2026-09-28", "2026-09-29", "2026-10-05", "2026-10-05-1", "2026-10-06", "2026-10-06-1", "2026-10-06-2", "2026-10-07", "2026-10-07-1", "2026-10-07-2", "2026-10-08", "2026-10-09", "2026-10-09-1", "2026-10-09-2", "2026-10-13", "2026-10-13-1", "2026-10-14", "2026-10-14-1", "2026-10-15", "2026-10-15-1", "2026-10-24", "2026-10-27", "2026-10-27-1", "2026-10-27-2", "2026-10-27-3" ], "example": "2026-10-27-3", "type": "string" }, "expires_at": { "description": "When the API key should stop working, as an ISO 8601 timestamp. Omit (or pass `null` on update) for a key that never expires.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "ip_allowlist": { "description": "IPv4/IPv6 CIDR ranges allowed to use this key, for example `[\"203.0.113.0/24\"]`. Empty or `null` allows any IP.", "items": { "example": "203.0.113.0/24", "type": "string" }, "type": [ "array", "null" ] }, "name": { "description": "A new human-readable name for the API key.", "example": "Shine Time Booking (staging)", "type": [ "string", "null" ] }, "permissions": { "description": "The permissions policy for the API key: explicit permission statements, or a system role to inherit from. Statements without a `resources` array default to the owning account (Account API keys) or every key-addressable resource (App API keys).", "properties": { "statements": { "description": "Explicit permission statements. Required unless `system_role` is set.", "items": { "properties": { "actions": { "description": "Permission actions covered by this statement, for example `company:basic:read`.", "items": { "example": "company:basic:read", "type": "string" }, "type": "array" }, "grant": { "description": "Whether the actions are granted (`true`) or denied (`false`).", "example": true, "type": "boolean" }, "resources": { "description": "Resource identifiers the statement applies to, for example `biz_xxx` or `biz_xxx|pass_*`. Defaults to the key's owning resource when omitted.", "items": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "actions", "grant" ], "type": "object" }, "type": "array" }, "system_role": { "description": "A system role to inherit permissions from. Only Account API keys can use a system role.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser", null ], "example": "admin", "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "api key updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the api key cannot be modified" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no api key with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Update API Key", "tags": [ "API Keys" ], "x-whop-credentials": [] }, "x-whop-surface": "native" }, "/api_keys/{id}/rotate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "API key ID, prefixed `apik_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Rotates the API key's secret, invalidating the previous secret immediately. The response is the only place the new `secret_key` is returned.", "operationId": "rotateApiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "api key rotated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required api-key management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no api key with that ID exists" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_api_key" ] } ], "summary": "Rotate API Key", "tags": [ "API Keys" ], "x-whop-credentials": [] }, "x-whop-surface": "native" }, "/api_logs": { "get": { "description": "Lists the requests served by Whop's API with the account's API keys, newest first — every surface (GraphQL, REST, and native /api/v1), reads and failed requests included.", "operationId": "listApiLogs", "parameters": [ { "description": "The account (biz_*) whose API logs to list. Defaults to the authenticated account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests served at or after this ISO 8601 timestamp. Defaults to 7 days before created_before, or 7 days ago.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests served before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests for this operation, matched exactly against the operation_name shown on each log row (for example api/v1/products#create).", "in": "query", "name": "operation_name", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests made with this HTTP method.", "in": "query", "name": "http_method", "required": false, "schema": { "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "type": "string" } }, { "description": "Only return requests that finished with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "success", "error" ], "type": "string" } }, { "description": "Only return requests made with this API key (apik_…).", "in": "query", "name": "api_key_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return requests that took at least this many milliseconds.", "in": "query", "name": "min_duration_ms", "required": false, "schema": { "type": "integer" } }, { "description": "Only return requests that took at most this many milliseconds.", "in": "query", "name": "max_duration_ms", "required": false, "schema": { "type": "integer" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 25, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "api_key_id": { "example": "apik_xxxxxxxxxxxxxx", "nullable": true, "type": "string" }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "duration_ms": { "example": 12, "nullable": true, "type": "integer" }, "http_method": { "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", null ], "example": "POST", "nullable": true, "type": "string" }, "http_path": { "example": "/api/v1/products/prod_abc", "nullable": true, "type": "string" }, "id": { "example": "evt_xxxxxxxxxxxxxx_1", "type": "string" }, "ip_address": { "example": "87.106.27.99", "nullable": true, "type": "string" }, "operation_name": { "example": "api/v1/products#create", "nullable": true, "type": "string" }, "resource_id": { "example": "prod_abc", "nullable": true, "type": "string" }, "status": { "enum": [ "success", "error", null ], "example": "success", "nullable": true, "type": "string" }, "status_code": { "example": 200, "nullable": true, "type": "integer" }, "user_agent": { "example": "node", "nullable": true, "type": "string" } }, "required": [ "id", "created_at" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": null, "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "api logs listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "caller lacks developer:logs:read on the account" }, "429": { "$ref": "#/components/responses/TooManyRequests", "description": "more than 10 reads per minute for the account" } }, "security": [ { "bearerAuth": [ "developer:logs:read" ] } ], "summary": "List Api Logs", "tags": [ "Api Logs" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/app_builds": { "get": { "description": "Returns a paginated list of build artifacts for an app, newest first, with optional platform, status, and creation-date filters.", "operationId": "listAppBuilds", "parameters": [ { "description": "The app to list builds for, prefixed `app_`.", "in": "query", "name": "app_id", "required": true, "schema": { "type": "string" } }, { "description": "Filter builds by target platform.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "ios", "android", "web" ], "type": "string" } }, { "description": "Filter builds by review status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "draft", "pending", "approved", "rejected" ], "type": "string" } }, { "description": "Only return builds created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": [ "integer", "string" ] } }, { "description": "Only return builds created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": [ "integer", "string" ] } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AppBuild" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "app builds listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the app_id is missing" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the build-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "List App Builds", "tags": [ "App Builds" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Uploads a new build artifact for an app. Upload the file first with `POST /files` or a direct upload, then reference it in `attachment`.", "operationId": "createAppBuild", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "app_id": { "description": "The app to create the build for, prefixed `app_`. Defaults to the app behind the presented credential.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "attachment": { "description": "The uploaded build file: pass `id` for an existing file or `direct_upload_id` for a completed direct upload. iOS and Android builds take a .zip bundle; web builds take a JavaScript file or a .zip archive of the hosted site.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "checksum": { "description": "A client-generated checksum of the build file, used to verify file integrity when unpacked.", "example": "xxxxxxxxxxxxxxx", "type": "string" }, "platform": { "description": "The target platform for the build.", "enum": [ "ios", "android", "web" ], "example": "web", "type": "string" }, "source_attachment": { "description": "An optional compressed archive (.zip or .gz) of the source code that produced this build, stored alongside the build so it can be downloaded later. Referenced like `attachment`, and must be a different file.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "supported_app_view_types": { "description": "The view types this build supports. Only list the ones its code implements.", "items": { "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "example": "hub", "type": "string" }, "type": "array" } }, "required": [ "attachment", "checksum", "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "app build created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the build-management scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Create App Build", "tags": [ "App Builds" ] }, "x-whop-surface": "native" }, "/app_builds/{id}": { "get": { "description": "Retrieves the details of an existing app build.", "operationId": "retrieveAppBuild", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "app build retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the build-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app build with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Retrieve App Build", "tags": [ "App Builds" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App build ID, prefixed `abld_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/app_builds/{id}/promote": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App build ID, prefixed `abld_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Promotes a draft or approved app build to production so it becomes the active version served to users. Draft builds enter review first.", "operationId": "promoteAppBuild", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppBuild" } } }, "description": "app build promotion started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the build cannot be promoted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the build-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app build with that ID exists" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Promote App Build", "tags": [ "App Builds" ] }, "x-whop-surface": "native" }, "/app_installations": { "get": { "description": "Lists app installations, newest first. An app's API key lists the accounts that installed it. An account lists the apps installed on it; a user passes that account's `account_id`. The developer of an app lists every installation of it by passing `app_id`. Uninstalled apps, deleted apps and deleted accounts are left out.", "operationId": "listAppInstallations", "parameters": [ { "description": "Only return installations on this account, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return installations of this app, prefixed `app_`. Pass your own app's ID to list the accounts that installed it.", "in": "query", "name": "app_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return installations of apps that have this view, such as `dashboard` for apps shown in a business's dashboard.", "in": "query", "name": "view_type", "required": false, "schema": { "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "type": "string" } }, { "description": "Only return the installation with this `external_id`, the installed app's own identifier for it. Only the app and its developer can filter by it.", "in": "query", "name": "external_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return installations created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return installations created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "Field to sort installations by. `name` sorts by app name, and only when listing the apps installed on one account.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "name" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AppInstallation" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "app installations listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the list needs an account, or filters by data only the app and its developer see" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the caller cannot read app installations on the account" } }, "security": [ { "bearerAuth": [ "developer:app_installation:read" ] }, { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "developer:basic:read" ] } ], "summary": "List App Installations", "tags": [ "App Installations" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/app_installations/{id}": { "get": { "description": "Retrieves an app installation, with the metadata the app stores on it. The app, its developer and the account it's installed on can retrieve it.", "operationId": "retrieveAppInstallation", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInstallation" } } }, "description": "app installation retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the caller cannot read this installation" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the installation does not belong to this app or is no longer active" } }, "security": [ { "bearerAuth": [ "developer:app_installation:read" ] }, { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "developer:basic:read" ] } ], "summary": "Retrieve App Installation", "tags": [ "App Installations" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App installation ID, prefixed `aag_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates the `metadata` and `external_id` your app keeps on an installation. Only the metadata keys you send change, so separate jobs can each keep their own keys.", "operationId": "updateAppInstallation", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "external_id": { "description": "Your app's own identifier for this installation, such as the ID of the linked account in another system, or `null` when none is set. At most 255 characters and unique across your app's installations, so you can find an installation with `GET /app_installations?external_id=`; setting one another installation already has returns a `409`. Only the app and its developer see it; for the account the app is installed on it is always `null`.", "example": "acme-store", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": [ "string", "null" ] }, "description": "Metadata keys to set, as string values. A key set to `null` is removed and keys you leave out don't change; an empty object clears every key. At most 50 keys; keys are at most 100 characters and values at most 500.", "example": { "last_synced_at": "2026-10-16T21:00:00Z" }, "type": "object" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInstallation" } } }, "description": "app installation updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the update is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the caller is not the app, or its key doesn't grant the update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the installation does not belong to this app" }, "409": { "$ref": "#/components/responses/Conflict", "description": "another installation of this app already has the external_id" } }, "security": [ { "bearerAuth": [ "developer:app_installation:update" ] } ], "summary": "Update App Installation", "tags": [ "App Installations" ], "x-whop-credentials": [ "app_api_key" ] }, "x-whop-surface": "native" }, "/apps": { "get": { "description": "Lists apps on the Whop platform: the app store's live apps, or — with `account_id` and developer access to that account — every app the account owns. Requires authentication except for Whop's public app and website discovery lists. Public website discovery includes built official blueprints (verified apps with a product) and built, live community blueprints that Whop recommends.", "operationId": "listApps", "parameters": [ { "description": "Only return apps created by this account (`biz_` tag). With developer access to the account this includes its unlisted and hidden apps.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter apps by the type of end-user they are built for. Apps of type `website` are left out unless you ask for them by name.", "in": "query", "name": "app_type", "required": false, "schema": { "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "type": "string" } }, { "description": "Only return apps supporting this view type, such as `dashboard` or `hub`.", "in": "query", "name": "view_type", "required": false, "schema": { "enum": [ "hub", "discover", "dash", "dashboard", "analytics", "skills", "openapi" ], "type": "string" } }, { "description": "Only return apps whose Whop verification status matches this value. Omit this filter to include every verification status the caller can see.", "in": "query", "name": "verified", "required": false, "schema": { "type": "boolean" } }, { "deprecated": true, "description": "Legacy compatibility filter. Use `verified` for field equality. `true` returns verified apps; clients pinned before `2026-08-25-2` retain the earlier public website discovery behavior.", "in": "query", "name": "verified_apps_only", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return apps Whop recommends (or, with `false`, only those it does not), independently of verification status.", "in": "query", "name": "recommended", "required": false, "schema": { "type": "boolean" } }, { "description": "A search string matched against app names.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort apps by. Defaults to discoverable_at, showing the most recently published apps first. `template_usage` ranks Whop-verified apps first, then by how many businesses created apps from each app as a template. `template_recent_sales` ranks them by how many of those businesses processed a payment in the last 24 hours, recounted hourly, breaking ties by `template_usage`.", "in": "query", "name": "order", "required": false, "schema": { "default": "discoverable_at", "enum": [ "created_at", "discoverable_at", "template_recent_sales", "template_usage", "total_installs_last_30_days", "total_installs_last_7_days" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AppListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "Mg", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "apps listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Apps", "tags": [ "Apps" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Registers a new app on the Whop developer platform. Apps provide custom experiences that can be added to products.", "operationId": "createApp", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to create the app for (`biz_` tag). Defaults to the account behind the presented credential.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "app_type": { "default": "b2c_app", "description": "The type of app to create. Defaults to `b2c_app`.", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "example": "website", "type": "string" }, "base_url": { "description": "The base production URL where the app is hosted, such as `https://myapp.example.com`.", "type": [ "string", "null" ] }, "domain_id": { "description": "A domain on the account (`dom_` tag) to serve the app at, such as a whop.site address claimed with `POST /domains`. Required with `template_id`.", "example": "dom_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "icon": { "description": "The icon image for the app in PNG, JPEG, or GIF format, referencing an uploaded file: `{ id }` for an existing attachment or `{ direct_upload_id }` for a new direct upload.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "imported_from_url": { "description": "The address of the existing website this app is imported from, such as `https://shop.example.com`. Must be an `http` or `https` URL.", "example": "https://shinetime.example", "type": [ "string", "null" ] }, "name": { "description": "The display name for the app, shown to users on the app store and product pages.", "example": "Shine Time Booking", "type": "string" }, "redirect_uris": { "description": "The whitelisted OAuth callback URLs that users are redirected to after authorizing the app.", "items": { "example": "https://booking.shinetime.example/oauth/callback", "type": "string" }, "type": "array" }, "route": { "deprecated": true, "description": "Deprecated: claim an address with `POST /domains` and pass `domain_id`. The subdomain route where the app's hosted web builds are served, such as `myapp` for myapp.whop.site.", "example": "shine-time-booking-site", "type": [ "string", "null" ] } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "app created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the app-creation scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no account with that ID exists" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:create_app" ] } ], "summary": "Create App", "tags": [ "Apps" ] }, "x-whop-surface": "native" }, "/apps/{id}": { "delete": { "description": "Deletes an app. The app stops resolving within seconds — a website's site stops serving, and any claimed subdomain is reserved for a month before it can be claimed again.", "operationId": "deleteApp", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted app.", "example": "app_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "app deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the app-update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:update_app" ] } ], "summary": "Delete App", "tags": [ "Apps" ] }, "get": { "description": "Retrieves an app by ID, claimed route, active verified custom hostname, or proxy domain id. Authentication is optional; credential fields stay `null` unless you have the matching developer permission on the owning account.", "operationId": "retrieveApp", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "app retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ {}, { "bearerAuth": [] } ], "summary": "Retrieve App", "tags": [ "Apps" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App ID (prefixed `app_`). Retrieval also accepts the app's claimed route, an active verified custom hostname, or its proxy domain id; a custom hostname returns `404` when its assignment is inactive, the owning account is suspended, or the app is deleted.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates the settings, metadata, or status of an app. Fields that are omitted keep their current value.", "operationId": "updateApp", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "app_store_description": { "description": "The detailed description shown on the app store's in-depth app view page.", "example": "Shine Time Booking turns a whop into a booking calendar. Members pick a package, choose a slot that fits the day's route, and pay up front.", "type": "string" }, "app_type": { "description": "The type of end-user the app is built for. Cannot be changed on an app whose type is already `website`.", "enum": [ "b2b_app", "b2c_app", "company_app", "component", "website" ], "example": "b2c_app", "type": "string" }, "base_url": { "description": "The base production URL where the app is hosted. Set to `null` to take the app proxy offline.", "example": "https://shine-time-booking.whop.site", "type": [ "string", "null" ] }, "dashboard_path": { "description": "The URL path for the account dashboard view.", "example": "/dashboard/[companyId]", "type": [ "string", "null" ] }, "description": { "description": "A short description of the app shown in listings and search results.", "example": "Let members book a mobile detailing appointment without leaving your whop.", "type": "string" }, "discover_path": { "description": "The URL path for the discover view.", "example": "/discover", "type": [ "string", "null" ] }, "experience_path": { "description": "The URL path for the member-facing hub view, such as `/experiences/[experienceId]`.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "icon": { "description": "The icon image for the app in PNG, JPEG, or GIF format, referencing an uploaded file: `{ id }` for an existing attachment or `{ direct_upload_id }` for a new direct upload.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "imported_from_url": { "description": "The address of the existing website this app is imported from, such as `https://shop.example.com`. Must be an `http` or `https` URL. Set to `null` to clear it.", "example": "https://shinetime.example", "type": [ "string", "null" ] }, "name": { "description": "The display name for the app, shown to users on the app store and product pages.", "example": "Shine Time Booking Pro", "type": "string" }, "oauth_client_type": { "description": "How the app authenticates at the OAuth token endpoint.", "enum": [ "public", "confidential" ], "example": "confidential", "type": "string" }, "openapi_path": { "description": "The URL path to the app's OpenAPI spec file (requires the ai_chat capability).", "example": "/openapi.json", "type": [ "string", "null" ] }, "per_install_schedule": { "description": "Five-field cron expression, read in UTC, on which Whop runs the production web build's `scheduled()` export once for every installation, with the installation in `ctx.props.app_installation`. It must fire at least once and no more often than every 15 minutes. Slots are skipped while the app has no production web build with a server entry. Set to `null` or an empty string to stop the per-install schedule.", "example": "*/15 * * * *", "maxLength": 64, "type": [ "string", "null" ] }, "production_android_build_id": { "description": "The app build (`abld_` tag) to serve as the Android production build, or `null` to unassign it. Same rules as `production_web_build_id`.", "example": "apbu_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "production_ios_build_id": { "description": "The app build (`abld_` tag) to serve as the iOS production build, or `null` to unassign it. Same rules as `production_web_build_id`.", "example": "apbu_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "production_web_build_id": { "description": "The app build (`abld_` tag) to serve as the web production build, or `null` to unassign it. The build must belong to this app, target web, and be in the draft or approved status; a draft build is queued for approval and takes over once approved. Requires the `developer:manage_builds` scope.", "example": "apbu_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_uris": { "description": "The whitelisted OAuth callback URLs users are redirected to after authorizing the app.", "items": { "example": "https://booking.shinetime.example/oauth/callback", "type": "string" }, "type": "array" }, "required_scopes": { "description": "The OAuth scopes the app requests from users when they install it.", "items": { "example": "read_user", "type": "string" }, "type": "array" }, "route": { "description": "The subdomain route where the app's hosted web builds are served.", "example": "shine-time-booking-pro", "type": "string" }, "schedule": { "description": "Five-field cron expression, read in UTC, on which Whop runs the production web build's `scheduled()` export once per slot, such as `*/15 * * * *`. It must fire at least once. Slots are skipped while the app has no production web build with a server entry. Set to `null` or an empty string to stop the global schedule.", "example": "0 * * * *", "maxLength": 64, "type": [ "string", "null" ] }, "secrets": { "description": "Secrets to add or overwrite on the app, as an object of string values. Keys not included are left untouched; pass null or an empty string as the value to delete a secret. Encrypted at rest and injected into the app's hosted server runtime.", "example": { "BOOKING_CALENDAR_ID": "cal_9f21" }, "type": "object" }, "skills_path": { "description": "The URL path to the app's skills directory (requires the ai_chat capability).", "example": "/skills", "type": [ "string", "null" ] }, "status": { "description": "Controls whether the app is published on Whop discovery or accessible only through its direct link. Publishing requires a name, icon, and description.", "enum": [ "live", "unlisted", "hidden" ], "example": "unlisted", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "app updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the app-update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:update_app" ] } ], "summary": "Update App", "tags": [ "Apps" ] }, "x-whop-surface": "native" }, "/apps/{id}/deploy": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The app to deploy, prefixed `app_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Builds the app's current source and ships it. Returns the run it started, so the caller can render progress from this response and then follow it on the app's `deployment` field. Only one deployment runs per app at a time — calling this while one is in flight reports that run rather than starting a second, and calling it with nothing to publish reports that instead of starting one.", "operationId": "deployApp", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "draft": { "description": "Upload the build without making it live. Defaults to `false`, which deploys and promotes in one step.", "example": false, "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDeployment" } } }, "description": "deployment started" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_builds" ] } ], "summary": "Deploy App", "tags": [ "Apps" ], "x-whop-credentials": [] }, "x-whop-surface": "native" }, "/apps/{id}/logs": { "get": { "description": "Lists a hosted app's server runtime logs, most recent first: console output, uncaught exceptions, and failed-request summaries captured on whop.site hosting. Logs are retained for 7 days.", "operationId": "listAppLogs", "parameters": [ { "description": "The ID of the app, which will look like app_*************.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Only return logs from this build.", "in": "query", "name": "app_build_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return console lines of this level.", "in": "query", "name": "level", "required": false, "schema": { "enum": [ "log", "debug", "info", "warn", "error" ], "type": "string" } }, { "description": "Only return logs whose message contains this text (case-insensitive).", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Start of the time window as an ISO 8601 timestamp. Defaults to 7 days before created_before.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "End of the time window as an ISO 8601 timestamp. Defaults to now.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 100, "maximum": 500, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "app_build_id": { "example": "abld_123", "type": "string" }, "app_id": { "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "cpu_time_ms": { "example": 8, "type": "integer" }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "level": { "enum": [ "log", "debug", "info", "warn", "error" ], "example": "error", "type": "string" }, "message": { "example": "TypeError: Cannot read properties of undefined (reading 'slotId')", "type": "string" }, "outcome": { "example": "exception", "type": [ "string", "null" ] }, "request_id": { "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "request_method": { "example": "GET", "type": [ "string", "null" ] }, "request_path": { "example": "/api/slots", "type": [ "string", "null" ] }, "response_status": { "example": 500, "type": [ "integer", "null" ] }, "source": { "enum": [ "console", "exception", "request" ], "example": "exception", "type": "string" }, "stack": { "example": "TypeError: Cannot read properties of undefined (reading 'slotId')\n at renderBookingSlot (/worker/booking.js:118:24)\n at handleRequest (/worker/index.js:42:11)", "type": [ "string", "null" ] }, "truncated": { "example": false, "type": "boolean" }, "wall_time_ms": { "example": 31, "type": "integer" } }, "required": [ "app_id", "app_build_id", "request_id", "created_at", "source", "level", "message" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_end", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_start", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "logs listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing the developer:logs:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "app not found" } }, "security": [ { "bearerAuth": [ "developer:logs:read" ] } ], "summary": "List App Logs", "tags": [ "Apps" ] }, "x-whop-surface": "native" }, "/apps/{id}/permissions": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App ID, prefixed `app_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Replaces the set of permissions the app requests from users when they install it. Requires a user session: the `developer:update_app_authorization` scope cannot be delegated to API keys. Sensitive permissions require step-up verification.", "operationId": "updateAppPermissions", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "requested_permissions": { "description": "The full set of permissions the app requests on install; permissions not listed are removed.", "items": { "properties": { "action": { "description": "The permission action, for example `company:basic:read`.", "example": "company:basic:read", "type": "string" }, "is_required": { "description": "Whether installing the app requires granting this permission.", "example": true, "type": "boolean" }, "justification": { "description": "Why the app needs this permission (20-512 characters), shown to the installing user.", "example": "Reads basic account info to render the dashboard home.", "type": "string" } }, "required": [ "action", "is_required", "justification" ], "type": "object" }, "type": "array" } }, "required": [ "requested_permissions" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } }, "description": "requested permissions updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the app-authorization scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no app with that ID exists" } }, "security": [ { "bearerAuth": [ "developer:update_app_authorization" ] } ], "summary": "Update App Permissions", "tags": [ "Apps" ], "x-whop-credentials": [] }, "x-whop-surface": "native" }, "/audiences": { "get": { "description": "Lists an account's custom and lookalike audiences.", "operationId": "listAudiences", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Audience ID, prefixed `adaud_`, used to filter the response to one audience.", "in": "query", "name": "audience_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by custom or lookalike audiences.", "in": "query", "name": "audience_type", "required": false, "schema": { "enum": [ "custom", "lookalike" ], "type": "string" } }, { "description": "Filter by uploaded customer lists, Whop People filters, or social engagement.", "in": "query", "name": "source_type", "required": false, "schema": { "enum": [ "csv_upload", "people_filter", "engagement" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Audience" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Audiences listed." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." } }, "security": [ { "bearerAuth": [ "audience:basic:read" ] } ], "summary": "List Audiences", "tags": [ "Audiences" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a custom audience from a customer list, your account's Whop People data, or engagement with videos, lead forms, Instagram profiles, or Facebook pages, or a lookalike audience that reaches people similar to an existing one. Processing runs asynchronously. A custom audience returns one audience; a lookalike returns the requested similarity bands in `data`.", "operationId": "createAudience", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "engagement": { "include": [ { "event": "engaged", "external_account_id": "sacc_xxxxxxxxxxxxxx", "object": "facebook_page", "retention_days": 30 } ], "platform": "meta" }, "name": "Page engagers", "source_type": "engagement" }, "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "audience_type": { "description": "Audience type. Defaults to `custom`.", "enum": [ "custom", "lookalike" ], "example": "lookalike", "type": "string" }, "auto_refresh": { "description": "Filter audiences only, and set only at creation. `true` (the default) rebuilds membership from the filters twice a day. `false` keeps whoever matched at creation and never rebuilds.", "example": true, "type": "boolean" }, "column_mapping": { "description": "CSV audiences only. Maps supported identity fields to CSV column headers. Map at least one of `email` or `phone`.", "properties": { "country": { "description": "CSV header for ISO 3166-1 alpha-2 country codes, such as `US`.", "example": "Country", "type": "string" }, "email": { "description": "CSV header for email addresses.", "example": "Email", "type": "string" }, "first_name": { "description": "CSV header for first names.", "example": "First Name", "type": "string" }, "last_name": { "description": "CSV header for last names.", "example": "Last Name", "type": "string" }, "ltv": { "description": "CSV header for each customer's lifetime value — a non-negative number, currency symbols allowed. When mapped, Meta creates the audience as value-based, so lookalikes built from it favor people similar to the highest-value customers.", "example": "Lifetime Value", "type": "string" }, "phone": { "description": "CSV header for phone numbers.", "example": "Phone", "type": "string" } }, "type": "object" }, "count": { "description": "Lookalikes only. Number of lookalike audiences to create (1–6).", "example": 3, "type": "integer" }, "engagement": { "additionalProperties": false, "description": "Rules for membership based on social engagement. Requires a connected social account with advertising access.", "properties": { "exclude": { "description": "Exclude anyone matching any exclusion rule. Defaults to an empty array. Video audiences do not support exclusions; use a separate audience in ad-group exclusions.", "items": { "$ref": "#/components/schemas/AudienceEngagementRule" }, "maxItems": 10, "type": "array" }, "include": { "description": "Match any inclusion rule. Video rules must share a retention window and cannot be combined with other sources.", "items": { "$ref": "#/components/schemas/AudienceEngagementRule" }, "maxItems": 10, "minItems": 1, "type": "array" }, "platform": { "description": "Ad platform that maintains membership.", "enum": [ "meta" ], "example": "meta", "type": "string" } }, "required": [ "platform", "include" ], "type": "object" }, "file_id": { "description": "CSV audiences only. The uploaded customer CSV — a file id (`file_...`) returned by `POST /files`.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "filters": { "description": "Filter audiences only. The People filters that define membership, keyed exactly as `GET /people` accepts them — for example `{\"os\": \"iOS\", \"country\": \"US\"}`. Activity dates `event_from` and `event_to` are inclusive and remain fixed on refresh. Use `event_within_days`, `first_seen_within_days` or `last_seen_within_days` for a rolling window. Source values are canonical source paths (`whop:::`, `ext::...`, `referrer:`, `direct`), exact or with a trailing `:*` wildcard.", "example": { "country": "US", "last_seen_within_days": 30 }, "type": "object" }, "name": { "description": "Audience display name. Required for custom audiences; lookalike names are generated from the source audience.", "example": "Page engagers", "type": "string" }, "percentage": { "description": "Lookalikes only. Total similarity reach as a whole percent (1–20), sliced evenly across `count` — must be divisible by `count`. For example, 3 audiences at 6% creates 0–2%, 2–4%, and 4–6% bands.", "example": 6, "type": "integer" }, "source_audience_id": { "description": "Lookalikes only. The ready custom audience (`adaud_`) to build from; uploaded and People audiences need at least 100 matched people. Meta validates engagement audience eligibility when creating the lookalike.", "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "source_type": { "description": "Custom audience source. Inferred from `engagement`, then `filters`, otherwise defaults to `csv_upload`. Supply only the fields for the selected source.", "enum": [ "csv_upload", "people_filter", "engagement" ], "example": "engagement", "type": "string" } }, "required": [ "account_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Audience" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/Audience" }, "type": "array" } }, "required": [ "data" ], "type": "object" } ] } } }, "description": "Audience created. Custom creation returns one audience; lookalike creation returns an array in `data`." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Conflicting audience sources." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "audience:update" ] } ], "summary": "Create Audience", "tags": [ "Audiences" ] }, "x-whop-surface": "native" }, "/audiences/{id}": { "delete": { "description": "Deletes an audience so it is no longer available for targeting.", "operationId": "deleteAudience", "parameters": [ { "description": "Audience ID, prefixed `adaud_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Audience deleted." } }, "security": [ { "bearerAuth": [ "audience:update" ] } ], "summary": "Delete Audience", "tags": [ "Audiences" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Renames an audience. For an audience built from People filters that keeps itself up to date, pass `filters` to replace them, which rebuilds membership immediately. Whether an audience auto refreshes is set when it is created.", "operationId": "updateAudience", "parameters": [ { "description": "Audience ID, prefixed `adaud_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "filters": { "description": "Replaces the People filters that define membership. The whole definition is replaced rather than merged, so send every filter you want to keep — a filter you leave out stops applying. Keys and values are the ones `GET /people` accepts, such as an `os` of `iOS` or a `country` of `US`, and at least one filter is required. Date filters must be rolling windows — `first_seen_within_days` or `last_seen_within_days` — so the audience re-anchors every time it rebuilds; fixed dates such as `first_seen_after` are rejected, as is `audience_id`. An array value holds at most 500 items, and each value at most 10 KB. Only an audience with a `source_type` of `people_filter` and `auto_refresh` of `true` accepts filters: an uploaded list has no filters to replace, and with auto refresh off the audience keeps the people it matched when it was built, so create a new audience instead.", "example": { "country": "US", "last_seen_within_days": 60 }, "type": "object" }, "name": { "description": "New audience display name. A blank value is ignored rather than clearing the name.", "example": "Austin visitors, last 60 days", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } }, "description": "Audience updated." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." } }, "security": [ { "bearerAuth": [ "audience:update" ] } ], "summary": "Update Audience", "tags": [ "Audiences" ] }, "x-whop-surface": "native" }, "/audiences/{id}/add_people": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Adds users from a new CSV file to an existing uploaded custom audience. The file uses the audience's saved column mapping, processing happens in the background, and existing audience members remain unchanged.", "operationId": "addAudiencePeople", "parameters": [ { "description": "Audience ID, prefixed `adaud_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "file_id": { "description": "The new customer CSV — a file id (`file_...`) returned by `POST /files`. Its headers must match the audience's saved column mapping.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "file_id" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } }, "description": "Audience upload accepted." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "audience:update" ] } ], "summary": "Add People", "tags": [ "Audiences" ] }, "x-whop-surface": "native" }, "/authorized_users": { "get": { "description": "Lists the authorized users on an account's team.\n\nRequired permissions:\n - `company:authorized_user:read`\n - `member:email:read`", "operationId": "listAuthorizedUser", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Filter results to a specific user to check if they are an authorized team member.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "role", "required": false, "schema": { "$ref": "#/components/schemas/AuthorizedUserRoles", "description": "Filter authorized users by their assigned role within the company." }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return authorized users created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return authorized users created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "The unique identifier of the company to list authorized users for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for AuthorizedUser.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/AuthorizedUserListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:authorized_user:read", "member:email:read" ] } ], "summary": "List authorized users", "tags": [ "Authorized users" ], "x-group-title": "Identity" }, "post": { "description": "Adds a user to an account's team as an authorized user with the given role.\n\nRequired permissions:\n - `authorized_user:create`\n - `member:email:read`", "operationId": "createAuthorizedUser", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateAuthorizedUser", "properties": { "account_id": { "description": "The ID of the company to add the authorized user to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "elevation": { "description": "Re-authentication proof required to perform this sensitive action.", "properties": { "authenticator_data": { "description": "Ignored. Kept so existing API clients that send a passkey assertion keep working.", "type": [ "string", "null" ] }, "client_data_json": { "description": "Ignored. Kept so existing API clients that send a passkey assertion keep working.", "type": [ "string", "null" ] }, "credential_id": { "description": "Ignored. Kept so existing API clients that send a passkey assertion keep working.", "type": [ "string", "null" ] }, "email_code": { "description": "The 6-digit code emailed to the user.", "type": [ "string", "null" ] }, "signature": { "description": "Ignored. Kept so existing API clients that send a passkey assertion keep working.", "type": [ "string", "null" ] }, "totp_code": { "description": "The 6-digit code from the authenticator app or SMS.", "type": [ "string", "null" ] }, "use_finance_session": { "description": "Ignored. Kept so existing API clients that send it keep working.", "type": [ "boolean", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "role": { "$ref": "#/components/schemas/GrantableAuthorizedUserRoles", "description": "The role to assign to the authorized user within the company. Supported roles: 'moderator', 'sales_manager'." }, "send_emails": { "description": "Whether to send notification emails to the user on creation.", "type": [ "boolean", "null" ] }, "user_id": { "description": "The ID of the user to add as an authorized user.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id", "role", "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedUser" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "authorized_user:create", "member:email:read" ] } ], "summary": "Create authorized user", "tags": [ "Authorized users" ], "x-group-title": "Identity" } }, "/authorized_users/{id}": { "delete": { "description": "Removes an authorized user from an account's team.\n\nRequired permissions:\n - `authorized_user:delete`", "operationId": "deleteAuthorizedUser", "parameters": [ { "description": "The ID of the authorized user or user to remove.", "in": "path", "name": "id", "required": true, "schema": { "example": "ausr_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "The ID of the company the authorized user belongs to. Optional if the authorized user ID is provided.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "authorized_user:delete" ] } ], "summary": "Delete authorized user", "tags": [ "Authorized users" ], "x-group-title": "Identity" }, "get": { "description": "Retrieves the details of an existing authorized user.\n\nRequired permissions:\n - `company:authorized_user:read`\n - `member:email:read`", "operationId": "retrieveAuthorizedUser", "parameters": [ { "description": "The unique identifier of the authorized user to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "ausr_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedUser" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:authorized_user:read", "member:email:read" ] } ], "summary": "Retrieve authorized user", "tags": [ "Authorized users" ], "x-group-title": "Identity" } }, "/bounties": { "get": { "description": "Lists bounties visible to the credential — for an account API key, the account's bounties including scheduled drafts; for a user token, the bounties the user can see and work.", "operationId": "listBounties", "parameters": [ { "description": "Scope the list to this account (`biz_` tag). Requires read access to the account; account API keys may pass their own account or a connected account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "List the bounties this user participated in (`user_` tag). Must be the authenticated user.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by lifecycle state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "scheduled", "open", "closed", "completed", "canceled" ], "type": "string" } }, { "description": "Filter by the poster's declared goal. Bounties created before the goal taxonomy carry no goal and never match this filter.", "in": "query", "name": "business_goal_type", "required": false, "schema": { "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other" ], "type": "string" } }, { "description": "Only bounties workable from this country, as an ISO 3166-1 alpha-2 code. Bounties with no country targeting are workable worldwide and always match.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "Only bounties posted to this forum experience, prefixed `exp_`. An unknown experience, or one outside the caller's scope, matches nothing.", "in": "query", "name": "experience_id", "required": false, "schema": { "type": "string" } }, { "description": "Substring match on the bounty title or ID.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only bounties created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only bounties created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "gross_paid_out_amount", "gross_reward_amount" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BountyListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "bounties listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the bounty-read scope" } }, "security": [ { "bearerAuth": [ "bounty:basic:read" ] } ], "summary": "List Bounties", "tags": [ "Bounties" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a bounty and escrows its reward pool. Publishes immediately, or as a scheduled draft when you set `publish_at`.", "operationId": "createBounty", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "accepted_submissions_limit": { "description": "Number of submissions that can be accepted (winner slots). Defaults to 1. The escrowed total is `gross_reward_amount` times this limit and must be at least $5.", "example": 3, "type": [ "integer", "null" ] }, "accepted_submissions_per_user_limit": { "description": "How many winner slots one worker can win. Defaults to `1`. Wins plus proofs awaiting review never exceed this number, and a worker runs one attempt at a time. Cannot exceed `accepted_submissions_limit`.", "example": 2, "minimum": 1, "type": [ "integer", "null" ] }, "account_id": { "description": "Account whose balance funds the bounty pool (`biz_` tag). Defaults to the caller's personal balance. Requires permission to move the account's funds.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "allowed_country_codes": { "description": "Countries whose residents can work the bounty, as ISO 3166 alpha-2 codes. Empty means worldwide.", "items": { "example": "US", "type": "string" }, "type": [ "array", "null" ] }, "business_goal_type": { "description": "What the poster wants the work to achieve, declared once here.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other" ], "example": "clipping", "type": "string" }, "capture_spec": { "description": "Per-bounty overrides of the served capture contract. Only accepted when `business_goal_type` is `data_capture`; omitted fields keep the platform defaults, and the resulting contract is echoed back as `capture_spec` on the bounty.", "properties": { "bitrate_target_mbps": { "description": "Average bitrate the recorder encodes at, in megabits per second. Must sit within the served floor and ceiling.", "example": 12, "type": "integer" }, "embed_camera_metadata": { "description": "Whether the recorder also writes camera make and model into the video container's metadata.", "example": true, "type": "boolean" }, "frame_gap_tolerance_ms": { "description": "Longest stall between consecutive frames a clip may contain before the client rejects it, in milliseconds. Unlike the recording fields this one can also be tuned after the bounty is created, since it bounds what is accepted rather than how footage is captured.", "example": 2000, "type": "integer" }, "min_clip_duration_seconds": { "description": "Minimum length of a single clip, in seconds.", "example": 120, "type": "integer" }, "min_total_verified_duration_seconds": { "description": "Total verified footage a submission must accumulate across all its clips before it can be submitted, in seconds. Must be a whole number of hours between 1 and 12. Editable after create, until someone starts an attempt.", "example": 14400, "type": "integer" }, "stabilization_mode": { "description": "How the recorder configures video stabilization. `off` preserves raw motion for pose extraction.", "enum": [ "off", "on", "any" ], "example": "off", "type": "string" } }, "type": "object" }, "description": { "description": "Full task instructions shown to workers.", "example": "Record one continuous pass of a full interior detail, dash to trunk, on a customer vehicle.", "type": "string" }, "experience_id": { "description": "Experience to host the bounty in (`exp_` tag). Any visibility — public for an open bounty, private for an invited one. Required unless account_id is set, in which case the bounty anchors in that account's public forum.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "frequency": { "description": "How often the schedule creates a new bounty. Each occurrence is a separate bounty. Defaults to `once`; only applies with `publish_at`.", "enum": [ "once", "hourly", "daily", "weekly", "monthly" ], "example": "weekly", "type": "string" }, "gross_reward_amount": { "description": "Gross bounty-pool amount (USD) escrowed per accepted submission, in whole dollars. Platform fees and affiliate shares are paid from this amount.", "example": 40.0, "type": "number" }, "publish_at": { "description": "ISO 8601 time to publish the bounty. When set, the bounty is created as a hidden draft and funded + published at this time instead of immediately.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "publish_at_timezone": { "description": "IANA timezone for recurring occurrences. Required when publish_at is set.", "example": "America/Chicago", "type": [ "string", "null" ] }, "title": { "description": "Short name of the task shown to workers.", "example": "Record interior detailing passes", "type": "string" } }, "required": [ "title", "description", "gross_reward_amount" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "bounty created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing reward amount" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential cannot fund the requested account" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "bounty:create" ] }, { "bearerAuth": [ "payout:transfer_funds" ] } ], "summary": "Create Bounty", "tags": [ "Bounties" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/bounties/{bounty_id}/submissions": { "get": { "description": "Lists a bounty's publicly visible work — submitted, approved, and denied submissions in the reduced public shape. Authentication is optional; a bounty that is not publicly visible returns `404`.", "operationId": "listPublicBountySubmissions", "parameters": [ { "description": "The bounty whose public submissions to list (`bnty_` tag).", "in": "path", "name": "bounty_id", "required": true, "schema": { "type": "string" } }, { "description": "Filter by lifecycle state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "submitted", "approved", "denied" ], "type": "string" } }, { "description": "Only submissions created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only submissions created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "updated_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PublicBountySubmission" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "public bounty submissions listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty not found or not publicly visible" } }, "security": [ {}, { "bearerAuth": [] } ], "summary": "List Public Submissions", "tags": [ "Bounties" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/bounties/{bounty_id}/submissions/{id}": { "get": { "description": "Retrieves one of a bounty's publicly visible submissions in the reduced public shape — the read behind a shared proof link, whose submission is usually outside the bounty page's capped preview. Authentication is optional; a bounty that is not publicly visible, and a submission that is not publicly visible work on it, both return `404`.", "operationId": "retrievePublicBountySubmission", "parameters": [ { "description": "The bounty the submission belongs to (`bnty_` tag).", "in": "path", "name": "bounty_id", "required": true, "schema": { "type": "string" } }, { "description": "The submission to retrieve (`btys_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBountySubmission" } } }, "description": "public bounty submission returned" }, "404": { "$ref": "#/components/responses/NotFound", "description": "submission not found or not publicly visible" } }, "security": [ {}, { "bearerAuth": [] } ], "summary": "Retrieve Public Submission", "tags": [ "Bounties" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/bounties/{id}": { "get": { "description": "Retrieves a bounty by ID. Authentication is optional: a request with no credential reads the bounty when it is publicly visible — published or completed, and not restricted to a private experience's members. Bounties outside the caller's scope, and bounties not publicly visible to an anonymous caller, return `404`.", "operationId": "retrieveBounty", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "bounty retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty not visible to the caller" } }, "security": [ {}, { "bearerAuth": [ "bounty:basic:read" ] } ], "summary": "Retrieve Bounty", "tags": [ "Bounties" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Bounty ID (`bnty_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a bounty. A published bounty accepts title, description, and country targeting while it is still open with nothing under review. A scheduled (not-yet-published) draft additionally accepts the reward, winner slots, and schedule.", "operationId": "updateBounty", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "accepted_submissions_limit": { "description": "Scheduled drafts only. Number of submissions that can be accepted (winner slots).", "example": 3, "type": [ "integer", "null" ] }, "accepted_submissions_per_user_limit": { "description": "How many winner slots one worker can win. Defaults to `1`. Wins plus proofs awaiting review never exceed this number, and a worker runs one attempt at a time. Cannot exceed `accepted_submissions_limit`. Editable while the bounty is still open with nothing under review.", "example": 2, "minimum": 1, "type": [ "integer", "null" ] }, "allowed_country_codes": { "description": "Replace the countries whose residents can work the bounty, as ISO 3166 alpha-2 codes. Empty means worldwide.", "items": { "example": "US", "type": "string" }, "type": [ "array", "null" ] }, "business_goal_type": { "description": "What the poster wants the work to achieve, declared once here.", "enum": [ "clipping", "post_engagement", "owned_account_growth", "ugc_content", "local_activation", "data_capture", "other" ], "example": "data_capture", "type": "string" }, "description": { "description": "New full task instructions.", "example": "Record one continuous pass of a full interior detail, dash to trunk, on a customer vehicle.", "type": "string" }, "frequency": { "description": "Scheduled drafts only. How often the schedule creates a new bounty.", "enum": [ "once", "hourly", "daily", "weekly", "monthly" ], "example": "weekly", "type": "string" }, "gross_reward_amount": { "description": "Scheduled drafts only. Gross bounty-pool amount (USD) escrowed per accepted submission. The escrowed total (this times accepted_submissions_limit) must stay at least $5.", "example": 40.0, "type": [ "number", "null" ] }, "publish_at": { "description": "Scheduled drafts only. New ISO 8601 time to publish the draft. Must be in the future.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "publish_at_timezone": { "description": "Scheduled drafts only. IANA timezone for recurring occurrences.", "example": "America/Chicago", "type": [ "string", "null" ] }, "title": { "description": "New short name of the task.", "example": "Record interior detailing passes", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "bounty updated" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty the caller cannot manage" } }, "security": [ { "bearerAuth": [ "bounty:update" ] } ], "summary": "Update Bounty", "tags": [ "Bounties" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/bounties/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Bounty ID (`bnty_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Cancels a bounty. With no in-flight work, it cancels immediately and refunds the funder. Otherwise it stops new submissions and cancels once the in-flight work resolves and pays out. Repeating the request is a no-op. A bounty that already paid out every slot returns `400`.", "operationId": "cancelBounty", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bounty" } } }, "description": "cancellation requested" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "bounty already completed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks fund authority on the funding account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty outside the caller's scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "bounty:basic:read", "payout:transfer_funds" ] } ], "summary": "Cancel", "tags": [ "Bounties" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/bounty_submissions": { "get": { "description": "Lists bounty submissions visible to the credential — for a user token, the submissions they authored plus those on bounties they posted; for an account API key, the submissions on the account's bounties. For the anonymous view of one bounty's reviewed work, use the submissions list under the bounty instead.", "operationId": "listBountySubmissions", "parameters": [ { "description": "Scope the list to submissions on this account's bounties (`biz_` tag). Requires read access to the account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only submissions on this bounty (`bnty_` tag).", "in": "query", "name": "bounty_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by lifecycle state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "in_progress", "submitted", "approved", "denied" ], "type": "string" } }, { "description": "Only submissions created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only submissions created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "updated_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BountySubmission" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "bounty submissions listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the bounty-read scope" } }, "security": [ { "bearerAuth": [ "bounty:basic:read" ] } ], "summary": "List Bounty Submissions", "tags": [ "Bounty Submissions" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a submission on a workforce bounty. Include a `deliverable` and the submission goes straight to review; create is the only step. For `data_capture` bounties, omit the deliverable: this starts a claimed attempt whose proof accumulates server-side, and `POST /bounty_submissions/:id/submit` sends it to review once complete. Requires a user credential — account API keys cannot author submissions.", "operationId": "createBountySubmission", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "affiliate_code": { "description": "Affiliate code crediting the referrer, when the worker arrived through one.", "example": "tanyacole", "type": [ "string", "null" ] }, "bounty_id": { "description": "The bounty to submit to (`bnty_` tag).", "example": "bnty_xxxxxxxxxxxxxx", "type": "string" }, "deliverable": { "description": "The submitted work. Combine `urls`, `file_ids`, and `caption` freely; at least one link or file is required.", "properties": { "caption": { "description": "Written context shown to reviewers alongside the work.", "example": "Ceramic coating reveal, shot at the Burnet Rd bay", "type": [ "string", "null" ] }, "file_ids": { "description": "IDs of uploaded files attached as work, up to 10, each prefixed `file_`. Combinable with `urls` and `caption`.", "items": { "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "type": { "description": "Legacy shape selector; no longer selects anything. When present it must name an inline shape (`content_url` or `media`).", "enum": [ "content_url", "media", null ], "example": "content_url", "type": [ "string", "null" ] }, "urls": { "description": "Links to the posted work, up to 10. Combinable with `file_ids` and `caption`.", "items": { "example": "https://youtube.com/shorts/2", "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] }, "metadata": { "description": "Optional capture metadata describing where and how the footage was recorded. Persisted on the submission. On a `data_capture` bounty every field except `fov` is required whenever metadata is provided.", "properties": { "city": { "description": "City the footage was recorded in.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Country the footage was recorded in.", "example": "US", "type": [ "string", "null" ] }, "device": { "description": "Device the footage was recorded on.", "example": "iPhone 15 Pro", "type": [ "string", "null" ] }, "fov": { "description": "Horizontal field of view in degrees.", "example": 120, "type": [ "integer", "null" ] }, "operator": { "description": "Identifier of the person who recorded the footage.", "example": "mwebb", "type": [ "string", "null" ] }, "site": { "description": "Site or venue the footage was recorded at.", "example": "BurnetRd", "type": [ "string", "null" ] }, "station": { "description": "Station or position within the site.", "example": "Bay2", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "required": [ "bounty_id" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BountySubmission" } } }, "description": "submission created with an inline deliverable" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "deliverable type must name an inline shape" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "user credential lacks the submission-create scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "bounty not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "bounty:submission:create" ] } ], "summary": "Create Bounty Submission", "tags": [ "Bounty Submissions" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/bounty_submissions/{id}": { "delete": { "description": "Cancels the caller's own active attempt on a bounty and discards any accumulated capture clips. Only the worker who started the attempt can cancel it — account API keys cannot.", "operationId": "cancelBountySubmission", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the cancelled submission.", "example": "btys_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "attempt cancelled" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "only the submission's own worker can cancel it" }, "404": { "$ref": "#/components/responses/NotFound", "description": "submission not found" } }, "security": [ { "bearerAuth": [ "bounty:submission:delete" ] } ], "summary": "Cancel Bounty Submission", "tags": [ "Bounty Submissions" ], "x-whop-credentials": [ "oauth_token" ] }, "get": { "description": "Retrieves one bounty submission the credential can see — one the caller authored, or one on a bounty they posted or their account owns. Reading another member's work on an account's bounty takes `account_id`, the same way the list does.", "operationId": "retrieveBountySubmission", "parameters": [ { "description": "Read the submission as this account (`biz_` tag), scoping the lookup to its bounties rather than the caller's own work. Requires read access to the account. Without it the lookup covers only what the credential owns — the submissions the caller authored plus those on bounties they posted.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BountySubmission" } } }, "description": "bounty submission returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "404": { "$ref": "#/components/responses/NotFound", "description": "submission not visible to the credential" } }, "security": [ { "bearerAuth": [ "bounty:basic:read" ] } ], "summary": "Retrieve Bounty Submission", "tags": [ "Bounty Submissions" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The bounty submission to act on (`btys_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/bounty_submissions/{id}/submit": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The claimed attempt to submit for review (`btys_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Submits a claimed attempt for review. A livestream attempt needs an ended proof stream and can attach a `deliverable`; a data capture attempt instead needs enough validated clip time and takes no payload. Only the worker who started the attempt can submit it — account API keys cannot.", "operationId": "submitBountySubmission", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "deliverable": { "description": "Work to attach to a livestream attempt. Combine `urls`, `file_ids`, and `caption` freely; all are optional. If the attempt already went to review when its stream ended, the deliverable attaches to it once, until reviewers start voting. Data capture attempts take no deliverable.", "properties": { "caption": { "description": "Written context shown to reviewers alongside the work.", "example": "Full interior detail, start to finish, on a 2019 Tacoma.", "type": [ "string", "null" ] }, "file_ids": { "description": "IDs of uploaded files attached as work, up to 10, each prefixed `file_`. Combinable with `urls` and `caption`.", "items": { "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "urls": { "description": "Links to the posted work, up to 10. Combinable with `file_ids` and `caption`.", "items": { "example": "https://youtube.com/shorts/4", "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BountySubmission" } } }, "description": "attempt submitted for review" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the attempt has not accumulated enough proof to submit" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "only the attempt's own worker can submit it" }, "404": { "$ref": "#/components/responses/NotFound", "description": "submission not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the submission's evidence is already frozen" } }, "security": [ { "bearerAuth": [ "bounty:submission:create" ] } ], "summary": "Submit Bounty Submission", "tags": [ "Bounty Submissions" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/card_transactions": { "get": { "description": "Lists the card transactions of an account or a user, newest first. Covers every card the owner has ever had, including canceled cards and spend that predates a re-application, and team members only see transactions on the cards assigned to them. Pass `transaction_ids` to fetch specific transactions instead of paging for them.", "operationId": "listCardTransactions", "parameters": [ { "description": "The account whose card transactions to list, prefixed `biz_`. Provide this or `user_id`. Defaults to the credential's account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The user whose personal card transactions to list, prefixed `user_`. Provide this or `account_id`. Only that user can read them.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Return only these card transactions, each prefixed `citx_`. Repeat the parameter, or pass one comma-separated value.", "in": "query", "name": "transaction_ids", "required": false, "schema": { "items": { "example": "citx_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Return only transactions charged to these cards, each prefixed `icrd_`.", "in": "query", "name": "card_id", "required": false, "schema": { "items": { "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Return only transactions on cards assigned to these users, each prefixed `user_`.", "in": "query", "name": "cardholder_id", "required": false, "schema": { "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Return only transactions with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "completed", "reversed", "declined" ], "type": "string" } }, { "description": "Return only transactions authorized at or after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Return only transactions authorized at or before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by. Defaults to `created_at`.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction. Defaults to `desc`.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CardTransaction" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "no owner passed falls back to the credential's account" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "transaction_ids is not a card transaction id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "not authorized for the scope" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "List Card Transactions", "tags": [ "Cards" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/card_transactions/{id}": { "get": { "description": "Retrieves a single card transaction from any card the owner has ever had, including canceled cards. Team members can retrieve only transactions on the cards assigned to them.", "operationId": "retrieveCardTransaction", "parameters": [ { "description": "The account that owns the transaction, prefixed `biz_`. Provide this or `user_id`. Defaults to the credential's account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The user that owns the transaction, prefixed `user_`. Provide this or `account_id`. Only that user can read it.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardTransaction" } } }, "description": "card transaction found" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "not authorized for the scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "card transaction belongs to another owner" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve Card Transaction", "tags": [ "Cards" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The card transaction ID, prefixed `citx_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/cards": { "get": { "description": "Lists the Whop cards of an account or user, including ones still being set up. Team members only see the cards assigned to them.", "operationId": "listCards", "parameters": [ { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2029", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "8319", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Detailing supplies", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "type": "string" }, "cvc": { "description": "Card verification code.", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 0, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "invited", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "cards listed for an assigned cardholder without the ledger scope" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither account_id nor user_id provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout-account-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no ledger for that owner is visible to the credential" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "List Cards", "tags": [ "Cards" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Issues a virtual card, or applies for card issuing. An account with no application files one here and gets back a `202`; call again to issue the card once it is approved. An account whose application was denied or canceled applies again the same way, replacing that application.", "operationId": "createCard", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "assigned_user_id": { "description": "The account member (a user_ identifier) to assign the card to. Required for business card issuing accounts. When this call files the card application, the member applies with their identity; a company API key that sends neither this nor kind is refused.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "billing": { "description": "The card's initial billing address. On a company card it also registers the assigned member as a cardholder if they are not one yet. For an individual card, region is also required.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": "string" }, "country_code": { "description": "Billing country code, ISO 3166-1 alpha-2.", "example": "US", "type": "string" }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": "string" }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": "string" }, "region": { "description": "Billing region or state. Required for an individual card.", "example": "TX", "type": "string" } }, "required": [ "line1", "city", "postal_code", "country_code" ], "type": "object" }, "cardholder": { "description": "Details for a company card's assigned member when they are not registered as a cardholder yet. Send with billing to register them and start provisioning in one call instead of sending them an onboarding invitation. The legal name comes from the member's approved identity verification when they have one, and from these fields when they do not.", "properties": { "email": { "description": "The member's email address. Defaults to the email on their user.", "example": "marcus@shinetime.example", "type": "string" }, "first_name": { "description": "The member's legal first name.", "example": "Tanya", "type": "string" }, "last_name": { "description": "The member's legal last name.", "example": "Cole", "type": "string" }, "phone": { "description": "The member's phone number.", "example": "+xxxxxxxxxxx", "type": "string" } }, "type": "object" }, "kind": { "description": "Who the card application verifies, set only on the call that files it; sending it while the account's application is in progress or approved is a 400. `business` applies as the account with its approved KYB. `individual` applies as a person: assigned_user_id when given, otherwise the account owner, using the identity verified on the account. Omit it to apply as the business when its KYB is approved, and as an individual otherwise.", "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "name": { "description": "A display name for the card.", "example": "Detailer card", "type": "string" }, "spend_limit": { "description": "Spending limit amount, in dollars.", "example": 500, "type": "number" }, "spend_limit_frequency": { "description": "The window the spend limit applies to.", "enum": [ "daily", "weekly", "monthly", "one_time" ], "example": "weekly", "type": "string" }, "transaction_limit": { "description": "Per-transaction limit amount, in dollars.", "example": 200, "type": "number" }, "user_id": { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2030", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 2500.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "monthly", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Detailing supplies", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "type": "string" }, "cvc": { "description": "Card verification code.", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 0, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" } } }, "description": "card created" }, "202": { "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": null, "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": null, "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": null, "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": null, "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Detailer card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "type": "string" }, "cvc": { "description": "Card verification code.", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 0, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "invited", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, { "properties": { "object": { "enum": [ "card_provisioning" ], "example": "card_provisioning", "type": "string" }, "provisioning_job_id": { "description": "Background job ID to poll until the card is ready.", "example": "card-issuing-create-card-123", "type": "string" } }, "required": [ "object", "provisioning_job_id" ], "type": "object" }, { "properties": { "invitation_sent": { "description": "Always true; the member must finish onboarding before the card is issued.", "example": true, "type": "boolean" }, "object": { "enum": [ "card_invitation" ], "example": "card_invitation", "type": "string" } }, "required": [ "object", "invitation_sent" ], "type": "object" }, { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" } ] } } }, "description": "card not issued synchronously: application submitted, provisioning started, onboarding invitation sent, or onboarding completed with the card returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the card or its application cannot be created as requested" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout-account-update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no ledger for that owner is visible to the credential" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the account's card application is not approved" } }, "security": [ { "bearerAuth": [ "payout:account:update" ] } ], "summary": "Create Card", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "/cards/{id}": { "get": { "description": "Retrieves a single card, including its `secrets` (card number, CVC, and PIN), which List Cards does not return.", "operationId": "retrieveCard", "parameters": [ { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" } } }, "description": "card retrieved with its PIN by the assigned cardholder" }, "404": { "$ref": "#/components/responses/NotFound", "description": "card not found" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve Card", "tags": [ "Cards" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Card ID to retrieve, prefixed `icrd_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates, freezes, or cancels a card. Updating the card's name, billing address, or limits requires both `payout:account:update` and `company:balance:read`; a card's assigned holder may update their own card's pin and frozen state with any user token.", "operationId": "updateCard", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "billing": { "description": "The billing address. On an issued card this replaces the card's billing address and region is also required. On an invited card, sending it as the invited user completes onboarding and starts card provisioning.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": "string" }, "country_code": { "description": "Billing country code, ISO 3166-1 alpha-2.", "example": "US", "type": "string" }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": "string" }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": "string" }, "region": { "description": "Billing region or state. Required when updating an issued card's billing address.", "example": "TX", "type": "string" } }, "required": [ "line1", "city", "postal_code", "country_code" ], "type": "object" }, "canceled": { "description": "Pass `true` to permanently cancel the card. A canceled card cannot be uncanceled. Cannot be combined with other fields.", "example": true, "type": "boolean" }, "cardholder": { "description": "Details for the invited cardholder, accepted only while completing onboarding on an invited card. The legal name comes from an approved identity verification when the invited user has one, and from these fields when they do not.", "properties": { "email": { "description": "Email address for the invited cardholder.", "example": "marcus@shinetime.example", "type": "string" }, "first_name": { "description": "Legal first name of the invited cardholder.", "example": "Tanya", "type": "string" }, "last_name": { "description": "Legal last name of the invited cardholder.", "example": "Cole", "type": "string" }, "phone": { "description": "Phone number for the invited cardholder.", "example": "+xxxxxxxxxxx", "type": "string" } }, "type": "object" }, "frozen": { "description": "Pass `true` to freeze the card, `false` to unfreeze it. The assigned cardholder may freeze their own card without the payout:account:update scope.", "example": true, "type": "boolean" }, "name": { "description": "A display name for the card.", "example": "Detailing supplies", "type": "string" }, "pin": { "description": "New 4-digit PIN. Can only be set on a card assigned to the acting user, who may set it without the payout:account:update scope.", "example": "1234", "type": "string" }, "remove_limit": { "description": "Pass `true` to remove the spending limit (make the card unlimited).", "example": true, "type": "boolean" }, "spend_limit": { "description": "Spending limit amount, in dollars.", "example": 2500.0, "type": "number" }, "spend_limit_frequency": { "description": "The window the spend limit applies to.", "enum": [ "daily", "weekly", "monthly", "one_time" ], "example": "monthly", "type": "string" }, "transaction_limit": { "description": "Per-transaction limit amount, in dollars.", "example": 500.0, "type": "number" }, "user_id": { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Detailing supplies", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "type": "string" }, "cvc": { "description": "Card verification code.", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" } } }, "description": "invited card onboarding completed: card provisioning started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid update request" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout-account-update scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "card not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the issuer declined the cardholder this card was invited for" } }, "security": [ { "bearerAuth": [ "payout:account:update" ] }, { "bearerAuth": [] } ], "summary": "Update Card", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "/cashback_rule": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a future-dated card cashback rule for your direct connected accounts, funded by the authenticated platform account. Creating a rule does not transfer funds; pay cashback out with `POST /cashback_rules/payout`. Requires `payout:transfer_funds`. Supports `Idempotency-Key` for safe retries.", "operationId": "createCashbackRule", "parameters": [ { "description": "Client-generated key for replaying the same request safely for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "description": "Optional description of the rule.", "example": "Software cashback", "maxLength": 255, "type": [ "string", "null" ] }, "expires_at": { "description": "Exclusive end, strictly later than starts_at. Omit or set null for no expiration.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "merchant_category_code": { "description": "Four-digit MCC, including leading zeros. Null matches any MCC. When both merchant filters are absent, scoped_account_id is required.", "example": "5734", "pattern": "^[0-9]{4}$", "type": [ "string", "null" ] }, "merchant_name": { "description": "Raw merchant name reported by the card provider, not the enriched display name. Omit or set null to match any merchant name. Supplied names must contain a non-whitespace character and match together with any MCC filter.", "example": "ACME SOFTWARE", "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "rate_bps": { "description": "Cashback rate in basis points: 500 means 5%.", "example": 500, "maximum": 10000, "minimum": 1, "type": "integer" }, "scoped_account_id": { "description": "Account ID, prefixed `biz_`, of one direct connected account to limit the rule to. Required when both merchant filters are omitted or `null`, in which case the rule matches all eligible transactions for that account. Otherwise, omit or set `null` to designate all direct connected accounts.", "pattern": "^biz_", "type": [ "string", "null" ] }, "starts_at": { "description": "Inclusive start, strictly later than the current time, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "rate_bps", "starts_at" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashbackRule" } } }, "description": "cashback rule created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid rule" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient funding permissions" }, "404": { "$ref": "#/components/responses/NotFound", "description": "connected account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create Cashback Rule", "tags": [ "Cashback Rules" ] }, "x-whop-surface": "native" }, "/cashback_rules": { "get": { "description": "Lists the cashback rules funded by the authenticated platform account, including scheduled, expired, and discarded rules. Requires an account-scoped credential with `payout:transfer:read`.", "operationId": "listCashbackRules", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "Field to sort by. Defaults to created_at.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CashbackRule" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": null, "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "cashback rules listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid sort order" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient read permissions" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Cashback Rules", "tags": [ "Cashback Rules" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/cashback_rules/payout": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Pays out cashback on demand from the authenticated platform's available USD balance to its direct connected accounts. Covers completed, unpaid card transactions created before the request, each under its latest matching rule, which must be funded by the authenticated platform. Filters combine, and an empty body includes every eligible transaction. Payouts process in the background and amounts are calculated then, so the response confirms queuing, not payment. If a payout fails for insufficient funds, add USD to the platform's balance. Requires `payout:transfer_funds`. Supports `Idempotency-Key`, and overlapping requests cannot pay the same card transaction twice.", "operationId": "payoutCashbackRules", "parameters": [ { "description": "Client-generated key for replaying the same request safely for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account_id": { "description": "Pay only this direct connected account.", "pattern": "^biz_", "type": [ "string", "null" ] }, "cashback_rule_id": { "description": "Pay only transactions whose winning cashback rule has this ID and is funded by the authenticated platform.", "pattern": "^cicbr_", "type": [ "string", "null" ] }, "transaction_id": { "description": "Pay only this card transaction belonging to a direct connected account.", "example": "citx_xxxxxxxxxxxxxx", "pattern": "^citx_", "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashbackPayout" } } }, "description": "queue rejected the request" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashbackPayout" } } }, "description": "payout queued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication required" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Pay Out Cashback", "tags": [ "Cashback Rules" ] }, "x-whop-surface": "native" }, "/cashback_rules/{id}": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "ID of the cashback rule, prefixed cicbr_.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates the merchant filters, description, or expiration of a cashback rule funded by the authenticated platform account; its start, rate, and accounts can't change. Omitted fields stay unchanged. Scheduled, active, and expired rules can be updated, but discarded rules can't. Updating a rule does not transfer funds. Requires `payout:transfer_funds`.", "operationId": "updateCashbackRule", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "description": "Description of the rule. Set null to clear it.", "example": "Cloud cashback", "maxLength": 255, "type": [ "string", "null" ] }, "expires_at": { "description": "Exclusive end as an ISO 8601 timestamp, strictly later than the original starts_at. May be in the past to end an active rule. Set null to remove the expiration.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "merchant_category_code": { "description": "Four-digit MCC, including leading zeros. Null matches any MCC. When both merchant filters are absent, scoped_account_id is required.", "example": "7372", "maxLength": 4, "minLength": 4, "pattern": "^[0-9]{4}$", "type": [ "string", "null" ] }, "merchant_name": { "description": "Raw merchant name reported by the card provider. Set null to match any merchant name. Supplied names must contain a non-whitespace character and match together with any MCC filter. Clearing both filters requires an existing scoped_account_id.", "example": "ACME CLOUD", "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashbackRule" } } }, "description": "cashback rule updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid update or discarded rule" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient funding permissions" }, "404": { "$ref": "#/components/responses/NotFound", "description": "cashback rule not found for this funding account" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update Cashback Rule", "tags": [ "Cashback Rules" ] }, "x-whop-surface": "native" }, "/chat_channels": { "get": { "description": "Lists the chat channels in an account.\n\nRequired permissions:\n - `chat:read`", "operationId": "listChatChannel", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_id", "required": false, "schema": { "description": "The unique identifier of a product to filter by. When set, only chat channels connected to this product are returned.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": true, "schema": { "description": "The unique identifier of the company to list chat channels for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for ChatFeed.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ChatChannelListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "List chat channels", "tags": [ "Chat channels" ], "x-group-title": "Engagement" } }, "/chat_channels/{id}": { "get": { "description": "Retrieves the details of an existing chat channel.\n\nRequired permissions:\n - `chat:read`", "operationId": "retrieveChatChannel", "parameters": [ { "description": "The unique identifier of the chat channel or experience to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] } ], "summary": "Retrieve chat channel", "tags": [ "Chat channels" ], "x-group-title": "Engagement" }, "patch": { "description": "Updates a chat channel's moderation settings, such as who can post, banned words, and media restrictions.\n\nRequired permissions:\n - `chat:moderate`", "operationId": "updateChatChannel", "parameters": [ { "description": "The unique identifier of the chat channel to update. Accepts either an experience ID (e.g. 'exp_xxxxx') or a chat channel ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateChatChannel", "properties": { "ban_media": { "description": "Whether media uploads such as images and videos are banned in this chat channel.", "type": [ "boolean", "null" ] }, "ban_urls": { "description": "Whether URLs and links are banned from being posted in this chat channel.", "type": [ "boolean", "null" ] }, "banned_words": { "description": "A list of words that are automatically blocked from messages in this chat channel. For example, ['spam', 'scam'].", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "user_posts_cooldown_seconds": { "description": "The minimum number of seconds a user must wait between sending messages in this chat channel. Pass null or 0 to remove the cooldown.", "example": 42, "type": [ "integer", "null" ] }, "who_can_post": { "description": "Controls which roles are allowed to send messages in this chat channel.", "oneOf": [ { "$ref": "#/components/schemas/WhoCanPostTypes" }, { "type": "null" } ] }, "who_can_react": { "description": "Controls which roles are allowed to add reactions to messages in this chat channel.", "oneOf": [ { "$ref": "#/components/schemas/WhoCanReactTypes" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:moderate" ] } ], "summary": "Update chat channel", "tags": [ "Chat channels" ], "x-group-title": "Engagement" } }, "/checkout_configurations": { "get": { "description": "Lists checkout configurations for an account.", "operationId": "listCheckoutConfigurations", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Only return checkout configurations for this variant ID, prefixed `plan_`.", "in": "query", "name": "variant_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return checkout configurations created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return checkout configurations created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Field used to sort checkout configurations.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction. Defaults to `desc`.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "affiliate_code": { "description": "Affiliate code applied at checkout, or `null` when none is set.", "example": "tanyacole", "type": [ "string", "null" ] }, "created_at": { "description": "When the checkout configuration was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for setup-mode payment method availability; defaults to `usd` when omitted.", "example": "usd", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout mounted from this configuration, resolved through every layer (its own overrides, the variant's, and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays this configuration's own editable override.", "properties": { "disabled": { "description": "Payment methods explicitly disabled.", "items": { "example": "crypto", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "id": { "description": "Checkout configuration ID, prefixed `ch_`.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships. `null` without the `checkout_configuration:basic:read` scope.", "example": { "booking_source": "front_desk" }, "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later.", "enum": [ "payment", "setup" ], "example": "payment", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the variant or platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for checkout.", "items": { "example": "crypto", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for checkout.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "purchase_url": { "description": "Checkout URL you can send to customers.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout, or `null` when no redirect is configured.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "three_ds_level": { "description": "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. Applies in setup mode; `null` uses frictionless 3DS. Payment mode uses the variant policy.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "updated_at": { "description": "When the checkout configuration was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "variant": { "description": "Variant used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this variant accepts local currency payments via adaptive pricing.", "example": true, "type": "boolean" }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "currency": { "description": "Three-letter ISO currency code for the variant's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based variants.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the variant currency.", "example": 0.0, "type": "number" }, "release_method": { "description": "Sales method for the variant.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59.0, "type": "number" }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "visibility", "billing_type", "release_method", "currency", "billing_period", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "adaptive_pricing_enabled" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "checkout configurations listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id missing" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "checkout_configuration:basic:read" ] } ], "summary": "List checkout configurations", "tags": [ "Checkout Configurations" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a reusable checkout configuration for an existing or inline variant. Send customers to its `purchase_url` to check out.", "operationId": "createCheckoutConfiguration", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "variant_id": "plan_xxxxxxxxxxxxx" }, "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "affiliate_code": { "description": "Affiliate code to apply to the checkout.", "example": "tanyacole", "type": [ "string", "null" ] }, "currency": { "description": "Currency used for setup-mode payment method availability.", "example": "usd", "type": [ "string", "null" ] }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships.", "example": { "booking_source": "front_desk" }, "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later. Defaults to `payment`.", "enum": [ "payment", "setup" ], "example": "payment", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` uses the variant or platform defaults.", "properties": { "disabled": { "description": "Payment method types explicitly disabled for checkout — the `type` values from the payment method types catalogue. Types Whop no longer offers, and the read-only `unknown` placeholder, are dropped.", "example": [ "paypal" ], "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "Payment method types explicitly enabled for checkout — the `type` values from the payment method types catalogue. Types Whop no longer offers, and the read-only `unknown` placeholder, are dropped.", "example": [ "card" ], "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "three_ds_level": { "description": "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. Applies in setup mode; `null` uses frictionless 3DS. Payment mode uses the variant policy.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "variant": { "description": "Variant attributes used to create or find a variant for this checkout configuration. Mutually exclusive with `variant_id`.", "properties": { "account_id": { "description": "Account ID for the inline variant, prefixed `biz_`. Defaults to the account resolved from the request.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual.", "example": 30, "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ "renewal", "one_time", null ], "example": "one_time", "type": [ "string", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the variant's prices.", "example": "usd", "type": [ "string", "null" ] }, "description": { "description": "Customer-visible variant description.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days for expiration-based variants.", "example": 365, "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Whether to create a new variant instead of reusing a matching one.", "example": true, "type": [ "boolean", "null" ] }, "initial_price": { "description": "Initial purchase price in the variant currency.", "example": 249, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value metadata stored on the variant.", "example": { "bay": "2" }, "type": [ "object", "null" ] }, "override_tax_type": { "description": "Tax classification override for this variant.", "example": "inclusive", "type": [ "string", "null" ] }, "payment_method_configuration": { "description": "Payment method overrides for the inline variant. `null` uses platform defaults.", "properties": { "disabled": { "description": "Payment method types explicitly disabled for this variant — the `type` values from the payment method types catalogue. Types Whop no longer offers, and the read-only `unknown` placeholder, are dropped.", "example": [ "paypal" ], "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "Payment method types explicitly enabled for this variant — the `type` values from the payment method types catalogue. Types Whop no longer offers, and the read-only `unknown` placeholder, are dropped.", "example": [ "card" ], "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "product_id": { "description": "Product ID the inline variant should belong to, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "release_method": { "description": "Sales method for the variant.", "enum": [ "buy_now", "waitlist", null ], "example": "buy_now", "type": [ "string", "null" ] }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59, "type": [ "number", "null" ] }, "stock": { "description": "Units available for purchase.", "example": 25, "type": [ "integer", "null" ] }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "title": { "description": "Variant display name shown to customers.", "example": "Ceramic Coating — Full Vehicle", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the variant has unlimited stock.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link", null ], "example": "visible", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "variant_id": { "description": "Existing variant ID, prefixed `plan_`. Mutually exclusive with `variant`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "affiliate_code": { "description": "Affiliate code applied at checkout, or `null` when none is set.", "example": "tanyacole", "type": [ "string", "null" ] }, "created_at": { "description": "When the checkout configuration was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for setup-mode payment method availability; defaults to `usd` when omitted.", "example": "usd", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout mounted from this configuration, resolved through every layer (its own overrides, the variant's, and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays this configuration's own editable override.", "properties": { "disabled": { "description": "Payment methods explicitly disabled.", "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "id": { "description": "Checkout configuration ID, prefixed `ch_`.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships. `null` without the `checkout_configuration:basic:read` scope.", "example": {}, "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later.", "enum": [ "payment", "setup" ], "example": "setup", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the variant or platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for checkout.", "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for checkout.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "purchase_url": { "description": "Checkout URL you can send to customers.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout, or `null` when no redirect is configured.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "three_ds_level": { "description": "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. Applies in setup mode; `null` uses frictionless 3DS. Payment mode uses the variant policy.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "updated_at": { "description": "When the checkout configuration was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "variant": { "description": "Variant used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this variant accepts local currency payments via adaptive pricing.", "example": true, "type": "boolean" }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ "renewal", "one_time" ], "example": "one_time", "type": "string" }, "currency": { "description": "Three-letter ISO currency code for the variant's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based variants.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the variant currency.", "example": 249.0, "type": "number" }, "release_method": { "description": "Sales method for the variant.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 0.0, "type": "number" }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "visibility", "billing_type", "release_method", "currency", "billing_period", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "adaptive_pricing_enabled" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode" ], "type": "object" } } }, "description": "checkout configuration created for an existing plan" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "checkout_configuration:create" ] } ], "summary": "Create a checkout configuration", "tags": [ "Checkout Configurations" ] }, "x-whop-surface": "native" }, "/checkout_configurations/{id}": { "delete": { "description": "Deletes a checkout configuration so its checkout URL can no longer be used.", "operationId": "deleteCheckoutConfiguration", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted checkout configuration.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "checkout configuration deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not found" } }, "security": [ { "bearerAuth": [ "checkout_configuration:delete" ] } ], "summary": "Delete a checkout configuration", "tags": [ "Checkout Configurations" ] }, "get": { "description": "Retrieves a checkout configuration by ID. This endpoint is public so a checkout page can load from the configuration URL.", "operationId": "retrieveCheckoutConfiguration", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "affiliate_code": { "description": "Affiliate code applied at checkout, or `null` when none is set.", "example": "tanyacole", "type": [ "string", "null" ] }, "created_at": { "description": "When the checkout configuration was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Currency used for setup-mode payment method availability; defaults to `usd` when omitted.", "example": "usd", "type": [ "string", "null" ] }, "effective_payment_method_configuration": { "description": "The configuration governing a checkout mounted from this configuration, resolved through every layer (its own overrides, the variant's, and the account's) — the shape a session's `payment_method_configuration` carries. Apply it over the payment method types catalogue for the offerable set. `null` means platform defaults; `payment_method_configuration` stays this configuration's own editable override.", "properties": { "disabled": { "description": "Payment methods explicitly disabled.", "items": { "example": "crypto", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "id": { "description": "Checkout configuration ID, prefixed `ch_`.", "example": "ch_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "description": "Custom key-value metadata copied to payments and memberships. `null` without the `checkout_configuration:basic:read` scope.", "example": { "booking_source": "front_desk" }, "type": [ "object", "null" ] }, "mode": { "description": "Controls whether checkout charges the buyer immediately or saves payment details for later.", "enum": [ "payment", "setup" ], "example": "payment", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the variant or platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for checkout.", "items": { "example": "crypto", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for checkout.", "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "description": "Whether platform default payment methods are included.", "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "purchase_url": { "description": "Checkout URL you can send to customers.", "example": "https://whop.com/checkout/ch_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "redirect_url": { "description": "URL customers are sent to after checkout, or `null` when no redirect is configured.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "three_ds_level": { "description": "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. Applies in setup mode; `null` uses frictionless 3DS. Payment mode uses the variant policy.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "updated_at": { "description": "When the checkout configuration was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "variant": { "description": "Variant used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this variant accepts local currency payments via adaptive pricing.", "example": true, "type": "boolean" }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual. `null` for one-time variants.", "example": 30, "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "currency": { "description": "Three-letter ISO currency code for the variant's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based variants.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Variant ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the variant currency.", "example": 0.0, "type": "number" }, "release_method": { "description": "Sales method for the variant.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59.0, "type": "number" }, "three_ds_level": { "description": "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` inherits the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "visibility", "billing_type", "release_method", "currency", "billing_period", "expiration_days", "initial_price", "renewal_price", "trial_period_days", "three_ds_level", "adaptive_pricing_enabled" ], "type": [ "object", "null" ] } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode" ], "type": "object" } } }, "description": "checkout configuration found (unauthenticated)" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not found" } }, "security": [ {}, { "bearerAuth": [ "checkout_configuration:basic:read" ] } ], "summary": "Retrieve a checkout configuration", "tags": [ "Checkout Configurations" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the checkout configuration.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/claim_links/{id}": { "get": { "description": "Retrieves a funded claim link by ID or by its public claim code. By ID, the caller needs `airdrop_link:basic:read` on the funding account, or must own the funding personal account; `code` and `claim_url` are `null` without `airdrop_link:manage` on the funding account or `payout:withdraw_funds` on the personal account. A claim code previews the sender, amount, expiry, and claim availability without authentication. Treat codes as secrets: anyone holding one can claim after signing in.", "operationId": "retrieveClaimLink", "responses": { "200": { "content": { "application/json": { "schema": { "description": "A shareable link anyone holding its code can open to claim the funds.", "properties": { "amount": { "description": "Amount each claim receives.", "example": "25.00", "type": "string" }, "claim_url": { "description": "Shareable claim URL. Null when retrieving by ID without claim-link management access.", "example": "https://whop.com/claim", "type": [ "string", "null" ] }, "claimable": { "description": "Whether this link can currently be claimed.", "example": true, "type": "boolean" }, "code": { "description": "Redeemable claim code. Null when retrieving by ID without claim-link management access.", "example": "demoClaim123", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "expires_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Claim-link ID, prefixed `airdrp_`.", "example": "airdrp_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "claim_link" ], "example": "claim_link", "type": "string" }, "redeemable_count": { "description": "Maximum number of claims.", "example": 1, "type": "integer" }, "redeemed_count": { "description": "Number of completed claims.", "example": 0, "type": "integer" }, "remaining_claims": { "description": "Number of available claims, excluding slots reserved by pending claims.", "example": 1, "type": "integer" }, "sender": { "description": "The public account or user funding the claim link.", "discriminator": { "propertyName": "object" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "title": "ClaimLinkSenderAccount", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "title": "ClaimLinkSenderUser", "type": "object" } ] }, "source": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id" ], "type": "object" }, "status": { "description": "The link's lifecycle status. A newly funded link is `pending`. Check `claimable` for current availability, including expiry and reserved claims.", "enum": [ "pending", "fully_claimed", "canceled", "expired" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "code", "claim_url", "status", "claimable", "amount", "currency", "redeemable_count", "redeemed_count", "remaining_claims", "expires_at", "created_at", "source", "sender" ], "title": "ClaimLink", "type": "object" } } }, "description": "claim link retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication required for an ID" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account read access required" }, "404": { "$ref": "#/components/responses/NotFound", "description": "claim link not found" } }, "security": [ {}, { "bearerAuth": [ "airdrop_link:basic:read" ] }, { "bearerAuth": [] } ], "summary": "Retrieve Claim Link", "tags": [ "Transfers" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "A claim-link ID (`airdrp_…`), or the public claim code from the `c` parameter in the claim URL.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/claim_links/{id}/claim": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The public claim code from the `c` parameter in the claim URL. A claim-link ID does not authorize redemption.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Claims a funded link into the authenticated user's personal balance and returns the updated link. Requires a signed-in user and the public claim code; account API keys cannot claim on a recipient's behalf. Each user can claim a link once. Reuse the same `Idempotency-Key` when retrying the same request. On-chain claims may take several minutes to complete.", "operationId": "claimClaimLink", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A shareable link anyone holding its code can open to claim the funds.", "properties": { "amount": { "description": "Amount each claim receives.", "example": "25.00", "type": "string" }, "claim_url": { "description": "Shareable claim URL. Null when retrieving by ID without claim-link management access.", "example": "https://whop.com/claim", "type": [ "string", "null" ] }, "claimable": { "description": "Whether this link can currently be claimed.", "example": false, "type": "boolean" }, "code": { "description": "Redeemable claim code. Null when retrieving by ID without claim-link management access.", "example": "demoClaim123", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "expires_at": { "example": null, "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Claim-link ID, prefixed `airdrp_`.", "example": "airdrp_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "claim_link" ], "example": "claim_link", "type": "string" }, "redeemable_count": { "description": "Maximum number of claims.", "example": 1, "type": "integer" }, "redeemed_count": { "description": "Number of completed claims.", "example": 1, "type": "integer" }, "remaining_claims": { "description": "Number of available claims, excluding slots reserved by pending claims.", "example": 0, "type": "integer" }, "sender": { "description": "The public account or user funding the claim link.", "discriminator": { "propertyName": "object" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": null, "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "title": "ClaimLinkSenderAccount", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "title": "ClaimLinkSenderUser", "type": "object" } ] }, "source": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id" ], "type": "object" }, "status": { "description": "The link's lifecycle status. A newly funded link is `pending`. Check `claimable` for current availability, including expiry and reserved claims.", "enum": [ "pending", "fully_claimed", "canceled", "expired" ], "example": "fully_claimed", "type": "string" } }, "required": [ "object", "id", "code", "claim_url", "status", "claimable", "amount", "currency", "redeemable_count", "redeemed_count", "remaining_claims", "expires_at", "created_at", "source", "sender" ], "title": "ClaimLink", "type": "object" } } }, "description": "claim link claimed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "link cannot be claimed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "user authentication required" }, "404": { "$ref": "#/components/responses/NotFound", "description": "claim code not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Claim", "tags": [ "Transfers" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/company_token_transactions": { "get": { "description": "Lists an account's token transactions, newest first.\n\nRequired permissions:\n - `company_token_transaction:read`\n - `member:basic:read`\n - `company:basic:read`", "operationId": "listCompanyTokenTransaction", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "Filter transactions to only those involving this specific user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "transaction_type", "required": false, "schema": { "$ref": "#/components/schemas/CompanyTokenTransactionTypes", "description": "Filter transactions by type." }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": true, "schema": { "description": "The unique identifier of the company to list token transactions for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for CompanyTokenTransaction.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CompanyTokenTransactionListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company_token_transaction:read", "member:basic:read", "company:basic:read" ] } ], "summary": "List company token transactions", "tags": [ "Company token transactions" ], "x-group-title": "CRM" }, "post": { "description": "Creates a token transaction that adds, subtracts, or transfers tokens for a member of an account.\n\nRequired permissions:\n - `company_token_transaction:create`\n - `member:basic:read`\n - `company:basic:read`", "operationId": "createCompanyTokenTransaction", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateCompanyTokenTransaction", "oneOf": [ { "description": "Autogenerated input type of CreateCompanyTokenTransaction", "properties": { "account_id": { "description": "The unique identifier of the company to create the transaction in, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "The positive number of tokens to transact. For example, 100.0 for 100 tokens.", "example": 6.9, "type": "number" }, "description": { "description": "A human-readable description of why the transaction was created.", "type": [ "string", "null" ] }, "destination_user_id": { "description": "The unique identifier of the user receiving the tokens. Required when the transaction type is 'transfer'.", "type": "string" }, "idempotency_key": { "description": "A unique key to prevent duplicate transactions. Use a UUID or similar unique string.", "type": [ "string", "null" ] }, "transaction_type": { "const": "transfer", "type": "string" }, "user_id": { "description": "The unique identifier of the user whose token balance will be affected, starting with 'user_'.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "account_id", "transaction_type", "user_id", "destination_user_id" ], "title": "CreateCompanyTokenTransactionInputTransactionTypeTransfer", "type": "object" }, { "description": "Autogenerated input type of CreateCompanyTokenTransaction", "properties": { "account_id": { "description": "The unique identifier of the company to create the transaction in, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "The positive number of tokens to transact. For example, 100.0 for 100 tokens.", "example": 6.9, "type": "number" }, "description": { "description": "A human-readable description of why the transaction was created.", "type": [ "string", "null" ] }, "idempotency_key": { "description": "A unique key to prevent duplicate transactions. Use a UUID or similar unique string.", "type": [ "string", "null" ] }, "transaction_type": { "const": "add", "type": "string" }, "user_id": { "description": "The unique identifier of the user whose token balance will be affected, starting with 'user_'.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "account_id", "transaction_type", "user_id" ], "title": "CreateCompanyTokenTransactionInputTransactionTypeAdd", "type": "object" }, { "description": "Autogenerated input type of CreateCompanyTokenTransaction", "properties": { "account_id": { "description": "The unique identifier of the company to create the transaction in, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "The positive number of tokens to transact. For example, 100.0 for 100 tokens.", "example": 6.9, "type": "number" }, "description": { "description": "A human-readable description of why the transaction was created.", "type": [ "string", "null" ] }, "idempotency_key": { "description": "A unique key to prevent duplicate transactions. Use a UUID or similar unique string.", "type": [ "string", "null" ] }, "transaction_type": { "const": "subtract", "type": "string" }, "user_id": { "description": "The unique identifier of the user whose token balance will be affected, starting with 'user_'.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "account_id", "transaction_type", "user_id" ], "title": "CreateCompanyTokenTransactionInputTransactionTypeSubtract", "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyTokenTransaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company_token_transaction:create", "member:basic:read", "company:basic:read" ] } ], "summary": "Create company token transaction", "tags": [ "Company token transactions" ], "x-group-title": "CRM" } }, "/company_token_transactions/{id}": { "get": { "description": "Retrieves a token transaction.\n\nRequired permissions:\n - `company_token_transaction:read`\n - `member:basic:read`\n - `company:basic:read`", "operationId": "retrieveCompanyTokenTransaction", "parameters": [ { "description": "The unique identifier of the token transaction to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyTokenTransaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company_token_transaction:read", "member:basic:read", "company:basic:read" ] } ], "summary": "Retrieve company token transaction", "tags": [ "Company token transactions" ], "x-group-title": "CRM" } }, "/confirmation_tokens/{id}": { "get": { "description": "Retrieves a confirmation token's payment method and billing details, never the underlying payment credential, to display what the buyer chose or check that the token is still usable. Requires no authentication and is rate-limited.", "operationId": "retrieveConfirmationToken", "parameters": [ { "description": "The account the token was minted for, prefixed `biz_`. It must match the token's account.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationToken" } } }, "description": "confirmation token retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account mismatch" } }, "security": [ {}, { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "Retrieve Confirmation Token", "tags": [ "Confirmation Tokens" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Confirmation token ID, prefixed `ctok_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/course_chapters": { "get": { "description": "Returns a paginated list of chapters within a course, ordered by position.\n\nRequired permissions:\n - `courses:read`", "operationId": "listCourseChapter", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "course_id", "required": true, "schema": { "description": "The unique identifier of the course to list chapters for.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Chapter.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseChapterListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "List course chapters", "tags": [ "Course chapters" ], "x-group-title": "Courses" }, "post": { "description": "Create a new chapter within a course to organize lessons into sections.\n\nRequired permissions:\n - `courses:update`", "operationId": "createCourseChapter", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateChapter", "properties": { "course_id": { "description": "The unique identifier of the course to create the chapter in (e.g., \"course_XXXXX\").", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display title of the chapter (e.g., \"Module 1: Introduction\").", "type": [ "string", "null" ] } }, "required": [ "course_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseChapter" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Create course chapter", "tags": [ "Course chapters" ], "x-group-title": "Courses" } }, "/course_chapters/{id}": { "delete": { "description": "Permanently delete a chapter and all of its lessons from a course.\n\nRequired permissions:\n - `courses:update`", "operationId": "deleteCourseChapter", "parameters": [ { "description": "The unique identifier of the chapter to delete (e.g., \"chap_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "chap_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Delete course chapter", "tags": [ "Course chapters" ], "x-group-title": "Courses" }, "get": { "description": "Retrieves the details of an existing course chapter.\n\nRequired permissions:\n - `courses:read`", "operationId": "retrieveCourseChapter", "parameters": [ { "description": "The unique identifier of the chapter to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "chap_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseChapter" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "Retrieve course chapter", "tags": [ "Course chapters" ], "x-group-title": "Courses" }, "patch": { "description": "Update a chapter's title within a course.\n\nRequired permissions:\n - `courses:update`", "operationId": "updateCourseChapter", "parameters": [ { "description": "The unique identifier of the chapter to update (e.g., \"chap_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "chap_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateChapter", "properties": { "title": { "description": "The new display title of the chapter (e.g., \"Module 1: Introduction\").", "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseChapter" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Update course chapter", "tags": [ "Course chapters" ], "x-group-title": "Courses" } }, "/course_lesson_interactions": { "get": { "description": "Returns a paginated list of lesson interactions for a lesson or course. Callers without admin access to the course's experience see only their own interactions.\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`", "operationId": "listCourseLessonInteraction", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "user_id", "required": false, "schema": { "description": "The unique identifier of the user to filter lesson interactions for.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "lesson_id", "required": false, "schema": { "description": "The unique identifier of the lesson to filter interactions for.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "course_id", "required": false, "schema": { "description": "The unique identifier of the course to filter interactions for.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "completed", "required": false, "schema": { "description": "Whether to filter for completed or in-progress lesson interactions.", "type": "boolean" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for LessonInteraction.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseLessonInteractionListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read", "course_analytics:read" ] } ], "summary": "List course lesson interactions", "tags": [ "Course lesson interactions" ], "x-group-title": "Courses" } }, "/course_lesson_interactions/{id}": { "get": { "description": "Retrieves the details of an existing course lesson interaction.\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`", "operationId": "retrieveCourseLessonInteraction", "parameters": [ { "description": "The unique identifier of the lesson interaction to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "crsli_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseLessonInteraction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read", "course_analytics:read" ] } ], "summary": "Retrieve course lesson interaction", "tags": [ "Course lesson interactions" ], "x-group-title": "Courses" } }, "/course_lessons": { "get": { "description": "Returns a paginated list of lessons within a course or chapter, ordered by position.\n\nRequired permissions:\n - `courses:read`", "operationId": "listCourseLesson", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "course_id", "required": false, "schema": { "description": "The unique identifier of the course to return all lessons across all chapters.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "chapter_id", "required": false, "schema": { "description": "The unique identifier of a chapter to return only its lessons.", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Lesson.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseLessonListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "List course lessons", "tags": [ "Course lessons" ], "x-group-title": "Courses" }, "post": { "description": "Create a new lesson within a course chapter. Lessons can contain video, text, or assessment content.\n\nRequired permissions:\n - `courses:update`", "operationId": "createCourseLesson", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateLesson", "properties": { "chapter_id": { "description": "The unique identifier of the chapter to create the lesson in (e.g., \"chap_XXXXX\").", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "content": { "description": "The Markdown content body of the lesson.", "type": [ "string", "null" ] }, "days_from_course_start_until_unlock": { "description": "The number of days after a student starts the course before this lesson becomes accessible.", "example": 42, "type": [ "integer", "null" ] }, "embed_id": { "description": "The external video identifier for embedded content (e.g., a YouTube video ID or Loom share ID).", "type": [ "string", "null" ] }, "embed_type": { "description": "The type of video embed for this lesson, such as YouTube or Loom.", "oneOf": [ { "$ref": "#/components/schemas/EmbedTypes" }, { "type": "null" } ] }, "lesson_type": { "$ref": "#/components/schemas/LessonTypes", "description": "The content type of the lesson, such as video, text, quiz, or knowledge check." }, "thumbnail": { "description": "The thumbnail image for the lesson in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "title": { "description": "The display title of the lesson (e.g., \"Getting Started with APIs\").", "type": [ "string", "null" ] } }, "required": [ "chapter_id", "lesson_type" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseLesson" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Create course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_lessons/{id}": { "delete": { "description": "Permanently delete a lesson and remove it from its chapter.\n\nRequired permissions:\n - `courses:update`", "operationId": "deleteCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson to delete (e.g., \"les_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "lesn_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Delete course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" }, "get": { "description": "Retrieves the details of an existing course lesson.\n\nRequired permissions:\n - `courses:read`", "operationId": "retrieveCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "lesn_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseLesson" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "Retrieve course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" }, "patch": { "description": "Update a lesson's content, type, visibility, assessment questions, or media attachments.\n\nRequired permissions:\n - `courses:update`", "operationId": "updateCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson to update (e.g., \"les_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "lesn_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateLesson", "properties": { "assessment_completion_requirement": { "description": "The passing criteria for quiz or knowledge check lessons, such as minimum grade or correct answers.", "properties": { "minimum_grade_percent": { "description": "The minimum grade percentage required to pass (0-100). Cannot be set together with minimum_questions_correct.", "example": 6.9, "type": [ "number", "null" ] }, "minimum_questions_correct": { "description": "The minimum number of questions that must be answered correctly. Cannot be set together with minimum_grade_percent.", "example": 42, "type": [ "integer", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "assessment_questions": { "description": "The full list of assessment questions for quiz or knowledge check lessons. Replaces all existing questions.", "items": { "description": "Input for creating or updating an assessment question", "properties": { "correct_answer": { "description": "The correct answer for the question. Used for short answer questions", "type": "string" }, "id": { "description": "The ID of an existing question. If provided, the question will be updated. If not provided, a new question will be created.", "type": [ "string", "null" ] }, "image": { "description": "Optional image attachment for the question", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "options": { "description": "The answer options for multiple choice/select questions", "items": { "description": "Input for creating or updating an assessment question option", "properties": { "id": { "description": "The ID of an existing option. If provided, the option will be updated. If not provided, a new option will be created.", "type": [ "string", "null" ] }, "is_correct": { "description": "Whether this option is a correct answer", "type": "boolean" }, "option_text": { "description": "The text of the answer option", "type": "string" } }, "required": [ "is_correct", "option_text" ], "type": "object" }, "type": [ "array", "null" ] }, "question_text": { "description": "The text of the question", "type": "string" }, "question_type": { "$ref": "#/components/schemas/CoursesAssessmentQuestionTypes", "description": "The type of the question" } }, "required": [ "correct_answer", "question_text", "question_type" ], "type": "object" }, "type": [ "array", "null" ] }, "attachments": { "description": "File attachments for the lesson such as PDFs or documents. Replaces all existing attachments.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "content": { "description": "The Markdown content body of the lesson.", "type": [ "string", "null" ] }, "days_from_course_start_until_unlock": { "description": "The number of days after a student starts the course before this lesson becomes accessible.", "example": 42, "type": [ "integer", "null" ] }, "embed_id": { "description": "The external video identifier for embedded content (e.g., a YouTube video ID or Loom share ID).", "type": [ "string", "null" ] }, "embed_type": { "description": "The type of video embed for this lesson, such as YouTube or Loom.", "oneOf": [ { "$ref": "#/components/schemas/EmbedTypes" }, { "type": "null" } ] }, "lesson_type": { "description": "The content type of the lesson, such as video, text, quiz, or knowledge check.", "oneOf": [ { "$ref": "#/components/schemas/LessonTypes" }, { "type": "null" } ] }, "main_pdf": { "description": "The primary PDF document attached to this lesson for student reference.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "max_attempts": { "description": "The maximum number of attempts a student is allowed for assessment lessons.", "example": 42, "type": [ "integer", "null" ] }, "mux_asset_id": { "description": "The identifier of a Mux video asset to attach to this lesson (e.g., \"mux_XXXXX\").", "example": "mux_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image for the lesson in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "title": { "description": "The display title of the lesson (e.g., \"Getting Started with APIs\").", "type": [ "string", "null" ] }, "visibility": { "description": "Controls whether this lesson is visible to students or hidden as a draft.", "oneOf": [ { "$ref": "#/components/schemas/LessonVisibilities" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseLesson" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Update course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_lessons/{lesson_id}/mark_as_completed": { "post": { "description": "Mark a lesson as completed for the current user after they finish the content.", "operationId": "markAsCompletedCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson to mark as completed (e.g., \"les_XXXXX\").", "in": "path", "name": "lesson_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Mark as completed course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_lessons/{lesson_id}/start": { "post": { "description": "Record that the current user has started viewing a lesson, creating progress tracking records.", "operationId": "startCourseLesson", "parameters": [ { "description": "The unique identifier of the lesson the user is starting (e.g., \"les_XXXXX\").", "in": "path", "name": "lesson_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Start course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_lessons/{lesson_id}/submit_assessment": { "post": { "description": "Submit answers for a quiz or knowledge check lesson and receive a graded result.", "operationId": "submitAssessmentCourseLesson", "parameters": [ { "description": "The unique identifier of the quiz or knowledge check lesson to submit answers for (e.g., \"les_XXXXX\").", "in": "path", "name": "lesson_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for SubmitAssessment", "properties": { "answers": { "description": "The list of answers to submit for each assessment question.", "items": { "description": "Input for a single question's answer in an assessment submission", "properties": { "answer_text": { "description": "The text answer provided by the user (for short answer questions)", "type": [ "string", "null" ] }, "question_id": { "description": "The ID of the question being answered", "type": "string" }, "selected_option_ids": { "description": "The IDs of the selected options (for multiple choice/select questions)", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "question_id" ], "type": "object" }, "type": "array" } }, "required": [ "answers" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The result of a user's assessment attempt", "properties": { "created_at": { "description": "The datetime the assessment result was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The unique identifier for the assessment result.", "example": "crsar_xxxxxxxxxxxx", "type": "string" }, "lesson": { "description": "The lesson this assessment result is for", "properties": { "id": { "description": "The unique identifier for the lesson.", "example": "lesn_xxxxxxxxxxxxx", "type": "string" }, "title": { "description": "The display name of the lesson shown to students. Maximum 120 characters.", "example": "Understanding Candlestick Patterns", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "result_correct": { "description": "The number of correct answers", "example": 42, "type": "integer" }, "result_grade": { "description": "The grade achieved on the assessment", "example": 6.9, "type": "number" }, "result_graded_questions": { "additionalProperties": true, "description": "Array of graded questions with details", "type": "object" }, "result_passing_grade": { "description": "Whether the user achieved a passing grade", "type": "boolean" }, "result_question_count": { "description": "The total number of questions in the assessment", "example": 42, "type": "integer" }, "score_percent": { "description": "The percentage score achieved on the assessment", "example": 6.9, "type": "number" }, "updated_at": { "description": "The datetime the assessment result was last updated.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "user": { "description": "The user who took the assessment", "properties": { "id": { "description": "The unique identifier for the user.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name shown on their public profile.", "example": "John Doe", "type": [ "string", "null" ] }, "username": { "description": "The user's unique username shown on their public profile.", "example": "johndoe42", "type": "string" } }, "required": [ "id", "name", "username" ], "type": "object" } }, "required": [ "id", "created_at", "updated_at", "result_grade", "result_correct", "result_question_count", "result_passing_grade", "result_graded_questions", "score_percent", "user", "lesson" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Submit assessment course lesson", "tags": [ "Course lessons" ], "x-group-title": "Courses" } }, "/course_students": { "get": { "description": "Returns a paginated list of students enrolled in a course, with optional name filtering.\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`", "operationId": "listCourseStudent", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "course_id", "required": true, "schema": { "description": "The unique identifier of the course to list enrolled students for.", "example": "cors_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "keyword", "required": false, "schema": { "description": "A search term to filter students by name or username.", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for CourseStudentType.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseStudentListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read", "course_analytics:read" ] } ], "summary": "List course students", "tags": [ "Course students" ], "x-group-title": "Courses" } }, "/course_students/{id}": { "get": { "description": "Retrieves the details of an existing course student.\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`", "operationId": "retrieveCourseStudent", "parameters": [ { "description": "The unique identifier of the course student record to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseStudent" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read", "course_analytics:read" ] } ], "summary": "Retrieve course student", "tags": [ "Course students" ], "x-group-title": "Courses" } }, "/courses": { "get": { "description": "Returns a paginated list of the courses in an experience or an account. `hidden` courses are included only for callers with `courses:update`.\n\nRequired permissions:\n - `courses:read`", "operationId": "listCourse", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "experience_id", "required": false, "schema": { "description": "The unique identifier of the experience to list courses for.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "The unique identifier of the company to list courses for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Course.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/CourseListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "List courses", "tags": [ "Courses" ], "x-group-title": "Courses" }, "post": { "description": "Create a new course within an experience, with optional chapters, lessons, and a certificate.\n\nRequired permissions:\n - `courses:update`", "operationId": "createCourse", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateCourse", "properties": { "certificate_after_completion_enabled": { "description": "Whether the course awards students a PDF certificate after completing all lessons.", "type": [ "boolean", "null" ] }, "experience_id": { "description": "The unique identifier of the experience to create the course in (e.g., \"exp_XXXXX\").", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "order": { "description": "The decimal order position of the course within its experience. Use fractional values (e.g., \"1.5\") to place between existing courses.", "example": "123.45", "type": [ "string", "null" ] }, "require_completing_lessons_in_order": { "description": "Whether students must complete each lesson sequentially before advancing to the next one.", "type": [ "boolean", "null" ] }, "tagline": { "description": "A short tagline displayed beneath the course title (e.g., \"Master the fundamentals of design\").", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image for the course in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "title": { "description": "The display title of the course (e.g., \"Introduction to Web Development\").", "type": "string" }, "visibility": { "description": "Controls whether this course is visible to students or hidden as a draft.", "oneOf": [ { "$ref": "#/components/schemas/CourseVisibilities" }, { "type": "null" } ] } }, "required": [ "experience_id", "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Course" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Create course", "tags": [ "Courses" ], "x-group-title": "Courses" } }, "/courses/{id}": { "delete": { "description": "Permanently delete a course and all of its chapters, lessons, and student progress.\n\nRequired permissions:\n - `courses:update`", "operationId": "deleteCourse", "parameters": [ { "description": "The unique identifier of the course to delete (e.g., \"course_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "cors_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Delete course", "tags": [ "Courses" ], "x-group-title": "Courses" }, "get": { "description": "Retrieves the details of an existing course. A `hidden` course is returned only to callers with `courses:update`.\n\nRequired permissions:\n - `courses:read`", "operationId": "retrieveCourse", "parameters": [ { "description": "The unique identifier of the course to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "cors_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Course" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:read" ] } ], "summary": "Retrieve course", "tags": [ "Courses" ], "x-group-title": "Courses" }, "patch": { "description": "Update a course's title, description, visibility, thumbnail, or chapter ordering.\n\nRequired permissions:\n - `courses:update`", "operationId": "updateCourse", "parameters": [ { "description": "The unique identifier of the course to update (e.g., \"course_XXXXX\").", "in": "path", "name": "id", "required": true, "schema": { "example": "cors_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateCourse", "properties": { "certificate_after_completion_enabled": { "description": "Whether the course awards students a PDF certificate after completing all lessons.", "type": [ "boolean", "null" ] }, "chapters": { "description": "A list of chapters with nested lessons to reorder or rename in bulk.", "items": { "description": "Input for updating a chapter while updating a course", "properties": { "id": { "description": "The ID of the chapter to update", "type": "string" }, "lessons": { "description": "The lessons to update within this chapter", "items": { "description": "Input for updating a lesson while updating a course", "properties": { "chapter_id": { "description": "The ID of the chapter this lesson belongs to (for moving between chapters)", "example": "chap_xxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of the lesson to update", "type": "string" }, "order": { "description": "The order of the lesson within its chapter", "example": 42, "type": "integer" }, "title": { "description": "The title of the lesson", "type": "string" } }, "required": [ "chapter_id", "id", "order", "title" ], "type": "object" }, "type": [ "array", "null" ] }, "order": { "description": "The order of the chapter within its course", "example": 42, "type": "integer" }, "title": { "description": "The title of the chapter", "type": "string" } }, "required": [ "id", "order", "title" ], "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "A short description of the course displayed to students on the course page.", "type": [ "string", "null" ] }, "language": { "description": "The primary language spoken in the video content of the course.", "oneOf": [ { "$ref": "#/components/schemas/Languages" }, { "type": "null" } ] }, "order": { "description": "The decimal order position of the course within its experience. Use fractional values (e.g., \"1.5\") to place between existing courses.", "example": "123.45", "type": [ "string", "null" ] }, "require_completing_lessons_in_order": { "description": "Whether students must complete each lesson sequentially before advancing to the next one.", "type": [ "boolean", "null" ] }, "tagline": { "description": "A short tagline displayed beneath the course title (e.g., \"Master the fundamentals of design\").", "type": [ "string", "null" ] }, "thumbnail": { "description": "The thumbnail image for the course in PNG, JPEG, or GIF format.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "title": { "description": "The display title of the course (e.g., \"Introduction to Web Development\").", "type": [ "string", "null" ] }, "visibility": { "description": "Controls whether this course is visible to students or hidden as a draft.", "oneOf": [ { "$ref": "#/components/schemas/CourseVisibilities" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Course" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "courses:update" ] } ], "summary": "Update course", "tags": [ "Courses" ], "x-group-title": "Courses" } }, "/deposits": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Returns the deposit methods for an account or user, including crypto addresses, bank transfer instructions, and, for a business, a hosted deposit page. Bitcoin deposits are converted to USDT on Plasma in the destination's wallet. Business destinations require no authentication. Pass `payment_method_id` to also charge a business's saved payment method for `amount` in USD and add it to the business's balance; that requires authentication with the `payment:charge` scope. The charge has no fees or taxes and does not count as revenue.", "operationId": "createDeposit", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "Amount to prefill on hosted deposit page. Crypto deposits require a $10 minimum. With `payment_method_id`, the amount in USD to charge, and required.", "example": 50.0, "type": "number" }, "destination": { "description": "Account ID to fund, `biz_` or `user_`. Any business resolves without authentication; a user account resolves only for that same authenticated user.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Custom metadata to attach to the payment the charge creates. Ignored unless `payment_method_id` is provided.", "example": { "attempt_id": "att_8f2k1" }, "type": [ "object", "null" ] }, "origin_bic": { "description": "SWIFT/BIC of the bank the funds are sent from, 8 or 11 characters. Fills each bank currency's `swift_bic` with the intermediary bank to route the wire through.", "example": "DEUTDEFFXXX", "type": "string" }, "payment_method_id": { "description": "A saved payment method of the business to charge for `amount`, prefixed `payt_`. Save one with Create setup intent and `owner_id` set to the account. Only for a `biz_` destination, and requires authentication with the `payment:charge` scope. A declined charge fails the request with 400.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "destination" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID of the destination owner.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "amount": { "description": "Requested deposit amount.", "example": "50.00", "type": "string" }, "hosted_url": { "description": "URL of the hosted deposit page. Only present for business destinations.", "example": "https://whop.com/deposit/biz_xxxxxxxxxxxxxx/", "type": [ "string", "null" ] }, "methods": { "description": "Available deposit methods for destination.", "properties": { "bank": { "description": "Bank deposit details. Only present when bank deposits are active for the destination account.", "properties": { "currencies": { "description": "Bank transfer currencies available for this deposit.", "items": { "properties": { "account_number": { "description": "Bank account number for deposits in this currency.", "example": "8825310472", "type": [ "string", "null" ] }, "currency": { "description": "Currency supported by these bank instructions.", "example": "USD", "type": "string" }, "deposit_bank_address": { "description": "Receiving bank address.", "example": "2115 Linwood Avenue, Fort Lee, New Jersey 07024", "type": [ "string", "null" ] }, "deposit_bank_name": { "description": "Receiving bank name.", "example": "Cross River Bank", "type": [ "string", "null" ] }, "deposit_beneficiary_name": { "description": "Beneficiary name to use for transfer.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "deposit_reference": { "description": "Reference to include with bank transfer.", "example": "SHINE-1042", "type": [ "string", "null" ] }, "rails": { "description": "Active deposit rails for this currency.", "items": { "enum": [ "ach", "wire", "sepa", "fps", "chaps" ], "example": "wire", "type": "string" }, "type": "array" }, "routing_number": { "description": "Bank routing number for deposits in this currency.", "example": "021214891", "type": [ "string", "null" ] }, "swift_bic": { "description": "SWIFT/BIC of the intermediary bank the sending bank routes an international wire through. Null unless `origin_bic` is provided and an intermediary is published for that bank and currency.", "example": "CHASUS33XXX", "type": [ "string", "null" ] } }, "required": [ "currency", "account_number", "routing_number", "deposit_bank_name", "deposit_bank_address", "deposit_beneficiary_name", "deposit_reference", "swift_bic", "rails" ], "type": "object" }, "type": "array" } }, "required": [ "currencies" ], "type": [ "object", "null" ] }, "card": { "description": "The charge to a saved payment method. Null unless `payment_method_id` was passed.", "properties": { "metadata": { "additionalProperties": { "type": "string" }, "description": "The custom metadata attached to the payment the charge created. Null if none was passed.", "example": { "attempt_id": "att_8f2k1" }, "type": [ "object", "null" ] }, "payment_id": { "description": "The payment the charge created, prefixed `pay_`. Retrieve it, or listen for `payment.succeeded`, to confirm the funds landed.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "payment_method_id": { "description": "The saved payment method that was charged, prefixed `payt_`.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "payment_method_id", "payment_id", "metadata" ], "type": [ "object", "null" ] }, "crypto": { "description": "Crypto networks available for this deposit, each with its on-chain deposit address and the tokens accepted on that network. Crypto deposits require a $10 minimum.", "items": { "properties": { "deposit_address": { "description": "Address to send funds to on this network. Null when the provider has not issued one yet.", "example": "soladdr", "type": [ "string", "null" ] }, "icon_url": { "description": "Network icon URL.", "example": "https://whop.com/_static/images/crypto/solana.svg", "type": [ "string", "null" ] }, "name": { "description": "Network display name.", "enum": [ "Ethereum", "Solana", "Bitcoin", "Base", "BNB Smart Chain", "Hyperliquid", "Hypercore", "MegaETH", "Polygon", "Plasma", "Arbitrum" ], "example": "Solana", "type": "string" }, "supported_currencies": { "description": "Tokens accepted for deposit on this network.", "items": { "properties": { "icon_url": { "description": "Token icon URL. Null when no icon is available.", "example": "https://whop.com/_static/images/crypto/pyusd.svg", "type": [ "string", "null" ] }, "name": { "description": "Token symbol.", "enum": [ "ARB", "BNB", "BTC", "ETH", "EURC", "HYPE", "PYUSD", "SOL", "USD1", "USDC", "USDC.e", "USDG", "USDT", "USDT0", "USDe", "USDm", "XO", "XPL", "pUSD", "wETH" ], "example": "PYUSD", "type": "string" } }, "required": [ "name", "icon_url" ], "type": "object" }, "type": "array" } }, "required": [ "name", "deposit_address", "icon_url", "supported_currencies" ], "type": "object" }, "type": "array" } }, "required": [ "bank", "crypto", "card" ], "type": "object" }, "object": { "enum": [ "deposit" ], "example": "deposit", "type": "string" } }, "required": [ "object", "account_id", "hosted_url", "methods" ], "type": "object" } } }, "description": "deposit created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ {}, { "bearerAuth": [ "payout:account:read" ] }, { "bearerAuth": [ "payment:charge" ] } ], "summary": "Create Deposit", "tags": [ "Deposits" ] }, "x-whop-surface": "native" }, "/deposits/{id}/reverse": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the bank deposit to reverse, prefixed `vbt_`.", "example": "vbt_xxxxxxxxxxxxxx", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Sends a bank deposit back to the bank account that wired it and takes it back out of the balance. Identify the deposit by its `vbt_` ID, the `source.id` of its row in the account's financial activity. The available balance has to cover the deposit minus the deposit fee, which is refunded. Returns the reversal's own row in the financial activity: a `topup_reversal` debit for the full deposit amount, whose `source` is the bank deposit. The source's `status` is `reversal_in_progress` until the money is back with the sender, then `reversed`.", "operationId": "reverseDeposit", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The business that received the deposit, prefixed `biz_`. Pass this or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Custom metadata to store with the reversal.", "example": { "ticket": "SUP-42" }, "type": [ "object", "null" ] }, "user_id": { "description": "The user that received the deposit, prefixed `user_`. Pass this or `account_id`.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerActivity" } } }, "description": "deposit reversed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:withdraw_funds scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no bank deposit with that ID on the account" }, "409": { "$ref": "#/components/responses/Conflict", "description": "deposit already reversed or not reversible" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "Reverse Deposit", "tags": [ "Deposits" ] }, "x-whop-surface": "native" }, "/dispute_alerts": { "get": { "description": "Lists the dispute alerts and early fraud warnings across the accounts you can read.", "operationId": "listDisputeAlerts", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Only alerts on this account's payments (`biz_` tag). Omit it to cover every account you can read.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only alerts on this payment (`pay_` tag). A payment can carry several.", "in": "query", "name": "payment_id", "required": false, "schema": { "type": "string" } }, { "description": "Only alerts of this kind. `early_fraud_warning` for issuer fraud reports, `dispute_alert` for pre-dispute notices, `rapid_dispute_resolution` for Visa RDR cases the network already closed.", "in": "query", "name": "type", "required": false, "schema": { "enum": [ "early_fraud_warning", "dispute_alert", "rapid_dispute_resolution" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort alerts by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "reported_at", "amount" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only alerts Whop received before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only alerts Whop received after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DisputeAlert" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "dispute alerts listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "an unrecognized type filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required dispute-alert-read scope" } }, "security": [ { "bearerAuth": [ "payment:dispute_alert:read" ] } ], "summary": "List Dispute Alerts", "tags": [ "Dispute alerts" ] }, "x-whop-surface": "native" }, "/dispute_alerts/{id}": { "get": { "description": "Retrieves a single dispute alert or early fraud warning by ID.", "operationId": "retrieveDisputeAlert", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The dispute alert ID, prefixed `dspa_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeAlert" } } }, "description": "dispute alert returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required dispute-alert-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "a record-only issuer signal Whop does not forward" } }, "security": [ { "bearerAuth": [ "payment:dispute_alert:read" ] } ], "summary": "Retrieve Dispute Alert", "tags": [ "Dispute alerts" ] }, "x-whop-surface": "native" }, "/disputes": { "get": { "description": "Lists the disputes across the accounts you can read.", "operationId": "listDisputes", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Only disputes filed against this account (`biz_` tag). Omit it to cover every account you can read.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort disputes by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "amount", "evidence_due_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only disputes in these statuses. Repeat the parameter to pass several — one paginated list covers all of them. Inquiries match only the `warning_` statuses. A `needs_response` dispute whose evidence deadline has passed reports and filters as `under_review` instead.", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "needs_response", "warning_needs_response", "under_review", "warning_under_review", "won", "lost", "prevented", "warning_closed" ], "example": "needs_response", "type": "string" }, "type": "array" } }, { "description": "Only disputes in this three-letter ISO currency.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes opened before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes opened after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Search disputes by dispute ID, payment ID, user ID, membership ID, user email, name, or username. Email filtering requires the member:email:read permission.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Also cover the account's connected accounts. Requires `account_id`, and is a 400 without it. Without `query`, covers the disputes of the account and every connected account, in any order. The listing is cut off after 10 seconds; add a `query` to narrow it. With `query`, matches on dispute, payment, user or membership ID, buyer email, or a card's first 6 or 8 digits and last 4 separated by a space or dash (`424242 4242`); free-text queries such as a name search only the named account. Connected accounts' disputes are returned only for connected accounts you can read disputes on.", "in": "query", "name": "include_connected_accounts", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Dispute" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "disputes listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "an unrecognized status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required dispute-read scope" } }, "security": [ { "bearerAuth": [ "payment:dispute:read" ] } ], "summary": "List Disputes", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/disputes/summary": { "get": { "description": "Totals up the same disputes the list returns, so you can build status tabs and totals without paging through them.", "operationId": "retrieveDisputeSummary", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Which breakdowns to return, keyed by these names under `groups`. Repeat the parameter to ask for several; omit it for all of them.", "in": "query", "name": "groups", "required": false, "schema": { "items": { "enum": [ "status", "currency" ], "example": "status", "type": "string" }, "type": "array" } }, { "description": "Only disputes filed against this account (`biz_` tag). Omit it to cover every account you can read.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes in these statuses. Repeat the parameter to pass several. A `needs_response` dispute whose evidence deadline has passed reports and filters as `under_review` instead.", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "needs_response", "warning_needs_response", "under_review", "warning_under_review", "won", "lost", "prevented", "warning_closed" ], "example": "needs_response", "type": "string" }, "type": "array" } }, { "description": "Only disputes in this three-letter ISO currency.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes opened before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only disputes opened after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Search disputes by dispute ID, payment ID, user ID, membership ID, user email, name, or username. Email filtering requires the member:email:read permission.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Also cover the account's connected accounts. Requires `account_id`, and is a 400 without it. Without `query`, covers the disputes of the account and every connected account, in any order. The listing is cut off after 10 seconds; add a `query` to narrow it. With `query`, matches on dispute, payment, user or membership ID, buyer email, or a card's first 6 or 8 digits and last 4 separated by a space or dash (`424242 4242`); free-text queries such as a name search only the named account. Connected accounts' disputes are returned only for connected accounts you can read disputes on.", "in": "query", "name": "include_connected_accounts", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "groups": { "description": "One entry per requested breakdown, keyed by the field it groups on. A field you did not ask for is absent.", "properties": { "currency": { "additionalProperties": { "type": "integer" }, "description": "How many of the matching disputes are in each currency, keyed by three-letter ISO code. Only currencies with at least one dispute are present.", "example": { "usd": 1 }, "type": "object" }, "status": { "description": "How many of the matching disputes are in each status. Every status is present, including those with a count of zero.", "properties": { "lost": { "example": 0, "type": "integer" }, "needs_response": { "example": 1, "type": "integer" }, "prevented": { "example": 0, "type": "integer" }, "under_review": { "example": 0, "type": "integer" }, "warning_closed": { "example": 0, "type": "integer" }, "warning_needs_response": { "example": 0, "type": "integer" }, "warning_under_review": { "example": 0, "type": "integer" }, "won": { "example": 0, "type": "integer" } }, "required": [ "needs_response", "warning_needs_response", "under_review", "warning_under_review", "won", "lost", "prevented", "warning_closed" ], "type": "object" } }, "type": "object" }, "total": { "description": "How many disputes match the filters.", "example": 1, "type": "integer" } }, "required": [ "total", "groups" ], "type": "object" } } }, "description": "summary returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "an unrecognized breakdown" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "payment:dispute:read" ] } ], "summary": "Retrieve Dispute Summary", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/disputes/{id}": { "get": { "description": "Retrieves a single dispute.", "operationId": "retrieveDispute", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "dispute returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" } }, "security": [ { "bearerAuth": [ "payment:dispute:read" ] } ], "summary": "Retrieve Dispute", "tags": [ "Disputes" ] }, "parameters": [ { "description": "The dispute ID (`dspt_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Edits a dispute's evidence while it is still editable. When the evidence is ready, send it to the payment processor with `POST /disputes/:id/submit`.", "operationId": "updateDispute", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "evidence": { "description": "The evidence packet to send to the processor. Only the fields you provide are changed.", "properties": { "access_activity_log": { "description": "Log of the customer's access to the product, such as sign-in or download activity.", "example": "Vehicle checked in 2026-01-04 09:02, released 2026-01-05 16:40. Signed release on file.", "type": [ "string", "null" ] }, "billing_address": { "description": "The billing address the customer provided at checkout.", "example": "4180 Burnet Rd, Austin, TX 78756, US", "type": [ "string", "null" ] }, "cancellation_policy_attachment": { "description": "The cancellation policy document. Defaults to the account's cancellation policy, then its terms of service, when not set.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "cancellation_policy_disclosure": { "description": "How the cancellation policy was shown to the customer before purchase.", "example": "Shown at checkout and again in the booking confirmation email.", "type": [ "string", "null" ] }, "customer_communication_attachment": { "description": "Correspondence with the customer, or proof they used the product.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "customer_email_address": { "description": "The email address the customer used at checkout.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "customer_name": { "description": "The customer's name as given at checkout.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "documents": { "description": "The full set of evidence documents the dispute should carry, beyond the four fixed evidence slots. Replaces all previously uploaded documents; an empty list removes them all. Send up to 10, 10MB each and 25MB in total. Accepted content types: application/pdf, application/json, image/jpeg, image/png, image/webp — any other type is rejected. Upload files through `POST /files` and reference them by `id`, or send the files as multipart file parts to upload and attach in one call. Policy documents (`return_policy`, `shipping_policy`, `cancellation_policy`, `terms_of_service`) default from the account's own documents; uploading one here replaces the account copy for this dispute, and a `cancellation_policy` or `return_policy` upload also takes precedence over the matching fixed evidence slot.", "items": { "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "type": "string" }, "document_type": { "description": "What this document proves, in the processor's own evidence vocabulary. `return_policy`, `cancellation_policy`, and `terms_of_service` are the seller's policy documents — uploading one overrides the account's copy for this dispute (`return_policy`, `cancellation_policy`, and `customer_communication` also override the matching fixed evidence slot). `shipping_policy` is the seller's shipping terms. `customer_communication` is correspondence with the buyer — a support thread or chat log. `product_image` is a photo of the product or service the buyer received. `physical_fulfillment` is proof a physical order shipped and arrived; `digital_fulfillment` is proof the buyer accessed a digital product. `customer_order_history` is the buyer's past orders with this seller; `prior_transactions` is their broader payment history across the platform, for a fraud defense. `customer_session` is checkout forensics — IP, device fingerprint, AVS/CVV, 3D Secure result. `subscription` is membership lifecycle evidence — renewals, cancellation, reminders sent.", "enum": [ "return_policy", "shipping_policy", "cancellation_policy", "terms_of_service", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription", "customer_communication" ], "example": "return_policy", "type": "string" }, "file": { "description": "The file itself. Send it as a file part to upload and attach in one call, or use `id`/`direct_upload_id` for a file that is already stored.", "format": "binary", "type": "string" }, "id": { "description": "The ID of a file already stored on Whop, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "document_type" ], "type": "object" }, "maxItems": 10, "type": "array" }, "notes": { "description": "Any additional context for the processor reviewing the dispute.", "example": "Two-day ceramic coating completed and collected. Before and after photos attached.", "type": [ "string", "null" ] }, "product_description": { "description": "What the customer purchased, in the seller's own words.", "example": "Two-stage paint correction with a three-year ceramic coating.", "type": [ "string", "null" ] }, "refund_policy_attachment": { "description": "The refund policy document. Defaults to the account's return policy when not set.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "refund_policy_disclosure": { "description": "How the refund policy was shown to the customer before purchase.", "example": "Linked from the booking page and accepted at checkout.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "Why a refund was refused, when one was requested and denied.", "example": "Work was completed and the vehicle collected, so the deposit is non-refundable.", "type": [ "string", "null" ] }, "service_date": { "description": "When the product or service was delivered.", "example": "2026-01-01", "type": [ "string", "null" ] }, "uncategorized_attachment": { "description": "Supporting evidence that does not fit the other categories.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } }, "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "evidence": { "description": "The evidence packet to send to the processor. Only the fields you provide are changed.", "properties": { "access_activity_log": { "description": "Log of the customer's access to the product, such as sign-in or download activity.", "example": "Vehicle checked in 2026-01-04 09:02, released 2026-01-05 16:40. Signed release on file.", "type": [ "string", "null" ] }, "billing_address": { "description": "The billing address the customer provided at checkout.", "example": "4180 Burnet Rd, Austin, TX 78756, US", "type": [ "string", "null" ] }, "cancellation_policy_attachment": { "description": "The cancellation policy document. Defaults to the account's cancellation policy, then its terms of service, when not set.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "cancellation_policy_disclosure": { "description": "How the cancellation policy was shown to the customer before purchase.", "example": "Shown at checkout and again in the booking confirmation email.", "type": [ "string", "null" ] }, "customer_communication_attachment": { "description": "Correspondence with the customer, or proof they used the product.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "customer_email_address": { "description": "The email address the customer used at checkout.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "customer_name": { "description": "The customer's name as given at checkout.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "documents": { "description": "The full set of evidence documents the dispute should carry, beyond the four fixed evidence slots. Replaces all previously uploaded documents; an empty list removes them all. Send up to 10, 10MB each and 25MB in total. Accepted content types: application/pdf, application/json, image/jpeg, image/png, image/webp — any other type is rejected. Upload files through `POST /files` and reference them by `id`, or send the files as multipart file parts to upload and attach in one call. Policy documents (`return_policy`, `shipping_policy`, `cancellation_policy`, `terms_of_service`) default from the account's own documents; uploading one here replaces the account copy for this dispute, and a `cancellation_policy` or `return_policy` upload also takes precedence over the matching fixed evidence slot.", "items": { "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "type": "string" }, "document_type": { "description": "What this document proves, in the processor's own evidence vocabulary. `return_policy`, `cancellation_policy`, and `terms_of_service` are the seller's policy documents — uploading one overrides the account's copy for this dispute (`return_policy`, `cancellation_policy`, and `customer_communication` also override the matching fixed evidence slot). `shipping_policy` is the seller's shipping terms. `customer_communication` is correspondence with the buyer — a support thread or chat log. `product_image` is a photo of the product or service the buyer received. `physical_fulfillment` is proof a physical order shipped and arrived; `digital_fulfillment` is proof the buyer accessed a digital product. `customer_order_history` is the buyer's past orders with this seller; `prior_transactions` is their broader payment history across the platform, for a fraud defense. `customer_session` is checkout forensics — IP, device fingerprint, AVS/CVV, 3D Secure result. `subscription` is membership lifecycle evidence — renewals, cancellation, reminders sent.", "enum": [ "return_policy", "shipping_policy", "cancellation_policy", "terms_of_service", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription", "customer_communication" ], "example": "return_policy", "type": "string" }, "file": { "description": "The file itself. Send it as a file part to upload and attach in one call, or use `id`/`direct_upload_id` for a file that is already stored.", "format": "binary", "type": "string" }, "id": { "description": "The ID of a file already stored on Whop, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "document_type" ], "type": "object" }, "maxItems": 10, "type": "array" }, "notes": { "description": "Any additional context for the processor reviewing the dispute.", "example": "Two-day ceramic coating completed and collected. Before and after photos attached.", "type": [ "string", "null" ] }, "product_description": { "description": "What the customer purchased, in the seller's own words.", "example": "Two-stage paint correction with a three-year ceramic coating.", "type": [ "string", "null" ] }, "refund_policy_attachment": { "description": "The refund policy document. Defaults to the account's return policy when not set.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "refund_policy_disclosure": { "description": "How the refund policy was shown to the customer before purchase.", "example": "Linked from the booking page and accepted at checkout.", "type": [ "string", "null" ] }, "refund_refusal_explanation": { "description": "Why a refund was refused, when one was requested and denied.", "example": "Work was completed and the vehicle collected, so the deposit is non-refundable.", "type": [ "string", "null" ] }, "service_date": { "description": "When the product or service was delivered.", "example": "2026-01-01", "type": [ "string", "null" ] }, "uncategorized_attachment": { "description": "Supporting evidence that does not fit the other categories.", "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The ID of an already-uploaded file.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "dispute updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the dispute's evidence can no longer be edited" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" } }, "security": [ { "bearerAuth": [ "payment:dispute" ] } ], "summary": "Update Dispute", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/disputes/{id}/accept": { "parameters": [ { "description": "The dispute ID (`dspt_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Accepts a chargeback, conceding it to the customer instead of contesting it. The payment processor closes the dispute as `lost`. This is final — the dispute cannot be contested afterwards. Only a dispute whose `acceptable` is true can be accepted.", "operationId": "acceptDispute", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "dispute accepted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the dispute can no longer be accepted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required dispute scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:dispute" ] } ], "summary": "Accept Dispute", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/disputes/{id}/submit": { "parameters": [ { "description": "The dispute ID (`dspt_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Sends a dispute's evidence to the payment processor. This is final — it cannot be edited or sent again.", "operationId": "submitDispute", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "dispute submitted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the dispute's evidence can no longer be submitted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:dispute" ] } ], "summary": "Submit Dispute", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/disputes/{id}/upload_evidence": { "parameters": [ { "description": "The dispute ID (`dspt_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Replaces the full set of uploaded evidence documents on a dispute, beyond the four fixed evidence slots. Prefer `PATCH /disputes/:id` with `evidence.documents`, which does the same replace alongside every other evidence field in one call.", "operationId": "uploadDisputeEvidence", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "documents": { "description": "The full set of evidence documents the dispute should carry, beyond the four fixed evidence slots. Replaces all previously uploaded documents; an empty list removes them all. Send up to 10, 10MB each and 25MB in total. Accepted content types: application/pdf, application/json, image/jpeg, image/png, image/webp — any other type is rejected. Upload files through `POST /files` and reference them by `id`, or send the files as multipart file parts to upload and attach in one call. Policy documents (`return_policy`, `shipping_policy`, `cancellation_policy`, `terms_of_service`) default from the account's own documents; uploading one here replaces the account copy for this dispute, and a `cancellation_policy` or `return_policy` upload also takes precedence over the matching fixed evidence slot.", "items": { "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "type": "string" }, "document_type": { "description": "What this document proves, in the processor's own evidence vocabulary. `return_policy`, `cancellation_policy`, and `terms_of_service` are the seller's policy documents — uploading one overrides the account's copy for this dispute (`return_policy`, `cancellation_policy`, and `customer_communication` also override the matching fixed evidence slot). `shipping_policy` is the seller's shipping terms. `customer_communication` is correspondence with the buyer — a support thread or chat log. `product_image` is a photo of the product or service the buyer received. `physical_fulfillment` is proof a physical order shipped and arrived; `digital_fulfillment` is proof the buyer accessed a digital product. `customer_order_history` is the buyer's past orders with this seller; `prior_transactions` is their broader payment history across the platform, for a fraud defense. `customer_session` is checkout forensics — IP, device fingerprint, AVS/CVV, 3D Secure result. `subscription` is membership lifecycle evidence — renewals, cancellation, reminders sent.", "enum": [ "return_policy", "shipping_policy", "cancellation_policy", "terms_of_service", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription", "customer_communication" ], "example": "return_policy", "type": "string" }, "file": { "description": "The file itself. Send it as a file part to upload and attach in one call, or use `id`/`direct_upload_id` for a file that is already stored.", "format": "binary", "type": "string" }, "id": { "description": "The ID of a file already stored on Whop, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "document_type" ], "type": "object" }, "maxItems": 10, "type": "array" } }, "required": [ "documents" ], "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "documents": { "description": "The full set of evidence documents the dispute should carry, beyond the four fixed evidence slots. Replaces all previously uploaded documents; an empty list removes them all. Send up to 10, 10MB each and 25MB in total. Accepted content types: application/pdf, application/json, image/jpeg, image/png, image/webp — any other type is rejected. Upload files through `POST /files` and reference them by `id`, or send the files as multipart file parts to upload and attach in one call. Policy documents (`return_policy`, `shipping_policy`, `cancellation_policy`, `terms_of_service`) default from the account's own documents; uploading one here replaces the account copy for this dispute, and a `cancellation_policy` or `return_policy` upload also takes precedence over the matching fixed evidence slot.", "items": { "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "type": "string" }, "document_type": { "description": "What this document proves, in the processor's own evidence vocabulary. `return_policy`, `cancellation_policy`, and `terms_of_service` are the seller's policy documents — uploading one overrides the account's copy for this dispute (`return_policy`, `cancellation_policy`, and `customer_communication` also override the matching fixed evidence slot). `shipping_policy` is the seller's shipping terms. `customer_communication` is correspondence with the buyer — a support thread or chat log. `product_image` is a photo of the product or service the buyer received. `physical_fulfillment` is proof a physical order shipped and arrived; `digital_fulfillment` is proof the buyer accessed a digital product. `customer_order_history` is the buyer's past orders with this seller; `prior_transactions` is their broader payment history across the platform, for a fraud defense. `customer_session` is checkout forensics — IP, device fingerprint, AVS/CVV, 3D Secure result. `subscription` is membership lifecycle evidence — renewals, cancellation, reminders sent.", "enum": [ "return_policy", "shipping_policy", "cancellation_policy", "terms_of_service", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription", "customer_communication" ], "example": "return_policy", "type": "string" }, "file": { "description": "The file itself. Send it as a file part to upload and attach in one call, or use `id`/`direct_upload_id` for a file that is already stored.", "format": "binary", "type": "string" }, "id": { "description": "The ID of a file already stored on Whop, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "document_type" ], "type": "object" }, "maxItems": 10, "type": "array" } }, "required": [ "documents" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } }, "description": "evidence documents attached" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unknown document_type" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no dispute with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:dispute" ] } ], "summary": "Upload Dispute Evidence", "tags": [ "Disputes" ] }, "x-whop-surface": "native" }, "/dm_channels": { "get": { "description": "Lists the authenticated user's DM channels, most recently active first.\n\nRequired permissions:\n - `dms:read`", "operationId": "listDmChannel", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "The unique identifier of a company to filter DM channels by. Only returns channels scoped to this company.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DmsFeed.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/DmChannelListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] } ], "summary": "List dm channels", "tags": [ "Dm channels" ], "x-group-title": "Engagement" }, "post": { "description": "Creates a DM channel between two or more users, optionally scoped to an account. Returns the existing channel if one already exists.\n\nRequired permissions:\n - `dms:channel:manage`", "operationId": "createDmChannel", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateDmChannelV2", "properties": { "account_id": { "description": "The unique identifier of the company to scope this DM channel to. When set, the channel is visible only within that company context.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "custom_name": { "description": "A custom display name for the DM channel. For example, 'Project Discussion'.", "type": [ "string", "null" ] }, "notifications_enabled": { "description": "Whether Whop app notifications are enabled for this direct message channel. Webhooks still fire.", "type": [ "boolean", "null" ] }, "with_user_ids": { "description": "The list of user identifiers to include in the DM channel. Each entry can be an email, username, or user ID (e.g. 'user_xxxxx').", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": "array" } }, "required": [ "with_user_ids" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:channel:manage" ] } ], "summary": "Create dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" } }, "/dm_channels/{id}": { "delete": { "description": "Permanently deletes a DM channel and all of its messages. Only a channel admin can delete it.\n\nRequired permissions (one of):\n - `dms:channel:manage`\n - `support_chat:create`", "operationId": "deleteDmChannel", "parameters": [ { "description": "The unique identifier of the DM channel to delete.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:channel:manage" ] }, { "bearerAuth": [ "support_chat:create" ] } ], "summary": "Delete dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing DM channel.\n\nRequired permissions (one of):\n - `dms:read`\n - `support_chat:read`", "operationId": "retrieveDmChannel", "parameters": [ { "description": "The unique identifier of the DM channel to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Retrieve dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" }, "patch": { "description": "Updates a DM channel's settings, such as its display name. Only a channel admin can update it.\n\nRequired permissions (one of):\n - `dms:channel:manage`\n - `support_chat:create`", "operationId": "updateDmChannel", "parameters": [ { "description": "The unique identifier of the DM channel to update.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateDmChannel", "properties": { "custom_name": { "description": "A new custom display name for the DM channel. For example, 'Project Discussion'.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:channel:manage" ] }, { "bearerAuth": [ "support_chat:create" ] } ], "summary": "Update dm channel", "tags": [ "Dm channels" ], "x-group-title": "Engagement" } }, "/dm_members": { "get": { "description": "Returns a paginated list of members in a specific DM channel, sorted by the date they were added.\n\nRequired permissions (one of):\n - `dms:read`\n - `support_chat:read`", "operationId": "listDmMember", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "channel_id", "required": true, "schema": { "description": "The unique identifier of the DM channel to list members for.", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DmsFeedMember.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/DmMemberListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "List dm members", "tags": [ "Dm members" ], "x-group-title": "Engagement" }, "post": { "description": "Add a new user to an existing DM channel. Only an admin of the channel can add members.\n\nRequired permissions (one of):\n - `dms:message:manage`\n - `support_chat:message:create`", "operationId": "createDmMember", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateDmMember", "properties": { "channel_id": { "description": "The unique identifier of the DM channel to add the new member to.", "type": "string" }, "user_id": { "description": "The unique identifier of the user to add to the DM channel. For example, 'user_xxxxx'.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "channel_id", "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmMember" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:message:manage" ] }, { "bearerAuth": [ "support_chat:message:create" ] } ], "summary": "Create dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" } }, "/dm_members/{id}": { "delete": { "description": "Remove a user from a DM channel. An admin can remove any member, and a member can remove themselves.\n\nRequired permissions (one of):\n - `dms:read`\n - `support_chat:read`", "operationId": "deleteDmMember", "parameters": [ { "description": "The unique identifier of the DM channel member to remove.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Delete dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing DM member.\n\nRequired permissions (one of):\n - `dms:read`\n - `support_chat:read`", "operationId": "retrieveDmMember", "parameters": [ { "description": "The unique identifier of the DM channel member to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmMember" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Retrieve dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" }, "patch": { "description": "Update a DM channel member's settings, such as their notification preferences or membership status.\n\nRequired permissions (one of):\n - `dms:read`\n - `support_chat:read`", "operationId": "updateDmMember", "parameters": [ { "description": "The unique identifier of the DM channel member to update.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateDmMember", "properties": { "notification_preference": { "description": "The notification setting for this member, controlling how they receive alerts for new messages in this channel.", "oneOf": [ { "$ref": "#/components/schemas/DmsFeedMemberNotificationPreferences" }, { "type": "null" } ] }, "status": { "description": "The membership status for this member in the DM channel.", "oneOf": [ { "$ref": "#/components/schemas/DmsFeedMemberStatuses" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmMember" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Update dm member", "tags": [ "Dm members" ], "x-group-title": "Engagement" } }, "/domains": { "get": { "description": "Lists your domains. Filter by account, app, status, hostname, or the state of a capability.\n\nPass `search` to find domains to buy instead: the exact domain first, even when taken, then your name on popular extensions, then suggestions. Pass `tlds` to check only the extensions you choose. Results aren't reserved.", "operationId": "listDomains", "parameters": [ { "description": "Only domains belonging to this account, prefixed biz_.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only domains whose website serves this app, prefixed app_.", "in": "query", "name": "app_id", "required": false, "schema": { "type": "string" } }, { "description": "Only domains with this status: the most pressing state of their capabilities, or `idle` when they want nothing.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "idle", "pending", "ready", "action_required", "releasing" ], "type": "string" } }, { "description": "Field to sort by. Domains with the same value keep their creation order in the same direction.", "in": "query", "name": "order", "required": false, "schema": { "default": "unique_visitors_last_7_days", "enum": [ "unique_visitors_last_7_days", "created_at", "updated_at", "domain" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "A name or domain to find domains to buy, such as `example` or `example.com`; a subdomain or URL searches its registrable domain. Returns domains with `availability` instead of your domains, without other filters or pagination.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "With `search`, check only these extensions, such as `com` or `co.uk`, returned in this order. Repeat for several, up to 100.", "in": "query", "name": "tlds", "required": false, "schema": { "items": { "example": "com", "type": "string" }, "type": "array" } }, { "description": "Only your domain with this hostname, such as `example.com`.", "in": "query", "name": "domain", "required": false, "schema": { "type": "string" } }, { "description": "Only domains with verification in this state, such as `ready`, or `any` for every domain that has verification.", "in": "query", "name": "verification", "required": false, "schema": { "enum": [ "pending", "ready", "action_required", "releasing", "any" ], "type": "string" } }, { "description": "Only domains with registration in this state, such as `ready`, or `any` for every domain that has registration.", "in": "query", "name": "registration", "required": false, "schema": { "enum": [ "pending", "ready", "action_required", "releasing", "any" ], "type": "string" } }, { "description": "Only domains with platform in this state, such as `ready`, or `any` for every domain that has platform.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "pending", "ready", "action_required", "releasing", "any" ], "type": "string" } }, { "description": "Only domains with website in this state, such as `ready`, or `any` for every domain that has website.", "in": "query", "name": "website", "required": false, "schema": { "enum": [ "pending", "ready", "action_required", "releasing", "any" ], "type": "string" } }, { "description": "Only domains with apple_pay in this state, such as `ready`, or `any` for every domain that has apple_pay.", "in": "query", "name": "apple_pay", "required": false, "schema": { "enum": [ "pending", "ready", "action_required", "releasing", "any" ], "type": "string" } }, { "description": "Only domains with pixel in this state, such as `ready`, or `any` for every domain that has pixel.", "in": "query", "name": "pixel", "required": false, "schema": { "enum": [ "pending", "ready", "action_required", "releasing", "any" ], "type": "string" } }, { "description": "Only domains with email in this state, such as `ready`, or `any` for every domain that has email.", "in": "query", "name": "email", "required": false, "schema": { "enum": [ "pending", "ready", "action_required", "releasing", "any" ], "type": "string" } }, { "description": "Only domains with transfer in this state, such as `ready`, or `any` for every domain that has transfer.", "in": "query", "name": "transfer", "required": false, "schema": { "enum": [ "pending", "ready", "action_required", "releasing", "any" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "search_results": { "value": { "data": [ { "account_id": null, "apple_pay": null, "availability": { "available": false, "premium": false, "price": null, "renewal_price": null, "score": 81, "transfer_price": { "amount": "14.99", "currency": "usd", "decimals": 2, "display_decimals": 2 } }, "created_at": null, "domain": "example.com", "email": null, "id": null, "issues": [], "metadata": {}, "owned_by": null, "pixel": null, "platform": null, "registration": null, "stats": null, "status": null, "transfer": null, "updated_at": null, "verification": null, "website": null }, { "account_id": null, "apple_pay": null, "availability": { "available": true, "premium": false, "price": { "amount": "24.99", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "renewal_price": { "amount": "29.99", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "score": 78, "transfer_price": null }, "created_at": null, "domain": "example.co", "email": null, "id": null, "issues": [], "metadata": {}, "owned_by": null, "pixel": null, "platform": null, "registration": null, "stats": null, "status": null, "transfer": null, "updated_at": null, "verification": null, "website": null }, { "account_id": null, "apple_pay": null, "availability": { "available": true, "premium": false, "price": { "amount": "12.99", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "renewal_price": { "amount": "14.99", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "score": 75, "transfer_price": null }, "created_at": null, "domain": "example.dev", "email": null, "id": null, "issues": [], "metadata": {}, "owned_by": null, "pixel": null, "platform": null, "registration": null, "stats": null, "status": null, "transfer": null, "updated_at": null, "verification": null, "website": null } ], "page_info": { "end_cursor": null, "has_next_page": false, "has_previous_page": false, "start_cursor": null } } } }, "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DomainListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Domain list" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid search" }, "429": { "$ref": "#/components/responses/TooManyRequests", "description": "Too many domain searches right now — wait for Retry-After before searching again" }, "503": { "$ref": "#/components/responses/ServiceUnavailable", "description": "The registrar is unavailable" } }, "security": [ { "bearerAuth": [ "domain:read" ] } ], "summary": "List Domains", "tags": [ "Domains" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Adds a domain to your account with the capabilities you want.\n\nPass `registration` to buy the domain through Whop; it's the default when you pass no capability. Pay its `amount_due` at `purchase_url`, or pass `registration.payment_method_id` to charge a saved card. Whop then registers it, runs its DNS, and renews it every year while `auto_renew` is on.\n\nPass `registration.auth_code` to transfer in a domain you own at another registrar. The transfer starts once its `amount_due` is paid, or at once when `amount_due` is `null`. While `registration.phase` is `transferring`, its `issues` say what the transfer needs from you.\n\nPass `verification` to connect a domain you registered elsewhere: its `issues` list the TXT and routing records to publish. Pass `website` with an `app_id` to serve that app on the domain.\n\nTo change a domain you already have, update it instead. Adding a domain this account deleted revives it under its original ID.", "operationId": "createDomain", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed biz_. Required for user credentials; otherwise defaults to the credential's account.", "type": "string" }, "apple_pay": { "description": "Accept Apple Pay at checkout on the domain. It needs no other capability. Whop registers the domain with Apple: it stays `pending` until Apple answers, then turns `ready`, or `action_required` when Apple couldn't fetch the domain association file. Serve the file, then check the domain to register it again. Pass `null` to turn Apple Pay off: Whop removes the domain from Apple, and the domain stays, like releasing any other capability.", "properties": {}, "type": [ "object", "null" ] }, "domain": { "description": "Bare hostname, such as example.com or checkout.example.com. A bought domain must be a root domain. Wildcards, paths, schemes, and ports are not accepted.", "example": "store.example.com", "type": "string" }, "email": { "description": "Send and receive email on the domain. Only a domain bought through Whop, or a subdomain of one in the same account, can have it. Whop publishes the DNS records and stays `pending` until its email provider verifies them, then turns `ready`. Pass `null` to remove email.", "properties": {}, "type": [ "object", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Custom string keys and values.", "example": { "project": "website" }, "type": "object" }, "pixel": { "description": "Track page views on the domain with the Whop pixel. It needs no other capability: it stays `pending` until the pixel records a page view, and turns `action_required` if it goes 7 days without one. Pass `null` to stop tracking.", "properties": {}, "type": [ "object", "null" ] }, "registration": { "description": "Buy the domain through Whop, or transfer in a domain you own elsewhere with `auth_code`, then renew it every year and let Whop run its DNS. Pass `null` to release an unpaid or failed purchase, or to cancel a transfer while its current registrar can still stop it.", "properties": { "auth_code": { "description": "Transfer the domain to Whop instead of buying it. This is the transfer authorization code (also called an EPP code) from the domain's current registrar, which you usually find in its domain settings after unlocking the domain. Whop becomes the domain's registrant, and the domain moves to Whop DNS once the transfer completes, so its current DNS records, including email, stop working. After the transfer, the registry may lock the domain against another transfer for 60 days. While it's `transferring`, pass the same or a new code again to resubmit. Whop never returns the code. To take a domain from another Whop account instead, pass the `whop_dt_` code from its `transfer`: the domain moves without a payment, keeps its expiry and Whop DNS, and can't be cancelled once entered.", "example": "Tr4nsfer-Code", "type": "string", "writeOnly": true }, "auto_renew": { "default": true, "description": "Whether Whop charges the saved card to renew the domain before it expires.", "type": "boolean" }, "payment_method_id": { "description": "Saved card to charge, prefixed `payt_`. It must belong to the signed-in user. Pass `null` to remove it.", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "transfer": { "description": "Move a domain registered through Whop to another Whop account. Turning it on returns a code in `transfer.code`; the receiving account enters it as `registration.auth_code` on its own copy of the domain. Whop then removes the domain's email, email addresses and Apple Pay from this account, moves the registration with its expiry, stops charging this account to renew it, and removes the domain from this account. Pass `null` to turn it off and invalidate the code, until another account has entered it.", "properties": { "destination": { "default": "internal", "description": "Where the domain moves. `internal` moves it to another Whop account.", "enum": [ "internal" ], "example": "internal", "type": "string" } }, "type": [ "object", "null" ] }, "verification": { "description": "Prove you control the domain's DNS: Whop returns a TXT record to publish in `issues`, and whoever publishes it owns the domain on Whop. Pass `null` to release it. Can't be combined with `registration`.", "properties": {}, "type": [ "object", "null" ] }, "website": { "description": "Serve a Whop website on the domain. Pass `null` to stop serving it; the domain keeps its other capabilities.", "properties": { "app_id": { "description": "App ID, prefixed app_, of the website to serve. The app must belong to the account. Leave it out to point the domain at Whop before the website exists; it shows a placeholder until you choose one. Pass `null` to detach the app and keep the domain pointed at Whop.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "required": [ "domain" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } }, "description": "Domain created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "The domain can't be bought" }, "409": { "$ref": "#/components/responses/Conflict", "description": "The account already has this domain" } }, "security": [ { "bearerAuth": [ "domain:manage" ] } ], "summary": "Create Domain", "tags": [ "Domains" ], "x-whop-credentials": [ "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/domains/{id}": { "delete": { "description": "Removes the domain from your account and releases its capabilities in the background. Deleting an unpaid purchase cancels it, and deleting a transfer cancels it and refunds it while the current registrar can still stop it. A registered domain can't be deleted; turn off `auto_renew` and it's released after it expires. Adding the domain to this account again revives it under the same ID.", "operationId": "deleteDomain", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } }, "description": "Domain deleted" }, "409": { "$ref": "#/components/responses/Conflict", "description": "The domain is registered" } }, "security": [ { "bearerAuth": [ "domain:manage" ] } ], "summary": "Delete Domain", "tags": [ "Domains" ] }, "get": { "description": "Retrieves a domain by ID or hostname. Both return the same domain, shown as fully as you can see it: everything for your own accounts, and only who has it and what it serves for anyone else.\n\nA hostname no domain on Whop has comes back with its `availability` instead.", "operationId": "retrieveDomain", "responses": { "200": { "content": { "application/json": { "examples": { "availability": { "value": { "account_id": null, "apple_pay": null, "availability": { "available": false, "premium": false, "price": null, "renewal_price": null, "score": 81, "transfer_price": { "amount": "14.99", "currency": "usd", "decimals": 2, "display_decimals": 2 } }, "created_at": null, "domain": "example.com", "email": null, "id": null, "issues": [], "metadata": {}, "owned_by": null, "pixel": null, "platform": null, "public_record": { "dnssec": false, "expires_at": "2027-08-13T04:00:00.000Z", "name_servers": [ "ns1.example.com", "ns2.example.com" ], "registered_at": "1995-08-14T04:00:00.000Z", "registrant": { "address": "Burlington\nMA", "contact_url": "https://registrar.example/contact/example.com", "country": "US", "email": null, "name": null, "organization": "Privacy Protect, LLC", "phone": null }, "registrar": { "iana_id": "9999", "name": "Example Registrar, Inc.", "url": "https://registrar.example" }, "statuses": [ "client transfer prohibited" ], "updated_at": "2026-08-14T07:01:44.000Z" }, "registration": null, "stats": null, "status": null, "transfer": null, "updated_at": null, "verification": null, "website": null } } }, "schema": { "$ref": "#/components/schemas/Domain" } } }, "description": "Domain details" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid hostname" }, "429": { "$ref": "#/components/responses/TooManyRequests", "description": "Too many domain lookups right now — wait for Retry-After before looking up a hostname again" } }, "security": [ { "bearerAuth": [ "domain:read" ] } ], "summary": "Retrieve Domain", "tags": [ "Domains" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Domain ID, prefixed `dom_`, or a hostname such as `example.com`; a bare name looks up `.com`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Changes a domain's capabilities or metadata. Pass a capability to add it or change its settings, or `null` to release it; capabilities you leave out don't change. Passing a capability that needs action again retries it. Releasing every capability keeps the domain, `idle`; delete it to remove it.", "operationId": "updateDomain", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "apple_pay": { "description": "Accept Apple Pay at checkout on the domain. It needs no other capability. Whop registers the domain with Apple: it stays `pending` until Apple answers, then turns `ready`, or `action_required` when Apple couldn't fetch the domain association file. Serve the file, then check the domain to register it again. Pass `null` to turn Apple Pay off: Whop removes the domain from Apple, and the domain stays, like releasing any other capability.", "properties": {}, "type": [ "object", "null" ] }, "email": { "description": "Send and receive email on the domain. Only a domain bought through Whop, or a subdomain of one in the same account, can have it. Whop publishes the DNS records and stays `pending` until its email provider verifies them, then turns `ready`. Pass `null` to remove email.", "properties": {}, "type": [ "object", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Replacement custom string keys and values.", "example": { "project": "storefront" }, "type": "object" }, "pixel": { "description": "Track page views on the domain with the Whop pixel. It needs no other capability: it stays `pending` until the pixel records a page view, and turns `action_required` if it goes 7 days without one. Pass `null` to stop tracking.", "properties": {}, "type": [ "object", "null" ] }, "registration": { "description": "Buy the domain through Whop, or transfer in a domain you own elsewhere with `auth_code`, then renew it every year and let Whop run its DNS. Pass `null` to release an unpaid or failed purchase, or to cancel a transfer while its current registrar can still stop it.", "properties": { "auth_code": { "description": "Transfer the domain to Whop instead of buying it. This is the transfer authorization code (also called an EPP code) from the domain's current registrar, which you usually find in its domain settings after unlocking the domain. Whop becomes the domain's registrant, and the domain moves to Whop DNS once the transfer completes, so its current DNS records, including email, stop working. After the transfer, the registry may lock the domain against another transfer for 60 days. While it's `transferring`, pass the same or a new code again to resubmit. Whop never returns the code. To take a domain from another Whop account instead, pass the `whop_dt_` code from its `transfer`: the domain moves without a payment, keeps its expiry and Whop DNS, and can't be cancelled once entered.", "example": "Tr4nsfer-Code", "type": "string", "writeOnly": true }, "auto_renew": { "default": true, "description": "Whether Whop charges the saved card to renew the domain before it expires.", "type": "boolean" }, "payment_method_id": { "description": "Saved card to charge, prefixed `payt_`. It must belong to the signed-in user. Pass `null` to remove it.", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "transfer": { "description": "Move a domain registered through Whop to another Whop account. Turning it on returns a code in `transfer.code`; the receiving account enters it as `registration.auth_code` on its own copy of the domain. Whop then removes the domain's email, email addresses and Apple Pay from this account, moves the registration with its expiry, stops charging this account to renew it, and removes the domain from this account. Pass `null` to turn it off and invalidate the code, until another account has entered it.", "properties": { "destination": { "default": "internal", "description": "Where the domain moves. `internal` moves it to another Whop account.", "enum": [ "internal" ], "example": "internal", "type": "string" } }, "type": [ "object", "null" ] }, "verification": { "description": "Prove you control the domain's DNS: Whop returns a TXT record to publish in `issues`, and whoever publishes it owns the domain on Whop. Pass `null` to release it. Can't be combined with `registration`.", "properties": {}, "type": [ "object", "null" ] }, "website": { "description": "Serve a Whop website on the domain. Pass `null` to stop serving it; the domain keeps its other capabilities.", "properties": { "app_id": { "description": "App ID, prefixed app_, of the website to serve. The app must belong to the account. Leave it out to point the domain at Whop before the website exists; it shows a placeholder until you choose one. Pass `null` to detach the app and keep the domain pointed at Whop.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } }, "description": "Domain updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "The change doesn't apply to this domain" } }, "security": [ { "bearerAuth": [ "domain:manage" ] } ], "summary": "Update Domain", "tags": [ "Domains" ] }, "x-whop-surface": "native" }, "/domains/{id}/check": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Domain ID, prefixed `dom_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Checks the domain's DNS, payment, and provider state again now instead of at its next scheduled check. Returns the domain as saved; retrieve it again to see the result.", "operationId": "checkDomain", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } }, "description": "Domain check started" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "domain:manage" ] } ], "summary": "Check Domain", "tags": [ "Domains" ] }, "x-whop-surface": "native" }, "/economic_intelligence": { "get": { "description": "Lists an account's recommendations and generation requests, newest first by default. When no recommendations are ready or in progress and you have `company:update` permission, listing queues generation, with a ten-minute cooldown after an unsuccessful request; unsuccessful requests are not listed. An account's executed recommendations and runs stay listed after Economic Intelligence turns off, but new recommendations are offered only while it is on. For visitor countries, page views, ad impressions and clicks, or payment volume over a time range, use `GET /stats/time_series/:metric`.", "operationId": "listEconomicIntelligence", "parameters": [ { "description": "Account ID, prefixed `biz_`. Defaults to the API key's own account; omit for personal onboarding, where signed-out visitors receive a business-setup template and eligible users receive their saved setup recommendation.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter recommendations by their current status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "queued", "pending", "ready", "running", "executed", "incomplete", "superseded" ], "type": "string" } }, { "description": "What you want recommendations for, in your own words. Up to 1000 characters. Narrows the list to the recommendations that address it. Without a `status` filter, when none do and you can update the account, new recommendations start generating for your input, and the list shows that request until they're ready. Repeating the same input while it generates doesn't start another.", "in": "query", "name": "input", "required": false, "schema": { "maxLength": 1000, "type": "string" } }, { "description": "When true, only recommendations someone has started running, by any user. Without `account_id`, covers every account you can read that has Economic Intelligence. Can't be combined with `input`.", "in": "query", "name": "has_run", "required": false, "schema": { "type": "boolean" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "run_started_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/EconomicIntelligence" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "recommendations listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unknown status" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account has no recommended actions entitlement" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not visible to the credential" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "ai_chat:create" ] }, {} ], "summary": "List Economic Intelligence", "tags": [ "Economic Intelligence" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/economic_intelligence/{id}": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Recommendation ID, prefixed `reca_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Account ID, prefixed `biz_`. Defaults to the API key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "patch": { "description": "Updates a recommendation status, records feedback, or both. Send `sentiment` to rate it. Include `status: superseded` to retire a ready recommendation and request replacements; a rating alone leaves its status unchanged. To run a recommendation yourself, send `status: running` to start, then `status: executed` when it is carried out (with `result_id` naming what it changed, or `result_page` naming where it worked, so the result links there) or `status: incomplete` if the run ended without carrying it out. Whop AI reports its own runs the same way. Send `status: acknowledged` once an executed run's result has been seen.", "operationId": "updateEconomicIntelligence", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "input": { "description": "What you want the replacement recommendation for, in your own words. Up to 1000 characters. Sent when superseding, it directs the generation that replaces the rejected recommendation.", "example": "Focus on returning buyers instead", "maxLength": 1000, "type": "string" }, "result_id": { "description": "With `status: executed`, the ID of what the run produced or changed, and the recommendation's `result_url` becomes where to view it: an ad (`ad_`), ad group (`adgrp_`) or ad campaign (`adcamp_`), a website (`app_`), a product (`prod_`), a plan (`plan_`), a checkout link (`ch_`), a promo code (`promo_`), or an experience (`exp_`). Without `result_id` or `result_page`, `result_url` links to the resource the recommendation was about, when it names one. Send only one of `result_id`, `result_page` and `result_url`.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "result_page": { "description": "With `status: executed`, the page where the run's result can be seen when it is not one resource, such as the checkout links list or the store page. The recommendation's `result_url` becomes that page on the account's dashboard, or its store page for `store_page`.", "enum": [ "home", "products", "ads", "websites", "checkout_links", "tracking_links", "promo_codes", "payments", "customers", "affiliates", "analytics", "store_page" ], "example": "promo_codes", "type": "string" }, "result_url": { "description": "With `status: executed`, where to view what was produced when it is outside Whop. An http or https URL. Prefer `result_id` for anything on Whop.", "example": "https://atlas.whop.site/", "maxLength": 2048, "type": "string" }, "sentiment": { "description": "A signed-in user can rate a recommendation as `positive` or `negative`. Can be sent alone or together with status.", "enum": [ "positive", "negative" ], "example": "positive", "type": "string" }, "status": { "description": "Use `running` to start a run of a ready recommendation, `executed` to record that it was carried out, `incomplete` to record that a running recommendation's run ended without carrying it out, `superseded` to reject a ready recommendation, or `acknowledged` to mark an executed run as seen; the recommendation stays `executed` and records `acknowledged_at`.", "enum": [ "running", "executed", "incomplete", "superseded", "acknowledged" ], "example": "superseded", "type": "string" }, "user_feedback": { "description": "An optional explanation of the rating or rejection. Negative feedback informs replacement recommendations.", "example": " Focus on returning buyers ", "maxLength": 2000, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EconomicIntelligence" } } }, "description": "recommendation superseded" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "status is not a supported transition" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account has no recommended actions entitlement" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown id, or a recommendation of another account" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the recommendation is not ready" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "Update Recommendation", "tags": [ "Economic Intelligence" ] }, "x-whop-surface": "native" }, "/email_addresses": { "get": { "description": "Lists the email addresses of the accounts you can read, and the mailboxes you own. A password is included only for mailboxes you can use.", "operationId": "listEmailAddresses", "parameters": [ { "description": "Only addresses belonging to this account, prefixed biz_.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "address" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/EmailAddress" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Email address list" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" } }, "security": [ { "bearerAuth": [ "email:read" ] } ], "summary": "List Email Addresses", "tags": [ "Email addresses" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a mailbox on one of the account's domains. The domain needs the `email` capability turned on. The address can be created and signed in to while email is still setting up, and it can send once email is `ready`. Give it to a team member with `user_id`, or leave it out to share the mailbox with the account. Creating an address this account deleted brings the mailbox back, with its mail and a new password.", "operationId": "createEmailAddress", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed biz_. Required for user credentials; otherwise defaults to the credential's account.", "type": "string" }, "address": { "description": "The full address, such as support@example.com. The part before the @ can use letters, numbers, dots, dashes, underscores and plus signs.", "example": "marcus@shinetime.example", "type": "string" }, "user_id": { "description": "ID of the team member who owns the mailbox, prefixed `user_`. Only they can read it or send from it. Leave it out, or pass `null`, to share the mailbox with the account. Giving an owned mailbox to someone else empties it: the owner's mail is never shown to anyone else.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "address" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddress" } } }, "description": "Email address created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "domain without email" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing email:manage" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "email:manage" ] } ], "summary": "Create Email Address", "tags": [ "Email addresses" ] }, "x-whop-surface": "native" }, "/email_addresses/{id}": { "delete": { "description": "Deletes the address. Mail apps signed in to it lose access, and mail sent to it is no longer received. Its mail is kept, and creating the address again in this account brings the mailbox back.", "operationId": "deleteEmailAddress", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddress" } } }, "description": "Email address deleted" } }, "security": [ { "bearerAuth": [ "email:manage" ] } ], "summary": "Delete Email Address", "tags": [ "Email addresses" ] }, "get": { "description": "Retrieves an email address. Its owner can always retrieve it; anyone else needs `email:read`. The password is included only if you can use the mailbox.", "operationId": "retrieveEmailAddress", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddress" } } }, "description": "Email address details" }, "404": { "$ref": "#/components/responses/NotFound", "description": "email address not found" } }, "security": [ { "bearerAuth": [ "email:read" ] } ], "summary": "Retrieve Email Address", "tags": [ "Email addresses" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Email address ID, prefixed `emaddr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Gives the mailbox to a team member, or shares it with the account, under a new password. A mailbox that had an owner starts empty, because its earlier mail is private to that owner; mail apps sync it again from the start.", "operationId": "updateEmailAddress", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "user_id": { "description": "ID of the team member who owns the mailbox, prefixed `user_`. Only they can read it or send from it. Leave it out, or pass `null`, to share the mailbox with the account. Giving an owned mailbox to someone else empties it: the owner's mail is never shown to anyone else.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddress" } } }, "description": "Email address updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "owner off the team" } }, "security": [ { "bearerAuth": [ "email:manage" ] } ], "summary": "Update Email Address", "tags": [ "Email addresses" ] }, "x-whop-surface": "native" }, "/email_addresses/{id}/mobileconfig": { "get": { "description": "Downloads an Apple configuration profile that adds the mailbox to Mail on a Mac, iPhone or iPad, signed in and ready to send. Only the owner can download it for an owned mailbox; a shared one needs `email:read` and `email:send`.", "operationId": "downloadEmailAddressMobileconfig", "responses": { "200": { "content": { "application/x-apple-aspen-config": { "schema": { "format": "binary", "type": "string" } } }, "description": "Configuration profile" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "mailbox owned by another user" } }, "security": [ { "bearerAuth": [ "email:read", "email:send" ] } ], "summary": "Download Email Address Configuration Profile", "tags": [ "Email addresses" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Email address ID, prefixed `emaddr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/email_addresses/{id}/reset_password": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Email address ID, prefixed `emaddr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Gives the mailbox a new password. Every mail app signed in with the old one loses access. Only the owner can reset an owned mailbox; a shared one needs `email:read` and `email:send`.", "operationId": "resetEmailAddressPassword", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddress" } } }, "description": "Password reset" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "mailbox owned by another user" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "email:read", "email:send" ] } ], "summary": "Reset Email Address Password", "tags": [ "Email addresses" ] }, "x-whop-surface": "native" }, "/events": { "get": { "description": "Lists identity-linked events, most recent first by default. Pass `identifier` for one person's journey, or omit it to list an account's events within a time range. Events have the same shape as the `POST /events` intake: attribution in `context`, identity in `user`.", "operationId": "listEvents", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Any hard identifier of the person: a person ID (prsn_*), user ID, email, phone number, or a tracking cookie value (wuid, anonymous ID, fbp/fbc/ttp/ga). Omit to list recent events for the account.", "in": "query", "name": "identifier", "required": false, "schema": { "type": "string" } }, { "description": "Account ID, prefixed `biz_`. Optional for account API keys; required for credentials that can access multiple accounts.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Start of the time range as an ISO 8601 timestamp. Required when identifier is omitted.", "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "End of the time range as an ISO 8601 timestamp. Required when identifier is omitted; otherwise defaults to now.", "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 500, "maximum": 500, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The order events are returned in by time. Defaults to desc (most recent first); asc reads a journey forwards from where it starts. after and before always page forwards and backwards through that order.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Full event names to filter by, comma-separated (payment.completed, pixel.lead, pixel.page, pixel.custom:) — the same vocabulary the events / people metrics use.", "in": "query", "name": "event", "required": false, "schema": { "type": "string" } }, { "description": "Canonical source path, exact or with a trailing :* prefix (whop::*, ext:meta:*, referrer:, direct, unknown). Selects conversions credited to this source.", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Attribution model for the source filter (defaults to last_touch).", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "Country codes to filter by, comma-separated.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "Cities to filter by, comma-separated.", "in": "query", "name": "city", "required": false, "schema": { "type": "string" } }, { "description": "Device families to filter by, comma-separated (e.g. iPhone, Mac).", "in": "query", "name": "device", "required": false, "schema": { "type": "string" } }, { "description": "Browser families to filter by, comma-separated (e.g. Chrome, Mobile Safari).", "in": "query", "name": "browser", "required": false, "schema": { "type": "string" } }, { "description": "Operating system families to filter by, comma-separated (e.g. iOS, Windows).", "in": "query", "name": "os", "required": false, "schema": { "type": "string" } }, { "description": "utm_source values to filter by, comma-separated.", "in": "query", "name": "utm_source", "required": false, "schema": { "type": "string" } }, { "description": "Page hostnames to filter by, comma-separated.", "in": "query", "name": "hostname", "required": false, "schema": { "type": "string" } }, { "description": "Page paths to filter by, comma-separated.", "in": "query", "name": "page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "context": { "properties": { "ad_campaign_id": { "example": "adcamp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "ad_click_id": { "description": "Stable identity for the ad click this event belongs to. Every event from one click carries the same value, so events group into clicks without re-deriving them.", "example": "IwAR123", "type": [ "string", "null" ] }, "ad_click_type": { "description": "How the ad click was identified: the network's click-id param (`fbclid`, `ttclid`, `gclid`, `gbraid`, `wbraid`, `twclid`) or `synthetic` when the click carried none.", "example": "fbclid", "type": [ "string", "null" ] }, "ad_id": { "example": "ad_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "ad_set_id": { "example": "adgrp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source_type": { "description": "How this event counts as an acquisition touch, using the same rule attribution credits a conversion with. `ad_click` and `lead_form` resolved to a Whop ad; `external_ad_click` is a paid click on a campaign run outside Whop; `referrer` is organic. Null when the event is not a touch.", "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", null ], "example": "ad_click", "type": [ "string", "null" ] }, "utm_campaign": { "example": "brand", "type": [ "string", "null" ] }, "utm_content": { "example": "creative", "type": [ "string", "null" ] }, "utm_medium": { "example": "paid", "type": [ "string", "null" ] }, "utm_source": { "example": "google", "type": [ "string", "null" ] }, "utm_term": { "example": "keyword", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "currency": { "example": "usd", "type": [ "string", "null" ] }, "custom_name": { "example": "coating_deposit_paid", "type": [ "string", "null" ] }, "event_id": { "example": "evt_124", "type": "string" }, "event_name": { "example": "pixel.custom", "type": "string" }, "event_time": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "example": "evt_124", "type": "string" }, "path": { "example": "/checkout/complete", "type": [ "string", "null" ] }, "person_id": { "example": "prsn_123", "type": "string" }, "questions": { "items": { "properties": { "answer": { "example": "SUV", "type": [ "string", "null" ] }, "id": { "example": "q_2", "type": [ "string", "null" ] }, "key": { "example": "vehicle_type", "type": [ "string", "null" ] }, "options": { "items": { "example": "Truck", "type": "string" }, "type": [ "array", "null" ] }, "question": { "example": "What vehicle are we detailing?", "type": [ "string", "null" ] }, "type": { "example": "custom", "type": [ "string", "null" ] } }, "type": "object" }, "type": [ "array", "null" ] }, "referrer_url": { "example": "https://google.com", "type": [ "string", "null" ] }, "related": { "description": "Hydrated details for the records this event references. Only present keys resolved.", "properties": { "account": { "properties": { "id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "ad": { "description": "The Whop ad this event's click resolved to.", "properties": { "id": { "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "thumbnail_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "example": "Ceramic coating — before/after reel", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "ad_campaign": { "description": "The Whop ad campaign this event's click resolved to, read from the ad entity tree rather than the click's url params.", "properties": { "id": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "platform": { "example": "whop_ads", "type": [ "string", "null" ] }, "title": { "example": "Ceramic coating — spring push", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "ad_group": { "description": "The Whop ad group this event's click resolved to.", "properties": { "id": { "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "title": { "example": "Austin — SUV owners", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "app": { "properties": { "domain_id": { "example": "whopappdomain0000001", "type": [ "string", "null" ] }, "icon_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "title": { "example": "Shine Time Booking", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "audience": { "description": "The saved audience this event came from. Present on the identify events an audience ingest writes for each of its members.", "properties": { "audience_type": { "enum": [ "custom", "lookalike", null ], "example": "custom", "type": [ "string", "null" ] }, "file_name": { "example": "shine-time-customers.csv", "type": [ "string", "null" ] }, "id": { "example": "adaud_xxxxxxxxxxxxxx", "type": "string" }, "source_type": { "enum": [ "csv_upload", "people_filter", "engagement", null ], "example": "csv_upload", "type": [ "string", "null" ] }, "title": { "example": "Austin ceramic coating leads", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "payment": { "properties": { "card_brand": { "example": "visa", "type": [ "string", "null" ] }, "card_last4": { "example": "4242", "type": [ "string", "null" ] }, "id": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "line_items": { "description": "Everything this payment charged for, in purchase order, including quantities. Older payments fall back to their original variant.", "items": { "$ref": "#/components/schemas/ReceiptLineItem" }, "type": "array" }, "provider": { "example": "stripe", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "product": { "properties": { "id": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "route": { "example": "ceramic-coating-package", "type": [ "string", "null" ] }, "title": { "example": "Ceramic Coating Package", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "user": { "properties": { "avatar_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "example": "danawhitfield", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "variant": { "properties": { "billing_period": { "example": 30, "type": [ "integer", "null" ] }, "currency": { "example": "usd", "type": [ "string", "null" ] }, "id": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "example": 0.0, "type": [ "number", "null" ] }, "renewal_price": { "example": 59.0, "type": [ "number", "null" ] }, "title": { "example": "Unlimited Wash Club", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "type": [ "object", "null" ] }, "total_usd_amount": { "example": 249.0, "type": [ "number", "null" ] }, "url": { "example": "https://shinetime.example/checkout/complete", "type": [ "string", "null" ] }, "user": { "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "example": "US", "type": [ "string", "null" ] }, "email": { "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Dana", "type": [ "string", "null" ] }, "last_name": { "example": "Whitfield", "type": [ "string", "null" ] }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "phone": { "example": "5551234567", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "value": { "example": 249.0, "type": [ "number", "null" ] } }, "required": [ "id", "event_id", "event_name", "person_id", "event_time" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_end", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_start", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "events listed oldest first" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid direction" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "member:basic:read" ] }, { "bearerAuth": [ "member:journey:read" ] } ], "summary": "List Events", "tags": [ "Events" ] }, "post": { "description": "Tracks a conversion or engagement event for an account, such as a lead or a sign-up, so it can be attributed to the ads and links that drove it. Send server-side events with an API key that has `event:create`; the browser pixel calls this without authentication.", "operationId": "createEvent", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateConversion", "properties": { "account_id": { "description": "The account to associate with this event.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "action_source": { "description": "Where the event originated.", "oneOf": [ { "description": "The channel where an event originated", "enum": [ "email", "website", "app", "phone_call", "chat", "physical_store", "system_generated", "business_messaging", "other" ], "example": "website", "type": "string" }, { "type": "null" } ] }, "app_build_id": { "description": "The build of the hosted app that served the page where the event occurred.", "example": "apbu_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "app_id": { "description": "The hosted app that served the page where the event occurred.", "example": "app_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "context": { "description": "Tracking and attribution context.", "properties": { "ad_campaign_id": { "description": "Ad campaign ID.", "example": "23851234567890123", "type": [ "string", "null" ] }, "ad_id": { "description": "Ad ID.", "example": "23851234567890125", "type": [ "string", "null" ] }, "ad_set_id": { "description": "Ad set ID.", "example": "23851234567890124", "type": [ "string", "null" ] }, "fbc": { "description": "Facebook click cookie (_fbc, format fb.1.{timestamp}.{fbclid}).", "example": "fb.1.xxxxxxxxxx.IwAR0shine", "type": [ "string", "null" ] }, "fbclid": { "description": "Facebook click ID.", "example": "IwAR0shineTimeAutoDetailing", "type": [ "string", "null" ] }, "fbp": { "description": "Facebook browser pixel ID.", "example": "fb.1.xxxxxxxxxx.xxxxxxxxxx", "type": [ "string", "null" ] }, "fingerprint": { "description": "Client-side device fingerprint.", "example": "fp_4d19c7", "type": [ "string", "null" ] }, "fingerprint_confidence": { "description": "Confidence score (0-1) for the device fingerprint.", "example": 6.9, "type": [ "number", "null" ] }, "ga": { "description": "Google Analytics client ID.", "example": "GA1.1.xxxxxxxxxx.xxxxxxxxxx", "type": [ "string", "null" ] }, "gbraid": { "description": "Google Ads gbraid click ID (iOS privacy).", "example": "0AAAAA-shinetime", "type": [ "string", "null" ] }, "gclid": { "description": "Google click ID.", "example": "Cj0KCQiAshinetime", "type": [ "string", "null" ] }, "ig_sid": { "description": "Instagram session ID.", "example": "ig_shinetime_1", "type": [ "string", "null" ] }, "ip_address": { "description": "IP address.", "example": "1.2.3.4", "type": [ "string", "null" ] }, "language": { "description": "Browser language (e.g. en-US).", "example": "en-US", "type": [ "string", "null" ] }, "li_fat_id": { "description": "LinkedIn click ID.", "example": "lifat-shinetime", "type": [ "string", "null" ] }, "msclkid": { "description": "Microsoft Advertising (Bing) click ID.", "example": "a1b2c3d4shine", "type": [ "string", "null" ] }, "rdt_cid": { "description": "Reddit click ID.", "example": "t2_shinetime", "type": [ "string", "null" ] }, "sc": { "description": "Whop SC identifier.", "example": "BDFB1C71", "type": [ "string", "null" ] }, "sccid": { "description": "Snapchat click ID.", "example": "sccid-shinetime", "type": [ "string", "null" ] }, "screen_resolution": { "description": "Screen resolution (e.g. 1920x1080).", "example": "390x844", "type": [ "string", "null" ] }, "timezone": { "description": "IANA timezone (e.g. America/New_York).", "example": "America/Chicago", "type": [ "string", "null" ] }, "ttclid": { "description": "TikTok click ID.", "example": "E.C.P.ttclid.shine", "type": [ "string", "null" ] }, "ttp": { "description": "TikTok pixel ID.", "example": "2ShineTimeTtp", "type": [ "string", "null" ] }, "twclid": { "description": "X (Twitter) click ID.", "example": "twclid-shinetime", "type": [ "string", "null" ] }, "user_agent": { "description": "Browser user agent string.", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15", "type": [ "string", "null" ] }, "utm_campaign": { "description": "UTM campaign parameter.", "example": "ceramic-coating-spring", "type": [ "string", "null" ] }, "utm_content": { "description": "UTM content parameter.", "example": "carousel-a", "type": [ "string", "null" ] }, "utm_id": { "description": "UTM ID parameter.", "example": "utm_88213", "type": [ "string", "null" ] }, "utm_medium": { "description": "UTM medium parameter.", "example": "cpc", "type": [ "string", "null" ] }, "utm_source": { "description": "UTM source parameter.", "example": "google", "type": [ "string", "null" ] }, "utm_term": { "description": "UTM term parameter.", "example": "ceramic coating austin", "type": [ "string", "null" ] }, "wbraid": { "description": "Google Ads wbraid click ID (iOS privacy).", "example": "Cj0KCQjw-wbraid-shine", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "currency": { "description": "ISO 4217 currency code.", "oneOf": [ { "description": "The available currencies on the platform", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, { "type": "null" } ] }, "custom_name": { "description": "Custom event name when event_name is 'custom'. Maximum 35 chars for this value.", "example": "coating_deposit_paid", "type": [ "string", "null" ] }, "duration": { "description": "For 'leave' events: milliseconds the visitor spent on the page.", "example": 42, "type": [ "integer", "null" ] }, "event_id": { "description": "Client-provided identifier for deduplication. Generated if omitted.", "example": "evnt_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "event_name": { "description": "The type of event.\n\nUse a standard event (lead, submit_application, contact, complete_registration, schedule, view_content, add_to_cart) or pass your own name directly for a custom event.", "example": "coating_deposit_paid", "type": "string" }, "event_time": { "description": "When the event occurred. Defaults to now.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": [ "string", "null" ] }, "plan_id": { "description": "The variant associated with the event.", "example": "plan_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product associated with the event.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "referrer_url": { "description": "The referring URL.", "example": "https://www.google.com/", "type": [ "string", "null" ] }, "resumed": { "description": "For 'page' events: true when the page was restored from the back/forward cache.", "example": false, "type": [ "boolean", "null" ] }, "source": { "description": "For 'identify' events: where the identity was captured (url, form, manual, iframe).", "example": "website", "type": [ "string", "null" ] }, "title": { "description": "For 'page' events: the document title.", "example": "Ceramic coating quote request", "type": [ "string", "null" ] }, "url": { "description": "The URL where the event occurred.", "example": "https://shinetime.example/quote", "type": [ "string", "null" ] }, "user": { "description": "User identity and profile data.", "properties": { "anonymous_id": { "description": "An anonymous identifier for the user.", "example": "anon_8f2c41", "type": [ "string", "null" ] }, "birthdate": { "description": "Date of birth (YYYY-MM-DD).", "example": "1990-01-15", "type": [ "string", "null" ] }, "city": { "description": "City.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Country.", "example": "US", "type": [ "string", "null" ] }, "email": { "description": "Email address.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "external_id": { "description": "An external identifier for the user.", "example": "crm_8842", "type": [ "string", "null" ] }, "first_name": { "description": "First name.", "example": "Dana", "type": [ "string", "null" ] }, "gender": { "description": "Gender.", "oneOf": [ { "description": "Gender", "enum": [ "male", "female" ], "example": "female", "type": "string" }, { "type": "null" } ] }, "last_name": { "description": "Last name.", "example": "Whitfield", "type": [ "string", "null" ] }, "linked_anonymous_id": { "description": "A second anonymous identifier to link to this user (e.g. captured across an iframe boundary).", "example": "anon_1b9de0", "type": [ "string", "null" ] }, "linked_wuid": { "description": "A wuid from a linked frame, captured across an iframe boundary.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "member_id": { "description": "The Whop member ID.", "example": "mber_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "membership_id": { "description": "The Whop membership ID.", "example": "mem_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "name": { "description": "Full display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "phone": { "description": "Phone number.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State or region.", "example": "TX", "type": [ "string", "null" ] }, "user_id": { "description": "The Whop user ID.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "username": { "description": "Username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [], "type": [ "object", "null" ] }, "value": { "description": "Monetary value associated with the event.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "account_id", "event_name" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "example": "evnt_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "description": "event created" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "event:create" ] }, {} ], "summary": "Create Event", "tags": [ "Events" ] }, "x-whop-surface": "native" }, "/events/pulse": { "get": { "description": "Returns a fully anonymized feed of recent money movement across Whop, most recent first, such as purchases, card spend, and transfers between accounts. Each item carries only its `type`, a USD amount, a coarse location, and a timestamp coarsened to the minute. The payload is identical for every caller and requires no authentication.", "operationId": "retrievePulse", "parameters": [ { "description": "Filter to one or more types, comma separated — for example `purchase,card_spend`. These are the item's `type`, not its `event_name`: several types share the `ledger_line.created` event name. Omit for every type in the feed. Values outside the feed's own set are rejected.", "in": "query", "name": "event", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 50, "maximum": 50, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Recent anonymized money-movement events, newest first.", "items": { "properties": { "event_name": { "description": "The underlying event recorded. Every movement on this feed is a ledger line, so switch on `type` rather than this.", "enum": [ "ledger_line.created" ], "example": "ledger_line.created", "type": "string" }, "event_time": { "description": "When the event happened, coarsened to the start of the minute.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "total_usd_amount": { "description": "The USD amount of the event.", "example": 45.5, "type": [ "number", "null" ] }, "type": { "description": "What moved: a purchase, an affiliate commission, Whop card spend, ad spend, app revenue, an off-platform sale, a wallet deposit, a card load, a claimed drop, a transfer between accounts, or a referral bonus.", "enum": [ "purchase", "affiliate_commission", "card_spend", "ad_spend", "app_revenue", "off_platform_sale", "deposit", "card_load", "airdrop_claim", "transfer", "referral_bonus" ], "example": "purchase", "type": "string" }, "user": { "description": "Coarse location, shaped like the event `user` block. It belongs to the owner of the wallet the money moved into or out of — the party the event is about, never their counterparty. Omitted entirely when nothing is known.", "properties": { "city": { "description": "City name. Omitted when unknown.", "example": "Austin", "type": "string" }, "country": { "description": "ISO 3166-1 alpha-2 country code. Omitted when unknown.", "example": "US", "type": "string" } }, "type": "object" } }, "required": [ "event_name", "type", "event_time" ], "type": "object" }, "maxItems": 50, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_end", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_start", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "pulse feed filtered to one type" }, "400": { "description": "event given as an event name rather than a type" } }, "security": [], "summary": "Retrieve the pulse feed", "tags": [ "Events" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/events/validate_pixel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Checks whether the Whop pixel is installed for an account, or on one page when you pass a `url`. Use it before launching an ad to confirm its destination is tracked, or in a setup flow to tell a merchant whether their install is live.", "operationId": "validatePixel", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account to check. Defaults to the authenticated account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "url": { "description": "A page to check for the pixel, such as an ad destination. Events from that page settle the answer; if it hasn't sent any lately, it is fetched and its source read for the pixel and the conversion events wired on it. Omit it to check the account from its events alone.", "example": "https://shinetime.example/checkout/complete", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixelValidation" } } }, "description": "pixel validated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "key lacks the required scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "member:basic:read" ] }, { "bearerAuth": [ "member:journey:read" ] } ], "summary": "Validate Pixel", "tags": [ "Events" ] }, "x-whop-surface": "native" }, "/experiences": { "get": { "description": "Lists the experiences in an account, optionally filtered to those attached to one product or powered by one app.", "operationId": "listExperience", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_id", "required": false, "schema": { "description": "Filter to only experiences attached to this product identifier.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "app_id", "required": false, "schema": { "description": "Filter to only experiences powered by this app identifier.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return experiences created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return experiences created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": true, "schema": { "description": "The unique identifier of the company to list experiences for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PublicExperience.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ExperienceListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List experiences", "tags": [ "Experiences" ], "x-group-title": "Engagement" }, "post": { "description": "Creates an experience for an account, powered by an app such as courses, forums, or chat. Attach it to a product with `POST /experiences/:id/attach` to give that product's customers access.\n\nRequired permissions:\n - `experience:create`", "operationId": "createExperience", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateExperience", "properties": { "account_id": { "description": "The unique identifier of the company to create this experience for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "app_id": { "description": "The unique identifier of the app that powers this experience.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "is_public": { "description": "Whether the experience is publicly accessible without a membership.", "type": [ "boolean", "null" ] }, "logo": { "description": "A logo image displayed alongside the experience name.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "name": { "description": "The display name of the experience. Defaults to the app's name if not provided.", "type": [ "string", "null" ] }, "notifications_enabled": { "description": "Whether Whop app notifications are enabled for this experience. Webhooks still fire.", "type": [ "boolean", "null" ] }, "section_id": { "description": "The unique identifier of the section to place the experience in.", "type": [ "string", "null" ] } }, "required": [ "app_id", "account_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:create" ] } ], "summary": "Create experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiences/{id}": { "delete": { "description": "Deletes an experience and detaches it from every product, removing customer access to it. Returns `true` on success.\n\nRequired permissions:\n - `experience:delete`", "operationId": "deleteExperience", "parameters": [ { "description": "The unique identifier of the experience to delete.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:delete" ] } ], "summary": "Delete experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing experience.", "operationId": "retrieveExperience", "parameters": [ { "description": "The unique identifier of the experience.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" }, "patch": { "description": "Updates an experience's name, logo, visibility, or notification setting, or moves it to another section or position.\n\nRequired permissions:\n - `experience:update`", "operationId": "updateExperience", "parameters": [ { "description": "The unique identifier of the experience to update.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateExperience", "properties": { "access_level": { "description": "The access level of the experience.", "oneOf": [ { "$ref": "#/components/schemas/ExperienceAccessLevels" }, { "type": "null" } ] }, "is_public": { "description": "Whether the experience is publicly accessible without a membership.", "type": [ "boolean", "null" ] }, "logo": { "description": "A logo image displayed alongside the experience name.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "name": { "description": "The display name of the experience.", "type": [ "string", "null" ] }, "notifications_enabled": { "description": "Whether Whop app notifications are enabled for this experience. Webhooks still fire.", "type": [ "boolean", "null" ] }, "order": { "description": "The position of the experience within its section for display ordering.", "example": "123.45", "type": [ "string", "null" ] }, "section_id": { "description": "The unique identifier of the section to move the experience into.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:update" ] } ], "summary": "Update experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiences/{id}/attach": { "post": { "description": "Attaches an experience to a product, giving the product's customers access to it.\n\nRequired permissions:\n - `experience:attach`", "operationId": "attachExperience", "parameters": [ { "description": "The unique identifier of the experience to attach.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for AddExperienceToAccessPass", "properties": { "product_id": { "description": "The unique identifier of the product to attach the experience to.", "example": "prod_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "product_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:attach" ] } ], "summary": "Attach experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiences/{id}/detach": { "post": { "description": "Detaches an experience from a product, removing customer access to it through that product.\n\nRequired permissions:\n - `experience:detach`", "operationId": "detachExperience", "parameters": [ { "description": "The unique identifier of the experience to detach.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for RemoveExperienceFromAccessPass", "properties": { "product_id": { "description": "The unique identifier of the product to detach the experience from.", "example": "prod_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "product_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:detach" ] } ], "summary": "Detach experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiences/{id}/duplicate": { "post": { "description": "Duplicates an experience and attaches the copy to the same products as the original. Forum and chat copies keep the original's settings, such as who can post or comment. No content, such as posts, messages, or lessons, is copied.\n\nRequired permissions:\n - `experience:create`", "operationId": "duplicateExperience", "parameters": [ { "description": "The unique identifier of the experience to duplicate.", "in": "path", "name": "id", "required": true, "schema": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for DuplicateExperience", "properties": { "name": { "description": "The display name for the duplicated experience. Defaults to the original experience's name.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experience" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "experience:create" ] } ], "summary": "Duplicate experience", "tags": [ "Experiences" ], "x-group-title": "Engagement" } }, "/experiments": { "get": { "description": "Lists the experiments and feature flags owned by an account. Requires `experiment:read` on the account.", "operationId": "listExperiments", "parameters": [ { "description": "Owning account ID.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by related resource; requires account_id.", "explode": true, "in": "query", "name": "related_resource", "required": false, "schema": { "$ref": "#/components/schemas/ExperimentResourceReference" }, "style": "deepObject" }, { "description": "Only experiments with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "draft", "active", "paused", "ended" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort experiments by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "flag_key" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Experiment" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "experiments listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Experiments", "tags": [ "Experiments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an experiment or feature flag in `draft` status for an account. Nothing is served until you activate it with `POST /experiments/:id/activate`. Requires `experiment:manage` on the account.", "operationId": "createExperiment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Owning account ID. Required; ownership cannot change.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "bucket_by": { "description": "Randomization unit, and the only identity the assignment is keyed on — evaluation fails rather than falling back to another. `user` (default) uses `subject[user_id]`; `account` uses `subject[account_id]`, so every user of an account gets the same arm; `anonymous` uses the anonymous id and survives sign-in. Fixed after creation.", "enum": [ "user", "account", "anonymous" ], "example": "user", "type": "string" }, "control": { "properties": { "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "nullable": true } }, "type": "object" }, "feature_flag_only": { "description": "When `true`, creates a binary feature flag rather than a full experiment. Feature flags expose the same evaluation API but do not collect metric results. Defaults to `false`.", "type": "boolean" }, "flag_key": { "description": "Developer-chosen handle referenced from code, used in evaluation and results calls. Interchangeable with the returned `expt_` id anywhere the API takes an experiment identifier.", "example": "checkout_redesign_v2", "type": "string" }, "hypothesis": { "description": "Required for full experiments; rejected on feature flags. Structure it as \"If we [change] for [cohort], then [measurable behavior] will [increase/decrease], resulting in [business outcome], because [evidence]. Created by [name].\" Evidence should be something real — a baseline number, a funnel breakdown — not a guess, and [name] is you, not something to leave blank.", "example": "If we send a blueprint nudge email 30 minutes after business creation, then GTV within 10 hours will increase among newly created businesses, resulting in more new business operators generating GTV within 10 hours, because operators currently land on an empty dashboard with no concrete next step. Created by Jane Doe.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable display name. Defaults to `flag_key` when omitted.", "example": "Checkout Redesign V2", "type": "string" }, "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "description": "Resource owned by the account that this experiment is bound to, such as an app or product. `null` when unbound. Fixed once the experiment first activates.", "nullable": true }, "targeting_rules": { "description": "Rules that determine which subjects qualify for the experiment.", "items": { "properties": { "conditions": { "description": "Conditions within this rule. Must be non-empty. All conditions must be satisfied for the rule to match (AND logic). Rules are OR-ed together.", "items": { "properties": { "field": { "description": "Property name to read from the user context. Required when `type` is `property`.", "nullable": true, "type": "string" }, "operator": { "description": "Comparison to apply: `any`/`none` — inclusion/exclusion list; `eq`/`neq` — equality; `gt`/`gte`/`lt`/`lte` — numeric range.", "enum": [ "any", "none", "eq", "neq", "gt", "gte", "lt", "lte" ], "example": "any", "type": "string" }, "type": { "description": "`user_id` — match on subject user ID; `account_id` — match on account ID (prefixed `biz_`); `property` — match on a named user property (requires `field`).", "enum": [ "user_id", "account_id", "property" ], "example": "user_id", "type": "string" }, "value": { "description": "Value or list of values to match against. Pass an array for `any`/`none`, a scalar for the others." } }, "required": [ "type", "operator", "value" ], "type": "object" }, "type": "array" }, "type": { "description": "`include` — users matching this rule qualify; `exclude` — users matching this rule are always excluded, overriding any include rule. Defaults to `include`.", "enum": [ "include", "exclude" ], "example": "include", "type": "string" } }, "required": [ "conditions" ], "type": "object" }, "type": "array" }, "variants": { "description": "Treatment arms to create. Users outside every arm form the implicit `control` group. Required unless `feature_flag_only` is `true`.", "items": { "properties": { "name": { "description": "Treatment identifier. `control` is reserved for the implicit remainder.", "example": "treatment", "type": "string" }, "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "nullable": true }, "weight": { "description": "Percentage of all subjects assigned to this treatment. The remainder is control.", "example": 50, "type": "integer" } }, "required": [ "name", "weight" ], "type": "object" }, "type": "array" } }, "required": [ "flag_key", "account_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } }, "description": "experiment created" }, "409": { "$ref": "#/components/responses/Conflict", "description": "experiment key already exists" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create Experiment", "tags": [ "Experiments" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/experiments/exposures": { "get": { "description": "Evaluates experiments and feature flags for a subject and records an exposure. Pass `flag_key` to evaluate one flag, or omit it to evaluate every active flag in the account and related resource scope. Requires no authentication; when a credential resolves, its authentication method, API key ID, and signed-in user ID are recorded on the exposure event.\n", "operationId": "evaluateExperimentExposures", "parameters": [ { "description": "Bucketing subject: the user, account, or anonymous ID the experiment's `bucket_by` assigns on. Only the identity matching `bucket_by` is used; when it is missing, evaluating a single flag fails and a batch omits that experiment. Subjects outside every treatment range receive `control`. `subject[account_id]` also enables account-level targeting rules. Experiment ownership comes from the top-level `account_id`.", "explode": true, "in": "query", "name": "subject", "required": false, "schema": { "properties": { "account_id": { "type": "string" }, "anonymous_id": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "style": "deepObject" }, { "description": "Restricts batch evaluation to this related resource; omitted batches contain only unbound experiments.", "explode": true, "in": "query", "name": "related_resource", "required": false, "schema": { "$ref": "#/components/schemas/ExperimentResourceReference" }, "style": "deepObject" }, { "description": "Flag or experiment to evaluate — the flag_key handle or the `expt_` id. Omit to return all flags the caller qualifies for.", "in": "query", "name": "flag_key", "required": false, "schema": { "type": "string" } }, { "description": "Owning account ID. Required when evaluating by flag_key or in a batch; optional for an expt_ ID.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object" } } }, "description": "JSON-encoded scalar values that property targeting conditions match against. Numeric and boolean strings are coerced. Nested query keys such as properties[variant]=pro remain accepted for existing callers.", "in": "query", "name": "properties", "required": false }, { "description": "Set `false` to read an assignment without recording an exposure, such as when a client caches assignments up front and records the exposure when the arm is rendered. Omitted records the exposure.", "in": "query", "name": "log_exposure", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ExperimentExposure" }, { "$ref": "#/components/schemas/ExperimentExposureBatch" } ] } } }, "description": "single flag evaluated" } }, "security": [ { "bearerAuth": [] }, {} ], "summary": "Evaluate Experiments", "tags": [ "Experiments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/experiments/{id}": { "get": { "description": "Retrieves an experiment or feature flag by its `expt_` ID or `flag_key` handle. Requires `experiment:read` on the owning account.", "operationId": "getExperiment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } }, "description": "experiment found" }, "404": { "$ref": "#/components/responses/NotFound", "description": "experiment not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve Experiment", "tags": [ "Experiments" ] }, "parameters": [ { "description": "Owning account ID. Required when id is a flag key; optional for an expt_ ID.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The experiment identifier — the `expt_` id or the flag_key handle.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates the targeting rules, treatment allocation, or hypothesis of an existing experiment or feature flag. To change its lifecycle, use the `activate`, `pause`, and `end` endpoints instead. Requires `experiment:manage` on the owning account.", "operationId": "updateExperiment", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "control": { "properties": { "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "nullable": true } }, "type": "object" }, "hypothesis": { "description": "Omit to leave unchanged. Send an empty string to clear it. Not accepted on feature flags. When setting it, structure it as \"If we [change] for [cohort], then [measurable behavior] will [increase/decrease], resulting in [business outcome], because [evidence]. Created by [name].\" same as on create.", "example": "If we send a blueprint nudge email 30 minutes after business creation, then GTV within 10 hours will increase among newly created businesses, resulting in more new business operators generating GTV within 10 hours, because operators currently land on an empty dashboard with no concrete next step. Created by Jane Doe.", "nullable": true, "type": "string" }, "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "description": "Resource owned by the account that this experiment is bound to, such as an app or product. `null` when unbound. Fixed once the experiment first activates.", "nullable": true }, "targeting_rules": { "description": "Replace the targeting rules with this set. Omit to leave unchanged.", "items": { "properties": { "conditions": { "description": "Conditions within this rule. Must be non-empty. All conditions must be satisfied for the rule to match (AND logic). Rules are OR-ed together.", "items": { "properties": { "field": { "description": "Property name to read from the user context. Required when `type` is `property`.", "nullable": true, "type": "string" }, "operator": { "description": "Comparison to apply: `any`/`none` — inclusion/exclusion list; `eq`/`neq` — equality; `gt`/`gte`/`lt`/`lte` — numeric range.", "enum": [ "any", "none", "eq", "neq", "gt", "gte", "lt", "lte" ], "example": "any", "type": "string" }, "type": { "description": "`user_id` — match on subject user ID; `account_id` — match on account ID (prefixed `biz_`); `property` — match on a named user property (requires `field`).", "enum": [ "user_id", "account_id", "property" ], "example": "user_id", "type": "string" }, "value": { "description": "Value or list of values to match against. Pass an array for `any`/`none`, a scalar for the others." } }, "required": [ "type", "operator", "value" ], "type": "object" }, "type": "array" }, "type": { "description": "`include` — users matching this rule qualify; `exclude` — users matching this rule are always excluded, overriding any include rule. Defaults to `include`.", "enum": [ "include", "exclude" ], "example": "include", "type": "string" } }, "required": [ "conditions" ], "type": "object" }, "type": "array" }, "variants": { "description": "Grow treatment allocation. Pass every existing treatment with an equal-or-higher weight; append new names to add arms. Weights never decrease and arms are never removed. Omit to leave unchanged.", "items": { "properties": { "name": { "description": "Treatment name. Pass every existing treatment (weights equal or higher); append new names to add arms. `control` is reserved.", "example": "treatment", "type": "string" }, "related_resource": { "$ref": "#/components/schemas/ExperimentResourceReference", "nullable": true }, "weight": { "description": "Percentage assigned to treatment; allocation may only grow.", "example": 80, "type": "integer" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } }, "description": "metrics added" }, "404": { "$ref": "#/components/responses/NotFound", "description": "experiment not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update Experiment", "tags": [ "Experiments" ] }, "x-whop-surface": "native" }, "/experiments/{id}/activate": { "parameters": [ { "description": "Owning account ID. Required when id is a flag key; optional for an expt_ ID.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The experiment identifier — the `expt_` id or the flag_key handle.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Starts (or resumes) an experiment or feature flag so evaluation begins serving it. Activating a draft stamps `started_at`; resuming a paused experiment keeps the original start. Only drafts and paused experiments can be activated. Requires `experiment:manage` on the owning account.", "operationId": "activateExperiment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "duration_days": { "description": "Reporting window length in days. Omit to use the default. This does not automatically end the experiment.", "example": 30, "nullable": true, "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } }, "description": "experiment activated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "transition not allowed" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Activate Experiment", "tags": [ "Experiments" ] }, "x-whop-surface": "native" }, "/experiments/{id}/end": { "parameters": [ { "description": "Owning account ID. Required when id is a flag key; optional for an expt_ ID.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The experiment identifier — the `expt_` id or the flag_key handle.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Concludes the experiment and records required `findings`. Pass `winning_arm` to serve the winning treatment to everyone; omit it when control won. Ended experiments cannot restart, but may be ended again to correct the winner. Requires `experiment:manage` on the owning account.", "operationId": "endExperiment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "findings": { "description": "What you learned and why you chose this outcome. Required.", "example": "Treatment lifted signups 12%, shipping it to everyone.", "type": "string" }, "winning_arm": { "description": "The treatment that won. Setting it rolls that arm out: every later evaluation returns it to every caller, ignoring targeting and allocation, and exposures stop being recorded. Omit it when control won — an ended experiment with no winning arm evaluates to `control` for everyone, so ending again without one also reverts a rollout recorded by mistake. Not accepted on feature flags, which evaluate to disabled once ended.", "example": "treatment", "nullable": true, "type": "string" } }, "required": [ "findings" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } }, "description": "experiment ended" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "winning_arm is not a treatment of this experiment" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "End Experiment", "tags": [ "Experiments" ] }, "x-whop-surface": "native" }, "/experiments/{id}/pause": { "parameters": [ { "description": "Owning account ID. Required when id is a flag key; optional for an expt_ ID.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The experiment identifier — the `expt_` id or the flag_key handle.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses an active experiment or feature flag: evaluation stops serving it and exposures stop flowing. Assignments are keyed on stable identity, so users return to their original arm when the experiment resumes. Requires `experiment:manage` on the owning account.", "operationId": "pauseExperiment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } }, "description": "experiment paused" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Pause Experiment", "tags": [ "Experiments" ] }, "x-whop-surface": "native" }, "/exports": { "get": { "description": "Lists the exports requested for an account, newest first. Only exports of resources the credential is allowed to export are returned.", "operationId": "listExports", "parameters": [ { "description": "The account to list exports for, prefixed `biz_`. Defaults to the credential's account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return exports of this resource.", "in": "query", "name": "resource", "required": false, "schema": { "enum": [ "ad_campaigns", "ad_groups", "ads", "apps", "audiences", "bounties", "bounty_submissions", "card_transactions", "checkout_configurations", "disputes", "events", "external_accounts", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "receipt_invoices", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "invoices", "cancelation_reasons", "child_companies", "ledger_lines", "withdrawal_lines" ], "type": "string" } }, { "description": "Only return exports in this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "processing", "completed", "failed", "expired" ], "type": "string" } }, { "description": "Only return exports created at or after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only return exports created at or before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Export" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "exports listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unknown status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "holds no export scope on the account" } }, "security": [ { "bearerAuth": [ "access_pass:basic:read" ] }, { "bearerAuth": [ "ad_campaign:basic:read" ] }, { "bearerAuth": [ "audience:basic:read" ] }, { "bearerAuth": [ "bounty:basic:read" ] }, { "bearerAuth": [ "checkout_configuration:basic:read" ] }, { "bearerAuth": [ "child_company:basic:export" ] }, { "bearerAuth": [ "company:authorized_user:read" ] }, { "bearerAuth": [ "company:balance:export" ] }, { "bearerAuth": [ "company:balance:read", "company:balance:export", "member:email:read" ] }, { "bearerAuth": [ "company:balance:read", "company:balance:export", "member:email:read", "payout:account:read" ] }, { "bearerAuth": [ "company:basic:read", "member:basic:read", "member:journey:read" ] }, { "bearerAuth": [ "developer:basic:read" ] }, { "bearerAuth": [ "developer:manage_webhook" ] }, { "bearerAuth": [ "invoice:basic:export" ] }, { "bearerAuth": [ "lead:basic:export" ] }, { "bearerAuth": [ "member:basic:export" ] }, { "bearerAuth": [ "payment:basic:export" ] }, { "bearerAuth": [ "payment:basic:read", "payment:basic:export" ] }, { "bearerAuth": [ "payment:dispute:read" ] }, { "bearerAuth": [ "payment:resolution_center_case:export" ] }, { "bearerAuth": [ "payment:resolution_center_case:read" ] }, { "bearerAuth": [ "payout:account:read" ] }, { "bearerAuth": [ "payout:destination:read" ] }, { "bearerAuth": [ "payout:transfer:read" ] }, { "bearerAuth": [ "payout:withdrawal:read" ] }, { "bearerAuth": [ "plan:basic:read" ] }, { "bearerAuth": [ "plan:waitlist:export" ] }, { "bearerAuth": [ "promo_code:basic:export" ] }, { "bearerAuth": [ "shipment:basic:read" ] }, { "bearerAuth": [ "social_account:read" ] }, { "bearerAuth": [ "tracking_link:basic:export" ] } ], "summary": "List Exports", "tags": [ "Exports" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts an asynchronous export of a resource for an account. Returns the export in `pending`; poll `GET /exports/:id` until `download_url` is set.", "operationId": "createExport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to export from, prefixed `biz_`. Defaults to the credential's account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "columns": { "description": "Column keys to include. Empty means all columns for the resource.", "items": { "example": "member_user_name", "type": "string" }, "type": "array" }, "filters": { "description": "Resource-specific filters. For native REST resources (`payouts`, `transfers`, `products`) these are the resource's own list query params; for dashboard tables they mirror the dashboard table filters.", "example": { "include_resource": false, "posted_after": "2026-01-01T12:00:00.000Z", "posted_before": "2026-01-01T12:00:00.000Z" }, "type": "object" }, "resource": { "description": "The resource to export, e.g. `payouts`, `receipts`, or `members`.", "enum": [ "ad_campaigns", "ad_groups", "ads", "apps", "audiences", "bounties", "bounty_submissions", "card_transactions", "checkout_configurations", "disputes", "events", "external_accounts", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "receipt_invoices", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "invoices", "cancelation_reasons", "child_companies" ], "example": "financial-activity", "type": "string" }, "timezone": { "description": "IANA timezone for date columns, e.g. `America/New_York`. Defaults to `UTC`.", "example": "America/Chicago", "type": "string" } }, "required": [ "resource" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } }, "description": "export created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "resource is not creatable over REST" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "not authorized for the scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "access_pass:basic:read" ] }, { "bearerAuth": [ "ad_campaign:basic:read" ] }, { "bearerAuth": [ "audience:basic:read" ] }, { "bearerAuth": [ "bounty:basic:read" ] }, { "bearerAuth": [ "checkout_configuration:basic:read" ] }, { "bearerAuth": [ "child_company:basic:export" ] }, { "bearerAuth": [ "company:authorized_user:read" ] }, { "bearerAuth": [ "company:balance:read", "company:balance:export", "member:email:read" ] }, { "bearerAuth": [ "company:balance:read", "company:balance:export", "member:email:read", "payout:account:read" ] }, { "bearerAuth": [ "company:basic:read", "member:basic:read", "member:journey:read" ] }, { "bearerAuth": [ "developer:basic:read" ] }, { "bearerAuth": [ "developer:manage_webhook" ] }, { "bearerAuth": [ "invoice:basic:export" ] }, { "bearerAuth": [ "lead:basic:export" ] }, { "bearerAuth": [ "member:basic:export" ] }, { "bearerAuth": [ "payment:basic:export" ] }, { "bearerAuth": [ "payment:basic:read", "payment:basic:export" ] }, { "bearerAuth": [ "payment:dispute:read" ] }, { "bearerAuth": [ "payment:resolution_center_case:export" ] }, { "bearerAuth": [ "payment:resolution_center_case:read" ] }, { "bearerAuth": [ "payout:account:read" ] }, { "bearerAuth": [ "payout:destination:read" ] }, { "bearerAuth": [ "payout:transfer:read" ] }, { "bearerAuth": [ "payout:withdrawal:read" ] }, { "bearerAuth": [ "plan:basic:read" ] }, { "bearerAuth": [ "plan:waitlist:export" ] }, { "bearerAuth": [ "promo_code:basic:export" ] }, { "bearerAuth": [ "shipment:basic:read" ] }, { "bearerAuth": [ "social_account:read" ] }, { "bearerAuth": [ "tracking_link:basic:export" ] } ], "summary": "Create Export", "tags": [ "Exports" ] }, "x-whop-surface": "native" }, "/exports/{id}": { "get": { "description": "Fetches an export's status and, once complete, its download link.", "operationId": "retrieveExport", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } }, "description": "export found" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "not authorized for the scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "export not found" } }, "security": [ { "bearerAuth": [ "access_pass:basic:read" ] }, { "bearerAuth": [ "ad_campaign:basic:read" ] }, { "bearerAuth": [ "audience:basic:read" ] }, { "bearerAuth": [ "bounty:basic:read" ] }, { "bearerAuth": [ "checkout_configuration:basic:read" ] }, { "bearerAuth": [ "child_company:basic:export" ] }, { "bearerAuth": [ "company:authorized_user:read" ] }, { "bearerAuth": [ "company:balance:export" ] }, { "bearerAuth": [ "company:balance:read", "company:balance:export", "member:email:read" ] }, { "bearerAuth": [ "company:balance:read", "company:balance:export", "member:email:read", "payout:account:read" ] }, { "bearerAuth": [ "company:basic:read", "member:basic:read", "member:journey:read" ] }, { "bearerAuth": [ "developer:basic:read" ] }, { "bearerAuth": [ "developer:manage_webhook" ] }, { "bearerAuth": [ "invoice:basic:export" ] }, { "bearerAuth": [ "lead:basic:export" ] }, { "bearerAuth": [ "member:basic:export" ] }, { "bearerAuth": [ "payment:basic:export" ] }, { "bearerAuth": [ "payment:basic:read", "payment:basic:export" ] }, { "bearerAuth": [ "payment:dispute:read" ] }, { "bearerAuth": [ "payment:resolution_center_case:export" ] }, { "bearerAuth": [ "payment:resolution_center_case:read" ] }, { "bearerAuth": [ "payout:account:read" ] }, { "bearerAuth": [ "payout:destination:read" ] }, { "bearerAuth": [ "payout:transfer:read" ] }, { "bearerAuth": [ "payout:withdrawal:read" ] }, { "bearerAuth": [ "plan:basic:read" ] }, { "bearerAuth": [ "plan:waitlist:export" ] }, { "bearerAuth": [ "promo_code:basic:export" ] }, { "bearerAuth": [ "shipment:basic:read" ] }, { "bearerAuth": [ "social_account:read" ] }, { "bearerAuth": [ "tracking_link:basic:export" ] } ], "summary": "Retrieve Export", "tags": [ "Exports" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The export ID, prefixed `exprt_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/external_accounts": { "get": { "description": "Lists the external accounts linked to an account or user.", "operationId": "listExternalAccounts", "parameters": [ { "description": "The Account that the external accounts are connected to. Provide either this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The User that the external accounts are connected to. Provide either this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return external accounts for the platform that is specified.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram", "linkedin", "snapchat", "klaviyo" ], "type": "string" } }, { "description": "Only return external accounts linked with this trust level, such as `oauth` for accounts connected through OAuth.", "in": "query", "name": "trust_level", "required": false, "schema": { "enum": [ "oauth", "api_key", "verified", "authorized", "claimed", "scraped" ], "type": "string" } }, { "description": "Only return external accounts that are verified on the platform.", "in": "query", "name": "verified", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return external accounts that have these scopes.", "in": "query", "name": "scopes", "required": false, "schema": { "items": { "enum": [ "advertise" ], "type": "string" }, "type": "array" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort external accounts by.", "in": "query", "name": "order", "required": false, "schema": { "default": "display_order", "enum": [ "display_order", "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "asc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalAccount" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "filtered to accounts holding the requested scope" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither account_id nor user_id resolvable" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List External Accounts", "tags": [ "External Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates or returns a Whop-managed Facebook page or TikTok account for an account, or connects the account's existing Klaviyo account with a private API key.", "operationId": "createExternalAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) to create the external account for. An account-scoped API key may omit this to default to its own account. Account API keys cannot update their own account's branding through Update Account; use a user-authenticated path.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "api_key": { "description": "A private API key for the account on the platform. Required for `klaviyo`, which needs read access to Accounts; not accepted for other platforms. Whop checks the key with the platform before connecting and never returns it.", "type": "string" }, "platform": { "description": "The platform to create the external account on. `facebook` requires the account's `banner_image`, `logo`, and `description`, and `tiktok` requires its `logo`; configure them with [Update Account](/api-reference/beta/accounts/update-account). The account is returned before the platform has created it — its `id` is usable right away, and the rest of the profile fills in once provisioning finishes. `klaviyo` connects the account's existing Klaviyo account with the `api_key` you pass.", "enum": [ "facebook", "tiktok", "klaviyo" ], "example": "facebook", "type": "string" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccount" } } }, "description": "external account created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the account is missing the banner_image, logo, or description a Facebook page requires" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "social_account:create" ] } ], "summary": "Create an External Account", "tags": [ "External Accounts" ] }, "x-whop-surface": "native" }, "/external_accounts/connect": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts an OAuth connection flow and returns an `authorize_url` to send the user to, where they connect an external account. Personal profile connections must be completed in a browser signed in as the Whop user who started the flow.", "operationId": "connectExternalAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) to connect the external account for. An account-scoped API key may omit this to default to its own account. Omit for user profile connections.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "platform": { "description": "The platform to connect the external account on. Use `meta_business` to connect Meta Business assets, which is how Facebook Pages and Instagram accounts are connected — there is no separate `instagram` value. Use `tiktok` for TikTok accounts, `snapchat` for Snapchat Public Profiles, `linkedin` to connect the authenticated user’s LinkedIn profile, `youtube` to connect their YouTube channel, or `x` to connect their X profile.", "enum": [ "meta_business", "tiktok", "linkedin", "youtube", "x", "snapchat" ], "example": "meta_business", "type": "string" }, "redirect_url": { "description": "Where to send the user once they finish connecting their accounts. Must be an `https` URL on whop.com; any other host is rejected. On success, the user is redirected with an `external_account_connected` query param naming the platform; if the connection fails, with an `external_account_error` query param instead. The same values also arrive as `social_account_connected` / `social_account_error`.", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/ads/settings", "type": "string" }, "scopes": { "description": "The connection purpose. For `meta_business` and `snapchat`, `advertise` is required and connects company advertising assets. For `linkedin`, `youtube`, and `x`, omit scopes to connect the authenticated user’s profile; advertising is not supported. For `tiktok`, omit scopes to connect the authenticated user’s profile, or pass `advertise` to connect company advertising assets. Profile connections still request the platform permissions needed to read the profile.", "items": { "enum": [ "advertise" ], "example": "advertise", "type": "string" }, "type": "array" } }, "required": [ "redirect_url", "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "authorize_url": { "description": "The OAuth authorization URL to redirect the user to.", "example": "https://www.facebook.com/v25.0/dialog/oauth", "type": "string" } }, "required": [ "authorize_url" ], "type": "object" } } }, "description": "authorize url returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unsupported platform" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "social_account:create" ] } ], "summary": "Connect an External Account", "tags": [ "External Accounts" ] }, "x-whop-surface": "native" }, "/external_accounts/{external_account_id}/partners": { "get": { "description": "Lists the creators an Instagram account runs partnership ads with, and where each creator's permission stands.", "operationId": "listExternalAccountPartners", "parameters": [ { "description": "The Account (biz_ identifier) that advertises as the Instagram account. An account-scoped API key may omit this to default to its own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "partners": { "value": { "data": [ { "error": null, "external_id": null, "id": "sacc_xxxxxxxxxxxxxx", "name": "Luvera", "parent_external_account": null, "partnership_status": "pending", "platform": "instagram", "profile_picture_url": "https://img.whop.com/sacc_xxxxxxxxxxxxxx.png", "scopes": [ "partner" ], "url": "https://instagram.com/luverahealth", "username": "luverahealth", "verified": false } ], "page_info": { "end_cursor": null, "has_next_page": false, "has_previous_page": false, "start_cursor": null } } } }, "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalAccount" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "partners listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "caller can't read the account's external accounts" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the account doesn't advertise as the Instagram account" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List External Account Partners", "tags": [ "External Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The Instagram account (a sacc_ identifier) the partners run partnership ads with.", "in": "path", "name": "external_account_id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Invites an Instagram creator to run partnership ads with an Instagram account. The creator approves the invitation in the Instagram app, and `partnership_status` stays `pending` until they do; [refresh](/api-reference/beta/external-accounts/refresh) the partner to pick up their answer.", "operationId": "addExternalAccountPartner", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) that advertises as the Instagram account. An account-scoped API key may omit this to default to its own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "username": { "description": "The creator's Instagram username, with or without the leading `@`. The creator needs a professional (Business or Creator) Instagram account.", "example": "@luverahealth", "type": "string" } }, "required": [ "username" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "partner": { "value": { "error": null, "external_id": null, "id": "sacc_xxxxxxxxxxxxxx", "name": "Luvera", "parent_external_account": null, "partnership_status": "pending", "platform": "instagram", "profile_picture_url": "https://img.whop.com/sacc_xxxxxxxxxxxxxx.png", "scopes": [ "partner" ], "url": "https://instagram.com/luverahealth", "username": "luverahealth", "verified": false } } }, "schema": { "$ref": "#/components/schemas/ExternalAccount" } } }, "description": "creator invited" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the creator has no professional Instagram account" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "caller lacks permission to add external accounts" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the account doesn't advertise as the Instagram account" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests", "description": "the Instagram account has sent too many invitations" } }, "security": [ { "bearerAuth": [ "social_account:create" ] } ], "summary": "Add Partner", "tags": [ "External Accounts" ] }, "x-whop-surface": "native" }, "/external_accounts/{external_account_id}/partners/{id}": { "delete": { "description": "Revokes a creator's permission to run partnership ads with an Instagram account. Every account that advertises as the Instagram account loses the partner, since the permission belongs to the Instagram account.", "operationId": "removeExternalAccountPartner", "parameters": [ { "description": "The Account (biz_ identifier) that advertises as the Instagram account. An account-scoped API key may omit this to default to its own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the removed partner's external account.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "partner removed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "caller lacks permission to delete external accounts" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the creator isn't a partner of the Instagram account" } }, "security": [ { "bearerAuth": [ "social_account:delete" ] } ], "summary": "Remove Partner", "tags": [ "External Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The Instagram account (a sacc_ identifier) the partner runs partnership ads with.", "in": "path", "name": "external_account_id", "required": true, "schema": { "type": "string" } }, { "description": "The partner creator's external account (a sacc_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/external_accounts/{id}": { "delete": { "description": "Disconnects an external account from an account or user without deleting the underlying platform account.", "operationId": "deleteExternalAccount", "parameters": [ { "description": "The Account that the external account is connected to. Provide either this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The User that the external account is connected to. Provide either this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the disconnected external account.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "user external account disconnected" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id and user_id both provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "caller lacks delete permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "link already disconnected" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the external account is the parent of others that are still connected" } }, "security": [ { "bearerAuth": [ "social_account:delete" ] } ], "summary": "Delete an External Account", "tags": [ "External Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the external account to disconnect.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/external_accounts/{id}/lead_forms": { "get": { "description": "Lists the active lead (instant) forms that already exist on a connected Facebook page, so an ad can reuse one as its `lead_gen_form_id` instead of authoring a new form. Every active form comes back in a single response — the list is not paginated.", "operationId": "listExternalAccountLeadForms", "parameters": [ { "description": "The Account (a biz_ identifier) the external account is connected to.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalAccountLeadForm" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "lead forms listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "account_id is missing" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "external account is not linked to the account" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List External Account Lead Forms", "tags": [ "External Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The external account (a sacc_ identifier) whose lead forms to list.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/external_accounts/{id}/posts": { "get": { "description": "Lists the existing posts of a connected Facebook page, Instagram account, or TikTok account.", "operationId": "listExternalAccountPosts", "parameters": [ { "description": "The Account (a biz_ identifier) the external account is connected to.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Return only the single post with this platform id, instead of the full list.", "in": "query", "name": "post_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExternalAccountPost" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "MTI=", "nullable": true, "type": "string" }, "has_next_page": { "example": true, "type": "boolean" } }, "required": [ "has_next_page", "end_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "single post returned when post_id is given" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the requested post is unavailable on the platform" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "external account is not linked to the account" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List External Account Posts", "tags": [ "External Accounts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The external account (a sacc_ identifier) whose posts to list.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/external_accounts/{id}/refresh": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The external account (a sacc_ identifier) to refresh.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Refreshes the state of an external account. Use it to clear an `error` that has been resolved.", "operationId": "refreshExternalAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) the external account is connected to. An account-scoped API key may omit this to default to its own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccount" } } }, "description": "refresh started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the external account's platform can't be refreshed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "caller lacks the advertising permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the external account isn't connected to the account for advertising" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the external account is still being set up" }, "429": { "$ref": "#/components/responses/TooManyRequests", "description": "the external account was refreshed less than a minute ago" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Refresh", "tags": [ "External Accounts" ] }, "x-whop-surface": "native" }, "/fee_markups": { "get": { "description": "Lists the fee markups configured for an account. For a platform account, returns the platform's default markups.\n\nRequired permissions:\n - `company:update_child_fees`", "operationId": "listFeeMarkup", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": true, "schema": { "description": "The unique identifier of the company to list fee markups for. Pass a platform account identifier to retrieve platform default markups.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for FeeMarkup.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/FeeMarkupListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:update_child_fees" ] } ], "summary": "List fee markups", "tags": [ "Fee markups" ], "x-group-title": "Identity" }, "post": { "description": "Creates or updates an account's markup for one fee type. If the account already has a markup for that `fee_type`, it is updated with the new values.\n\nRequired permissions:\n - `company:update_child_fees`", "operationId": "createFeeMarkup", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateFeeMarkup", "properties": { "account_id": { "description": "The unique identifier of the company to create or update the fee markup for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "fee_type": { "$ref": "#/components/schemas/FeeMarkupTypes", "description": "The type of fee this markup applies to, such as processing or platform fees." }, "fixed_fee_usd": { "description": "The fixed fee amount in USD to charge per transaction. Must be between 0 and 50.", "example": 6.9, "type": [ "number", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value metadata to attach to this fee markup.", "type": [ "object", "null" ] }, "notes": { "description": "Internal notes about this fee markup for record-keeping purposes.", "type": [ "string", "null" ] }, "percentage_fee": { "description": "The percentage fee to charge per transaction. Must be between 0 and 25.", "example": 6.9, "type": [ "number", "null" ] } }, "required": [ "account_id", "fee_type" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeMarkup" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:update_child_fees" ] } ], "summary": "Create fee markup", "tags": [ "Fee markups" ], "x-group-title": "Identity" } }, "/fee_markups/{id}": { "delete": { "description": "Deletes a fee markup, removing the custom fee override so the account reverts to its parent account's default fees.\n\nRequired permissions:\n - `company:update_child_fees`", "operationId": "deleteFeeMarkup", "parameters": [ { "description": "The unique identifier of the fee markup to delete.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:update_child_fees" ] } ], "summary": "Delete fee markup", "tags": [ "Fee markups" ], "x-group-title": "Identity" } }, "/feedback_submissions": { "post": { "description": "Submits an issue or an unanswered question to Whop for review, recorded under the authenticated user, account, or app. Returns a receipt once the submission is accepted; processing is asynchronous and no reply is sent.", "operationId": "createFeedbackSubmission", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account_id": { "description": "The ID of the account the feedback is about (biz_...), if any. Recorded as context only; it does not require or grant access to that account.", "maxLength": 255, "pattern": "^biz_[A-Za-z0-9]+$", "type": "string" }, "content": { "description": "The problem or question in plain text, with enough context to act on. Leave out credentials, personal data, and payment details.", "example": "The docs omit the required permission", "maxLength": 20000, "minLength": 1, "type": "string" }, "source": { "description": "What kind of submission this is. Use api_report_feedback for an issue or api_ask_question for an unanswered question. The other values are reserved for Whop's own clients: the hosted MCP server, the Whop CLI, and Whop AI chat.", "enum": [ "mcp_report_feedback", "mcp_ask_question", "cli_report_feedback", "cli_ask_question", "ai_chat_report_feedback", "ai_chat_ask_question", "api_report_feedback", "api_ask_question" ], "example": "api_report_feedback", "type": "string" } }, "required": [ "source", "content" ], "type": "object" } } } }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "created_at": { "description": "When the submission was accepted, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "description": "The ID of the feedback submission receipt (fbk_...).", "example": "fbk_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "created_at" ], "type": "object" } } }, "description": "accepted" }, "400": { "description": "invalid feedback" }, "401": { "description": "authentication required" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Submit Feedback", "tags": [ "Feedback" ] }, "x-whop-surface": "native" }, "/files": { "get": { "description": "Returns the files with the given IDs, newest first — fetch a batch in one request instead of retrieving each file individually. Only files you created are returned; IDs that do not exist, or that another credential created, are omitted. For a batch larger than one page, follow `page_info` with the same `file_ids` to walk the rest.", "operationId": "listFiles", "parameters": [ { "description": "The files to return, each prefixed `file_`. Repeat the parameter to pass several, up to 250 per request. Batches of up to 100 answer in one page by default; larger batches page at up to 100 per response.", "explode": true, "in": "query", "name": "file_ids", "required": true, "schema": { "items": { "example": "file_xxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/File" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": true, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "files listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Files", "tags": [ "Files" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a file and returns a presigned destination to upload its bytes to. PUT the bytes to `upload_url` (single-part), or to each of `multipart_upload_urls` and then call Complete File Multipart Upload. Once the bytes land the file becomes `ready`, and its ID can be attached wherever a file is accepted — account legal documents, dispute evidence documents. For a step-by-step walkthrough of single-part and multipart uploads, see the [direct file uploads guide](/developer/guides/direct-file-uploads).", "operationId": "createFile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "byte_size": { "description": "The file's size in bytes. Required when `multipart` is `true`. Multipart uploads support at most 10,000 parts of 5MB each (about 50 GB).", "example": 15728640, "type": "integer" }, "filename": { "description": "The name of the file including its extension, e.g. `terms.pdf`.", "example": "terms.pdf", "type": "string" }, "multipart": { "description": "Upload the file in 5MB parts. Required for files larger than 5GB; useful above ~100MB. The file must be larger than 5MB.", "example": true, "type": "boolean" }, "visibility": { "description": "`public` files are served via an unsigned CDN URL — use for assets anyone may see. `private` files are served via a signed, expiring URL — use for sensitive documents. Defaults to `private`.", "enum": [ "public", "private" ], "example": "public", "type": "string" } }, "required": [ "filename" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "file created with a single-part upload destination" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "bad request" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create File", "tags": [ "Files" ] }, "x-whop-surface": "native" }, "/files/{id}": { "get": { "description": "Retrieves a file you uploaded — poll it after uploading the bytes to see `upload_status` become `ready`. Only the creator can retrieve a file this way; a file attached to another resource is read through that resource.", "operationId": "retrieveFile", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "file retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve File", "tags": [ "Files" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the file, prefixed `file_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/files/{id}/complete": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the file, prefixed `file_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Assembles the parts of a multipart upload after every part has been PUT to its presigned URL. Pass the `multipart_upload_id` from Create File and each part's `ETag` response header. For a step-by-step walkthrough of multipart uploads, see the [direct file uploads guide](/developer/guides/direct-file-uploads).", "operationId": "completeFile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "multipart_parts": { "description": "Every uploaded part, in order.", "items": { "properties": { "etag": { "description": "The `ETag` response header from the part's upload.", "example": "etag-1", "type": "string" }, "part_number": { "description": "The 1-based index of the part.", "example": 1, "type": "integer" } }, "required": [ "part_number", "etag" ], "type": "object" }, "type": "array" }, "multipart_upload_id": { "description": "The ID of the multipart upload, returned by Create File.", "example": "upload-id", "type": "string" } }, "required": [ "multipart_upload_id", "multipart_parts" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "description": "multipart upload completed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "bad request" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Complete File Multipart Upload", "tags": [ "Files" ] }, "x-whop-surface": "native" }, "/financial_activity": { "get": { "description": "Returns an account's or user's activity feed: every movement of money in or out.", "operationId": "listFinancialActivity", "parameters": [ { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "When true, aggregates the authenticated user's personal ledger with the businesses they own (owner role with balance read) into one feed. Requires user_id to be the authenticated user; cannot be combined with account_id or the settlement-date filters. Each returned row includes the owning `account`.", "in": "query", "name": "include_owned_accounts", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to include the `resource` field in the response or not. Consider passing `false` if you need a fast response without as many rich details.", "in": "query", "name": "include_resource", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Optional ledger line categories to include. Some categories (for example `onchain_deposit`, which covers inbound crypto deposits such as MoonPay onramps) are only returned when explicitly requested here.", "explode": true, "in": "query", "name": "line_types", "required": false, "schema": { "items": { "enum": [ "account_settlement", "ad_affiliate_payout_received", "ad_budget_release", "ad_campaign_budget", "ad_publisher_payout", "ad_publisher_payout_received", "ad_spend_charge", "affiliate_fee", "airdrop", "airdrop_link_created", "airdrop_link_redeemed", "airdrop_link_returned", "airdrop_reversal", "application_fee", "application_fee_payout", "balance_reservation", "balance_reservation_reversal", "bank_transfer", "billing_percentage_fee", "buyer_fee", "card_interchange", "card_load_deposit", "card_load_transfer", "card_spend_authorization", "card_spend_authorization_void", "card_spend_refund", "card_unload_deposit", "card_unload_transfer", "cashback", "cashback_funding", "company_referral", "connected_account_negative_balance", "cross_border_percentage_fee", "currency_conversion_incoming", "currency_conversion_outgoing", "dispute_alert_fee", "dispute_hold_adjustment", "dispute_representment_fee", "economic_intelligence_percentage_fee", "external_card_load_deposit", "fees", "fraud_prevention_fee", "fx_percentage_fee", "high_risk_merchant_fee", "installment_default", "internal_balance_transfer_incoming", "internal_balance_transfer_outgoing", "internal_withdrawal", "internal_withdrawal_complete", "internal_withdrawal_fee", "internal_withdrawal_fee_reversal", "internal_withdrawal_in_transit", "internal_withdrawal_in_transit_reversal", "internal_withdrawal_markup_fee", "internal_withdrawal_markup_fee_payout", "internal_withdrawal_markup_fee_payout_reversal", "internal_withdrawal_markup_fee_reversal", "internal_withdrawal_reversal", "legacy_crypto_payment", "legacy_payment", "legacy_payment_refund", "license_sale", "license_sale_commission", "license_sale_revenue", "marketplace_affiliate_fee", "misc_purchase", "misc_refund", "misc_reversal", "onboarding_reward", "onchain_deposit", "onchain_internal_transfer_incoming", "onchain_internal_transfer_outgoing", "onchain_platform_transfer_incoming", "onchain_platform_transfer_outgoing", "onchain_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "orchestration_percentage_fee", "partner_grant_reward", "passthrough_gmv", "payment_dispute", "payment_dispute_adjustment", "payment_dispute_fee", "payment_dispute_reversal", "payment_gross", "payment_gross_reversal", "payment_processing_fixed_fee", "payment_processing_percentage_fee", "payment_referral", "payment_referral_refund", "payment_referral_reversal", "payment_refund", "payment_refund_reversal", "payment_return_fee", "payment_revshare", "payment_revshare_payout", "payment_revshare_refund", "payment_revshare_reversal", "payout_fee", "platform_affiliate_payment", "platform_affiliate_payment_reversal", "platform_balance_payment", "platform_balance_payment_refund", "platform_balance_transfer_fee", "platform_balance_transfer_incoming", "platform_balance_transfer_outgoing", "platform_covered_dispute", "platform_credits_granted", "platform_credits_payment", "platform_credits_payment_refund", "platform_earning", "platform_markup_fee", "platform_markup_fee_payout", "promo_reversal", "referral_bonus", "resolution_center_refund", "revshare_percentage_fee", "sales_tax_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "software_rental_revshare", "software_rental_transaction", "stripe_domestic_processing_fee", "stripe_international_processing_fee", "swap_fee", "three_ds_fixed_fee", "topup", "topup_fee", "topup_reversal", "treasury_payin", "whop_processing_fee", "withdrawal", "withdrawal_clawback", "withdrawal_clawback_reversal", "withdrawal_fee", "withdrawal_fee_reversal", "withdrawal_markup_fee", "withdrawal_markup_fee_payout", "withdrawal_markup_fee_payout_reversal", "withdrawal_markup_fee_reversal", "withdrawal_reclassification", "withdrawal_reversal", "withdrawal_topup_adjustment" ], "example": "onchain_deposit", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Optional direction filter. `money_in` returns positive activity and `money_out` returns negative activity.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "money_in", "money_out" ], "type": "string" } }, { "description": "Optional prefixed resource ID. Returns activity associated with that resource.", "in": "query", "name": "resource_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter activity by payment ID (pay_), including related refunds, disputes, and fees. Combines with resource_id and other filters within the selected accounts. Unknown payments return an empty list.", "in": "query", "name": "payment_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional ledger activity ID (for example `line_3`). Returns at most that one activity.", "in": "query", "name": "activity_id", "required": false, "schema": { "type": "string" } }, { "description": "Whether to exclude balance reservations and balanced movements between the account's own balances.", "in": "query", "name": "exclude_internal_movements", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Which balance the activity changes. `total` includes available, pending, and reserved funds. `available` includes only movements into or out of available funds, including reservations, releases, and fees. Movements within the selected balance are omitted. Omit to preserve the existing activity feed. Requires account_id or user_id; cannot be combined with available_after or available_before.", "in": "query", "name": "balance_type", "required": false, "schema": { "enum": [ "total", "available" ], "type": "string" } }, { "description": "Withdrawal ID (wdrl_). With balance_type=available, selects the same period as its statement, after the previous withdrawal and through this withdrawal, excluding this withdrawal and its fee. Requires a single account. Overrides currency and posted-date filters.", "in": "query", "name": "withdrawal_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional currency code filter, for example `usd`.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Only include rows posted after this ISO 8601 timestamp.", "in": "query", "name": "posted_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include rows posted before this ISO 8601 timestamp.", "in": "query", "name": "posted_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include balance credits and debits available on or after this `YYYY-MM-DD` date (UTC), distinct from posted_at. Requires currency.", "in": "query", "name": "available_after", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Only include balance credits and debits available on or before this `YYYY-MM-DD` date (UTC). Set equal to available_after for a single day. Requires currency.", "in": "query", "name": "available_before", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Maximum number of rows to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor returned by the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LedgerActivity" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_2", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_1", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "activities listed for a user" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither account_id nor user_id provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no ledger for that owner is visible to the credential" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] }, { "bearerAuth": [ "user:balance:read" ] } ], "summary": "List Financial Activity", "tags": [ "Ledgers" ] }, "x-whop-surface": "native" }, "/financial_reports": { "get": { "description": "Returns a financial report — balance activity, income statement, or balance summary — for an account over a date range.", "operationId": "getFinancialReport", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The owning account ID (a biz_ identifier), or `global` for a platform-wide report across all ledger accounts (requires internal admin access).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "The type of financial report to generate.", "in": "query", "name": "report_type", "required": true, "schema": { "enum": [ "balance_summary", "income_statement", "balance_activity" ], "type": "string" } }, { "description": "Filter rows to this currency, for example `usd`. Defaults to `usd` unless `in_currency` is provided.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Aggregate all activity into this display currency via FX conversion.", "in": "query", "name": "in_currency", "required": false, "schema": { "type": "string" } }, { "description": "Start of the report window as an ISO 8601 timestamp. Required for platform-wide (global) reports.", "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Exclusive end of the report window as an ISO 8601 timestamp. Required for platform-wide (global) reports.", "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Grouping granularity for report rows. Hourly grouping is supported for account-level balance activity reports only; hourly periods are timestamps in the requested timezone.", "in": "query", "name": "group_by", "required": false, "schema": { "default": "month", "enum": [ "hour", "day", "week", "month" ], "type": "string" } }, { "description": "IANA timezone (for example `America/New_York`) used to bucket report periods. Defaults to UTC. `from` and `to` remain exact instants.", "in": "query", "name": "timezone", "required": false, "schema": { "type": "string" } }, { "description": "Account-level balance activity only: ledger line categories to include.", "explode": true, "in": "query", "name": "line_types", "required": false, "schema": { "items": { "enum": [ "account_settlement", "ad_affiliate_payout_received", "ad_budget_release", "ad_campaign_budget", "ad_publisher_payout", "ad_publisher_payout_received", "ad_spend_charge", "affiliate_fee", "airdrop", "airdrop_link_created", "airdrop_link_redeemed", "airdrop_link_returned", "airdrop_reversal", "application_fee", "application_fee_payout", "balance_reservation", "balance_reservation_reversal", "bank_transfer", "billing_percentage_fee", "buyer_fee", "card_interchange", "card_load_deposit", "card_load_transfer", "card_spend_authorization", "card_spend_authorization_void", "card_spend_refund", "card_unload_deposit", "card_unload_transfer", "cashback", "cashback_funding", "company_referral", "connected_account_negative_balance", "cross_border_percentage_fee", "currency_conversion_incoming", "currency_conversion_outgoing", "dispute_alert_fee", "dispute_hold_adjustment", "dispute_representment_fee", "economic_intelligence_percentage_fee", "external_card_load_deposit", "fees", "fraud_prevention_fee", "fx_percentage_fee", "high_risk_merchant_fee", "installment_default", "internal_balance_transfer_incoming", "internal_balance_transfer_outgoing", "internal_withdrawal", "internal_withdrawal_complete", "internal_withdrawal_fee", "internal_withdrawal_fee_reversal", "internal_withdrawal_in_transit", "internal_withdrawal_in_transit_reversal", "internal_withdrawal_markup_fee", "internal_withdrawal_markup_fee_payout", "internal_withdrawal_markup_fee_payout_reversal", "internal_withdrawal_markup_fee_reversal", "internal_withdrawal_reversal", "legacy_crypto_payment", "legacy_payment", "legacy_payment_refund", "license_sale", "license_sale_commission", "license_sale_revenue", "marketplace_affiliate_fee", "misc_purchase", "misc_refund", "misc_reversal", "onboarding_reward", "onchain_deposit", "onchain_internal_transfer_incoming", "onchain_internal_transfer_outgoing", "onchain_platform_transfer_incoming", "onchain_platform_transfer_outgoing", "onchain_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "orchestration_percentage_fee", "partner_grant_reward", "passthrough_gmv", "payment_dispute", "payment_dispute_adjustment", "payment_dispute_fee", "payment_dispute_reversal", "payment_gross", "payment_gross_reversal", "payment_processing_fixed_fee", "payment_processing_percentage_fee", "payment_referral", "payment_referral_refund", "payment_referral_reversal", "payment_refund", "payment_refund_reversal", "payment_return_fee", "payment_revshare", "payment_revshare_payout", "payment_revshare_refund", "payment_revshare_reversal", "payout_fee", "platform_affiliate_payment", "platform_affiliate_payment_reversal", "platform_balance_payment", "platform_balance_payment_refund", "platform_balance_transfer_fee", "platform_balance_transfer_incoming", "platform_balance_transfer_outgoing", "platform_covered_dispute", "platform_credits_granted", "platform_credits_payment", "platform_credits_payment_refund", "platform_earning", "platform_markup_fee", "platform_markup_fee_payout", "promo_reversal", "referral_bonus", "resolution_center_refund", "revshare_percentage_fee", "sales_tax_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "software_rental_revshare", "software_rental_transaction", "stripe_domestic_processing_fee", "stripe_international_processing_fee", "swap_fee", "three_ds_fixed_fee", "topup", "topup_fee", "topup_reversal", "treasury_payin", "whop_processing_fee", "withdrawal", "withdrawal_clawback", "withdrawal_clawback_reversal", "withdrawal_fee", "withdrawal_fee_reversal", "withdrawal_markup_fee", "withdrawal_markup_fee_payout", "withdrawal_markup_fee_payout_reversal", "withdrawal_markup_fee_reversal", "withdrawal_reclassification", "withdrawal_reversal", "withdrawal_topup_adjustment" ], "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Account-level balance activity only: include money moving in or money moving out.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "money_in", "money_out" ], "type": "string" } }, { "description": "Platform-wide (global) reports only: when true, return cumulative balances as of to (all history, no lower bound) instead of activity within the period.", "in": "query", "name": "cumulative", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Platform-wide (global) reports only: narrow the report to ledger lines on the ledger account owned by this account ID (a biz_ identifier). Ignored unless account_id is `global`.", "in": "query", "name": "scope_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Balance activity only: include payment costs grouped by payment method and provider.", "in": "query", "name": "include_payment_fee_breakdown", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Account-level balance activity only: return only currencies with cashflow in the exact requested window. Requires `from` and `to`.", "in": "query", "name": "period_only_currencies", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "beginning_balance": { "example": 11480.02, "type": [ "number", "null" ] }, "currencies": { "description": "Cashflow currencies ordered by volume in the requested period. Includes lifetime currencies unless `period_only_currencies` is true.", "items": { "example": "usd", "type": "string" }, "type": "array" }, "ending_balance": { "example": 23750.55, "type": [ "number", "null" ] }, "fx_excluded_currencies": { "items": { "example": "ngn", "type": "string" }, "type": "array" }, "payment_fee_breakdown": { "description": "Payment costs grouped by customer-facing payment method and provider when requested.", "items": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Payment costs attributed to this payment method." }, "category": { "description": "The customer-facing payment method family or standalone service.", "enum": [ "app_store_payments", "bank_payments", "buy_now_pay_later", "card_payments", "crypto_payments", "fraud_prevention", "local_payments", "other_payment_methods", "subscription_billing", "wallet_payments", "whop_balance", "whop_orchestration" ], "example": "app_store_payments", "type": "string" }, "payment_method": { "description": "The card brand, payment provider, payment rail, or standalone service.", "type": "string" }, "period": { "description": "Start of the time bucket containing these payment costs.", "type": "string" } }, "required": [ "period", "category", "payment_method", "amount" ], "type": "object" }, "type": "array" }, "report_type": { "description": "The report that was generated, echoing the requested `report_type`.", "enum": [ "balance_summary", "income_statement", "balance_activity" ], "example": "balance_summary", "type": "string" }, "rows": { "items": { "properties": { "account_ik_path": { "example": "assets/wallets/wallet/available", "type": [ "string", "null" ] }, "account_name": { "example": "Available balance", "type": [ "string", "null" ] }, "account_type": { "example": "asset", "type": [ "string", "null" ] }, "amount": { "example": 23750.55, "type": "number" }, "grouping": { "description": "The family the row's `line_category` rolls up into. Balance summary rows are always `balance`.", "enum": [ "advertising", "affiliates_and_revshare", "airdrops", "bad_debt", "balance", "clawbacks", "connected_accounts", "crypto", "disputes", "fees", "fx", "legacy", "misc", "operational_costs", "other", "payments", "platform_credits", "refunds", "reserves", "transfers", "wallets_and_balance", "withdrawals" ], "example": "payments", "type": "string" }, "line_category": { "description": "The ledger line category the row aggregates. Balance summary rows carry the balance bucket instead.", "enum": [ "accelerated_settlement_fee", "account_settlement", "ad_affiliate_payout", "ad_affiliate_payout_received", "ad_balance_funding_receipt", "ad_budget_release", "ad_campaign_budget", "ad_funding_disbursement", "ad_income_expense", "ad_income_receipt", "ad_network_cost", "ad_network_settlement", "ad_publisher_payout", "ad_publisher_payout_received", "ad_spend_charge", "ad_spend_margin", "ad_spend_purchase", "ads_card_spread", "affiliate_fee", "aggregated_fee", "airdrop", "airdrop_expense", "airdrop_expense_reversal", "airdrop_link_canceled", "airdrop_link_claimed", "airdrop_link_created", "airdrop_link_funded", "airdrop_link_redeemed", "airdrop_link_returned", "airdrop_reversal", "application_fee", "application_fee_payable", "application_fee_payout", "available", "bad_debt_expense", "bad_debt_offset", "balance_reservation", "balance_reservation_hold", "balance_reservation_release", "balance_reservation_reversal", "billing_percentage_fee", "buyer_fee", "card_interchange", "card_interchange_receivable", "card_load_deposit", "card_load_transfer", "card_spend_authorization", "card_spend_authorization_hold", "card_spend_authorization_void", "card_spend_authorization_void_release", "card_spend_capture", "card_spend_capture_offset", "card_spend_refund", "card_spend_refund_offset", "card_unload_deposit", "card_unload_transfer", "cashback", "cashback_expense", "cashback_funding", "clawback_fee", "clawback_receivable", "clawback_receivable_reversal", "clawback_receivable_settlement", "clawback_receivable_settlement_reversal", "company_referral", "connected_account_clawback", "connected_account_negative_balance", "cross_border_percentage_fee", "crypto", "currency_conversion_incoming", "currency_conversion_outgoing", "dispute_alert_fee", "dispute_hold", "dispute_hold_adjustment", "dispute_hold_blocked", "dispute_management_fee", "dispute_payable_clearing", "dispute_payable_reversal", "dispute_representment_fee", "dispute_settlement", "dispute_settlement_reversal", "dispute_unreconciled_clearing", "dispute_unreconciled_reversal", "economic_intelligence_percentage_fee", "external_account_connection_fee", "external_card_load_deposit", "external_card_load_offset", "fraud_prevention_fee", "fx_gain_loss", "fx_markup", "fx_percentage_fee", "fx_settlement_gain_loss", "high_risk_merchant_fee", "identity_verification_fee", "installment_default", "internal_balance_transfer_incoming", "internal_balance_transfer_outgoing", "internal_withdrawal", "internal_withdrawal_complete", "internal_withdrawal_fee", "internal_withdrawal_fee_reversal", "internal_withdrawal_in_transit", "internal_withdrawal_in_transit_reversal", "internal_withdrawal_markup_fee", "internal_withdrawal_markup_fee_payout", "internal_withdrawal_markup_fee_payout_reversal", "internal_withdrawal_markup_fee_reversal", "internal_withdrawal_payable", "internal_withdrawal_payable_reversal", "internal_withdrawal_reversal", "legacy_crypto_payment", "legacy_payment", "legacy_payment_refund", "license_sale", "license_sale_commission", "license_sale_revenue", "marketplace_affiliate_fee", "misc_purchase", "misc_refund", "misc_reversal", "onboarding_reward", "onchain_deposit", "onchain_deposit_offset", "onchain_internal_transfer_incoming", "onchain_internal_transfer_outgoing", "onchain_platform_transfer_incoming", "onchain_platform_transfer_outgoing", "onchain_swap_offset", "onchain_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "onchain_withdrawal_offset", "orchestration_percentage_fee", "partner_grant_reward", "passthrough_gmv", "passthrough_gmv_offset", "payment_dispute", "payment_dispute_adjustment", "payment_dispute_fee", "payment_dispute_reversal", "payment_gross", "payment_gross_reversal", "payment_processing_fixed_fee", "payment_processing_percentage_fee", "payment_receivable_clearing", "payment_receivable_reversal", "payment_receivable_settlement", "payment_referral", "payment_referral_payable", "payment_referral_refund", "payment_referral_reversal", "payment_refund", "payment_refund_fee", "payment_refund_reversal", "payment_return_fee", "payment_revshare", "payment_revshare_payout", "payment_revshare_refund", "payment_revshare_reversal", "payment_unreconciled_clearing", "payment_unreconciled_reversal", "payout_fee", "payout_receivable", "payout_subsidy", "payout_unreconciled_clearing", "pending", "platform_affiliate_payment", "platform_affiliate_payment_reversal", "platform_balance_payment", "platform_balance_payment_refund", "platform_balance_transfer_fee", "platform_balance_transfer_incoming", "platform_balance_transfer_outgoing", "platform_covered_dispute", "platform_credits_granted", "platform_credits_payment", "platform_credits_payment_refund", "platform_earning", "platform_earning_settlement", "platform_earning_unreconciled_clearing", "platform_markup_fee", "platform_markup_fee_payout", "promo_reversal", "psp_accelerated_settlement_fee", "psp_account_debit", "psp_account_updater_fee", "psp_adjusted_processing_fee", "psp_authentication_fee", "psp_bank_pull_clearing", "psp_bank_pull_settlement", "psp_billing_fee", "psp_clawback_fee", "psp_clawback_settlement", "psp_clawback_settlement_reversal", "psp_collection_settlement", "psp_commission_fee", "psp_connect_fee", "psp_correction", "psp_currency_conversion_incoming", "psp_currency_conversion_outgoing", "psp_currency_conversion_receivable", "psp_currency_conversion_receivable_clearing", "psp_dispute_alert_fee", "psp_dispute_fee", "psp_dispute_management_fee", "psp_dispute_payable", "psp_external_account_connection_fee", "psp_fixed_fee", "psp_fx_adjustment", "psp_gateway_fee", "psp_identity_verification_fee", "psp_interchange_fee", "psp_invoice_tax_fee", "psp_invoicing_fee", "psp_markup_fee", "psp_network_token_fee", "psp_optimization_fee", "psp_payin_clearing", "psp_payin_settlement", "psp_payment_method_fee", "psp_payment_receivable", "psp_payout_consolidation", "psp_payout_deposit", "psp_payout_fee", "psp_payout_receivable", "psp_payout_receivable_clearing", "psp_payout_settlement", "psp_payout_settlement_reversal", "psp_pool_clearing", "psp_pool_dispute_settlement", "psp_pool_refund_clearing", "psp_pool_refund_settlement", "psp_pool_settlement", "psp_processing_fee", "psp_receivable_pooled", "psp_recipient_wallet_load", "psp_refund_fee", "psp_refund_payable", "psp_reserve_hold", "psp_reserve_release", "psp_risk_fee", "psp_scheme_fee", "psp_service_fee", "psp_tax_filing_fee", "psp_tax_service_fee", "psp_terminal_fee", "psp_transfer_settlement", "psp_transfer_settlement_reversal", "psp_treasury_fee", "psp_variable_fee", "psp_withholding_tax", "recipient_wallet_load", "referral_bonus", "refund_payable_clearing", "refund_payable_reversal", "refund_settlement", "refund_settlement_reversal", "refund_unreconciled_clearing", "refund_unreconciled_reversal", "reserve", "resolution_center_refund", "revshare_percentage_fee", "sales_tax_collected", "sales_tax_collected_reversal", "sales_tax_fee", "sales_tax_remittance", "sales_tax_remittance_reversal", "sales_tax_remitted", "settlement_rounding_variance", "settlement_shortfall_loss", "software_rental_revshare", "software_rental_transaction", "stripe_domestic_processing_fee", "stripe_international_processing_fee", "swap_fee", "tax_filing_fee", "three_ds_fixed_fee", "topup", "topup_fee", "topup_reversal", "trading_account_deposit", "trading_account_deposit_offset", "trading_account_withdrawal", "trading_account_withdrawal_offset", "treasury_fee", "treasury_payin", "treasury_payin_receivable", "whop_processing_fee", "whop_swap_fee_received", "withdrawal", "withdrawal_clawback", "withdrawal_clawback_reversal", "withdrawal_fee", "withdrawal_fee_reversal", "withdrawal_markup_fee", "withdrawal_markup_fee_payout", "withdrawal_markup_fee_payout_reversal", "withdrawal_markup_fee_reversal", "withdrawal_payable", "withdrawal_payable_clearing", "withdrawal_payable_clearing_reversal", "withdrawal_payable_reversal", "withdrawal_reclassification", "withdrawal_reversal", "withdrawal_topup_adjustment" ], "example": "payment_gross", "type": "string" }, "line_count": { "example": 214, "type": [ "integer", "null" ] }, "period": { "description": "Start of the time bucket this row covers, truncated to `group_by`.", "example": "2026-05", "type": "string" }, "profit_and_loss_section": { "description": "Which side of the income statement the category falls on, or `null` when it is not a P&L category.", "enum": [ "revenue", "cost_of_revenue", null ], "example": "revenue", "type": [ "string", "null" ] } }, "required": [ "period", "grouping", "line_category", "amount" ], "type": "object" }, "type": "array" }, "total": { "example": 23750.55, "type": "number" } }, "required": [ "report_type", "rows", "total" ], "type": "object" } } }, "description": "financial report returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid report type" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no ledger for that account" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Get Financial Report", "tags": [ "Ledgers" ] }, "x-whop-surface": "native" }, "/financial_reports/breakdown": { "get": { "description": "Breaks one bucket of a financial report, such as payments received or card spend, into the customers, accounts, merchants, or campaigns that contributed most, with the rest summed as a remainder. Use it to explain a total from `GET /financial_reports`.", "operationId": "getFinancialReportBreakdown", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The owning account ID (a biz_ identifier).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "The high-level report bucket to explain.", "in": "query", "name": "bucket", "required": true, "schema": { "enum": [ "transfers", "payments", "refunds", "ads", "application_fees", "card_spend", "card_authorization_releases", "withdrawals", "withdrawal_markup", "platform_markup", "clawbacks", "disputes", "affiliate_earnings", "affiliate_payouts", "revenue_share", "swaps", "card_loads" ], "type": "string" } }, { "description": "Whether to explain money received or money sent.", "in": "query", "name": "direction", "required": true, "schema": { "enum": [ "money_in", "money_out" ], "type": "string" } }, { "description": "The report currency to explain.", "in": "query", "name": "currency", "required": true, "schema": { "type": "string" } }, { "description": "Start of the report window as an ISO 8601 timestamp.", "in": "query", "name": "from", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Exclusive end of the report window as an ISO 8601 timestamp.", "in": "query", "name": "to", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Period grouping used by the parent report.", "in": "query", "name": "group_by", "required": false, "schema": { "default": "month", "enum": [ "hour", "day", "week", "month" ], "type": "string" } }, { "description": "IANA timezone used by the parent report to bucket periods. Defaults to UTC.", "in": "query", "name": "timezone", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "activity_filters": { "properties": { "direction": { "enum": [ "money_in", "money_out" ], "example": "money_out", "type": "string" }, "line_types": { "items": { "example": "platform_balance_transfer_outgoing", "type": "string" }, "type": "array" } }, "required": [ "line_types", "direction" ], "type": "object" }, "bucket": { "enum": [ "transfers", "payments", "refunds", "ads", "application_fees", "card_spend", "card_authorization_releases", "withdrawals", "withdrawal_markup", "platform_markup", "clawbacks", "disputes", "affiliate_earnings", "affiliate_payouts", "revenue_share", "swaps", "card_loads" ], "example": "transfers", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "direction": { "enum": [ "money_in", "money_out" ], "example": "money_out", "type": "string" }, "items": { "items": { "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "avatar": { "description": "How to draw the row's icon. `null` when the row has nothing to show (balances, adjustments, ad campaigns), so clients render no icon rather than a placeholder.", "oneOf": [ { "properties": { "shape": { "enum": [ "circle", "square" ], "example": "circle", "type": "string" }, "url": { "description": "The image to show, or `null` to fall back to the row's initials.", "type": [ "string", "null" ] } }, "required": [ "url", "shape" ], "type": "object" }, { "type": "null" } ] }, "image_url": { "type": [ "string", "null" ] }, "key": { "description": "An opaque identifier for this grouping within the breakdown.", "type": "string" }, "name": { "type": "string" }, "object": { "enum": [ "user", "account", "merchant", "payout_destination", "balance", "withdrawal_adjustment", "ad_campaign" ], "example": "user", "type": "string" }, "resource_id": { "description": "The prefixed identifier of the represented Whop resource, when one exists.", "type": [ "string", "null" ] } }, "required": [ "key", "resource_id", "object", "name", "image_url", "avatar", "amount" ], "type": "object" }, "maxItems": 5, "type": "array" }, "other_amount": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "example": null, "type": "null" } ] }, "other_name": { "example": "Other", "type": "string" } }, "required": [ "bucket", "direction", "currency", "items", "other_amount", "other_name", "activity_filters" ], "type": "object" } } }, "description": "breakdown returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid breakdown parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required balance-read scope" } }, "security": [ { "bearerAuth": [ "company:balance:read" ] } ], "summary": "Get Financial Report Breakdown", "tags": [ "Ledgers" ] }, "x-whop-surface": "native" }, "/financing_applications": { "get": { "description": "Lists payment-financing applications. Without `account_id`, an account credential lists its own account and its direct connected accounts, but not deeper descendants, and a user credential lists every account it can read applications for.", "operationId": "listFinancingApplications", "parameters": [ { "description": "Only applications for this account, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only applications in this review state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "requires_collection", "awaiting_review", "completed", "approved", "denied" ], "type": "string" } }, { "description": "Applications created at or before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Applications created at or after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Field to sort by. Defaults to created_at.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "updated_at" ], "type": "string" } }, { "description": "Sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/FinancingApplication" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": null, "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Applications returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Read permission required" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "List Financing Applications", "tags": [ "Financing Applications" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts an application for payment-financing approval, or returns the account's open one: an application in `awaiting_review` takes precedence over one in `requires_collection`, and the open application is reused across different `Idempotency-Key` values. Creating an application does not submit it for review. The account must have a Whop balance set up, and accounts in restricted industries cannot apply. Once an application closes, the account can apply again.", "operationId": "createFinancingApplication", "parameters": [ { "description": "A unique key for safely retrying the same request for up to 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account applying, prefixed `biz_`. Defaults to the account behind an account credential; required with a user credential.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancingApplication" } } }, "description": "Open application reused" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancingApplication" } } }, "description": "Application created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Restricted industry" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Update permission required" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:account:update" ] } ], "summary": "Create Financing Application", "tags": [ "Financing Applications" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/financing_applications/{id}": { "get": { "description": "Retrieves a payment-financing application with its review state, requirements, saved answers, documents, current terms, and review feedback. Requires read access to the account that owns it.", "operationId": "retrieveFinancingApplication", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancingApplication" } } }, "description": "Application returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Read permission required" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Application not found" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve Financing Application", "tags": [ "Financing Applications" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Financing application ID, prefixed `inrq_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Saves merchant answers to an application in `requires_collection`. The batch is atomic: if any answer is rejected, none are saved. Omitted requirements and answer fields are left unchanged. Saving answers does not submit the application; call Submit Financing Application when it is complete.", "operationId": "updateFinancingApplication", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "answers": { "items": { "additionalProperties": false, "properties": { "file_ids": { "description": "Complete replacement set of file IDs for this requirement, prefixed `file_`. Upload documents through the Files API first: new files must belong to the caller, be ready and private, and satisfy the requirement's formats and 20 MB limit. An empty array removes all files.", "items": { "type": "string" }, "maxItems": 20, "type": "array", "uniqueItems": true }, "money": { "additionalProperties": false, "description": "Price answer, such as `max_product_price`. `null` clears the price.", "properties": { "amount": { "description": "Positive exact decimal amount in major units, such as 1234.56. At most 12 whole digits and the currency's fractional precision.", "type": "string" }, "currency": { "description": "Currency of the maximum product price.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "cny", "kzt", "awg" ], "example": "usd", "type": "string" } }, "required": [ "amount", "currency" ], "type": [ "object", "null" ] }, "requirement_id": { "description": "ID of a merchant requirement returned on this application.", "example": "inrqi_xxxxxxxxxxxxxx", "type": "string" }, "values": { "description": "Text answers. Use `money` instead for `max_product_price`. An empty array clears the answer.", "items": { "example": "https://shop.example.com/updated", "type": "string" }, "type": "array" } }, "required": [ "requirement_id" ], "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "answers" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancingApplication" } } }, "description": "Answers saved" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid answers or application state" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Update permission required" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Application not found" } }, "security": [ { "bearerAuth": [ "payout:account:update" ] } ], "summary": "Update Financing Application", "tags": [ "Financing Applications" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/financing_applications/{id}/submit": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Financing application ID, prefixed `inrq_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Submits a complete application for financing review, recording the merchant's acceptance, who submitted, and when, then moving it to `awaiting_review`. Before calling, present the application's `terms.content`, policies, and disclosure to the merchant and collect affirmative acceptance; every resubmission needs acceptance again. Only an application in `requires_collection` can be submitted, including after a reviewer requests more information. Retry with the same `Idempotency-Key`: submitting an application already in review without a replay returns an error. Approval does not by itself enable financing payment methods.", "operationId": "submitFinancingApplication", "parameters": [ { "description": "A unique key for safely retrying the same request for up to 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "merchant_acceptance": { "properties": { "accepted": { "description": "Affirmation that the merchant accepted the presented terms.", "enum": [ true ], "example": true, "type": "boolean" }, "terms_version": { "description": "Exact `terms.version` returned by the application and presented to the merchant. A stale version is rejected.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "accepted", "terms_version" ], "type": "object" } }, "required": [ "merchant_acceptance" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancingApplication" } } }, "description": "Application submitted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid answers, acceptance, or application state" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication required" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Update permission required" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Application not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:account:update" ] } ], "summary": "Submit Financing Application", "tags": [ "Financing Applications" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/forum_posts": { "get": { "description": "Returns a paginated list of forum posts within a specific experience, with optional filtering by parent post or pinned status.\n\nRequired permissions:\n - `forum:read`", "operationId": "listForumPost", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "experience_id", "required": true, "schema": { "description": "The unique identifier of the experience to list forum posts for.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "include_bounty_anchors", "required": false, "schema": { "description": "Whether to include top-level bounty discussion anchors as rich forum items.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "parent_id", "required": false, "schema": { "description": "The unique identifier of a parent post to list comments for. When set, returns replies to that post.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "pinned", "required": false, "schema": { "description": "Whether to filter for only pinned posts. Set to true to return only pinned posts.", "type": "boolean" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for ForumPost.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ForumPostListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:read" ] } ], "summary": "List forum posts", "tags": [ "Forum posts" ], "x-group-title": "Engagement" }, "post": { "description": "Create a new forum post or comment within an experience. Supports text content, attachments, polls, paywalling, and pinning.\n\nRequired permissions:\n - `forum:post:create`", "operationId": "createForumPost", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateForumPostV2", "properties": { "account_id": { "description": "The unique identifier of the company whose public forum to post in. Required when experience_id is 'public'. For example, 'biz_xxxxx'.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "attachments": { "description": "A list of file attachments to include with the post, such as images or videos.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "content": { "description": "The main body of the post in Markdown format. For example, 'Check out this **update**'. Hidden if the post is paywalled and the viewer has not purchased access.", "type": [ "string", "null" ] }, "experience_id": { "description": "The unique identifier of the experience to create this post in. For example, 'exp_xxxxx'. Pass 'public' along with account_id to automatically use the account's public forum.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "is_mention": { "description": "Whether to send this post as a mention notification to all users in the experience who have mentions enabled.", "type": [ "boolean", "null" ] }, "parent_id": { "description": "The unique identifier of the parent post to comment on. Omit this field to create a top-level post.", "type": [ "string", "null" ] }, "paywall_amount": { "description": "The price to unlock this post in the specified paywall currency. For example, 5.00 for $5.00. When set, users must purchase access to view the post content.", "example": 6.9, "type": [ "number", "null" ] }, "paywall_currency": { "description": "The currency for the paywall price on this post. When set along with paywall_amount, users must purchase access to view the post content.", "oneOf": [ { "$ref": "#/components/schemas/Currencies" }, { "type": "null" } ] }, "pinned": { "description": "Whether this post should be pinned to the top of the forum.", "type": [ "boolean", "null" ] }, "poll": { "description": "A poll to attach to this post, allowing members to vote on options.", "properties": { "options": { "description": "The options for the poll. Must have sequential IDs starting from 1", "items": { "description": "Input type for a single poll option", "properties": { "id": { "description": "Sequential ID for the poll option (starting from '1')", "type": "string" }, "text": { "description": "The text of the poll option", "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "type": "array" } }, "required": [ "options" ], "type": [ "object", "null" ] }, "rich_content": { "description": "The rich content of the post in Tiptap JSON format. When provided, takes priority over the markdown content field for rendering.", "type": [ "string", "null" ] }, "title": { "description": "The title of the post, displayed prominently at the top. Required for paywalled posts as it remains visible to non-purchasers.", "type": [ "string", "null" ] }, "visibility": { "description": "Controls who can see this forum post, such as members only or public.", "oneOf": [ { "$ref": "#/components/schemas/ForumPostVisibilityTypes" }, { "type": "null" } ] } }, "required": [ "experience_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumPost" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:post:create" ] } ], "summary": "Create forum post", "tags": [ "Forum posts" ], "x-group-title": "Engagement" } }, "/forum_posts/{id}": { "get": { "description": "Retrieves the details of an existing forum post.\n\nRequired permissions:\n - `forum:read`", "operationId": "retrieveForumPost", "parameters": [ { "description": "The unique identifier of the forum post to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumPost" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:read" ] } ], "summary": "Retrieve forum post", "tags": [ "Forum posts" ], "x-group-title": "Engagement" }, "patch": { "description": "Edit the content, attachments, pinned status, or visibility of an existing forum post or comment.", "operationId": "updateForumPost", "parameters": [ { "description": "The unique identifier of the forum post to update.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateForumPost", "properties": { "attachments": { "description": "A replacement list of file attachments for this post, such as images or videos.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "content": { "description": "The updated body of the post in Markdown format. For example, 'Check out this **update**'. Hidden if the post is paywalled and the viewer has not purchased access.", "type": [ "string", "null" ] }, "is_pinned": { "description": "Whether this post should be pinned to the top of the forum. Only top-level posts can be pinned, not comments.", "type": [ "boolean", "null" ] }, "title": { "description": "The updated title of the post, displayed prominently at the top. Required for paywalled posts as it remains visible to non-purchasers.", "type": [ "string", "null" ] }, "visibility": { "description": "Controls who can see this forum post, such as members only or public.", "oneOf": [ { "$ref": "#/components/schemas/ForumPostVisibilityTypes" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumPost" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update forum post", "tags": [ "Forum posts" ], "x-group-title": "Engagement" } }, "/forums": { "get": { "description": "Returns a paginated list of forums for an account, with optional filtering by product.\n\nRequired permissions:\n - `forum:read`", "operationId": "listForum", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_id", "required": false, "schema": { "description": "The unique identifier of a product to filter by. When set, only forums connected to this product are returned.", "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": true, "schema": { "description": "The unique identifier of the company to list forums for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for ForumFeed.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ForumListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:read" ] } ], "summary": "List forums", "tags": [ "Forums" ], "x-group-title": "Engagement" } }, "/forums/{id}": { "get": { "description": "Retrieves the details of an existing forum.\n\nRequired permissions:\n - `forum:read`", "operationId": "retrieveForum", "parameters": [ { "description": "The unique identifier of the forum or experience to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forum" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:read" ] } ], "summary": "Retrieve forum", "tags": [ "Forums" ], "x-group-title": "Engagement" }, "patch": { "description": "Update moderation and notification settings for a forum, such as who can post, who can comment, and email notification preferences.\n\nRequired permissions:\n - `forum:moderate`", "operationId": "updateForum", "parameters": [ { "description": "The unique identifier of the forum to update. Accepts either an experience ID (e.g. 'exp_xxxxx') or a forum ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateForum", "properties": { "banned_words": { "description": "A list of words that are automatically blocked from posts in this forum. For example, ['spam', 'scam'].", "items": { "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.", "type": "string" }, "type": [ "array", "null" ] }, "banner_image": { "description": "The banner image displayed at the top of the forum page. Pass null to remove the existing banner.", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": [ "object", "null" ] }, "email_notification_preference": { "description": "Controls how email notifications are sent to members when new posts are created in this forum.", "oneOf": [ { "$ref": "#/components/schemas/ForumEmailNotificationPreferences" }, { "type": "null" } ] }, "who_can_comment": { "description": "Controls which roles are allowed to comment on posts in this forum.", "oneOf": [ { "$ref": "#/components/schemas/ForumWhoCanCommentTypes" }, { "type": "null" } ] }, "who_can_post": { "description": "Controls which roles are allowed to create new posts in this forum.", "oneOf": [ { "$ref": "#/components/schemas/ForumWhoCanPostTypes" }, { "type": "null" } ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forum" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "forum:moderate" ] } ], "summary": "Update forum", "tags": [ "Forums" ], "x-group-title": "Engagement" } }, "/identity_profiles": { "get": { "description": "Lists the identity profiles currently linked to an account, or to every account you can read when `account_id` is omitted.\n\nRequired permissions:\n - `identity:read`", "operationId": "listIdentityProfile", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "profile_type", "required": false, "schema": { "$ref": "#/components/schemas/IdentityProfileKinds", "description": "Filter by profile type (individual or business)." }, "style": "form" }, { "explode": true, "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/IdentityProfileStatuses", "description": "Filter by derived verification status." }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "Account to list identity profiles for, prefixed `biz_`. Omit to list profiles across every account you can read, including child accounts under a parent and, with a user credential, your own user.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for IdentityProfile.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/IdentityProfileListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "identity:read" ] } ], "summary": "List identity profiles", "tags": [ "Identity profiles" ], "x-group-title": "Payouts" } }, "/identity_profiles/{id}": { "delete": { "description": "Unlinks an identity profile from the account or user that owns `ledger_account_id`. Requires `identity:write` on that account or user.\n\nRequired permissions:\n - `identity:write`", "operationId": "unlinkIdentityProfile", "parameters": [ { "description": "The ID of the IdentityProfile to unlink.", "in": "path", "name": "id", "required": true, "schema": { "example": "idpf_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "ledger_account_id", "required": true, "schema": { "description": "The ID of the LedgerAccount to unlink the identity profile from.", "example": "ldgr_xxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProfile" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "identity:write" ] } ], "summary": "Unlink an identity profile", "tags": [ "Identity profiles" ], "x-group-title": "Payouts" }, "get": { "description": "Retrieves the details of an existing identity profile.\n\nRequired permissions:\n - `identity:read`", "operationId": "retrieveIdentityProfile", "parameters": [ { "description": "The unique identifier of the identity profile (idpf_xxx).", "in": "path", "name": "id", "required": true, "schema": { "example": "idpf_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProfile" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "identity:read" ] } ], "summary": "Retrieve identity profile", "tags": [ "Identity profiles" ], "x-group-title": "Payouts" } }, "/identity_profiles/{id}/verifications": { "get": { "description": "Returns a list of verifications attached to an identity profile, ordered by most recent first.\n\nRequired permissions:\n - `identity:read`", "operationId": "listVerificationsIdentityProfile", "parameters": [ { "description": "The unique identifier of the identity profile (idpf_xxx).", "in": "path", "name": "id", "required": true, "schema": { "example": "idpf_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Verification.", "properties": { "data": { "description": "A list of nodes.", "items": { "description": "An identity verification session used to confirm a person or entity's identity for payout account eligibility.", "properties": { "created_at": { "description": "When the verification record was created.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "id": { "description": "The numeric id of the verification record.", "example": "verf_xxxxxxxxxxxxx", "type": "string" }, "last_error_code": { "description": "The most recent error code returned during verification. Null if no error has occurred.", "oneOf": [ { "$ref": "#/components/schemas/VerificationErrorCodes" }, { "type": "null" } ] }, "last_error_reason": { "description": "A human-readable explanation of the most recent verification error. Null if no error has occurred.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "session_url": { "description": "A URL the user can visit to complete the verification process. Null if the session does not require user interaction.", "example": "https://verify.stripe.com/session/abc123", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VerificationStatuses", "description": "The current status of this verification session." } }, "required": [ "id", "status", "session_url", "last_error_code", "last_error_reason", "created_at" ], "type": "object" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "identity:read" ] } ], "summary": "List identity profile verifications", "tags": [ "Identity profiles" ], "x-group-title": "Payouts" } }, "/invoices": { "get": { "description": "Lists receipt-backed invoices for accounts the caller can read. Legacy invoices are excluded.", "operationId": "listInvoices", "parameters": [ { "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "enum": [ "draft", "open", "authorized", "paid", "pending", "uncollectible", "unresolved", "void" ], "type": "string" } }, { "in": "query", "name": "overdue", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "member_id", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "product_id", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "due_at" ], "type": "string" } }, { "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Invoice" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "invoices" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid overdue filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission on the account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "List Invoices", "tags": [ "Invoices" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a draft invoice backed by a receipt, with saved items, quantities, prices, and recipients. Issue the draft to resolve final tax and open the invoice. The pay_ ID stays the same when paid.", "operationId": "createInvoice", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account_id": { "description": "The issuing account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "billing_address": { "additionalProperties": false, "description": "Create a billing address linked to this member.", "properties": { "city": { "example": "New York", "type": "string" }, "country": { "description": "ISO 3166-1 alpha-2 country code.", "example": "US", "type": "string" }, "line1": { "example": "123 Main St", "type": "string" }, "line2": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "postal_code": { "example": "10001", "type": "string" }, "state": { "example": "NY", "type": [ "string", "null" ] } }, "required": [ "line1", "city", "postal_code", "country" ], "type": [ "object", "null" ] }, "buyer_fee_percentage": { "description": "The buyer's adjustable fee in percentage points, with at most two decimal places.", "example": 2.5, "maximum": 100, "minimum": 0, "type": "number" }, "customer_name": { "description": "The contact name when creating an email-only member.", "type": [ "string", "null" ] }, "due_at": { "description": "When payment is due, as an ISO 8601 timestamp.", "format": "date-time", "type": [ "string", "null" ] }, "email_address": { "description": "Resolve or create the member for this email, creating a Whop user when none exists. Mutually exclusive with member_id.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "items": { "description": "The variants being invoiced, all in the same currency. Each variant may appear once; use quantity for multiple units. Product and price come from each variant; a recurring variant must belong to a product, bills its renewal price and, once the invoice is paid, renews as a subscription charged to the payment method that paid it. With several items, every item that has a product must be a regular product, and all items need compatible payment, tax, and access settings.", "items": { "additionalProperties": false, "oneOf": [ { "example": { "variant_id": "plan_xxxxxxxxxxxxxx" }, "required": [ "variant_id" ] }, { "example": { "variant_id": "plan_xxxxxxxxxxxxxx" }, "required": [ "variant" ] } ], "properties": { "quantity": { "default": 1, "maximum": 999999, "minimum": 1, "type": "integer" }, "variant": { "additionalProperties": false, "description": "Find or create a variant inline by its attributes, using the payment API properties. Requires plan:create.", "properties": { "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "type": [ "boolean", "null" ] }, "application_fee_amount": { "description": "Application fee the platform collects per unit, in the variant currency (5.00 means $5.00 for USD). Must be positive and below the initial price for one-time variants or renewal price for recurring variants. Paid to the parent account alongside other processing fees; collection is capped to remaining proceeds. Applies to subsequent payments on recurring variants. Only valid for connected accounts with a parent account.", "type": [ "number", "null" ] }, "billing_period": { "description": "Recurring billing interval in days.", "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ null, "renewal", "one_time" ], "example": "one_time", "type": [ "string", "null" ] }, "currency": { "description": "Currency code for the variant prices.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "description": { "description": "Variant description.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Days until access expires.", "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Create a new variant instead of reusing a matching variant.", "type": [ "boolean", "null" ] }, "initial_price": { "description": "Additional amount charged on the first purchase, in the variant currency. For recurring variants without a trial, the first charge includes this amount plus renewal_price.", "example": 99, "type": [ "number", "null" ] }, "internal_notes": { "description": "Internal notes for the account.", "type": [ "string", "null" ] }, "override_tax_type": { "description": "Whether the variant's price includes tax: `inclusive` (tax is included in the price), `exclusive` (tax is added on top), or `unspecified`. Omit it or pass `null` to use the account's tax setting. On an account enrolled in the Whop tax service, `inclusive` or `exclusive` replaces the account's setting and `unspecified` keeps it. Otherwise it applies only where the account is the merchant of record: `inclusive` or `exclusive` replaces the account's setting when the account collects tax, and `unspecified` means the variant collects no tax. Where Whop is the merchant of record, the account's setting applies. Variants that differ only in this value are different variants.", "enum": [ null, "exclusive", "inclusive", "unspecified" ], "example": "exclusive", "type": [ "string", "null" ] }, "product": { "description": "Find or create a product by external identifier. Mutually exclusive with product_id.", "properties": { "collect_shipping_address": { "description": "Whether to collect a shipping address at checkout.", "type": [ "boolean", "null" ] }, "custom_statement_descriptor": { "description": "Custom card statement descriptor for the product, starting with WHOP*.", "type": [ "string", "null" ] }, "description": { "description": "Product description.", "type": [ "string", "null" ] }, "external_identifier": { "description": "Your unique identifier for the product.", "pattern": "\\S", "type": "string" }, "global_affiliate_percentage": { "description": "Percentage of revenue paid to global affiliates.", "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "Global affiliate program status.", "enum": [ null, "enabled", "disabled" ], "example": "enabled", "type": [ "string", "null" ] }, "headline": { "description": "Product headline.", "type": [ "string", "null" ] }, "product_tax_code_id": { "description": "Product tax code identifier.", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "Where to redirect the buyer after purchase.", "type": [ "string", "null" ] }, "route": { "description": "Product route.", "type": [ "string", "null" ] }, "title": { "description": "Product title.", "pattern": "\\S", "type": "string" }, "visibility": { "default": "hidden", "description": "Product visibility. Defaults to hidden.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "external_identifier", "title" ], "type": [ "object", "null" ] }, "product_id": { "description": "Existing product ID belonging to the account, prefixed `prod_`. Mutually exclusive with `product`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "renewal_price": { "description": "Recurring price in the variant currency.", "type": [ "number", "null" ] }, "title": { "description": "Variant title.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before renewal.", "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers.", "enum": [ null, "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": [ "string", "null" ] } }, "required": [ "currency" ], "type": "object" }, "variant_id": { "description": "An existing variant belonging to the account, identified by its plan_ ID.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" }, "mailing_address_id": { "description": "An address associated with the member. Mutually exclusive with billing_address.", "type": [ "string", "null" ] }, "member_id": { "description": "The billed customer, a member of the account. Changing email recipients does not change this buyer.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Up to 50 caller-owned string key/value pairs.", "example": { "purchase_order": "PO-42" }, "type": "object" }, "payment_method_id": { "description": "A saved payment method belonging to the member, prefixed `payt_`. Sending the invoice emails it now and charges this method on `due_at`, or right away when there is no `due_at` or it has passed. Issuing the invoice without sending it charges right away.", "example": "payt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "recipient_emails": { "description": "Email addresses saved for invoice delivery, independent of the billed customer. Saving them sends no email. Defaults to the customer email when omitted on create. Can be updated on draft, open, or uncollectible invoices.", "items": { "format": "email", "type": "string" }, "maxItems": 50, "type": "array" } }, "required": [ "account_id", "items" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "invoice created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid invoice" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Create Invoice", "tags": [ "Invoices" ] }, "x-whop-surface": "native" }, "/invoices/{id}": { "get": { "description": "Retrieves a receipt-backed invoice by its pay_ ID.", "operationId": "retrieveInvoice", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "invoice" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "invoice not found" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "Retrieve Invoice", "tags": [ "Invoices" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The invoice's pay_ ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates draft invoice items and billing fields. Recipient-only updates are also allowed on unpaid invoices. Edit customer contact details through the member API.", "operationId": "updateInvoice", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "billing_address": { "additionalProperties": false, "description": "Create a billing address linked to this member.", "properties": { "city": { "example": "New York", "type": "string" }, "country": { "description": "ISO 3166-1 alpha-2 country code.", "example": "US", "type": "string" }, "line1": { "example": "123 Main St", "type": "string" }, "line2": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "postal_code": { "example": "10001", "type": "string" }, "state": { "example": "NY", "type": [ "string", "null" ] } }, "required": [ "line1", "city", "postal_code", "country" ], "type": [ "object", "null" ] }, "buyer_fee_percentage": { "description": "The buyer's adjustable fee in percentage points, with at most two decimal places.", "example": 2.5, "maximum": 100, "minimum": 0, "type": "number" }, "due_at": { "description": "When payment is due, as an ISO 8601 timestamp.", "format": "date-time", "type": [ "string", "null" ] }, "items": { "description": "The variants being invoiced, all in the same currency. Each variant may appear once; use quantity for multiple units. Product and price come from each variant; a recurring variant must belong to a product, bills its renewal price and, once the invoice is paid, renews as a subscription charged to the payment method that paid it. With several items, every item that has a product must be a regular product, and all items need compatible payment, tax, and access settings.", "items": { "additionalProperties": false, "oneOf": [ { "example": { "variant_id": "plan_xxxxxxxxxxxxxx" }, "required": [ "variant_id" ] }, { "example": { "variant_id": "plan_xxxxxxxxxxxxxx" }, "required": [ "variant" ] } ], "properties": { "quantity": { "default": 1, "maximum": 999999, "minimum": 1, "type": "integer" }, "variant": { "additionalProperties": false, "description": "Find or create a variant inline by its attributes, using the payment API properties. Requires plan:create.", "properties": { "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "type": [ "boolean", "null" ] }, "application_fee_amount": { "description": "Application fee the platform collects per unit, in the variant currency (5.00 means $5.00 for USD). Must be positive and below the initial price for one-time variants or renewal price for recurring variants. Paid to the parent account alongside other processing fees; collection is capped to remaining proceeds. Applies to subsequent payments on recurring variants. Only valid for connected accounts with a parent account.", "type": [ "number", "null" ] }, "billing_period": { "description": "Recurring billing interval in days.", "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ null, "renewal", "one_time" ], "example": "one_time", "type": [ "string", "null" ] }, "currency": { "description": "Currency code for the variant prices.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "description": { "description": "Variant description.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Days until access expires.", "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Create a new variant instead of reusing a matching variant.", "type": [ "boolean", "null" ] }, "initial_price": { "description": "Additional amount charged on the first purchase, in the variant currency. For recurring variants without a trial, the first charge includes this amount plus renewal_price.", "example": 99, "type": [ "number", "null" ] }, "internal_notes": { "description": "Internal notes for the account.", "type": [ "string", "null" ] }, "override_tax_type": { "description": "Whether the variant's price includes tax: `inclusive` (tax is included in the price), `exclusive` (tax is added on top), or `unspecified`. Omit it or pass `null` to use the account's tax setting. On an account enrolled in the Whop tax service, `inclusive` or `exclusive` replaces the account's setting and `unspecified` keeps it. Otherwise it applies only where the account is the merchant of record: `inclusive` or `exclusive` replaces the account's setting when the account collects tax, and `unspecified` means the variant collects no tax. Where Whop is the merchant of record, the account's setting applies. Variants that differ only in this value are different variants.", "enum": [ null, "exclusive", "inclusive", "unspecified" ], "example": "exclusive", "type": [ "string", "null" ] }, "product": { "description": "Find or create a product by external identifier. Mutually exclusive with product_id.", "properties": { "collect_shipping_address": { "description": "Whether to collect a shipping address at checkout.", "type": [ "boolean", "null" ] }, "custom_statement_descriptor": { "description": "Custom card statement descriptor for the product, starting with WHOP*.", "type": [ "string", "null" ] }, "description": { "description": "Product description.", "type": [ "string", "null" ] }, "external_identifier": { "description": "Your unique identifier for the product.", "pattern": "\\S", "type": "string" }, "global_affiliate_percentage": { "description": "Percentage of revenue paid to global affiliates.", "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "Global affiliate program status.", "enum": [ null, "enabled", "disabled" ], "example": "enabled", "type": [ "string", "null" ] }, "headline": { "description": "Product headline.", "type": [ "string", "null" ] }, "product_tax_code_id": { "description": "Product tax code identifier.", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "Where to redirect the buyer after purchase.", "type": [ "string", "null" ] }, "route": { "description": "Product route.", "type": [ "string", "null" ] }, "title": { "description": "Product title.", "pattern": "\\S", "type": "string" }, "visibility": { "default": "hidden", "description": "Product visibility. Defaults to hidden.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "external_identifier", "title" ], "type": [ "object", "null" ] }, "product_id": { "description": "Existing product ID belonging to the account, prefixed `prod_`. Mutually exclusive with `product`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "renewal_price": { "description": "Recurring price in the variant currency.", "type": [ "number", "null" ] }, "title": { "description": "Variant title.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before renewal.", "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers.", "enum": [ null, "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": [ "string", "null" ] } }, "required": [ "currency" ], "type": "object" }, "variant_id": { "description": "An existing variant belonging to the account, identified by its plan_ ID.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" }, "mailing_address_id": { "description": "An address associated with the member. Mutually exclusive with billing_address.", "type": [ "string", "null" ] }, "member_id": { "description": "The billed customer, a member of the account. Changing email recipients does not change this buyer.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Up to 50 caller-owned string key/value pairs.", "example": { "purchase_order": "PO-42" }, "type": "object" }, "payment_method_id": { "description": "A saved payment method belonging to the member, prefixed `payt_`. Sending the invoice emails it now and charges this method on `due_at`, or right away when there is no `due_at` or it has passed. Issuing the invoice without sending it charges right away.", "example": "payt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "recipient_emails": { "description": "Email addresses saved for invoice delivery, independent of the billed customer. Saving them sends no email. Defaults to the customer email when omitted on create. Can be updated on draft, open, or uncollectible invoices.", "items": { "format": "email", "type": "string" }, "maxItems": 50, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "draft updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invoice already issued" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Update Invoice", "tags": [ "Invoices" ] }, "x-whop-surface": "native" }, "/invoices/{id}/generate_pdf": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The invoice's pay_ ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Generates the invoice as a PDF and returns a short-lived link to download it. A draft shows its estimated totals. The buyer's name and email need `member:basic:read` and `member:email:read`, and the Pay now link on an open invoice needs `payment:charge`. Each call generates a new file and link, so this endpoint does not replay `Idempotency-Key` responses.", "operationId": "generateInvoicePdf", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePdf" } } }, "description": "invoice PDF generated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "invoice not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "Generate Invoice PDF", "tags": [ "Invoices" ] }, "x-whop-surface": "native" }, "/invoices/{id}/issue": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The invoice's pay_ ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resolves final tax and opens a draft invoice. An invoice with a `payment_method_id` is then charged to it off-session, as `POST /payments` charges a saved payment method. Issuing an open invoice again retains its totals and charges nothing.", "operationId": "issueInvoice", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "invoice issued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invoice cannot be issued" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "invoice not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Issue Invoice", "tags": [ "Invoices" ] }, "x-whop-surface": "native" }, "/invoices/{id}/mark_uncollectible": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The invoice's pay_ ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Marks an open invoice as uncollectible. Reminders stop, but the customer can still pay it.", "operationId": "markInvoiceUncollectible", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "invoice updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invoice cannot be changed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Mark Invoice Uncollectible", "tags": [ "Invoices" ] }, "x-whop-surface": "native" }, "/invoices/{id}/send": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The invoice's pay_ ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Issues a draft and emails it to its recipients, with reminders after the due date. A draft with a `payment_method_id` needs `payment:charge`: when its `due_at` is still ahead, it is emailed now and charged to that method on `due_at` (see `scheduled_charge_at`); otherwise it is charged right away instead of emailed. Voiding the invoice, marking it uncollectible, or paying it first cancels the scheduled charge, and its recipients get the payment link if a charge fails. Sending an open invoice emails it again, up to three emails a day including the first send. With `send_at`, the draft is sent at that time instead, and cannot be edited, except its recipients, until it is sent or unscheduled. Each email, reminders included, is sent separately to the customer email shown on the invoice and to each address in `recipient_emails`, so recipients never see each other's addresses.", "operationId": "sendInvoice", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "send_at": { "description": "When to send the draft, as an ISO 8601 timestamp in the future. Omit to send now.", "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "invoice sent" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invoice cannot be sent" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Send Invoice", "tags": [ "Invoices" ] }, "x-whop-surface": "native" }, "/invoices/{id}/unschedule": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The invoice's pay_ ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Cancels a draft's scheduled send, so it can be edited again. An invoice with no scheduled send is returned unchanged.", "operationId": "unscheduleInvoice", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "invoice unscheduled" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Cancel Scheduled Send", "tags": [ "Invoices" ] }, "x-whop-surface": "native" }, "/invoices/{id}/void": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The invoice's pay_ ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Voids a draft or unpaid invoice.", "operationId": "voidInvoice", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "invoice updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invoice cannot be changed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Void Invoice", "tags": [ "Invoices" ] }, "x-whop-surface": "native" }, "/leads": { "get": { "description": "Lists an account's leads, newest first.\n\nRequired permissions:\n - `lead:basic:read`\n - `member:email:read`\n - `access_pass:basic:read`\n - `member:basic:read`", "operationId": "listLead", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return leads created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return leads created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "product_ids", "required": false, "schema": { "description": "Filter leads to only those associated with these specific product identifiers.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": "array" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": true, "schema": { "description": "The unique identifier of the company to list leads for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Lead.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/LeadListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "lead:basic:read", "member:email:read", "access_pass:basic:read", "member:basic:read" ] } ], "summary": "List leads", "tags": [ "Leads" ], "x-group-title": "CRM" }, "post": { "description": "Records a lead: a potential customer's interest in an account or one of its products.\n\nRequired permissions:\n - `lead:manage`\n - `member:email:read`\n - `access_pass:basic:read`\n - `member:basic:read`", "operationId": "createLead", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateLeadV2", "properties": { "account_id": { "description": "The unique identifier of the company to create the lead for, starting with 'biz_'.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "A JSON object of custom metadata to attach to the lead for tracking purposes.", "type": [ "object", "null" ] }, "product_id": { "description": "The unique identifier of the product the lead is interested in, starting with 'prod_'.", "example": "prod_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "referrer": { "description": "The referral URL that brought the lead to the company, such as 'https://example.com/landing'.", "type": [ "string", "null" ] }, "user_id": { "description": "The unique identifier of the user to record as the lead. If authenticated as a user, that user is used automatically.", "example": "user_xxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "account_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "lead:manage", "member:email:read", "access_pass:basic:read", "member:basic:read" ] } ], "summary": "Create lead", "tags": [ "Leads" ], "x-group-title": "CRM" } }, "/leads/{id}": { "get": { "description": "Retrieves the details of an existing lead.\n\nRequired permissions:\n - `lead:basic:read`\n - `member:email:read`\n - `access_pass:basic:read`\n - `member:basic:read`", "operationId": "retrieveLead", "parameters": [ { "description": "The unique identifier of the lead to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "lead_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "lead:basic:read", "member:email:read", "access_pass:basic:read", "member:basic:read" ] } ], "summary": "Retrieve lead", "tags": [ "Leads" ], "x-group-title": "CRM" }, "patch": { "description": "Updates a lead's `metadata` or `referrer`.\n\nRequired permissions:\n - `lead:manage`\n - `member:email:read`\n - `access_pass:basic:read`\n - `member:basic:read`", "operationId": "updateLead", "parameters": [ { "description": "The unique identifier of the lead to update, starting with 'lead_'.", "in": "path", "name": "id", "required": true, "schema": { "example": "lead_xxxxxxxxxxxxx", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateLead", "properties": { "metadata": { "additionalProperties": true, "description": "A JSON object of custom metadata to set on the lead, replacing any existing metadata.", "type": [ "object", "null" ] }, "referrer": { "description": "The updated referral URL for the lead, such as 'https://example.com/landing'.", "type": [ "string", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "lead:manage", "member:email:read", "access_pass:basic:read", "member:basic:read" ] } ], "summary": "Update lead", "tags": [ "Leads" ], "x-group-title": "CRM" } }, "/ledger_accounts/{id}": { "get": { "description": "Retrieves the details of an existing ledger account.\n\nRequired permissions:\n - `company:balance:read`\n - `payout:account:read`", "operationId": "retrieveLedgerAccount", "parameters": [ { "description": "The identifier to look up the ledger account. Accepts a user ID ('user_xxx'), company ID ('biz_xxx'), or ledger account ID ('ldgr_xxx').", "in": "path", "name": "id", "required": true, "schema": { "example": "ldgr_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAccount" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "company:balance:read", "payout:account:read" ] } ], "summary": "Retrieve ledger account", "tags": [ "Ledger accounts" ], "x-group-title": "Payouts" } }, "/livestreams": { "get": { "description": "Lists the livestreams in an experience, live and ended, newest first.", "operationId": "listLivestreams", "parameters": [ { "description": "ID of a livestreams experience, prefixed `exp_`.", "in": "query", "name": "experience_id", "required": true, "schema": { "type": "string" } }, { "description": "When `true`, only pinned livestreams, most recently pinned first. When `false`, only livestreams that are not pinned.", "in": "query", "name": "pinned", "required": false, "schema": { "type": "boolean" } }, { "description": "When `true`, only ended livestreams that were recorded, including recordings still processing. `false` or omitted lists every livestream.", "in": "query", "name": "recorded", "required": false, "schema": { "type": "boolean" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Livestream" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "livestreams listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "no access to the experience" }, "404": { "$ref": "#/components/responses/NotFound", "description": "experience not found" } }, "security": [ { "bearerAuth": [ "livestream:chat:read" ] } ], "summary": "List Livestreams", "tags": [ "Livestreams" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/livestreams/{id}": { "get": { "description": "Retrieves a livestream by ID.", "operationId": "retrieveLivestream", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Livestream" } } }, "description": "livestream found" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "no access to the livestream" }, "404": { "$ref": "#/components/responses/NotFound", "description": "livestream not found" } }, "security": [ { "bearerAuth": [ "livestream:chat:read" ] } ], "summary": "Retrieve Livestream", "tags": [ "Livestreams" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Livestream ID, prefixed `lfeed_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/livestreams/{id}/pin": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Livestream ID, prefixed `lfeed_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pins an ended livestream's recording so everyone in the experience sees it featured. Pinning it again keeps the original `pinned_at`.", "operationId": "pinLivestream", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Livestream" } } }, "description": "livestream pinned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "livestream has not ended" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing the `livestream:moderate` permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "livestream not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "livestream:moderate" ] } ], "summary": "Pin Livestream", "tags": [ "Livestreams" ] }, "x-whop-surface": "native" }, "/livestreams/{id}/unpin": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Livestream ID, prefixed `lfeed_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Unpins a livestream's recording so it is no longer featured in the experience.", "operationId": "unpinLivestream", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Livestream" } } }, "description": "livestream unpinned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing the `livestream:moderate` permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "livestream not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "livestream:moderate" ] } ], "summary": "Unpin Livestream", "tags": [ "Livestreams" ] }, "x-whop-surface": "native" }, "/media/generate": { "post": { "description": "Starts an AI media generation job billed from the account's balance. Generation is asynchronous — poll `GET /media/{id}` until the asset is `ready`, then use `file.id` anywhere attachments are accepted.", "operationId": "generateMediaAsset", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID, prefixed `biz_`. Defaults to the account the API key belongs to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "duration_seconds": { "description": "Video length in seconds. Video only; defaults to 5.", "enum": [ 5, 10, 15 ], "example": 5, "type": "integer" }, "prompt": { "description": "What to generate. Up to 2,000 characters.", "example": "A 9:16 product showcase of a cordless power scrubber", "type": "string" }, "reference_media": { "description": "Optional reference image file IDs (`file_` prefixed), up to 4. For video, a single reference seeds the opening frame; multiple references guide subject and style instead.", "items": { "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "resolution": { "description": "Video resolution. Video only; defaults to `1080p`. `1080p` is not supported by Seedance 2.0 Fast or Mini; `4k` is only supported by Seedance 2.0.", "enum": [ "480p", "720p", "1080p", "4k" ], "example": "1080p", "type": "string" }, "type": { "description": "The kind of media to generate.", "enum": [ "video", "image" ], "example": "video", "type": "string" } }, "required": [ "type", "prompt" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsset" } } }, "description": "Generation started." }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "message": { "example": "duration_seconds is only valid for video generations", "type": "string" }, "type": { "example": "bad_request", "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid generation parameters." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "deposit_url": { "description": "Hosted page where the account can deposit funds before retrying.", "example": "https://whop.com/deposit/biz_xxxxxxxxxxxxxx/", "type": "string" }, "message": { "example": "Insufficient balance to fund this generation. Deposit funds and retry.", "type": "string" }, "type": { "enum": [ "payment_required" ], "example": "payment_required", "type": "string" } }, "required": [ "type", "message", "deposit_url" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Insufficient balance." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Missing the media:generate scope." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "media:generate" ] } ], "summary": "Generate Media Asset", "tags": [ "Media" ] }, "x-whop-surface": "native" }, "/media/{id}": { "get": { "description": "Retrieves a media asset by ID. Poll this while the asset is `processing`.", "operationId": "retrieveMediaAsset", "parameters": [ { "description": "Media asset ID, prefixed `media_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaAsset" } } }, "description": "Media asset retrieved." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Unknown media asset, including generation jobs not created through this API." } }, "security": [ { "bearerAuth": [ "media:read" ] } ], "summary": "Retrieve Media Asset", "tags": [ "Media" ] }, "x-whop-surface": "native" }, "/members": { "get": { "description": "Lists the members of an account. A member is one buyer's relationship with the account, regardless of how many memberships they hold.", "operationId": "listMembers", "parameters": [ { "description": "The account to list members for (`biz_` tag). Defaults to the account the credential acts as.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by what the member can reach on the account.", "in": "query", "name": "access_level", "required": false, "schema": { "enum": [ "no_access", "admin", "customer" ], "type": "string" } }, { "description": "Filter by whether the member is still part of the account.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "joined", "left" ], "type": "string" } }, { "description": "Only return members whose users match these `user_` identifiers.", "in": "query", "name": "user_ids", "required": false, "schema": { "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return members whose `most_recent_action` is one of these values.", "in": "query", "name": "most_recent_actions", "required": false, "schema": { "items": { "enum": [ "canceling", "churned", "finished_split_pay", "paused", "paid_subscriber", "paid_once", "expiring", "joined", "left", "trialing", "pending_entry", "renewing", "past_due" ], "type": "string" }, "type": "array" } }, { "description": "`active` returns members holding at least one membership that currently grants access; `inactive` returns members holding at least one membership that does not. Combined with `product_ids`, `variant_ids`, or `promo_code_ids`, one membership must match all of them.", "in": "query", "name": "membership_status", "required": false, "schema": { "enum": [ "active", "inactive" ], "type": "string" } }, { "description": "Only return members holding a membership to one of these products, prefixed `prod_`. Unknown IDs match nothing.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return members holding a membership on one of these variants, prefixed `plan_`. Unknown IDs match nothing.", "in": "query", "name": "variant_ids", "required": false, "schema": { "items": { "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return members holding a membership bought with one of these promo codes, prefixed `promo_`. Unknown IDs match nothing.", "in": "query", "name": "promo_code_ids", "required": false, "schema": { "items": { "example": "promo_xxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Search members by name or username. An exact email address also matches when the credential holds the member:email:read scope.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only members who joined after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only members who joined before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field. `most_recent_action_at` places members without one first when ascending and last when descending.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "joined_at", "last_accessed_at", "most_recent_action_at", "usd_total_spent" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Member" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "members listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid access_level filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the member-read scope" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "List Members", "tags": [ "Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/members/{id}": { "get": { "description": "Retrieves a member by ID. Accessible to the account and to the member's own user.", "operationId": "retrieveMember", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } }, "description": "the stamped number outranks the consented account read" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks access to the member's account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown member" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "Retrieve Member", "tags": [ "Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Member ID (`mber_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/members/{id}/logs": { "get": { "description": "Lists activity for a member and all of their memberships that are not `drafted`, most recent first.", "operationId": "listMemberLogs", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "action": { "example": "Membership activated", "type": [ "string", "null" ] }, "actor": { "properties": { "id": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "action", "created_at", "actor" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "member logs listed" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks access to the member's account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown member" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "List Member Logs", "tags": [ "Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Member ID (`mber_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/members/{member_id}/notes": { "get": { "description": "Lists a member's notes, newest first. Notes are visible to the account's team.", "operationId": "listMemberNotes", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MemberNote" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "member notes listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the member-read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown member" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "List Member Notes", "tags": [ "Members" ], "x-whop-docs-subgroup": "Notes" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The member the notes are about, prefixed `mber_`.", "in": "path", "name": "member_id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Adds a note to a member. Notes are visible to the account's team.", "operationId": "createMemberNote", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "description": "The note text.", "example": "Wants a call next week.", "type": "string" } }, "required": [ "content" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberNote" } } }, "description": "member note created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing content" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the member-manage scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown member" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Create Member Note", "tags": [ "Members" ], "x-whop-docs-subgroup": "Notes" }, "x-whop-surface": "native" }, "/memberships": { "get": { "description": "Lists every membership the caller can read: an account API key its account's; a user credential their own plus those of every account they manage. `account_id` and `user_id` only narrow that list — values outside the caller's reach return fewer results, not an error.", "operationId": "listMemberships", "parameters": [ { "description": "Narrow to one account (`biz_` tag). With read access to the account this lists all of its memberships; without, only the caller's own memberships in it.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Narrow to one user's memberships (`user_` tag, or `me` for the caller). A user outside the caller's visible set returns an empty list.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Narrow to one member's memberships (`mber_` tag), including memberships bought by another business. A member outside the caller's visible set returns an empty list.", "in": "query", "name": "member_id", "required": false, "schema": { "type": "string" } }, { "description": "Narrow to memberships linked to one Discord or Telegram account, given as the platform's user ID prefixed with `discord_` or `telegram_`. Discord matches include memberships imported with that Discord ID. Any other format is a 400.", "in": "query", "name": "external_account", "required": false, "schema": { "example": "discord_123456789012345678", "type": "string" } }, { "description": "Filter by billing state. `trialing`, `active`, `past_due`, `completed`, `canceled`, and `expired` match the membership's `status`; `active`, `trialing`, and `past_due` exclude memberships set to cancel at period end. The other values are derived buckets that never appear as a `status`: `canceling` matches memberships set to cancel at period end; `paused` matches memberships with payment collection paused; `expiring` matches one-time purchases that have not yet expired; `one_time` matches one-time purchases that never expire; `unclaimed` matches memberships with no buyer user, including memberships bought by another business; `banned` matches memberships whose buyer is banned from the account.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "trialing", "past_due", "completed", "canceled", "expired", "canceling", "paused", "expiring", "one_time", "unclaimed", "banned" ], "type": "string" } }, { "description": "Filter to memberships matching any of these billing states, with the same meanings as `status`. Repeat the parameter to pass several. Combined with `status` when both are sent.", "in": "query", "name": "statuses", "required": false, "schema": { "items": { "enum": [ "active", "trialing", "past_due", "completed", "canceled", "expired", "canceling", "paused", "expiring", "one_time", "unclaimed", "banned" ], "example": "canceled", "type": "string" }, "type": "array" } }, { "description": "Filter to memberships of this product (`prod_` tag).", "in": "query", "name": "product_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to memberships of any of these products, each prefixed `prod_`. Repeat the parameter to pass several.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Filter to memberships of this variant (`plan_` tag).", "in": "query", "name": "variant_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to memberships of any of these variants, each prefixed `plan_`. Repeat the parameter to pass several.", "in": "query", "name": "variant_ids", "required": false, "schema": { "items": { "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Filter to memberships discounted by any of these promo codes, each prefixed `promo_`. Repeat the parameter to pass several.", "in": "query", "name": "promo_code_ids", "required": false, "schema": { "items": { "example": "promo_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only memberships created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only memberships created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Membership" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "memberships listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account_id" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "List Memberships", "tags": [ "Memberships" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/memberships/invite": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Emails one recipient an invitation to a free variant's membership. The invitation is bound to that recipient; after signing in, accepting it immediately grants the membership without checkout. This Experimental endpoint is available only to accounts enabled for membership invitations.", "operationId": "inviteMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "user_id": { "description": "Recipient user ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "variant_id": { "description": "Free variant whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "variant_id", "user_id" ], "title": "InviteMembershipByUser", "type": "object" }, { "properties": { "email": { "description": "Recipient email address.", "example": "marcus@shinetime.example", "format": "email", "type": "string" }, "variant_id": { "description": "Free variant whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "variant_id", "email" ], "title": "InviteMembershipByEmail", "type": "object" } ], "properties": { "email": { "description": "Recipient email address. Pass exactly one of `user_id` or `email`.", "example": "marcus@shinetime.example", "format": "email", "type": "string" }, "user_id": { "description": "Recipient user ID, prefixed `user_`. Pass exactly one of `user_id` or `email`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "variant_id": { "description": "Free variant whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "variant_id" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "invitation_sent": { "example": true, "type": "boolean" } }, "required": [ "invitation_sent" ], "type": "object" } } }, "description": "invitation accepted for delivery" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid recipient" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the create scope or account is not enabled" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown plan" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "membership:create" ] } ], "summary": "Invite to a Membership", "tags": [ "Memberships" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "x-whop-surface": "native" }, "/memberships/{id}": { "get": { "description": "Retrieves a membership by ID or license key. Accessible to the account and to the membership's own user.", "operationId": "retrieveMembership", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership retrieved with its recorded phone number" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks access to the membership" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown membership" } }, "security": [ { "bearerAuth": [ "member:basic:read" ] } ], "summary": "Retrieve Membership", "tags": [ "Memberships" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag), or a software license key.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a membership's metadata, scheduled cancellation, renewal payment method, or renewal cadence.", "operationId": "updateMembership", "parameters": [], "requestBody": { "content": { "application/json": { "examples": { "billing_period_days": { "summary": "Update Membership", "value": { "billing_period_days": 45 } } }, "schema": { "example": { "billing_period_days": 45 }, "minProperties": 1, "not": { "anyOf": [ { "required": [ "billing_period_days", "cancel_at_period_end" ] }, { "required": [ "billing_period_days", "metadata" ] }, { "required": [ "billing_period_days", "payment_method_id" ] } ] }, "properties": { "billing_period_days": { "description": "Number of days between recurring charges. Sets the current period end to the current period start plus this value and applies to every recurring variant, so future renewals use the same cadence. The new period end must remain in the future. Only for active, trialing, or past-due memberships billed automatically by Whop; invoice, externally billed, and canceling memberships are not supported. Existing non-daily memberships cannot be changed to daily billing. Cannot be combined with other fields.", "example": 45, "maximum": 365, "minimum": 1, "type": "integer" }, "cancel_at_period_end": { "description": "`true` cancels at the end of the current billing period (the customer keeps access until then); `false` reverses a pending cancellation.", "example": true, "type": "boolean" }, "metadata": { "description": "Key-value pairs to merge into the membership's metadata. Pass an empty object to clear it.", "example": { "seat": "42" }, "type": "object" }, "payment_method_id": { "description": "The ID of a payment method the customer has saved with your account. Future renewals charge it, and an open past-due payment is retried on it right away. Requires the `member:payment_methods:manage` permission.", "example": "payt_xxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "no updatable fields given" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" } }, "security": [ { "bearerAuth": [ "member:manage" ] }, { "bearerAuth": [ "membership:cancel" ] }, { "bearerAuth": [ "member:payment_methods:manage" ] } ], "summary": "Update Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/apply_promo_code": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Applies a promo code to an `active` or `trialing` membership that does not already have one and has exactly one recurring item, for Stripe-billed memberships and memberships billed by Whop's billing engine. The discount lands on the next invoice and follows the code's duration (`once`, `repeating`, or `forever`).", "operationId": "applyPromoCodeMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "promo_code": { "description": "The promo code to apply, as customers enter it at checkout (for example `SAVE20`). Its stock, variant eligibility, and expiry are checked as at checkout.", "example": "SAVE20", "type": "string" } }, "required": [ "promo_code" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "promo code applied" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "promo code cannot be applied" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Apply Promo Code to Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/assign_affiliate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Assigns an affiliate to a membership and pays them the commission you set on its future payments; past payments are not recalculated. A user who is not yet an affiliate of your account becomes one, which also requires `affiliate:create`. Send a new `commission_type` or `commission_value` for the membership's current affiliate to change their commission; a membership that already has a different affiliate returns a conflict. Works for active or trialing memberships with one recurring variant that bill through Stripe or Whop's billing engine, and not for marketplace memberships, paused payments, or a scheduled cancellation. You cannot assign yourself.", "operationId": "assignAffiliateMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "examples": { "flat_fee": { "summary": "Assign a flat fee commission", "value": { "commission_type": "flat_fee", "commission_value": 5, "email": "affiliate@example.com" } }, "percentage": { "summary": "Assign a percentage commission", "value": { "commission_type": "percentage", "commission_value": 20, "user_id": "user_xxxxxxxxxxxxx" } } }, "schema": { "properties": { "commission_type": { "description": "Whether the commission is a percentage of each payment or a fixed amount per payment.", "enum": [ "flat_fee", "percentage" ], "example": "percentage", "type": "string" }, "commission_value": { "description": "A whole number from 1 to 90 for `percentage`, or an amount greater than 1 in the membership currency for `flat_fee`. The payout cannot exceed 90% of the next renewal amount. Flat fees need matching billing and settlement currencies.", "example": 20, "type": "number" }, "email": { "description": "Email address of the user to assign. Pass exactly one of `user_id`, `email`, or `username`.", "example": "affiliate@example.com", "type": "string" }, "user_id": { "description": "The user to assign, prefixed `user_`. Pass exactly one of `user_id`, `email`, or `username`.", "example": "user_xxxxxxxxxxxxx", "type": "string" }, "username": { "description": "Whop username of the user to assign. Pass exactly one of `user_id`, `email`, or `username`.", "example": "affiliate", "type": "string" } }, "required": [ "commission_type", "commission_value" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "affiliate assigned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the commission or the way the user is named is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage or affiliate scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "membership or user not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "the membership already has a different affiliate or is being edited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable", "description": "the upcoming invoice could not be retrieved, so nothing was saved" } }, "security": [ { "bearerAuth": [ "member:manage", "affiliate:update" ] } ], "summary": "Assign Affiliate to Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Cancels a membership, either immediately or at the end of the current billing period. Buyers cannot cancel buy-now-pay-later (`splitit`, `sezzle`) or non-trial split-pay memberships.", "operationId": "cancelMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cancel_at_period_end": { "description": "`true` stops auto-renewal and keeps access until the current billing period ends. Omit or `false` revokes access immediately.", "example": true, "type": "boolean" }, "feedback_option_id": { "description": "The ID of the feedback option the customer picked as their reason for canceling, from the account's `feedback_options` preference. The membership records the option's label as the customer saw it and its category as `cancel_option`.", "example": "fo_xxxxxxxxxxxxxxxx", "type": "string" }, "reason": { "description": "Free-form note recording why the membership was canceled.", "example": "chargeback risk", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership canceled" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the cancel scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown membership" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "membership:cancel" ] }, { "bearerAuth": [ "member:manage" ] } ], "summary": "Cancel Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/extend": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Adds free days to a membership, extending its current billing period, expiration date, or trial depending on the plan type.", "operationId": "extendMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "days": { "description": "Number of free days to add (1-1095).", "example": 7, "minimum": 1, "type": "integer" } }, "required": [ "days" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership extended" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "days is not a positive integer" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Extend Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pauses a membership's recurring payment collection. The customer keeps access but is not charged until the membership is resumed.", "operationId": "pauseMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "until": { "description": "ISO 8601 time to automatically resume payment collection. Must be in the future; only supported for memberships billed by Whop.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership paused" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "until on a membership not billed by Whop" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Pause Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/reactivate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Restores access to a `canceled` or `expired` membership that contains only one-time purchases and sets its `status` to `completed`. Lifetime memberships regain lifetime access; for memberships with an expiration, `days` sets the new `current_period_end`. Active and recurring memberships cannot be reactivated.", "operationId": "reactivateMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "days": { "description": "Days of access from now (1-1095), which sets `current_period_end`. Omit to keep the original `current_period_end`; required once it has passed. Ignored for lifetime memberships.", "example": 10, "maximum": 1095, "minimum": 1, "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership reactivated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "membership cannot be reactivated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "membership not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "membership is being updated by another request" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Reactivate Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/resume": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resumes a previously paused membership's recurring payment collection. Billing resumes on the next cycle.", "operationId": "resumeMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "membership resumed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "membership cannot be resumed" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the manage scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "member:manage" ] } ], "summary": "Resume Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/resync_access": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Re-runs access fulfillment for a membership: recomputes the member's content access on Whop, re-validates their Discord link (re-adding them to the server and re-assigning roles if needed), and re-fulfills TradingView indicator access. Telegram access is invite-based and is not resynced. The work runs in the background and the outcome is written to the membership's logs.", "operationId": "resyncAccessMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } }, "description": "access resync queued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "membership has no access to resync" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the resync scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "membership:resync_access" ] } ], "summary": "Resync Membership Access", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/memberships/{id}/transfer": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Membership ID (`mem_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Creates a one-use transfer URL for a membership. Opening the URL while logged into a different Whop account claims the membership onto that account. The membership's buyer can generate a link for their own membership with `membership:transfer` when the product allows transfers and the membership is `trialing`, `active`, or `completed`. An account credential with `membership:update` bypasses both restrictions.", "operationId": "transferMembership", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "url": { "description": "One-use URL the destination account opens to claim the membership.", "example": "https://whop.com/activate", "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "description": "transfer URL created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "membership is not transferable in its current state" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the transfer scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown membership" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "membership:transfer" ] }, { "bearerAuth": [ "membership:update" ] } ], "summary": "Transfer Membership", "tags": [ "Memberships" ] }, "x-whop-surface": "native" }, "/messages": { "get": { "description": "Lists messages in an experience chat, DM, or group chat channel, sorted by creation time.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `support_chat:read`", "operationId": "listMessage", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "channel_id", "required": true, "schema": { "description": "The unique identifier of the channel or experience to list messages for.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for messages by creation time. Use 'asc' for oldest first or 'desc' for newest first." }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DmsPost.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/MessageListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "List messages", "tags": [ "Messages" ], "x-group-title": "Engagement" }, "post": { "description": "Sends a message in an experience chat, DM, or group chat channel. Supports text content, attachments, polls, and replies.\n\nRequired permissions (one of):\n - `chat:message:create`\n - `dms:message:manage`\n - `livestream:chat:write`\n - `support_chat:message:create`", "operationId": "createMessage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateMessage", "properties": { "attachments": { "description": "A list of file attachments to include with the message, such as images or videos.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "auto_detect_links": { "description": "Automatically detect URLs in the message and generate link previews.", "type": [ "boolean", "null" ] }, "channel_id": { "description": "The unique identifier of the channel or experience to send the message in. For example, 'exp_xxxxx' or 'feed_xxxxx'.", "type": "string" }, "content": { "description": "The body of the message in Markdown format. For example, 'Hello **world**'.", "type": "string" }, "poll": { "description": "A poll to attach to this message, allowing recipients to vote on options.", "properties": { "options": { "description": "The options for the poll. Must have sequential IDs starting from 1", "items": { "description": "Input type for a single poll option", "properties": { "id": { "description": "Sequential ID for the poll option (starting from '1')", "type": "string" }, "text": { "description": "The text of the poll option", "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "type": "array" } }, "required": [ "options" ], "type": [ "object", "null" ] }, "replying_to_message_id": { "description": "The unique identifier of the message this is replying to, creating a threaded reply.", "type": [ "string", "null" ] } }, "required": [ "channel_id", "content" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:message:create" ] }, { "bearerAuth": [ "dms:message:manage" ] }, { "bearerAuth": [ "livestream:chat:write" ] }, { "bearerAuth": [ "support_chat:message:create" ] } ], "summary": "Create message", "tags": [ "Messages" ], "x-group-title": "Engagement" } }, "/messages/{id}": { "delete": { "description": "Permanently deletes a message from an experience chat, DM, or group chat channel. Only the message author or a channel admin can delete a message.\n\nRequired permissions (one of):\n - `chat:message:create` and `chat:read`\n - `dms:message:manage` and `dms:read`\n - `livestream:chat:write` and `livestream:chat:read`\n - `support_chat:message:create` and `support_chat:read`", "operationId": "deleteMessage", "parameters": [ { "description": "The unique identifier of the message to delete.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:message:create", "chat:read" ] }, { "bearerAuth": [ "dms:message:manage", "dms:read" ] }, { "bearerAuth": [ "livestream:chat:write", "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:message:create", "support_chat:read" ] } ], "summary": "Delete message", "tags": [ "Messages" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing message.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `livestream:chat:read`\n - `support_chat:read`", "operationId": "retrieveMessage", "parameters": [ { "description": "The unique identifier of the message to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Retrieve message", "tags": [ "Messages" ], "x-group-title": "Engagement" }, "patch": { "description": "Edits the content, attachments, or pinned status of a message in an experience chat, DM, or group chat channel.\n\nRequired permissions (one of):\n - `chat:message:create`\n - `dms:message:manage`\n - `livestream:chat:write`\n - `support_chat:message:create`", "operationId": "updateMessage", "parameters": [ { "description": "The unique identifier of the message to update.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for UpdateMessage", "properties": { "attachments": { "description": "A replacement list of file attachments for this message, such as images or videos.", "items": { "description": "Input for an attachment", "properties": { "id": { "description": "The ID of an existing file object.", "type": "string" } }, "required": [ "id" ], "title": "FileInputWithId", "type": "object" }, "type": [ "array", "null" ] }, "content": { "description": "The updated body of the message in Markdown format. For example, 'Hello **world**'.", "type": [ "string", "null" ] }, "is_pinned": { "description": "Whether this message should be pinned to the top of the channel.", "type": [ "boolean", "null" ] } }, "required": [], "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:message:create" ] }, { "bearerAuth": [ "dms:message:manage" ] }, { "bearerAuth": [ "livestream:chat:write" ] }, { "bearerAuth": [ "support_chat:message:create" ] } ], "summary": "Update message", "tags": [ "Messages" ], "x-group-title": "Engagement" } }, "/notifications": { "get": { "description": "Lists the authenticated user's notifications, newest first. Without filters the feed spans every experience the user belongs to plus the teams they are a member of. Requires a user credential — an account API key has no notification feed.", "operationId": "listNotifications", "parameters": [ { "description": "Only return notifications created since the user last viewed their source.", "in": "query", "name": "unread", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return notifications from this experience (`exp_` tag).", "in": "query", "name": "experience_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return team notifications for this account (`biz_` tag).", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return notifications that mention the user directly.", "in": "query", "name": "mentions", "required": false, "schema": { "type": "boolean" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Notification" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "ntfr_xxxxxxxxxxxxxx:xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "ntfr_xxxxxxxxxxxxxx:xxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "notifications listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid cursor" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account API key instead of a user credential" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "List Notifications", "tags": [ "Notifications" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Queues a notification to every user of an experience or to an account's team, processed asynchronously. Every send is attributed to an app: use an app API key, or a credential acting on behalf of an app. Narrow the audience with `user_ids` to send a mention.", "operationId": "sendNotification", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account whose team members receive the notification (`biz_` tag). Exactly one of `experience_id` or `account_id` is required.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "content": { "description": "Main body text of the notification.", "example": "Drop off at 4180 Burnet Rd. Plan on two days for the full coating.", "type": "string" }, "experience_id": { "description": "Experience whose users receive the notification (`exp_` tag). Exactly one of `experience_id` or `account_id` is required.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "icon_user_id": { "description": "User whose profile picture is used as the notification icon. Defaults to the experience or account avatar.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "rest_path": { "description": "Path segment appended to the generated deep link that opens your app, for example `/settings/billing`.", "example": "/bookings/upcoming", "type": [ "string", "null" ] }, "subtitle": { "description": "Optional secondary line displayed below the title.", "example": "Tuesday 9:00 AM, Bay 2", "type": [ "string", "null" ] }, "title": { "description": "Headline text of the notification.", "example": "Your ceramic coating is booked", "type": "string" }, "user_ids": { "description": "Optional `user_` tags narrowing the audience. When provided, only these users are notified (as a mention), provided they are in the targeted experience or account.", "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "title", "content" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "notification queued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "both targets provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential is not attributed to an app" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] }, { "bearerAuth": [ "notification:create" ] } ], "summary": "Send Notification", "tags": [ "Notifications" ], "x-whop-credentials": [ "app_api_key" ] }, "x-whop-surface": "native" }, "/notifications/badges": { "get": { "description": "Lists the authenticated user's per-experience unread badge state. Requires a user credential. Returns one row per experience the user belongs to (or per requested experience).", "operationId": "listNotificationBadges", "parameters": [ { "description": "Only return badges for these experiences (`exp_` tags).", "in": "query", "name": "experience_ids", "required": false, "schema": { "items": { "example": "exp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "The client's last fetched-at ISO 8601 timestamp, used to partially refresh badges after a websocket message.", "in": "query", "name": "last_fetched_at", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NotificationBadge" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "badges listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account API key instead of a user credential" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "List Notification Badges", "tags": [ "Notifications" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/notifications/mark_read": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Marks the authenticated user's notifications as read, for one experience or all of them, and returns the refreshed badge rows for that scope. Requires a user credential.", "operationId": "markNotificationsRead", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "all": { "description": "Pass `true` to mark every notification read. Exactly one of `experience_id` or `all` is required.", "example": true, "type": "boolean" }, "experience_id": { "description": "Experience to mark read (`exp_` tag). Exactly one of `experience_id` or `all` is required.", "example": "exp_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NotificationBadge" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "notifications marked read" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither or both selectors provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "account API key instead of a user credential" }, "404": { "$ref": "#/components/responses/NotFound", "description": "experience does not exist" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "user:notifications:update" ] } ], "summary": "Mark Notifications Read", "tags": [ "Notifications" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/notifications/topics": { "get": { "description": "Lists the platform's visible notification topics — the categories users can set notification preferences on. App-created topics are not returned.", "operationId": "listNotificationTopics", "parameters": [ { "description": "Only return topics of this scope: `user` (member notifications) or `account_team` (team notifications).", "in": "query", "name": "topic_type", "required": false, "schema": { "enum": [ "user", "account_team" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NotificationTopic" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "notification topics listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid topic_type" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Notification Topics", "tags": [ "Notifications" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/notifications/{id}": { "get": { "description": "Retrieves a single notification, from the feed or from a push or websocket event. Requires a user credential.", "operationId": "retrieveNotification", "parameters": [ { "description": "A notification `id` from List Notifications, or the ephemeral id delivered with a push or websocket event.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } }, "description": "notification found" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "notification expired or not visible to the user" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "Retrieve Notification", "tags": [ "Notifications" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/partner_referral_requests": { "get": { "description": "Lists your referral links and attribution requests, including incoming requests for you or businesses you own, with filters for recipient, partner, type, and status.", "operationId": "listPartnerReferralRequests", "parameters": [ { "description": "Only requests for this business ID, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only requests received by this user ID, prefixed `user_`.", "in": "query", "name": "target_user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only requests sent by this partner's user ID, prefixed `user_`.", "in": "query", "name": "partner_id", "required": false, "schema": { "type": "string" } }, { "description": "Only requests with this approval status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "accepted", "denied", "cancelled" ], "type": "string" } }, { "description": "Only requests initiated in this way.", "in": "query", "name": "request_type", "required": false, "schema": { "enum": [ "manual", "ownership_transfer", "link" ], "type": "string" } }, { "description": "Field used to sort requests.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PartnerReferralRequest" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Requests listed." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid filter." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication is required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "An API key without read permission cannot list requests." } }, "security": [ { "bearerAuth": [ "partner:referral_request:read" ] } ], "summary": "List partner referral requests", "tags": [ "Partner Referral Requests" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a referral link, or sends an attribution request to an existing business or user for approval. Links require an enrolled partner who is not suspended; attribution requests require an enrolled, verified partner. Recipients do not need to join the partner program.", "operationId": "createPartnerReferralRequest", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "account_id": { "description": "Business to request attribution for, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "authorized_user_id": { "description": "Your team membership on the business this referral is made for, prefixed `ausr_`. Omit for a personal referral.", "type": "string" }, "member_id": { "description": "Your member record on the business this referral is made for, prefixed `mber_`, when your role there is held on your member record. Send this or `authorized_user_id`, not both.", "type": "string" } }, "required": [ "account_id" ], "type": "object" }, { "properties": { "account_url": { "description": "HTTP or HTTPS Whop business or product link.", "example": "https://whop.com/manual-request-business/", "type": "string" }, "authorized_user_id": { "description": "Your team membership on the business this referral is made for, prefixed `ausr_`. Omit for a personal referral.", "type": "string" }, "member_id": { "description": "Your member record on the business this referral is made for, prefixed `mber_`, when your role there is held on your member record. Send this or `authorized_user_id`, not both.", "type": "string" } }, "required": [ "account_url" ], "type": "object" }, { "properties": { "authorized_user_id": { "description": "Your team membership on the business this referral is made for, prefixed `ausr_`. Omit for a personal referral.", "type": "string" }, "member_id": { "description": "Your member record on the business this referral is made for, prefixed `mber_`, when your role there is held on your member record. Send this or `authorized_user_id`, not both.", "type": "string" }, "target_user_id": { "description": "User to request attribution for, prefixed `user_`.", "type": "string" } }, "required": [ "target_user_id" ], "type": "object" }, { "properties": { "authorized_user_id": { "description": "Your team membership on the business this referral is made for, prefixed `ausr_`. Omit for a personal referral.", "type": "string" }, "member_id": { "description": "Your member record on the business this referral is made for, prefixed `mber_`, when your role there is held on your member record. Send this or `authorized_user_id`, not both.", "type": "string" }, "target_username": { "description": "Username of the user to request attribution for, with or without a leading @.", "type": "string" } }, "required": [ "target_username" ], "type": "object" }, { "properties": { "authorized_user_id": { "description": "Your team membership on the business this referral is made for, prefixed `ausr_`. Omit for a personal referral.", "type": "string" }, "member_id": { "description": "Your member record on the business this referral is made for, prefixed `mber_`, when your role there is held on your member record. Send this or `authorized_user_id`, not both.", "type": "string" }, "target_email": { "description": "Email address on an existing user's account. Matching is case-insensitive. The user does not need to be enrolled in the partner program.", "format": "email", "type": "string" } }, "required": [ "target_email" ], "type": "object" }, { "additionalProperties": false, "description": "Create your own referral link with an optional custom code and redemption limit. Without configuration, returns your oldest saved link for the selected team membership, or your personal context when `authorized_user_id` is omitted, creating a random code when none exists.", "properties": { "authorized_user_id": { "description": "The partner's team membership on the business this link is made for, prefixed `ausr_`. Omit for a personal link.", "type": "string" }, "code": { "description": "Case-insensitive referral code containing letters, numbers, and single hyphens. New codes are stored in lowercase. Omit to generate six random letters, or reuse a saved link when no configuration is supplied.", "example": "QJMTXR", "maxLength": 64, "pattern": "^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$", "type": "string" }, "max_redemptions": { "description": "Maximum permitted redemptions, or null for no configured limit.", "example": 10, "maximum": 2147483647, "minimum": 1, "type": [ "integer", "null" ] }, "member_id": { "description": "The partner's member record on the business this link is made for, prefixed `mber_`, when their role there is held on their member record. Send this or `authorized_user_id`, not both.", "type": "string" }, "partner_id": { "description": "Optional. Your own partner ID, prefixed `user_`; you cannot create a link for another partner.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "request_type": { "description": "Create or retrieve a reusable referral link without requesting attribution for an existing business.", "enum": [ "link" ], "example": "link", "type": "string" } }, "required": [ "request_type" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerReferralRequest" } } }, "description": "Existing request or referral link returned." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerReferralRequest" } } }, "description": "Request created." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid account ID." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication is required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "The partner is not eligible." }, "404": { "$ref": "#/components/responses/NotFound", "description": "The business was not found." }, "409": { "$ref": "#/components/responses/Conflict", "description": "The business already has a partner." } }, "security": [ { "bearerAuth": [ "partner:referral_request:create" ] } ], "summary": "Create a partner referral request", "tags": [ "Partner Referral Requests" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "x-whop-surface": "native" }, "/partner_referral_requests/{id}": { "get": { "description": "Retrieves a referral link or attribution request by ID, including its partner, recipient, approval status, and referral code when present.", "operationId": "retrievePartnerReferralRequest", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerReferralRequest" } } }, "description": "Request retrieved." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication is required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "An API key without read permission cannot retrieve a request." }, "404": { "$ref": "#/components/responses/NotFound", "description": "The request is not visible to this user." } }, "security": [ { "bearerAuth": [ "partner:referral_request:read" ] } ], "summary": "Retrieve a partner referral request", "tags": [ "Partner Referral Requests" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Partner referral request ID, prefixed `prfr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/partner_referral_requests/{id}/accept": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Partner referral request ID, prefixed `prfr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Accepts a pending attribution request as the receiving user or business owner, assigning the requesting partner as that user's or business's referrer.", "operationId": "acceptPartnerReferralRequest", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerReferralRequest" } } }, "description": "Request resolved." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication is required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "The user cannot perform this action." }, "404": { "$ref": "#/components/responses/NotFound", "description": "The request is not visible to this user." }, "409": { "$ref": "#/components/responses/Conflict", "description": "The request was resolved differently." } }, "security": [ { "bearerAuth": [ "partner:referral_request:accept" ] } ], "summary": "Accept a partner referral request", "tags": [ "Partner Referral Requests" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "x-whop-surface": "native" }, "/partner_referral_requests/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Partner referral request ID, prefixed `prfr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Cancels a pending attribution request you sent so the recipient can no longer accept it, and returns the cancelled request.", "operationId": "cancelPartnerReferralRequest", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerReferralRequest" } } }, "description": "Request resolved." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication is required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "The user cannot perform this action." }, "404": { "$ref": "#/components/responses/NotFound", "description": "The request is not visible to this user." }, "409": { "$ref": "#/components/responses/Conflict", "description": "The request was resolved differently." } }, "security": [ { "bearerAuth": [ "partner:referral_request:cancel" ] } ], "summary": "Cancel a partner referral request", "tags": [ "Partner Referral Requests" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "x-whop-surface": "native" }, "/partner_referral_requests/{id}/decline": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Partner referral request ID, prefixed `prfr_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Declines a pending attribution request for you or a business you own, marking it as denied without assigning the requesting partner as a referrer.", "operationId": "declinePartnerReferralRequest", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerReferralRequest" } } }, "description": "Request resolved." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Authentication is required." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "The user cannot perform this action." }, "404": { "$ref": "#/components/responses/NotFound", "description": "The request is not visible to this user." }, "409": { "$ref": "#/components/responses/Conflict", "description": "The request was resolved differently." } }, "security": [ { "bearerAuth": [ "partner:referral_request:decline" ] } ], "summary": "Decline a partner referral request", "tags": [ "Partner Referral Requests" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "x-whop-surface": "native" }, "/partners": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Enrolls the calling user in the Whop partner program, making their partner businesses eligible for earnings. Idempotent — enrolling again keeps the original enrollment time.", "operationId": "createReferralPartner", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "referral_link": { "description": "The caller's referral link — businesses that sign up through it are attributed to the caller.", "example": "https://whop.com/network/", "type": "string" }, "whop_partner_enabled_at": { "description": "When the caller became a Whop partner.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "whop_partner_enabled_at", "referral_link" ], "type": "object" } } }, "description": "enrolled" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the partner-create scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "partner:create" ] } ], "summary": "Enroll as a Whop partner", "tags": [ "Partners" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/partners/businesses": { "get": { "description": "Lists the businesses the authenticated user referred onto Whop, most recent first.", "operationId": "listPartnerBusinesses", "parameters": [ { "description": "List the referrals this business's team members made, past members included, instead of the authenticated user's own. Requires company:basic:read on that business, which every team member holds, and cannot be combined with user_id. The owner role reads every referral; anyone else reads only the referrals made by themselves and by the people under them in the org chart.", "in": "query", "name": "referring_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter the authenticated partner's CPA offers by status. Use offered for every state after qualification.", "in": "query", "name": "advance_status", "required": false, "schema": { "enum": [ "projected", "available", "accepted", "funded", "clawed_back", "completed", "expired", "withdrawn", "offered" ], "type": "string" } }, { "description": "Filter by referral status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "removed" ], "type": "string" } }, { "description": "When true, only businesses with pending or completed earnings paid to the caller.", "in": "query", "name": "has_earnings", "required": false, "schema": { "type": "boolean" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort partner businesses by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "referral_started_at", "referral_expires_at", "payout_percentage", "volume_usd", "volume_30d_usd", "earnings_usd" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return partner businesses created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return partner businesses created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only return partner businesses whose first paid sale above zero happened before this timestamp.", "in": "query", "name": "first_sale_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return partner businesses whose first paid sale above zero happened after this timestamp. Combined with first_sale_before, this is the net new set: businesses that processed their first $1 inside the window.", "in": "query", "name": "first_sale_after", "required": false, "schema": { "type": "string" } }, { "description": "Filter to referrals attributed to this user. For first-tier referrals, this is the referred account owner; for second-tier referrals, this is the partner you recruited.", "in": "query", "name": "referred_user_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter by the referred user's exact username. Ignored when `referred_user_id` is present.", "in": "query", "name": "referred_username", "required": false, "schema": { "type": "string" } }, { "description": "Filter to referrals from a single tier: first, second, or blueprint.", "in": "query", "name": "tier", "required": false, "schema": { "enum": [ "first", "second", "blueprint" ], "type": "string" } }, { "description": "Case-insensitive business-name prefix, or an exact `biz_` account ID. Surrounding whitespace is ignored; blank values apply no filter.", "in": "query", "name": "business_prefix_query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account": { "description": "Referred account.", "properties": { "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route" ], "type": [ "object", "null" ] }, "blueprint_partner": { "description": "The partner whose blueprint the business deployed. Null unless this is a blueprint referral.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "commission_advance": { "description": "CPA terms for the referring partner. Omitted for other callers. An offer token requires partner:commission_advance:accept permission.", "oneOf": [ { "$ref": "#/components/schemas/PartnerAdvance" }, { "type": "null" } ] }, "commission_advance_projections_allowed": { "description": "Whether this referral meets the partner and ownership requirements for saving commission advance projections. Returned only to the referring partner; existing advance terms and update permissions still apply.", "example": false, "type": "boolean" }, "created_at": { "description": "When the partner business was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "deal_closed_reason": { "description": "How the partner closed this business, in their own words. Null until the partner saves one.", "example": null, "type": [ "string", "null" ] }, "earnings_usd": { "properties": { "completed": { "description": "Commission already paid out, in USD.", "example": "3.00", "type": "string" }, "pending": { "description": "Commission scheduled but not yet paid, in USD.", "example": "1.00", "type": "string" }, "total": { "description": "Pending + completed commission, in USD.", "example": "4.00", "type": "string" } }, "required": [ "total", "pending", "completed" ], "type": "object" }, "first_tier_partner": { "description": "The partner who referred the business owner onto Whop (first tier). Null if there is no active first-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "id": { "description": "Partner business ID.", "example": "coma_xxxxxxxxxxxxxx", "type": "string" }, "my_partner_tier": { "description": "Which tier the caller earns on for this business: `first` (they referred the owner), `second` (they referred the first-tier partner), or `blueprint` (the business deployed a site from their blueprint).", "enum": [ "first", "second", "blueprint" ], "example": "first", "type": "string" }, "object": { "enum": [ "partner_business" ], "example": "partner_business", "type": "string" }, "owner": { "description": "The owner of the referred business.", "properties": { "email": { "description": "The business owner's email address, so a partner can follow up on a referral they made. Requires the `partner:email:read` scope; `null` without it, or while the account has no reachable address of its own.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture", "email" ], "type": [ "object", "null" ] }, "payout_percentages": { "description": "The referrer's commission rate for each income source, expressed as a fraction (0.3 = 30%).", "properties": { "ad_spend": { "description": "Share of the referred business's Whop Ads spend.", "example": 0.015, "format": "float", "type": [ "number", "null" ] }, "card_interchange": { "description": "Share of Whop's profit from card interchange.", "example": 0.2, "format": "float", "type": [ "number", "null" ] }, "sales": { "description": "Share of Whop's profit from product sales.", "example": 0.3, "format": "float", "type": "number" }, "transfer": { "description": "Share of Whop's profit from platform balance transfers.", "example": 0.25, "format": "float", "type": [ "number", "null" ] }, "withdrawal": { "description": "Share of Whop's profit from withdrawals.", "example": 0.3, "format": "float", "type": [ "number", "null" ] } }, "required": [ "sales", "ad_spend", "transfer", "card_interchange", "withdrawal" ], "type": "object" }, "referral_expires_at": { "description": "When the referral expires.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "referral_started_at": { "description": "When the referral became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "referring_business": { "description": "The partner business whose team member made this referral, the one its commission is paid to. Null for a solo partner's referral.", "properties": { "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route" ], "type": [ "object", "null" ] }, "second_tier_partner": { "description": "The second-tier partner who earns on this business (referred the first-tier partner). Null if there is no active second-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "status": { "description": "Current referral status.", "enum": [ "active", "removed" ], "example": "active", "type": "string" }, "volume_usd": { "properties": { "attributed": { "description": "Credited GMV (awaiting_settlement + settled); excludes canceled and reversed, in USD.", "example": "40.00", "type": "string" }, "awaiting_settlement": { "description": "GMV awaiting settlement (commission not yet computed), in USD.", "example": "0.00", "type": "string" }, "last_30d": { "description": "Credited GMV from the trailing 30 days (awaiting_settlement + settled), in USD.", "example": "0.00", "type": "string" }, "settled": { "description": "GMV of pending + completed payments, in USD.", "example": "40.00", "type": "string" } }, "required": [ "attributed", "awaiting_settlement", "settled", "last_30d" ], "type": "object" } }, "required": [ "object", "id", "account", "owner", "first_tier_partner", "second_tier_partner", "blueprint_partner", "my_partner_tier", "status", "payout_percentages", "referral_started_at", "referral_expires_at", "created_at", "volume_usd", "earnings_usd", "deal_closed_reason" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "partner businesses listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid sort field" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the referral-read scope" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "referral:basic:read" ] } ], "summary": "List referred businesses", "tags": [ "Partners" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/partners/businesses/{id}": { "get": { "description": "Retrieves a single referred business and its referral terms. The original referrer or a caller with company:basic:read on the business credited for the referral can read it.", "operationId": "retrievePartnerBusiness", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "description": "Referred account.", "properties": { "capabilities": { "$ref": "#/components/schemas/AccountCapabilities", "nullable": true }, "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "recommended_actions": { "description": "Optional actions that unlock capabilities or grow the referred account.", "items": { "$ref": "#/components/schemas/AccountRecommendedAction" }, "type": [ "array", "null" ] }, "required_actions": { "description": "Actions the referred account owner must take to unblock capabilities.", "items": { "$ref": "#/components/schemas/AccountRequiredAction" }, "type": [ "array", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route", "capabilities", "required_actions", "recommended_actions" ], "type": [ "object", "null" ] }, "blueprint_partner": { "description": "The partner whose blueprint the business deployed. Null unless this is a blueprint referral.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "commission_advance": { "description": "CPA terms for the referring partner. Omitted for other callers. An offer token requires partner:commission_advance:accept permission.", "oneOf": [ { "$ref": "#/components/schemas/PartnerAdvance" }, { "type": "null" } ] }, "commission_advance_projections_allowed": { "description": "Whether this referral meets the partner and ownership requirements for saving commission advance projections. Returned only to the referring partner; existing advance terms and update permissions still apply.", "example": false, "type": "boolean" }, "commission_advance_rate": { "description": "Estimated upfront advance per USD of annual card and BNPL payments, including advance share and remaining term. Multiply annual payments by this rate, cap at 2500 USD, and round down to cents. Uses observed commissions or, without history, reference US card fees minus estimated percentage costs times the partner share. Null when projections or pricing are unavailable. Only returned to the referring partner. Qualification and final offers use actual activity.", "example": null, "type": [ "string", "null" ] }, "created_at": { "description": "When the partner business was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "deal_closed_reason": { "description": "How the partner closed this business, in their own words. Null until the partner saves one.", "example": null, "type": [ "string", "null" ] }, "earnings_usd": { "properties": { "completed": { "description": "Commission already paid out, in USD.", "example": "0.00", "type": "string" }, "pending": { "description": "Commission scheduled but not yet paid, in USD.", "example": "0.00", "type": "string" }, "total": { "description": "Pending + completed commission, in USD.", "example": "0.00", "type": "string" } }, "required": [ "total", "pending", "completed" ], "type": "object" }, "first_tier_partner": { "description": "The partner who referred the business owner onto Whop (first tier). Null if there is no active first-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "id": { "description": "Partner business ID.", "example": "coma_xxxxxxxxxxxxxx", "type": "string" }, "my_partner_tier": { "description": "Which tier the caller earns on for this business: `first` (they referred the owner), `second` (they referred the first-tier partner), or `blueprint` (the business deployed a site from their blueprint).", "enum": [ "first", "second", "blueprint" ], "example": "blueprint", "type": "string" }, "object": { "enum": [ "partner_business" ], "example": "partner_business", "type": "string" }, "owner": { "description": "The owner of the referred business.", "properties": { "email": { "description": "The business owner's email address, so a partner can follow up on a referral they made. Requires the `partner:email:read` scope; `null` without it, or while the account has no reachable address of its own.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "tanyacole", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture", "email" ], "type": [ "object", "null" ] }, "payout_percentages": { "description": "The referrer's commission rate for each income source, expressed as a fraction (0.3 = 30%).", "properties": { "ad_spend": { "description": "Share of the referred business's Whop Ads spend.", "example": 0.0, "format": "float", "type": [ "number", "null" ] }, "card_interchange": { "description": "Share of Whop's profit from card interchange.", "example": 0.0, "format": "float", "type": [ "number", "null" ] }, "sales": { "description": "Share of Whop's profit from product sales.", "example": 0.3, "format": "float", "type": "number" }, "transfer": { "description": "Share of Whop's profit from platform balance transfers.", "example": 0.0, "format": "float", "type": [ "number", "null" ] }, "withdrawal": { "description": "Share of Whop's profit from withdrawals.", "example": 0.0, "format": "float", "type": [ "number", "null" ] } }, "required": [ "sales", "ad_spend", "transfer", "card_interchange", "withdrawal" ], "type": "object" }, "pending_owner_invites": { "description": "Outstanding invites to claim ownership of this business. Present only to the first-tier partner's whop.com session, or the Whop CLI or MCP with the `partner:handoff` scope, and empty once every invite has been accepted.", "items": { "properties": { "email": { "description": "The address the invite to claim this business was emailed to.", "type": "string" }, "id": { "description": "The invite ID (an ausri_ identifier). Pass it to the resend endpoint.", "type": "string" } }, "required": [ "id", "email" ], "type": "object" }, "type": "array" }, "referral_expires_at": { "description": "When the referral expires.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "referral_started_at": { "description": "When the referral became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "referring_business": { "description": "The partner business whose team member made this referral, the one its commission is paid to. Null for a solo partner's referral.", "properties": { "id": { "description": "Referred account ID.", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "type": [ "string", "null" ] }, "route": { "description": "Referred account route.", "type": "string" }, "title": { "description": "Referred account display name.", "type": "string" } }, "required": [ "id", "title", "logo_url", "route" ], "type": [ "object", "null" ] }, "second_tier_partner": { "description": "The second-tier partner who earns on this business (referred the first-tier partner). Null if there is no active second-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "status": { "description": "Current referral status.", "enum": [ "active", "removed" ], "example": "active", "type": "string" }, "volume_usd": { "properties": { "attributed": { "description": "Credited GMV (awaiting_settlement + settled); excludes canceled and reversed, in USD.", "example": "0.00", "type": "string" }, "awaiting_settlement": { "description": "GMV awaiting settlement (commission not yet computed), in USD.", "example": "0.00", "type": "string" }, "last_30d": { "description": "Credited GMV from the trailing 30 days (awaiting_settlement + settled), in USD.", "example": "0.00", "type": "string" }, "settled": { "description": "GMV of pending + completed payments, in USD.", "example": "0.00", "type": "string" } }, "required": [ "attributed", "awaiting_settlement", "settled", "last_30d" ], "type": "object" } }, "required": [ "object", "id", "account", "owner", "first_tier_partner", "second_tier_partner", "blueprint_partner", "my_partner_tier", "status", "payout_percentages", "referral_started_at", "referral_expires_at", "created_at", "volume_usd", "earnings_usd", "deal_closed_reason" ], "type": "object" } } }, "description": "partner business retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no such partner business is visible to the credential" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "referral:basic:read" ] }, { "bearerAuth": [ "company:basic:read" ] } ], "summary": "Retrieve a referred business", "tags": [ "Partners" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The partner business ID (a coma_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Save annual payment projections for a business referred by the authenticated partner. Unaccepted projections can be replaced with updated annual card and BNPL payment volume. To qualify, payment volume over the last 30 days must reach 5% of the annual payment projection. Ads are excluded from CPA; ordinary ad commissions continue. Pass withdraw_projections: true without projection amounts to remove unaccepted projections. Accepted projections are immutable. Public API access requires a partner OAuth token; business API keys are not supported.", "operationId": "updatePartnerBusiness", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "annual_processing_usd": { "description": "Annual projected card and BNPL processing combined, in USD.", "example": "1200000", "type": "string" }, "deal_closed_reason": { "description": "How the partner closed this business. Send it on its own to save it; the response is then the business ID and the saved reason.", "type": [ "string", "null" ] }, "withdraw_projections": { "description": "Remove unaccepted projections and invalidate the offer. The original CPA term is retained if projections are later added again.", "type": "boolean" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commission_advance": { "$ref": "#/components/schemas/PartnerAdvance", "nullable": true }, "id": { "description": "The referred business relationship ID.", "example": "coma_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "commission_advance" ], "type": "object" } } }, "description": "CPA projections saved" } }, "security": [ { "bearerAuth": [ "partner:commission_advance:update" ] } ], "summary": "Save CPA projections", "tags": [ "Partners" ] }, "x-whop-surface": "native" }, "/partners/businesses/{id}/accept_commission_advance": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The referred business relationship ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Accept the authenticated partner's CPA offer with the reviewed terms and signed offer token. Public API access requires a partner OAuth token; business API keys are not supported.", "operationId": "acceptPartnerBusinessCommissionAdvance", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "acknowledgments": { "example": [ "commission_replacement", "clawback", "term" ], "items": { "enum": [ "commission_replacement", "clawback", "term" ], "example": "term", "type": "string" }, "type": "array" }, "expected_amount_usd": { "description": "Reviewed payment amount in USD.", "example": "1079.99", "type": "string" }, "offer_token": { "description": "Signed offer token returned by the partner business response. Requires partner:commission_advance:accept permission to retrieve.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "terms_version": { "description": "Reviewed CPA terms version.", "example": "2026-01-01", "type": "string" } }, "required": [ "offer_token", "terms_version", "expected_amount_usd", "acknowledgments" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commission_advance": { "$ref": "#/components/schemas/PartnerAdvance" }, "id": { "description": "The referred business relationship ID.", "example": "coma_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "commission_advance" ], "type": "object" } } }, "description": "CPA offer accepted" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "partner:commission_advance:accept" ] } ], "summary": "Accept a CPA offer", "tags": [ "Partners" ] }, "x-whop-surface": "native" }, "/partners/businesses/{id}/earnings": { "get": { "description": "Lists the earnings Whop pays out for one referred business's activity, most recent first. The original referrer or a caller with company:basic:read on the business credited for the referral can read them.", "operationId": "listPartnerBusinessEarnings", "parameters": [ { "description": "Filter by earning status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "awaiting_settlement", "pending", "completed", "canceled", "reversed" ], "type": "string" } }, { "description": "Filter to earnings from these income sources. Repeat the parameter for each one (income_source=sales&income_source=ad_spend).", "explode": true, "in": "query", "name": "income_source", "required": false, "schema": { "items": { "enum": [ "sales", "ad_spend", "transfer", "card_interchange", "withdrawal", "onboarding_reward", "partner_reward", "verified_partner_referral_payback", "commission_advance" ], "example": "sales", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort earnings by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "commission_amount", "transaction_amount", "payout_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only return earnings created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return earnings created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account": { "description": "Referred account.", "properties": { "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route" ], "type": [ "object", "null" ] }, "cancelation_reason": { "description": "Why the earning was canceled or reversed, if applicable.", "example": "payment_refunded", "type": [ "string", "null" ] }, "commission_amount_usd": { "description": "What the referrer earns, in USD. Null until the earning settles.", "example": "1.00", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "financial_activity": { "description": "Income and cost lines behind this earning's commission. Null for earnings settled before this data was recorded.", "items": { "properties": { "amount": { "description": "Line amount in its native currency.", "example": "3.00", "type": "string" }, "amount_usd": { "description": "Line amount in USD.", "example": "3.00", "type": "string" }, "category": { "description": "Fee or cost category of the line.", "example": "whop_processing_fee", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Currency of the native amount.", "example": "usd", "type": "string" }, "type": { "description": "Whether the line is income Whop collected or a cost Whop paid.", "enum": [ "income", "expense" ], "example": "income", "type": "string" } }, "required": [ "type", "category", "currency", "amount", "amount_usd", "created_at" ], "type": "object" }, "type": [ "array", "null" ] }, "id": { "example": "afpy_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "income_source": { "description": "Which income source the commission is on: product-sales gross profit, Whop Ads spend billed to the business, platform balance transfer fees, Whop Card interchange, withdrawal gross profit, or a fixed onboarding or referral link reward paid to the partner when a referred business qualifies.", "enum": [ "sales", "ad_spend", "transfer", "card_interchange", "withdrawal", "onboarding_reward", "partner_reward", "verified_partner_referral_payback", "commission_advance" ], "example": "sales", "type": "string" }, "object": { "enum": [ "partner_business_earning" ], "example": "partner_business_earning", "type": "string" }, "payout_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "payout_percentage": { "description": "The referrer's share of Whop's gross profit, as a fraction (0.3 = 30%). Null until the earning settles.", "example": 0.04, "format": "float", "type": [ "number", "null" ] }, "product": { "properties": { "id": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "route": { "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": "string" }, "title": { "example": "Ceramic Coating Package", "type": "string" } }, "required": [ "id", "title", "route" ], "type": [ "object", "null" ] }, "projected_commission_amount_usd": { "description": "Estimated commission while awaiting settlement. Null when no estimate is available or the earning has settled.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "example": null, "type": "null" } ] }, "resource": { "anyOf": [ { "properties": { "alternative_payment_method": { "properties": { "image_url": { "example": "https://content.whop.com/core/pm_cashapp.svg", "type": [ "string", "null" ] }, "name": { "example": "Cash App", "type": "string" } }, "required": [ "name", "image_url" ], "type": [ "object", "null" ] }, "brand": { "example": "visa", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "id": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "example": "4242", "type": [ "string", "null" ] }, "object": { "enum": [ "receipt" ], "example": "receipt", "type": "string" }, "payment_method_type": { "example": "card", "type": [ "string", "null" ] }, "processor": { "example": "stripe", "type": [ "string", "null" ] } }, "required": [ "object", "id", "currency", "payment_method_type", "processor", "brand", "last4", "created_at", "alternative_payment_method" ], "type": [ "object", "null" ] }, { "properties": { "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "id": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "transfer" ], "example": "transfer", "type": "string" } }, "required": [ "object", "id", "currency", "created_at" ], "type": "object" }, { "properties": { "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "id": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "withdrawal" ], "example": "withdrawal", "type": "string" } }, "required": [ "object", "id", "currency", "created_at" ], "type": "object" }, { "properties": { "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": [ "string", "null" ] }, "id": { "example": "citx_xxxxxxxxxxxxxx", "type": "string" }, "merchant_name": { "example": "Austin Detail Supply", "type": [ "string", "null" ] }, "object": { "enum": [ "card_transaction" ], "example": "card_transaction", "type": "string" } }, "required": [ "object", "id", "currency", "merchant_name", "created_at" ], "type": "object" }, { "properties": { "business_id": { "description": "The referred business that qualified.", "type": "string" }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "description": "The retired onboarding reward ID. Always null; retained for historical earnings compatibility.", "example": null, "type": [ "string", "null" ] }, "object": { "enum": [ "onboarding_reward" ], "example": "onboarding_reward", "type": "string" }, "slug": { "description": "The retired reward link slug. Always null; retained for historical earnings compatibility.", "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "id", "slug", "business_id", "created_at" ], "type": "object" }, { "properties": { "business_id": { "description": "The referred business that qualified.", "type": "string" }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "description": "The referral link reward the business qualified for, prefixed `prwd_`.", "example": "prwd_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "partner_reward" ], "example": "partner_reward", "type": "string" } }, "required": [ "object", "id", "business_id", "created_at" ], "type": "object" }, { "type": "null" } ], "description": "The resource that generated the earning: the customer payment receipt for sales and ad spend earnings, the balance transfer for transfer earnings, the withdrawal for withdrawal earnings, the card transaction for card interchange earnings, or the qualifying reward for fixed reward earnings." }, "second_tier": { "description": "Whether this earning is a second-tier (grandparent) commission.", "example": false, "type": "boolean" }, "status": { "description": "Current status of the earning.", "enum": [ "awaiting_settlement", "pending", "completed", "canceled", "reversed" ], "example": "pending", "type": "string" }, "transaction_amount_usd": { "description": "The underlying transaction amount the commission's income comes from, in USD.", "example": "10.00", "type": "string" } }, "required": [ "object", "id", "account", "product", "status", "second_tier", "income_source", "transaction_amount_usd", "payout_percentage", "commission_amount_usd", "projected_commission_amount_usd", "financial_activity", "cancelation_reason", "created_at", "payout_at", "resource" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "earnings listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid sort direction" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "referral:basic:read" ] }, { "bearerAuth": [ "company:basic:read" ] } ], "summary": "List referred business earnings", "tags": [ "Partners" ], "x-whop-credentials": [ "account_api_key", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The partner business ID (a coma_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/partners/businesses/{id}/resend_invite": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The partner business ID (a coma_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Re-emails an outstanding invite to claim ownership of a referred business. Find the invite in the business's `pending_owner_invites`. Only the first-tier partner can resend, from a whop.com session or the Whop CLI or MCP with `partner:handoff`. Rate limited to one resend per invite every five minutes.", "operationId": "resendPartnerBusinessInvite", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "invite_id": { "description": "The outstanding invite to resend (an ausri_ identifier from `pending_owner_invites`).", "example": "ausri_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "invite_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "description": "Referred account.", "properties": { "capabilities": { "$ref": "#/components/schemas/AccountCapabilities", "nullable": true }, "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "recommended_actions": { "description": "Optional actions that unlock capabilities or grow the referred account.", "items": { "$ref": "#/components/schemas/AccountRecommendedAction" }, "type": [ "array", "null" ] }, "required_actions": { "description": "Actions the referred account owner must take to unblock capabilities.", "items": { "$ref": "#/components/schemas/AccountRequiredAction" }, "type": [ "array", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route", "capabilities", "required_actions", "recommended_actions" ], "type": [ "object", "null" ] }, "blueprint_partner": { "description": "The partner whose blueprint the business deployed. Null unless this is a blueprint referral.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "commission_advance": { "description": "CPA terms for the referring partner. Omitted for other callers. An offer token requires partner:commission_advance:accept permission.", "oneOf": [ { "$ref": "#/components/schemas/PartnerAdvance" }, { "type": "null" } ] }, "commission_advance_projections_allowed": { "description": "Whether this referral meets the partner and ownership requirements for saving commission advance projections. Returned only to the referring partner; existing advance terms and update permissions still apply.", "example": false, "type": "boolean" }, "created_at": { "description": "When the partner business was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "deal_closed_reason": { "description": "How the partner closed this business, in their own words. Null until the partner saves one.", "example": null, "type": [ "string", "null" ] }, "earnings_usd": { "properties": { "completed": { "description": "Commission already paid out, in USD.", "example": "3.00", "type": "string" }, "pending": { "description": "Commission scheduled but not yet paid, in USD.", "example": "1.00", "type": "string" }, "total": { "description": "Pending + completed commission, in USD.", "example": "4.00", "type": "string" } }, "required": [ "total", "pending", "completed" ], "type": "object" }, "first_tier_partner": { "description": "The partner who referred the business owner onto Whop (first tier). Null if there is no active first-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "id": { "description": "Partner business ID.", "example": "coma_xxxxxxxxxxxxxx", "type": "string" }, "my_partner_tier": { "description": "Which tier the caller earns on for this business: `first` (they referred the owner), `second` (they referred the first-tier partner), or `blueprint` (the business deployed a site from their blueprint).", "enum": [ "first", "second", "blueprint" ], "example": "first", "type": "string" }, "object": { "enum": [ "partner_business" ], "example": "partner_business", "type": "string" }, "owner": { "description": "The owner of the referred business.", "properties": { "email": { "description": "The business owner's email address, so a partner can follow up on a referral they made. Requires the `partner:email:read` scope; `null` without it, or while the account has no reachable address of its own.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture", "email" ], "type": [ "object", "null" ] }, "payout_percentages": { "description": "The referrer's commission rate for each income source, expressed as a fraction (0.3 = 30%).", "properties": { "ad_spend": { "description": "Share of the referred business's Whop Ads spend.", "example": 0.015, "format": "float", "type": [ "number", "null" ] }, "card_interchange": { "description": "Share of Whop's profit from card interchange.", "example": 0.2, "format": "float", "type": [ "number", "null" ] }, "sales": { "description": "Share of Whop's profit from product sales.", "example": 0.3, "format": "float", "type": "number" }, "transfer": { "description": "Share of Whop's profit from platform balance transfers.", "example": 0.25, "format": "float", "type": [ "number", "null" ] }, "withdrawal": { "description": "Share of Whop's profit from withdrawals.", "example": 0.3, "format": "float", "type": [ "number", "null" ] } }, "required": [ "sales", "ad_spend", "transfer", "card_interchange", "withdrawal" ], "type": "object" }, "pending_owner_invites": { "description": "Outstanding invites to claim ownership of this business. Present only to the first-tier partner's whop.com session, or the Whop CLI or MCP with the `partner:handoff` scope, and empty once every invite has been accepted.", "items": { "properties": { "email": { "description": "The address the invite to claim this business was emailed to.", "example": "marcus@shinetime.example", "type": "string" }, "id": { "description": "The invite ID (an ausri_ identifier). Pass it to the resend endpoint.", "example": "ausri_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "email" ], "type": "object" }, "type": "array" }, "referral_expires_at": { "description": "When the referral expires.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "referral_started_at": { "description": "When the referral became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "referring_business": { "description": "The partner business whose team member made this referral, the one its commission is paid to. Null for a solo partner's referral.", "properties": { "id": { "description": "Referred account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Referred account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "route": { "description": "Referred account route.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "title": { "description": "Referred account display name.", "example": "Gleam Mobile Detailing", "type": "string" } }, "required": [ "id", "title", "logo_url", "route" ], "type": [ "object", "null" ] }, "second_tier_partner": { "description": "The second-tier partner who earns on this business (referred the first-tier partner). Null if there is no active second-tier partner.", "properties": { "id": { "description": "User ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name.", "example": "Nina Alvarez", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username.", "example": "ninaalvarez", "type": "string" } }, "required": [ "id", "username", "name", "profile_picture" ], "type": [ "object", "null" ] }, "status": { "description": "Current referral status.", "enum": [ "active", "removed" ], "example": "active", "type": "string" }, "volume_usd": { "properties": { "attributed": { "description": "Credited GMV (awaiting_settlement + settled); excludes canceled and reversed, in USD.", "example": "40.00", "type": "string" }, "awaiting_settlement": { "description": "GMV awaiting settlement (commission not yet computed), in USD.", "example": "0.00", "type": "string" }, "last_30d": { "description": "Credited GMV from the trailing 30 days (awaiting_settlement + settled), in USD.", "example": "0.00", "type": "string" }, "settled": { "description": "GMV of pending + completed payments, in USD.", "example": "40.00", "type": "string" } }, "required": [ "attributed", "awaiting_settlement", "settled", "last_30d" ], "type": "object" } }, "required": [ "object", "id", "account", "owner", "first_tier_partner", "second_tier_partner", "blueprint_partner", "my_partner_tier", "status", "payout_percentages", "referral_started_at", "referral_expires_at", "created_at", "volume_usd", "earnings_usd", "deal_closed_reason" ], "type": "object" } } }, "description": "invite resent" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the invite was resent too recently" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the handoff scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no such outstanding invite on this business" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "partner:handoff" ] } ], "summary": "Resend an owner invite", "tags": [ "Partners" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/partners/fee_options": { "get": { "description": "Lists, per income stream, the fee a business the caller refers would be charged, how low the caller may price it, and the commission the caller earns on that stream. Answers for a referral that does not exist yet, so a referral flow can price the deal before the business is created. Requires `partner:fees:update`, since the floors a partner may price down to are only for a credential that can set them.", "operationId": "retrievePartnerFeeOptions", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "object": { "enum": [ "partner_fee_options" ], "example": "partner_fee_options", "type": "string" }, "streams": { "description": "One entry per income stream a partner earns on.", "items": { "properties": { "adjustable": { "description": "Whether a partner may lower the fee on this stream in exchange for a cut to their commission on it.", "example": true, "type": "boolean" }, "commission_percentage": { "description": "The partner's commission on this stream, in percent units (30 means 30%).", "example": 30.0, "type": [ "number", "null" ] }, "fee": { "description": "The merchant fee behind this stream, or null when the business is charged nothing on it.", "properties": { "minimum_percentage": { "description": "The lowest the fee may be priced down to.", "example": 2.4, "type": "number" }, "percentage": { "description": "The fee in force, in percent units (2.7 means 2.7%).", "example": 2.7, "type": "number" }, "reference_region": { "description": "For a regionally priced fee, the region `percentage` and `minimum_percentage` describe, and the region an adjustment is quoted against. Null for a fee that is not priced per region.", "example": "usa", "type": [ "string", "null" ] }, "regions": { "description": "Every region this fee is priced for, so a caller can tell which regions a given value would reach. Empty for a fee that is not priced per region.", "items": { "properties": { "minimum_percentage": { "description": "The lowest fee this region may be priced down to.", "example": 2.4, "type": "number" }, "percentage": { "description": "The fee in force for this region.", "example": 2.7, "type": "number" }, "region": { "description": "The region this card row prices, e.g. `usa`.", "example": "usa", "type": "string" } }, "required": [ "region", "percentage", "minimum_percentage" ], "type": "object" }, "type": "array" } }, "required": [ "percentage", "minimum_percentage", "reference_region", "regions" ], "type": [ "object", "null" ] }, "income_stream": { "description": "The income stream these terms describe.", "enum": [ "sales", "transfer", "card_interchange", "ad_spend", "withdrawal", "onboarding_reward", "partner_reward", "verified_partner_referral_payback" ], "example": "sales", "type": "string" }, "unadjustable_reason": { "description": "Why the stream cannot be adjusted: `no_merchant_fee` (the business is charged nothing on it), `commission_fixed` (the commission is a flat share a fee discount may not move), `no_headroom` (already at the floor), `fee_unavailable` (no fee or rate could be resolved). Null when adjustable.", "enum": [ "no_merchant_fee", "commission_fixed", "no_headroom", "fee_unavailable", null ], "example": "no_merchant_fee", "type": [ "string", "null" ] } }, "required": [ "income_stream", "commission_percentage", "adjustable", "unadjustable_reason", "fee" ], "type": "object" }, "type": "array" } }, "required": [ "object", "streams" ], "type": "object" } } }, "description": "fee terms retrieved" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential cannot set partner fees" } }, "security": [ { "bearerAuth": [ "partner:basic:read", "partner:fees:update" ] } ], "summary": "Retrieve the fee terms a partner can offer", "tags": [ "Partners" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/partners/leaderboard": { "get": { "description": "Ranks referrers by partner business earnings over the chosen `period`, all-time by default. Authentication is optional: authenticated callers also get their own standing, anonymous callers get the rankings alone.", "operationId": "retrievePartnerLeaderboard", "parameters": [ { "description": "Time window for the rankings. `day`, `month`, and `year` count earnings since the start of the current calendar day, month, or year; `last_30_days` counts earnings over the trailing 30 days; `all_time` ranks lifetime earnings.", "in": "query", "name": "period", "required": false, "schema": { "default": "all_time", "enum": [ "day", "month", "year", "last_30_days", "all_time" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "leaders": { "description": "The top referrers by total earnings, best first.", "items": { "properties": { "first_referral_started_at": { "description": "When the referrer's earliest partner business became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "rank": { "description": "1-based leaderboard position.", "example": 1, "type": "integer" }, "total_earnings_usd": { "description": "The referrer's pending + completed earnings across all referred businesses, in USD.", "example": "100.00", "type": "string" }, "total_volume_usd": { "description": "Credited GMV across all the referrer's referred businesses, in USD.", "example": "0.00", "type": "string" }, "user": { "description": "The ranked referrer. Identity fields (id, name, username, profile_picture) are returned only on the caller's own entry; other referrers expose coarse location only.", "properties": { "city": { "description": "The city where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "The country where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "US", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`. Present only on the caller's own entry.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name. Present only on the caller's own entry.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture. Present only on the caller's own entry.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username. Present only on the caller's own entry.", "example": "marcuswebb", "type": "string" } }, "required": [ "country", "city" ], "type": [ "object", "null" ] } }, "required": [ "rank", "total_earnings_usd", "total_volume_usd", "first_referral_started_at", "user" ], "type": "object" }, "maxItems": 10, "type": "array" }, "me": { "description": "The caller's own standing; null when the caller has no referral earnings.", "properties": { "first_referral_started_at": { "description": "When the referrer's earliest partner business became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "rank": { "description": "1-based leaderboard position.", "example": 2, "type": "integer" }, "total_earnings_usd": { "description": "The referrer's pending + completed earnings across all referred businesses, in USD.", "example": "4.00", "type": "string" }, "total_volume_usd": { "description": "Credited GMV across all the referrer's referred businesses, in USD.", "example": "40.00", "type": "string" }, "user": { "description": "The ranked referrer. Identity fields (id, name, username, profile_picture) are returned only on the caller's own entry; other referrers expose coarse location only.", "properties": { "city": { "description": "The city where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "The country where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "US", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`. Present only on the caller's own entry.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name. Present only on the caller's own entry.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture. Present only on the caller's own entry.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username. Present only on the caller's own entry.", "example": "marcuswebb", "type": "string" } }, "required": [ "country", "city" ], "type": [ "object", "null" ] } }, "required": [ "rank", "total_earnings_usd", "total_volume_usd", "first_referral_started_at", "user" ], "type": [ "object", "null" ] }, "nearby": { "description": "The referrers ranked within five places of the caller, including the caller, best first. Empty when the caller has no referral earnings or is anonymous.", "items": { "properties": { "first_referral_started_at": { "description": "When the referrer's earliest partner business became active.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "rank": { "description": "1-based leaderboard position.", "example": 1, "type": "integer" }, "total_earnings_usd": { "description": "The referrer's pending + completed earnings across all referred businesses, in USD.", "example": "100.00", "type": "string" }, "total_volume_usd": { "description": "Credited GMV across all the referrer's referred businesses, in USD.", "example": "0.00", "type": "string" }, "user": { "description": "The ranked referrer. Identity fields (id, name, username, profile_picture) are returned only on the caller's own entry; other referrers expose coarse location only.", "properties": { "city": { "description": "The city where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "The country where the referrer is located, derived from their IP address. Null if location sharing is disabled.", "example": "US", "type": [ "string", "null" ] }, "id": { "description": "User ID, prefixed `user_`. Present only on the caller's own entry.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The user's display name. Present only on the caller's own entry.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "profile_picture": { "description": "The user's profile picture. Present only on the caller's own entry.", "properties": { "url": { "description": "The user's profile picture URL.", "example": "https://ui-avatars.com/api/", "type": "string" } }, "required": [ "url" ], "type": "object" }, "username": { "description": "The user's unique username. Present only on the caller's own entry.", "example": "marcuswebb", "type": "string" } }, "required": [ "country", "city" ], "type": [ "object", "null" ] } }, "required": [ "rank", "total_earnings_usd", "total_volume_usd", "first_referral_started_at", "user" ], "type": "object" }, "maxItems": 11, "type": "array" } }, "required": [ "leaders", "me", "nearby" ], "type": "object" } } }, "description": "caller has no referral earnings" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid period" } }, "security": [ {}, { "bearerAuth": [ "partner:basic:read" ] } ], "summary": "Retrieve the leaderboard", "tags": [ "Partners" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/partners/referred_users": { "get": { "description": "Lists the users the caller referred onto Whop, newest first by default, each with the caller's total affiliate earnings from that user across all tiers.", "operationId": "listReferredUsers", "parameters": [ { "description": "The selected referring partner's user_ ID. Requires user_id=global; cannot be combined with earning_partner_username.", "in": "query", "name": "earning_partner_id", "required": false, "schema": { "type": "string" } }, { "description": "The selected referring partner's exact username. Requires user_id=global; cannot be combined with earning_partner_id.", "in": "query", "name": "earning_partner_username", "required": false, "schema": { "type": "string" } }, { "description": "List the users this business's team members referred, past members included, instead of the caller's own. Requires company:basic:read on that business, which every team member holds, and cannot be combined with user_id. The owner role reads every team member's referrals; anyone else reads only their own and those of the people under them in the org chart. earning_partner_id or earning_partner_username then narrows to one team member.", "in": "query", "name": "referring_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Search referred users by name or username. In global mode, matches the beginning of usernames only.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "When true, only referred users who brought at least one business onto Whop.", "in": "query", "name": "has_businesses", "required": false, "schema": { "type": "boolean" } }, { "description": "When true, only referred users with at least one business that has generated earnings.", "in": "query", "name": "has_earning_businesses", "required": false, "schema": { "type": "boolean" } }, { "description": "The field to sort by. created_at uses the user's signup date; earnings_usd uses the current primary referrer's cached total affiliate earnings from that user.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "earnings_usd" ], "type": "string" } }, { "description": "The direction to sort results.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "business_count": { "description": "Number of active businesses this user referred that credit the caller as a second-tier partner, or any earning partner in global mode. An earning-partner filter narrows the count to that partner. Excludes deleted businesses.", "example": 1, "type": "integer" }, "earnings": { "$ref": "#/components/schemas/Money", "description": "Total pending and completed affiliate earnings from this user for their current primary referrer, across all tiers, in USD. Includes historical earnings from removed referrals and deleted businesses." }, "joined_at": { "description": "When the referred user joined Whop, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "total_earnings_usd": { "example": "10.00", "type": "string" }, "total_volume_usd": { "example": "100.00", "type": "string" }, "user": { "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "example": "US", "type": [ "string", "null" ] }, "email": { "description": "The referred user's email address, so a partner can follow up with someone they brought onto Whop. Requires the `partner:email:read` scope; `null` without it, or while the account has no reachable address of its own.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "example": "Tanya Cole", "type": [ "string", "null" ] }, "profile_picture": { "properties": { "url": { "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] } }, "type": "object" }, "username": { "example": "tanyacole", "type": "string" } }, "required": [ "id", "username", "email" ], "type": "object" }, "volume_30d": { "$ref": "#/components/schemas/Money", "description": "Attributed volume over the last 30 days across the business referrals included in business_count, in USD." } }, "required": [ "total_earnings_usd", "total_volume_usd", "business_count", "volume_30d", "earnings", "joined_at", "user" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "referred users listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid sort field" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "partner selection is not authorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "selected partner not found" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "referral:basic:read" ] } ], "summary": "List the users the caller referred", "tags": [ "Partners" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/partners/{id}": { "get": { "description": "Retrieves the authenticated user's partner profile: enrollment and verification status, certification completion, active direct business referral count, and default payout rates. Other users' profiles are not accessible. To create and manage referral links, use `/partner_referral_requests`.", "operationId": "retrievePartner", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Partner" } } }, "description": "partner retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing partner read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "partner is not accessible" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "referral:basic:read" ] } ], "summary": "Retrieve a partner", "tags": [ "Partners" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The authenticated partner's user ID, prefixed user_, or me. Other users' profiles are not accessible.", "example": "me", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/payment_method_domains": { "get": { "deprecated": true, "description": "Lists the payment method domains registered for your account and its connected accounts. Deprecated: list domains with `GET /domains` and the `apple_pay` filter instead.", "operationId": "listPaymentMethodDomains", "parameters": [ { "description": "Only domains registered for this account (`biz_` tag). Defaults to the caller's account plus its connected accounts.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only the domain with this exact hostname.", "in": "query", "name": "hostname", "required": false, "schema": { "type": "string" } }, { "description": "Only domains with this verification status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "verified" ], "type": "string" } }, { "description": "Only domains registered with this wallet provider.", "in": "query", "name": "provider", "required": false, "schema": { "enum": [ "apple" ], "type": "string" } }, { "description": "Only domains created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only domains created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PaymentMethodDomain" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "payment method domains listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "List Payment Method Domains", "tags": [ "Payment Method Domains" ], "x-whop-deprecated-since": "2026-10-14", "x-whop-docs": "hidden", "x-whop-successor": "GET /domains" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "deprecated": true, "description": "Registers a hostname with the wallet provider and attempts verification inline. Returns `verified` when the provider fetched the domain-association file (for Apple Pay, `/.well-known/apple-developer-merchantid-domain-association`), or `pending` when it could not: host the file, then retry with `POST /payment_method_domains/:id/verify`. Deprecated: add Apple Pay with `POST /domains` and `apple_pay: {}` instead.", "operationId": "createPaymentMethodDomain", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account to register the domain for (`biz_` tag). Required when authenticating as a user; an account API key supplies its own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "hostname": { "description": "Hostname to register (e.g. `checkout.shinetime.com`).", "example": "pending.shinetime.com", "type": "string" } }, "required": [ "hostname" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDomain" } } }, "description": "domain registered as pending when verification fails" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "domain already verified" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "Create Payment Method Domain", "tags": [ "Payment Method Domains" ], "x-whop-deprecated-since": "2026-10-14", "x-whop-docs": "hidden", "x-whop-successor": "POST /domains" }, "x-whop-surface": "native" }, "/payment_method_domains/{id}": { "delete": { "deprecated": true, "description": "Unregisters a payment method domain so its wallet payment methods stop rendering there. Deprecated: remove Apple Pay with `PATCH /domains/{id}` and `apple_pay: null` instead. `DELETE /domains/{id}` removes the whole domain, including any website on it.", "operationId": "deletePaymentMethodDomain", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "dom_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "payment method domain deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "domain not found" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "Delete Payment Method Domain", "tags": [ "Payment Method Domains" ], "x-whop-deprecated-since": "2026-10-14", "x-whop-docs": "hidden", "x-whop-successor": "PATCH /domains/{id}" }, "get": { "deprecated": true, "description": "Retrieves a payment method domain to check its verification status. Deprecated: retrieve the domain with `GET /domains/{id}` instead, using the same ID.", "operationId": "retrievePaymentMethodDomain", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDomain" } } }, "description": "payment method domain retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "domain not found" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "Retrieve Payment Method Domain", "tags": [ "Payment Method Domains" ], "x-whop-deprecated-since": "2026-10-14", "x-whop-docs": "hidden", "x-whop-successor": "GET /domains/{id}" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the payment method domain, prefixed `pmd_` or `dom_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/payment_method_domains/{id}/verify": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the payment method domain, prefixed `pmd_` or `dom_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "deprecated": true, "description": "Re-attempts provider verification of a pending domain once the association file is hosted. Fails with a `bad_request` explaining what to fix; verifying an already `verified` domain is a no-op. Deprecated: check the domain with `POST /domains/{id}/check` instead.", "operationId": "verifyPaymentMethodDomain", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDomain" } } }, "description": "already verified domain is a no-op" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "verification failed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing permission" }, "404": { "$ref": "#/components/responses/NotFound", "description": "domain not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:manage_checkout" ] } ], "summary": "Verify Payment Method Domain", "tags": [ "Payment Method Domains" ], "x-whop-deprecated-since": "2026-10-14", "x-whop-docs": "hidden", "x-whop-successor": "POST /domains/{id}/check" }, "x-whop-surface": "native" }, "/payment_methods": { "get": { "description": "Returns a paginated list of saved payment methods for a member or account, or for the authenticated user when you pass neither.\n\nRequired permissions:\n - `member:payment_methods:read`", "operationId": "listPaymentMethod", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "member_id", "required": false, "schema": { "description": "The unique identifier of the member to list payment methods for. Omit this and account_id to list your own saved payment methods.", "example": "mber_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for ordering results, either ascending or descending." }, "style": "form" }, { "explode": true, "in": "query", "name": "created_before", "required": false, "schema": { "description": "Only return payment methods created before this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "created_after", "required": false, "schema": { "description": "Only return payment methods created after this timestamp.", "example": "2023-12-01T05:00:00.401Z", "format": "date-time", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "future_usage", "required": false, "schema": { "$ref": "#/components/schemas/FutureUsageTypes", "description": "Only return methods that can be charged this way. `on_session` leaves out saved Apple Pay and Google Pay cards, which can't be charged again while the buyer is present; `off_session` keeps every stored credential." }, "style": "form" }, { "explode": true, "in": "query", "name": "payment_method_types", "required": false, "schema": { "description": "Only return payment methods of these types. Pass the eligible `type` values from the payment method types catalogue so the list holds nothing the purchase cannot take. An empty list returns no payment methods.", "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "style": "form" }, { "explode": true, "in": "query", "name": "card_brands", "required": false, "schema": { "description": "Only return cards on these networks, such as the networks the seller accepts. Payment methods that are not cards are unaffected.", "items": { "$ref": "#/components/schemas/CardBrands" }, "type": "array" }, "style": "form" }, { "explode": true, "in": "query", "name": "card_funding_types", "required": false, "schema": { "description": "Only return cards funded this way. A card whose funding could not be determined is excluded, and payment methods that are not cards are unaffected.", "items": { "$ref": "#/components/schemas/CardFundingTypes" }, "type": "array" }, "style": "form" }, { "explode": true, "in": "query", "name": "has_payer_document", "required": false, "schema": { "description": "Filter cards by whether they carry the payer identity document their payment provider requires. Payment methods that are not cards are unaffected.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "expired", "required": false, "schema": { "description": "Filter by expiry. Only a card can expire, so `false` keeps every payment method that is not past its expiration month and `true` returns expired cards alone.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "broken", "required": false, "schema": { "description": "Filter by whether the stored credential has permanently stopped charging, such as a vault entry its provider closed.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "The unique identifier of the company. Provide either this or member_id, not both. Omit both to address your own saved payment methods.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PaymentMethodInterface.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/PaymentMethodListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:payment_methods:read" ] } ], "summary": "List payment methods", "tags": [ "Payment methods" ], "x-group-title": "Payins" } }, "/payment_methods/{id}": { "delete": { "description": "Delete a saved payment method. Cannot delete a payment method attached to an active subscription.\n\nRequired permissions:\n - `member:payment_methods:manage`", "operationId": "deletePaymentMethod", "parameters": [ { "description": "The unique identifier of the payment method to delete.", "in": "path", "name": "id", "required": true, "schema": { "example": "payt_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "member_id", "required": false, "schema": { "description": "The unique identifier of the member. Provide either this or account_id, not both. Omit both to address your own saved payment methods.", "example": "mber_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "The unique identifier of the company. Provide either this or member_id, not both. Omit both to address your own saved payment methods.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:payment_methods:manage" ] } ], "summary": "Delete payment method", "tags": [ "Payment methods" ], "x-group-title": "Payins" }, "get": { "description": "Retrieves a saved payment method from a member's wallet when you pass `member_id` or `account_id`, or from your own otherwise.\n\nRequired permissions:\n - `member:payment_methods:read`", "operationId": "retrievePaymentMethod", "parameters": [ { "description": "The unique identifier of the payment method.", "in": "path", "name": "id", "required": true, "schema": { "example": "payt_xxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "member_id", "required": false, "schema": { "description": "The unique identifier of the member. Provide either this or account_id, not both. Omit both to address your own saved payment methods.", "example": "mber_xxxxxxxxxxxxx", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "The unique identifier of the company. Provide either this or member_id, not both. Omit both to address your own saved payment methods.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "member:payment_methods:read" ] } ], "summary": "Retrieve payment method", "tags": [ "Payment methods" ], "x-group-title": "Payins" } }, "/payment_quotes": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Prices a purchase the way a payment for it will be charged. The body is the `PaymentInput` a payment takes plus where the buyer is, which a seller that collects no tax on the purchase can leave out. The purchase is priced from exactly what you send: no buyer is looked up, so no stored registration or purchase history applies. Pass the quote's `id` as `quote_id` when you create the payment to charge exactly the purchase, promo code, and tax shown here. A quote is priced once and may be consumed by one payment before `expires_at`. Cart entries must name existing variants with `variant_id`.", "operationId": "createPaymentQuote", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaymentInput" }, { "properties": { "address": { "description": "The buyer's billing address. Where tax is calculated when no shipping address is given, and the address a tax registration belongs to. A seller that collects tax on this purchase needs the buyer located by a `country` here, on `shipping_address`, a `presentment_country`, or an `ip_address`; without one the quote is refused with `quote_location_required`. Only the keys you supply are kept. The payment that consumes the quote must put the buyer in the same place, by country, state and postal code, through its own `shipping_address` or its confirmation token's billing address, or it is refused with `quote_mismatch`.", "properties": { "city": { "description": "City name.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code, such as `US`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "1114 Bouldin Ave", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Unit B", "type": [ "string", "null" ] }, "name": { "description": "The full name on the address.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78704", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, such as `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "ip_address": { "description": "The buyer's IP address, when your server makes the call on their behalf. Locates the buyer when neither address carries a country and no `presentment_country` is sent. A quote located this way (`located_by` is `ip_address`) is a preview: a payment refuses it with `quote_preview_only`, so quote again with the buyer's address before paying. Also where `presentment_currency` `auto` and `recommended_currencies` find the buyer's local currency, and where a payment method must be able to collect it.", "example": "203.0.113.7", "type": [ "string", "null" ] }, "line_items": { "description": "What the buyer is purchasing. Each entry names an existing variant by `variant_id`. Several entries form a cart, which requires every variant to be compatible, belong to this account, and use the same currency.", "example": [ { "quantity": 1, "variant_id": "plan_xxxxxxxxxxxxxx" } ], "items": { "properties": { "quantity": { "description": "How many units of the variant to purchase. Defaults to 1; more than 1 requires the variant to allow multiple quantities.", "example": 1, "maximum": 999999, "minimum": 1, "type": [ "integer", "null" ] }, "variant_id": { "description": "An existing variant to charge for, prefixed `plan_`. Each variant may appear once — use `quantity` for multiple units.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "variant_id" ], "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" }, "presentment_country": { "description": "The country to price the purchase for, as an ISO 3166-1 alpha-2 code such as `JP`, when the buyer chose one: a store's country picker. Prices in the currency `auto` would pick for a buyer in that country, so send it instead of `presentment_currency`, never with it. Whether a payment method can collect that currency is still judged where the buyer is: by `ip_address`, and by this country only without one. With no address that carries a country, tax is estimated for this country (`located_by` is `presentment_country`) at the country level, and a quote located this way is a preview a payment refuses with `quote_preview_only`. Send it only once the buyer has chosen a country: without it, an `ip_address` estimates more precisely, such as for a US state. For a country Whop has no currency for, the quote is priced as `auto` for the buyer's `ip_address`, and tax is still estimated for the country.", "example": "JP", "type": [ "string", "null" ] }, "presentment_currency": { "description": "The currency to price and charge the purchase in. Omit it, or send null, to price in the variants' own currency. `auto` prices in the currency of the country Whop places the buyer's `ip_address` in when the purchase can be converted into it and a payment method can collect it, and in the variants' own currency otherwise, including when no `ip_address` is sent or Whop cannot place it in a country. To choose that country instead, send `presentment_country` in place of this. A three-letter ISO 4217 code, such as `eur`, prices in that currency or is refused: with `presentment_currency_unsupported` when the purchase cannot be converted into it (adaptive pricing is off for the variant, the variant is not a one-time purchase, or `plan` describes a variant that does not exist yet), and with `presentment_currency_not_payable` when no payment method can collect it. A converted quote states every amount in this currency at an `exchange_rate` fixed until `expires_at`, and the payment that consumes it is charged in this currency at that rate.", "example": "auto", "type": [ "string", "null" ] }, "shipping_address": { "description": "Where physical goods ship. When present it is where tax is calculated; omit it for digital goods. Only the keys you supply are kept. The payment that consumes the quote must ship to the same place, by country, state and postal code, or it is refused with `quote_mismatch`.", "properties": { "city": { "description": "City name.", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code, such as `US`.", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "type": [ "string", "null" ] }, "name": { "description": "The full name on the address.", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, such as `CA`.", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "tax_ids": { "description": "The buyer's tax registration, for a business purchase. One entry. Prices the purchase as business-to-business where that applies (EU reverse charge, for one) and requires an `address` to belong to.", "items": { "properties": { "type": { "description": "The registration type.", "enum": [ "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" ], "example": "eu_vat", "type": "string" }, "value": { "description": "The registration number as issued.", "example": "DE123456789", "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "maxItems": 1, "type": [ "array", "null" ] } }, "required": [], "type": "object" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentQuote" } } }, "description": "payment quote priced" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "variant_id and line_items together" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:charge on the account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "variant from another account" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Create Payment Quote", "tags": [ "Payment Quotes" ] }, "x-whop-surface": "native" }, "/payment_quotes/{id}": { "get": { "description": "Retrieves a payment quote. Use it to check which payment holds the quote, through `payment_id`, and when it expires.", "operationId": "retrievePaymentQuote", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentQuote" } } }, "description": "payment quote retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without read access to the quote's account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown payment quote" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "Retrieve Payment Quote", "tags": [ "Payment Quotes" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment quote ID, prefixed `pq_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/payment_rules": { "get": { "description": "Lists the payment rules on an account.", "operationId": "listPaymentRules", "parameters": [ { "description": "Only return rules belonging to this account. Defaults to the account the request is acting for.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return rules with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "inactive", "deleted" ], "type": "string" } }, { "description": "Only return rules that take this action.", "in": "query", "name": "action", "required": false, "schema": { "enum": [ "allow", "block", "review", "enforce_3ds" ], "type": "string" } }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PaymentRule" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A list of payment rules" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "The status filter is not a known status" } }, "security": [ { "bearerAuth": [] } ], "summary": "List payment rules", "tags": [ "Payment Rules" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a payment rule. It is created `active` and applies its `action` to new payments that match all of its `conditions`.", "operationId": "createPaymentRule", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account_id": { "description": "The account to create the rule on. Defaults to the account the request is acting for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "action": { "description": "What this account's rule requests when every condition matches. One applicable account-rule action wins, in this order: `allow`, `block`, `review`, `enforce_3ds`. An `allow` overrides this account's other rules, never Whop's own fraud controls. A `review` requests authorization without capture for an eligible on-session card payment through Whop Payments. Automatic capture is scheduled for 48 hours after authorization; capture or void the payment before then to decide sooner. Capture may complete later or fail. Review is skipped for unsupported methods, off-session payments, and payments already configured for manual capture. An `enforce_3ds` is skipped when the account rule cannot apply a challenge. Other 3DS requirements still apply.", "enum": [ "allow", "block", "review", "enforce_3ds" ], "example": "review", "type": "string" }, "conditions": { "additionalProperties": false, "description": "The conditions a payment is matched against. Up to 10 conditions, and 8 KiB once serialized.", "example": { "all": [ { "field": "risk_score", "operator": "gte", "value": 70 } ] }, "properties": { "all": { "items": { "additionalProperties": false, "properties": { "field": { "description": "The payment attribute this condition reads.", "enum": [ "risk_score", "amount_in_usd", "card_country", "card_brand", "card_funding", "card_bin", "billing_country", "billing_postal_code", "billing_city", "customer_email", "email_domain", "ip_address", "ip_country" ], "example": "risk_score", "type": "string" }, "operator": { "description": "How the payment attribute is compared to the value.", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "starts_with", "contains", "ends_with", "in_cidr" ], "example": "gte", "type": "string" }, "value": { "$ref": "#/components/schemas/PaymentRuleConditionValue" } }, "required": [ "field", "operator", "value" ], "type": "object" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "all" ], "type": "object" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Custom string-to-string values for your integration. Maximum 50 keys, 40 characters per key, 500 characters per value.", "example": { "team": "risk" }, "type": "object" }, "name": { "description": "A name for this rule. Up to 255 characters.", "example": "Review risky cards", "maxLength": 255, "minLength": 1, "type": "string" } }, "required": [ "name", "action", "conditions" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRule" } } }, "description": "The created rule" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "The action is not a supported action" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "The caller cannot write to this account" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a payment rule", "tags": [ "Payment Rules" ] }, "x-whop-surface": "native" }, "/payment_rules/fields": { "get": { "description": "Lists the payment attributes a rule condition can read, with the operators and values each one accepts. Small and returned in full on one page.", "operationId": "listPaymentRuleFields", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PaymentRuleField" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "The fields a condition can read, with the operators and values each one accepts" } }, "security": [ { "bearerAuth": [] } ], "summary": "List fields", "tags": [ "Payment Rules" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/payment_rules/{id}": { "delete": { "description": "Deletes a payment rule. It stops applying to new payments but is kept, so the payments it already decided still name it.", "operationId": "deletePaymentRule", "responses": { "200": { "description": "The deleted rule" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete a payment rule", "tags": [ "Payment Rules" ] }, "get": { "description": "Retrieves a payment rule.", "operationId": "retrievePaymentRule", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRule" } } }, "description": "The requested rule" }, "404": { "$ref": "#/components/responses/NotFound", "description": "No rule with this ID" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve a payment rule", "tags": [ "Payment Rules" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment rule ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a payment rule's name or metadata, keeping its ID and everything recorded against it. A rule's `action` and `conditions` are fixed once created, so the payments it decided keep naming the rule that decided them; use `POST /payment_rules/:id/replace` to change them.", "operationId": "updatePaymentRule", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "metadata": { "additionalProperties": { "type": "string" }, "description": "Custom string-to-string values for your integration. Maximum 50 keys, 40 characters per key, 500 characters per value.", "example": { "team": "risk" }, "type": "object" }, "name": { "description": "A name for this rule. Up to 255 characters.", "example": "Review risky cards", "maxLength": 255, "minLength": 1, "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRule" } } }, "description": "The updated rule" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update a payment rule", "tags": [ "Payment Rules" ] }, "x-whop-surface": "native" }, "/payment_rules/{id}/activate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment rule ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Activates an inactive payment rule so it applies to new payments again. A deleted rule cannot be activated.", "operationId": "activatePaymentRule", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRule" } } }, "description": "The activated rule" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Activate a payment rule", "tags": [ "Payment Rules" ] }, "x-whop-surface": "native" }, "/payment_rules/{id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment rule ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Deactivates a payment rule so it stops applying to new payments. It keeps its ID and can be activated again.", "operationId": "deactivatePaymentRule", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRule" } } }, "description": "The deactivated rule" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deactivate a payment rule", "tags": [ "Payment Rules" ] }, "x-whop-surface": "native" }, "/payment_rules/{id}/replace": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment rule ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Changes a payment rule's `action` and `conditions` by deleting it and creating its successor in one step. The successor has a new ID and keeps the replaced rule's name, metadata, and `active` or `inactive` status.", "operationId": "replacePaymentRule", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "action": { "description": "What this account's rule requests when every condition matches. One applicable account-rule action wins, in this order: `allow`, `block`, `review`, `enforce_3ds`. An `allow` overrides this account's other rules, never Whop's own fraud controls. A `review` requests authorization without capture for an eligible on-session card payment through Whop Payments. Automatic capture is scheduled for 48 hours after authorization; capture or void the payment before then to decide sooner. Capture may complete later or fail. Review is skipped for unsupported methods, off-session payments, and payments already configured for manual capture. An `enforce_3ds` is skipped when the account rule cannot apply a challenge. Other 3DS requirements still apply.", "enum": [ "allow", "block", "review", "enforce_3ds" ], "example": "review", "type": "string" }, "conditions": { "additionalProperties": false, "description": "The conditions a payment is matched against. Up to 10 conditions, and 8 KiB once serialized.", "example": { "all": [ { "field": "risk_score", "operator": "gte", "value": 70 } ] }, "properties": { "all": { "items": { "additionalProperties": false, "properties": { "field": { "description": "The payment attribute this condition reads.", "enum": [ "risk_score", "amount_in_usd", "card_country", "card_brand", "card_funding", "card_bin", "billing_country", "billing_postal_code", "billing_city", "customer_email", "email_domain", "ip_address", "ip_country" ], "example": "risk_score", "type": "string" }, "operator": { "description": "How the payment attribute is compared to the value.", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "starts_with", "contains", "ends_with", "in_cidr" ], "example": "gte", "type": "string" }, "value": { "$ref": "#/components/schemas/PaymentRuleConditionValue" } }, "required": [ "field", "operator", "value" ], "type": "object" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "all" ], "type": "object" } }, "required": [ "action", "conditions" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRule" } } }, "description": "The rule that replaced this one" }, "409": { "$ref": "#/components/responses/Conflict", "description": "The rule was already replaced or deleted" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace a payment rule", "tags": [ "Payment Rules" ] }, "x-whop-surface": "native" }, "/payments": { "get": { "description": "Lists payments, newest first. By default, returns sales for the accounts your credential can read: an account credential's own account, or every account a user can read payments for. Set `mode` to `user_sales` to list the sales the signed-in user received personally, outside any account.", "operationId": "listPayments", "parameters": [ { "description": "Which sales to list. `account_sales` returns sales for the accounts the caller can read. `user_sales` returns only sales the signed-in user received personally, outside any account; it requires the user's own Whop login session and cannot be combined with `account_id`.", "in": "query", "name": "mode", "required": false, "schema": { "default": "account_sales", "enum": [ "account_sales", "user_sales" ], "type": "string" } }, { "description": "Only payments charged by this account, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only payments in this lifecycle state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "open", "authorized", "paid", "pending", "uncollectible", "unresolved", "void" ], "type": "string" } }, { "description": "Only payments whose most recently attached kept shipment is in this tracking state. `missing_tracking` selects paid payments with a captured shipping address and no kept shipment, excluding fully refunded payments. `needs_tracking` selects payments with an open pre-shipment funds hold and no kept shipment. Shipment states do not imply a payment or refund state. Requires `shipment:basic:read` as well as `payment:basic:read`; user-wide lists include only accounts readable under both scopes. Only supported with `mode=account_sales`.", "in": "query", "name": "tracking_status", "required": false, "schema": { "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error", "needs_tracking", "missing_tracking" ], "type": "string" } }, { "description": "Only payments charged for this reason. `subscription_cycle` also matches renewals recorded as `subscription_update`.", "in": "query", "name": "billing_reason", "required": false, "schema": { "enum": [ "subscription_create", "subscription_cycle", "subscription_update", "one_time", "manual", "subscription" ], "type": "string" } }, { "description": "Only payments presented in this three-letter currency, such as `usd`.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Only payments made by this buyer, prefixed `user_`. This filters sales the caller can read, so `me` is not accepted; list the caller's own purchases with `GET /memberships?user_id=me`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Search payments by payment ID, dispute ID, user ID, membership ID, user email, name, or username. Email filtering requires the member:email:read permission.", "in": "query", "name": "query", "required": false, "schema": { "description": "Search payments by payment ID, dispute ID, user ID, membership ID, user email, name, or username. Email filtering requires the member:email:read permission.", "type": "string" } }, { "description": "Also cover the account's connected accounts. Requires `account_id`, and is a 400 without it. Without `query`, lists the payments of the account and every connected account, newest first by `created_at` only; another `order` is a 400. The listing is cut off after 10 seconds, which a rare filter on an account with little recent activity can reach; add a `query` to narrow it. With `query`, matches on payment, dispute, user or membership ID, buyer email, or a card's first 6 or 8 digits and last 4 separated by a space or dash (`424242 4242`); free-text queries such as a name search only the named account. Connected accounts' payments are returned only for connected accounts you can read payments on.", "in": "query", "name": "include_connected_accounts", "required": false, "schema": { "type": "boolean" } }, { "description": "Only payments made by this member, prefixed `mber_`.", "in": "query", "name": "member_id", "required": false, "schema": { "type": "string" } }, { "description": "Only payments billed under this membership, prefixed `mem_`.", "in": "query", "name": "membership_id", "required": false, "schema": { "type": "string" } }, { "description": "Only payments for this product, prefixed `prod_`.", "in": "query", "name": "product_id", "required": false, "schema": { "type": "string" } }, { "description": "Only payments priced by this variant, prefixed `plan_`.", "in": "query", "name": "variant_id", "required": false, "schema": { "type": "string" } }, { "description": "Only payments created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments in any of these lifecycle states, with the same meanings as `status`. Repeat the parameter to pass several. Combined with `status` when both are sent.", "in": "query", "name": "statuses", "required": false, "schema": { "items": { "enum": [ "open", "authorized", "paid", "pending", "uncollectible", "unresolved", "void" ], "example": "paid", "type": "string" }, "type": "array" } }, { "description": "Only payments whose `substatus` is any of these. Repeat the parameter to pass several. `incomplete` also matches payments that report `incomplete` because no finer status was recorded.", "in": "query", "name": "substatuses", "required": false, "schema": { "items": { "enum": [ "succeeded", "requires_capture", "pending", "failed", "blocked", "past_due", "canceled", "price_too_low", "uncollectible", "refunded", "auto_refunded", "partially_refunded", "dispute_warning", "dispute_needs_response", "dispute_warning_needs_response", "resolution_needs_response", "dispute_under_review", "dispute_warning_under_review", "resolution_under_review", "dispute_won", "dispute_warning_closed", "resolution_won", "dispute_lost", "dispute_closed", "resolution_lost", "drafted", "incomplete", "unresolved" ], "example": "dispute_needs_response", "type": "string" }, "type": "array" } }, { "description": "Only payments charged for any of these reasons, with the same meanings as `billing_reason`. Repeat the parameter to pass several. Combined with `billing_reason` when both are sent.", "in": "query", "name": "billing_reasons", "required": false, "schema": { "items": { "enum": [ "subscription_create", "subscription_cycle", "subscription_update", "one_time", "manual", "subscription" ], "example": "subscription_cycle", "type": "string" }, "type": "array" } }, { "description": "Only payments presented in any of these three-letter currencies. Repeat the parameter to pass several. Combined with `currency` when both are sent.", "in": "query", "name": "currencies", "required": false, "schema": { "items": { "example": "eur", "type": "string" }, "type": "array" } }, { "description": "Only payments priced by any of these variants, each prefixed `plan_`. Repeat the parameter to pass several. Combined with `variant_id` when both are sent.", "in": "query", "name": "variant_ids", "required": false, "schema": { "items": { "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only payments for any of these products, each prefixed `prod_`. Repeat the parameter to pass several. Combined with `product_id` when both are sent.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only payments paid with any of these methods: a card brand such as `amex`, a wallet such as `apple_pay`, or a payment method type such as `paypal`. Repeat the parameter to pass several.", "in": "query", "name": "payment_methods", "required": false, "schema": { "items": { "enum": [ "mastercard", "visa", "amex", "discover", "unionpay", "jcb", "diners", "link", "troy", "visadankort", "visabancontact", "china_union_pay", "rupay", "jcbrupay", "elo", "maestro", "tarjeta_naranja", "cirrus", "nspk_mir", "verve", "ebt", "private_label", "local_brand", "uatp", "wexcard", "uzcard", "meeza", "hrg_store_card", "girocard", "fuel_card", "dankort", "carnet", "atm_card", "china_union_payuzcard", "codensa", "cabal", "hipercard", "jcblankapay", "cmi", "aura", "accel", "culiance", "nyce", "pulse", "star", "eftpos", "alelo", "edenred", "sodexo", "unknown", "acss_debit", "addi", "affirm", "afterpay_clearpay", "alipay", "alipayhk", "alma", "amazon_pay", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_present", "card_installments_three", "card_installments_six", "card_installments_twelve", "cashapp", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "duitnow_qr", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "giropay", "google_pay", "gopay", "grabpay", "id_bank_transfer", "ideal", "interac", "kakao_pay", "klarna", "klarna_pay_now", "konbini", "kr_card", "kr_market", "kriya", "kueski", "mb_way", "m_pesa", "mercado_pago", "mercado_pago_ar", "mercado_pago_mx", "mobilepay", "modo", "mondu", "multibanco", "naver_pay", "nequi", "netbanking", "ng_bank", "ng_bank_transfer", "ng_card", "ng_market", "ng_ussd", "ng_wallet", "nupay", "nz_bank_account", "oney", "oney_3x", "oney_4x", "opay", "oxxo", "p24", "pago_efectivo", "pse", "pay_by_bank", "payco", "paynow", "paypal", "paypal_express", "paypay", "payto", "payto_email", "payto_phone", "payto_bank_account", "pix", "platform_balance", "promptpay", "qris", "rapipago", "rechnung", "revolut_pay", "samsung_pay", "satispay", "scalapay", "sencillito", "sepa_debit", "sequra", "servipag", "sezzle", "shop_pay", "shopeepay", "sofort", "south_korea_market", "spei", "splitit", "sunbit", "swish", "tabby", "tamara", "touch_n_go", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "vipps", "webpay", "wechat_pay", "whop_pay", "yape", "zip", "coinflow", "tap_to_pay" ], "example": "amex", "type": "string" }, "type": "array" } }, { "description": "Only payments whose shipment is in any of these tracking states, or that still need a tracking number (`needs_tracking`). Repeat the parameter to pass several. Requires `account_id` and the shipment:basic:read permission.", "in": "query", "name": "tracking_states", "required": false, "schema": { "items": { "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error", "needs_tracking", "missing_tracking" ], "example": "needs_tracking", "type": "string" }, "type": "array" } }, { "description": "Only payments refunded after this ISO 8601 timestamp.", "in": "query", "name": "refunded_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments refunded before this ISO 8601 timestamp.", "in": "query", "name": "refunded_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments with a dispute alert after this ISO 8601 timestamp.", "in": "query", "name": "dispute_alerted_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments with a dispute alert before this ISO 8601 timestamp.", "in": "query", "name": "dispute_alerted_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments with a dispute opened after this ISO 8601 timestamp.", "in": "query", "name": "dispute_created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments with a dispute opened before this ISO 8601 timestamp.", "in": "query", "name": "dispute_created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The field to sort by. `amount` sorts by the amount charged, in the currency it was charged in.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "paid_at", "amount" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Payment" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "payments listed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "unknown status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "tracking filter without shipment read permission" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "List Payments", "tags": [ "Payments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Charges a buyer for one or more variants with a payment method already on file (`member_id` and `payment_method_id`), or with a `confirmation_token` for a method the buyer just supplied. Collection runs in the background, so the response is the payment as created, not its outcome: poll Retrieve payment status for how far it has got and what the buyer must still do.", "operationId": "createPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaymentInput" }, { "properties": { "affiliate_code": { "description": "The code an affiliate link carries, which is the affiliate's username. The affiliate is credited for this payment as on a checkout session. A code naming no one eligible to earn on the product is ignored, and the payment goes ahead. A promo code with its own affiliate takes precedence. No affiliate is credited on a variant without a product or on a purchase of several variants. At most 255 characters. Not supported with a `card_present` `payment_method`.", "example": "priyaraman", "type": [ "string", "null" ] }, "auto_capture_after_minutes": { "description": "Minutes after authorization at which Whop captures the hold automatically unless it has been voided. Requires `capture: false`. Between 5 and 5760 (4 days).", "example": 60, "maximum": 5760, "minimum": 5, "type": [ "integer", "null" ] }, "billing_address": { "description": "The buyer's billing address, returned on the payment as `billing_address` and used to calculate tax when Whop calculates it for the account. Only with a `paypal` `payment_method`. Only the keys you supply are kept.", "properties": { "city": { "description": "City name.", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code, such as `US`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "1 Market St", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "type": [ "string", "null" ] }, "name": { "description": "The buyer's full name.", "example": "Dana Shine", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "94105", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, such as `CA`.", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "capture": { "description": "Whether to capture a card payment immediately. Defaults to true. Pass false to place an authorization hold that must be captured in full within five days via the capture endpoint, or automatically after `auto_capture_after_minutes`.", "example": false, "type": [ "boolean", "null" ] }, "confirmation_token": { "description": "A confirmation token describing a payment method the buyer just supplied. Provide this instead of `member_id` and `payment_method_id`; the buyer is resolved from the token's billing email, or from `email`. The buyer may still have a step to complete — poll the payment's status for what to do next.", "example": "ctok_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "email": { "description": "The buyer's email, resolving or creating the user the payment belongs to. With `confirmation_token` it overrides the email the token carries, and is ignored when the token was created by a signed-in buyer; with a `card_present` `payment_method` it names a buyer the point of sale already knows, otherwise the sale belongs to a guest until a buyer is attached; with a `paypal` `payment_method` it names the buyer and is required unless `member_id` is provided. Ignored with `member_id`.", "example": "dana@shinetime.example", "type": [ "string", "null" ] }, "ip_address": { "description": "The buyer's IPv4 or IPv6 address, used to assess the charge's risk and passed to the processor. Ignored unless a saved payment method is charged with `off_session` set to false.", "example": "203.0.113.24", "type": [ "string", "null" ] }, "line_items": { "description": "What the buyer is purchasing. Each entry takes exactly one of `variant_id` or an inline `variant`. One entry charges that variant; several entries form a cart, which requires every variant to be compatible, belong to this account, and use the same currency. Mutually exclusive with `variant_id` and `variant`.", "example": [ { "quantity": 1, "variant_id": "plan_xxxxxxxxxxxxxx" } ], "items": { "oneOf": [ { "required": [ "variant_id" ] }, { "required": [ "variant" ] } ], "properties": { "quantity": { "description": "How many units of the variant to purchase. Defaults to 1; more than 1 requires the variant to allow multiple quantities.", "example": 1, "maximum": 999999, "minimum": 1, "type": [ "integer", "null" ] }, "variant": { "description": "Find or create the variant for this entry by its attributes. Unknown properties return an error. Creating a variant requires `plan:create`, and creating or updating a product requires the matching product permission.", "properties": { "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "type": [ "boolean", "null" ] }, "application_fee_amount": { "description": "Application fee the platform collects per unit, in the variant currency (5.00 means $5.00 for USD). Must be positive and below the initial price for one-time variants or renewal price for recurring variants. Paid to the parent account alongside other processing fees; collection is capped to remaining proceeds. Applies to subsequent payments on recurring variants. Only valid for connected accounts with a parent account.", "type": [ "number", "null" ] }, "billing_period": { "description": "Recurring billing interval in days.", "type": [ "integer", "null" ] }, "billing_type": { "description": "Billing model for the variant.", "enum": [ null, "renewal", "one_time" ], "example": "renewal", "type": [ "string", "null" ] }, "currency": { "description": "Currency code for the variant prices.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "description": { "description": "Variant description.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Days until access expires.", "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Create a new variant instead of reusing a matching variant.", "type": [ "boolean", "null" ] }, "initial_price": { "description": "Additional amount charged on the first purchase, in the variant currency. For recurring variants without a trial, the first charge includes this amount plus renewal_price.", "type": [ "number", "null" ] }, "internal_notes": { "description": "Internal notes for the account.", "type": [ "string", "null" ] }, "override_tax_type": { "description": "Whether the variant's price includes tax: `inclusive` (tax is included in the price), `exclusive` (tax is added on top), or `unspecified`. Omit it or pass `null` to use the account's tax setting. On an account enrolled in the Whop tax service, `inclusive` or `exclusive` replaces the account's setting and `unspecified` keeps it. Otherwise it applies only where the account is the merchant of record: `inclusive` or `exclusive` replaces the account's setting when the account collects tax, and `unspecified` means the variant collects no tax. Where Whop is the merchant of record, the account's setting applies. Variants that differ only in this value are different variants.", "enum": [ null, "exclusive", "inclusive", "unspecified" ], "example": "exclusive", "type": [ "string", "null" ] }, "product": { "description": "Find or create a product by external identifier. Mutually exclusive with product_id.", "properties": { "collect_shipping_address": { "description": "Whether to collect a shipping address at checkout.", "type": [ "boolean", "null" ] }, "custom_statement_descriptor": { "description": "Custom card statement descriptor for the product, starting with WHOP*.", "type": [ "string", "null" ] }, "description": { "description": "Product description.", "type": [ "string", "null" ] }, "external_identifier": { "description": "Your unique identifier for the product.", "pattern": "\\S", "type": "string" }, "global_affiliate_percentage": { "description": "Percentage of revenue paid to global affiliates.", "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "Global affiliate program status.", "enum": [ null, "enabled", "disabled" ], "example": "enabled", "type": [ "string", "null" ] }, "headline": { "description": "Product headline.", "type": [ "string", "null" ] }, "product_tax_code_id": { "description": "Product tax code identifier.", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "Where to redirect the buyer after purchase.", "type": [ "string", "null" ] }, "route": { "description": "Product route.", "type": [ "string", "null" ] }, "title": { "description": "Product title.", "pattern": "\\S", "type": "string" }, "visibility": { "default": "hidden", "description": "Product visibility. Defaults to hidden.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "external_identifier", "title" ], "type": [ "object", "null" ] }, "product_id": { "description": "Existing product ID belonging to the account, prefixed `prod_`. Mutually exclusive with `product`.", "type": [ "string", "null" ] }, "renewal_price": { "description": "Recurring price in the variant currency.", "type": [ "number", "null" ] }, "title": { "description": "Variant title.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before renewal.", "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers.", "enum": [ null, "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": [ "string", "null" ] } }, "required": [ "currency" ], "type": "object" }, "variant_id": { "description": "An existing variant to charge for, prefixed `plan_`. Mutually exclusive with `variant`. Each variant may appear once — use `quantity` for multiple units.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" }, "member_id": { "description": "The member to charge, prefixed `mber_`. Required with `payment_method_id` unless `confirmation_token` is provided. With a `paypal` `payment_method` it names the buyer instead of `email`, and must belong to a user.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Custom metadata to attach to the payment.", "example": { "register": "front" }, "type": [ "object", "null" ] }, "off_session": { "description": "Whether the buyer is absent from your checkout and can't authenticate. Pass true when you charge the card without the buyer, such as a renewal on your own schedule. Pass false when the buyer is present, such as a one-click upsell right after checkout: the charge is processed as a customer-initiated card-on-file payment, and if the issuer asks the buyer to authenticate, the payment's status is `requires_action` with a `next_action` to send them to, after which they return to `return_url`. From API version 2026-10-07-1 it defaults to false when `return_url` is provided and to true otherwise; before that version it defaults to true. A saved Apple Pay, Google Pay or PayPal payment method is always charged with `off_session` true. Ignored unless `member_id` and `payment_method_id` are provided.", "example": true, "type": [ "boolean", "null" ] }, "payment_method": { "description": "A payment method named on this call rather than described by a confirmation token. `type` names it and the member named after it carries its details. Nothing is collected on this call: the payment is created first and the buyer or device then acts on the `next_action` the status endpoint serves. `card_present` (Tap to Pay): the reader collects against the payment with the client secret in `next_action`. `paypal`: the buyer approves on PayPal's page, reached through a `redirect` `next_action`, then returns to `return_url`; `member_id` or `email` names the buyer. Mutually exclusive with `confirmation_token` and `payment_method_id`, and with `member_id` except for `paypal`.", "properties": { "card_present": { "description": "Required when `type` is `card_present`.", "properties": { "platform": { "description": "Which Tap to Pay SDK collects the payment. Stripe offers Tap to Pay in different countries per platform, so eligibility is checked for the named one, as it is for the connection-token session.", "enum": [ "ios", "android" ], "example": "ios", "type": "string" } }, "required": [ "platform" ], "type": "object" }, "type": { "description": "The kind of payment method; the member named after it carries its details.", "enum": [ "card_present", "paypal" ], "example": "paypal", "type": "string" } }, "required": [ "type" ], "type": [ "object", "null" ] }, "payment_method_id": { "description": "The stored payment method to charge, prefixed `payt_`. It must belong to the member. Required unless `confirmation_token` is provided.", "example": "payt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "quote_id": { "description": "A payment quote from `POST /payment_quotes`, prefixed `pq_`. The payment charges exactly the quote: its purchase (its variants and quantities, or the `variant` it priced), which this body may then omit, its promo code, and its tax, the quote's `tax_amount` rather than a figure calculated now. Omit it, or send null, to have tax calculated when the payment is charged. The quote must belong to `account_id`. A purchase field you omit or send as null takes the quote's value; the buyer's email, the addresses and the payment method are this request's own, never the quote's. Whatever you do send must describe the quoted purchase: the same variants, quantities and promo code. A quote that priced `variant` takes only the same `variant` you sent to `POST /payment_quotes` (or omit the purchase to take the quoted one), never `variant_id` or `line_items`, and a quote that priced variants by id never takes `variant`. Unless the quote located no buyer (`located_by` is null), the address the payment carries (its shipping address, else its billing address) must put the buyer where the quote priced tax, by country, state and postal code; otherwise the payment is refused with 400 before the payment method is used. A quote located by IP address or by the country the buyer chose (`located_by` is `ip_address` or `presentment_country`) is a preview and cannot be paid. A quote is consumed by one payment: a declined payment keeps it and can be retried; a new payment needs a new quote. A quote cannot be charged by a processor that doesn't take quotes, such as a seller's own connected PayPal account; such a payment is refused before the payment method is used. A quote priced in a `presentment_currency` is charged in that currency at the quote's `exchange_rate`. A payment refused over its quote carries an error `code`. `quote_expired`: the quote has expired; quote again. `quote_tax_unavailable`: the quote could not price tax; quote again, or omit `quote_id`. `quote_preview_only`: the quote was located by IP address or by the country the buyer chose; quote again with the buyer's address. `quote_in_use` (409): another payment holds the quote. `quote_mismatch`: the purchase or the buyer's address is not the one quoted. `quote_rate_expired`: the exchange rate the quote was priced at has moved too far to charge; quote again. `payment_method_currency_unsupported`: the payment method cannot pay in the quote's currency; use another method, or quote again in another currency. `quote_processor_unsupported`: the payment would be processed by a processor that doesn't take quotes, such as a seller's own connected PayPal account; use another method, or omit `quote_id` to have tax calculated when the payment is charged.", "example": "pq_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "return_url": { "description": "Where the buyer continues after completing an off-site step such as 3D Secure. An absolute https URL without credentials, at most 2,048 characters. Required when a saved payment method is charged with `off_session` false; otherwise ignored unless `confirmation_token` or a `paypal` `payment_method` is provided.", "example": "https://shinetime.example/checkout/done", "type": [ "string", "null" ] }, "setup_future_usage": { "description": "Attests that the buyer was told the payment method will be saved for later charges, and saves it once they approve, so it can be charged with `member_id` and `payment_method_id`. PayPal shows the buyer the agreement to future charges on its approval page. Omit it for a one-time payment that saves nothing. Ignored unless a `paypal` `payment_method` is provided.", "enum": [ "off_session", null ], "example": "off_session", "type": [ "string", "null" ] }, "shipping_address": { "description": "Where physical goods ship, returned on the payment as `shipping_address`. Only the keys you supply are kept; omit it for digital goods.", "properties": { "city": { "description": "City name.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code, such as `US`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "1114 Bouldin Ave", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Unit B", "type": [ "string", "null" ] }, "name": { "description": "The recipient's full name, as it should appear on the shipping label.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78704", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, such as `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "statement_descriptor": { "description": "Overrides the text on the buyer's card statement for this payment only. Takes precedence over the product's and account's custom descriptors, and changes neither. Must start with `WHOP*` unless the business processes as the merchant of record. For businesses processing as the merchant of record, omit the `WHOP*` prefix; the descriptor appears as provided. Must be 5-22 characters, contain at least one letter, and use only Latin letters, numbers, spaces, underscores, hyphens, or asterisks.", "example": "WHOP*SHINETIME", "type": [ "string", "null" ] } }, "required": [], "type": "object" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "payment created from a stored payment method" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "confirmation_token combined with a stored method" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:charge" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payment method not on file for the member" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Create Payment", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/direct": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Charges a buyer for a variant from card details you hold yourself, for integrators whose own systems are PCI compliant. Card details are accepted only on the vault host, which tokenizes the card before it reaches Whop; the official SDKs route this operation there, and raw card details sent to the regular host are refused. Collection runs in the background, so the response is the payment as created, not its outcome: poll Retrieve payment status for how far it has got and what the buyer must still do, such as 3D Secure.", "operationId": "createDirectPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaymentInput" }, { "properties": { "affiliate_code": { "description": "The code an affiliate link carries, which is the affiliate's username. The affiliate is credited for this payment as on a checkout session. A code naming no one eligible to earn on the product is ignored, and the payment goes ahead. A promo code with its own affiliate takes precedence. No affiliate is credited on a variant without a product or on a purchase of several variants. At most 255 characters.", "example": "priyaraman", "type": [ "string", "null" ] }, "auto_capture_after_minutes": { "description": "Minutes after authorization at which Whop captures the hold automatically unless it has been voided. Requires `capture: false`. Between 5 and 5760 (4 days).", "example": 60, "maximum": 5760, "minimum": 5, "type": [ "integer", "null" ] }, "billing_details": { "description": "The buyer's billing details.", "properties": { "address": { "description": "The billing address.", "properties": { "city": { "description": "City.", "example": "San Francisco", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code.", "example": "US", "type": "string" }, "line1": { "description": "Street address, first line.", "example": "1 Market St", "type": "string" }, "line2": { "description": "Street address, second line.", "example": "Suite 400", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal code.", "example": "94105", "type": "string" }, "state": { "description": "State, province or region.", "example": "CA", "type": [ "string", "null" ] } }, "required": [ "postal_code", "country" ], "type": "object" }, "email": { "description": "The buyer's email. Resolves or creates the user the operation is for.", "example": "dana@shinetime.example", "type": "string" }, "name": { "description": "The name on the card.", "example": "Dana Shine", "type": "string" }, "phone": { "description": "The buyer's phone number in E.164 format.", "example": "+14155550123", "type": [ "string", "null" ] } }, "required": [ "name", "email", "address" ], "type": "object" }, "capture": { "description": "Whether to capture the payment immediately. Defaults to true. Pass false to place an authorization hold that must be captured in full within five days via the capture endpoint, or automatically after `auto_capture_after_minutes`.", "type": [ "boolean", "null" ] }, "line_items": { "description": "What the buyer is purchasing. Each entry names an existing variant by `variant_id`. Several entries form a cart, which requires every variant to be compatible, belong to this account, and use the same currency.", "example": [ { "quantity": 1, "variant_id": "plan_xxxxxxxxxxxxxx" } ], "items": { "properties": { "quantity": { "description": "How many units of the variant to purchase. Defaults to 1; more than 1 requires the variant to allow multiple quantities.", "example": 1, "maximum": 999999, "minimum": 1, "type": [ "integer", "null" ] }, "variant_id": { "description": "An existing variant to charge for, prefixed `plan_`. Each variant may appear once — use `quantity` for multiple units.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "variant_id" ], "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" }, "member_id": { "description": "The member to charge, prefixed `mber_`. When omitted the buyer is resolved from `billing_details.email`.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Custom metadata to attach to the payment.", "example": { "order_ref": "SHINE-4417" }, "type": [ "object", "null" ] }, "off_session": { "description": "Whether the charge is merchant-initiated, with the buyer not present. Defaults to false. When true, `payment_method.card.network_transaction_id` is required: a merchant-initiated charge on a card Whop has not charged before carries the id of the card's prior customer-initiated transaction. No 3D Secure step is offered: an issuer that requires the buyer to authenticate declines the charge, and the payment fails with that reason so the card can be charged again with the buyer present. A declined card is not saved.", "example": true, "type": [ "boolean", "null" ] }, "payment_method": { "description": "The payment method to charge, as the raw details the caller holds. Raw details are accepted only on the vault host, where Whop's vault tokenizes them in transit; the official SDKs route this operation there. Whop's own clients, which tokenize with the Basis Theory SDK, send the resulting token intent id to the regular host.", "properties": { "card": { "description": "The card to charge. Present when `type` is `card`.", "properties": { "details": { "description": "The card's raw fields. Sent to the vault host and tokenized before it reaches Whop; Whop's servers never receive the number.", "example": { "cvc": "123", "exp_month": 12, "exp_year": 2031, "number": "4242424242424242" }, "properties": { "cvc": { "description": "The card security code.", "example": "123", "type": "string" }, "exp_month": { "description": "The expiry month.", "example": 12, "maximum": 12, "minimum": 1, "type": "integer" }, "exp_year": { "description": "The four-digit expiry year.", "example": 2031, "type": "integer" }, "number": { "description": "The card number, digits only.", "example": "4242424242424242", "type": "string" } }, "required": [ "number", "exp_month", "exp_year" ], "type": "object", "x-whop-vault": { "bt_type": "card", "data": { "cvc": "cvc", "exp_month": "expiration_month", "exp_year": "expiration_year", "number": "number" }, "type": "card" } }, "network_transaction_id": { "description": "The network transaction id of the card's most recent customer-initiated transaction on another processor, when the caller brings a card it has charged before. Required for an `off_session` charge; on a setup it is kept with the saved card for its later charges. Up to 64 characters.", "example": "016153570198200", "type": [ "string", "null" ] } }, "required": [ "details" ], "type": "object" }, "type": { "description": "The kind of payment method; the member named after it carries the credential.", "enum": [ "card" ], "example": "card", "type": "string" } }, "required": [ "type" ], "type": "object" }, "plan": { "deprecated": true, "description": "Deprecated: send `variant`, which takes `billing_type` in place of `plan_type`. Accepted only from callers pinned to an API version before 2026-10-27-2.", "properties": { "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "type": [ "boolean", "null" ] }, "application_fee_amount": { "description": "Application fee the platform collects per unit, in the variant currency (5.00 means $5.00 for USD). Must be positive and below the initial price for one-time variants or renewal price for recurring variants. Paid to the parent account alongside other processing fees; collection is capped to remaining proceeds. Applies to subsequent payments on recurring variants. Only valid for connected accounts with a parent account.", "type": [ "number", "null" ] }, "billing_period": { "description": "Recurring billing interval in days.", "type": [ "integer", "null" ] }, "currency": { "description": "Currency code for the variant prices.", "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "description": { "description": "Variant description.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Days until access expires.", "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Create a new variant instead of reusing a matching variant.", "type": [ "boolean", "null" ] }, "initial_price": { "description": "Additional amount charged on the first purchase, in the variant currency. For recurring variants without a trial, the first charge includes this amount plus renewal_price.", "type": [ "number", "null" ] }, "internal_notes": { "description": "Internal notes for the account.", "type": [ "string", "null" ] }, "override_tax_type": { "description": "Whether the variant's price includes tax: `inclusive` (tax is included in the price), `exclusive` (tax is added on top), or `unspecified`. Omit it or pass `null` to use the account's tax setting. On an account enrolled in the Whop tax service, `inclusive` or `exclusive` replaces the account's setting and `unspecified` keeps it. Otherwise it applies only where the account is the merchant of record: `inclusive` or `exclusive` replaces the account's setting when the account collects tax, and `unspecified` means the variant collects no tax. Where Whop is the merchant of record, the account's setting applies. Variants that differ only in this value are different variants.", "enum": [ null, "exclusive", "inclusive", "unspecified" ], "example": "exclusive", "type": [ "string", "null" ] }, "plan_type": { "description": "Billing model for the variant.", "enum": [ null, "renewal", "one_time" ], "example": "renewal", "type": [ "string", "null" ] }, "product": { "description": "Find or create a product by external identifier. Mutually exclusive with product_id.", "properties": { "collect_shipping_address": { "description": "Whether to collect a shipping address at checkout.", "type": [ "boolean", "null" ] }, "custom_statement_descriptor": { "description": "Custom card statement descriptor for the product, starting with WHOP*.", "type": [ "string", "null" ] }, "description": { "description": "Product description.", "type": [ "string", "null" ] }, "external_identifier": { "description": "Your unique identifier for the product.", "pattern": "\\S", "type": "string" }, "global_affiliate_percentage": { "description": "Percentage of revenue paid to global affiliates.", "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "Global affiliate program status.", "enum": [ null, "enabled", "disabled" ], "example": "enabled", "type": [ "string", "null" ] }, "headline": { "description": "Product headline.", "type": [ "string", "null" ] }, "product_tax_code_id": { "description": "Product tax code identifier.", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "Where to redirect the buyer after purchase.", "type": [ "string", "null" ] }, "route": { "description": "Product route.", "type": [ "string", "null" ] }, "title": { "description": "Product title.", "pattern": "\\S", "type": "string" }, "visibility": { "default": "hidden", "description": "Product visibility. Defaults to hidden.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "external_identifier", "title" ], "type": [ "object", "null" ] }, "product_id": { "description": "Existing product ID belonging to the account, prefixed `prod_`. Mutually exclusive with `product`.", "type": [ "string", "null" ] }, "renewal_price": { "description": "Recurring price in the variant currency.", "type": [ "number", "null" ] }, "title": { "description": "Variant title.", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before renewal.", "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers.", "enum": [ null, "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": [ "string", "null" ] } }, "required": [ "currency" ], "type": "object" }, "plan_id": { "deprecated": true, "description": "Deprecated: send `variant_id`. Accepted only from callers pinned to an API version before 2026-10-27-2.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "quote_id": { "description": "A payment quote from `POST /payment_quotes`, prefixed `pq_`. The payment charges exactly the quote: its purchase (its variants and quantities, or the `variant` it priced), which this body may then omit, its promo code, and its tax, the quote's `tax_amount` rather than a figure calculated now. Omit it, or send null, to have tax calculated when the payment is charged. The quote must belong to `account_id`. A purchase field you omit or send as null takes the quote's value; the buyer's email, the addresses and the payment method are this request's own, never the quote's. Whatever you do send must describe the quoted purchase: the same variants, quantities and promo code. A quote that priced `variant` takes only the same `variant` you sent to `POST /payment_quotes` (or omit the purchase to take the quoted one), never `variant_id` or `line_items`, and a quote that priced variants by id never takes `variant`. Unless the quote located no buyer (`located_by` is null), the address the payment carries (its shipping address, else its billing address) must put the buyer where the quote priced tax, by country, state and postal code; otherwise the payment is refused with 400 before the payment method is used. A quote located by IP address or by the country the buyer chose (`located_by` is `ip_address` or `presentment_country`) is a preview and cannot be paid. A quote is consumed by one payment: a declined payment keeps it and can be retried; a new payment needs a new quote. A quote cannot be charged by a processor that doesn't take quotes, such as a seller's own connected PayPal account; such a payment is refused before the payment method is used. A quote priced in a `presentment_currency` is charged in that currency at the quote's `exchange_rate`. A payment refused over its quote carries an error `code`. `quote_expired`: the quote has expired; quote again. `quote_tax_unavailable`: the quote could not price tax; quote again, or omit `quote_id`. `quote_preview_only`: the quote was located by IP address or by the country the buyer chose; quote again with the buyer's address. `quote_in_use` (409): another payment holds the quote. `quote_mismatch`: the purchase or the buyer's address is not the one quoted. `quote_rate_expired`: the exchange rate the quote was priced at has moved too far to charge; quote again. `payment_method_currency_unsupported`: the payment method cannot pay in the quote's currency; use another method, or quote again in another currency. `quote_processor_unsupported`: the payment would be processed by a processor that doesn't take quotes, such as a seller's own connected PayPal account; use another method, or omit `quote_id` to have tax calculated when the payment is charged.", "example": "pq_xxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "return_url": { "description": "Where the buyer continues after completing an off-site step such as 3D Secure. An absolute https URL without credentials, at most 2,048 characters.", "example": "https://shinetime.example/checkout/done", "type": [ "string", "null" ] }, "setup_future_usage": { "description": "Attests that the buyer was told the card will be saved for later charges. `off_session` for merchant-initiated charges, `on_session` for buyer-present ones.", "enum": [ "off_session", "on_session", null ], "example": "off_session", "type": [ "string", "null" ] }, "statement_descriptor": { "description": "Overrides the text on the buyer's card statement for this payment only. Must start with `WHOP*`, be 5-22 characters, contain at least one letter, and use only Latin letters, numbers, spaces, underscores, hyphens, or asterisks.", "example": "WHOP*SHINETIME", "type": [ "string", "null" ] } }, "required": [ "payment_method", "billing_details" ], "type": "object" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "payment created from card details" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "servers": [ { "url": "https://vault-api.whop.com/api/v1", "x-fern-server-name": "vault" }, { "url": "https://sandbox-vault-api.whop.com/api/v1", "x-fern-server-name": "vault" } ], "summary": "Create Payment with Card Details", "tags": [ "Payments" ], "x-whop-docs": "gated", "x-whop-docs-groups": [ "direct-card" ], "x-whop-vault": true }, "x-whop-surface": "native" }, "/payments/summary": { "get": { "description": "Totals up the same payments the list returns, so you can build status tabs and filter options without paging through them. Takes the same filters as List Payments.", "operationId": "retrievePaymentSummary", "parameters": [ { "description": "Which breakdowns to return, keyed by these names under `groups`. Repeat the parameter to ask for several; omit it for all of them.", "in": "query", "name": "groups", "required": false, "schema": { "items": { "enum": [ "substatus", "currency" ], "example": "substatus", "type": "string" }, "type": "array" } }, { "description": "Only payments charged by this account, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only payments in any of these lifecycle states. Repeat the parameter to pass several.", "in": "query", "name": "statuses", "required": false, "schema": { "items": { "enum": [ "open", "authorized", "paid", "pending", "uncollectible", "unresolved", "void" ], "example": "paid", "type": "string" }, "type": "array" } }, { "description": "Only payments whose `substatus` is any of these. Repeat the parameter to pass several.", "in": "query", "name": "substatuses", "required": false, "schema": { "items": { "enum": [ "succeeded", "requires_capture", "pending", "failed", "blocked", "past_due", "canceled", "price_too_low", "uncollectible", "refunded", "auto_refunded", "partially_refunded", "dispute_warning", "dispute_needs_response", "dispute_warning_needs_response", "resolution_needs_response", "dispute_under_review", "dispute_warning_under_review", "resolution_under_review", "dispute_won", "dispute_warning_closed", "resolution_won", "dispute_lost", "dispute_closed", "resolution_lost", "drafted", "incomplete", "unresolved" ], "example": "succeeded", "type": "string" }, "type": "array" } }, { "description": "Only payments charged for any of these reasons. Repeat the parameter to pass several.", "in": "query", "name": "billing_reasons", "required": false, "schema": { "items": { "enum": [ "subscription_create", "subscription_cycle", "subscription_update", "one_time", "manual", "subscription" ], "example": "subscription_cycle", "type": "string" }, "type": "array" } }, { "description": "Only payments presented in any of these three-letter currencies. Repeat the parameter to pass several.", "in": "query", "name": "currencies", "required": false, "schema": { "items": { "example": "usd", "type": "string" }, "type": "array" } }, { "description": "Only payments priced by any of these variants, each prefixed `plan_`. Repeat the parameter to pass several.", "in": "query", "name": "variant_ids", "required": false, "schema": { "items": { "example": "plan_xxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only payments for any of these products, each prefixed `prod_`. Repeat the parameter to pass several.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only payments paid with any of these methods. Repeat the parameter to pass several.", "in": "query", "name": "payment_methods", "required": false, "schema": { "items": { "enum": [ "mastercard", "visa", "amex", "discover", "unionpay", "jcb", "diners", "link", "troy", "visadankort", "visabancontact", "china_union_pay", "rupay", "jcbrupay", "elo", "maestro", "tarjeta_naranja", "cirrus", "nspk_mir", "verve", "ebt", "private_label", "local_brand", "uatp", "wexcard", "uzcard", "meeza", "hrg_store_card", "girocard", "fuel_card", "dankort", "carnet", "atm_card", "china_union_payuzcard", "codensa", "cabal", "hipercard", "jcblankapay", "cmi", "aura", "accel", "culiance", "nyce", "pulse", "star", "eftpos", "alelo", "edenred", "sodexo", "unknown", "acss_debit", "addi", "affirm", "afterpay_clearpay", "alipay", "alipayhk", "alma", "amazon_pay", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_present", "card_installments_three", "card_installments_six", "card_installments_twelve", "cashapp", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "duitnow_qr", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "giropay", "google_pay", "gopay", "grabpay", "id_bank_transfer", "ideal", "interac", "kakao_pay", "klarna", "klarna_pay_now", "konbini", "kr_card", "kr_market", "kriya", "kueski", "mb_way", "m_pesa", "mercado_pago", "mercado_pago_ar", "mercado_pago_mx", "mobilepay", "modo", "mondu", "multibanco", "naver_pay", "nequi", "netbanking", "ng_bank", "ng_bank_transfer", "ng_card", "ng_market", "ng_ussd", "ng_wallet", "nupay", "nz_bank_account", "oney", "oney_3x", "oney_4x", "opay", "oxxo", "p24", "pago_efectivo", "pse", "pay_by_bank", "payco", "paynow", "paypal", "paypal_express", "paypay", "payto", "payto_email", "payto_phone", "payto_bank_account", "pix", "platform_balance", "promptpay", "qris", "rapipago", "rechnung", "revolut_pay", "samsung_pay", "satispay", "scalapay", "sencillito", "sepa_debit", "sequra", "servipag", "sezzle", "shop_pay", "shopeepay", "sofort", "south_korea_market", "spei", "splitit", "sunbit", "swish", "tabby", "tamara", "touch_n_go", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "vipps", "webpay", "wechat_pay", "whop_pay", "yape", "zip", "coinflow", "tap_to_pay" ], "example": "visa", "type": "string" }, "type": "array" } }, { "description": "Only payments in any of these tracking states. Requires `account_id` and the shipment:basic:read permission.", "in": "query", "name": "tracking_states", "required": false, "schema": { "items": { "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error", "needs_tracking", "missing_tracking" ], "example": "needs_tracking", "type": "string" }, "type": "array" } }, { "description": "Only payments created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments refunded after this ISO 8601 timestamp.", "in": "query", "name": "refunded_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments refunded before this ISO 8601 timestamp.", "in": "query", "name": "refunded_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments with a dispute alert after this ISO 8601 timestamp.", "in": "query", "name": "dispute_alerted_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments with a dispute alert before this ISO 8601 timestamp.", "in": "query", "name": "dispute_alerted_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments with a dispute opened after this ISO 8601 timestamp.", "in": "query", "name": "dispute_created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payments with a dispute opened before this ISO 8601 timestamp.", "in": "query", "name": "dispute_created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Search payments by payment ID, dispute ID, user ID, membership ID, user email, name, or username.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only for searches: with `query`, also search the account's connected accounts. Requires `account_id` and `query`, and is a 400 without either; it never lists connected accounts' payments on its own. Matches on payment, dispute, user or membership ID, buyer email, or a card's first 6 or 8 digits and last 4 separated by a space or dash (`424242 4242`). Free-text queries such as a name search only the named account. Connected accounts' payments are returned only for connected accounts you can read payments on.", "in": "query", "name": "include_connected_accounts", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "groups": { "description": "One entry per requested breakdown, keyed by the field it groups on. A field you did not ask for is absent.", "properties": { "currency": { "additionalProperties": { "type": "integer" }, "description": "How many of the matching payments are in each currency, keyed by three-letter code. Only currencies with at least one payment are present.", "example": { "usd": 1 }, "type": "object" }, "substatus": { "description": "How many of the matching payments are in each substatus. Every substatus is present, including those with a count of zero.", "properties": { "auto_refunded": { "example": 0, "type": "integer" }, "blocked": { "example": 0, "type": "integer" }, "canceled": { "example": 0, "type": "integer" }, "dispute_closed": { "example": 0, "type": "integer" }, "dispute_lost": { "example": 0, "type": "integer" }, "dispute_needs_response": { "example": 0, "type": "integer" }, "dispute_under_review": { "example": 0, "type": "integer" }, "dispute_warning": { "example": 0, "type": "integer" }, "dispute_warning_closed": { "example": 0, "type": "integer" }, "dispute_warning_needs_response": { "example": 0, "type": "integer" }, "dispute_warning_under_review": { "example": 0, "type": "integer" }, "dispute_won": { "example": 0, "type": "integer" }, "drafted": { "example": 0, "type": "integer" }, "failed": { "example": 0, "type": "integer" }, "incomplete": { "example": 1, "type": "integer" }, "partially_refunded": { "example": 0, "type": "integer" }, "past_due": { "example": 0, "type": "integer" }, "pending": { "example": 0, "type": "integer" }, "price_too_low": { "example": 0, "type": "integer" }, "refunded": { "example": 0, "type": "integer" }, "requires_capture": { "example": 0, "type": "integer" }, "resolution_lost": { "example": 0, "type": "integer" }, "resolution_needs_response": { "example": 0, "type": "integer" }, "resolution_under_review": { "example": 0, "type": "integer" }, "resolution_won": { "example": 0, "type": "integer" }, "succeeded": { "example": 0, "type": "integer" }, "uncollectible": { "example": 0, "type": "integer" }, "unresolved": { "example": 0, "type": "integer" } }, "required": [ "succeeded", "requires_capture", "pending", "failed", "blocked", "past_due", "canceled", "price_too_low", "uncollectible", "refunded", "auto_refunded", "partially_refunded", "dispute_warning", "dispute_needs_response", "dispute_warning_needs_response", "resolution_needs_response", "dispute_under_review", "dispute_warning_under_review", "resolution_under_review", "dispute_won", "dispute_warning_closed", "resolution_won", "dispute_lost", "dispute_closed", "resolution_lost", "drafted", "incomplete", "unresolved" ], "type": "object" } }, "type": "object" }, "total": { "description": "How many payments match the filters.", "example": 1, "type": "integer" } }, "required": [ "total", "groups" ], "type": "object" } } }, "description": "summary returned" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "Retrieve Payment Summary", "tags": [ "Payments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/payments/{id}": { "get": { "description": "Returns one payment, including every purchased line item with its quantity and subtotal. Related records are ids — resolve a variant, membership, member or shipment on its own endpoint, and list this payment's refunds, disputes or Resolution Center cases with `?payment_id=`.", "operationId": "retrievePayment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "payment retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:basic:read" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown payment" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "Retrieve Payment", "tags": [ "Payments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment, prefixed `pay_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a payment's `shipping_address` or `return_url`.", "operationId": "updatePayment", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "return_url": { "description": "Where the buyer continues after completing an off-site step. An absolute https URL without credentials, at most 2,048 characters. Only for payments created with a `confirmation_token`, and only until the buyer has returned. Omit it to leave it unchanged.", "example": "https://shinetime.example/checkout/thanks", "type": "string" }, "shipping_address": { "description": "The complete new shipping address. It replaces the current address as a whole and is never merged with it, so send every field the address should have, including the ones that are not changing. Any field you leave out is cleared: sending only `city` leaves an address with nothing but a city. Pass null to remove the address, or omit `shipping_address` to leave it unchanged. It cannot change once a shipment exists for the payment.", "properties": { "city": { "description": "City name.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code, such as `US`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "1114 Bouldin Ave", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Unit B", "type": [ "string", "null" ] }, "name": { "description": "The recipient's full name, as it should appear on the shipping label.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78704", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, such as `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "shipping address replaced" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "shipping_address is not an object" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:manage" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payment not found" } }, "security": [ { "bearerAuth": [ "payment:manage" ] } ], "summary": "Update Payment", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/{id}/capture": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Captures the full amount of a card payment created with `capture: false`. The payment must still be in `requires_capture` before `capture_expires_at`. Partial capture, multiple captures, capturing more than the authorized amount, and tips are not supported.", "operationId": "capturePayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatus" } } }, "description": "Payment captured" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Credential lacks a capture scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Payment not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Capture payment", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/{id}/fees": { "get": { "description": "Returns the fee breakdown of one payment — Whop's fee, processing, affiliate and other lines — each in the currency it was collected in and converted to the payment's settlement currency. The list is complete in one page.", "operationId": "listPaymentFees", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PaymentFee" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": null, "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "fees listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown payment" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "List Payment Fees", "tags": [ "Payments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment whose fees to list, prefixed `pay_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/payments/{id}/generate_pdf": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment whose receipt to generate, prefixed `pay_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Generates the payment's receipt (invoice) as a PDF and returns a short-lived link to download it. Each call generates a new file and link, so this endpoint does not replay `Idempotency-Key` responses.", "operationId": "generatePaymentPdf", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPdf" } } }, "description": "receipt PDF generated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing payment:basic:read" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown payment" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "Generate Payment PDF", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/{id}/refund": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment to refund, prefixed `pay_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Refunds all or part of a payment through the processor that charged it, and updates its membership to match. The buyer is emailed, the affiliate commission on the payment is clawed back, and any open Resolution Center case on the payment is closed.", "operationId": "refundPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "metadata": { "additionalProperties": { "type": "string" }, "description": "Your own key-value data to attach to the refund, returned on it and on its `refund.created` and `refund.updated` webhooks. At most 50 keys; keys up to 100 characters and values up to 500.", "example": { "refund_id": "ref_8f2k1" }, "type": [ "object", "null" ] }, "partial_amount": { "description": "The amount to refund, stated in this payment's `currency` like every other amount on it. When the buyer was billed in a different currency, it is converted at the payment's own exchange rate before the refund is issued. An amount that covers everything still refundable refunds the rest of the payment — omit it to refund the rest without having to work out what that is.", "example": 49.0, "type": [ "number", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "payment refunded" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "partial_amount is not a number" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:manage" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payment not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:manage" ] } ], "summary": "Refund Payment", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/{id}/retry": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment to retry, prefixed `pay_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Charges an unpaid payment again with its original payment method and variant. A payment can typically be retried once, and only while its membership is active, trialing or past due, or when it is a membership's failed first payment.", "operationId": "retryPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "payment retried" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payment not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:manage" ] } ], "summary": "Retry Payment", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/{id}/void": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment to void, prefixed `pay_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Voids or cancels an eligible payment. The request is rejected if the payment is no longer eligible. Some processors confirm the release of a card authorization asynchronously: the payment is then returned still `authorized`, and a `payment.canceled` webhook follows once the hold is released.", "operationId": "voidPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "payment voided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payment not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:manage" ] } ], "summary": "Void Payment", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/{payment_id}/resume": { "post": { "description": "Charges the saved card again, with the buyer present, for a payment their bank declined until they authenticate (such as with 3DS). Retrieve the payment afterward to get the bank's challenge from `next_action`; once the buyer completes it, they land on `return_url`, or on Whop's hosted verification page if none was given. Only the buyer can call this, with the payment's `client_secret` in the body, an OAuth token for their own account with the `member:payment_methods:use` scope, or the token from a verified `payment` session intent. An API key gets a `403`. Has no effect on a payment that is not waiting on authentication.", "operationId": "resumePayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "payment_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_secret": { "description": "The payment's own `client_secret`, for a buyer without a token.", "type": "string" }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters. Defaults to Whop's hosted verification page. Ignored when the payment is not waiting on authentication.", "example": "https://shinetime.example/billing/recovered", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatus" } } }, "description": "Resume requested" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "The resume could not start" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "A seller cannot charge the buyer's saved card" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Payment not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ {}, { "bearerAuth": [ "member:payment_methods:use" ] } ], "summary": "Resume a parked renewal", "tags": [ "Payments" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/payments/{payment_id}/return_url": { "patch": { "description": "Changes where the buyer lands after completing an off-site step, up until they return. Accepts either a secret key or the payment's own `client_secret` in the body, so the surface that knows the final destination can set it.", "operationId": "updateReturnUrlPayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "payment_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_secret": { "description": "The payment's own `client_secret`, for a caller without a secret key.", "type": "string" }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters.", "example": "https://shinetime.example/checkout/thanks", "type": "string" } }, "required": [ "return_url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatus" } } }, "description": "Return URL updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid return URL" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" } }, "security": [ {}, { "bearerAuth": [ "payment:manage" ] }, { "bearerAuth": [ "member:payment_methods:use" ] } ], "summary": "Update payment return URL", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payments/{payment_id}/status": { "get": { "description": "Retrieves how far a payment has got and what the buyer must do next, if anything. A payment is collected in the background, so poll this rather than reading the create response. Accepts either a secret key or the payment's own `client_secret` as a query parameter, so the surface collecting the payment can poll it directly.", "operationId": "retrieveStatusPayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "payment_id", "required": true, "schema": { "type": "string" } }, { "description": "The payment's own `client_secret`, for a caller without a secret key.", "in": "query", "name": "client_secret", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatus" } } }, "description": "Payment status retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Payment not found" } }, "security": [ {}, { "bearerAuth": [ "payment:basic:read" ] }, { "bearerAuth": [ "member:payment_methods:use" ] } ], "summary": "Retrieve payment status", "tags": [ "Payments" ] }, "x-whop-surface": "native" }, "/payout_accounts/{id}": { "get": { "description": "Retrieves the details of an existing payout account.\n\nRequired permissions:\n - `payout:account:read`", "operationId": "retrievePayoutAccount", "parameters": [ { "description": "The unique identifier of the payout account to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "poact_xxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAccount" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:account:read" ] } ], "summary": "Retrieve payout account", "tags": [ "Payout accounts" ], "x-group-title": "Payouts" } }, "/payout_methods": { "get": { "description": "Lists the active payout methods configured for an account, newest first.\n\nRequired permissions:\n - `payout:destination:read`", "operationId": "listPayoutMethod", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": true, "schema": { "description": "The unique identifier of the company to list payout methods for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for PayoutToken.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/PayoutMethodListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:destination:read" ] } ], "summary": "List payout methods", "tags": [ "Payout methods" ], "x-group-title": "Payouts" } }, "/payout_methods/{id}": { "get": { "description": "Retrieves the details of an existing payout method.\n\nRequired permissions:\n - `payout:destination:read`", "operationId": "retrievePayoutMethod", "parameters": [ { "description": "The unique identifier of the payout method to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "potk_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutMethod" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "payout:destination:read" ] } ], "summary": "Retrieve payout method", "tags": [ "Payout methods" ], "x-group-title": "Payouts" } }, "/payouts": { "get": { "description": "Lists an account's or user's payouts, newest first.", "operationId": "listPayouts", "parameters": [ { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional currency code filter, for example `usd`.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Filter to payouts whose `status` reads this word, matching exactly what this version displays — `reversed` finds settled payouts the bank later returned. Requires Api-Version-Date 2026-08-21 or later.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "type": "string" } }, { "description": "Filter by how the payout was created. Payouts created before source tracking or through internal tooling carry no source and never match.", "in": "query", "name": "source", "required": false, "schema": { "enum": [ "api", "dashboard", "automatic" ], "type": "string" } }, { "description": "Filter to payouts sent to one saved payout method (a pytk_ identifier). An unknown id matches nothing.", "in": "query", "name": "payout_method_id", "required": false, "schema": { "type": "string" } }, { "description": "Only payouts created before this ISO 8601 time (exclusive).", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only payouts created at or after this ISO 8601 time (inclusive).", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "cancelable": { "description": "Whether `POST /payouts/{id}/cancel` would act on this payout right now: `true` while it is `in_review`, while it is `processing` with nothing yet submitted to the payout provider, or while a submitted payout can still be asked to cancel at the provider. `false` once the money has arrived or the payout has already ended.", "example": true, "type": "boolean" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a payout funded by a conversion request it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled payout funded by a conversion request can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. Match it to the settled payout in `GET /payouts`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "The payment description sent with the payout, or `null` if no descriptor was set. When set, 5-80 printable ASCII characters.", "example": "MYCOMPANY", "maxLength": 80, "minLength": 5, "type": [ "string", "null" ] }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "cancelable", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "statement_descriptor", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "payouts listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:withdrawal:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account or user not found" } }, "security": [ { "bearerAuth": [ "payout:withdrawal:read" ] } ], "summary": "List Payouts", "tags": [ "Payouts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Sends money from an account or user balance to a saved payout method for that owner.", "operationId": "createPayout", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 50.0, "currency": "usd", "notes": "Detailing supplies restock", "payout_method_id": "potk_xxxxxxxxxxxxxx", "speed": "standard" }, "required": [ "account_id" ] }, { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 50.0, "currency": "usd", "notes": "Detailing supplies restock", "payout_method_id": "potk_xxxxxxxxxxxxxx", "speed": "standard" }, "required": [ "user_id" ] } ], "properties": { "account_id": { "description": "Account to pay out from, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "acknowledge_bank_warning": { "description": "Set to `true` to continue when the destination bank could not confirm the payout method account holder's name, or `false` to have the payout refused in that case so the account holder can correct the name or link their bank first. Omitting the field skips the warning gate — a client that cannot show the warning keeps its pre-gate behavior.", "example": true, "type": "boolean" }, "amount": { "description": "The amount to pay out in the specified currency.", "example": 50.0, "format": "float", "type": "number" }, "currency": { "description": "The currency to pay out. Balances are held per currency and the payout draws only from the balance in this currency, so match the currency the funds arrived in — for example `cad` for an account funded by CAD transfers. When omitted, uses `usd` if that balance can cover a withdrawal, otherwise the account's only other funded currency.", "example": "usd", "type": "string" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Key-value data to attach to the payout, echoed on every read and in webhook payloads. At most 50 keys, key names up to 40 characters, string values up to 500 characters. Never store secrets or regulated personal data here — webhook bodies are retained for delivery inspection.", "example": { "batch_id": "2026-08-18" }, "maxProperties": 50, "propertyNames": { "maxLength": 40 }, "type": "object" }, "notes": { "description": "Free-form notes to attach to the payout, with a maximum of 255 characters. Omit or pass `null` for no notes.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "payment_method_id": { "description": "A saved card of the account, prefixed `payt_`, to charge for this payout instead of paying from the balance. Requires a `quote_token` from `POST /payouts/quotes` made with the same card and `amount`. Only for business accounts paying a saved recipient in `usd` at `standard` speed. The payout is returned under the card payment's `pay_` id until it is submitted, then `GET /payouts/{id}` returns the submitted payout.", "type": "string" }, "payout_method_id": { "description": "The saved payout method to deliver to (a potk_ identifier).", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "platform_covers_fees": { "description": "Whether the parent platform covers the payout fee instead of the account being paid out. Omit to use the platform's configured fee coverage policy; pass `false` to opt out of it. `true` is only accepted for accounts that belong to a platform, and requires the platform's policy to cover this payout method's category or a caller authorized to manage the platform's child account fees.", "example": true, "type": "boolean" }, "quote_token": { "description": "The server-signed quote_token returned by POST /payouts/quotes. Send it when the ledger account's payout_quote_required is true. A business with quote enforcement on refuses a payout without it with the invalid_payout_quote error type. When provided, Whop will not commit a provider payout below the destination amount the quote showed.", "example": "signed-payout-quote", "type": "string" }, "speed": { "default": "standard", "description": "How fast the funds should arrive. `instant` is only accepted when the account and payout method are eligible; otherwise the payout is rejected.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "Payment description sent with the payout, such as an invoice number or what it pays for. Must be 5-80 printable ASCII characters (letters, digits, spaces and punctuation); Whop sends it in upper case. Not all countries and banks show it on the recipient's statement, and it is not the sender name. Without a `quote_token`, omit or pass `null` to use the default descriptor. With a `quote_token`, set this value when creating the quote; the payout request may omit it but cannot add or change it.", "example": "ACME INV-10432", "maxLength": 80, "minLength": 5, "pattern": "^[ -~]+$", "type": [ "string", "null" ] }, "user_id": { "description": "User to pay out from, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "amount", "payout_method_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "50.0", "format": "decimal", "type": "string" }, "cancelable": { "description": "Whether `POST /payouts/{id}/cancel` would act on this payout right now: `true` while it is `in_review`, while it is `processing` with nothing yet submitted to the payout provider, or while a submitted payout can still be asked to cancel at the provider. `false` once the money has arrived or the payout has already ended.", "example": true, "type": "boolean" }, "created_at": { "description": "When the payout was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Null until the payout settles; appears on the payout in GET /payouts once assigned.", "example": null, "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method. On a payout funded by a conversion request it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": null, "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account. Null until the payout settles.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Null until the payout settles; appears on the payout in GET /payouts once assigned.", "example": null, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "2.5", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_` — the id POST returns is the id GET /payouts lists. Conversion requests created before this version keep answering under their `cofr_` id. A payout paid from a card with `payment_method_id` answers under its card payment's `pay_` id until it is submitted.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled payout funded by a conversion request can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout. Null until the payout settles.", "example": "MassPay", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Ops checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-payout-icon", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "The id of the conversion request that funds this payout, prefixed `cofr_`; `null` when the payout has none.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "instant", "type": "string" }, "statement_descriptor": { "description": "The payment description sent with the payout, or `null` if no descriptor was set. When set, 5-80 printable ASCII characters.", "example": "MYCOMPANY", "maxLength": 80, "minLength": 5, "type": [ "string", "null" ] }, "status": { "description": "Current payout status, in the same vocabulary as GET /payouts.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "pending_debit", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Always `null` here — it is assigned when the payout is submitted to the bank, and appears on the payout in GET /payouts once it has been sent; payouts not sent over ACH never get one.", "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "cancelable", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "statement_descriptor", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" } } }, "description": "payout created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request is invalid or cannot be fulfilled, for example insufficient balance" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:withdraw_funds scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout method not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "Create Payout", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "/payouts/methods": { "get": { "description": "Lists the bank accounts, wallets, and crypto addresses an account or user can pay out to, newest first.", "operationId": "listPayoutMethods", "parameters": [ { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional status filter. `created` means saved but unused, `active` means a payout through it succeeded, `broken` means the last payout failed and the method needs fixing.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "created", "active", "broken" ], "type": "string" } }, { "description": "Optional payout amount in whole currency units, for example `250.00`. When provided, each method includes a quote with the estimated fee, amount received, and delivery date for that amount.", "in": "query", "name": "amount", "required": false, "schema": { "type": "number" } }, { "description": "Currency code of the amount, for example `usd`. Only meaningful with amount or include_limits.", "in": "query", "name": "currency", "required": false, "schema": { "default": "usd", "type": "string" } }, { "description": "When true, also includes bill-pay recipient methods tied to this funding account. Defaults to false, returning only the account's own payout methods.", "in": "query", "name": "include_recipients", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "When true, the response also carries limits — the live per-speed payout caps the account's payout requests are validated against, in the requested currency. Requires the payout:withdrawal:read scope.", "in": "query", "name": "include_limits", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account_reference": { "description": "Masked identifier for the destination, such as the last four digits of a bank account.", "example": "••••6789", "type": [ "string", "null" ] }, "bank_verification_state": { "description": "Lifecycle trust state: `checking` (verification still running), `verified` (bank confirmed ownership or a payout already completed to it), `no_data` (verification unavailable or bank returned no ownership data), `warning` (bank could not confirm the destination's owner), `broken` (payouts failed with a permanent account error), `null` (never checked).", "enum": [ "checking", "verified", "no_data", "warning", "broken", null ], "example": "verified", "type": [ "string", "null" ] }, "created_at": { "description": "When the payout method was added.", "example": "2026-06-15T09:00:00.000Z", "format": "date-time", "type": "string" }, "destination_currency": { "description": "Currency payouts are delivered in for this method.", "example": "usd", "type": "string" }, "estimated_arrival": { "description": "Estimated arrival times before an amount-specific quote is requested. Null when the method is not currently eligible.", "properties": { "instant": { "description": "Estimated instant-delivery arrival, or null when unavailable.", "example": "2026-07-30T12:30:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "standard": { "description": "Estimated standard-delivery arrival, or null when unavailable.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "standard", "instant" ], "type": [ "object", "null" ] }, "fee_structure": { "description": "Configured fee terms for this payout method. Null when the method is not currently eligible. An amount-specific quote remains authoritative.", "properties": { "currency": { "description": "Currency code of fixed_amount.", "example": "usd", "type": "string" }, "fixed_amount": { "description": "Fixed fee charged, denominated in `currency`.", "example": 0.25, "format": "float", "type": "number" }, "percentage": { "description": "Percentage of the payout amount charged as a fee.", "example": 0.0, "format": "float", "type": "number" } }, "required": [ "percentage", "fixed_amount", "currency" ], "type": [ "object", "null" ] }, "id": { "description": "Payout method ID.", "example": "pyot_xxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "Name of the bank or institution receiving payouts.", "example": "Frost Bank", "type": [ "string", "null" ] }, "is_clone": { "description": "Whether this method is a copy of one saved on another of the payer's accounts.", "example": false, "type": "boolean" }, "is_default": { "description": "Whether this is the default payout method for the account.", "example": true, "type": "boolean" }, "last_paid_out_at": { "description": "When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. `null` when nothing has been paid out to it yet.", "example": "2026-08-02T15:30:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "linked_via_plaid": { "description": "Whether the payer added this method by signing in to their bank rather than typing account details.", "example": false, "type": "boolean" }, "needs_plaid_reconnect": { "description": "Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.", "example": false, "type": "boolean" }, "nickname": { "description": "User-defined label for the payout method.", "example": "Business checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "payer_name": { "description": "Display name of the payout rail, such as `ACH Bank Deposit`.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "quote": { "description": "Fee and delivery estimate for paying out the requested amount through this method. Null unless an amount was provided, or when the estimate is unavailable.", "properties": { "amount": { "description": "The payout amount the quote is for.", "example": 500.0, "format": "float", "type": "number" }, "currency": { "description": "Currency of the quoted amount.", "example": "usd", "type": "string" }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency.", "example": 1.0, "format": "float", "type": "number" }, "instant": { "description": "Instant-delivery estimate. Null if the method does not support instant delivery, instant delivery is unavailable for the account, or the amount does not cover the fee.", "properties": { "fee": { "description": "Total fee charged, in the payout currency.", "example": 5.25, "format": "float", "type": "number" }, "total_received": { "description": "Amount remaining after fees, in the payout currency.", "example": 494.75, "format": "float", "type": "number" } }, "required": [ "fee", "total_received" ], "type": [ "object", "null" ] }, "instant_unavailable_reason": { "description": "Why instant delivery is unavailable for this method. `minimum_crypto_sales_not_met` means the account has not reached the total sales required for instant cryptocurrency payouts. `null` when this restriction does not apply.", "enum": [ "minimum_crypto_sales_not_met", null ], "example": "minimum_crypto_sales_not_met", "type": [ "string", "null" ] }, "max_limit": { "description": "Maximum payout amount for this method, in the payout currency.", "example": 25000.0, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount for this method, in the payout currency.", "example": 1.0, "format": "float", "type": "number" }, "standard": { "description": "Standard-delivery estimate. Null if the method does not support standard delivery, or the amount does not cover the fee.", "properties": { "fee": { "description": "Total fee charged, in the payout currency.", "example": 0.25, "format": "float", "type": "number" }, "total_received": { "description": "Amount remaining after fees, in the payout currency.", "example": 499.75, "format": "float", "type": "number" } }, "required": [ "fee", "total_received" ], "type": [ "object", "null" ] } }, "required": [ "amount", "currency", "exchange_rate", "min_limit", "max_limit", "instant_unavailable_reason", "standard", "instant" ], "type": [ "object", "null" ] }, "recipient": { "description": "The recipient of a third-party payout method. Present only for recipient payout methods.", "properties": { "country": { "description": "ISO 3166-1 alpha-3 country code.", "type": "string" }, "email": { "example": "jane.doe@example.com", "format": "email", "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } }, "required": [ "email", "first_name", "last_name", "country" ], "type": "object" }, "status": { "description": "Lifecycle status: `created` means saved but unused, `active` means a payout succeeded through it, `broken` means a payout failure disabled it; a later successful payout returns it to `active`.", "enum": [ "created", "active", "broken" ], "example": "active", "type": "string" }, "status_reason": { "description": "Machine-readable code for why the method is `broken` — the newest disabling failure recorded through it, whether a payout error or a pre-payout rejection. `null` unless the method is broken, or when it was disabled without a recorded failure.", "example": null, "type": [ "string", "null" ] }, "supported_payout_method": { "description": "The supported payout method this saved method was created from.", "properties": { "country_code": { "description": "ISO 3166-1 alpha-3 country the destination pays out to.", "example": "USA", "type": [ "string", "null" ] }, "delivery_type": { "description": "How funds are delivered.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_plaid": { "description": "Whether the payer can link this method by signing in to their bank instead of typing account details.", "example": true, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "name", "icon_url", "delivery_type", "country_code", "supports_standard_delivery", "supports_instant_delivery", "supports_plaid" ], "type": [ "object", "null" ] }, "unavailable_reason": { "description": "Why this method is unavailable: `destination_retired` means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. `null` means no unavailability reason is known.", "enum": [ "destination_retired", null ], "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "status_reason", "is_default", "nickname", "account_reference", "bank_verification_state", "linked_via_plaid", "needs_plaid_reconnect", "is_clone", "institution_name", "payer_name", "destination_currency", "created_at", "last_paid_out_at", "unavailable_reason", "supported_payout_method", "fee_structure", "estimated_arrival", "quote" ], "type": "object" }, "type": "array" }, "limits": { "description": "The live per-speed payout caps for the account in the requested currency — the numbers a payout request is validated against at submit time, so clients can cap an amount input at a value the request will accept. Only present when include_limits is true.", "properties": { "currency": { "description": "The currency the caps are denominated in.", "example": "usd", "type": "string" }, "instant": { "description": "Caps for instant-speed payouts, which additionally draw on pending funds.", "properties": { "daily_amount_remaining": { "description": "How much of the account's daily instant allowance is left, in the requested currency. Null when the account is exempt from the daily cap, which is not the same as 0.", "example": 9999.0, "format": "float", "type": [ "number", "null" ] }, "error_code": { "description": "Why instant payouts are unavailable for this account, or null when they are available.", "enum": [ "amount_too_high", "account_daily_limit_reached", "restricted_account", "feature_disabled", null ], "example": "restricted_account", "type": [ "string", "null" ] }, "error_message": { "description": "Human-readable form of error_code, or null when instant payouts are available.", "example": "Instant payouts are not available for your account at this time.", "type": [ "string", "null" ] }, "max_amount": { "description": "The maximum amount an instant payout can move right now, in whole currency units. Already bounded by the remaining daily instant allowance; 0 while an eligibility error blocks instant payouts.", "example": 0.0, "format": "float", "type": "number" }, "resets_at": { "description": "When the daily instant allowance resets, or null when the account is exempt from the daily cap.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "max_amount", "error_code", "error_message", "daily_amount_remaining", "resets_at" ], "type": "object" }, "object": { "enum": [ "payout_limit" ], "example": "payout_limit", "type": "string" }, "standard": { "description": "Caps for standard-speed payouts, which draw on settled funds only.", "properties": { "error_code": { "description": "Why a standard payout cannot move funds right now, or null when the cap is above 0.", "enum": [ "account_suspended", "block_move_money_out_because_clawback", "card_usage_review_payout_status_hold", "under_review", "kyc_completed", "rmi_clear", "identity_rfi_clear", "guardian_id_clear", "block_move_money_out", "block_move_money_out_set_by_parent", "no_available_balance", null ], "example": "no_available_balance", "type": [ "string", "null" ] }, "error_message": { "description": "Human-readable form of error_code, or null when a standard payout can move funds.", "example": "You don't have an available balance to withdraw.", "type": [ "string", "null" ] }, "max_amount": { "description": "The maximum amount a standard payout can move right now, in whole currency units.", "example": 500.0, "format": "float", "type": "number" } }, "required": [ "max_amount", "error_code", "error_message" ], "type": "object" } }, "required": [ "object", "currency", "standard", "instant" ], "type": "object" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "payout methods listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:destination:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account or user not found" } }, "security": [ { "bearerAuth": [ "payout:destination:read" ] } ], "summary": "List Saved Payout Methods", "tags": [ "Payouts" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Saves a bank account, wallet, or crypto address an account or user can pay out to, from a method listed by `GET /payouts/supported_methods`. Sensitive details are vaulted in transit and never stored raw.", "operationId": "createPayoutMethod", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to add the payout method for, prefixed `biz_`. Provide this or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "destination_currency": { "default": "usd", "description": "Currency the supported payout method delivers payouts in.", "example": "usd", "type": "string" }, "fields": { "additionalProperties": { "type": "string" }, "description": "The supported payout method's required field values, keyed by field id — list them with `GET /payouts/supported_methods?supported_payout_method_id=...`. Field ids are stable `fld_` identifiers you may hardcode; they never change for a given field. A Basis Theory token id may be passed in place of a raw value. For a U.S. bank routing-number field, a raw nine-digit value must also pass the ABA checksum. A validation failure returns the method's full required_fields schema alongside the error. Required whenever the account details are supplied directly.", "example": { "fld_bank_account_number": "8825310472", "fld_bank_account_type": "Checking" }, "type": "object" }, "is_default": { "default": false, "description": "Whether to make this the account's default payout method.", "example": false, "type": "boolean" }, "nickname": { "description": "A label for the payout method, unique per destination.", "example": "Ops checking", "type": "string" }, "paypal_link_token": { "description": "The token your `return_url` received after a Log in with PayPal session started with `POST /payouts/paypal_link_sessions`. Use it for a PayPal supported payout method instead of `fields`. Sending `fields` or `plaid_public_token` alongside it is rejected, and `nickname` is ignored because Whop names the method after the PayPal email. The PayPal holder's name must match the name on the account's payout setup. An account PayPal reports as unverified, or with an unconfirmed email, is saved and flagged on the method's log rather than refused. Single use; expires 15 minutes after the login.", "example": "pplt_mYWzcqskZuBf2-JTpooLjo5hl5HdE2P68o90dgJjWGQ", "type": "string" }, "recipient": { "description": "Creates a recipient payout account linked to the funding ledger as a non-default account, then saves the bank method on it. No Whop user, company, or recipient ledger is created. A valid recipient email is required. Recipient methods cannot be default or recurring methods and cannot use Plaid.", "properties": { "address": { "description": "The recipient's address in recipient.country. Saved on the recipient payout account and supplied to bank methods that require address fields. Omit to retain the existing address when reusing a recipient.", "properties": { "city": { "description": "The recipient's city.", "example": " New York ", "maxLength": 120, "type": "string" }, "line1": { "description": "The recipient's street address.", "example": " 123 Main Street ", "maxLength": 120, "type": "string" }, "line2": { "description": "Apartment, suite or unit.", "maxLength": 120, "type": "string" }, "postal_code": { "description": "The recipient's postal or ZIP code.", "example": "10001", "maxLength": 120, "type": "string" }, "state": { "description": "The recipient's state, province or region.", "example": "NY", "maxLength": 120, "type": "string" } }, "required": [ "line1", "city" ], "type": "object" }, "country": { "description": "ISO 3166-1 alpha-2 or alpha-3 country code.", "example": "us", "type": "string" }, "email": { "description": "Required email for the recipient's MassPay payout account. Trimmed and lowercased.", "example": "marcus@shinetime.example", "format": "email", "maxLength": 50, "type": "string" }, "first_name": { "description": "Recipient's first name, at most 120 UTF-8 bytes. The trimmed full name, including a space between the names, must be at most 100 characters and cannot contain angle brackets or double quotes.", "example": "Jane", "type": "string" }, "last_name": { "description": "Recipient's last name, at most 120 UTF-8 bytes. The combined full name follows the same 100-character limit as a Whop user name.", "example": "Doe", "type": "string" } }, "required": [ "first_name", "last_name", "country", "email" ], "type": "object" }, "supported_payout_method_id": { "description": "The supported payout method to save (a podst_ identifier from a previous listing).", "example": "podst_xxxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "The user to add the payout method for, prefixed `user_`. Provide this or `account_id`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "supported_payout_method_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_reference": { "description": "Masked identifier for the destination.", "example": "••••0472", "type": [ "string", "null" ] }, "bank_verification_state": { "description": "Lifecycle trust state: `checking` (verification still running), `verified` (bank confirmed ownership or a payout already completed to it), `no_data` (verification unavailable or bank returned no ownership data), `warning` (bank could not confirm the destination's owner), `broken` (payouts failed with a permanent account error), `null` (never checked).", "enum": [ "checking", "verified", "no_data", "warning", "broken", null ], "example": "checking", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination_currency": { "example": "usd", "type": "string" }, "estimated_arrival": { "description": "Null on create. List payout methods to retrieve arrival estimates.", "example": null, "type": [ "object", "null" ] }, "fee_structure": { "description": "Null on create. List payout methods to retrieve the configured fee terms.", "example": null, "type": [ "object", "null" ] }, "id": { "description": "Payout method ID, usable as payout_method_id on POST /payouts.", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "institution_name": { "example": "Frost Bank", "type": [ "string", "null" ] }, "is_clone": { "description": "Whether this method is a copy of one saved on another of the payer's accounts.", "example": false, "type": "boolean" }, "is_default": { "example": false, "type": "boolean" }, "last_paid_out_at": { "description": "When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. `null` when nothing has been paid out to it yet.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "linked_via_plaid": { "description": "Whether the payer added this method by signing in to their bank rather than typing account details.", "example": false, "type": "boolean" }, "needs_plaid_reconnect": { "description": "Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.", "example": false, "type": "boolean" }, "nickname": { "description": "User-defined label for the payout method.", "example": "Ops checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "payer_name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "quote": { "description": "Always null on create.", "example": null, "type": [ "object", "null" ] }, "recipient": { "description": "The recipient of a third-party payout method. Present only for recipient payout methods.", "properties": { "country": { "description": "ISO 3166-1 alpha-3 country code.", "example": "USA", "type": "string" }, "email": { "example": "jane.doe@example.com", "format": "email", "type": "string" }, "first_name": { "example": "Jane", "type": "string" }, "last_name": { "example": "Doe", "type": "string" } }, "required": [ "email", "first_name", "last_name", "country" ], "type": "object" }, "status": { "description": "Always `created` on create — no payout has used the method yet.", "enum": [ "created", "active", "broken" ], "example": "created", "type": "string" }, "status_reason": { "description": "Always `null` on create.", "example": null, "type": [ "string", "null" ] }, "supported_payout_method": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-3 country the destination pays out to.", "example": "USA", "type": [ "string", "null" ] }, "delivery_type": { "description": "How funds are delivered.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-bank-deposit-icon", "type": [ "string", "null" ] }, "name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_plaid": { "description": "Whether the payer can link this method by signing in to their bank instead of typing account details.", "example": true, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "name", "icon_url", "delivery_type", "supports_standard_delivery", "supports_instant_delivery" ], "type": [ "object", "null" ] }, "unavailable_reason": { "description": "Why this method is unavailable: `destination_retired` means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. `null` means no unavailability reason is known.", "enum": [ "destination_retired", null ], "example": "destination_retired", "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "status_reason", "is_default", "nickname", "account_reference", "institution_name", "payer_name", "destination_currency", "created_at", "last_paid_out_at", "unavailable_reason", "supported_payout_method", "fee_structure", "estimated_arrival", "quote" ], "type": "object" } } }, "description": "payout method created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request is invalid or the account has no payout setup yet" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:create_destination scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "supported payout method not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "payout setup is still being provisioned" } }, "security": [ { "bearerAuth": [ "payout:create_destination" ] } ], "summary": "Create Saved Payout Method", "tags": [ "Payouts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/payouts/methods/{id}": { "delete": { "description": "Deletes a saved payout method so it can no longer receive payouts.", "operationId": "deletePayoutMethod", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always `true`.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted payout method, prefixed `potk_`.", "example": "potk_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "payout method deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:delete_destination scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout method not found" } }, "security": [ { "bearerAuth": [ "payout:delete_destination" ] } ], "summary": "Delete Saved Payout Method", "tags": [ "Payouts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Payout method ID, prefixed `potk_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Changes the label used to identify a saved payout method, makes it the account's default payout method, or updates the payout address on file for it. Send `address` on its own: it cannot be combined with `nickname` or `is_default`. Address updates require the `payout:account:update` scope as well, on the same account, and are supported only for bank and wallet payout methods, not recipient payout methods.", "operationId": "updatePayoutMethod", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "minProperties": 1, "properties": { "address": { "additionalProperties": false, "description": "The payout address to keep on file for this payout method. Only the fields you send are changed; blank fields are ignored.", "minProperties": 1, "properties": { "city": { "description": "The city.", "example": "New York", "maxLength": 120, "type": "string" }, "line1": { "description": "The first line of the street address.", "example": "123 Main Street", "maxLength": 120, "type": "string" }, "line2": { "description": "The second line of the street address, such as an apartment or suite number.", "example": "Apt 4", "maxLength": 120, "type": "string" }, "postal_code": { "description": "The postal or ZIP code.", "example": "10001", "maxLength": 120, "type": "string" }, "state": { "description": "The state, province, or region.", "example": "NY", "maxLength": 120, "type": "string" } }, "type": "object" }, "is_default": { "description": "Set to `true` to make this the account's default payout method. `false` is not accepted.", "enum": [ true ], "example": true, "type": "boolean" }, "nickname": { "description": "New label for the payout method, with at least one non-whitespace character and a maximum of 100 characters.", "example": "Primary checking", "maxLength": 100, "minLength": 1, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_reference": { "description": "Masked identifier for the destination.", "example": "••••0472", "type": [ "string", "null" ] }, "bank_verification_state": { "description": "Lifecycle trust state: `checking` (verification still running), `verified` (bank confirmed ownership or a payout already completed to it), `no_data` (verification unavailable or bank returned no ownership data), `warning` (bank could not confirm the destination's owner), `broken` (payouts failed with a permanent account error), `null` (never checked).", "enum": [ "checking", "verified", "no_data", "warning", "broken", null ], "example": "checking", "type": [ "string", "null" ] }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination_currency": { "example": "usd", "type": "string" }, "estimated_arrival": { "description": "`null` after an update. List payout methods to retrieve arrival estimates.", "example": null, "type": [ "object", "null" ] }, "fee_structure": { "description": "`null` after an update. List payout methods to retrieve the configured fee terms.", "example": null, "type": [ "object", "null" ] }, "id": { "description": "Payout method ID, prefixed `potk_`.", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "institution_name": { "example": "Frost Bank", "type": [ "string", "null" ] }, "is_clone": { "description": "Whether this method is a copy of one saved on another of the payer's accounts.", "example": false, "type": "boolean" }, "is_default": { "example": true, "type": "boolean" }, "last_paid_out_at": { "description": "When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. `null` when nothing has been paid out to it yet.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "linked_via_plaid": { "description": "Whether the payer added this method by signing in to their bank rather than typing account details.", "example": false, "type": "boolean" }, "needs_plaid_reconnect": { "description": "Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.", "example": false, "type": "boolean" }, "nickname": { "description": "User-defined label for the payout method.", "example": "Primary checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "payer_name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "quote": { "description": "Always `null` after an update.", "example": null, "type": [ "object", "null" ] }, "recipient": { "description": "The recipient of a third-party payout method. Present only for recipient payout methods.", "properties": { "country": { "description": "ISO 3166-1 alpha-3 country code.", "type": "string" }, "email": { "example": "jane.doe@example.com", "format": "email", "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } }, "required": [ "email", "first_name", "last_name", "country" ], "type": "object" }, "status": { "description": "`created` — saved, no payout has completed through it yet. `active` — a payout through it completed. `broken` — a payout through it failed with an error attributable to the method, and it no longer accepts payouts; a later successful payout returns it to `active`.", "enum": [ "created", "active", "broken" ], "example": "created", "type": "string" }, "status_reason": { "description": "Machine-readable code for why the method is `broken` — the newest failure recorded through it, whether a payout error or a pre-payout rejection. `null` unless the method is broken, or when it was disabled without a recorded failure.", "example": null, "type": [ "string", "null" ] }, "supported_payout_method": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-3 country the destination pays out to.", "example": "USA", "type": [ "string", "null" ] }, "delivery_type": { "description": "How funds are delivered.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-bank-deposit-icon", "type": [ "string", "null" ] }, "name": { "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_plaid": { "description": "Whether the payer can link this method by signing in to their bank instead of typing account details.", "example": true, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "name", "icon_url", "delivery_type", "country_code", "supports_standard_delivery", "supports_instant_delivery", "supports_plaid" ], "type": [ "object", "null" ] }, "unavailable_reason": { "description": "Why this method is unavailable: `destination_retired` means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. `null` means no unavailability reason is known.", "enum": [ "destination_retired", null ], "example": "destination_retired", "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "status_reason", "is_default", "nickname", "account_reference", "bank_verification_state", "linked_via_plaid", "needs_plaid_reconnect", "is_clone", "institution_name", "payer_name", "destination_currency", "created_at", "last_paid_out_at", "unavailable_reason", "supported_payout_method", "fee_structure", "estimated_arrival", "quote" ], "type": "object" } } }, "description": "payout method updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "no update attributes are provided" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:update_destination scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout method not found" } }, "security": [ { "bearerAuth": [ "payout:update_destination" ] } ], "summary": "Update Saved Payout Method", "tags": [ "Payouts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/payouts/paypal_link_sessions": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts a Log in with PayPal session so PayPal itself can confirm the account holder owns a verified PayPal account. Send the holder to `authorize_url`; after they log in, PayPal returns them to Whop, and Whop redirects the browser to your `return_url` with a `paypal_link_token` query parameter to pass to `POST /payouts/methods`. If the login fails or is canceled, `return_url` receives an `error` query parameter (`paypal_login_canceled` or `paypal_login_failed`) instead. The payout method saved this way pays the email on the PayPal account, and its holder name must match the name on the account's payout setup. PayPal login is rolling out per account: until it is enabled for the account this answers `403 forbidden`, and `supports_paypal_login` on `GET /payouts/supported_methods` is false.", "operationId": "createPaypalLinkSession", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account that will own the PayPal payout method, prefixed `biz_`. Provide this or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "destination_currency": { "default": "usd", "description": "Currency the PayPal payout method will deliver payouts in.", "example": "usd", "type": "string" }, "return_url": { "description": "Where to send the holder once the PayPal login finishes. Must be an `https` URL whose host is a domain added to the account, or to its platform, with `POST /domains` and `verification: {}`; the domain doesn't need to finish verifying. Whop's own pages and `https://localhost` are also accepted; they're the only options for a `user_id` session. It receives `paypal_link_token` on success or `error` on failure.", "example": "https://example.com/settings/payouts", "type": "string" }, "supported_payout_method_id": { "description": "The PayPal supported payout method to connect (a `podst_` identifier whose `supports_paypal_login` is true).", "example": "podst_xxxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "The user who will own the PayPal payout method, prefixed `user_`. Provide this or `account_id`.", "type": "string" } }, "required": [ "supported_payout_method_id", "return_url" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "authorize_url": { "description": "The PayPal login page to send the account holder to.", "example": "https://www.paypal.com/connect", "type": "string" }, "expires_at": { "description": "When the login session stops being accepted, as an ISO 8601 timestamp; start a new one after this.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "authorize_url", "expires_at" ], "type": "object" } } }, "description": "PayPal login started" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "supported_payout_method_id or return_url missing, the method is not PayPal, return_url is not https or not on a domain added to the account, or the currency is not supported" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:create_destination scope, or PayPal login is not enabled for the account" }, "404": { "$ref": "#/components/responses/NotFound", "description": "supported payout method not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:create_destination" ] } ], "summary": "Create PayPal Link Session", "tags": [ "Payouts" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/payouts/quotes": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a short-lived, provider-backed quote of a payout's fee, exchange rate, and destination amount. No funds move until you submit the returned `quote_token` to `POST /payouts`.", "operationId": "createPayoutQuote", "parameters": [ { "description": "A unique key that makes this quote request safe to retry.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "example": "payout-quote-aed-20260824", "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account to pay out from, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "The amount to pay out in the specified currency, fees included. Provide exactly one of `amount` or `recipient_amount`.", "example": 6762.41, "format": "float", "type": "number" }, "currency": { "description": "The currency to pay out. When omitted, uses `usd` if that balance can cover a withdrawal, otherwise the account's only other funded currency.", "example": "eur", "type": "string" }, "payment_method_id": { "description": "A saved card of the account, prefixed `payt_`, to quote paying this payout from. The quote's `amount` is the card charge, `fee` adds the estimated card fees to the payout fee, and `net_amount` is what the recipient receives.", "type": "string" }, "payout_method_id": { "description": "The saved payout method to quote (a potk_ identifier).", "example": "potk_xxxxxxxxxxxxxx", "type": "string" }, "platform_covers_fees": { "description": "Whether the parent platform covers the payout fee instead of the account being paid out.", "type": "boolean" }, "recipient_amount": { "description": "The amount the recipient should receive, with fees added on top. When the payout method pays out in `currency`, the quote's `destination_amount` covers it; otherwise its `net_amount` does. Provide exactly one of `amount` or `recipient_amount`.", "format": "float", "type": "number" }, "speed": { "default": "standard", "description": "How fast the funds should arrive.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "Payment description sent with the payout, such as an invoice number or what it pays for. Must be 5-80 printable ASCII characters (letters, digits, spaces and punctuation); Whop sends it in upper case. Not all countries and banks show it on the recipient's statement, and it is not the sender name. Omit or pass `null` to use the default descriptor.", "example": "ACME INV-10432", "maxLength": 80, "minLength": 5, "pattern": "^[ -~]+$", "type": [ "string", "null" ] }, "user_id": { "description": "User to pay out from, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.", "type": "string" } }, "required": [ "payout_method_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Gross payout amount." }, "destination_amount": { "$ref": "#/components/schemas/Money", "description": "Exact amount quoted for delivery." }, "exchange_rate": { "description": "Quoted exchange rate from the source currency to the destination currency.", "example": 4.13978443, "format": "float", "type": "number" }, "expires_at": { "description": "When the quote expires.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "fee": { "$ref": "#/components/schemas/Money", "description": "Fee charged for the payout." }, "id": { "description": "Provider-backed payout quote ID, prefixed `pout_`.", "example": "pout_aed_quote", "type": "string" }, "net_amount": { "$ref": "#/components/schemas/Money", "description": "Amount remaining after fees." }, "object": { "enum": [ "payout_quote" ], "example": "payout_quote", "type": "string" }, "quote_token": { "description": "Server-signed quote token to submit to POST /payouts.", "example": "signed-payout-quote", "type": "string" }, "recommended_method": { "description": "An optional payout method to connect for estimated savings. The quote still uses the requested saved method.", "properties": { "country": { "description": "Two-letter ISO country code for connecting the method.", "example": "AE", "type": "string" }, "destination_currency": { "description": "Currency to select when connecting the method.", "example": "eur", "type": "string" }, "estimated_arrival": { "description": "Estimated arrival when paying out with the suggested method, when available.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "estimated_fee": { "$ref": "#/components/schemas/Money", "description": "Estimated total cost, including same-currency exchange-rate loss." }, "estimated_savings": { "$ref": "#/components/schemas/Money", "description": "Estimated increase in the delivered amount after fees compared with this quote." }, "name": { "description": "Display name of the suggested payout method.", "example": "Bank Wire", "type": "string" }, "supported_payout_method_id": { "description": "Supported payout method to connect, prefixed `podst_`.", "example": "podst_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "supported_payout_method_id", "name", "country", "destination_currency", "estimated_savings", "estimated_fee", "estimated_arrival" ], "type": [ "object", "null" ] } }, "required": [ "object", "id", "amount", "fee", "net_amount", "destination_amount", "exchange_rate", "expires_at", "quote_token", "recommended_method" ], "type": "object" } } }, "description": "payout quote created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "idempotency key is required" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the withdraw-funds scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "Create Payout Quote", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "/payouts/supported_methods": { "get": { "description": "Lists the payout methods an account or user is eligible to add. Pass a result's ID as `supported_payout_method_id` to `POST /payouts/methods` to save one.", "operationId": "listSupportedPayoutMethods", "parameters": [ { "description": "The owning account ID (a biz_ identifier). Provide this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The owning user ID (a user_ identifier). Provide this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "ISO 3166-1 alpha-2 country code for the bank account or wallet, such as `US`. Defaults to the country of supported_payout_method_id when one is given, otherwise the payout account's country.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "Optional payout amount in whole currency units, for example `250.00`. When provided, each destination includes per-currency fee and delivery quotes.", "in": "query", "name": "amount", "required": false, "schema": { "type": "number" } }, { "description": "Currency code of the amount, for example `usd`. Only meaningful with amount.", "in": "query", "name": "currency", "required": false, "schema": { "default": "usd", "type": "string" } }, { "description": "Narrows the list to one supported payout method (a podst_ identifier) and includes the required_fields needed to save it as a payout method.", "in": "query", "name": "supported_payout_method_id", "required": false, "schema": { "type": "string" } }, { "description": "Currency the supported payout method would deliver payouts in. Only meaningful with supported_payout_method_id; required fields vary by destination currency.", "in": "query", "name": "destination_currency", "required": false, "schema": { "default": "usd", "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "delivery_type": { "description": "How funds are delivered, for example `bank_deposit`.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-bank-deposit", "type": [ "string", "null" ] }, "id": { "description": "Supported payout method ID.", "example": "podst_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Supported payout method display name.", "example": "SEPA Bank Transfer", "type": [ "string", "null" ] }, "object": { "enum": [ "supported_payout_method" ], "example": "supported_payout_method", "type": "string" }, "quotes": { "description": "Fee and delivery estimates for the requested amount, one per destination currency. Null unless an amount was provided.", "items": { "properties": { "amount": { "description": "The payout amount the quote is for.", "example": 2500.0, "format": "float", "type": "number" }, "currency": { "description": "Currency of the quoted amount.", "example": "usd", "type": "string" }, "destination_currency": { "description": "Currency the funds are delivered in.", "example": "usd", "type": "string" }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency.", "example": 1.0, "format": "float", "type": "number" }, "instant": { "description": "Instant-delivery estimate. Null if unsupported, unavailable for the account, or the amount does not cover the fee.", "properties": { "estimated_arrival": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "fee": { "example": 12.5, "format": "float", "type": "number" }, "total_received": { "example": 2487.5, "format": "float", "type": "number" } }, "required": [ "fee", "total_received", "estimated_arrival" ], "type": [ "object", "null" ] }, "max_limit": { "description": "Maximum payout amount, in the payout currency.", "example": 50000.0, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount, in the payout currency.", "example": 10.0, "format": "float", "type": "number" }, "standard": { "description": "Standard-delivery estimate. Null if unsupported or the amount does not cover the fee.", "properties": { "estimated_arrival": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "fee": { "example": 2.5, "format": "float", "type": "number" }, "total_received": { "example": 2497.5, "format": "float", "type": "number" } }, "required": [ "fee", "total_received", "estimated_arrival" ], "type": [ "object", "null" ] } }, "required": [ "destination_currency", "amount", "currency", "exchange_rate", "min_limit", "max_limit", "standard", "instant" ], "type": "object" }, "type": [ "array", "null" ] }, "required_fields": { "description": "Fields to collect before saving this supported payout method. Present only when supported_payout_method_id narrows the request to one method.", "items": { "properties": { "id": { "description": "Stable field ID (`fld_` + the semantic type), used as the field key when creating the payout method. Safe to hardcode — it never changes for a given field.", "example": "fld_bank_account_number", "type": "string" }, "input_type": { "description": "How to collect the value: `text`, `options`, or `date`.", "example": "text", "type": "string" }, "label": { "description": "Human-readable field name.", "example": "Account Number", "type": "string" }, "object": { "enum": [ "required_field" ], "example": "required_field", "type": "string" }, "options": { "description": "Allowed values for options fields.", "items": { "example": "savings", "type": "string" }, "type": [ "array", "null" ] }, "placeholder": { "description": "Example value.", "example": "8825310472", "type": [ "string", "null" ] }, "required": { "description": "Whether the field must be provided.", "example": true, "type": "boolean" }, "sensitive": { "description": "Whether the value is vaulted in transit and never stored raw.", "example": true, "type": "boolean" }, "type": { "description": "Semantic field type, for example `bank_account_number` or `swift`.", "example": "bank_account_number", "type": "string" }, "validation": { "description": "Regex the value must match. Null for options fields.", "example": "^[0-9]{4,17}$", "type": [ "string", "null" ] } }, "required": [ "object", "id", "label", "type", "input_type", "required", "validation", "options", "placeholder", "sensitive" ], "type": "object" }, "type": [ "array", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_paypal_login": { "description": "Whether the payer can add this method by logging in to PayPal through `POST /payouts/paypal_link_sessions`, which confirms the PayPal account is verified and owned by the payee. True only for the PayPal method, and only once PayPal login is enabled for the account.", "example": false, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "object", "id", "name", "icon_url", "delivery_type", "supports_standard_delivery", "supports_instant_delivery", "quotes", "required_fields" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "MQ", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "supported payout methods listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid list parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:destination:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "supported payout method not found or not available for this account" } }, "security": [ { "bearerAuth": [ "payout:destination:read" ] } ], "summary": "List Supported Payout Methods", "tags": [ "Payouts" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/payouts/{id}": { "get": { "description": "Retrieves a payout by its `wdrl_` ID, or by the `cofr_` conversion request ID a payout carries as `payout_request_id`. Authentication is optional: anyone with the ID can view tracking details, including notes, trace code, exchange rate, and payout request ID, while accounting fields require `payout:withdrawal:read` on the account or user that owns the payout. A supplied invalid credential returns 401.", "operationId": "retrievePayout", "parameters": [ { "description": "Optional owning account ID, prefixed `biz_`. The payout ID identifies its ledger. If supplied, this must match the owner and cannot be combined with `user_id`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional owning user ID, prefixed `user_`. The payout ID identifies its ledger. If supplied, this must match the owner and cannot be combined with `account_id`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string. Only returned to callers with payout:withdrawal:read on the owning ledger.", "example": "500.0", "format": "decimal", "type": "string" }, "cancelable": { "description": "Whether `POST /payouts/{id}/cancel` would act on this payout right now: `true` while it is `in_review`, while it is `processing` with nothing yet submitted to the payout provider, or while a submitted payout can still be asked to cancel at the provider. `false` once the money has arrived or the payout has already ended. Only returned to callers with payout:withdrawal:read on the owning ledger.", "example": true, "type": "boolean" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "delayed": { "description": "Whether an in-transit withdrawal is past its settlement window.", "example": false, "type": "boolean" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a payout funded by a conversion request it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "estimated_arrival_end": { "description": "End of the expected bank settlement window.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string. Only returned to callers with payout:withdrawal:read on the owning ledger.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform. Only returned to callers with payout:withdrawal:read on the owning ledger.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_` for a payout returned by `GET /payouts`, `cofr_` for a payout request returned by `POST /payouts`, or `pay_` for a payout funded by a card payment that has not been submitted yet.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies. Only returned to callers with payout:withdrawal:read on the owning ledger.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters. Only returned to callers with payout:withdrawal:read on the owning ledger.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled payout funded by a conversion request can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "Payout method display details. The nickname requires payout:destination:read on the owning ledger; otherwise it is null.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. For a request retrieved by its own `cofr_` ID, this equals `id`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "recipient_name": { "description": "The recipient's first name and last initial, or null when no recipient name is available.", "example": "Rishabh J.", "type": [ "string", "null" ] }, "sender_name": { "description": "The sending business's display name, or a personal sender's first name and last initial.", "example": "Whop Blueprints", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling. Only returned to callers with payout:withdrawal:read on the owning ledger.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "The payment description sent with the payout, or `null` if no descriptor was set. When set, 5-80 printable ASCII characters. Only returned to callers with payout:withdrawal:read on the owning ledger.", "example": "MYCOMPANY", "maxLength": 80, "minLength": 5, "type": [ "string", "null" ] }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "timeline": { "description": "Completed lifecycle events in chronological order. Present once the payout has a withdrawal record.", "items": { "properties": { "error_message": { "description": "Failure message, only with payout:destination:read.", "example": null, "type": [ "string", "null" ] }, "estimated_arrival": { "example": null, "format": "date-time", "type": [ "string", "null" ] }, "status": { "enum": [ "requested", "awaiting_payment", "in_transit", "completed", "failed", "canceled", "denied" ], "example": "requested", "type": "string" }, "status_detail": { "description": "Informational event detail; security_review identifies manual review.", "example": "security_review", "type": [ "string", "null" ] }, "timestamp": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "status", "status_detail", "timestamp", "estimated_arrival", "error_message" ], "type": "object" }, "type": "array" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "currency", "destination_currency", "destination_amount", "exchange_rate", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "net_amount", "failure", "payout_method" ], "type": "object" } } }, "description": "payout found" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout not found" } }, "security": [ {}, { "bearerAuth": [ "payout:withdrawal:read" ] } ], "summary": "Retrieve Payout", "tags": [ "Payouts" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Payout ID, prefixed `wdrl_` for a payout returned by `GET /payouts` or `cofr_` for the payout request returned by `POST /payouts`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/payouts/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Payout ID, prefixed `wdrl_`, or the `cofr_` payout request ID returned by `POST /payouts` — both cancel the same payout.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Cancels a payout before it is sent to the payout provider, or asks the provider to stop one already sent. While the payout is `in_review`, or `processing` with nothing sent yet (see `cancelable`), it is canceled and the funds, fees included, return to the balance. Once sent, the response is 202 with a `cancellation` object, and the payout reads `canceled` only if the provider confirms it stopped. A `requested` payout returns 409 until it reaches review, a payout the provider can no longer stop returns 409 with error type `not_cancelable`, and canceling an already-canceled payout returns it unchanged.", "operationId": "cancelPayout", "parameters": [ { "description": "Owning account ID, prefixed `biz_`. Provide exactly one of `account_id` or `user_id`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Owning user ID, prefixed `user_`. Provide exactly one of `account_id` or `user_id`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "cancelable": { "description": "Whether `POST /payouts/{id}/cancel` would act on this payout right now: `true` while it is `in_review`, while it is `processing` with nothing yet submitted to the payout provider, or while a submitted payout can still be asked to cancel at the provider. `false` once the money has arrived or the payout has already ended.", "example": false, "type": "boolean" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a payout funded by a conversion request it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "example": "Canceled by the account owner", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_` for a payout returned by `GET /payouts`, `cofr_` for a payout request returned by `POST /payouts`, or `pay_` for a payout funded by a card payment that has not been submitted yet.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled payout funded by a conversion request can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. For a request retrieved by its own `cofr_` ID, this equals `id`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "The payment description sent with the payout, or `null` if no descriptor was set. When set, 5-80 printable ASCII characters.", "example": "MYCOMPANY", "maxLength": 80, "minLength": 5, "type": [ "string", "null" ] }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "canceled", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "cancelable", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "statement_descriptor", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" } } }, "description": "payout canceled and funds returned" }, "202": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "cancelable": { "description": "Whether `POST /payouts/{id}/cancel` would act on this payout right now: `true` while it is `in_review`, while it is `processing` with nothing yet submitted to the payout provider, or while a submitted payout can still be asked to cancel at the provider. `false` once the money has arrived or the payout has already ended.", "example": true, "type": "boolean" }, "cancellation": { "description": "The cancellation request placed with the payout provider. The payout keeps its current `status` until the provider confirms the outcome; poll `GET /payouts/{id}` or subscribe to `payout.updated` to see it end `canceled` with `failure.funds_returned_at` set, or keep processing if the provider could not stop it.", "properties": { "requested_at": { "description": "When the cancellation was requested from the payout provider.", "example": "2026-09-17T14:03:12.000Z", "format": "date-time", "type": "string" }, "status": { "description": "`requested` when the provider accepted the request and is trying to stop the payout; `canceled_at_provider` when the provider reported the payout stopped on the spot. Neither is final until the payout itself reads `canceled`.", "enum": [ "canceled_at_provider", "requested" ], "example": "requested", "type": "string" } }, "required": [ "status", "requested_at" ], "type": "object" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a payout funded by a conversion request it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_` for a payout returned by `GET /payouts`, `cofr_` for a payout request returned by `POST /payouts`, or `pay_` for a payout funded by a card payment that has not been submitted yet.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled payout funded by a conversion request can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. For a request retrieved by its own `cofr_` ID, this equals `id`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "The payment description sent with the payout, or `null` if no descriptor was set. When set, 5-80 printable ASCII characters.", "example": "MYCOMPANY", "maxLength": 80, "minLength": 5, "type": [ "string", "null" ] }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "processing", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "cancelable", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "statement_descriptor", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method", "cancellation" ], "type": "object" } } }, "description": "cancellation requested from the payout provider" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the payout:withdraw_funds scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout not found" }, "409": { "$ref": "#/components/responses/Conflict", "description": "payout is already processing" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "Cancel Payout", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "/people": { "get": { "description": "Lists the people (visitors and customers) of an account: identity-linked profiles assembled from every pixel, payment, and platform event. Filter and sort them to segment an account's audience.", "operationId": "listPeople", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Account ID, prefixed `biz_`. Optional for account API keys; required for credentials that can access multiple accounts.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Search people by name, email, phone, or whop user ID (case-insensitive substring match).", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only include people acquired from any of these sources — canonical paths (whop:::, ext::..., referrer:, direct, other), exact or with a trailing :* prefix. The same vocabulary the events / people metrics use.", "explode": true, "in": "query", "name": "source", "required": false, "schema": { "items": { "example": "direct", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Attribution model the source filter matches against (defaults to last_touch).", "in": "query", "name": "attribution_model", "required": false, "schema": { "enum": [ "last_touch", "first_touch" ], "type": "string" } }, { "description": "Only include people who fired any of these events, e.g. payment.completed or page.checkout.view.", "explode": true, "in": "query", "name": "event_name", "required": false, "schema": { "items": { "example": "payment.completed", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Only include people who fired this custom pixel event.", "in": "query", "name": "custom_event", "required": false, "schema": { "type": "string" } }, { "description": "Match activity within a rolling number of days. Cannot be combined with event_from/event_to.", "in": "query", "name": "event_within_days", "required": false, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Inclusive activity-window start. Alias for event_from.", "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Inclusive activity-window end. Alias for event_to.", "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The inclusive start of the matching activity window.", "in": "query", "name": "event_from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The inclusive end of the matching activity window, for both stats drilldowns and saved audiences.", "in": "query", "name": "event_to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include people in this audience. An audience that keeps itself up to date resolves to the People filters that define it, so this always reflects who matches now; uploaded lists and point-in-time snapshots match their recorded members.", "in": "query", "name": "audience_id", "required": false, "schema": { "type": "string" } }, { "description": "Only include the person linked to this whop user ID.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only include the person linked to this email address.", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Only include the person linked to this phone number.", "in": "query", "name": "phone", "required": false, "schema": { "type": "string" } }, { "description": "Only include people with activity from this ISO 3166-1 alpha-2 country code.", "in": "query", "name": "country", "required": false, "schema": { "type": "string" } }, { "description": "true for customers only, false for people who have never purchased.", "in": "query", "name": "has_purchased", "required": false, "schema": { "type": "boolean" } }, { "description": "true for people who have an email address or phone number — the ones an ad platform can match.", "in": "query", "name": "contactable", "required": false, "schema": { "type": "boolean" } }, { "description": "Only include people first seen within this many days, as a rolling window.", "in": "query", "name": "first_seen_within_days", "required": false, "schema": { "type": "integer" } }, { "description": "Only include people last seen within this many days, as a rolling window.", "in": "query", "name": "last_seen_within_days", "required": false, "schema": { "type": "integer" } }, { "description": "Only include people first seen at or after this ISO 8601 timestamp.", "in": "query", "name": "first_seen_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include people first seen before this ISO 8601 timestamp.", "in": "query", "name": "first_seen_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include people last seen at or after this ISO 8601 timestamp.", "in": "query", "name": "last_seen_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include people last seen before this ISO 8601 timestamp.", "in": "query", "name": "last_seen_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Select people whose lifetime ltv is greater than this value. LTV and AOV are in USD.", "in": "query", "name": "ltv_gt", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime ltv is at least this value. LTV and AOV are in USD.", "in": "query", "name": "ltv_gte", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime ltv is less than this value. LTV and AOV are in USD.", "in": "query", "name": "ltv_lt", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime ltv is at most this value. LTV and AOV are in USD.", "in": "query", "name": "ltv_lte", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime aov is greater than this value. LTV and AOV are in USD.", "in": "query", "name": "aov_gt", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime aov is at least this value. LTV and AOV are in USD.", "in": "query", "name": "aov_gte", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime aov is less than this value. LTV and AOV are in USD.", "in": "query", "name": "aov_lt", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime aov is at most this value. LTV and AOV are in USD.", "in": "query", "name": "aov_lte", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime purchase_count is greater than this value. LTV and AOV are in USD.", "in": "query", "name": "purchase_count_gt", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime purchase_count is at least this value. LTV and AOV are in USD.", "in": "query", "name": "purchase_count_gte", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime purchase_count is less than this value. LTV and AOV are in USD.", "in": "query", "name": "purchase_count_lt", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime purchase_count is at most this value. LTV and AOV are in USD.", "in": "query", "name": "purchase_count_lte", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime event_count is greater than this value. LTV and AOV are in USD.", "in": "query", "name": "event_count_gt", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime event_count is at least this value. LTV and AOV are in USD.", "in": "query", "name": "event_count_gte", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime event_count is less than this value. LTV and AOV are in USD.", "in": "query", "name": "event_count_lt", "required": false, "schema": { "type": "number" } }, { "description": "Select people whose lifetime event_count is at most this value. LTV and AOV are in USD.", "in": "query", "name": "event_count_lte", "required": false, "schema": { "type": "number" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 100, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "Column to sort by. Defaults to last_seen_at.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "first_seen_at", "last_seen_at", "first_purchase_at", "last_purchase_at", "purchase_count", "event_count", "ltv", "aov", "name", "email" ], "type": "string" } }, { "description": "Sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "aov": { "example": 74.99, "type": "number" }, "device": { "properties": { "browser": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "device": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "os": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "type": "object" }, "email": { "description": "The email from the person's most recent event that carried one.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "event_count": { "example": 42, "type": "integer" }, "first_purchase_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "first_seen_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "first_source": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": [ "object", "null" ] }, "id": { "example": "prsn_123", "type": "string" }, "last_ip": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "last_purchase_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "last_seen_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "last_source": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": [ "object", "null" ] }, "location": { "properties": { "city": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "continent": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "country": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "type": "object" }, "ltv": { "example": 149.98, "type": "number" }, "member": { "description": "The user's member record at this account, when they are a member of it.", "properties": { "id": { "example": "mem_dana1", "type": "string" }, "joined_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "usd_total_spend": { "example": 149.98, "type": "number" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "name": { "description": "The name from the person's most recent event that carried one.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "phone": { "description": "The phone from the person's most recent event that carried one.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "purchase_count": { "example": 2, "type": "integer" }, "timezone": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "user": { "description": "The person's primary whop user, when one of their identities is a whop account.", "properties": { "id": { "example": "user_dana1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "profile_pic_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "example": "danawhitfield", "type": "string" } }, "required": [ "id", "username" ], "type": [ "object", "null" ] } }, "required": [ "id", "account_id", "first_seen_at", "last_seen_at", "event_count", "purchase_count" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "cursor_end", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "cursor_start", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page" ], "type": "object" }, "total_count": { "example": 42, "type": "integer" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "people listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid input" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "member:basic:read" ] }, { "bearerAuth": [ "member:journey:read" ] } ], "summary": "List People", "tags": [ "People" ] }, "x-whop-surface": "native" }, "/people/{id}": { "get": { "description": "Retrieves one person for an account, looked up by person ID, user ID, email address, or phone number.", "operationId": "retrievePerson", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The person ID (prefixed `prsn_`), user ID (prefixed `user_`), email address, or phone number to look up. A merged person resolves to the surviving profile.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Account ID, prefixed `biz_`. Optional for account API keys; required for credentials that can access multiple accounts.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The full profile a retrieve returns: the summary plus every linked identity, purchase rows, all acquisition sources, and exact usage breakdowns.", "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "aov": { "example": 74.99, "type": "number" }, "audience_ids": { "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "custom_event_names": { "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "device": { "properties": { "browser": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "device": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "os": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "type": "object" }, "email": { "description": "The email from the person's most recent event that carried one.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "emails": { "description": "Every linked email, primary first.", "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "event_count": { "example": 42, "type": "integer" }, "event_names": { "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "first_purchase_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "first_seen_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "first_source": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": [ "object", "null" ] }, "id": { "example": "prsn_123", "type": "string" }, "last_ip": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "last_purchase_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "last_seen_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "last_source": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": [ "object", "null" ] }, "location": { "properties": { "city": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "continent": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "country": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "type": "object" }, "ltv": { "example": 149.98, "type": "number" }, "member": { "description": "The user's member record at this account, when they are a member of it.", "properties": { "id": { "example": "mem_dana1", "type": "string" }, "joined_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "usd_total_spend": { "example": 149.98, "type": "number" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "name": { "description": "The name from the person's most recent event that carried one.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "names": { "description": "Every name the person's linked identities carried, primary first.", "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "phone": { "description": "The phone from the person's most recent event that carried one.", "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] }, "phones": { "description": "Every linked phone, primary first.", "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "purchase_count": { "example": 2, "type": "integer" }, "purchases": { "items": { "properties": { "event_id": { "example": "evt_2", "type": "string" }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "usd_value": { "example": 74.99, "type": "number" } }, "required": [ "event_id", "usd_value", "occurred_at" ], "type": "object" }, "type": "array" }, "roles": { "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" }, "sources": { "description": "Every distinct acquisition signal the person ever carried, ad entities hydrated.", "items": { "description": "Where a visit came from: a whop ad click, a lead form, an external ad, or a referring site.", "properties": { "ad": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "ad_group": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "campaign": { "properties": { "id": { "example": "adcamp_1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "thumbnail_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": [ "object", "null" ] }, "domain": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "occurred_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "type": { "enum": [ "ad_click", "lead_form", "external_ad_click", "referrer", "utm" ], "example": "ad_click", "type": "string" }, "utm_source": { "example": "Dana Whitfield", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": "object" }, "type": "array" }, "timezone": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "usage": { "description": "Exact usage breakdowns for the person's browser traffic (distinct events per value).", "properties": { "browser": { "items": { "properties": { "events": { "example": 10, "type": "integer" }, "value": { "example": "Chrome", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "city": { "items": { "properties": { "events": { "example": 9, "type": "integer" }, "value": { "example": "Austin", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "country": { "items": { "properties": { "events": { "example": 12, "type": "integer" }, "value": { "example": "US", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "device": { "items": { "properties": { "events": { "example": 5, "type": "integer" }, "value": { "example": "iPhone", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "ip": { "items": { "properties": { "events": { "example": 3, "type": "integer" }, "value": { "example": "1.1.1.1", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "os": { "items": { "properties": { "events": { "example": 7, "type": "integer" }, "value": { "example": "Mac OS X", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "referrer": { "items": { "properties": { "events": { "example": 4, "type": "integer" }, "value": { "example": "google.com", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" }, "timezone": { "items": { "properties": { "events": { "example": 12, "type": "integer" }, "value": { "example": "America/Chicago", "type": "string" } }, "required": [ "value", "events" ], "type": "object" }, "type": "array" } }, "type": "object" }, "user": { "description": "The person's primary whop user, when one of their identities is a whop account.", "properties": { "id": { "example": "user_dana1", "type": "string" }, "name": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "profile_pic_url": { "example": "Dana Whitfield", "type": [ "string", "null" ] }, "username": { "example": "danawhitfield", "type": "string" } }, "required": [ "id", "username" ], "type": [ "object", "null" ] }, "user_ids": { "description": "Every linked whop account, the most used one first.", "items": { "example": "Dana Whitfield", "type": "string" }, "type": "array" } }, "required": [ "id", "account_id", "first_seen_at", "last_seen_at", "event_count", "purchase_count" ], "type": "object" } } }, "description": "person retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "person not found" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] }, { "bearerAuth": [ "member:basic:read" ] }, { "bearerAuth": [ "member:journey:read" ] } ], "summary": "Retrieve Person", "tags": [ "People" ] }, "x-whop-surface": "native" }, "/permissions": { "get": { "description": "Lists permission actions and whether the calling credential is granted each one for a resource. Answers for whichever identity authenticated the request — a user session, an OAuth token, or an account or app API key — so it never describes who else can reach the resource.", "operationId": "listPermissions", "parameters": [ { "description": "Tag of the resource to check against: an account (`biz_`), product (`prod_`), experience (`exp_`), or app (`app_`). A resource the credential cannot see is reported as granted nothing rather than as an error.", "in": "query", "name": "resource_id", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated permission actions to check, for example `stats:read,payment:basic:read`. Every action is returned when omitted.", "in": "query", "name": "actions", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "action": { "$ref": "#/components/schemas/PermissionAction" }, "granted": { "description": "Whether the credential is granted the action for the resource.", "example": false, "type": "boolean" } }, "required": [ "action", "granted" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "permissions listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "Check Permissions", "tags": [ "Permissions" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/plans": { "get": { "deprecated": true, "description": "Deprecated compatibility endpoint. List variants with `GET /variants` instead.", "operationId": "listPlans", "parameters": [ { "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "in": "query", "name": "order", "required": false, "schema": { "enum": [ "id", "active_members_count", "created_at", "internal_notes", "expiration_days" ], "type": "string" } }, { "in": "query", "name": "release_methods", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "in": "query", "name": "visibilities", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "in": "query", "name": "billing_types", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PlanListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "variants listed through the deprecated plans path" } }, "security": [ {}, { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "List Plans", "tags": [ "Plans" ], "x-whop-deprecated-since": "2026-09-24", "x-whop-docs": "hidden", "x-whop-successor": "GET /variants" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "deprecated": true, "description": "Deprecated compatibility endpoint. Create variants with `POST /variants` instead.", "operationId": "createPlan", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "adaptive_pricing_enabled": { "type": [ "boolean", "null" ] }, "allow_multiple_quantity": { "type": "boolean" }, "attributes": { "type": [ "object", "null" ] }, "billing_period": { "type": [ "integer", "null" ] }, "billing_type": { "example": "one_time", "type": "string" }, "cancel_discount_intervals": { "type": [ "integer", "null" ] }, "cancel_discount_percentage": { "maximum": 100, "minimum": 1, "type": [ "integer", "null" ] }, "checkout_styling": { "type": [ "object", "null" ] }, "currency": { "type": "string" }, "custom_fields": { "items": { "properties": { "field_type": { "enum": [ "text" ], "example": "text", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "order": { "type": "integer" }, "placeholder": { "type": [ "string", "null" ] }, "required": { "type": "boolean" } }, "type": "object" }, "type": [ "array", "null" ] }, "description": { "type": [ "string", "null" ] }, "expiration_days": { "type": [ "integer", "null" ] }, "image": { "properties": { "direct_upload_id": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ] }, "initial_price": { "type": [ "number", "null" ] }, "internal_notes": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "offer_cancel_discount": { "type": [ "boolean", "null" ] }, "override_tax_type": { "type": "string" }, "payment_method_configuration": { "properties": { "disabled": { "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "type": "boolean" } }, "type": [ "object", "null" ] }, "product_id": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "example": "buy_now", "type": "string" }, "renewal_price": { "type": [ "number", "null" ] }, "sku": { "type": [ "string", "null" ] }, "split_pay_required_payments": { "maximum": 115, "minimum": 2, "type": [ "integer", "null" ] }, "stock": { "type": [ "integer", "null" ] }, "three_ds_level": { "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "title": { "example": "Deprecated plan creation", "maxLength": 30, "type": [ "string", "null" ] }, "trial_period_days": { "type": [ "integer", "null" ] }, "unlimited_stock": { "type": [ "boolean", "null" ] }, "visibility": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "variant created through the deprecated plans path" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "plan:create" ] } ], "summary": "Create Plan", "tags": [ "Plans" ], "x-whop-deprecated-since": "2026-09-24", "x-whop-docs": "hidden", "x-whop-successor": "POST /variants" }, "x-whop-surface": "native" }, "/plans/{id}": { "delete": { "deprecated": true, "description": "Deprecated compatibility endpoint. Delete variants with `DELETE /variants/{id}` instead.", "operationId": "deletePlan", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "variant deleted through the deprecated plans path" } }, "security": [ { "bearerAuth": [ "plan:delete" ] } ], "summary": "Delete Plan", "tags": [ "Plans" ], "x-whop-deprecated-since": "2026-09-24", "x-whop-docs": "hidden", "x-whop-successor": "DELETE /variants/{id}" }, "get": { "deprecated": true, "description": "Deprecated compatibility endpoint. Retrieve variants with `GET /variants/{id}` instead.", "operationId": "retrievePlan", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "variant retrieved through the deprecated plans path" } }, "security": [ {}, { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "Retrieve Plan", "tags": [ "Plans" ], "x-whop-deprecated-since": "2026-09-24", "x-whop-docs": "hidden", "x-whop-successor": "GET /variants/{id}" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Variant ID, prefixed `plan_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "deprecated": true, "description": "Deprecated compatibility endpoint. Update variants with `PATCH /variants/{id}` instead.", "operationId": "updatePlan", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "adaptive_pricing_enabled": { "type": [ "boolean", "null" ] }, "allow_multiple_quantity": { "type": "boolean" }, "attributes": { "type": [ "object", "null" ] }, "billing_period": { "type": [ "integer", "null" ] }, "cancel_discount_intervals": { "type": [ "integer", "null" ] }, "cancel_discount_percentage": { "maximum": 100, "minimum": 1, "type": [ "integer", "null" ] }, "checkout_styling": { "type": [ "object", "null" ] }, "currency": { "type": "string" }, "custom_fields": { "items": { "properties": { "field_type": { "enum": [ "text" ], "example": "text", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "order": { "type": "integer" }, "placeholder": { "type": [ "string", "null" ] }, "required": { "type": "boolean" } }, "type": "object" }, "type": [ "array", "null" ] }, "description": { "type": [ "string", "null" ] }, "expiration_days": { "type": [ "integer", "null" ] }, "image": { "properties": { "direct_upload_id": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ] }, "initial_price": { "type": [ "number", "null" ] }, "internal_notes": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "offer_cancel_discount": { "type": [ "boolean", "null" ] }, "override_tax_type": { "type": "string" }, "payment_method_configuration": { "properties": { "disabled": { "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "type": "boolean" } }, "type": [ "object", "null" ] }, "release_method": { "example": "buy_now", "type": "string" }, "renewal_price": { "type": [ "number", "null" ] }, "sku": { "type": [ "string", "null" ] }, "split_pay_required_payments": { "maximum": 115, "minimum": 2, "type": [ "integer", "null" ] }, "stock": { "type": [ "integer", "null" ] }, "strike_through_initial_price": { "type": [ "number", "null" ] }, "strike_through_renewal_price": { "type": [ "number", "null" ] }, "three_ds_level": { "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] }, "title": { "example": "Deprecated plan creation", "maxLength": 30, "type": [ "string", "null" ] }, "trial_period_days": { "type": [ "integer", "null" ] }, "unlimited_stock": { "type": [ "boolean", "null" ] }, "visibility": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "variant updated through the deprecated plans path" } }, "security": [ { "bearerAuth": [ "plan:update" ] } ], "summary": "Update Plan", "tags": [ "Plans" ], "x-whop-deprecated-since": "2026-09-24", "x-whop-docs": "hidden", "x-whop-successor": "PATCH /variants/{id}" }, "x-whop-surface": "native" }, "/plans/{id}/calculate_tax": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Variant ID, prefixed `plan_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "deprecated": true, "description": "Deprecated compatibility endpoint. Quote tax with `POST /payment_quotes` instead.", "operationId": "calculatePlanTax", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "properties": { "city": { "type": [ "string", "null" ] }, "country": { "example": "US", "type": "string" }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "postal_code": { "example": "78701", "type": [ "string", "null" ] }, "state": { "example": "TX", "type": [ "string", "null" ] } }, "required": [ "country" ], "type": [ "object", "null" ] }, "ip_address": { "type": "string" }, "tax_ids": { "items": { "properties": { "type": { "enum": [ "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", "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" ], "example": "ad_nrt", "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "maxItems": 1, "type": [ "array", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "currency": { "example": "usd", "type": "string" }, "status": { "enum": [ "calculated", "not_calculated" ], "example": "calculated", "type": "string" }, "subtotal": { "example": 1000, "type": "integer" }, "tax_amount": { "example": 70, "type": "integer" }, "tax_behavior": { "enum": [ "exclusive", "inclusive" ], "example": "exclusive", "type": "string" }, "total": { "example": 1070, "type": "integer" } }, "required": [ "currency", "tax_behavior", "subtotal", "tax_amount", "total", "status" ], "type": "object" } } }, "description": "variant tax calculated through the deprecated plans path" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "Calculate Tax", "tags": [ "Plans" ], "x-whop-deprecated-since": "2026-09-24", "x-whop-docs": "hidden", "x-whop-successor": "POST /payment_quotes" }, "x-whop-surface": "native" }, "/product_affiliates": { "get": { "description": "Lists affiliate enrollments for an account's products, newest first, including affiliates who have not made a referral. Requires `affiliate:basic:read` on the account. Email addresses and email search also require `member:email:read`.", "operationId": "listProductAffiliates", "parameters": [ { "description": "Account whose product affiliates are listed (`biz_` tag).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Matches the start of the affiliate's username or of any word in their name, or their exact email (with `member:email:read`).", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only product affiliates with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "archived" ], "type": "string" } }, { "description": "Only product affiliates of these products.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only signups at or after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only signups before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProductAffiliate" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" }, "total_count": { "description": "Matching product affiliates, or `null` past 10,000.", "example": 2, "type": [ "integer", "null" ] } }, "required": [ "data", "page_info", "total_count" ], "type": "object" } } }, "description": "product affiliates listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "affiliate read access required" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "affiliate:basic:read" ] } ], "summary": "List Product Affiliates", "tags": [ "Product Affiliates" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/products": { "get": { "description": "Lists an account's products, or searches the public marketplace when you omit `account_id`.", "operationId": "listProducts", "parameters": [ { "description": "The unique identifier of the account to list products for. Omit to search the public marketplace.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filters products by text. The public marketplace list searches product title, account name, headline and description, ranking products that match every word first and the closest partial matches after them; an account's own list is a plain substring match over title, headline and description. Omit to browse by recency.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only return marketplace products assigned to this category route, such as `trading`.", "in": "query", "name": "marketplace_category_route", "required": false, "schema": { "type": "string" } }, { "description": "Filter to products with a buyable variant of these billing models, such as `one_time` or `renewal`.", "in": "query", "name": "billing_types", "required": false, "schema": { "items": { "enum": [ "renewal", "one_time" ], "type": "string" }, "type": "array" } }, { "description": "Only return products whose advertised buyable variant has a displayed price of at least this amount. Recurring variants use renewal price.", "in": "query", "name": "price_minimum", "required": false, "schema": { "type": "number" } }, { "description": "Only return products whose advertised buyable variant has a displayed price of at most this amount. Recurring variants use renewal price.", "in": "query", "name": "price_maximum", "required": false, "schema": { "type": "number" } }, { "description": "Filter to only products matching these visibility states. Ignored on the public marketplace list, which only returns visible products.", "in": "query", "name": "visibilities", "required": false, "schema": { "items": { "example": "visible", "type": "string" }, "type": "array" } }, { "description": "Filter to only products matching these types.", "in": "query", "name": "access_pass_types", "required": false, "schema": { "items": { "example": "regular", "type": "string" }, "type": "array" } }, { "description": "Filter to only products carrying all of these labels. Labels are matched lowercased.", "in": "query", "name": "labels", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "The sort direction for results. Defaults to descending.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "The field to sort results by. Account lists default to `created_at`. Marketplace lists default to `discoverable_at` and accept `created_at` or `discoverable_at`. Cannot be combined with `query`.", "in": "query", "name": "order", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "Only return products created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Only return products created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProductListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "marketplace products listed without an account" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "marketplace order cannot be combined with query" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ {}, { "bearerAuth": [ "access_pass:basic:read" ] } ], "summary": "List Products", "tags": [ "Products" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a new product for an account.", "operationId": "createProduct", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The unique identifier of the account to create this product for.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "collect_shipping_address": { "description": "Whether to collect a shipping address at checkout.", "example": false, "type": [ "boolean", "null" ] }, "custom_cta": { "description": "The call-to-action button label.", "enum": [ "get_access", "join", "order_now", "shop_now", "call_now", "donate_now", "contact_us", "sign_up", "subscribe", "purchase", "get_offer", "apply_now", "complete_order", null ], "example": "order_now", "type": [ "string", "null" ] }, "custom_cta_url": { "description": "A URL the call-to-action button links to.", "example": "https://shinetime.example/book", "type": [ "string", "null" ] }, "custom_statement_descriptor": { "description": "Custom bank statement descriptor. Must start with WHOP*.", "example": "WHOP*SHINETIME", "type": [ "string", "null" ] }, "description": { "description": "A written description displayed on the product page. Maximum 1,500 characters.", "example": "Full interior extraction, leather conditioning, and an ozone odor treatment.", "maxLength": 1500, "type": [ "string", "null" ] }, "gallery_images": { "description": "Images or videos displayed in the product gallery, in display order. Replaces the existing gallery. Send an empty array to clear it; omit or pass null to leave it unchanged. A banner image does not populate the gallery.", "items": { "properties": { "direct_upload_id": { "description": "The signed ID of a completed direct upload, as an alternative to id.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "maxItems": 8, "type": [ "array", "null" ] }, "global_affiliate_percentage": { "description": "The commission rate affiliates earn.", "example": 10, "type": [ "number", "null" ] }, "global_affiliate_status": { "description": "The enrollment status in the global affiliate program.", "enum": [ "enabled", "disabled" ], "example": "enabled", "type": "string" }, "headline": { "description": "A short marketing headline for the product page. Maximum 80 characters.", "example": "Steam, shampoo, and odor removal in one visit", "maxLength": 80, "type": [ "string", "null" ] }, "labels": { "description": "Labels used to group products into collections. Stored lowercased and de-duplicated. Maximum 20 labels, 50 characters each.", "items": { "example": "interior", "type": "string" }, "type": [ "array", "null" ] }, "member_affiliate_percentage": { "description": "The commission rate members earn.", "example": 5, "type": [ "number", "null" ] }, "member_affiliate_status": { "description": "The enrollment status in the member affiliate program.", "enum": [ "enabled", "disabled" ], "example": "enabled", "type": "string" }, "metadata": { "description": "Custom key-value pairs to store on the product.", "example": { "bay": "1", "duration_hours": "4" }, "type": [ "object", "null" ] }, "product_tax_code_id": { "description": "The unique identifier of the tax classification code. See the available [product categories](https://docs.numeral.com/essentials/product-categories).", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "redirect_purchase_url": { "description": "A URL to redirect the customer to after purchase.", "example": "https://shinetime.example/thanks", "type": [ "string", "null" ] }, "route": { "description": "The URL slug for the product's public link.", "example": "interior-deep-clean", "type": [ "string", "null" ] }, "send_welcome_message": { "description": "Whether to send an automated welcome message via support chat when a user joins this product. Defaults to true.", "example": true, "type": [ "boolean", "null" ] }, "title": { "description": "The display name of the product. Maximum 80 characters.", "example": "Interior Deep Clean", "maxLength": 80, "type": "string" }, "visibility": { "description": "Whether the product is visible to customers.", "example": "visible", "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product created" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "access_pass:create" ] } ], "summary": "Create Product", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "/products/{id}": { "delete": { "description": "Deletes a product. Only products with no memberships, entries, reviews, or invoices can be deleted.", "operationId": "deleteProduct", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted product.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "product deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" } }, "security": [ { "bearerAuth": [ "access_pass:delete" ] } ], "summary": "Delete Product", "tags": [ "Products" ] }, "get": { "description": "Retrieves a product. Requires no authentication.", "operationId": "retrieveProduct", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product retrieved without authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" } }, "security": [], "summary": "Retrieve Product", "tags": [ "Products" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the product.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates an existing product.", "operationId": "updateProduct", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "banner_image": { "description": "A wide image for the product, shown on the product page and on listing cards. Pass `{ id }` for an existing attachment or `{ direct_upload_id }` for a completed direct upload; `null` removes it.", "properties": { "direct_upload_id": { "description": "The signed id of a completed direct upload.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "description": { "description": "A written description displayed on the product page. Maximum 1,500 characters.", "example": "Full interior extraction, leather conditioning, and an ozone odor treatment.", "maxLength": 1500, "type": [ "string", "null" ] }, "gallery_images": { "description": "Images or videos displayed in the product gallery, in display order. Replaces the existing gallery. Send an empty array to clear it; omit or pass null to leave it unchanged. A banner image does not populate the gallery.", "items": { "properties": { "direct_upload_id": { "description": "The signed ID of a completed direct upload, as an alternative to id.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "description": "The tag of an already-uploaded attachment.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "maxItems": 8, "type": [ "array", "null" ] }, "headline": { "description": "A short marketing headline for the product page. Maximum 80 characters.", "example": "Steam, shampoo, and odor removal in one visit", "maxLength": 80, "type": [ "string", "null" ] }, "labels": { "description": "Labels used to group products into collections. Replaces the existing labels. Send an empty array to clear them.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "metadata": { "description": "Custom key-value pairs to store on the product.", "example": { "bay": "1", "duration_hours": "4" }, "type": [ "object", "null" ] }, "product_tax_code_id": { "description": "The unique identifier of the tax classification code. See the available [product categories](https://docs.numeral.com/essentials/product-categories).", "example": "ptc_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "send_welcome_message": { "description": "Whether to send an automated welcome message via support chat when a user joins this product.", "example": true, "type": [ "boolean", "null" ] }, "title": { "description": "The display name of the product. Maximum 80 characters.", "example": "Interior Deep Clean", "maxLength": 80, "type": "string" }, "visibility": { "description": "Whether the product is visible to customers.", "example": "visible", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product tax code updated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" } }, "security": [ { "bearerAuth": [ "access_pass:update" ] } ], "summary": "Update Product", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "/products/{id}/publish": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the product, prefixed `prod_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Submits a product to the whop.com marketplace for review. The product moves to `pending_review`; a Whop reviewer approves it before it goes live. Requires a logo, a headline, and at least one gallery image or video; the request fails naming whichever is missing.", "operationId": "publishProduct", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product submitted for review" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "access_pass:update" ] } ], "summary": "Publish Product", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "/products/{id}/unpublish": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the product, prefixed `prod_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Removes a product from the whop.com marketplace. The product moves to `not_available`.", "operationId": "unpublishProduct", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "description": "product removed from the marketplace" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "product not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "access_pass:update" ] } ], "summary": "Unpublish Product", "tags": [ "Products" ] }, "x-whop-surface": "native" }, "/promo_codes": { "get": { "description": "Lists an account's promo codes.", "operationId": "listPromoCodes", "parameters": [ { "description": "Account whose promo codes are listed (`biz_` tag).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Promo-code status. `expired` groups inactive and archived codes.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "inactive", "archived", "expired" ], "type": "string" } }, { "description": "Only promo codes scoped to these product IDs.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only promo codes scoped to these variant IDs.", "in": "query", "name": "variant_ids", "required": false, "schema": { "items": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only promo codes created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only promo codes created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Sort field.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PromoCodeListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "promo codes listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" } }, "security": [ { "bearerAuth": [ "promo_code:basic:read" ] } ], "summary": "List Promo Codes", "tags": [ "Promo Codes" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a promo code for an account.", "operationId": "createPromoCode", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount_off": { "example": 25, "type": "number" }, "base_currency": { "enum": [ "usd", "sgd", "inr", "aud", "brl", "cad", "dkk", "eur", "nok", "gbp", "sek", "chf", "hkd", "huf", "jpy", "mxn", "myr", "pln", "czk", "nzd", "aed", "eth", "ape", "cop", "ron", "thb", "bgn", "idr", "dop", "php", "try", "krw", "twd", "vnd", "pkr", "clp", "uyu", "ars", "zar", "dzd", "tnd", "mad", "kes", "kwd", "jod", "all", "xcd", "amd", "bsd", "bhd", "bob", "bam", "khr", "crc", "xof", "egp", "etb", "gmd", "ghs", "gtq", "gyd", "ils", "jmd", "mop", "mga", "mur", "mdl", "mnt", "nad", "ngn", "mkd", "omr", "pyg", "pen", "qar", "rwf", "sar", "rsd", "lkr", "tzs", "ttd", "uzs", "rub", "btc", "cny", "usdt", "kzt", "awg", "whop_usd", "xau" ], "example": "usd", "type": "string" }, "churned_users_only": { "example": false, "type": "boolean" }, "code": { "example": "AFFILIATE25", "type": "string" }, "existing_memberships_only": { "example": false, "type": "boolean" }, "expires_at": { "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "new_users_only": { "example": true, "type": "boolean" }, "one_per_customer": { "example": true, "type": "boolean" }, "product_id": { "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "promo_duration_months": { "example": 3, "type": "integer" }, "promo_type": { "enum": [ "percentage", "flat_amount" ], "example": "percentage", "type": "string" }, "stock": { "example": 200, "type": [ "integer", "null" ] }, "unlimited_stock": { "example": false, "type": "boolean" }, "variant_ids": { "items": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, "required": [ "account_id", "amount_off", "base_currency", "code", "new_users_only", "promo_duration_months", "promo_type" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "promo code created" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing credentials" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "promo_code:create" ] } ], "summary": "Create Promo Code", "tags": [ "Promo Codes" ] }, "x-whop-surface": "native" }, "/promo_codes/{id}": { "delete": { "description": "Archives a promo code so it cannot be used in future checkouts.", "operationId": "deletePromoCode", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "promo_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "promo code deleted" } }, "security": [ { "bearerAuth": [ "promo_code:delete" ] } ], "summary": "Delete Promo Code", "tags": [ "Promo Codes" ] }, "get": { "description": "Retrieves a promo code by ID.", "operationId": "retrievePromoCode", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "promo code retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "promo code not found" } }, "security": [ { "bearerAuth": [ "promo_code:basic:read" ] } ], "summary": "Retrieve Promo Code", "tags": [ "Promo Codes" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Promo code ID (`promo_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/promo_codes/{id}/activate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Promo code ID (`promo_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Turns an inactive promo code back on so it can be redeemed at checkout.", "operationId": "activatePromoCode", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "promo code activated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "promo code archived" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "promo_code:update" ] } ], "summary": "Activate Promo Code", "tags": [ "Promo Codes" ] }, "x-whop-surface": "native" }, "/promo_codes/{id}/deactivate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Promo code ID (`promo_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Turns off an active promo code so it can no longer be redeemed at checkout.", "operationId": "deactivatePromoCode", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoCode" } } }, "description": "promo code deactivated" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "promo_code:update" ] } ], "summary": "Deactivate Promo Code", "tags": [ "Promo Codes" ] }, "x-whop-surface": "native" }, "/reactions": { "get": { "description": "Returns a paginated list of emoji reactions on a specific message or forum post, sorted by most recent.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `forum:read`\n - `livestream:chat:read`\n - `support_chat:read`", "operationId": "listReaction", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "resource_id", "required": true, "schema": { "description": "The unique identifier of the message or forum post to list reactions for.", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for Reaction.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/ReactionListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "forum:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "List reactions", "tags": [ "Reactions" ], "x-group-title": "Engagement" }, "post": { "description": "Add an emoji reaction or poll vote to a message or forum post. In forums, the reaction is always a like.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `forum:read`\n - `livestream:chat:read`\n - `support_chat:read`", "operationId": "createReaction", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateReaction", "properties": { "emoji": { "description": "The emoji to react with, in shortcode or unicode format. For example, ':heart:' or a unicode emoji. Ignored in forums where reactions are always likes.", "type": [ "string", "null" ] }, "poll_option_id": { "description": "The unique identifier of a poll option to vote for. Only valid when the target message or post contains a poll.", "type": [ "string", "null" ] }, "resource_id": { "description": "The unique identifier of the message or forum post to react to.", "type": "string" } }, "required": [ "resource_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "forum:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Create reaction", "tags": [ "Reactions" ], "x-group-title": "Engagement" } }, "/reactions/{id}": { "delete": { "description": "Remove an emoji reaction from a message or forum post. Only the reaction author or a channel admin can remove a reaction.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `forum:read`\n - `livestream:chat:read`\n - `support_chat:read`", "operationId": "deleteReaction", "parameters": [ { "description": "The unique identifier of the reaction to remove, or the identifier of the message or forum post to remove a reaction from. When passing a message or post ID, you must also provide the emoji argument.", "in": "path", "name": "id", "required": true, "schema": { "example": "reac_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "explode": true, "in": "query", "name": "emoji", "required": false, "schema": { "description": "The emoji to remove, in shortcode or unicode format. For example, ':heart:' or a unicode emoji. Required when the id refers to a message or post instead of a reaction.", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Represents `true` or `false` values.", "type": "boolean" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "forum:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Delete reaction", "tags": [ "Reactions" ], "x-group-title": "Engagement" }, "get": { "description": "Retrieves the details of an existing reaction.\n\nRequired permissions (one of):\n - `chat:read`\n - `dms:read`\n - `forum:read`\n - `livestream:chat:read`\n - `support_chat:read`", "operationId": "retrieveReaction", "parameters": [ { "description": "The unique identifier of the reaction to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "example": "reac_xxxxxxxxxxxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reaction" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "chat:read" ] }, { "bearerAuth": [ "dms:read" ] }, { "bearerAuth": [ "forum:read" ] }, { "bearerAuth": [ "livestream:chat:read" ] }, { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Retrieve reaction", "tags": [ "Reactions" ], "x-group-title": "Engagement" } }, "/refunds": { "get": { "description": "Lists refunds the caller can read, newest first. Filter by payment, account, or buyer to narrow the results.", "operationId": "listRefunds", "parameters": [ { "description": "Only refunds issued by this account, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only refunds of this payment, prefixed `pay_`.", "in": "query", "name": "payment_id", "required": false, "schema": { "type": "string" } }, { "description": "Only refunds to this buyer, prefixed `user_`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only refunds requested before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only refunds requested after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Refund" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "refunds listed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "unsupported sort field" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown payment filter" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "List Refunds", "tags": [ "Refunds" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/refunds/{id}": { "get": { "description": "Returns one refund.", "operationId": "retrieveRefund", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } }, "description": "refund retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:basic:read" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown refund" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "Retrieve Refund", "tags": [ "Refunds" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The refund to retrieve, prefixed `rf_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/resolution_center_cases": { "get": { "description": "Lists resolution center cases. Without `account_id` you get every case you can read — the ones you opened as a buyer and every account you are a team member of; the filters narrow that list.", "operationId": "listResolutionCenterCases", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Only cases filed against this account (`biz_` tag). With read access to the account this lists its whole queue; without, only the cases you opened against it.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only cases opened by this customer — a `user_` tag, or `me` for the calling user. It narrows what you can already read, so `me` lists the cases you opened without the ones on accounts you are a team member of.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort cases by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "response_due_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only cases in these statuses. Repeat the parameter to pass several — one paginated list covers all of them.", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "awaiting_merchant", "awaiting_customer", "under_review", "closed" ], "example": "awaiting_merchant", "type": "string" }, "type": "array" } }, { "description": "Only cases opened for these reasons. Repeat the parameter to pass several.", "in": "query", "name": "reason", "required": false, "schema": { "items": { "enum": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "example": "fraudulent", "type": "string" }, "type": "array" } }, { "description": "Only closed cases that ended these ways. Repeat the parameter to pass several.", "in": "query", "name": "outcome", "required": false, "schema": { "items": { "enum": [ "customer_won", "merchant_won", "withdrawn" ], "example": "customer_won", "type": "string" }, "type": "array" } }, { "description": "Only cases created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only cases created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "cases listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account_id" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "List Resolution Center Cases", "tags": [ "Resolution Center Cases" ] }, "post": { "description": "Opens a case, as the customer, against one of your own payments. Provide the payment (`receipt_id`), the `reason`, and a `message`.", "operationId": "createResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "The customer's explanation.", "example": "The mobile detailer never showed up for the Ceramic Coating appointment.", "type": "string" }, "reason": { "description": "What went wrong. Uses the same vocabulary as `/disputes`.", "enum": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "example": "product_not_received", "type": "string" }, "receipt_id": { "description": "The payment to open the case against (`pay_` tag).", "example": "pay_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "receipt_id", "reason", "message" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case opened" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:manage" ] } ], "summary": "Open a Case as the Customer", "tags": [ "Resolution Center Cases" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/summary": { "get": { "description": "Aggregates the same cases `GET /resolution_center_cases` lists, using the same filters. Use it to build status tabs and issue filters without paging the whole list.", "operationId": "retrieveResolutionCenterCaseSummary", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Which breakdowns to return, keyed by these names under `groups`. Repeat the parameter to ask for several; omit it for all of them.", "in": "query", "name": "groups", "required": false, "schema": { "items": { "enum": [ "status", "reason", "outcome" ], "example": "status", "type": "string" }, "type": "array" } }, { "description": "The account to summarize cases for (`biz_` tag).", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only cases opened by this customer — a `user_` tag, or `me` for the calling user.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only cases in these statuses.", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "awaiting_merchant", "awaiting_customer", "under_review", "closed" ], "example": "awaiting_merchant", "type": "string" }, "type": "array" } }, { "description": "Only cases opened for these reasons.", "in": "query", "name": "reason", "required": false, "schema": { "items": { "enum": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "example": "fraudulent", "type": "string" }, "type": "array" } }, { "description": "Only closed cases that ended these ways.", "in": "query", "name": "outcome", "required": false, "schema": { "items": { "enum": [ "customer_won", "merchant_won", "withdrawn" ], "example": "customer_won", "type": "string" }, "type": "array" } }, { "description": "Only count cases created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only count cases created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "groups": { "description": "One entry per requested breakdown, keyed by the field it groups on. A field you did not ask for is absent.", "properties": { "outcome": { "description": "How many of the matching cases ended each way. Every outcome is present, including those with a count of zero; open cases are counted in none of them.", "properties": { "customer_won": { "example": 0, "type": "integer" }, "merchant_won": { "example": 0, "type": "integer" }, "withdrawn": { "example": 0, "type": "integer" } }, "required": [ "customer_won", "merchant_won", "withdrawn" ], "type": "object" }, "reason": { "description": "How many of the matching cases were opened for each reason. Every reason is present, including those with a count of zero.", "properties": { "fraudulent": { "example": 0, "type": "integer" }, "not_as_described": { "example": 0, "type": "integer" }, "product_not_received": { "example": 1, "type": "integer" }, "product_unacceptable": { "example": 0, "type": "integer" }, "subscription_canceled": { "example": 0, "type": "integer" } }, "required": [ "fraudulent", "product_not_received", "not_as_described", "product_unacceptable", "subscription_canceled" ], "type": "object" }, "status": { "description": "How many of the matching cases are in each status. Every status is present, including those with a count of zero.", "properties": { "awaiting_customer": { "example": 0, "type": "integer" }, "awaiting_merchant": { "example": 1, "type": "integer" }, "closed": { "example": 0, "type": "integer" }, "under_review": { "example": 0, "type": "integer" } }, "required": [ "awaiting_merchant", "awaiting_customer", "under_review", "closed" ], "type": "object" } }, "type": "object" }, "total": { "description": "How many cases match the filters.", "example": 1, "type": "integer" } }, "required": [ "total", "groups" ], "type": "object" } } }, "description": "summary returned" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "an unrecognized breakdown" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "Retrieve Resolution Center Case Summary", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}": { "get": { "description": "Retrieves a single resolution center case with its full event timeline.", "operationId": "retrieveResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case returned" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no case with that ID" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "Retrieve Resolution Center Case", "tags": [ "Resolution Center Cases" ] }, "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/resolution_center_cases/{id}/accept": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Accepts the case in the customer's favor, as the merchant: refunds the payment in full and closes the case.", "operationId": "acceptResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "An optional note to the customer, recorded on the case timeline.", "example": "Refunding the deposit in full — we could not make the Austin booking window.", "type": "string" }, "terminate_membership": { "description": "Whether to also terminate the customer's membership.", "example": false, "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case accepted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required write scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center" ] } ], "summary": "Accept a Case", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/appeal": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Appeals a decision, as the customer, on a case that closed in the merchant's favor. Escalates the case to Whop for platform review. A case can be appealed once, within 7 days of the decision.", "operationId": "appealResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "Why you are appealing the decision.", "example": "The coating is already flaking on the hood two weeks later.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case appealed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:manage" ] } ], "summary": "Appeal a Case", "tags": [ "Resolution Center Cases" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/deny": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Denies the case, as the merchant: rejects the claim and closes the case with no refund.", "operationId": "denyResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "Why the claim is being denied. Shown to the customer.", "example": "The ceramic coating was applied and the vehicle was collected on 2026-01-05.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case denied" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center" ] } ], "summary": "Deny a Case", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/events": { "get": { "description": "Lists the case timeline, newest first. Events the viewer is not allowed to see are omitted — a customer reads the customer-visible timeline, the merchant reads the full one.", "operationId": "listResolutionCenterCaseEvents", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ResolutionEvent" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "events listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no case with that ID" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:read" ] } ], "summary": "List Resolution Center Case Events", "tags": [ "Resolution Center Cases" ] }, "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/resolution_center_cases/{id}/reply": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Replies to an open request for information on the case. As the merchant this answers Whop's request (valid while the case awaits your information); as the customer it provides the information requested from you. The actor is resolved from the credential.", "operationId": "replyToResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "The reply to add to the case.", "example": "Here are the before and after photos from the Burnet Rd bay.", "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "reply added" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center" ] }, { "bearerAuth": [ "payment:resolution_center_case:manage" ] } ], "summary": "Reply to a Case", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/request_info": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Asks the customer for more information, as the merchant. Allowed up to 3 times per case before you must accept or deny it.", "operationId": "requestResolutionCenterCaseInfo", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Up to 3 evidence files, by existing file `id` or `direct_upload_id`.", "items": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "message": { "description": "What you need from the customer.", "example": "Please send a photo of the panels you are unhappy with.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "information requested" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center" ] } ], "summary": "Request Information from the Customer", "tags": [ "Resolution Center Cases" ] }, "x-whop-surface": "native" }, "/resolution_center_cases/{id}/withdraw": { "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Withdraws (cancels) a case you opened, as the customer. Only possible while the case is still open.", "operationId": "withdrawResolutionCenterCase", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionCenterCase" } } }, "description": "case withdrawn" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:resolution_center_case:manage" ] } ], "summary": "Withdraw a Case", "tags": [ "Resolution Center Cases" ], "x-whop-credentials": [ "oauth_token" ] }, "x-whop-surface": "native" }, "/reviews": { "get": { "description": "Lists the published reviews for a product or account. Without `account_id` or `product_id`, a user lists the reviews they wrote, an account or app API key lists its account's reviews, and a request without credentials returns 400.", "operationId": "listReview", "parameters": [ { "description": "The unique identifier of the account to list reviews for.", "in": "query", "name": "account_id", "required": false, "schema": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, { "description": "The unique identifier of the product to list reviews for.", "in": "query", "name": "product_id", "required": false, "schema": { "example": "prod_xxxxxxxxxxxxx", "type": "string" } }, { "description": "The minimum star rating to include in results, from 1 to 5 inclusive.", "in": "query", "name": "min_stars", "required": false, "schema": { "type": "integer" } }, { "description": "The maximum star rating to include in results, from 1 to 5 inclusive.", "in": "query", "name": "max_stars", "required": false, "schema": { "type": "integer" } }, { "description": "Only return reviews created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only return reviews created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The field to sort reviews by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "stars" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ReviewListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Reviews for the product" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "No filter and no credentials" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Product not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "List reviews", "tags": [ "Reviews" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/reviews/{id}": { "delete": { "description": "Deletes a review the signed-in user wrote. Requires the `review:delete` scope, and returns 404 for a review another user wrote.", "operationId": "deleteReview", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "rev_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "Review deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Not signed in" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Missing review:delete scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Review not found or written by someone else" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete review", "tags": [ "Reviews" ], "x-whop-credentials": [ "oauth_token" ] }, "get": { "description": "Retrieves a published review. Reviews that are not published return 404.", "operationId": "retrieveReview", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } }, "description": "Review details" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Review not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve review", "tags": [ "Reviews" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the review.", "in": "path", "name": "id", "required": true, "schema": { "example": "rev_xxxxxxxxxxxxxx", "type": "string" } } ], "x-whop-surface": "native" }, "/setup_intents": { "get": { "description": "Lists setup intents newest first. An account API key lists its own account; a user token lists every account it can read, or one account with `account_id`.", "operationId": "listSetupIntents", "parameters": [ { "description": "Only setup intents for this account, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only setup intents in this state.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "processing", "succeeded", "canceled", "requires_action" ], "type": "string" } }, { "description": "Only setup intents created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only setup intents created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SetupIntent" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "setup intents listed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "unknown status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:setup_intent:read" } }, "security": [ { "bearerAuth": [ "payment:setup_intent:read" ] } ], "summary": "List Setup Intents", "tags": [ "Setup Intents" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Saves a buyer's payment method for later without charging it — one the buyer just supplied through the payment elements in setup mode, or one already on file to re-verify. The setup completes in the background, so the response is the setup intent as created, not its outcome: hand `client_secret` to the elements' `handleNextAction`, or poll Retrieve setup status. A buyer's own token holding `member:payment_methods:use` may create a setup intent for itself from a confirmation token.", "operationId": "createSetupIntent", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to save the payment method for, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "confirmation_token": { "description": "A confirmation token describing a payment method the buyer just supplied, collected by the payment elements in setup mode. Provide this or `payment_method_id`, not both. The buyer is resolved from the token's billing email, or from `email`, and may still have a step to complete — poll Retrieve setup status for what to do next.", "example": "ctok_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "currency": { "description": "The currency the saved payment method will be used with, as a lowercase ISO 4217 code. Controls which currency-specific payment methods are available. Defaults to `usd`.", "example": "usd", "type": [ "string", "null" ] }, "email": { "description": "Overrides the buyer email carried on the confirmation token, resolving or creating the user the method belongs to. Ignored unless `confirmation_token` is provided, and when the token was created by a signed-in buyer or the caller is the buyer.", "example": "dana@shinetime.example", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Custom metadata to attach to the setup intent. Returned on the setup intent and its webhooks.", "example": { "customer_id": "cus_4417" }, "type": [ "object", "null" ] }, "owner_id": { "description": "Who the saved payment method belongs to. Pass `account_id` to save it on the account itself, which needs `payment:charge` on the account. Pass your own user ID, prefixed `user_`, to save it on the authenticated user. Omit it to save it on the buyer: the caller when it is the buyer, otherwise the user the confirmation token names. Not available with `payment_method_id`, which keeps its current owner, or with `purpose`.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "payment_method_id": { "description": "An existing payment method to re-verify and save, prefixed `payt_`. Provide this or `confirmation_token`, not both. Not available to a buyer credential.", "example": "payt_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "purpose": { "description": "What the saved payment method will pay for. Set to `ads_billing` when saving a card to pay for Whop Ads on `account_id`: the card is verified by Whop Ads, the merchant that charges it, which helps minimize security declines on ad payments, and it requires `ad_campaign:create` on `account_id`. Omit it for any other payment method.", "enum": [ "ads_billing", null ], "example": "ads_billing", "type": [ "string", "null" ] }, "return_url": { "description": "Where the buyer continues after completing an off-site step. An absolute https URL without credentials, at most 2,048 characters.", "example": "https://shinetime.example/billing/saved", "type": [ "string", "null" ] }, "three_ds_level": { "description": "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. Applies to this setup only, and only while the buyer is present: ignored with `payment_method_id`, which re-verifies off session. Not available with `purpose: ads_billing`. Defaults to `frictionless_if_required`.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "mandate_challenge", "type": [ "string", "null" ] } }, "required": [ "account_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntent" } } }, "description": "setup intent created from a confirmation token" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "confirmation token combined with a stored payment method" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:charge" }, "404": { "$ref": "#/components/responses/NotFound", "description": "confirmation token from another account" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "summary": "Create Setup Intent", "tags": [ "Setup Intents" ] }, "x-whop-surface": "native" }, "/setup_intents/direct": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Saves a card for later charges from card details you hold yourself, for integrators whose own systems are PCI compliant. Send this operation to the vault host, which tokenizes the card before it reaches Whop; the official SDKs route it there, and raw card details sent to the regular host are refused. The setup runs in the background: poll Retrieve setup status for its outcome and for anything the buyer must still do, such as 3D Secure. Once it succeeds, the saved payment method arrives on the `setup_intent.succeeded` webhook and in List payment methods for the member.", "operationId": "createDirectSetupIntent", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account the card is saved for, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "billing_details": { "description": "The buyer's billing details.", "properties": { "address": { "description": "The billing address.", "properties": { "city": { "description": "City.", "example": "San Francisco", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code.", "example": "US", "type": "string" }, "line1": { "description": "Street address, first line.", "example": "1 Market St", "type": "string" }, "line2": { "description": "Street address, second line.", "example": "Suite 400", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal code.", "example": "94105", "type": "string" }, "state": { "description": "State, province or region.", "example": "CA", "type": [ "string", "null" ] } }, "required": [ "postal_code", "country" ], "type": "object" }, "email": { "description": "The buyer's email. Resolves or creates the user the operation is for.", "example": "dana@shinetime.example", "type": "string" }, "name": { "description": "The name on the card.", "example": "Dana Shine", "type": "string" }, "phone": { "description": "The buyer's phone number in E.164 format.", "example": "+14155550123", "type": [ "string", "null" ] } }, "required": [ "name", "email", "address" ], "type": "object" }, "currency": { "description": "The currency the card will be charged in, as a three-letter code. Defaults to usd.", "example": "usd", "type": [ "string", "null" ] }, "member_id": { "description": "The member the card belongs to, prefixed `mber_`. When omitted the buyer is resolved from `billing_details.email`.", "example": "mber_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Custom metadata to attach to the setup.", "example": { "crm_id": "C-88" }, "type": [ "object", "null" ] }, "payment_method": { "description": "The payment method to save, as the raw details the caller holds. Raw details are accepted only on the vault host, where Whop's vault tokenizes them in transit; the official SDKs route this operation there. Whop's own clients, which tokenize with the Basis Theory SDK, send the resulting token intent id to the regular host.", "properties": { "card": { "description": "The card to save. Present when `type` is `card`.", "properties": { "details": { "description": "The card's raw fields. Sent to the vault host and tokenized before it reaches Whop; Whop's servers never receive the number.", "example": { "cvc": "123", "exp_month": 12, "exp_year": 2031, "number": "4242424242424242" }, "properties": { "cvc": { "description": "The card security code.", "example": "123", "type": "string" }, "exp_month": { "description": "The expiry month.", "example": 12, "maximum": 12, "minimum": 1, "type": "integer" }, "exp_year": { "description": "The four-digit expiry year.", "example": 2031, "type": "integer" }, "number": { "description": "The card number, digits only.", "example": "4242424242424242", "type": "string" } }, "required": [ "number", "exp_month", "exp_year" ], "type": "object", "x-whop-vault": { "bt_type": "card", "data": { "cvc": "cvc", "exp_month": "expiration_month", "exp_year": "expiration_year", "number": "number" }, "type": "card" } }, "network_transaction_id": { "description": "The network transaction id of the card's most recent customer-initiated transaction on another processor, when the caller brings a card it has charged before. Required for an `off_session` charge; on a setup it is kept with the saved card for its later charges. Up to 64 characters.", "example": "016153570198200", "type": [ "string", "null" ] } }, "required": [ "details" ], "type": "object" }, "type": { "description": "The kind of payment method; the member named after it carries the credential.", "enum": [ "card" ], "example": "card", "type": "string" } }, "required": [ "type" ], "type": "object" }, "return_url": { "description": "Where the buyer continues after completing an off-site step such as 3D Secure. An absolute https URL without credentials, at most 2,048 characters.", "example": "https://shinetime.example/billing/saved", "type": [ "string", "null" ] } }, "required": [ "account_id", "payment_method", "billing_details" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntent" } } }, "description": "setup started from card details" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payment:charge" ] } ], "servers": [ { "url": "https://vault-api.whop.com/api/v1", "x-fern-server-name": "vault" }, { "url": "https://sandbox-vault-api.whop.com/api/v1", "x-fern-server-name": "vault" } ], "summary": "Save Card Details", "tags": [ "Setup Intents" ], "x-whop-docs": "gated", "x-whop-docs-groups": [ "direct-card" ], "x-whop-vault": true }, "x-whop-surface": "native" }, "/setup_intents/{id}": { "get": { "description": "Retrieves a setup intent. Once its `status` is `succeeded`, charge the saved method by its `payment_method_id`. The buyer's own token may retrieve a setup intent that belongs to it.", "operationId": "retrieveSetupIntent", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntent" } } }, "description": "setup intent retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential without payment:setup_intent:read" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown setup intent" } }, "security": [ { "bearerAuth": [ "payment:setup_intent:read" ] } ], "summary": "Retrieve Setup Intent", "tags": [ "Setup Intents" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The setup intent to retrieve, prefixed `sint_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/setup_intents/{setup_intent_id}/return_url": { "patch": { "description": "Changes where the buyer lands after completing an off-site step, up until they return. Accepts either a secret key or the setup's own `client_secret` in the body, so the surface that knows the final destination can set it.", "operationId": "updateReturnUrlSetupIntent", "parameters": [ { "description": "The unique identifier of the setup intent.", "in": "path", "name": "setup_intent_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_secret": { "description": "The setup's own `client_secret`, for a caller without a secret key.", "type": "string" }, "return_url": { "description": "Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials (http is allowed for localhost), at most 2,048 characters.", "example": "https://shinetime.example/checkout/thanks", "type": "string" } }, "required": [ "return_url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupStatus" } } }, "description": "Return URL updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid return URL" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Forbidden" } }, "security": [ {}, { "bearerAuth": [ "payment:setup_intent:manage" ] } ], "summary": "Update setup return URL", "tags": [ "Setup Intents" ] }, "x-whop-surface": "native" }, "/setup_intents/{setup_intent_id}/status": { "get": { "description": "Retrieves how far a setup has got and what the buyer must do next, if anything. Collection runs in the background, so poll this rather than reading the create response. Accepts either a secret key or the setup's own `client_secret` as a query parameter, so the surface collecting the payment method can poll it directly.", "operationId": "retrieveStatusSetupIntent", "parameters": [ { "description": "The unique identifier of the setup intent.", "in": "path", "name": "setup_intent_id", "required": true, "schema": { "type": "string" } }, { "description": "The setup's own `client_secret`, for a caller without a secret key.", "in": "query", "name": "client_secret", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupStatus" } } }, "description": "Setup status retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound", "description": "Setup intent not found" } }, "security": [ {}, { "bearerAuth": [ "payment:setup_intent:read" ] } ], "summary": "Retrieve setup status", "tags": [ "Setup Intents" ] }, "x-whop-surface": "native" }, "/shipments": { "get": { "description": "Lists an account's shipments.", "operationId": "listShipments", "parameters": [ { "description": "The account to list shipments for. Defaults to the acting account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to shipments with this delivery status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled", "error" ], "type": "string" } }, { "description": "Only shipments fulfilling these payments, each prefixed `pay_`. Repeat the parameter to pass several, up to 100 per request — one paginated list covers all of them.", "explode": true, "in": "query", "name": "payment_id", "required": false, "schema": { "items": { "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Return shipments created before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Return shipments created after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Shipment" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "excludes the created_after boundary row" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status filter" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient permissions" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account" } }, "security": [ { "bearerAuth": [ "shipment:basic:read" ] } ], "summary": "List Shipments", "tags": [ "Shipments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Attaches a carrier tracking number to a payment and begins tracking it.", "operationId": "createShipment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The unique identifier of the account, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "payment_id": { "description": "The payment to attach the shipment to, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "tracking_number": { "description": "The carrier-assigned tracking number.", "example": "1Z999AA10123456784", "type": "string" } }, "required": [ "payment_id", "tracking_number" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "description": "shipment created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing tracking_number" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient permissions" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "shipment:create" ] } ], "summary": "Create Shipment", "tags": [ "Shipments" ] }, "x-whop-surface": "native" }, "/shipments/lookup": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Finds the delivery for a purchase from an account with customer tracking turned on, using exactly one order or tracking number plus the buyer's current receipt email. No authentication is required and no sign-in or session is created. Email matching ignores case and surrounding whitespace, but dots and +tags must match. Every miss returns the same 404: an unknown account, tracking turned off, a wrong number or email, an unpaid order or a purchase with nothing to ship. `shipment` is `null` while a paid physical purchase has no tracking yet. Limited to 30 attempts per five minutes per client IP. Responses are never cached or replayed with Idempotency-Key.", "operationId": "lookupShipment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The selling account, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "maxLength": 255, "type": "string" }, "email": { "description": "The buyer's current receipt email.", "example": "marcus@shinetime.example", "format": "email", "maxLength": 254, "type": "string" }, "order_number": { "description": "The payment ID prefixed `pay_`, or the order number printed on the receipt (optional leading `#`). Supply this or `tracking_number`, not both.", "example": "pay_xxxxxxxxxxxxxx", "maxLength": 255, "type": "string" }, "tracking_number": { "description": "The exact carrier tracking number. Supply this or `order_number`, not both.", "maxLength": 255, "type": "string" } }, "required": [ "account_id", "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentLookup" } } }, "description": "shipment found" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid lookup" }, "404": { "$ref": "#/components/responses/NotFound", "description": "shipment not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [], "summary": "Look Up Shipment", "tags": [ "Shipments" ] }, "x-whop-surface": "native" }, "/shipments/{id}": { "get": { "description": "Retrieves a shipment by its ID, or by the ID of the payment it fulfills.", "operationId": "retrieveShipment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "description": "shipment retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient permissions" }, "404": { "$ref": "#/components/responses/NotFound", "description": "shipment not found" } }, "security": [ { "bearerAuth": [ "shipment:basic:read" ] }, { "bearerAuth": [] } ], "summary": "Retrieve Shipment", "tags": [ "Shipments" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The shipment id (`ship_`), or the payment id (`pay_`) it fulfills.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a shipment's tracking number and re-tracks it with the carrier.", "operationId": "updateShipment", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "tracking_number": { "description": "The new carrier-assigned tracking number.", "example": "9400111899223456789012", "type": "string" } }, "required": [ "tracking_number" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } }, "description": "shipment updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing tracking_number" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "insufficient permissions" }, "404": { "$ref": "#/components/responses/NotFound", "description": "shipment not found" } }, "security": [ { "bearerAuth": [ "shipment:create" ] } ], "summary": "Update Shipment", "tags": [ "Shipments" ] }, "x-whop-surface": "native" }, "/social_accounts": { "get": { "deprecated": true, "description": "Deprecated compatibility endpoint. List external accounts with `GET /external_accounts` instead.", "operationId": "listSocialAccounts", "parameters": [ { "description": "The Account that the external accounts are connected to. Provide either this or user_id.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The User that the external accounts are connected to. Provide either this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return external accounts for the platform that is specified.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram", "linkedin", "snapchat", "klaviyo" ], "type": "string" } }, { "description": "Only return external accounts linked with this trust level, such as `oauth` for accounts connected through OAuth.", "in": "query", "name": "trust_level", "required": false, "schema": { "enum": [ "oauth", "api_key", "verified", "authorized", "claimed", "scraped" ], "type": "string" } }, { "description": "Only return external accounts that are verified on the platform.", "in": "query", "name": "verified", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return external accounts that have these scopes.", "in": "query", "name": "scopes", "required": false, "schema": { "items": { "enum": [ "advertise" ], "type": "string" }, "type": "array" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort external accounts by.", "in": "query", "name": "order", "required": false, "schema": { "default": "display_order", "enum": [ "display_order", "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "asc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SocialAccount" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "social accounts listed through the deprecated path" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Accounts", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "GET /external_accounts" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "deprecated": true, "description": "Deprecated compatibility endpoint. Create external accounts with `POST /external_accounts` instead.", "operationId": "createSocialAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) to create the external account for. An account-scoped API key may omit this to default to its own account. Account API keys cannot update their own account's branding through Update Account; use a user-authenticated path.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "api_key": { "description": "A private API key for the account on the platform. Required for `klaviyo`, which needs read access to Accounts; not accepted for other platforms. Whop checks the key with the platform before connecting and never returns it.", "type": "string" }, "platform": { "description": "The platform to create the external account on. `facebook` requires the account's `banner_image`, `logo`, and `description`, and `tiktok` requires its `logo`; configure them with [Update Account](/api-reference/beta/accounts/update-account). The account is returned before the platform has created it — its `id` is usable right away, and the rest of the profile fills in once provisioning finishes. `klaviyo` connects the account's existing Klaviyo account with the `api_key` you pass.", "enum": [ "facebook", "tiktok", "klaviyo" ], "example": "facebook", "type": "string" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialAccount" } } }, "description": "social account created through the deprecated path" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "social_account:create" ] } ], "summary": "Create a Social Account", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "POST /external_accounts" }, "x-whop-surface": "native" }, "/social_accounts/connect": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "deprecated": true, "description": "Deprecated compatibility endpoint. Connect external accounts with `POST /external_accounts/connect` instead.", "operationId": "connectSocialAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) to connect the external account for. An account-scoped API key may omit this to default to its own account. Omit for user profile connections.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "platform": { "description": "The platform to connect the external account on. Use `meta_business` to connect Meta Business assets, which is how Facebook Pages and Instagram accounts are connected — there is no separate `instagram` value. Use `tiktok` for TikTok accounts, `snapchat` for Snapchat Public Profiles, `linkedin` to connect the authenticated user’s LinkedIn profile, `youtube` to connect their YouTube channel, or `x` to connect their X profile.", "enum": [ "meta_business", "tiktok", "linkedin", "youtube", "x", "snapchat" ], "example": "meta_business", "type": "string" }, "redirect_url": { "description": "Where to send the user once they finish connecting their accounts. Must be an `https` URL on whop.com; any other host is rejected. On success, the user is redirected with an `external_account_connected` query param naming the platform; if the connection fails, with an `external_account_error` query param instead. The same values also arrive as `social_account_connected` / `social_account_error`.", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/ads/settings", "type": "string" }, "scopes": { "description": "The connection purpose. For `meta_business` and `snapchat`, `advertise` is required and connects company advertising assets. For `linkedin`, `youtube`, and `x`, omit scopes to connect the authenticated user’s profile; advertising is not supported. For `tiktok`, omit scopes to connect the authenticated user’s profile, or pass `advertise` to connect company advertising assets. Profile connections still request the platform permissions needed to read the profile.", "items": { "enum": [ "advertise" ], "example": "advertise", "type": "string" }, "type": "array" } }, "required": [ "redirect_url", "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "authorize_url": { "example": "https://www.facebook.com/v25.0/dialog/oauth", "type": "string" } }, "required": [ "authorize_url" ], "type": "object" } } }, "description": "authorize url returned through the deprecated path" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "social_account:create" ] } ], "summary": "Connect a Social Account", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "POST /external_accounts/connect" }, "x-whop-surface": "native" }, "/social_accounts/{id}": { "delete": { "deprecated": true, "description": "Deprecated compatibility endpoint. Disconnect external accounts with `DELETE /external_accounts/{id}` instead.", "operationId": "deleteSocialAccount", "parameters": [ { "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "social account disconnected through the deprecated path" } }, "security": [ { "bearerAuth": [ "social_account:delete" ] } ], "summary": "Delete a Social Account", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "DELETE /external_accounts/{id}" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the social account to disconnect.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/social_accounts/{id}/lead_forms": { "get": { "deprecated": true, "description": "Deprecated compatibility endpoint. List lead forms with `GET /external_accounts/{id}/lead_forms` instead.", "operationId": "listSocialAccountLeadForms", "parameters": [ { "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SocialAccountLeadForm" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "lead forms listed through the deprecated path" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Account Lead Forms", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "GET /external_accounts/{id}/lead_forms" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The social account (a sacc_ identifier) whose lead forms to list.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/social_accounts/{id}/partners": { "get": { "deprecated": true, "description": "Deprecated compatibility endpoint. List partners with `GET /external_accounts/{external_account_id}/partners` instead.", "operationId": "listSocialAccountPartners", "parameters": [ { "description": "The Account (biz_ identifier) that advertises as the Instagram account. An account-scoped API key may omit this to default to its own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SocialAccount" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "nullable": true, "type": "string" } }, "required": [ "has_next_page", "end_cursor", "has_previous_page", "start_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "partners listed through the deprecated path" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Account Partners", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "GET /external_accounts/{external_account_id}/partners" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The brand's Instagram social account (a sacc_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "deprecated": true, "description": "Deprecated compatibility endpoint. Add partners with `POST /external_accounts/{external_account_id}/partners` instead.", "operationId": "addSocialAccountPartner", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) that advertises as the Instagram account. An account-scoped API key may omit this to default to its own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "username": { "description": "The creator's Instagram username, with or without the leading `@`. The creator needs a professional (Business or Creator) Instagram account.", "example": "@luverahealth", "type": "string" } }, "required": [ "username" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialAccount" } } }, "description": "creator invited through the deprecated path" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "social_account:create" ] } ], "summary": "Add Partner", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "POST /external_accounts/{external_account_id}/partners" }, "x-whop-surface": "native" }, "/social_accounts/{id}/partners/{partner_id}": { "delete": { "deprecated": true, "description": "Deprecated compatibility endpoint. Remove partners with `DELETE /external_accounts/{external_account_id}/partners/{id}` instead.", "operationId": "removeSocialAccountPartner", "parameters": [ { "description": "The Account (biz_ identifier) that advertises as the Instagram account. An account-scoped API key may omit this to default to its own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "partner removed through the deprecated path" } }, "security": [ { "bearerAuth": [ "social_account:delete" ] } ], "summary": "Remove Partner", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "DELETE /external_accounts/{external_account_id}/partners/{id}" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The brand's Instagram social account (a sacc_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The partner creator's social account (a sacc_ identifier).", "in": "path", "name": "partner_id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/social_accounts/{id}/posts": { "get": { "deprecated": true, "description": "Deprecated compatibility endpoint. List posts with `GET /external_accounts/{id}/posts` instead.", "operationId": "listSocialAccountPosts", "parameters": [ { "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "post_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SocialAccountPost" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" } }, "required": [ "has_next_page", "end_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "posts listed through the deprecated path" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Account Posts", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "GET /external_accounts/{id}/posts" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The social account (a sacc_ identifier) whose posts to list.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/social_accounts/{id}/refresh": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The social account (a sacc_ identifier) to refresh.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "deprecated": true, "description": "Deprecated compatibility endpoint. Refresh external accounts with `POST /external_accounts/{id}/refresh` instead.", "operationId": "refreshSocialAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) the external account is connected to. An account-scoped API key may omit this to default to its own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialAccount" } } }, "description": "refresh started through the deprecated path" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Refresh", "tags": [ "Social Accounts" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-successor": "POST /external_accounts/{id}/refresh" }, "x-whop-surface": "native" }, "/stats": { "get": { "deprecated": true, "description": "Deprecated. Lists every metric without saying which ones you can chart. List chartable metrics with `GET /stats/time_series`, and aggregates that are not bucketed over time with `GET /stats/reports`.", "operationId": "listMetrics", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "The available metrics.", "items": { "properties": { "breakdowns": { "description": "Supported breakdown_by values when they differ from the filter properties.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "A short description of what the metric measures.", "example": "Ad platform delivery over time (spend, impressions, clicks) on the unified source language: source scopes by a whop::: path, exact or with a trailing :* prefix (whop alone or no source = the whole account), and group_by=source groups one path segment deeper than the filter prefix. Only whop:* paths report delivery today; other roots return nothing. breakdown_by=metric returns each delivery measure per bucket plus whole-window data.totals. breakdown_by can instead split delivery by a dimension — age, gender, age_gender, placement, publisher_platform, country, region, device_platform, or impression_device — with the metric parameter picking the measure (spend, impressions, or clicks; defaults to spend). On the placement and publisher_platform dimensions the metric parameter also accepts results, roas, and cost_per_result: conversion-side measures attributed from your own tracked events rather than reported by the ad platform, with results counting conversions that match each ad group's conversion event. Dimension entries don't sum exactly to the totals (the ad platform withholds tiny cells) and are grouped by the ad account's calendar day — they can't re-bucket into time_zone. Spend converts to convert_to (defaults to usd). Whole-account attribution numbers live in the events and people metrics.", "type": "string" }, "key": { "description": "The metric's key. Pass it to GET /stats/time_series/{metric} to query its values.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Human-readable display name for the metric.", "example": "Ad delivery", "type": "string" }, "properties": { "description": "The properties you can use with this metric — pass one as a filter (property=value) to narrow the series, or as breakdown_by=property to split it.", "items": { "example": "source", "type": "string" }, "type": "array" }, "unit": { "description": "How to read the metric's values: count is an integer, currency is a decimal amount, and percent is a number where 1.6 means 1.6%.", "enum": [ "count", "currency", "percent" ], "example": "currency", "type": "string" }, "windows": { "description": "Snapshot metrics only: the trailing windows you can pass as snapshot_window, for example 30d. Absent on live metrics, which use from/to instead.", "items": { "example": "7d", "type": "string" }, "type": "array" } }, "required": [ "key", "name", "unit", "properties", "description" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "the metric catalog served through the deprecated path" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Metrics", "tags": [ "Stats" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-docs": "hidden", "x-whop-successor": "GET /stats/time_series" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/stats/reports": { "get": { "description": "Lists every report: the aggregates that are not bucketed over time, with the breakdowns and columns each one accepts. Use it to discover what a report can return before you retrieve it. For a bucketed series, use `GET /stats/time_series`.", "operationId": "listReports", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "breakdowns": { "description": "The values `breakdown_by` accepts.", "items": { "example": "product_category", "type": "string" }, "type": "array" }, "columns": { "description": "Every property and metric the report can return.", "items": { "properties": { "aggregate": { "description": "Metrics only. How to combine the metric across rows. `none` cannot be rebuilt from rows.", "enum": [ "sum", "average", "none" ], "example": "sum", "type": "string" }, "available_on": { "description": "Properties only. The breakdowns this property can ride along with.", "items": { "example": "industry_type", "type": "string" }, "type": "array" }, "breakdowns": { "description": "Metrics only. The breakdowns the metric supports, or `null` for every one.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "default": { "description": "Metrics only. Whether the metric is returned when `columns` is omitted.", "type": "boolean" }, "key": { "description": "The column's key, as `columns` accepts it and as rows carry it.", "example": "product_category", "type": "string" }, "name": { "description": "The column's display name.", "example": "Product category", "type": "string" }, "set": { "description": "Properties only. `fixed` breakdowns list every value, zero-filled; `open` ones list values with activity.", "enum": [ "fixed", "open" ], "example": "open", "type": "string" }, "type": { "description": "Whether the column is an attribute of the row or a number measured over it.", "enum": [ "property", "metric" ], "example": "property", "type": "string" }, "unit": { "description": "Metrics only. `money` is a Money object, `rate` a decimal fraction, the rest numbers.", "enum": [ "money", "count", "rate", "months", "years" ], "example": "money", "type": "string" }, "weight": { "description": "Metrics only. For `average` metrics, the column to weight by.", "nullable": true, "type": "string" }, "windows": { "description": "Metrics only. The window tokens the metric supports, or `null` for every one.", "items": { "type": "string" }, "nullable": true, "type": "array" } }, "required": [ "key", "name", "type" ], "type": "object" }, "type": "array" }, "description": { "description": "What the report measures.", "example": "Payments across all of Whop, by business type, industry type, product category, account country or customer country.", "type": "string" }, "key": { "description": "The report's key, which is also the last segment of its path.", "example": "platform_trends", "type": "string" }, "path": { "description": "The path that retrieves the report.", "example": "/api/v1/stats/reports/platform_trends", "type": "string" }, "window_field": { "description": "The timestamp a range window filters on, such as `paid_at`.", "example": "paid_at", "nullable": true, "type": "string" }, "window_kind": { "description": "`range` reports measure activity in a period; `as_of` reports measure state at a moment.", "enum": [ "range", "as_of" ], "example": "range", "type": "string" } }, "required": [ "key", "path", "description", "window_kind", "window_field", "breakdowns", "columns" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Every report you can retrieve." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Reports", "tags": [ "Stats" ], "x-whop-docs-subgroup": "Reports" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/stats/reports/platform_trends": { "get": { "description": "Retrieves payments across all of Whop for up to four windows at once, optionally broken down by business type, industry type, product category, account country or customer country. The report covers the whole platform, so it takes no `account_id` and any authenticated caller can read it.", "operationId": "retrievePlatformTrendsReport", "parameters": [ { "description": "What each row is. Omit it for one row per window, holding the window's total.", "in": "query", "name": "breakdown_by", "required": false, "schema": { "enum": [ "business_type", "industry_type", "product_category", "account_country", "customer_country" ], "type": "string" } }, { "description": "Comma-separated properties and metrics to return on each row. `business_type` can ride along on `industry_type` rows. Defaults to `gross_revenue,businesses`.", "in": "query", "name": "columns", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated windows, at most four: `1d`, `7d`, `30d`, `90d`, `365d`, `mtd`, `qtd`, `ytd`, `all_time`, an explicit `2026-09-01..2026-10-01`, any of these prefixed `prev:` for the equal-length period before, or suffixed `@2026-09-01` to end earlier. Defaults to `30d`.", "in": "query", "name": "windows", "required": false, "schema": { "type": "string" } }, { "description": "IANA zone that day, month, quarter and year boundaries fall in. Defaults to `Etc/UTC`.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "The requested metric that ranks rows, by its value in the first window. Defaults to the first requested metric.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "gross_revenue", "businesses", "products", "payments", "customers", "aov", "repeat_rate", "median_gross_revenue", "new_businesses", "avg_business_age", "avg_owner_age", "avg_customer_age" ], "type": "string" } }, { "description": "Ranking direction. Defaults to `desc`.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Currency every money metric is converted into. Defaults to `usd`.", "in": "query", "name": "convert_to", "required": false, "schema": { "type": "string" } }, { "description": "Only counts payments to businesses of these comma-separated business types, such as `education`.", "in": "query", "name": "business_type", "required": false, "schema": { "type": "string" } }, { "description": "Only counts payments to businesses in these comma-separated industry types, such as `options_trading`.", "in": "query", "name": "industry_type", "required": false, "schema": { "type": "string" } }, { "description": "Only counts payments for products in these comma-separated product categories, such as `algo_trading_course`.", "in": "query", "name": "product_category", "required": false, "schema": { "type": "string" } }, { "description": "Only counts payments to accounts located in these comma-separated countries, as ISO 3166-1 alpha-2 codes such as `US`.", "in": "query", "name": "account_country", "required": false, "schema": { "type": "string" } }, { "description": "Only counts payments from customers in these comma-separated countries, as ISO 3166-1 alpha-2 codes such as `US`.", "in": "query", "name": "customer_country", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 1000, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "data": { "breakdown_by": "industry_type", "columns": [ { "key": "industry_type", "name": "Industry type", "type": "property" }, { "key": "business_type", "name": "Business type", "type": "property" }, { "aggregate": "sum", "key": "gross_revenue", "name": "Gross revenue", "type": "metric", "unit": "money", "weight": null }, { "aggregate": "sum", "key": "businesses", "name": "Businesses", "type": "metric", "unit": "count", "weight": null } ], "data_as_of": "2026-10-07T04:48:34Z", "report": "platform_trends", "reports": [ { "rows": [ { "business_type": { "id": "services", "name": "Services" }, "businesses": 828, "gross_revenue": { "amount": "7002670.25", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "industry_type": { "id": "marketing_agency", "name": "Marketing Agency" } } ], "window": { "as_of": null, "from": "2026-09-30T04:00:00Z", "key": "7d", "kind": "range", "time_zone": "Etc/UTC", "to": "2026-10-07T04:00:00Z" } }, { "rows": [ { "business_type": { "id": "services", "name": "Services" }, "businesses": 796, "gross_revenue": { "amount": "5841223.30", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "industry_type": { "id": "marketing_agency", "name": "Marketing Agency" } } ], "window": { "as_of": null, "from": "2026-09-23T04:00:00Z", "key": "prev:7d", "kind": "range", "time_zone": "Etc/UTC", "to": "2026-09-30T04:00:00Z" } } ] }, "page_info": { "end_cursor": "MQ", "has_next_page": true, "has_previous_page": false, "start_cursor": "MQ" } }, "properties": { "data": { "properties": { "breakdown_by": { "description": "What each row is, or `null` for one total row per window.", "example": "industry_type", "nullable": true, "type": "string" }, "columns": { "description": "The breakdown first, then each requested property and metric, in row order.", "items": { "properties": { "aggregate": { "description": "Metrics only. How to combine the metric across rows.", "enum": [ "sum", "average", "none" ], "example": "sum", "type": "string" }, "key": { "description": "The column's key on each row.", "example": "industry_type", "type": "string" }, "name": { "description": "The column's display name.", "example": "Industry type", "type": "string" }, "type": { "description": "An attribute of the row, or a number measured over it.", "enum": [ "property", "metric" ], "example": "property", "type": "string" }, "unit": { "description": "Metrics only. Sets the value's JSON type.", "enum": [ "money", "count", "rate", "months", "years" ], "example": "money", "type": "string" }, "weight": { "description": "Metrics only. The column an `average` metric is weighted by.", "example": null, "nullable": true, "type": "string" } }, "required": [ "key", "name", "type" ], "type": "object" }, "type": "array" }, "data_as_of": { "description": "When the data was read, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "report": { "description": "The report's key.", "example": "platform_trends", "type": "string" }, "reports": { "description": "One entry per requested window, in request order. Rows line up by index across entries.", "items": { "properties": { "rows": { "description": "The page of rows. Only the requested columns are present. Every breakdown value with a sale is listed, down to a single business.", "items": { "properties": { "account_country": { "nullable": true, "properties": { "id": { "description": "The value's id, such as `options_trading`.", "example": "education", "type": "string" }, "name": { "description": "The value's display name.", "example": "Education", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "aov": { "description": "Gross revenue per payment.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "avg_business_age": { "description": "Average age in months of the businesses that sold.", "nullable": true, "type": "number" }, "avg_customer_age": { "description": "Average age in years of the paying customers.", "nullable": true, "type": "number" }, "avg_owner_age": { "description": "Average age in years of those businesses' owners.", "nullable": true, "type": "number" }, "business_type": { "nullable": true, "properties": { "id": { "description": "The value's id, such as `options_trading`.", "example": "education", "type": "string" }, "name": { "description": "The value's display name.", "example": "Education", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "businesses": { "description": "Businesses with a paid payment.", "example": 3, "nullable": true, "type": "integer" }, "customer_country": { "nullable": true, "properties": { "id": { "description": "The value's id, such as `options_trading`.", "example": "education", "type": "string" }, "name": { "description": "The value's display name.", "example": "Education", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "customers": { "description": "Distinct paying customers. A customer who pays in two groups counts in both.", "nullable": true, "type": "integer" }, "gross_revenue": { "description": "Paid sales, before refunds and fees, measured the way an account's gross revenue is.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "industry_type": { "nullable": true, "properties": { "id": { "description": "The value's id, such as `options_trading`.", "example": "education", "type": "string" }, "name": { "description": "The value's display name.", "example": "Education", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "median_gross_revenue": { "description": "The median paid volume per business that sold.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "new_businesses": { "description": "Businesses created in the window that also sold in it.", "nullable": true, "type": "integer" }, "payments": { "description": "Paid payments.", "nullable": true, "type": "integer" }, "product_category": { "nullable": true, "properties": { "id": { "description": "The value's id, such as `options_trading`.", "example": "education", "type": "string" }, "name": { "description": "The value's display name.", "example": "Education", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "products": { "description": "Products with a paid payment.", "nullable": true, "type": "integer" }, "repeat_rate": { "description": "Share of customers who paid more than once, as a fraction.", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" }, "window": { "properties": { "as_of": { "description": "Always `null` for a range window.", "example": null, "nullable": true, "type": "string" }, "from": { "description": "Start of the data that answered the window, as an ISO 8601 timestamp. `null` for `all_time`.", "example": "2026-01-01T12:00:00.000Z", "nullable": true, "type": "string" }, "key": { "description": "The window as requested, such as `30d` or `prev:7d`.", "example": "prev:7d", "type": "string" }, "kind": { "description": "Always `range` for this report.", "enum": [ "range" ], "example": "range", "type": "string" }, "time_zone": { "description": "The zone the window's boundaries fall in.", "example": "Etc/UTC", "type": "string" }, "to": { "description": "End of the data that answered the window, exclusive, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "nullable": true, "type": "string" } }, "required": [ "key", "kind", "from", "to", "as_of", "time_zone" ], "type": "object" } }, "required": [ "window", "rows" ], "type": "object" }, "type": "array" } }, "required": [ "report", "breakdown_by", "columns", "reports", "data_as_of" ], "type": "object" }, "page_info": { "properties": { "end_cursor": { "description": "Pass as `after` for the next page.", "example": null, "nullable": true, "type": "string" }, "has_next_page": { "description": "Whether more rows follow this page.", "example": false, "type": "boolean" }, "has_previous_page": { "description": "Whether rows precede this page.", "example": false, "type": "boolean" }, "start_cursor": { "description": "The cursor of the first row on this page.", "example": "MQ", "nullable": true, "type": "string" } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Platform trends for each requested window, with rows in the same order in every window." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "The request parameters are invalid." } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve Platform Trends", "tags": [ "Stats" ], "x-whop-docs-subgroup": "Reports" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/stats/time_series": { "get": { "description": "Lists the metrics you can chart over time, with the unit each reports and the properties you can filter or break it down by. Aggregates that are not bucketed over time are reports, listed at `GET /stats/reports`.", "operationId": "listTimeSeriesMetrics", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "The available metrics.", "items": { "properties": { "breakdowns": { "description": "Supported breakdown_by values when they differ from the filter properties.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "A short description of what the metric measures.", "example": "Ad platform delivery over time (spend, impressions, clicks) on the unified source language: source scopes by a whop::: path, exact or with a trailing :* prefix (whop alone or no source = the whole account), and group_by=source groups one path segment deeper than the filter prefix. Only whop:* paths report delivery today; other roots return nothing. breakdown_by=metric returns each delivery measure per bucket plus whole-window data.totals. breakdown_by can instead split delivery by a dimension — age, gender, age_gender, placement, publisher_platform, country, region, device_platform, or impression_device — with the metric parameter picking the measure (spend, impressions, or clicks; defaults to spend). On the placement and publisher_platform dimensions the metric parameter also accepts results, roas, and cost_per_result: conversion-side measures attributed from your own tracked events rather than reported by the ad platform, with results counting conversions that match each ad group's conversion event. Dimension entries don't sum exactly to the totals (the ad platform withholds tiny cells) and are grouped by the ad account's calendar day — they can't re-bucket into time_zone. Spend converts to convert_to (defaults to usd). Whole-account attribution numbers live in the events and people metrics.", "type": "string" }, "key": { "description": "The metric's key. Pass it to GET /stats/time_series/{metric} to query its values.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "Human-readable display name for the metric.", "example": "Ad delivery", "type": "string" }, "properties": { "description": "The properties you can use with this metric — pass one as a filter (property=value) to narrow the series, or as breakdown_by=property to split it.", "items": { "example": "source", "type": "string" }, "type": "array" }, "unit": { "description": "How to read the metric's values: count is an integer, currency is a decimal amount, and percent is a number where 1.6 means 1.6%.", "enum": [ "count", "currency", "percent" ], "example": "currency", "type": "string" }, "windows": { "description": "Snapshot metrics only: the trailing windows you can pass as snapshot_window, for example 30d. Absent on live metrics, which use from/to instead.", "items": { "example": "7d", "type": "string" }, "type": "array" } }, "required": [ "key", "name", "unit", "properties", "description" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "metric catalog" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Time Series Metrics", "tags": [ "Stats" ], "x-whop-docs-subgroup": "Time Series" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/stats/time_series/{metric}": { "get": { "description": "Retrieves a metric as a series of points over a time range for an account or user. For an aggregate that is not bucketed over time, use a report from `GET /stats/reports`. The `market_prices` metric is public and requires no authentication.", "operationId": "retrieveMetricTimeSeries", "parameters": [ { "description": "Account this query concerns, prefixed `biz_`, or `platform` for all of Whop.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The user this query concerns, for example user_AbC123. Available on metrics that support user subjects, such as account_balance.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Start of the range — a date (YYYY-MM-DD), expanded to the start of that day, or an ISO 8601 timestamp (for example 2026-07-16T16:37:00Z), used exactly.", "in": "query", "name": "from", "required": true, "schema": { "type": "string" } }, { "description": "End of the range — a date (YYYY-MM-DD), expanded to the end of that day, or an ISO 8601 timestamp (for example 2026-07-17T16:37:00Z), used exactly. Funnel entry ranges cannot exceed 90 days.", "in": "query", "name": "to", "required": true, "schema": { "type": "string" } }, { "description": "How wide each point is. Defaults to day. Snapshot metrics are day-only. Funnels support at most 2,000 first-entry cohort buckets.", "in": "query", "name": "interval", "required": false, "schema": { "enum": [ "minute", "five_minutes", "thirty_minutes", "hour", "day", "week", "month", "year" ], "type": "string" } }, { "description": "Split the metric out by one of its properties — each point gets a breakdown array. For example breakdown_by=currency returns an entry for usd, an entry for eur, and so on. Funnels use a property of the first matched event, with at most 300 groups. experiment_id and variant require an exposure as step 1. For funnel source breakdowns, steps[1][source]=whop:* groups by campaign, whop::* by ad group, and whop:::* by ad. See the metric catalog for supported breakdowns.", "in": "query", "name": "breakdown_by", "required": false, "schema": { "type": "string" } }, { "description": "Display currency for money metrics — every amount is converted into this ISO currency using the exchange rate on each period's date. Defaults to usd. For the ads metrics (ad_spend, ad_delivery), pass the account's ads reporting currency to match the ad entity endpoints. On transaction metrics, it is ignored when you filter or break down by currency (those report the original transaction currency, unconverted).", "in": "query", "name": "convert_to", "required": false, "schema": { "type": "string" } }, { "description": "Select the source currency or asset on metrics that list currency. For transaction metrics, for example currency=eur, values are reported without conversion. For market_prices, use btc or xaut and convert_to=usd. Pair with breakdown_by=currency to split a metric by currency.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "IANA time zone to bucket the series in, for example America/New_York. Defaults to UTC. Not accepted by snapshot metrics, which are UTC only.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single payment method, for example card or crypto. Available on metrics that list payment_method.", "in": "query", "name": "payment_method", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single card brand, for example visa. A refinement of payment_method=card. Available on metrics that list card_network.", "in": "query", "name": "card_network", "required": false, "schema": { "type": "string" } }, { "description": "Filter disputes to a normalized reason, for example product_not_received. Pair with breakdown_by=dispute_reason to split dispute counts by reason.", "in": "query", "name": "dispute_reason", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single GMV source, for example payments — or, on the traffic metrics, a visit source (whop_ads, direct, or a utm_source value). Pair with breakdown_by=source to split by source. Available on metrics that list source.", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one website hostname, for example shop.example.com. On the events and people metrics, comma-separated hostnames match any listed hostname. Pair with breakdown_by=hostname to split by website.", "in": "query", "name": "hostname", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one page — a hostname plus normalized path, for example shop.example.com/pricing. Pair with breakdown_by=page to split by page.", "in": "query", "name": "page", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one device type: desktop, mobile, tablet, or unknown. Pair with breakdown_by=device_type to split by device.", "in": "query", "name": "device_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one visitor country (uppercase ISO 3166-1 alpha-2, for example US). Pair with breakdown_by=country_code to split by country.", "in": "query", "name": "country_code", "required": false, "schema": { "type": "string" } }, { "description": "Filter the events metric to one tracked event name, for example pixel.page or pixel.custom. Pair with breakdown_by=event_name to split by event.", "in": "query", "name": "event_name", "required": false, "schema": { "type": "string" } }, { "description": "Filter the events metric to a canonical group of events: page_view (pixel page views plus whop.com store views), checkout_start (hosted and embedded checkout views), or other. Pair with breakdown_by=event_type to split by group.", "in": "query", "name": "event_type", "required": false, "schema": { "enum": [ "page_view", "checkout_start", "other" ], "type": "string" } }, { "description": "Filter the events metric to one merchant-defined custom event name. Only valid alongside event_name=pixel.custom. Pair with breakdown_by=custom_name to split custom events by name.", "in": "query", "name": "custom_name", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single wallet-balance segment, for example available. Pair with breakdown_by=segment to split the balance. Available on metrics that list segment.", "in": "query", "name": "segment", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single balance-activity category, for example payments. Pair with breakdown_by=category to split the activity. Available on metrics that list category.", "in": "query", "name": "category", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single cashback merchant bucket, for example whop-ads. Pair with breakdown_by=merchant to split cashback by merchant. Available on metrics that list merchant.", "in": "query", "name": "merchant", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single fee type. Pair with breakdown_by=fee_type to split fees by type. Available on metrics that list fee_type.", "in": "query", "name": "fee_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single product (access pass id), for example prod_AbC123. Pair with breakdown_by=product. Available on metrics that list product.", "in": "query", "name": "product", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single membership status. Pair with breakdown_by=status. Available on metrics that list status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single access level. Pair with breakdown_by=access_level. Available on metrics that list access_level.", "in": "query", "name": "access_level", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single most-recent member action. Pair with breakdown_by=most_recent_action. Available on metrics that list most_recent_action.", "in": "query", "name": "most_recent_action", "required": false, "schema": { "type": "string" } }, { "description": "Filter a referral metric to the businesses attributed to one person you referred, for example user_AbC123. Available on metrics that list referred_user_id.", "in": "query", "name": "referred_user_id", "required": false, "schema": { "type": "string" } }, { "description": "Ad campaign ids (adcamp_...) to scope the report to; stats are summed across them. Available on metrics that list ad_campaign_ids.", "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "items": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Ad group ids (adgrp_...) to scope the report to; stats are summed across them. Available on metrics that list ad_group_ids.", "in": "query", "name": "ad_group_ids", "required": false, "schema": { "items": { "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Ad ids (ad_...) to scope the report to; stats are summed across them. Available on metrics that list ad_ids.", "in": "query", "name": "ad_ids", "required": false, "schema": { "items": { "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Window used by a snapshot metric. Ordinary snapshots accept 30d as their trailing activity window. Cohorted dispute metrics accept 7d or 28d as the sales-transaction pool; their attribution window is fixed in the metric name. Card network program metrics accept 7d, 14d, 28d, or 56d. Each metric lists its accepted values in the catalog.", "in": "query", "name": "snapshot_window", "required": false, "schema": { "enum": [ "7d", "14d", "28d", "30d", "56d" ], "type": "string" } }, { "description": "Filter the events metric to one or more full event names, for example payment.completed or pixel.lead. Comma-separated names match any listed event. Use group_by=event for separate groups. Available on metrics that list event.", "in": "query", "name": "event", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one business type, for example `education`. Pair with `breakdown_by=business_type` to split by business type. Available on metrics that list `business_type`.", "in": "query", "name": "business_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one industry type, for example `options_trading`. Pair with `breakdown_by=industry_type` to split by industry type. Available on metrics that list `industry_type`.", "in": "query", "name": "industry_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one product category, for example `algo_trading_course`. Pair with `breakdown_by=product_category` to split by product category. Available on metrics that list `product_category`.", "in": "query", "name": "product_category", "required": false, "schema": { "type": "string" } }, { "description": "Filter to accounts located in one country, as an ISO 3166-1 alpha-2 code such as `US`. Pair with `breakdown_by=account_country` to split by account country. Available on metrics that list `account_country`.", "in": "query", "name": "account_country", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one card-issuing bank, named as the processor reports it, for example JPMORGAN CHASE BANK N A, or unknown for payments with no reported bank. Available on metrics that list issuer.", "in": "query", "name": "issuer", "required": false, "schema": { "type": "string" } }, { "description": "Funnel only. Time allowed from the first event to the final event: integer minutes, hours, or days, up to 30d.", "in": "query", "name": "conversion_window", "required": false, "schema": { "default": "7d", "pattern": "^[1-9][0-9]*[mhd]$", "type": "string" } }, { "description": "Funnel only. Include only entrants whose full conversion window has elapsed. Required for confidence intervals and comparisons.", "in": "query", "name": "mature_only", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Funnel only. Required when metric=funnel. 2 to 10 ordered events per person, as consecutive one-based bracket parameters such as `steps[1][event]=pixel.page&steps[1][page]=/pricing*&steps[2][event]=payment.completed`. Values are scalar strings, never JSON. A person's first step 1 match inside `from`/`to` anchors their cohort, breakdown, and conversion window; later matches do not restart it. Other events may occur between steps, and conversions may land after `to`. For an experiment funnel, make `experiment.exposure` step 1 and pass `breakdown_by=variant`.", "explode": true, "in": "query", "name": "steps", "required": false, "schema": { "additionalProperties": false, "properties": { "1": { "$ref": "#/components/schemas/FunnelStep" }, "10": { "$ref": "#/components/schemas/FunnelStep" }, "2": { "$ref": "#/components/schemas/FunnelStep" }, "3": { "$ref": "#/components/schemas/FunnelStep" }, "4": { "$ref": "#/components/schemas/FunnelStep" }, "5": { "$ref": "#/components/schemas/FunnelStep" }, "6": { "$ref": "#/components/schemas/FunnelStep" }, "7": { "$ref": "#/components/schemas/FunnelStep" }, "8": { "$ref": "#/components/schemas/FunnelStep" }, "9": { "$ref": "#/components/schemas/FunnelStep" } }, "required": [ "1", "2" ], "type": "object" }, "style": "deepObject" }, { "description": "Funnel only. The breakdown value to use as baseline for whole-window final conversion. Requires breakdown_by and mature_only=true; defaults confidence_level to 0.95.", "in": "query", "name": "compare_to", "required": false, "schema": { "type": "string" } }, { "description": "Funnel only. Confidence level for whole-window final conversion intervals, for example 0.95. Requires mature_only=true. Exposure steps must each filter one user-randomized experiment.", "in": "query", "name": "confidence_level", "required": false, "schema": { "exclusiveMaximum": 1, "exclusiveMinimum": 0, "type": "number" } }, { "description": "People metric only: contactable equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "contactable", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: has_purchased equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "has_purchased", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: first_seen_at greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "first_seen_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "People metric only: first_seen_at less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "first_seen_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "People metric only: last_seen_at greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "last_seen_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "People metric only: last_seen_at less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "last_seen_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "People metric only: first_seen_at within this many days of now. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "first_seen_within_days", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "People metric only: last_seen_at within this many days of now. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "last_seen_within_days", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "People metric only: known equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "known", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: has_email equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "has_email", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: has_phone equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "has_phone", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: ltv greater than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "ltv_gt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: ltv greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "ltv_gte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: ltv less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "ltv_lt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: ltv less than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "ltv_lte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: aov greater than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "aov_gt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: aov greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "aov_gte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: aov less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "aov_lt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: aov less than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "aov_lte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: purchase_count greater than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "purchase_count_gt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: purchase_count greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "purchase_count_gte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: purchase_count less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "purchase_count_lt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: purchase_count less than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "purchase_count_lte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: event_count greater than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "event_count_gt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: event_count greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "event_count_gte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: event_count less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "event_count_lt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: event_count less than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "event_count_lte", "required": false, "schema": { "type": "number" } }, { "description": "Read a referral metric for a business instead of the caller: the referrals its team members made, past members included, for example biz_AbC123. Requires company:basic:read on that business and cannot be combined with user_id. Available on metrics that list referring_account_id.", "in": "query", "name": "referring_account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "currency": { "description": "ISO currency the values are denominated in. Present for currency-unit metrics: the convert_to currency, or usd.", "example": "usd", "nullable": true, "type": "string" }, "points": { "description": "One entry per period, oldest first.", "items": { "properties": { "breakdown": { "description": "Present only when broken down: one entry per property value in this period.", "items": { "properties": { "name": { "description": "The property value, for example usd or visa.", "example": "spend", "type": "string" }, "steps": { "description": "Present for the funnel metric. People reaching each step in order, starting with the entry step.", "items": { "$ref": "#/components/schemas/FunnelStepResult" }, "type": "array" }, "value": { "description": "The metric's value for this entry.", "example": 2.82, "nullable": true, "type": "number" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "steps": { "description": "Present for the funnel metric. People reaching each step in order, starting with the entry step.", "items": { "$ref": "#/components/schemas/FunnelStepResult" }, "type": "array" }, "timestamp": { "description": "Unix timestamp (seconds) of the period start.", "example": 1767268800, "type": "integer" }, "value": { "description": "The metric's value for this period, in the metric's unit. For `funnel`, the final-step conversion percentage.", "example": 3, "nullable": true, "type": "number" } }, "required": [ "timestamp", "value" ], "type": "object" }, "type": "array" }, "totals": { "description": "Whole-window aggregates, present when the metric computes them. Don't derive these from `points`: a rate is measured across the whole window, not averaged across its points, and whole-window unique people are distinct across every bucket.", "items": { "properties": { "comparison": { "$ref": "#/components/schemas/FunnelComparison" }, "confidence_interval": { "$ref": "#/components/schemas/FunnelConfidenceInterval", "description": "Funnel only. The Wilson interval for final conversion, present when confidence_level or compare_to is supplied." }, "name": { "description": "The property value this total is for, or the metric's name when it isn't split by a property.", "example": "wins", "type": "string" }, "steps": { "description": "Present for the funnel metric. People reaching each step in order, starting with the entry step.", "items": { "$ref": "#/components/schemas/FunnelStepResult" }, "type": "array" }, "value": { "description": "The metric's whole-window value for this entry.", "example": 4, "nullable": true, "type": "number" } }, "required": [ "name", "value" ], "type": "object" }, "nullable": true, "type": "array" } }, "required": [ "points" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "a user-scoped metric via a scoped OAuth token" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "subject tag type mismatch" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication for an account-scoped metric" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "a user-scoped metric with a credential that cannot act as a user" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account" } }, "security": [ { "bearerAuth": [ "stats:read" ] }, { "bearerAuth": [ "ad_campaign:read" ] } ], "summary": "Retrieve Metric Time Series", "tags": [ "Stats" ], "x-whop-docs-subgroup": "Time Series" }, "parameters": [ { "description": "The metric to retrieve, for example net_revenue. Use GET /stats/time_series to see every metric key. The metric sets the unit and the properties you can filter or break down by.", "in": "path", "name": "metric", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/stats/{metric}": { "get": { "deprecated": true, "description": "Deprecated compatibility endpoint. Retrieve a metric's time series with `GET /stats/time_series/{metric}` instead.", "operationId": "retrieveMetric", "parameters": [ { "description": "Account this query concerns, prefixed `biz_`, or `platform` for all of Whop.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The user this query concerns, for example user_AbC123. Available on metrics that support user subjects, such as account_balance.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Start of the range — a date (YYYY-MM-DD), expanded to the start of that day, or an ISO 8601 timestamp (for example 2026-07-16T16:37:00Z), used exactly.", "in": "query", "name": "from", "required": true, "schema": { "type": "string" } }, { "description": "End of the range — a date (YYYY-MM-DD), expanded to the end of that day, or an ISO 8601 timestamp (for example 2026-07-17T16:37:00Z), used exactly. Funnel entry ranges cannot exceed 90 days.", "in": "query", "name": "to", "required": true, "schema": { "type": "string" } }, { "description": "How wide each point is. Defaults to day. Snapshot metrics are day-only. Funnels support at most 2,000 first-entry cohort buckets.", "in": "query", "name": "interval", "required": false, "schema": { "enum": [ "minute", "five_minutes", "thirty_minutes", "hour", "day", "week", "month", "year" ], "type": "string" } }, { "description": "Split the metric out by one of its properties — each point gets a breakdown array. For example breakdown_by=currency returns an entry for usd, an entry for eur, and so on. Funnels use a property of the first matched event, with at most 300 groups. experiment_id and variant require an exposure as step 1. For funnel source breakdowns, steps[1][source]=whop:* groups by campaign, whop::* by ad group, and whop:::* by ad. See the metric catalog for supported breakdowns.", "in": "query", "name": "breakdown_by", "required": false, "schema": { "type": "string" } }, { "description": "Display currency for money metrics — every amount is converted into this ISO currency using the exchange rate on each period's date. Defaults to usd. For the ads metrics (ad_spend, ad_delivery), pass the account's ads reporting currency to match the ad entity endpoints. On transaction metrics, it is ignored when you filter or break down by currency (those report the original transaction currency, unconverted).", "in": "query", "name": "convert_to", "required": false, "schema": { "type": "string" } }, { "description": "Select the source currency or asset on metrics that list currency. For transaction metrics, for example currency=eur, values are reported without conversion. For market_prices, use btc or xaut and convert_to=usd. Pair with breakdown_by=currency to split a metric by currency.", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "IANA time zone to bucket the series in, for example America/New_York. Defaults to UTC. Not accepted by snapshot metrics, which are UTC only.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single payment method, for example card or crypto. Available on metrics that list payment_method.", "in": "query", "name": "payment_method", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single card brand, for example visa. A refinement of payment_method=card. Available on metrics that list card_network.", "in": "query", "name": "card_network", "required": false, "schema": { "type": "string" } }, { "description": "Filter disputes to a normalized reason, for example product_not_received. Pair with breakdown_by=dispute_reason to split dispute counts by reason.", "in": "query", "name": "dispute_reason", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single GMV source, for example payments — or, on the traffic metrics, a visit source (whop_ads, direct, or a utm_source value). Pair with breakdown_by=source to split by source. Available on metrics that list source.", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one website hostname, for example shop.example.com. On the events and people metrics, comma-separated hostnames match any listed hostname. Pair with breakdown_by=hostname to split by website.", "in": "query", "name": "hostname", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one page — a hostname plus normalized path, for example shop.example.com/pricing. Pair with breakdown_by=page to split by page.", "in": "query", "name": "page", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one device type: desktop, mobile, tablet, or unknown. Pair with breakdown_by=device_type to split by device.", "in": "query", "name": "device_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter traffic metrics to one visitor country (uppercase ISO 3166-1 alpha-2, for example US). Pair with breakdown_by=country_code to split by country.", "in": "query", "name": "country_code", "required": false, "schema": { "type": "string" } }, { "description": "Filter the events metric to one tracked event name, for example pixel.page or pixel.custom. Pair with breakdown_by=event_name to split by event.", "in": "query", "name": "event_name", "required": false, "schema": { "type": "string" } }, { "description": "Filter the events metric to a canonical group of events: page_view (pixel page views plus whop.com store views), checkout_start (hosted and embedded checkout views), or other. Pair with breakdown_by=event_type to split by group.", "in": "query", "name": "event_type", "required": false, "schema": { "enum": [ "page_view", "checkout_start", "other" ], "type": "string" } }, { "description": "Filter the events metric to one merchant-defined custom event name. Only valid alongside event_name=pixel.custom. Pair with breakdown_by=custom_name to split custom events by name.", "in": "query", "name": "custom_name", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single wallet-balance segment, for example available. Pair with breakdown_by=segment to split the balance. Available on metrics that list segment.", "in": "query", "name": "segment", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single balance-activity category, for example payments. Pair with breakdown_by=category to split the activity. Available on metrics that list category.", "in": "query", "name": "category", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single cashback merchant bucket, for example whop-ads. Pair with breakdown_by=merchant to split cashback by merchant. Available on metrics that list merchant.", "in": "query", "name": "merchant", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single fee type. Pair with breakdown_by=fee_type to split fees by type. Available on metrics that list fee_type.", "in": "query", "name": "fee_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single product (access pass id), for example prod_AbC123. Pair with breakdown_by=product. Available on metrics that list product.", "in": "query", "name": "product", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single membership status. Pair with breakdown_by=status. Available on metrics that list status.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single access level. Pair with breakdown_by=access_level. Available on metrics that list access_level.", "in": "query", "name": "access_level", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single most-recent member action. Pair with breakdown_by=most_recent_action. Available on metrics that list most_recent_action.", "in": "query", "name": "most_recent_action", "required": false, "schema": { "type": "string" } }, { "description": "Filter a referral metric to the businesses attributed to one person you referred, for example user_AbC123. Available on metrics that list referred_user_id.", "in": "query", "name": "referred_user_id", "required": false, "schema": { "type": "string" } }, { "description": "Ad campaign ids (adcamp_...) to scope the report to; stats are summed across them. Available on metrics that list ad_campaign_ids.", "in": "query", "name": "ad_campaign_ids", "required": false, "schema": { "items": { "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Ad group ids (adgrp_...) to scope the report to; stats are summed across them. Available on metrics that list ad_group_ids.", "in": "query", "name": "ad_group_ids", "required": false, "schema": { "items": { "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Ad ids (ad_...) to scope the report to; stats are summed across them. Available on metrics that list ad_ids.", "in": "query", "name": "ad_ids", "required": false, "schema": { "items": { "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Window used by a snapshot metric. Ordinary snapshots accept 30d as their trailing activity window. Cohorted dispute metrics accept 7d or 28d as the sales-transaction pool; their attribution window is fixed in the metric name. Card network program metrics accept 7d, 14d, 28d, or 56d. Each metric lists its accepted values in the catalog.", "in": "query", "name": "snapshot_window", "required": false, "schema": { "enum": [ "7d", "14d", "28d", "30d", "56d" ], "type": "string" } }, { "description": "Filter the events metric to one or more full event names, for example payment.completed or pixel.lead. Comma-separated names match any listed event. Use group_by=event for separate groups. Available on metrics that list event.", "in": "query", "name": "event", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one business type, for example `education`. Pair with `breakdown_by=business_type` to split by business type. Available on metrics that list `business_type`.", "in": "query", "name": "business_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one industry type, for example `options_trading`. Pair with `breakdown_by=industry_type` to split by industry type. Available on metrics that list `industry_type`.", "in": "query", "name": "industry_type", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one product category, for example `algo_trading_course`. Pair with `breakdown_by=product_category` to split by product category. Available on metrics that list `product_category`.", "in": "query", "name": "product_category", "required": false, "schema": { "type": "string" } }, { "description": "Filter to accounts located in one country, as an ISO 3166-1 alpha-2 code such as `US`. Pair with `breakdown_by=account_country` to split by account country. Available on metrics that list `account_country`.", "in": "query", "name": "account_country", "required": false, "schema": { "type": "string" } }, { "description": "Filter to one card-issuing bank, named as the processor reports it, for example JPMORGAN CHASE BANK N A, or unknown for payments with no reported bank. Available on metrics that list issuer.", "in": "query", "name": "issuer", "required": false, "schema": { "type": "string" } }, { "description": "Funnel only. Time allowed from the first event to the final event: integer minutes, hours, or days, up to 30d.", "in": "query", "name": "conversion_window", "required": false, "schema": { "default": "7d", "pattern": "^[1-9][0-9]*[mhd]$", "type": "string" } }, { "description": "Funnel only. Include only entrants whose full conversion window has elapsed. Required for confidence intervals and comparisons.", "in": "query", "name": "mature_only", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Funnel only. Required when metric=funnel. 2 to 10 ordered events per person, as consecutive one-based bracket parameters such as `steps[1][event]=pixel.page&steps[1][page]=/pricing*&steps[2][event]=payment.completed`. Values are scalar strings, never JSON. A person's first step 1 match inside `from`/`to` anchors their cohort, breakdown, and conversion window; later matches do not restart it. Other events may occur between steps, and conversions may land after `to`. For an experiment funnel, make `experiment.exposure` step 1 and pass `breakdown_by=variant`.", "explode": true, "in": "query", "name": "steps", "required": false, "schema": { "additionalProperties": false, "properties": { "1": { "$ref": "#/components/schemas/FunnelStep" }, "10": { "$ref": "#/components/schemas/FunnelStep" }, "2": { "$ref": "#/components/schemas/FunnelStep" }, "3": { "$ref": "#/components/schemas/FunnelStep" }, "4": { "$ref": "#/components/schemas/FunnelStep" }, "5": { "$ref": "#/components/schemas/FunnelStep" }, "6": { "$ref": "#/components/schemas/FunnelStep" }, "7": { "$ref": "#/components/schemas/FunnelStep" }, "8": { "$ref": "#/components/schemas/FunnelStep" }, "9": { "$ref": "#/components/schemas/FunnelStep" } }, "required": [ "1", "2" ], "type": "object" }, "style": "deepObject" }, { "description": "Funnel only. The breakdown value to use as baseline for whole-window final conversion. Requires breakdown_by and mature_only=true; defaults confidence_level to 0.95.", "in": "query", "name": "compare_to", "required": false, "schema": { "type": "string" } }, { "description": "Funnel only. Confidence level for whole-window final conversion intervals, for example 0.95. Requires mature_only=true. Exposure steps must each filter one user-randomized experiment.", "in": "query", "name": "confidence_level", "required": false, "schema": { "exclusiveMaximum": 1, "exclusiveMinimum": 0, "type": "number" } }, { "description": "People metric only: contactable equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "contactable", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: has_purchased equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "has_purchased", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: first_seen_at greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "first_seen_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "People metric only: first_seen_at less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "first_seen_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "People metric only: last_seen_at greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "last_seen_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "People metric only: last_seen_at less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "last_seen_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "People metric only: first_seen_at within this many days of now. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "first_seen_within_days", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "People metric only: last_seen_at within this many days of now. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "last_seen_within_days", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "People metric only: known equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "known", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: has_email equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "has_email", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: has_phone equals this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "has_phone", "required": false, "schema": { "type": "boolean" } }, { "description": "People metric only: ltv greater than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "ltv_gt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: ltv greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "ltv_gte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: ltv less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "ltv_lt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: ltv less than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "ltv_lte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: aov greater than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "aov_gt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: aov greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "aov_gte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: aov less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "aov_lt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: aov less than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "aov_lte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: purchase_count greater than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "purchase_count_gt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: purchase_count greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "purchase_count_gte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: purchase_count less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "purchase_count_lt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: purchase_count less than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "purchase_count_lte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: event_count greater than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "event_count_gt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: event_count greater than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "event_count_gte", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: event_count less than this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "event_count_lt", "required": false, "schema": { "type": "number" } }, { "description": "People metric only: event_count less than or equal this value. Applies to the current person profile for every time bucket. LTV and AOV are in USD. Not accepted by the Events metric.", "in": "query", "name": "event_count_lte", "required": false, "schema": { "type": "number" } }, { "description": "Read a referral metric for a business instead of the caller: the referrals its team members made, past members included, for example biz_AbC123. Requires company:basic:read on that business and cannot be combined with user_id. Available on metrics that list referring_account_id.", "in": "query", "name": "referring_account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "currency": { "description": "ISO currency the values are denominated in. Present for currency-unit metrics: the convert_to currency, or usd.", "example": "usd", "nullable": true, "type": "string" }, "points": { "description": "One entry per period, oldest first.", "items": { "properties": { "breakdown": { "description": "Present only when broken down: one entry per property value in this period.", "items": { "properties": { "name": { "description": "The property value, for example usd or visa.", "example": "control", "type": "string" }, "steps": { "description": "Present for the funnel metric. People reaching each step in order, starting with the entry step.", "items": { "$ref": "#/components/schemas/FunnelStepResult" }, "type": "array" }, "value": { "description": "The metric's value for this entry.", "example": 10.0, "nullable": true, "type": "number" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "steps": { "description": "Present for the funnel metric. People reaching each step in order, starting with the entry step.", "items": { "$ref": "#/components/schemas/FunnelStepResult" }, "type": "array" }, "timestamp": { "description": "Unix timestamp (seconds) of the period start.", "example": 1767268800, "type": "integer" }, "value": { "description": "The metric's value for this period, in the metric's unit. For `funnel`, the final-step conversion percentage.", "example": 12.0, "nullable": true, "type": "number" } }, "required": [ "timestamp", "value" ], "type": "object" }, "type": "array" }, "totals": { "description": "Whole-window aggregates, present when the metric computes them. Don't derive these from `points`: a rate is measured across the whole window, not averaged across its points, and whole-window unique people are distinct across every bucket.", "items": { "properties": { "comparison": { "$ref": "#/components/schemas/FunnelComparison" }, "confidence_interval": { "$ref": "#/components/schemas/FunnelConfidenceInterval", "description": "Funnel only. The Wilson interval for final conversion, present when confidence_level or compare_to is supplied." }, "name": { "description": "The property value this total is for, or the metric's name when it isn't split by a property.", "example": "funnel", "type": "string" }, "steps": { "description": "Present for the funnel metric. People reaching each step in order, starting with the entry step.", "items": { "$ref": "#/components/schemas/FunnelStepResult" }, "type": "array" }, "value": { "description": "The metric's whole-window value for this entry.", "example": 12.0, "nullable": true, "type": "number" } }, "required": [ "name", "value" ], "type": "object" }, "nullable": true, "type": "array" } }, "required": [ "points" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "a metric's series served through the deprecated path" } }, "security": [ { "bearerAuth": [ "stats:read" ] } ], "summary": "Retrieve Metric", "tags": [ "Stats" ], "x-whop-deprecated-since": "2026-10-06", "x-whop-docs": "hidden", "x-whop-successor": "GET /stats/time_series/{metric}" }, "parameters": [ { "description": "The metric to retrieve, for example net_revenue.", "in": "path", "name": "metric", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/support_channels": { "get": { "description": "Lists support channels between an account's team and its customers, most recently active first by default. Pass `open=true` to find channels awaiting a support response.\n\nRequired permissions:\n - `support_chat:read`", "operationId": "listSupportChannel", "parameters": [ { "explode": true, "in": "query", "name": "after", "required": false, "schema": { "description": "Returns the elements in the list that come after the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "before", "required": false, "schema": { "description": "Returns the elements in the list that come before the specified cursor.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "first", "required": false, "schema": { "description": "Returns the first _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "last", "required": false, "schema": { "description": "Returns the last _n_ elements from the list.", "example": 42, "type": "integer" }, "style": "form" }, { "explode": true, "in": "query", "name": "view", "required": false, "schema": { "$ref": "#/components/schemas/SupportChannelView", "description": "Filter support channels by the authenticated user's role. Defaults to admin. When the caller is a company API key (no user), only admin-visible channels are returned." }, "style": "form" }, { "explode": true, "in": "query", "name": "open", "required": false, "schema": { "description": "Whether to filter by open or resolved support channels. Set to true to only return channels awaiting a response, or false for resolved channels.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "customer_user_id", "required": false, "schema": { "description": "Only return support channels opened by this customer.", "type": "string" }, "style": "form" }, { "explode": true, "in": "query", "name": "customer_user_ids", "required": false, "schema": { "description": "Only return support channels opened by any of these customers. Maximum 100 IDs per request.", "items": { "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"VXNlci0xMA==\"`) or integer (such as `4`) input value will be accepted as an ID.", "type": "string" }, "type": "array" }, "style": "form" }, { "explode": true, "in": "query", "name": "participated", "required": false, "schema": { "description": "Set to true to only return channels the authenticated user has joined as a participant. Requires a user.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "include_last_message", "required": false, "schema": { "description": "Set to true to return `last_message` and `unread` on each channel. Both are `null` otherwise, which keeps large lists fast.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "include_participated", "required": false, "schema": { "description": "Set to true to return `participated` on each channel. It is `null` otherwise, which keeps large lists fast.", "type": "boolean" }, "style": "form" }, { "explode": true, "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction", "description": "The sort direction for the results. Use 'asc' for oldest first or 'desc' for newest first." }, "style": "form" }, { "explode": true, "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/MessageChannelOrder", "description": "The field to sort the support channels by, such as creation date or last message time." }, "style": "form" }, { "explode": true, "in": "query", "name": "account_id", "required": false, "schema": { "description": "The unique identifier of the company to list support channels for. Includes channels of child companies. When omitted, returns support channels across all companies the user has access to.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The connection type for DmsFeed.", "properties": { "data": { "description": "A list of nodes.", "items": { "$ref": "#/components/schemas/SupportChannelListItem" }, "type": "array" }, "page_info": { "$ref": "#/components/schemas/PageInfo", "description": "Information to aid in pagination." } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "support_chat:read" ] } ], "summary": "List support channels", "tags": [ "Support channels" ], "x-group-title": "Engagement" }, "post": { "description": "Opens a support channel between an account's team and a customer. Returns the existing channel if that customer already has one.\n\nRequired permissions:\n - `support_chat:create`", "operationId": "createSupportChannel", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "description": "Parameters for CreateSupportChatForUser", "properties": { "account_id": { "description": "The unique identifier of the company to create the support channel in.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "custom_name": { "description": "Optional custom display name for the support channel.", "type": [ "string", "null" ] }, "notifications_enabled": { "description": "Whether Whop app notifications are enabled for this support channel. Webhooks still fire.", "type": [ "boolean", "null" ] }, "user_id": { "description": "The user ID (e.g. 'user_xxxxx') or username of the customer to open a support channel for.", "example": "user_xxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id", "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "support_chat:create" ] } ], "summary": "Create support channel", "tags": [ "Support channels" ], "x-group-title": "Engagement" } }, "/support_channels/{id}": { "get": { "description": "Retrieves the details of an existing support channel.\n\nRequired permissions:\n - `support_chat:read`", "operationId": "retrieveSupportChannel", "parameters": [ { "description": "The unique identifier of the support channel to retrieve.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportChannel" } } }, "description": "A successful response" }, "400": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "Missing required parameter: amount.", "param": "amount", "type": "invalid_request_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "example": { "error": { "message": "Invalid or missing API key", "type": "unauthorized" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": { "message": "You do not have permission to access this resource", "type": "forbidden" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "message": "Resource not found", "type": "not_found" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not found" }, "422": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Verification required" }, "429": { "content": { "application/json": { "example": { "error": null }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "example": { "error": { "message": "An unexpected error occurred", "type": "internal_server_error" } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json'", "type": [ "string", "null" ] }, "message": { "type": "string" }, "param": { "description": "The parameter that caused the error, if applicable", "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Internal server error" } }, "security": [ { "bearerAuth": [ "support_chat:read" ] } ], "summary": "Retrieve support channel", "tags": [ "Support channels" ], "x-group-title": "Engagement" } }, "/swaps": { "get": { "description": "Lists the completed or pending swaps for an account or user — currently only the most recent one.", "operationId": "listSwaps", "parameters": [ { "description": "Business account whose swaps to list, prefixed `biz_`. Provide this or `user_id`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The caller's own user ID, prefixed `user_`, to list swaps in their personal account. Provide this or `account_id`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Swaps returned for this account.", "items": { "properties": { "account_id": { "description": "Account that owns the swap: a business ID prefixed `biz_`, or the user ID for a personal account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "The from_token amount the swap was created to spend, as a decimal string. A swap created with `all` reports the wallet balance it read. Null for a fiat pair.", "example": "0.052341", "type": [ "string", "null" ] }, "error": { "description": "Latest error returned for a failed swap.", "example": "Swap reverted: quoted price moved beyond the slippage tolerance", "type": [ "string", "null" ] }, "id": { "description": "Swap ID.", "example": "vault-swap-cwal_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "swap" ], "example": "swap", "type": "string" }, "status": { "description": "Current swap status. `complete` and `failed` are terminal.", "enum": [ "queued", "working", "complete", "failed" ], "example": "working", "type": "string" }, "tx_hashes": { "description": "On-chain transaction hashes produced by the swap.", "items": { "example": "0xabc", "type": "string" }, "type": "array" }, "user_id": { "description": "User whose personal account owns the swap, prefixed `user_`. Null for a business account.", "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "id", "account_id", "user_id", "status", "tx_hashes", "amount" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "swaps listed" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the crypto-wallet scope" } }, "security": [ { "bearerAuth": [ "crypto_wallet:swap" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "List Swaps", "tags": [ "Swaps" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Swaps one token for another in an account or user's wallet, or converts between their fiat balances at the mid-market rate. Crypto swaps finish in the background — retrieve the swap to follow its status.", "operationId": "createSwap", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Business account that makes the swap, prefixed `biz_`. Provide this or `user_id`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "Source token amount. Required for a crypto pair: a decimal amount, or `all` to swap the whole from_token balance in the account's wallet, read from the chain when the swap is created (any token but USDT). An amount above that balance is rejected when the balance can be read. For fiat pairs: the amount of from_token to convert at the mid-market rate; omit (along with to_amount) to repay the full negative to_token balance instead.", "example": "100", "type": [ "string", "null" ] }, "from_chain": { "description": "Source chain name or chain ID. Defaults to the source token's chain when omitted.", "oneOf": [ { "example": "plasma", "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "from_token": { "description": "Source token contract address or ticker symbol, such as \"USDT\".", "example": "usd", "type": "string" }, "slippage_bps": { "description": "Maximum slippage tolerance in basis points.", "example": 50, "type": [ "integer", "null" ] }, "to_amount": { "description": "Fiat pairs only: sizes a partial repayment of the negative to_token balance, denominated in to_token. Must not exceed the debt. Mutually exclusive with amount.", "example": "180.00", "type": [ "string", "null" ] }, "to_chain": { "description": "Destination chain name or chain ID. Defaults to the destination token's chain when omitted.", "oneOf": [ { "example": "plasma", "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "to_token": { "description": "Destination token contract address or ticker symbol, such as \"XAUT\".", "example": "cad", "type": "string" }, "user_id": { "description": "The caller's own user ID, prefixed `user_`, to swap in their personal account. Provide this or `account_id`.", "type": "string" } }, "required": [ "from_token", "to_token" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account that owns the swap: a business ID prefixed `biz_`, or the user ID for a personal account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "Crypto pairs only: the from_token amount the swap spends, as a decimal string. A request for `all` returns the wallet balance it read.", "example": "100.0", "type": [ "string", "null" ] }, "amount_in": { "description": "Fiat pairs only: amount of the source currency converted. Null while a stablecoin repayment is processing.", "example": 131.4, "type": [ "number", "null" ] }, "amount_out": { "description": "Fiat pairs only: amount credited in the destination currency. Null while a stablecoin repayment is processing.", "example": 180.0, "type": [ "number", "null" ] }, "amount_out_expected": { "description": "Expected destination token amount.", "example": "98.9", "type": "string" }, "amount_out_min": { "description": "Minimum destination amount after slippage.", "example": "98.4", "type": "string" }, "from_token": { "description": "Fiat pairs only: the source currency.", "properties": { "symbol": { "example": "usd", "type": "string" } }, "type": [ "object", "null" ] }, "id": { "description": "Swap ID. Poll `GET /swaps/:id` for status.", "example": "vault-swap-cwal_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "swap" ], "example": "swap", "type": "string" }, "rate": { "description": "Quoted exchange rate used to create the swap.", "example": "0.989", "type": "string" }, "status": { "description": "Swap status. Crypto swaps start `queued`; fiat conversions return `complete`, or `working` while a stablecoin repayment settles.", "enum": [ "queued", "working", "complete", "failed" ], "example": "queued", "type": "string" }, "to_chain": { "description": "Destination chain for the swap.", "example": "ethereum", "type": "string" }, "to_token": { "description": "Fiat pairs only: the destination currency.", "properties": { "symbol": { "example": "cad", "type": "string" } }, "type": [ "object", "null" ] }, "user_id": { "description": "User whose personal account owns the swap, prefixed `user_`. Null for a business account.", "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "account_id", "user_id", "status" ], "type": "object" } } }, "description": "swap created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the crypto-wallet scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "crypto_wallet:swap" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] }, { "bearerAuth": [ "payout:transfer_funds" ] } ], "summary": "Create Swap", "tags": [ "Swaps" ] }, "x-whop-surface": "native" }, "/swaps/quote": { "post": { "description": "Previews the price of a swap before you create it. Fiat pairs quote the mid-market rate — the same rate creating the swap fills at. No funds move, nothing is saved, and no authentication is required.", "operationId": "createSwapQuote", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "Source token amount.", "example": "100", "type": "string" }, "from_address": { "description": "Source wallet address used for the quote.", "example": "0x6f1c0a3d5b2e4f8a9c7d1e0b3a5f7c9d2e4b6a80", "type": [ "string", "null" ] }, "from_chain": { "description": "Source chain name or chain ID. Defaults to the source token's chain when omitted.", "oneOf": [ { "example": "plasma", "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "from_token": { "description": "Source token contract address or ticker symbol, such as \"USDT\".", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Metadata to include with the quote response.", "example": { "external_id": "shop_4417" }, "type": "object" }, "slippage_bps": { "description": "Maximum slippage tolerance in basis points.", "example": 50, "type": [ "integer", "null" ] }, "to_address": { "description": "Destination wallet address used for the quote.", "example": "0x9d2e4b6a806f1c0a3d5b2e4f8a9c7d1e0b3a5f7c", "type": [ "string", "null" ] }, "to_chain": { "description": "Destination chain name or chain ID. Defaults to the destination token's chain when omitted.", "oneOf": [ { "example": "plasma", "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "to_token": { "description": "Destination token contract address or ticker symbol, such as \"XAUT\".", "example": "0x1b64b9025eebb9a6239575df9ea4b9ac46d4d193", "type": "string" } }, "required": [ "amount", "from_token", "to_token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount_in": { "description": "Source token amount used for the quote.", "example": "100", "type": "string" }, "amount_out": { "description": "Estimated destination token amount.", "example": "0.15", "type": "string" }, "amount_out_min": { "description": "Minimum destination amount after slippage.", "example": "0.148", "type": "string" }, "bridge_fee": { "description": "Estimated bridge fee for cross-chain swaps.", "example": "0.25", "type": [ "string", "null" ] }, "estimated_duration_seconds": { "description": "Estimated time for the swap to complete.", "example": 30, "type": [ "integer", "null" ] }, "fee_bps": { "description": "Whop fee in basis points.", "example": 100, "type": "integer" }, "from_address": { "description": "Source wallet address used for the quote.", "example": "0x6f1c0a3d5b2e4f8a9c7d1e0b3a5f7c9d2e4b6a80", "type": [ "string", "null" ] }, "from_token": { "additionalProperties": true, "description": "Resolved source token details.", "example": { "address": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "chain_id": 9745, "decimals": 6, "network": "plasma", "symbol": "USDT" }, "type": "object" }, "metadata": { "additionalProperties": true, "description": "Metadata from the request.", "example": { "external_id": "shop_4417" }, "type": "object" }, "object": { "enum": [ "swap_quote" ], "example": "swap_quote", "type": "string" }, "rate": { "description": "Quoted exchange rate.", "example": "1.5", "type": "string" }, "requires_token_approval": { "description": "Whether the source token needs approval before swapping.", "example": true, "type": [ "boolean", "null" ] }, "to_address": { "description": "Destination wallet address used for the quote.", "example": "0x9d2e4b6a806f1c0a3d5b2e4f8a9c7d1e0b3a5f7c", "type": [ "string", "null" ] }, "to_token": { "additionalProperties": true, "description": "Resolved destination token details.", "example": { "address": "0x1b64b9025eebb9a6239575df9ea4b9ac46d4d193", "chain_id": 9745, "decimals": 6, "network": "plasma", "symbol": "XAUT" }, "type": "object" } }, "required": [ "object", "amount_in", "amount_out", "rate", "fee_bps", "from_token", "to_token", "metadata" ], "type": "object" } } }, "description": "swap quote created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [], "summary": "Create Swap Quote", "tags": [ "Swaps" ] }, "x-whop-surface": "native" }, "/swaps/{id}": { "get": { "description": "Retrieves a swap and its status. Poll it after creating a crypto swap, which finishes in the background.", "operationId": "retrieveSwap", "parameters": [ { "description": "Swap ID returned from POST /swaps.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account that owns the swap: a business ID prefixed `biz_`, or the user ID for a personal account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "The from_token amount the swap was created to spend, as a decimal string. A swap created with `all` reports the wallet balance it read. Null for a fiat pair.", "example": "0.052341", "type": [ "string", "null" ] }, "error": { "description": "Latest error returned for a failed swap.", "example": "Swap reverted: quoted price moved beyond the slippage tolerance", "type": [ "string", "null" ] }, "id": { "description": "Swap ID.", "example": "vault-swap-cwal_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "swap" ], "example": "swap", "type": "string" }, "status": { "description": "Current swap status. `complete` and `failed` are terminal.", "enum": [ "queued", "working", "complete", "failed" ], "example": "failed", "type": "string" }, "tx_hashes": { "description": "On-chain transaction hashes produced by the swap.", "items": { "example": "0xabc", "type": "string" }, "type": "array" }, "user_id": { "description": "User whose personal account owns the swap, prefixed `user_`. Null for a business account.", "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "id", "account_id", "user_id", "status", "tx_hashes", "amount" ], "type": "object" } } }, "description": "swap status retrieved" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "swap id is invalid" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the crypto-wallet scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "swap does not exist" } }, "security": [ { "bearerAuth": [ "crypto_wallet:swap" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "Retrieve Swap", "tags": [ "Swaps" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/team_members": { "get": { "description": "Lists an account's team members, including pending invites. A user credential with `company:basic:read` may list only its own joined membership by passing its own `user_id` and `status=joined`. Listing `role=workforce` is also allowed with the `bounty:create` scope. Members with the view-only Partner role are listed after all other members.", "operationId": "listTeamMembers", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } }, { "description": "Only return members with this status: `joined` (accepted members) or `pending` (pending invites). Both are returned by default.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "joined", "pending" ], "type": "string" } }, { "description": "Only return the membership for this user ID, prefixed `user_`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return members with this role. `custom` matches members on a dashboard-managed custom role.", "in": "query", "name": "role", "required": false, "schema": { "enum": [ "owner", "admin", "partner", "sales_manager", "moderator", "advertiser", "app_manager", "support", "manager", "workforce", "custom" ], "type": "string" } }, { "description": "Only return members whose name or username contains this text, and invites whose email contains it.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only return the direct reports of this team member, prefixed `ausr_`. Pass the account ID, prefixed `biz_`, for the members who report to the business directly. Pending invites are excluded, and the list pages in `created_at` order without moving Partner-role members last.", "in": "query", "name": "reports_to_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return members with at least this many direct reports. Pending invites are excluded, and the list pages in `created_at` order without moving Partner-role members last.", "in": "query", "name": "direct_reports_min", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "Only return members with at most this many direct reports; `0` returns the people who manage no one. Pending invites are excluded, and the list pages in `created_at` order without moving Partner-role members last.", "in": "query", "name": "direct_reports_max", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "Only return members added before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return members added after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Field used to sort members. Members with the view-only Partner role are listed after all other members whichever way the list is sorted.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction. Defaults to `desc`.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TeamMember" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "a:WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "Team members listed." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid filter." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Missing the required scope." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Account not found." } }, "security": [ { "bearerAuth": [ "company:authorized_user:read" ] } ], "summary": "List Team Members", "tags": [ "Team Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Adds a member to an account's team with a system role. Identify them by exactly one of `user_id` or `email`. If the person has not yet accepted, or the email does not belong to a Whop account yet, an invitation is sent instead and the response is `202` with the pending team member, whose `status` is `pending` and whose id is prefixed `ausri_`. If they already have a pending invite, the request fails with a `400`. Granting the `workforce` role is also allowed with the `bounty:create` scope.", "operationId": "createTeamMember", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "role": "sales_manager", "user_id": "user_xxxxxxxxxxxxxx" }, "properties": { "account_id": { "description": "Account ID, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "email": { "description": "Email address to invite. Mutually exclusive with `user_id`. If the email already belongs to a Whop account it is treated the same as passing that account's `user_id`; otherwise a pending invite is created for the email.", "example": "marcus@shinetime.example", "type": "string" }, "role": { "description": "The system role to grant. Custom roles cannot be granted through the API. The Partner role provides view-only access.", "enum": [ "owner", "admin", "partner", "sales_manager", "moderator", "advertiser", "workforce" ], "example": "sales_manager", "type": "string" }, "user_id": { "description": "The user to add to the team, prefixed `user_`. Mutually exclusive with `email`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id", "role" ], "title": "CreateTeamMemberWithSystemRole", "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }, "description": "Team member created." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }, "description": "Invitation sent. The team member stays pending until they accept." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid request." }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid authentication." }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "authorized_user:create" ] } ], "summary": "Create Team Member", "tags": [ "Team Members" ], "x-whop-credentials": [ "account_api_key" ] }, "x-whop-surface": "native" }, "/team_members/{id}": { "delete": { "description": "Removes a team member from the account, or revokes a pending invite when given an `ausri_` ID. A user session may delete its own membership to leave the team without the delete scope. Removing a member on the `workforce` role is also allowed with the `bounty:create` scope. The account owner cannot be removed.", "operationId": "deleteTeamMember", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Team member removed." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid request." }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Not allowed to remove this member." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Team member not found." } }, "security": [ { "bearerAuth": [ "authorized_user:delete" ] }, { "bearerAuth": [ "bounty:create" ] } ], "summary": "Delete Team Member", "tags": [ "Team Members" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "get": { "description": "Retrieves a team member or pending invite by ID.", "operationId": "retrieveTeamMember", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }, "description": "Team member retrieved." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Team member not found." } }, "security": [ { "bearerAuth": [ "company:authorized_user:read" ] } ], "summary": "Retrieve Team Member", "tags": [ "Team Members" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Team member ID — `ausr_` for accepted members, `ausri_` for pending invites.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Changes a team member's system role. Requires a user session — account API keys cannot change member roles. The account owner's role cannot be changed, and you cannot change your own role.", "operationId": "updateTeamMember", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "role": { "description": "The system role to grant. Custom roles cannot be granted through the API. The Partner role provides view-only access.", "enum": [ "owner", "admin", "partner", "sales_manager", "moderator", "advertiser", "workforce" ], "example": "partner", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }, "description": "Team member updated." }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "Invalid request." }, "404": { "$ref": "#/components/responses/NotFound", "description": "Team member not found." } }, "security": [ { "bearerAuth": [ "authorized_user:update" ] } ], "summary": "Update Team Member", "tags": [ "Team Members" ], "x-whop-credentials": [] }, "x-whop-surface": "native" }, "/trades": { "get": { "description": "Lists trades you can access, newest first. User credentials see their own trades and those of accounts they belong to, including connected accounts; account credentials see their account and its connected accounts.", "operationId": "listTrades", "parameters": [ { "description": "Only return trades for this account or user, prefixed `biz_` or `user_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return trades with this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "processing", "in_review", "completed", "failed" ], "type": "string" } }, { "description": "Only return trades of this type.", "in": "query", "name": "type", "required": false, "schema": { "enum": [ "close", "order", "deposit", "withdraw" ], "type": "string" } }, { "description": "Field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "updated_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Trade" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "trades listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "status is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication is missing" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "selected account is not authorized" } }, "security": [ { "bearerAuth": [ "crypto_wallet:trade:read" ] }, { "bearerAuth": [ "crypto_wallet:trade" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "List Trades", "tags": [ "Trades" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Places an order, closes a perpetual position, or deposits to or withdraws from the trading balance, from the Whop-managed wallet of an account or user. Answers `201` with the trade in `pending`; it runs in the background, so read it with `GET /trades/:id` until its `status` is `completed`, `failed` or `in_review`. Trades run alongside each other, except a second order on one market at a different leverage, which answers `409`. A retry with the same `Idempotency-Key` returns the same trade.", "operationId": "createTrade", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account or user whose wallet trades, prefixed `biz_` or `user_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "Only for a deposit or withdraw, and required for both. For a deposit, the USDT0 to send from the wallet, with at most 6 decimals. For a withdraw, the USDC to send back, at least 1 with at most 6 decimals, or `all`.", "type": "string" }, "client_order_id": { "description": "Only for an order. Your own ID for the trade, 1 to 128 characters, unique for the account. Sending it again with the same order returns the same trade; with a different order it answers `409`.", "type": "string" }, "instrument_type": { "description": "`perpetual` or `spot`. Required for an order. A spot order first switches the trading account to Hyperliquid's unified account mode, where spot and perpetuals share one USDC balance.", "enum": [ "perpetual", "spot" ], "example": "perpetual", "type": "string" }, "leverage": { "description": "Only for a perpetual order. The cross leverage, from 1 to the market's maximum. Required unless `reduce_only`; not accepted on a reduce-only order.", "example": 10, "type": "integer" }, "market": { "description": "The market: a perpetual such as `BTC`, or for spot a pair priced in USDC such as `HYPE/USDC`. Required for an order or close, and a close takes only a perpetual; not accepted for a deposit or withdraw.", "example": "BTC", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Only for an order. Free-form string-to-string annotations: up to 50 keys of at most 40 characters, values up to 500 characters.", "type": "object" }, "notional": { "description": "Only for an order. The order value in USD, as a decimal string; the size is rounded down to the market's decimals. Send exactly one of `size` or `notional`.", "type": "string" }, "order_type": { "description": "`market` fills now within `slippage_bps` of the mid price; `limit` fills now at `price` or better. Anything unfilled is canceled. Required for an order.", "enum": [ "market", "limit" ], "example": "market", "type": "string" }, "price": { "description": "Only for an order. The limit price in USD, as a decimal string Hyperliquid accepts without rounding. Required for a limit order; not accepted for a market order.", "type": "string" }, "reduce_only": { "description": "Only for a perpetual order. Only reduce an open position; defaults to `false`. A reduce-only order takes no `leverage`.", "type": "boolean" }, "side": { "description": "`buy` or `sell`. Required for an order.", "enum": [ "buy", "sell" ], "example": "buy", "type": "string" }, "size": { "description": "Only for an order. The size in units of the market, as a decimal string, with at most the market's size decimals. Send exactly one of `size` or `notional`. The order must be worth at least 10 USD, unless reduce-only, and at most 5000 USD.", "example": "0.001", "type": "string" }, "slippage_bps": { "description": "Only for a market order or a close. The worst price as basis points from the mid price, from 1 to 1000; defaults to 100.", "type": "integer" }, "type": { "description": "`order` places one order from the trading balance, setting cross `leverage` first on a perpetual; when the balance is short, it bridges the USDT0 it needs from the wallet first. `deposit` bridges `amount` USDT0 from the wallet to the trading balance. `withdraw` sends `amount` USDC (or `all`) from the trading balance back to the wallet. `close` closes the whole position in `market` with a market reduce-only order; when the account is then flat, a `withdraw` trade sends the trading balance back to the wallet.", "enum": [ "close", "order", "deposit", "withdraw" ], "example": "order", "type": "string" } }, "required": [ "type", "account_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trade" } } }, "description": "trade created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the body is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication is missing" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "trading is not allowed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "an order on the market at another leverage is running, or the client_order_id is taken" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "trading is not available" } }, "security": [ { "bearerAuth": [ "crypto_wallet:trade" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "Create Trade", "tags": [ "Trades" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/trades/markets": { "get": { "description": "Returns every market you can trade on Whop.\n\n- **Spot:** listed by symbol: `BTC`, `ETH`, `SOL` and `XAUT` (gold).\n- **Perpetuals:** such as `BTC`. Send the `id` as `market` when you create a trade.\n\nThe same symbol can appear twice, once as a perpetual and once as spot, so use `id` together with `instrument_type` to tell them apart. Results are sorted by `id`, then `instrument_type`.\n\nThis endpoint is public: no API key is needed, and each IP address can make up to 60 requests a minute.", "operationId": "listMarkets", "parameters": [ { "description": "Only return perpetuals or only spot markets.", "in": "query", "name": "instrument_type", "required": false, "schema": { "enum": [ "perpetual", "spot" ], "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "markets": { "value": { "data": [ { "id": "BTC", "instrument_type": "perpetual", "max_leverage": 40, "price": { "amount": "80155.500000", "currency": "usd", "decimals": 6, "display_decimals": 6 }, "size_decimals": 5 }, { "id": "BTC", "instrument_type": "spot", "max_leverage": null, "price": { "amount": "80065.50000000", "currency": "usd", "decimals": 8, "display_decimals": 8 }, "size_decimals": 5 }, { "id": "ETH", "instrument_type": "perpetual", "max_leverage": 25, "price": { "amount": "2322.350000", "currency": "usd", "decimals": 6, "display_decimals": 6 }, "size_decimals": 4 }, { "id": "ETH", "instrument_type": "spot", "max_leverage": null, "price": { "amount": "2320.65000000", "currency": "usd", "decimals": 8, "display_decimals": 8 }, "size_decimals": 4 }, { "id": "SOL", "instrument_type": "perpetual", "max_leverage": 20, "price": { "amount": "101.325000", "currency": "usd", "decimals": 6, "display_decimals": 6 }, "size_decimals": 2 }, { "id": "SOL", "instrument_type": "spot", "max_leverage": null, "price": { "amount": "101.23500000", "currency": "usd", "decimals": 8, "display_decimals": 8 }, "size_decimals": 3 }, { "id": "XAUT", "instrument_type": "spot", "max_leverage": null, "price": { "amount": "4012.85000000", "currency": "usd", "decimals": 8, "display_decimals": 8 }, "size_decimals": 2 } ], "page_info": { "end_cursor": null, "has_next_page": false, "has_previous_page": false, "start_cursor": "MQ" } } } }, "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Market" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "type": [ "string", "null" ] } }, "required": [ "start_cursor", "end_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "markets listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "instrument_type is invalid" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ErrorResponse" } } }, "description": "market data is not available" } }, "security": [], "summary": "List Markets", "tags": [ "Trades" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/trades/{id}": { "get": { "description": "Retrieves a trade. Read it until its `status` is `completed`, `failed` or `in_review`.", "operationId": "retrieveTrade", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trade" } } }, "description": "trade retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "authentication is missing" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "trading permission is missing" }, "404": { "$ref": "#/components/responses/NotFound", "description": "trade was not found" } }, "security": [ { "bearerAuth": [ "crypto_wallet:trade:read" ] }, { "bearerAuth": [ "crypto_wallet:trade" ] }, { "bearerAuth": [ "crypto_wallet:manage" ] } ], "summary": "Retrieve Trade", "tags": [ "Trades" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Trade ID, prefixed `tint_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/transfers": { "get": { "description": "Lists the transfers you can see, sent or received, newest first by default. Optional account filters narrow the results.", "operationId": "listTransfer", "parameters": [ { "description": "Filter to transfers sent from this account.", "in": "query", "name": "origin_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to transfers received by this account.", "in": "query", "name": "destination_id", "required": false, "schema": { "type": "string" } }, { "description": "Sort column. Defaults to created_at.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "amount" ], "type": "string" } }, { "description": "Sort direction. Defaults to desc.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Only transfers created strictly before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only transfers created strictly after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "description": "A transfer between Whop accounts or users.", "properties": { "amount": { "description": "Amount credited to the recipient. Null while the transfer has not succeeded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination": { "description": "Business account or user receiving the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": null, "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "user", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "failed_at": { "description": "Recorded failure time. Null unless the transfer has failed.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable failure code. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "failure_reason": { "description": "Failure explanation. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "fee": { "description": "All applicable transfer fees, including platform markup. Null when the authoritative total is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": "object" }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Business account or user sending the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "account", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "status": { "description": "Current transfer status. A transfer can be created `processing` and settle a few seconds later; poll Retrieve Transfer or listen for the `transfer.completed` and `transfer.failed` webhooks instead of treating the create response as final. `succeeded` and `failed` are final.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" }, "status_changed_at": { "description": "Recorded time of the current transition. Null when the historical transition time is unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "succeeded_at": { "description": "Recorded success time. Null when unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "tracking_url": { "description": "Tracking page for the transfer. Viewing it requires sign-in and access to the transfer.", "example": "https://whop.com/ctt_xxxxxxxxxxxxxx/", "format": "uri", "type": "string" } }, "required": [ "object", "id", "status", "origin", "destination", "amount", "fee", "created_at", "status_changed_at", "succeeded_at", "failed_at", "failure_code", "failure_reason", "notes", "metadata", "tracking_url" ], "title": "Transfer", "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page", "start_cursor", "end_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "transfers listed" } }, "security": [ { "bearerAuth": [ "payout:transfer:read" ] } ], "summary": "List Transfers", "tags": [ "Transfers" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Moves money between Whop balances or funds a claim link anyone with the URL can redeem. The `type` you send decides which object comes back.", "operationId": "createTransfer", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "Moves credit between two Whop balances and returns a `transfer`. The transfer can come back `processing` and reach `succeeded` or `failed` asynchronously, usually within seconds.", "properties": { "amount": { "description": "The amount to move, in the transfer currency. For example 25.00.", "example": 25.0, "type": "number" }, "currency": { "description": "Currency, such as `usd`.", "example": "usd", "type": "string" }, "destination_id": { "description": "The recipient. A user ID (user_xxx), account ID (biz_xxx), or ledger account ID (ldgr_xxx).", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "feed_id": { "description": "The feed the transfer was initiated from. Given with `feed_type`, the payment receipt posts into that feed instead of a direct message.", "example": "feed_shineclub", "type": [ "string", "null" ] }, "feed_type": { "description": "The type of the feed named by `feed_id`.", "enum": [ "dms_feed", "chat_feed", "forum_feed", "livestream_feed", "universal_post", "user", null ], "example": "chat_feed", "type": [ "string", "null" ] }, "idempotence_key": { "description": "A unique key that makes retries safe. Retrying with the same key returns the original transfer instead of moving money twice.", "example": "shine-refund-1042", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Custom key-value pairs attached to the transfer. Max 50 keys, 100 chars per key, 500 chars per string value.", "example": { "order_id": "SHINE-1042" }, "type": [ "object", "null" ] }, "notes": { "description": "A short note describing the transfer.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "origin_id": { "description": "The account sending the funds. A user ID (user_xxx), account ID (biz_xxx), or ledger account ID (ldgr_xxx).", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "type": { "description": "The kind of money movement.", "enum": [ "balance" ], "example": "balance", "type": "string" } }, "required": [ "type", "origin_id", "destination_id", "amount", "currency" ], "title": "CreateBalanceTransfer", "type": "object" }, { "description": "Funds a shareable link anyone with the URL can redeem and returns a `claim_link`.", "properties": { "amount": { "description": "The amount to move, in the transfer currency. For example 25.00.", "example": 25.0, "type": "number" }, "expires_at": { "description": "Link expiry as an ISO 8601 timestamp. Defaults to 24 hours from creation.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "origin_id": { "description": "The account sending the funds. A user ID (user_xxx), account ID (biz_xxx), or ledger account ID (ldgr_xxx).", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "redeemable_count": { "description": "How many different users can claim the link. Defaults to 1.", "example": 3, "type": "integer" }, "type": { "description": "The kind of money movement.", "enum": [ "claim_link" ], "example": "claim_link", "type": "string" } }, "required": [ "type", "origin_id", "amount" ], "title": "CreateClaimLink", "type": "object" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "A transfer between Whop accounts or users.", "properties": { "amount": { "description": "Amount credited to the recipient. Null while the transfer has not succeeded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination": { "description": "Business account or user receiving the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "account", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "failed_at": { "description": "Recorded failure time. Null unless the transfer has failed.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable failure code. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "failure_reason": { "description": "Failure explanation. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "fee": { "description": "All applicable transfer fees, including platform markup. Null when the authoritative total is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": "object" }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Business account or user sending the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "account", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "status": { "description": "Current transfer status. A transfer can be created `processing` and settle a few seconds later; poll Retrieve Transfer or listen for the `transfer.completed` and `transfer.failed` webhooks instead of treating the create response as final. `succeeded` and `failed` are final.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" }, "status_changed_at": { "description": "Recorded time of the current transition. Null when the historical transition time is unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "succeeded_at": { "description": "Recorded success time. Null when unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "tracking_url": { "description": "Tracking page for the transfer. Viewing it requires sign-in and access to the transfer.", "example": "https://whop.com/ctt_xxxxxxxxxxxxxx/", "format": "uri", "type": "string" } }, "required": [ "object", "id", "status", "origin", "destination", "amount", "fee", "created_at", "status_changed_at", "succeeded_at", "failed_at", "failure_code", "failure_reason", "notes", "metadata", "tracking_url" ], "title": "Transfer", "type": "object" }, { "description": "A shareable link anyone holding its code can open to claim the funds.", "properties": { "amount": { "description": "Amount each claim receives.", "example": "25.00", "type": "string" }, "claim_url": { "description": "Shareable claim URL.", "example": "https://whop.com/claim", "type": "string" }, "claimable": { "description": "Whether this link can currently be claimed.", "example": false, "type": "boolean" }, "code": { "description": "Redeemable claim code.", "example": "demoFunded01", "type": "string" }, "created_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "expires_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Claim-link ID, prefixed `airdrp_`.", "example": "airdrp_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "claim_link" ], "example": "claim_link", "type": "string" }, "redeemable_count": { "description": "Maximum number of claims.", "example": 3, "type": "integer" }, "redeemed_count": { "description": "Number of completed claims.", "example": 0, "type": "integer" }, "remaining_claims": { "description": "Number of available claims, excluding slots reserved by pending claims.", "example": 3, "type": "integer" }, "sender": { "description": "The public account or user funding the claim link.", "discriminator": { "propertyName": "object" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "title": "ClaimLinkSenderAccount", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "title": "ClaimLinkSenderUser", "type": "object" } ] }, "source": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id" ], "type": "object" }, "status": { "description": "The newly funded link is ready to claim.", "enum": [ "pending" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "code", "claim_url", "status", "claimable", "amount", "currency", "redeemable_count", "redeemed_count", "remaining_claims", "expires_at", "created_at", "source", "sender" ], "title": "ClaimLink", "type": "object" } ] } } }, "description": "money movement created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required scope" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "payout:transfer_funds" ] }, { "bearerAuth": [ "payout:withdraw_funds" ] }, { "bearerAuth": [ "airdrop_link:manage" ] } ], "summary": "Create Transfer", "tags": [ "Transfers" ] }, "x-whop-surface": "native" }, "/transfers/recipients": { "get": { "description": "Lists the people and accounts you can send money to from a balance. Pass a result's ID as `destination_id` when creating a transfer.", "operationId": "listTransferRecipients", "parameters": [ { "description": "The account sending the money: a company account ID (`biz_`), or a user ID (`user_`) for that user's own personal balance.", "in": "query", "name": "origin_id", "required": true, "schema": { "type": "string" } }, { "description": "Search anyone on Whop by name or username, plus your own accounts by name or ID. An exact business ID (`biz_`), user ID (`user_`), or username returns that recipient first; an ID or an `@username` returns only that recipient. Omit it to get the team around the balance, the people you follow, and your own accounts. The list is the same whether the balance belongs to a company or to you. Searching from a `biz_` origin additionally requires the member:basic:read scope. A credential scoped to a single company is the exception to the search itself: it only ever sees that company's own people. Complete email addresses return no matches. Search results are limited to 20 recipients.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "oneOf": [ { "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "enum": [ "user" ], "example": "user", "type": "string" }, "profile_picture_url": { "description": "User profile image URL.", "example": "https://ui-avatars.com/api/", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "danawhitfield", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "username", "profile_picture_url" ], "title": "TransferRecipientUser", "type": "object" }, { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Account logo URL.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "object": { "enum": [ "account" ], "example": "account", "type": "string" }, "route": { "description": "Account route.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "Account display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] } }, "required": [ "object", "id", "title", "route", "logo_url" ], "title": "TransferRecipientAccount", "type": "object" } ] }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "recipients listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "origin account is missing" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks a required scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "origin account not found" } }, "security": [ { "bearerAuth": [ "payout:withdraw_funds", "company:authorized_user:read" ] }, { "bearerAuth": [ "payout:withdraw_funds" ] } ], "summary": "List Transfer Recipients", "tags": [ "Transfers" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_user_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/transfers/{id}": { "get": { "description": "Retrieves a single transfer.", "operationId": "retrieveTransfer", "responses": { "200": { "content": { "application/json": { "schema": { "description": "A transfer between Whop accounts or users.", "properties": { "amount": { "description": "Amount credited to the recipient. Null while the transfer has not succeeded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination": { "description": "Business account or user receiving the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "account", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "failed_at": { "description": "Recorded failure time. Null unless the transfer has failed.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable failure code. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "failure_reason": { "description": "Failure explanation. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "fee": { "description": "All applicable transfer fees, including platform markup. Null when the authoritative total is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": "object" }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Business account or user sending the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "account", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "status": { "description": "Current transfer status. A transfer can be created `processing` and settle a few seconds later; poll Retrieve Transfer or listen for the `transfer.completed` and `transfer.failed` webhooks instead of treating the create response as final. `succeeded` and `failed` are final.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" }, "status_changed_at": { "description": "Recorded time of the current transition. Null when the historical transition time is unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "succeeded_at": { "description": "Recorded success time. Null when unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "tracking_url": { "description": "Tracking page for the transfer. Viewing it requires sign-in and access to the transfer.", "example": "https://whop.com/ctt_xxxxxxxxxxxxxx/", "format": "uri", "type": "string" } }, "required": [ "object", "id", "status", "origin", "destination", "amount", "fee", "created_at", "status_changed_at", "succeeded_at", "failed_at", "failure_code", "failure_reason", "notes", "metadata", "tracking_url" ], "title": "Transfer", "type": "object" } } }, "description": "transfer retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "transfer not found" } }, "security": [ { "bearerAuth": [ "payout:transfer:read" ] } ], "summary": "Retrieve Transfer", "tags": [ "Transfers" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The transfer ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/users": { "get": { "description": "Searches for users by name or username, ranked by social proximity to the authenticated user. Without a `query`, returns the user's most recently followed users.", "operationId": "listUsers", "parameters": [ { "description": "A search term to filter users by name or username.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/User" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "MQ", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "users listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "dms:read" ] } ], "summary": "List Users", "tags": [ "Users" ], "x-whop-credentials": [ "app_api_key", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/users/me": { "get": { "description": "Retrieves the authenticated user. Same as `GET /users/:id` with the reserved id `me`: the self view, where self-only fields such as `email`, `balance`, and `cards` can be populated.", "operationId": "retrieveCurrentUser", "parameters": [ { "description": "Also return the trading account under `trading`: its address and its Hyperliquid WebSocket subscriptions. Only honored on the self view (me) with crypto_wallet:trade:read, crypto_wallet:trade, or crypto_wallet:manage permission and an Ethereum wallet.", "in": "query", "name": "include_trading", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "When set, returns your account-specific profile overrides for this account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Compute live wallet and owned-account balances (default true). Set false for identity-only reads. Ignored for callers without balance-read scope.", "in": "query", "name": "include_balance", "required": false, "schema": { "type": "boolean" } }, { "description": "Also compute your balance history (opt-in; runs a heavier query). Ignored for callers without balance-read scope.", "in": "query", "name": "include_balance_history", "required": false, "schema": { "type": "boolean" } }, { "description": "Balance-history window start, ISO 8601 date or datetime. Defaults to 30 days ago. Only used with `include_balance_history`.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "Balance-history window end, ISO 8601 date or datetime. Defaults to now. Only used with `include_balance_history`.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "Balance-history point granularity. Defaults to `day`. Only used with `include_balance_history`.", "in": "query", "name": "interval", "required": false, "schema": { "enum": [ "hour", "day", "week", "month" ], "type": "string" } }, { "description": "IANA time zone the balance-history points are bucketed in. Defaults to `UTC`. Only used with `include_balance_history`.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "current user retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve Current User", "tags": [ "Users" ], "x-whop-docs": "hidden" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates the authenticated user's global profile, or their profile override for an account when `account_id` is given. Not available to API keys.", "operationId": "updateCurrentUser", "parameters": [ { "description": "When set, updates the authenticated user's profile override for this account instead of their global profile.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "banner": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "bio": { "example": "Interior specialist. Leather, upholstery, and odor removal.", "type": "string" }, "name": { "example": "Tanya Cole", "type": "string" }, "profile_picture": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "username": { "example": "tanyacole", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "current user updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "API keys cannot update a global profile" } }, "security": [ { "bearerAuth": [ "user:profile:update" ] } ], "summary": "Update Current User", "tags": [ "Users" ], "x-whop-docs": "hidden" }, "x-whop-surface": "native" }, "/users/me/oauth_grants": { "get": { "description": "Lists the authenticated user's own OAuth grants: one per app they have authorized, per account they authorized it for. You cannot read another user's grants. Requires a user session: an API key or an OAuth token is refused, so an app can never enumerate the other apps a user has authorized.", "operationId": "listOauthGrants", "parameters": [ { "description": "Only return grants for this app, prefixed `app_`. An app the user has never authorized returns an empty list.", "in": "query", "name": "app_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort grants by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/OauthGrant" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "oauth grants listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" } }, "security": [ { "bearerAuth": [] } ], "summary": "List OAuth Grants", "tags": [ "Users" ], "x-whop-credentials": [], "x-whop-docs-subgroup": "OAuth Grants" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Completes the OAuth authorization step for the authenticated user: records their consent to the scopes an app asked for and mints an authorization code. Returns the grant plus a `redirect_url` carrying the code, which is returned only this once; the app exchanges it at `POST /oauth/token`. Requires a user session, because consent has to come from the account holder: an API key or an OAuth token is refused, so an app can never authorize itself. Send an `Idempotency-Key` so a retry returns the original `redirect_url` and code instead of issuing a second one.", "operationId": "createOauthGrant", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Authorize the app for one of the user's accounts rather than for the user alone, prefixed `biz_`. The user must have access to it.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "client_id": { "description": "The app being authorized, prefixed `app_`.", "example": "app_xxxxxxxxxxxxxx", "type": "string" }, "code_challenge": { "description": "The PKCE code challenge: the base64url-encoded SHA-256 of your code verifier, without padding. Required unless the app is confidential; a confidential app that leaves it out redeems the code with its secret instead of a verifier.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "code_challenge_method": { "description": "How `code_challenge` was derived. Only `S256` is accepted. Required with `code_challenge`.", "enum": [ "S256" ], "example": "S256", "type": "string" }, "consent_shown": { "default": true, "description": "Whether the consent UI listed these scopes for the user. Sending `false` succeeds only when the user has already granted every scope requested, or when the app is one of Whop's own with the consent skip switched on and asks for `openid` alone.", "example": true, "type": "boolean" }, "mcp_client": { "additionalProperties": false, "description": "The downstream MCP client displayed on the consent screen. Requires explicit consent even when the upstream app already has a grant. Bound to the authorization code and returned on token exchange so the MCP server can verify the approved client.", "properties": { "client_id": { "description": "The requesting MCP client's identifier.", "maxLength": 2048, "minLength": 1, "type": "string" }, "client_name": { "description": "The requesting MCP client's display name.", "maxLength": 2048, "minLength": 1, "type": "string" }, "redirect_uri": { "description": "The downstream redirect URI displayed to the user.", "maxLength": 2048, "minLength": 1, "type": "string" } }, "required": [ "client_id", "client_name", "redirect_uri" ], "type": "object" }, "nonce": { "description": "OIDC nonce, echoed into the resulting ID token. Required when `requested_scopes` includes `openid`.", "example": "n-0S6_WzA2Mj", "type": "string" }, "redirect_uri": { "description": "Where to send the user once they have consented. Must match one of the app's registered redirect URIs exactly — it is compared as a string, not normalized.", "example": "https://Booking.Shinetime.example:8443/oauth/Callback/", "type": "string" }, "requested_scopes": { "description": "The permissions the app is asking for, for example `member:basic:read`. `GET /api_keys/permissions` names and describes each one. Granting adds to whatever the user already granted this app rather than replacing it.", "items": { "example": "profile", "type": "string" }, "type": "array" }, "response_type": { "description": "The OAuth response type. Only `code` is accepted; defaults to `code`.", "enum": [ "code" ], "example": "code", "type": "string" }, "state": { "description": "Opaque value appended to `redirect_url` unchanged, for the client to correlate the response with its request.", "example": "opaque-client-state", "type": "string" } }, "required": [ "client_id", "redirect_uri", "requested_scopes" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthGrant" } } }, "description": "the app is authorized" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the account does not exist" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Authorize an App", "tags": [ "Users" ], "x-whop-credentials": [], "x-whop-docs-subgroup": "OAuth Grants" }, "x-whop-surface": "native" }, "/users/me/passkeys": { "get": { "description": "Lists the authenticated user's own passkeys, newest first. You cannot read another user's passkeys. Requires a user session: an API key or an OAuth token is refused, because a passkey confirms the account holder before a sensitive action and no app may enumerate one.", "operationId": "listPasskeys", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort passkeys by.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at" ], "type": "string" } }, { "description": "Sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Passkey" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] }, "has_next_page": { "example": true, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "passkeys listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" } }, "security": [ { "bearerAuth": [] } ], "summary": "List", "tags": [ "Users" ], "x-whop-credentials": [], "x-whop-docs-subgroup": "Passkeys" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Registers a passkey for the authenticated user from the attestation a browser produced for a `registration` challenge. Mint that challenge first with `POST /users/me/passkeys/challenge` and run the ceremony with its `creation_options`; it is single-use and expires 5 minutes after it is issued. Send back the `user_handle` the options carried: registering with it replaces the account's passkeys made before Whop issued options, which can only be deleted. Requires a user session that has completed step-up verification.", "operationId": "createPasskey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attestation_object": { "description": "The `attestationObject` from the WebAuthn attestation response, base64url-encoded.", "example": "YXR0ZXN0YXRpb24", "type": "string" }, "client_data_json": { "description": "The `clientDataJSON` from the WebAuthn attestation response, base64url-encoded.", "example": "Y2xpZW50LWRhdGE", "type": "string" }, "credential_id": { "description": "The WebAuthn credential ID the authenticator returned, base64url-encoded.", "example": "bmV3LWNyZWRlbnRpYWw", "type": "string" }, "nickname": { "description": "A name for this passkey, usually the device it lives on. 255 characters or fewer.", "example": "Work laptop", "type": "string" }, "transports": { "description": "The `getTransports()` result from the registration response. Values Whop does not recognize are dropped.", "items": { "type": "string" }, "type": "array" }, "user_handle": { "description": "The `creation_options.user.id` the passkey was created with. Must match the challenge's options.", "type": "string" } }, "required": [ "credential_id", "client_data_json", "attestation_object", "nickname" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passkey" } } }, "description": "passkey registered" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Register", "tags": [ "Users" ], "x-whop-credentials": [], "x-whop-docs-subgroup": "Passkeys" }, "x-whop-surface": "native" }, "/users/me/passkeys/challenge": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Mints the challenge and WebAuthn options a browser needs to run a ceremony against the authenticated user's own passkeys. A `registration` challenge enrolls a new passkey; a `deletion` challenge is bound to the one passkey named by `passkey_id` and proves the user still holds it. The options are in wire snake_case: convert the keys to camelCase before passing them to the browser. Challenges are single-use and expire 5 minutes after they are issued, so send a fresh `Idempotency-Key` per ceremony — a replayed key returns the original challenge, which may already have expired. Requires a user session. A `registration` challenge also requires step-up verification, so the user completes it before the browser ceremony.", "operationId": "createPasskeyChallenge", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "challenge_type": { "description": "The ceremony this challenge is for.", "enum": [ "registration", "deletion" ], "example": "deletion", "type": "string" }, "passkey_id": { "description": "The passkey the ceremony targets, prefixed `wcred_`. Required when `challenge_type` is `deletion`, ignored otherwise.", "example": "wcred_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "challenge_type" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyChallenge" } } }, "description": "challenge minted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the passkey is not the caller's own" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create Challenge", "tags": [ "Users" ], "x-whop-credentials": [], "x-whop-docs-subgroup": "Passkeys" }, "x-whop-surface": "native" }, "/users/me/passkeys/{id}": { "delete": { "description": "Deletes one of the authenticated user's own passkeys. The request body carries a WebAuthn assertion from the passkey being deleted, so possession of the credential is proven before it is removed: mint a `deletion` challenge for it first, run the ceremony with that passkey, and send the result here. Deleting the user's last passkey is allowed — their other step-up factors remain. Requires a user session.", "operationId": "deletePasskey", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authenticator_data": { "description": "The `authenticatorData` from the WebAuthn assertion, base64url-encoded.", "example": "YXV0aGVudGljYXRvci1kYXRh", "type": "string" }, "client_data_json": { "description": "The `clientDataJSON` from the WebAuthn assertion, base64url-encoded.", "example": "Y2xpZW50LWRhdGE", "type": "string" }, "signature": { "description": "The `signature` from the WebAuthn assertion, base64url-encoded.", "example": "c2lnbmF0dXJl", "type": "string" } }, "required": [ "client_data_json", "authenticator_data", "signature" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always `true`: the passkey was removed.", "example": true, "type": "boolean" }, "id": { "description": "The ID of the deleted passkey.", "example": "wcred_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "deleted", "id" ], "type": "object" } } }, "description": "passkey deleted" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request parameters are invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "the credential is not a user session" }, "404": { "$ref": "#/components/responses/NotFound", "description": "the passkey is not the caller's own" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete", "tags": [ "Users" ], "x-whop-credentials": [], "x-whop-docs-subgroup": "Passkeys" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Passkey ID, prefixed `wcred_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/users/me/preferences": { "get": { "description": "Retrieves the authenticated user's settings document.", "operationId": "retrieveUserPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferences" } } }, "description": "preferences retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [ "user:profile:update" ] } ], "summary": "Retrieve", "tags": [ "Users" ], "x-whop-credentials": [ "oauth_token" ], "x-whop-docs-subgroup": "Preferences" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates the authenticated user's settings document. Replaces the top-level keys it is given and leaves the rest untouched.", "operationId": "updateUserPreferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bounty_worker_onboarding_dismissed": { "description": "Whether the user has dismissed the first-time bounty worker onboarding. Set to `false` to show it again.", "example": true, "type": "boolean" }, "cards_auto_top_up": { "description": "Whether incoming funds, including pending balance, are automatically moved to the user's personal cards balance. Requires a cards balance and the `payout:account:update` permission.", "type": "boolean" }, "investigation_enabled": { "description": "Whether investigation mode is enabled for the user. Only meaningful for staff users with investigation access.", "example": false, "type": "boolean" }, "terms_accepted": { "description": "Records the user's acceptance of Whop's terms and policies. Only `true` is accepted — the server stamps `terms_accepted_at` and acceptance cannot be withdrawn here.", "example": true, "type": "boolean" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferences" } } }, "description": "preferences updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "unsupported preference key" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [ "user:profile:update" ] } ], "summary": "Update", "tags": [ "Users" ], "x-whop-credentials": [ "oauth_token" ], "x-whop-docs-subgroup": "Preferences" }, "x-whop-surface": "native" }, "/users/me/preferences/notifications": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Sets the authenticated user's notification preferences, each addressed by `scope` rather than by ID. The batch is applied in one transaction: if any entry is rejected, none are written. Experience levels are applied before topic overrides, because setting a level replaces every topic preference for that experience, so an override sent alongside a level wins. The response reports what each scope now resolves to, in the order the entries were sent.", "operationId": "setUserNotificationPreferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "preferences": { "description": "The preferences to set, at most 100 per request.", "items": { "properties": { "level": { "description": "What the user is notified about in this scope. `mentions` is only valid for an experience level; a topic override is `all` or `nothing`. `null` clears the preference, so the scope inherits its default again rather than being switched off.", "enum": [ "all", "mentions", "nothing", null ], "example": "nothing", "type": [ "string", "null" ] }, "scope": { "description": "What the preference applies to. `null` on a dimension means the preference is not narrowed there. A scope read back from either list endpoint can be sent as-is. A scope naming an experience with no topic sets that experience's level; any other scope sets a topic override.", "properties": { "account_id": { "description": "Account to scope the preference to (member notifications), `biz_` tag.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "channel": { "description": "Delivery channel the preference applies to. Omit it (or pass `null`) to apply the preference to every channel.", "enum": [ "in_app", "mobile", null ], "example": "in_app", "type": [ "string", "null" ] }, "experience_id": { "description": "Experience to scope the preference to (`exp_` tag). Requires `account_id` when a `topic_id` is also given.", "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "team_account_id": { "description": "Account whose team notifications the preference is scoped to, `biz_` tag.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "topic_id": { "description": "Notification topic to scope the preference to, `topic_` tag. Topic IDs come from `GET /notifications/topics`.", "example": "topic_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "type": "object" } }, "required": [ "scope", "level" ], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "preferences" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/NotificationPreferenceState" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "preferences set" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "scope names nothing to scope to" }, "404": { "$ref": "#/components/responses/NotFound", "description": "scoped account does not exist" } }, "security": [ { "bearerAuth": [ "user:notifications:update" ] } ], "summary": "Set", "tags": [ "Users" ], "x-whop-credentials": [ "oauth_token" ], "x-whop-docs-subgroup": "Preferences/Notifications" }, "x-whop-surface": "native" }, "/users/me/preferences/notifications/experiences": { "get": { "description": "Lists the authenticated user's per-experience notification levels. Experiences the user never set a level for are omitted — their effective level is `all`.", "operationId": "listUserNotificationExperiencePreferences", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ExperienceNotificationPreference" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "preferences listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "List Experiences", "tags": [ "Users" ], "x-whop-credentials": [ "oauth_token" ], "x-whop-docs-subgroup": "Preferences/Notifications" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/users/me/preferences/notifications/topics": { "get": { "description": "Lists the authenticated user's topic-scoped notification preferences, plus user-agnostic platform defaults. Per-experience levels are listed separately, by `GET /users/me/preferences/notifications/experiences`.", "operationId": "listUserNotificationTopicPreferences", "parameters": [ { "description": "Only return preferences for this delivery channel (or not narrowed to a channel).", "in": "query", "name": "channel", "required": false, "schema": { "enum": [ "in_app", "mobile" ], "type": "string" } }, { "description": "Only return preferences scoped to this account's member notifications (`biz_` tag), or not narrowed to an account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this account's team notifications (`biz_` tag), or not narrowed to a team account.", "in": "query", "name": "team_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this experience (`exp_` tag), or not narrowed to an experience.", "in": "query", "name": "experience_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this notification topic (`topic_` tag), or not narrowed to a topic.", "in": "query", "name": "topic_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UserNotificationPreference" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "preferences listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "no authenticated user" } }, "security": [ { "bearerAuth": [ "user:notifications:read" ] } ], "summary": "List Topics", "tags": [ "Users" ], "x-whop-credentials": [ "oauth_token" ], "x-whop-docs-subgroup": "Preferences/Notifications" }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/users/{id}": { "get": { "description": "Retrieves a user by `user_` tag or username, or the authenticated user with the reserved id `me`. Self-only fields such as `email`, `balance`, and `earnings_usd` are populated only when the id is `me`, and are always `null` when addressing a user by tag or username.", "operationId": "retrieveUser", "parameters": [ { "description": "Also return the trading account under `trading`: its address and its Hyperliquid WebSocket subscriptions. Only honored on the self view (me) with crypto_wallet:trade:read, crypto_wallet:trade, or crypto_wallet:manage permission and an Ethereum wallet.", "in": "query", "name": "include_trading", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "When set, returns the user's account-specific profile overrides for this account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Compute live wallet and owned-account balances on the self view (default true). Set false for identity-only reads. Ignored when the id is not `me` or the caller lacks balance-read scope.", "in": "query", "name": "include_balance", "required": false, "schema": { "type": "boolean" } }, { "description": "Also compute your balance history (opt-in; runs a heavier query). Only applies when the id is `me`; ignored for callers without balance-read scope.", "in": "query", "name": "include_balance_history", "required": false, "schema": { "type": "boolean" } }, { "description": "Balance-history window start, ISO 8601 date or datetime. Defaults to 30 days ago. Only used with `include_balance_history`.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "Balance-history window end, ISO 8601 date or datetime. Defaults to now. Only used with `include_balance_history`.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "Balance-history point granularity. Defaults to `day`. Only used with `include_balance_history`.", "in": "query", "name": "interval", "required": false, "schema": { "enum": [ "hour", "day", "week", "month" ], "type": "string" } }, { "description": "IANA time zone the balance-history points are bucketed in. Defaults to `UTC`. Only used with `include_balance_history`.", "in": "query", "name": "time_zone", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "user retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no user with that id" } }, "security": [ {}, { "bearerAuth": [] } ], "summary": "Retrieve User", "tags": [ "Users" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "User ID (prefixed `user_`), username, or `me` for the authenticated user.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a user, addressed by `user_` tag, username, or the reserved id `me` for the authenticated user. A user token updates their own global profile; an API key updates the user's profile override for the account in `account_id`.", "operationId": "updateUser", "parameters": [ { "description": "The account whose profile override to update. Required for API key callers.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "banner": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "bio": { "example": "Interior specialist. Leather, upholstery, and odor removal.", "type": "string" }, "name": { "example": "Tanya Cole", "type": "string" }, "profile_picture": { "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "username": { "example": "tanyacole", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "user updated" } }, "security": [ { "bearerAuth": [ "user:profile:update" ] } ], "summary": "Update User", "tags": [ "Users" ] }, "x-whop-surface": "native" }, "/users/{id}/access/{resource_id}": { "get": { "description": "Checks whether a user has access to an account, product, or experience the caller can reach.", "operationId": "checkUserAccess", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_level": { "enum": [ "no_access", "admin", "customer" ], "example": "customer", "type": "string" }, "has_access": { "example": true, "type": "boolean" } }, "required": [ "has_access", "access_level" ], "type": "object" } } }, "description": "access checked" } }, "security": [ { "bearerAuth": [] } ], "summary": "Check User Access", "tags": [ "Users" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The user_ tag or username to check access for.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "An account (biz_), product (prod_), or experience (exp_) ID.", "in": "path", "name": "resource_id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/users/{id}/recommend_actions": { "get": { "description": "Lists the recommended actions computed for the authenticated user: personal suggestions, such as starting a business or becoming an affiliate, pooled with the highest-impact actions across the accounts the user owns. You can only list your own recommended actions.", "operationId": "listUserRecommendedActions", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UserRecommendedAction" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "recommended actions listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "reading another user's recommended actions" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Recommended Actions", "tags": [ "Users" ], "x-whop-credentials": [ "account_user_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "`me`, or the authenticated user's own `user_` tag or username.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/users/{user_id}/fees": { "get": { "description": "Retrieves the fees charged when the user moves money with their personal balance: withdrawals, transfers, bank deposits, and funding cards from pending balance. Each fee has the same shape as in Retrieve Account Fees. You can only retrieve your own fees, and they are read-only.", "operationId": "retrieveUserFees", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFees" } } }, "description": "fees retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "another user's fees" }, "404": { "$ref": "#/components/responses/NotFound", "description": "user not found" } }, "security": [ { "bearerAuth": [ "user:balance:read" ] } ], "summary": "Retrieve User Fees", "tags": [ "Users" ], "x-whop-credentials": [ "oauth_token" ] }, "parameters": [ { "description": "`me`, or the authenticated user's own `user_` tag or username.", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ApiVersionDate" } ], "x-whop-surface": "native" }, "/variants": { "get": { "description": "Lists an account's variants. To list a product's public, buyable variants without authentication, omit `account_id` and pass `product_ids`.", "operationId": "listVariants", "parameters": [ { "description": "The unique identifier of the account to list variants for. Required unless `product_ids` is provided for a public product-variant read.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The sort direction for results. Defaults to descending.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "The field to sort results by. Defaults to created_at.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "id", "active_members_count", "created_at", "internal_notes", "expiration_days" ], "type": "string" } }, { "description": "Filter to only variants matching these release methods.", "in": "query", "name": "release_methods", "required": false, "schema": { "items": { "example": "buy_now", "type": "string" }, "type": "array" } }, { "description": "Filter to only variants matching these visibility states.", "in": "query", "name": "visibilities", "required": false, "schema": { "items": { "example": "visible", "type": "string" }, "type": "array" } }, { "description": "Filter to only variants matching these billing types.", "in": "query", "name": "billing_types", "required": false, "schema": { "items": { "example": "renewal", "type": "string" }, "type": "array" } }, { "description": "Filter to only variants belonging to these product identifiers. When `account_id` is omitted, this is required and the response is publicly readable: only visible, non-invoice variants are returned.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return variants created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return variants created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "The currency to state each variant's prices in. Omit it, or send null, for each variant's own currency. `auto` states them in the currency of the country Whop places the buyer in: by `ip_address` when your server sends one, and by the request's own IP address otherwise. To choose that country instead, send `presentment_country` in place of this. A three-letter ISO 4217 code, such as `eur`, states them in that currency. A variant converts only where a payment quote for it would be priced in that currency, and stays in its own currency otherwise: a renewing variant, one with adaptive pricing off, a currency no payment method can collect, or `auto` for a buyer Whop cannot place in a country. Converted prices are an estimate at the current exchange rate. Nothing is held: the payment quote the buyer pays from fixes the rate.", "in": "query", "name": "presentment_currency", "required": false, "schema": { "example": "auto", "type": [ "string", "null" ] } }, { "description": "The buyer's IP address, when your server reads on their behalf. Needs an API key; any other caller is placed by its own request. Where `presentment_currency` `auto` finds the buyer's local currency, and where a payment method must be able to collect it.", "in": "query", "name": "ip_address", "required": false, "schema": { "example": "203.0.113.7", "type": [ "string", "null" ] } }, { "description": "The country to state each variant's prices for, as an ISO 3166-1 alpha-2 code such as `JP`, when the buyer chose one: a store's country picker. States them in the currency `auto` would for a buyer in that country, so send it instead of `presentment_currency`, never with it. Whether a payment method can collect that currency is still judged where the buyer is: by `ip_address`, else by the request's own IP address. A country Whop has no currency for is ignored, and the prices are stated as `auto` would state them.", "in": "query", "name": "presentment_country", "required": false, "schema": { "example": "JP", "type": [ "string", "null" ] } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/VariantListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "visible variants listed by product without authentication" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ {}, { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "List Variants", "tags": [ "Variants" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a pricing variant for a product, defining the billing interval, price, and availability customers buy it with.", "operationId": "createVariant", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The unique identifier of the account to create this variant for. Required when authenticating as a user; an account API key supplies its own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "adaptive_pricing_enabled": { "description": "Whether this variant accepts local currency payments via adaptive pricing.", "example": true, "type": [ "boolean", "null" ] }, "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "type": "boolean" }, "attributes": { "description": "Attribute values that make this variant one variant of its product, as a map of attribute name to value, e.g. `{\"size\": \"Large\", \"color\": \"Blue\"}`. Names are normalized to snake_case identifiers (`Ring Size` becomes `ring_size`) and come back in alphabetical order. Every variant on a product must carry the same attribute names and a distinct set of values. Send `null` to make the variant an ordinary pricing option again.", "example": { "color": "Blue", "size": "Large" }, "type": [ "object", "null" ] }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual.", "example": 30, "type": [ "integer", "null" ] }, "billing_type": { "description": "Variant billing type, such as `one_time` or `renewal`.", "example": "renewal", "type": "string" }, "cancel_discount_intervals": { "description": "How long the retention discount lasts: `0` forever, `1` the next payment only, or a number of calendar months from when the customer accepts it. Required when `offer_cancel_discount` is true.", "example": 3, "type": [ "integer", "null" ] }, "cancel_discount_percentage": { "description": "Percentage taken off each discounted renewal, as a whole number from 1 to 100. Required when `offer_cancel_discount` is true.", "example": 20, "maximum": 100, "minimum": 1, "type": [ "integer", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this variant.", "example": { "background_color": "#0f172a", "border_style": "rounded", "button_color": "#f59e0b", "font_family": "roboto" }, "type": [ "object", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the variant's pricing. Defaults to USD.", "example": "usd", "type": "string" }, "custom_fields": { "description": "An array of custom field definitions to collect from customers at checkout. Omitting this field clears existing custom fields.", "items": { "properties": { "field_type": { "description": "The type of the custom field.", "enum": [ "text" ], "example": "text", "type": "string" }, "id": { "description": "The ID of the custom field (if being updated).", "example": "field_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The name of the custom field.", "example": "Vehicle make and model", "type": "string" }, "order": { "description": "The order of the field.", "example": 1, "type": "integer" }, "placeholder": { "description": "An example response displayed in the input field.", "example": "2021 Audi S5", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "example": true, "type": "boolean" } }, "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "A text description of the variant displayed to customers on the product page.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days before the membership expires.", "example": 365, "type": [ "integer", "null" ] }, "image": { "description": "An image displayed on the product page to represent this variant.", "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial amount charged in the variant's currency, e.g. 10.43 for $10.43. A paid fiat variant charges at least 1.00 in its currency; use 0 for free.", "example": 0, "type": [ "number", "null" ] }, "internal_notes": { "description": "Private notes visible only to the account owner. Not shown to customers.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "metadata": { "description": "Custom key-value pairs to store on the variant. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` (a checkout call-to-action button label — one of the product custom CTA values, e.g. `subscribe`, `get_offer`) and `custom_cta_url` (a URL the button links to; web or `tel:`) override the product's call to action for this variant and are validated on save.", "example": { "bay": "2", "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club", "route": "north-austin" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether to offer a retention discount when a customer attempts to cancel.", "example": true, "type": [ "boolean", "null" ] }, "override_tax_type": { "description": "Override the default tax classification for this specific variant.", "example": "inclusive", "type": "string" }, "payment_method_configuration": { "description": "Explicit payment method configuration for the variant. When not provided, the account's defaults apply. Send at least one of `enabled` or `disabled`; an omitted one is empty.", "properties": { "disabled": { "description": "Payment method types explicitly disabled for this variant — the `type` values from the payment method types catalogue. Types Whop no longer offers, and the read-only `unknown` placeholder, are dropped.", "example": [ "paypal" ], "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "Payment method types explicitly enabled for this variant — the `type` values from the payment method types catalogue. Types Whop no longer offers, and the read-only `unknown` placeholder, are dropped.", "example": [ "card" ], "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "product_id": { "description": "The unique identifier of the product to attach this variant to.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this variant.", "example": "buy_now", "type": "string" }, "renewal_price": { "description": "The amount charged each billing period for recurring variants, in the variant's currency. A paid fiat variant charges at least 1.00 in its currency.", "example": 59, "type": [ "number", "null" ] }, "sku": { "description": "Stock keeping unit for this variant. Maximum 100 characters. Free text, not enforced unique.", "example": "TEE-LARGE-BLUE", "type": [ "string", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses, from 2 to 115. Only valid on `renewal` variants.", "example": 4, "maximum": 115, "minimum": 2, "type": [ "integer", "null" ] }, "stock": { "description": "The maximum number of units available for purchase. Ignored when unlimited_stock is true.", "example": 25, "type": [ "integer", "null" ] }, "three_ds_level": { "description": "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. Send `null` to inherit the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "title": { "description": "The display name of the variant shown to customers on the product page. Maximum 30 characters.", "example": "Unlimited Wash Club", "maxLength": 30, "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial duration before the first recurring charge.", "example": 7, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the variant has unlimited stock. When true, the stock field is ignored.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers or hidden from public view.", "example": "visible", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } }, "description": "variant created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid parameters" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "plan:create" ] } ], "summary": "Create Variant", "tags": [ "Variants" ] }, "x-whop-surface": "native" }, "/variants/{id}": { "delete": { "description": "Deletes a variant from a product. It stops selling immediately; existing memberships on it are unaffected.", "operationId": "deleteVariant", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted variant.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "variant deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no variant with that id" } }, "security": [ { "bearerAuth": [ "plan:delete" ] } ], "summary": "Delete Variant", "tags": [ "Variants" ] }, "get": { "description": "Retrieves a variant. Requires no authentication; fields that need a permission are `null` for callers without it.", "operationId": "retrieveVariant", "parameters": [ { "description": "The currency to state each variant's prices in. Omit it, or send null, for each variant's own currency. `auto` states them in the currency of the country Whop places the buyer in: by `ip_address` when your server sends one, and by the request's own IP address otherwise. To choose that country instead, send `presentment_country` in place of this. A three-letter ISO 4217 code, such as `eur`, states them in that currency. A variant converts only where a payment quote for it would be priced in that currency, and stays in its own currency otherwise: a renewing variant, one with adaptive pricing off, a currency no payment method can collect, or `auto` for a buyer Whop cannot place in a country. Converted prices are an estimate at the current exchange rate. Nothing is held: the payment quote the buyer pays from fixes the rate.", "in": "query", "name": "presentment_currency", "required": false, "schema": { "example": "auto", "type": [ "string", "null" ] } }, { "description": "The buyer's IP address, when your server reads on their behalf. Needs an API key; any other caller is placed by its own request. Where `presentment_currency` `auto` finds the buyer's local currency, and where a payment method must be able to collect it.", "in": "query", "name": "ip_address", "required": false, "schema": { "example": "203.0.113.7", "type": [ "string", "null" ] } }, { "description": "The country to state each variant's prices for, as an ISO 3166-1 alpha-2 code such as `JP`, when the buyer chose one: a store's country picker. States them in the currency `auto` would for a buyer in that country, so send it instead of `presentment_currency`, never with it. Whether a payment method can collect that currency is still judged where the buyer is: by `ip_address`, else by the request's own IP address. A country Whop has no currency for is ignored, and the prices are stated as `auto` would state them.", "in": "query", "name": "presentment_country", "required": false, "schema": { "example": "JP", "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } }, "description": "variant retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no variant with that id" } }, "security": [ {}, { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "Retrieve Variant", "tags": [ "Variants" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Variant ID, prefixed `plan_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a variant's pricing, billing interval, visibility, stock, and other settings.", "operationId": "updateVariant", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "adaptive_pricing_enabled": { "description": "Whether this variant accepts local currency payments via adaptive pricing.", "example": true, "type": [ "boolean", "null" ] }, "allow_multiple_quantity": { "description": "Whether more than one unit can be purchased in an order. Renewal variants cannot enable it. When `false`, checkouts, carts, and invoices reject a quantity above 1.", "type": "boolean" }, "attributes": { "description": "Attribute values that make this variant one variant of its product, as a map of attribute name to value, e.g. `{\"size\": \"Large\", \"color\": \"Blue\"}`. Names are normalized to snake_case identifiers (`Ring Size` becomes `ring_size`) and come back in alphabetical order. Every variant on a product must carry the same attribute names and a distinct set of values. Send `null` to make the variant an ordinary pricing option again.", "example": { "color": "Blue", "size": "Large" }, "type": [ "object", "null" ] }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual.", "example": 30, "type": [ "integer", "null" ] }, "cancel_discount_intervals": { "description": "How long the retention discount lasts: `0` forever, `1` the next payment only, or a number of calendar months from when the customer accepts it. Required when `offer_cancel_discount` is true.", "example": 3, "type": [ "integer", "null" ] }, "cancel_discount_percentage": { "description": "Percentage taken off each discounted renewal, as a whole number from 1 to 100. Required when `offer_cancel_discount` is true.", "example": 20, "maximum": 100, "minimum": 1, "type": [ "integer", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this variant.", "example": { "background_color": "#0f172a", "border_style": "rounded", "button_color": "#f59e0b", "font_family": "roboto" }, "type": [ "object", "null" ] }, "currency": { "description": "The three-letter ISO currency code for the variant's pricing. Defaults to USD.", "example": "usd", "type": "string" }, "custom_fields": { "description": "An array of custom field definitions to collect from customers at checkout. Omitting this field clears existing custom fields.", "items": { "properties": { "field_type": { "description": "The type of the custom field.", "enum": [ "text" ], "example": "text", "type": "string" }, "id": { "description": "The ID of the custom field (if being updated).", "example": "field_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "The name of the custom field.", "example": "Vehicle make and model", "type": "string" }, "order": { "description": "The order of the field.", "example": 1, "type": "integer" }, "placeholder": { "description": "An example response displayed in the input field.", "example": "2021 Audi S5", "type": [ "string", "null" ] }, "required": { "description": "Whether or not the field is required.", "example": true, "type": "boolean" } }, "type": "object" }, "type": [ "array", "null" ] }, "description": { "description": "A text description of the variant displayed to customers on the product page.", "example": "Two hand washes a month, interior vacuum, and a quarterly sealant top-up.", "type": [ "string", "null" ] }, "expiration_days": { "description": "Access duration in days before the membership expires.", "example": 365, "type": [ "integer", "null" ] }, "image": { "description": "An image displayed on the product page to represent this variant.", "properties": { "direct_upload_id": { "example": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "id": { "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": [ "object", "null" ] }, "initial_price": { "description": "Initial amount charged in the variant's currency, e.g. 10.43 for $10.43. A paid fiat variant charges at least 1.00 in its currency; use 0 for free.", "example": 0, "type": [ "number", "null" ] }, "internal_notes": { "description": "Private notes visible only to the account owner. Not shown to customers.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "metadata": { "description": "Custom key-value pairs to store on the variant. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value. The reserved keys `custom_cta` (a checkout call-to-action button label — one of the product custom CTA values, e.g. `subscribe`, `get_offer`) and `custom_cta_url` (a URL the button links to; web or `tel:`) override the product's call to action for this variant and are validated on save.", "example": { "bay": "2", "custom_cta": "subscribe", "custom_cta_url": "https://shinetime.example/wash-club", "route": "north-austin" }, "type": [ "object", "null" ] }, "offer_cancel_discount": { "description": "Whether to offer a retention discount when a customer attempts to cancel.", "example": true, "type": [ "boolean", "null" ] }, "override_tax_type": { "description": "Override the default tax classification for this specific variant.", "example": "inclusive", "type": "string" }, "payment_method_configuration": { "description": "Explicit payment method configuration for the variant. When not provided, the account's defaults apply. Send at least one of `enabled` or `disabled`; an omitted one is empty.", "properties": { "disabled": { "description": "Payment method types explicitly disabled for this variant — the `type` values from the payment method types catalogue. Types Whop no longer offers, and the read-only `unknown` placeholder, are dropped.", "example": [ "paypal" ], "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "enabled": { "description": "Payment method types explicitly enabled for this variant — the `type` values from the payment method types catalogue. Types Whop no longer offers, and the read-only `unknown` placeholder, are dropped.", "example": [ "card" ], "items": { "$ref": "#/components/schemas/PaymentMethodTypes" }, "type": "array" }, "include_platform_defaults": { "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "release_method": { "description": "Sales method for this variant.", "example": "buy_now", "type": "string" }, "renewal_price": { "description": "The amount charged each billing period for recurring variants, in the variant's currency. A paid fiat variant charges at least 1.00 in its currency.", "example": 59, "type": [ "number", "null" ] }, "sku": { "description": "Stock keeping unit for this variant. Maximum 100 characters. Free text, not enforced unique.", "example": "TEE-LARGE-BLUE", "type": [ "string", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses, from 2 to 115. Only valid on `renewal` variants.", "example": 4, "maximum": 115, "minimum": 2, "type": [ "integer", "null" ] }, "stock": { "description": "The maximum number of units available for purchase. Ignored when unlimited_stock is true.", "example": 25, "type": [ "integer", "null" ] }, "strike_through_initial_price": { "description": "A comparison price displayed with a strikethrough for the initial price.", "example": 99, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "A comparison price displayed with a strikethrough for the renewal price.", "example": 79, "type": [ "number", "null" ] }, "three_ds_level": { "description": "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. Send `null` to inherit the account default.", "enum": [ "mandate_challenge", "mandate_if_required", "frictionless_if_required", null ], "example": "frictionless_if_required", "type": [ "string", "null" ] }, "title": { "description": "The display name of the variant shown to customers on the product page. Maximum 30 characters.", "example": "Unlimited Wash Club", "maxLength": 30, "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial duration before the first recurring charge.", "example": 7, "type": [ "integer", "null" ] }, "unlimited_stock": { "description": "Whether the variant has unlimited stock. When true, the stock field is ignored.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the variant is visible to customers or hidden from public view.", "example": "visible", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Variant" } } }, "description": "variant updated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "plan:update" ] } ], "summary": "Update Variant", "tags": [ "Variants" ] }, "x-whop-surface": "native" }, "/variants/{id}/calculate_tax": { "parameters": [ { "description": "Variant ID, prefixed `plan_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "deprecated": true, "description": "Deprecated. Quote tax with `POST /payment_quotes` instead. Previews tax for a variant before checkout, based on the buyer's location.", "operationId": "calculateVariantTax", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "address": { "country": "DE", "postal_code": "10115" } }, "properties": { "address": { "description": "Buyer billing address used for tax calculation. Provide either `address.country` or `ip_address`; include state and postal code when available for more accurate results.", "properties": { "city": { "description": "City name.", "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2 country code, such as `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, such as `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "country" ], "type": [ "object", "null" ] }, "ip_address": { "description": "Buyer IP address used to infer location when no billing address is provided.", "example": "1.2.3.4", "type": "string" }, "tax_ids": { "description": "Optional buyer tax ID for B2B exemptions. At most one entry is supported.", "items": { "properties": { "type": { "description": "Tax ID type, such as `eu_vat` for an EU VAT number.", "enum": [ "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", "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" ], "example": "us_ein", "type": "string" }, "value": { "description": "Tax ID value, for example `DE123456789`.", "example": "12-3456789", "type": "string" } }, "type": "object" }, "maxItems": 1, "type": [ "array", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "example": { "currency": "usd", "status": "calculated", "subtotal": 1000, "tax_amount": 70, "tax_behavior": "exclusive", "total": 1070 }, "properties": { "currency": { "description": "Three-letter ISO 4217 currency code for the returned amounts.", "example": "usd", "type": "string" }, "status": { "description": "Whether Whop calculated tax for this preview. `not_calculated` means no tax could be determined, so `tax_amount` is 0 and `total` equals `subtotal`.", "enum": [ "calculated", "not_calculated" ], "example": "calculated", "type": "string" }, "subtotal": { "description": "Variant price in the currency's smallest unit, for example cents. For exclusive tax, this is the pre-tax amount; for inclusive tax, it already includes tax and equals the total.", "example": 1000, "type": "integer" }, "tax_amount": { "description": "Calculated tax amount in the currency's smallest unit. For exclusive tax, this is added on top of the subtotal; for inclusive tax, it is the portion of the subtotal that is tax.", "example": 70, "type": "integer" }, "tax_behavior": { "description": "Whether tax is added on top of the variant price or already included in it for this buyer's location.", "enum": [ "exclusive", "inclusive" ], "example": "exclusive", "type": "string" }, "total": { "description": "Amount the buyer would pay in the currency's smallest unit.", "example": 1070, "type": "integer" } }, "required": [ "currency", "tax_behavior", "subtotal", "tax_amount", "total", "status" ], "type": "object" } } }, "description": "tax calculated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "request is invalid" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the variant read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "variant not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "Calculate Tax", "tags": [ "Variants" ], "x-whop-deprecated-since": "2026-10-12", "x-whop-docs": "hidden", "x-whop-successor": "POST /payment_quotes" }, "x-whop-surface": "native" }, "/verifications": { "get": { "description": "Lists the verifications for an account or user, including their status and any required actions.", "operationId": "listVerifications", "parameters": [ { "description": "Business account whose verifications you want to list, prefixed `biz_`. Provide this or `user_id`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The caller's own user ID, prefixed `user_`, to list personal verifications. Provide this or `account_id`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Field used to sort returned verifications.", "in": "query", "name": "order", "required": false, "schema": { "default": "updated_at", "enum": [ "updated_at", "created_at" ], "type": "string" } }, { "description": "Sort direction for returned verifications.", "in": "query", "name": "direction", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "incorporation_date": { "description": "Date the business was incorporated, formatted as `YYYY-MM-DD`, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "2021-03-15", "type": [ "string", "null" ] }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "owners": { "description": "Owners of the business and the progress of each one's own verification. Empty for individual verifications.", "items": { "properties": { "date_of_birth": { "description": "The owner's date of birth on file, formatted as `YYYY-MM-DD`.", "example": "1985-06-01", "type": [ "string", "null" ] }, "first_name": { "example": "Riley", "type": [ "string", "null" ] }, "id": { "description": "Owner ID, prefixed `own_`. Send it in Update Verification's `owners` to change or remove the owner, including one added in the hosted session.", "example": "own_xxxxxxxxxxxxxx", "type": "string" }, "last_name": { "example": "Owner", "type": [ "string", "null" ] }, "ownership_percentage": { "description": "Share of the business the person owns, from 0 to 100.", "example": 60, "type": [ "number", "null" ] }, "rejected_checks": { "description": "What the provider rejected when the owner's verification was sent back: `details` (their name, date of birth, or other details don't match their ID), `identity_document`, or `selfie`. Fix only these with Update Verification. Empty otherwise.", "items": { "enum": [ "details", "identity_document", "selfie" ], "example": "details", "type": "string" }, "type": "array" }, "required_documents": { "description": "The owner's documents and their progress. Empty for an owner added with `verification_id`.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "roles": { "description": "What the person is to the business.", "items": { "enum": [ "ubo", "director", "representative", "shareholder" ], "example": "ubo", "type": "string" }, "type": "array" }, "status": { "description": "Where the owner's own verification stands, in the same states as `status`. `action_required` when their documents need sending again.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "not_started", "type": "string" } }, "required": [ "id", "roles", "ownership_percentage", "first_name", "last_name", "date_of_birth", "status", "required_documents", "rejected_checks" ], "type": "object" }, "type": "array" }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "place_of_incorporation": { "description": "State or region where the business is incorporated, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "Delaware", "type": [ "string", "null" ] }, "registration_number": { "description": "Number the business was registered under in its place of incorporation, such as a state file number in the US or a Company Number in the UK. Business verifications only; as on file for the business verification, or `null` until it is sent.", "example": "7654321", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted. For a business verification created with `documents` or `owners`, this includes the company details and documents still missing before it can be sent for review; each owner's documents are listed under that owner.", "items": { "properties": { "action_url": { "description": "URL for a related action, such as completing liveness verification or viewing a payment. Absent when no action is available.", "type": "string" }, "alternative_document_label": { "description": "A document that answers this item in place of `value`, such as an IRS EIN letter when the EIN could not be matched. Send its pages in `files`, with or without a corrected `value`. Absent when only `value` is accepted.", "example": "IRS EIN letter (CP 575 or 147C) that shows your business's legal name and your EIN on the same letter", "type": "string" }, "details_label": { "description": "Follow-up prompt shown with this requirement.", "type": "string" }, "details_required": { "description": "Whether the follow-up response is required when visible.", "type": "boolean" }, "details_visible_for": { "description": "Selected option values that make the follow-up prompt visible.", "items": { "type": "string" }, "type": "array" }, "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "response_type": { "description": "Optional native input format for a text response.", "enum": [ "yes_no", "yes_no_na", "date", "url", "number", "tel" ], "example": "yes_no", "type": "string" }, "selection_mode": { "description": "Whether a question with `options` accepts one value or multiple values.", "enum": [ "single", "multiple" ], "example": "single", "type": "string" }, "supporting_documents": { "description": "Documents supplied with the requirement for context.", "items": { "$ref": "#/components/schemas/File" }, "type": "array" }, "supporting_files_explanation_allowed": { "description": "Whether a written explanation may replace required supporting files.", "type": "boolean" }, "supporting_files_required": { "description": "Whether this requirement also needs supporting files.", "type": "boolean" }, "supporting_files_visible_for": { "description": "Selected option values that make the supporting-file input visible.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), `text_with_files` (send `value` and optional `files`), `address` (send `address`), or `liveness` (open `action_url`, then send `value` as `true` after completion).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on individual verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/abc", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "action_required", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "required": [ "owners" ], "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required identity-read scope" } }, "security": [ { "bearerAuth": [ "identity:read" ] } ], "summary": "List Verifications", "tags": [ "Verifications" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts a hosted verification session for an account or user, or returns the active session when one already exists; any fields you send prefill it. To skip the hosted session, send `documents` to verify the person from files in this request, `share_token` to reuse a verification another Sumsub account completed, or `verification_id` to reuse one the signed-in user completed on Whop. For a business, `documents` and `owners` add company formation documents and owners to the verification, and once everything is in this call sends the business for review — call it again after Update Verification to send it. Until then it stays `pending` and the hosted session collects anything left out. Once the account has an `approved` verification, every mode except `verification_id` is rejected — unlink it first to start a new one.", "operationId": "createVerification", "parameters": [ { "description": "Business account whose identity you want to verify, prefixed `biz_`. Provide this or `user_id`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "The caller's own user ID, prefixed `user_`, for a personal verification. Provide this or `account_id`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "discriminator": { "propertyName": "kind" }, "oneOf": [ { "description": "Request body for an individual (KYC) verification. Omit `kind` or set it to `individual`. KYC is required to pay out funds and is a prerequisite for Whop Card access. Accepting payments does not require verification until a business reaches $5000 in payments.\n\nAdd `business_name` and `business_structure` if the individual operates under a business entity — this enables payouts to be received by a business bank account. `country` is always the individual's own country, and the supported `business_structure` values vary by it — see [Business structures](/developer/verification/business-structures).", "properties": { "address": { "description": "Every value accepts `null`, so a form seeded from a previous response can round-trip unset fields unchanged.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`. An address in a [sanctioned country or region](/trust-and-safety/trust-safety-overview/sanctioned-countries) is rejected with the error code `address_country_sanctioned`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "business_name": { "description": "Legal business name for a sole proprietor or single-member LLC.", "example": "Shine Time Auto Detailing LLC", "type": "string" }, "business_structure": { "description": "Entity type for sole proprietors, such as `single_member_llc`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "private_corporation", "type": "string" }, "business_tax_identification_number": { "description": "The business ID number of the company, as appropriate for the company's country. Examples are an Employer Identification Number (EIN) in the US, a Business Number in Canada, or a Company Number in the UK.", "example": "12-3456789", "type": "string" }, "business_website": { "description": "Business website URL. Whop store pages are not accepted.", "example": "https://shinetime.example", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "document_type": { "description": "Identity document being sent, when verifying with `documents`. Decides exactly which file slots to send: `id_card` → `id_card_front` + `id_card_back` + `selfie`; `drivers` → `drivers_front` + `drivers_back` + `selfie`; `residence_permit` → `residence_permit_front` + `residence_permit_back` + `selfie`; `passport` → `passport_front` + `selfie`. See [Identity documents](/developer/verification/identity-documents).", "enum": [ "id_card", "drivers", "residence_permit", "passport" ], "example": "residence_permit", "type": "string" }, "documents": { "description": "Identity document files, each value the file's raw bytes base64-encoded (JPEG, PNG, or PDF, up to 5MB per file before encoding). Sending this object verifies the person from the files in this request instead of a hosted session — individual verifications only, and the request must also carry `document_type`, `first_name`, `last_name`, `date_of_birth`, `country`, `phone`, `tax_identification_number`, and an `address` with `line1`, `city`, `state`, and `postal_code`. Send every slot for your `document_type` — a missing or rejected file fails the whole request and nothing is submitted; review starts automatically once every document is accepted. See [Identity documents](/developer/verification/identity-documents) for a full walkthrough.", "properties": { "drivers_back": { "description": "Back of the driver's license, base64-encoded. Required when `document_type` is `drivers`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "drivers_front": { "description": "Front of the driver's license, base64-encoded. Required when `document_type` is `drivers`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "id_card_back": { "description": "Back of the ID card, base64-encoded. Required when `document_type` is `id_card`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "id_card_front": { "description": "Front of the ID card, base64-encoded. Required when `document_type` is `id_card`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "passport_front": { "description": "Photo page of the passport, base64-encoded. Required when `document_type` is `passport`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "residence_permit_back": { "description": "Back of the residence permit, base64-encoded. Required when `document_type` is `residence_permit`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "residence_permit_front": { "description": "Front of the residence permit, base64-encoded. Required when `document_type` is `residence_permit`.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" }, "selfie": { "description": "Photo of the person's face, base64-encoded. Always required, with every document type. Must be JPEG or PNG.", "example": "/9j/4GFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh/9k=", "type": "string" } }, "type": "object" }, "first_name": { "example": "Marcus", "type": "string" }, "kind": { "description": "Verification type. Defaults to `individual`.", "enum": [ "individual" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": "string" }, "phone": { "example": "+xxxxxxxxxxx", "type": "string" }, "share_token": { "description": "Sumsub share token for a person a partner has already verified, generated by their Sumsub account for Whop's client ID. Reuses that verification instead of collecting anything: Whop imports the shared identity, rechecks it against its own requirements, and returns `approved` when it satisfies them, or `pending` with a `session_url` covering only what is still missing. Requires a Reusable KYC agreement between the partner's Sumsub account and Whop's. Each token works once, and cannot be combined with `documents` or `document_type`.", "example": "_act-sbx-jwt-eyJhbGciOiJub25l", "type": "string" }, "tax_identification_number": { "description": "The government-issued ID number of the person being verified — the individual for a KYC verification, or the business representative for a KYB verification — as appropriate for their country. Examples are a Social Security Number (SSN) in the US, or a Social Insurance Number in Canada.", "example": "123456789", "type": "string" }, "verification_id": { "description": "ID of an `approved` verification to reuse on this account instead of verifying the person again, for example `idpf_XXXXXXXX`. The verification becomes this account's current one for its kind — replacing whichever verification of that kind the account already has, and carrying its payout account across — and the response is that same verification, unchanged. Only the signed-in Whop user who started the original verification can reuse it: API keys, OAuth tokens, and onboarding links are refused. `kind` is the only other field it accepts, and must match the reused verification. An account whose verification was denied or is still under review cannot reuse one.", "example": "idpf_xxxxxxxxxxxxxx", "type": "string" } }, "title": "CreateIndividualVerification", "type": "object" }, { "description": "Request body for a business entity (KYB) verification. Set `kind` to `business`. KYB includes everything KYC provides and additionally unlocks financing options for payments and business Whop Cards.", "properties": { "address": { "description": "Every value accepts `null`, so a form seeded from a previous response can round-trip unset fields unchanged.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`. An address in a [sanctioned country or region](/trust-and-safety/trust-safety-overview/sanctioned-countries) is rejected with the error code `address_country_sanctioned`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing LLC", "type": "string" }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "private_corporation", "type": "string" }, "business_tax_identification_number": { "description": "The business ID number of the company, as appropriate for the company's country. Examples are an Employer Identification Number (EIN) in the US, a Business Number in Canada, or a Company Number in the UK.", "example": "12-3456789", "type": "string" }, "business_website": { "description": "Business website URL. Whop store pages are not accepted.", "example": "https://shinetime.example", "type": "string" }, "country": { "description": "Country of incorporation as a two-letter ISO 3166-1 country code.", "example": "US", "type": "string" }, "date_of_birth": { "description": "Business representative's date of birth, formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "documents": { "description": "Company formation documents, each the ID of a file uploaded with Create File and not yet attached to anything else, prefixed `file_`. Send the ID once its `upload_status` is `ready`. Each file must be a PDF, JPEG, or PNG of up to 10MB. They are filed under the business's country, from `country`, `address`, or an earlier request. A document of a kind already on file is kept unless it was rejected, so a retried request does not add a second copy. The hosted session at `session_url` collects anything still missing.", "properties": { "articles_of_incorporation": { "description": "File ID of the articles of incorporation or organization, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "certificate_of_incorporation": { "description": "File ID of the certificate of incorporation or formation, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "first_name": { "description": "First name of the business representative, used to prefill the verification session.", "example": "Marcus", "type": "string" }, "incorporation_date": { "description": "Date the business was incorporated, formatted as `YYYY-MM-DD`. Cannot be in the future. Sent to the verification provider and returned in the response; `requested_information` asks for it while it is still missing.", "example": "2026-01-01", "format": "date", "type": "string" }, "kind": { "description": "Must be `business` to start a KYB verification.", "enum": [ "business" ], "example": "business", "type": "string" }, "last_name": { "description": "Last name of the business representative, used to prefill the verification session.", "example": "Webb", "type": "string" }, "owners": { "description": "Owners of the business, up to 10 per request. Once the company details, the company documents, and the owners are in and every new owner's documents were sent, Create Verification sends the business for review: in the request that completes it, as soon as the last owner's documents finish sending in the background, or when called again after Update Verification. Owners can still be added, changed, or removed while the review waits on them.", "items": { "description": "An owner of the business. Send `verification_id` to add someone with an approved verification on this account or on a member of its team, or a new owner's details and documents to verify them from this request. An owner already on the verification is not added twice, so a retried request is safe.", "properties": { "address": { "description": "The new owner's home address, with `line1`, `city`, `state`, and `postal_code`.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`. An address in a [sanctioned country or region](/trust-and-safety/trust-safety-overview/sanctioned-countries) is rejected with the error code `address_country_sanctioned`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "country": { "description": "The new owner's country, as a two-letter ISO 3166-1 code.", "example": "US", "type": "string" }, "date_of_birth": { "description": "The new owner's date of birth, formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "format": "date", "type": "string" }, "document_type": { "description": "Identity document in `documents`. Decides which slots to send: `id_card` → `id_card_front` + `id_card_back`; `drivers` → `drivers_front` + `drivers_back`; `residence_permit` → `residence_permit_front` + `residence_permit_back`; `passport` → `passport_front`. Every type also takes `selfie`.", "enum": [ "id_card", "drivers", "residence_permit", "passport" ], "example": "passport", "type": "string" }, "documents": { "description": "The owner's identity document and selfie, each the ID of a ready file uploaded with Create File and not yet attached to anything else, prefixed `file_`. Send every slot for `document_type` plus `selfie`. Document files can be a PDF, JPEG, or PNG and the selfie a JPEG or PNG, each up to 10MB. They're sent to the verification provider in the background: the owner reads `processing` until then, and `action_required`, with a `rejection_reason` on each document, if a file couldn't be used.", "properties": { "drivers_back": { "description": "File ID of the back of the driver's license. Required when `document_type` is `drivers`.", "type": "string" }, "drivers_front": { "description": "File ID of the front of the driver's license. Required when `document_type` is `drivers`.", "type": "string" }, "id_card_back": { "description": "File ID of the back of the ID card. Required when `document_type` is `id_card`.", "type": "string" }, "id_card_front": { "description": "File ID of the front of the ID card. Required when `document_type` is `id_card`.", "type": "string" }, "passport_front": { "description": "File ID of the passport's photo page. Required when `document_type` is `passport`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_back": { "description": "File ID of the back of the residence permit. Required when `document_type` is `residence_permit`.", "type": "string" }, "residence_permit_front": { "description": "File ID of the front of the residence permit. Required when `document_type` is `residence_permit`.", "type": "string" }, "selfie": { "description": "File ID of a photo of the owner's face. Must be a JPEG or PNG. Required, except on Update Verification for an owner whose selfie already passed.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "email": { "description": "The new owner's email address.", "example": "marcus@shinetime.example", "type": "string" }, "first_name": { "description": "The new owner's first name.", "example": "Riley", "type": "string" }, "last_name": { "description": "The new owner's last name.", "example": "Owner", "type": "string" }, "ownership_percentage": { "description": "Share of the business the person owns, from 0 to 100. Across every owner it can't add up to more than 100.", "example": 40, "maximum": 100, "minimum": 0, "type": "number" }, "phone": { "description": "The new owner's phone number, with country code.", "example": "+xxxxxxxxxxx", "type": "string" }, "roles": { "description": "What the person is to the business: `ubo` for an ultimate beneficial owner, `director`, `representative` for someone who acts for the business, or `shareholder`. Required for a new owner.", "items": { "enum": [ "ubo", "director", "representative", "shareholder" ], "example": "ubo", "type": "string" }, "type": "array" }, "tax_identification_number": { "description": "The new owner's government-issued ID number, such as a Social Security Number in the US.", "example": "123456780", "type": "string" }, "verification_id": { "description": "ID of an `approved` individual verification to add as this owner, prefixed `idpf_`. It must be the account's own verification or a team member's. Takes only `roles` and `ownership_percentage` alongside it.", "example": "idpf_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "maxItems": 10, "type": "array" }, "place_of_incorporation": { "description": "State or region where the business is incorporated. Sent to the verification provider and returned in the response; `requested_information` asks for it while it is still missing.", "example": "TX", "type": "string" }, "registration_number": { "description": "Number the business was registered under in its place of incorporation, such as a state file number in the US or a Company Number in the UK. Sent to the verification provider and returned in the response; `requested_information` asks for it while it is still missing.", "example": "0803486771", "type": "string" }, "share_token": { "description": "Sumsub share token for a person a partner has already verified, generated by their Sumsub account for Whop's client ID. Reuses that verification instead of collecting anything: Whop imports the shared identity, rechecks it against its own requirements, and returns `approved` when it satisfies them, or `pending` with a `session_url` covering only what is still missing. Requires a Reusable KYC agreement between the partner's Sumsub account and Whop's. Each token works once, and cannot be combined with `documents` or `document_type`.", "example": "_act-sbx-jwt-eyJhbGciOiJub25l", "type": "string" }, "tax_identification_number": { "description": "The government-issued ID number of the person being verified — the individual for a KYC verification, or the business representative for a KYB verification — as appropriate for their country. Examples are a Social Security Number (SSN) in the US, or a Social Insurance Number in Canada.", "example": "123456789", "type": "string" }, "verification_id": { "description": "ID of an `approved` verification to reuse on this account instead of verifying the person again, for example `idpf_XXXXXXXX`. The verification becomes this account's current one for its kind — replacing whichever verification of that kind the account already has, and carrying its payout account across — and the response is that same verification, unchanged. Only the signed-in Whop user who started the original verification can reuse it: API keys, OAuth tokens, and onboarding links are refused. `kind` is the only other field it accepts, and must match the reused verification. An account whose verification was denied or is still under review cannot reuse one.", "example": "idpf_xxxxxxxxxxxxxx", "type": "string" } }, "title": "CreateBusinessVerification", "type": "object" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "incorporation_date": { "description": "Date the business was incorporated, formatted as `YYYY-MM-DD`, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "2021-03-15", "type": [ "string", "null" ] }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "owners": { "description": "Owners of the business and the progress of each one's own verification. Empty for individual verifications.", "items": { "properties": { "date_of_birth": { "description": "The owner's date of birth on file, formatted as `YYYY-MM-DD`.", "example": "1985-06-01", "type": [ "string", "null" ] }, "first_name": { "example": "Riley", "type": [ "string", "null" ] }, "id": { "description": "Owner ID, prefixed `own_`. Send it in Update Verification's `owners` to change or remove the owner, including one added in the hosted session.", "example": "own_xxxxxxxxxxxxxx", "type": "string" }, "last_name": { "example": "Owner", "type": [ "string", "null" ] }, "ownership_percentage": { "description": "Share of the business the person owns, from 0 to 100.", "example": 60, "type": [ "number", "null" ] }, "rejected_checks": { "description": "What the provider rejected when the owner's verification was sent back: `details` (their name, date of birth, or other details don't match their ID), `identity_document`, or `selfie`. Fix only these with Update Verification. Empty otherwise.", "items": { "enum": [ "details", "identity_document", "selfie" ], "example": "details", "type": "string" }, "type": "array" }, "required_documents": { "description": "The owner's documents and their progress. Empty for an owner added with `verification_id`.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "roles": { "description": "What the person is to the business.", "items": { "enum": [ "ubo", "director", "representative", "shareholder" ], "example": "ubo", "type": "string" }, "type": "array" }, "status": { "description": "Where the owner's own verification stands, in the same states as `status`. `action_required` when their documents need sending again.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "not_started", "type": "string" } }, "required": [ "id", "roles", "ownership_percentage", "first_name", "last_name", "date_of_birth", "status", "required_documents", "rejected_checks" ], "type": "object" }, "type": "array" }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "place_of_incorporation": { "description": "State or region where the business is incorporated, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "Delaware", "type": [ "string", "null" ] }, "registration_number": { "description": "Number the business was registered under in its place of incorporation, such as a state file number in the US or a Company Number in the UK. Business verifications only; as on file for the business verification, or `null` until it is sent.", "example": "7654321", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted. For a business verification created with `documents` or `owners`, this includes the company details and documents still missing before it can be sent for review; each owner's documents are listed under that owner.", "items": { "properties": { "action_url": { "description": "URL for a related action, such as completing liveness verification or viewing a payment. Absent when no action is available.", "type": "string" }, "alternative_document_label": { "description": "A document that answers this item in place of `value`, such as an IRS EIN letter when the EIN could not be matched. Send its pages in `files`, with or without a corrected `value`. Absent when only `value` is accepted.", "example": "IRS EIN letter (CP 575 or 147C) that shows your business's legal name and your EIN on the same letter", "type": "string" }, "details_label": { "description": "Follow-up prompt shown with this requirement.", "type": "string" }, "details_required": { "description": "Whether the follow-up response is required when visible.", "type": "boolean" }, "details_visible_for": { "description": "Selected option values that make the follow-up prompt visible.", "items": { "type": "string" }, "type": "array" }, "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "response_type": { "description": "Optional native input format for a text response.", "enum": [ "yes_no", "yes_no_na", "date", "url", "number", "tel" ], "example": "yes_no", "type": "string" }, "selection_mode": { "description": "Whether a question with `options` accepts one value or multiple values.", "enum": [ "single", "multiple" ], "example": "single", "type": "string" }, "supporting_documents": { "description": "Documents supplied with the requirement for context.", "items": { "$ref": "#/components/schemas/File" }, "type": "array" }, "supporting_files_explanation_allowed": { "description": "Whether a written explanation may replace required supporting files.", "type": "boolean" }, "supporting_files_required": { "description": "Whether this requirement also needs supporting files.", "type": "boolean" }, "supporting_files_visible_for": { "description": "Selected option values that make the supporting-file input visible.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), `text_with_files` (send `value` and optional `files`), `address` (send `address`), or `liveness` (open `action_url`, then send `value` as `true` after completion).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on individual verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/abc", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "action_required", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "required": [ "owners" ], "type": "object" } } }, "description": "OK" }, "201": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "incorporation_date": { "description": "Date the business was incorporated, formatted as `YYYY-MM-DD`, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "2021-03-15", "type": [ "string", "null" ] }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "owners": { "description": "Owners of the business and the progress of each one's own verification. Empty for individual verifications.", "items": { "properties": { "date_of_birth": { "description": "The owner's date of birth on file, formatted as `YYYY-MM-DD`.", "example": "1985-06-01", "type": [ "string", "null" ] }, "first_name": { "example": "Riley", "type": [ "string", "null" ] }, "id": { "description": "Owner ID, prefixed `own_`. Send it in Update Verification's `owners` to change or remove the owner, including one added in the hosted session.", "example": "own_xxxxxxxxxxxxxx", "type": "string" }, "last_name": { "example": "Owner", "type": [ "string", "null" ] }, "ownership_percentage": { "description": "Share of the business the person owns, from 0 to 100.", "example": 60, "type": [ "number", "null" ] }, "rejected_checks": { "description": "What the provider rejected when the owner's verification was sent back: `details` (their name, date of birth, or other details don't match their ID), `identity_document`, or `selfie`. Fix only these with Update Verification. Empty otherwise.", "items": { "enum": [ "details", "identity_document", "selfie" ], "example": "details", "type": "string" }, "type": "array" }, "required_documents": { "description": "The owner's documents and their progress. Empty for an owner added with `verification_id`.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "roles": { "description": "What the person is to the business.", "items": { "enum": [ "ubo", "director", "representative", "shareholder" ], "example": "ubo", "type": "string" }, "type": "array" }, "status": { "description": "Where the owner's own verification stands, in the same states as `status`. `action_required` when their documents need sending again.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "processing", "type": "string" } }, "required": [ "id", "roles", "ownership_percentage", "first_name", "last_name", "date_of_birth", "status", "required_documents", "rejected_checks" ], "type": "object" }, "type": "array" }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "place_of_incorporation": { "description": "State or region where the business is incorporated, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "Delaware", "type": [ "string", "null" ] }, "registration_number": { "description": "Number the business was registered under in its place of incorporation, such as a state file number in the US or a Company Number in the UK. Business verifications only; as on file for the business verification, or `null` until it is sent.", "example": "7654321", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted. For a business verification created with `documents` or `owners`, this includes the company details and documents still missing before it can be sent for review; each owner's documents are listed under that owner.", "items": { "properties": { "action_url": { "description": "URL for a related action, such as completing liveness verification or viewing a payment. Absent when no action is available.", "type": "string" }, "alternative_document_label": { "description": "A document that answers this item in place of `value`, such as an IRS EIN letter when the EIN could not be matched. Send its pages in `files`, with or without a corrected `value`. Absent when only `value` is accepted.", "example": "IRS EIN letter (CP 575 or 147C) that shows your business's legal name and your EIN on the same letter", "type": "string" }, "details_label": { "description": "Follow-up prompt shown with this requirement.", "type": "string" }, "details_required": { "description": "Whether the follow-up response is required when visible.", "type": "boolean" }, "details_visible_for": { "description": "Selected option values that make the follow-up prompt visible.", "items": { "type": "string" }, "type": "array" }, "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "response_type": { "description": "Optional native input format for a text response.", "enum": [ "yes_no", "yes_no_na", "date", "url", "number", "tel" ], "example": "yes_no", "type": "string" }, "selection_mode": { "description": "Whether a question with `options` accepts one value or multiple values.", "enum": [ "single", "multiple" ], "example": "single", "type": "string" }, "supporting_documents": { "description": "Documents supplied with the requirement for context.", "items": { "$ref": "#/components/schemas/File" }, "type": "array" }, "supporting_files_explanation_allowed": { "description": "Whether a written explanation may replace required supporting files.", "type": "boolean" }, "supporting_files_required": { "description": "Whether this requirement also needs supporting files.", "type": "boolean" }, "supporting_files_visible_for": { "description": "Selected option values that make the supporting-file input visible.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), `text_with_files` (send `value` and optional `files`), `address` (send `address`), or `liveness` (open `action_url`, then send `value` as `true` after completion).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on individual verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/new", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "pending", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "required": [ "owners" ], "type": "object" } } }, "description": "verification created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required identity-write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "identity:write" ] } ], "summary": "Create Verification", "tags": [ "Verifications" ], "x-whop-credentials": [ "account_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/verifications/{id}": { "get": { "description": "Retrieves a verification by ID, including its status and any information or documents still required.", "operationId": "getVerification", "parameters": [ { "description": "Verification profile ID, prefixed `idpf_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "incorporation_date": { "description": "Date the business was incorporated, formatted as `YYYY-MM-DD`, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "2021-03-15", "type": [ "string", "null" ] }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "owners": { "description": "Owners of the business and the progress of each one's own verification. Empty for individual verifications.", "items": { "properties": { "date_of_birth": { "description": "The owner's date of birth on file, formatted as `YYYY-MM-DD`.", "example": "1985-06-01", "type": [ "string", "null" ] }, "first_name": { "example": "Riley", "type": [ "string", "null" ] }, "id": { "description": "Owner ID, prefixed `own_`. Send it in Update Verification's `owners` to change or remove the owner, including one added in the hosted session.", "example": "own_xxxxxxxxxxxxxx", "type": "string" }, "last_name": { "example": "Owner", "type": [ "string", "null" ] }, "ownership_percentage": { "description": "Share of the business the person owns, from 0 to 100.", "example": 60, "type": [ "number", "null" ] }, "rejected_checks": { "description": "What the provider rejected when the owner's verification was sent back: `details` (their name, date of birth, or other details don't match their ID), `identity_document`, or `selfie`. Fix only these with Update Verification. Empty otherwise.", "items": { "enum": [ "details", "identity_document", "selfie" ], "example": "details", "type": "string" }, "type": "array" }, "required_documents": { "description": "The owner's documents and their progress. Empty for an owner added with `verification_id`.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "roles": { "description": "What the person is to the business.", "items": { "enum": [ "ubo", "director", "representative", "shareholder" ], "example": "ubo", "type": "string" }, "type": "array" }, "status": { "description": "Where the owner's own verification stands, in the same states as `status`. `action_required` when their documents need sending again.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "not_started", "type": "string" } }, "required": [ "id", "roles", "ownership_percentage", "first_name", "last_name", "date_of_birth", "status", "required_documents", "rejected_checks" ], "type": "object" }, "type": "array" }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "place_of_incorporation": { "description": "State or region where the business is incorporated, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "Delaware", "type": [ "string", "null" ] }, "registration_number": { "description": "Number the business was registered under in its place of incorporation, such as a state file number in the US or a Company Number in the UK. Business verifications only; as on file for the business verification, or `null` until it is sent.", "example": "7654321", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted. For a business verification created with `documents` or `owners`, this includes the company details and documents still missing before it can be sent for review; each owner's documents are listed under that owner.", "items": { "properties": { "action_url": { "description": "URL for a related action, such as completing liveness verification or viewing a payment. Absent when no action is available.", "type": "string" }, "alternative_document_label": { "description": "A document that answers this item in place of `value`, such as an IRS EIN letter when the EIN could not be matched. Send its pages in `files`, with or without a corrected `value`. Absent when only `value` is accepted.", "example": "IRS EIN letter (CP 575 or 147C) that shows your business's legal name and your EIN on the same letter", "type": "string" }, "details_label": { "description": "Follow-up prompt shown with this requirement.", "type": "string" }, "details_required": { "description": "Whether the follow-up response is required when visible.", "type": "boolean" }, "details_visible_for": { "description": "Selected option values that make the follow-up prompt visible.", "items": { "type": "string" }, "type": "array" }, "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "response_type": { "description": "Optional native input format for a text response.", "enum": [ "yes_no", "yes_no_na", "date", "url", "number", "tel" ], "example": "yes_no", "type": "string" }, "selection_mode": { "description": "Whether a question with `options` accepts one value or multiple values.", "enum": [ "single", "multiple" ], "example": "single", "type": "string" }, "supporting_documents": { "description": "Documents supplied with the requirement for context.", "items": { "$ref": "#/components/schemas/File" }, "type": "array" }, "supporting_files_explanation_allowed": { "description": "Whether a written explanation may replace required supporting files.", "type": "boolean" }, "supporting_files_required": { "description": "Whether this requirement also needs supporting files.", "type": "boolean" }, "supporting_files_visible_for": { "description": "Selected option values that make the supporting-file input visible.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), `text_with_files` (send `value` and optional `files`), `address` (send `address`), or `liveness` (open `action_url`, then send `value` as `true` after completion).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on individual verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "submitted", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/abc", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "action_required", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "required": [ "owners" ], "type": "object" } } }, "description": "verification retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no verification with that ID is visible to the credential" } }, "security": [ { "bearerAuth": [ "identity:read" ] }, { "bearerAuth": [ "ad_campaign:create" ] } ], "summary": "Retrieve Verification", "tags": [ "Verifications" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates editable profile details or submits answers for items returned in `requested_information`. On a business verification still collecting details, company details, `documents`, and `owners` also go to the verification provider; call Create Verification again to send the business for review once everything is in. Under review, `registration_number`, `incorporation_date`, `place_of_incorporation`, and `documents` are refused. While the review waits on owners, owners can still be added, changed, or removed with `remove`; otherwise only an owner's missing documents can still be sent. Once a verification is `approved` its profile details are locked and can no longer be edited.", "operationId": "updateVerification", "parameters": [ { "description": "Verification profile ID, prefixed `idpf_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "requested_information": [ { "id": "inrqi_textxxxxxx", "value": "https://example.com", "value_type": "raw" }, { "address": { "city": "Austin", "country": "US", "line1": "4180 Burnet Rd", "postal_code": "78756", "state": "TX" }, "id": "inrqi_addrxxxxxx" }, { "file": "upload_xxxxxxxxxxxx", "id": "inrqi_filexxxxxx" } ] }, "oneOf": [ { "description": "Fields that can be updated on an individual (KYC) verification. At least one field is required.", "properties": { "business_name": { "description": "Legal business name for a sole proprietor or single-member LLC.", "example": "Shine Time Auto Detailing", "type": "string" }, "business_structure": { "description": "Entity type for sole proprietors, such as `single_member_llc`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": "string" }, "business_tax_identification_number": { "description": "The business ID number of the company, as appropriate for the company's country. Examples are an Employer Identification Number (EIN) in the US, a Business Number in Canada, or a Company Number in the UK.", "example": "12-3456789", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "first_name": { "example": "Marcus", "type": "string" }, "last_name": { "example": "Webb", "type": "string" }, "personal_address": { "description": "Personal address for the individual.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`. An address in a [sanctioned country or region](/trust-and-safety/trust-safety-overview/sanctioned-countries) is rejected with the error code `address_country_sanctioned`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "requested_information": { "description": "Answers to items in `requested_information`. Each entry pairs the item `id` with one answer payload matching its `type`.", "items": { "properties": { "address": { "description": "Answer for `address` items.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`. An address in a [sanctioned country or region](/trust-and-safety/trust-safety-overview/sanctioned-countries) is rejected with the error code `address_country_sanctioned`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "document_number": { "description": "Identity number for an `id_document` answer.", "type": "string" }, "documents": { "description": "Answer for an `id_document` item: the same slot keys Create Verification takes, so the key names both the document and the side. Send every slot for the ID you are uploading — `PASSPORT` is `passport_front`; `ID_CARD`, `DRIVERS` and `RESIDENCE_PERMIT` take a front and a back. Each value is a direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "properties": { "drivers_back": { "description": "Back of the driver's license.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "drivers_front": { "description": "Front of the driver's license.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "id_card_back": { "description": "Back of the ID card.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "id_card_front": { "description": "Front of the ID card.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "passport_front": { "description": "Photo page of the passport.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_back": { "description": "Back of the residence permit.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_front": { "description": "Front of the residence permit.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "files": { "description": "Answer for a `files` item, optional supporting documents for `text_with_files`, or the document an item's `alternative_document_label` names — a list of pages, first page first. Each entry is a direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "items": { "description": "A direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "id": { "description": "Item ID from `requested_information`.", "example": "inrqi_xxxxxxxxxxxxxx", "type": "string" }, "issuing_country": { "description": "Two-letter ISO 3166-1 issuing country for an `id_document` answer.", "type": "string" }, "value": { "description": "Answer for `text`, `text_with_files`, `date`, `phone`, and `select` items, and the chosen document type for a `file` item that lists `options`.", "example": "Mobile detailing only; no retail storefront.", "type": "string" }, "value_type": { "description": "Whether `value` is raw input or a vault token.", "enum": [ "raw", "vault_token" ], "example": "raw", "type": "string" }, "values": { "description": "Every chosen option for a `select` item that accepts more than one answer, such as the countries an advertising certification covers. Use `value` for every other item.", "items": { "type": "string" }, "type": "array" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "tax_identification_number": { "description": "The government-issued ID number of the person being verified — the individual for a KYC verification, or the business representative for a KYB verification — as appropriate for their country. Examples are a Social Security Number (SSN) in the US, or a Social Insurance Number in Canada.", "example": "123456789", "type": "string" } }, "title": "UpdateIndividualVerification", "type": "object" }, { "description": "Fields that can be updated on a business entity (KYB) verification. At least one field is required.", "properties": { "business_address": { "description": "Business address.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`. An address in a [sanctioned country or region](/trust-and-safety/trust-safety-overview/sanctioned-countries) is rejected with the error code `address_country_sanctioned`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing", "type": "string" }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": "string" }, "business_tax_identification_number": { "description": "The business ID number of the company, as appropriate for the company's country. Examples are an Employer Identification Number (EIN) in the US, a Business Number in Canada, or a Company Number in the UK.", "example": "12-3456789", "type": "string" }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": "string" }, "date_of_birth": { "description": "Business representative's date of birth, formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "type": "string" }, "documents": { "description": "Company formation documents, each the ID of a file uploaded with Create File and not yet attached to anything else, prefixed `file_`. Send the ID once its `upload_status` is `ready`. Each file must be a PDF, JPEG, or PNG of up to 10MB. They are filed under the business's country, from `country`, `address`, or an earlier request. A document of a kind already on file is kept unless it was rejected, so a retried request does not add a second copy. The hosted session at `session_url` collects anything still missing.", "properties": { "articles_of_incorporation": { "description": "File ID of the articles of incorporation or organization, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "certificate_of_incorporation": { "description": "File ID of the certificate of incorporation or formation, prefixed `file_`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "first_name": { "description": "First name of the business representative.", "example": "Marcus", "type": "string" }, "incorporation_date": { "description": "Date the business was incorporated, formatted as `YYYY-MM-DD`. Cannot be in the future. Sent to the verification provider and returned in the response; `requested_information` asks for it while it is still missing.", "format": "date", "type": "string" }, "last_name": { "description": "Last name of the business representative.", "example": "Webb", "type": "string" }, "owners": { "description": "Owners of the business, up to 10 per request. Once the company details, the company documents, and the owners are in and every new owner's documents were sent, Create Verification sends the business for review: in the request that completes it, as soon as the last owner's documents finish sending in the background, or when called again after Update Verification. Owners can still be added, changed, or removed while the review waits on them.", "items": { "description": "An owner to add, change, or remove. Send `id` to change an owner already on the verification: new `roles` or `ownership_percentage`; corrected details such as `date_of_birth` or `first_name`, or `document_type` and `documents`, while the owner's verification is waiting on them (see `rejected_checks`). Send `id` with `remove` set to `true` to remove that owner. Without `id`, the entry adds an owner as it does on Create Verification. Owners left out are not changed.", "properties": { "address": { "description": "The new owner's home address, with `line1`, `city`, `state`, and `postal_code`.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`. An address in a [sanctioned country or region](/trust-and-safety/trust-safety-overview/sanctioned-countries) is rejected with the error code `address_country_sanctioned`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "country": { "description": "The new owner's country, as a two-letter ISO 3166-1 code.", "example": "US", "type": "string" }, "date_of_birth": { "description": "The new owner's date of birth, formatted as `YYYY-MM-DD`.", "example": "2026-01-01", "format": "date", "type": "string" }, "document_type": { "description": "Identity document in `documents`. Decides which slots to send: `id_card` → `id_card_front` + `id_card_back`; `drivers` → `drivers_front` + `drivers_back`; `residence_permit` → `residence_permit_front` + `residence_permit_back`; `passport` → `passport_front`. Every type also takes `selfie`.", "enum": [ "id_card", "drivers", "residence_permit", "passport" ], "example": "passport", "type": "string" }, "documents": { "description": "The owner's identity document and selfie, each the ID of a ready file uploaded with Create File and not yet attached to anything else, prefixed `file_`. Send every slot for `document_type` plus `selfie`. Document files can be a PDF, JPEG, or PNG and the selfie a JPEG or PNG, each up to 10MB. They're sent to the verification provider in the background: the owner reads `processing` until then, and `action_required`, with a `rejection_reason` on each document, if a file couldn't be used.", "properties": { "drivers_back": { "description": "File ID of the back of the driver's license. Required when `document_type` is `drivers`.", "type": "string" }, "drivers_front": { "description": "File ID of the front of the driver's license. Required when `document_type` is `drivers`.", "type": "string" }, "id_card_back": { "description": "File ID of the back of the ID card. Required when `document_type` is `id_card`.", "type": "string" }, "id_card_front": { "description": "File ID of the front of the ID card. Required when `document_type` is `id_card`.", "type": "string" }, "passport_front": { "description": "File ID of the passport's photo page. Required when `document_type` is `passport`.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_back": { "description": "File ID of the back of the residence permit. Required when `document_type` is `residence_permit`.", "type": "string" }, "residence_permit_front": { "description": "File ID of the front of the residence permit. Required when `document_type` is `residence_permit`.", "type": "string" }, "selfie": { "description": "File ID of a photo of the owner's face. Must be a JPEG or PNG. Required, except on Update Verification for an owner whose selfie already passed.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "email": { "description": "The new owner's email address.", "example": "marcus@shinetime.example", "type": "string" }, "first_name": { "description": "The new owner's first name.", "example": "Riley", "type": "string" }, "id": { "description": "An owner already on the verification, prefixed `own_`, from `owners`.", "example": "own_xxxxxxxxxxxxxx", "type": "string" }, "last_name": { "description": "The new owner's last name.", "example": "Owner", "type": "string" }, "ownership_percentage": { "description": "Share of the business the person owns, from 0 to 100. Across every owner it can't add up to more than 100.", "example": 40, "maximum": 100, "minimum": 0, "type": "number" }, "phone": { "description": "The new owner's phone number, with country code.", "example": "+xxxxxxxxxxx", "type": "string" }, "remove": { "description": "Set to `true` with `id` to remove that owner from the business. Takes no other fields. The owner's own verification is kept, so a reused owner can be added back with `verification_id` and a person you added by sending their details and documents again.", "example": true, "type": "boolean" }, "roles": { "description": "What the person is to the business: `ubo` for an ultimate beneficial owner, `director`, `representative` for someone who acts for the business, or `shareholder`. Required for a new owner.", "items": { "enum": [ "ubo", "director", "representative", "shareholder" ], "example": "ubo", "type": "string" }, "type": "array" }, "tax_identification_number": { "description": "The new owner's government-issued ID number, such as a Social Security Number in the US.", "example": "123456780", "type": "string" }, "verification_id": { "description": "ID of an `approved` individual verification to add as this owner, prefixed `idpf_`. It must be the account's own verification or a team member's. Takes only `roles` and `ownership_percentage` alongside it.", "example": "idpf_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "maxItems": 10, "type": "array" }, "place_of_incorporation": { "description": "State or region where the business is incorporated. Sent to the verification provider and returned in the response; `requested_information` asks for it while it is still missing.", "type": "string" }, "registration_number": { "description": "Number the business was registered under in its place of incorporation, such as a state file number in the US or a Company Number in the UK. Sent to the verification provider and returned in the response; `requested_information` asks for it while it is still missing.", "example": "0803486771", "type": "string" }, "requested_information": { "description": "Answers to items in `requested_information`. Each entry pairs the item `id` with one answer payload matching its `type`.", "items": { "properties": { "address": { "description": "Answer for `address` items.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`. An address in a [sanctioned country or region](/trust-and-safety/trust-safety-overview/sanctioned-countries) is rejected with the error code `address_country_sanctioned`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": "object" }, "document_number": { "description": "Identity number for an `id_document` answer.", "type": "string" }, "documents": { "description": "Answer for an `id_document` item: the same slot keys Create Verification takes, so the key names both the document and the side. Send every slot for the ID you are uploading — `PASSPORT` is `passport_front`; `ID_CARD`, `DRIVERS` and `RESIDENCE_PERMIT` take a front and a back. Each value is a direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "properties": { "drivers_back": { "description": "Back of the driver's license.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "drivers_front": { "description": "Front of the driver's license.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "id_card_back": { "description": "Back of the ID card.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "id_card_front": { "description": "Front of the ID card.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "passport_front": { "description": "Photo page of the passport.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_back": { "description": "Back of the residence permit.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "residence_permit_front": { "description": "Front of the residence permit.", "example": "file_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "files": { "description": "Answer for a `files` item, optional supporting documents for `text_with_files`, or the document an item's `alternative_document_label` names — a list of pages, first page first. Each entry is a direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "items": { "description": "A direct upload ID, or a `file_`-prefixed attachment ID to reuse an uploaded document.", "example": "file_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "id": { "description": "Item ID from `requested_information`.", "example": "inrqi_xxxxxxxxxxxxxx", "type": "string" }, "issuing_country": { "description": "Two-letter ISO 3166-1 issuing country for an `id_document` answer.", "type": "string" }, "value": { "description": "Answer for `text`, `text_with_files`, `date`, `phone`, and `select` items, and the chosen document type for a `file` item that lists `options`.", "example": "Mobile detailing only; no retail storefront.", "type": "string" }, "value_type": { "description": "Whether `value` is raw input or a vault token.", "enum": [ "raw", "vault_token" ], "example": "raw", "type": "string" }, "values": { "description": "Every chosen option for a `select` item that accepts more than one answer, such as the countries an advertising certification covers. Use `value` for every other item.", "items": { "type": "string" }, "type": "array" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "tax_identification_number": { "description": "The government-issued ID number of the person being verified — the individual for a KYC verification, or the business representative for a KYB verification — as appropriate for their country. Examples are a Social Security Number (SSN) in the US, or a Social Insurance Number in Canada.", "example": "123456789", "type": "string" } }, "title": "UpdateBusinessVerification", "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "Address on the verification profile. `null` when no address is set.", "properties": { "city": { "example": "Austin", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "First line of the street address.", "example": "4180 Burnet Rd", "type": "string" }, "line2": { "description": "Second line of the street address.", "example": "Suite 2", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal or ZIP code.", "example": "78756", "type": [ "string", "null" ] }, "state": { "description": "State, province, or region code, for example `CA`.", "example": "TX", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "business_name": { "description": "Legal business name.", "example": "Shine Time Auto Detailing, LLC", "type": [ "string", "null" ] }, "business_structure": { "description": "Legal entity structure of the business, such as `private_corporation` or `sole_proprietorship`. Supported values vary by country of incorporation — see [Business structures](/developer/verification/business-structures).", "example": "sole_proprietorship", "type": [ "string", "null" ] }, "country": { "description": "Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.", "example": "US", "type": [ "string", "null" ] }, "created_at": { "description": "When the verification profile was created, as an ISO 8601 timestamp.", "example": "2026-06-01T12:00:00.000Z", "type": "string" }, "date_of_birth": { "description": "Formatted as `YYYY-MM-DD`.", "example": "1990-01-01", "type": [ "string", "null" ] }, "email": { "description": "Email address on the verification profile.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "first_name": { "example": "Marcus", "type": [ "string", "null" ] }, "id": { "description": "Verification profile ID, prefixed `idpf_`.", "example": "idpf_xxxxxxxxxxxx", "type": "string" }, "incorporation_date": { "description": "Date the business was incorporated, formatted as `YYYY-MM-DD`, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "2021-03-15", "type": [ "string", "null" ] }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "owners": { "description": "Owners of the business and the progress of each one's own verification. Empty for individual verifications.", "items": { "properties": { "date_of_birth": { "description": "The owner's date of birth on file, formatted as `YYYY-MM-DD`.", "example": "1985-06-01", "type": [ "string", "null" ] }, "first_name": { "example": "Riley", "type": [ "string", "null" ] }, "id": { "description": "Owner ID, prefixed `own_`. Send it in Update Verification's `owners` to change or remove the owner, including one added in the hosted session.", "example": "own_xxxxxxxxxxxxxx", "type": "string" }, "last_name": { "example": "Owner", "type": [ "string", "null" ] }, "ownership_percentage": { "description": "Share of the business the person owns, from 0 to 100.", "example": 60, "type": [ "number", "null" ] }, "rejected_checks": { "description": "What the provider rejected when the owner's verification was sent back: `details` (their name, date of birth, or other details don't match their ID), `identity_document`, or `selfie`. Fix only these with Update Verification. Empty otherwise.", "items": { "enum": [ "details", "identity_document", "selfie" ], "example": "details", "type": "string" }, "type": "array" }, "required_documents": { "description": "The owner's documents and their progress. Empty for an owner added with `verification_id`.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "pending_upload", "type": "string" } }, "type": "object" }, "type": "array" }, "roles": { "description": "What the person is to the business.", "items": { "enum": [ "ubo", "director", "representative", "shareholder" ], "example": "ubo", "type": "string" }, "type": "array" }, "status": { "description": "Where the owner's own verification stands, in the same states as `status`. `action_required` when their documents need sending again.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "not_started", "type": "string" } }, "required": [ "id", "roles", "ownership_percentage", "first_name", "last_name", "date_of_birth", "status", "required_documents", "rejected_checks" ], "type": "object" }, "type": "array" }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "type": [ "string", "null" ] }, "place_of_incorporation": { "description": "State or region where the business is incorporated, as on file for the business verification. Business verifications only; `null` until it is sent.", "example": "Delaware", "type": [ "string", "null" ] }, "registration_number": { "description": "Number the business was registered under in its place of incorporation, such as a state file number in the US or a Company Number in the UK. Business verifications only; as on file for the business verification, or `null` until it is sent.", "example": "7654321", "type": [ "string", "null" ] }, "requested_information": { "description": "What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted. For a business verification created with `documents` or `owners`, this includes the company details and documents still missing before it can be sent for review; each owner's documents are listed under that owner.", "items": { "properties": { "action_url": { "description": "URL for a related action, such as completing liveness verification or viewing a payment. Absent when no action is available.", "type": "string" }, "alternative_document_label": { "description": "A document that answers this item in place of `value`, such as an IRS EIN letter when the EIN could not be matched. Send its pages in `files`, with or without a corrected `value`. Absent when only `value` is accepted.", "example": "IRS EIN letter (CP 575 or 147C) that shows your business's legal name and your EIN on the same letter", "type": "string" }, "details_label": { "description": "Follow-up prompt shown with this requirement.", "type": "string" }, "details_required": { "description": "Whether the follow-up response is required when visible.", "type": "boolean" }, "details_visible_for": { "description": "Selected option values that make the follow-up prompt visible.", "items": { "type": "string" }, "type": "array" }, "errors": { "description": "Present after a rejected submission.", "items": { "properties": { "code": { "description": "Stable error code.", "example": "document_not_readable", "type": "string" }, "reason": { "description": "Why it was rejected.", "example": "The uploaded image was too blurry to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Requested information item ID, prefixed `inrqi_`.", "example": "inrqi_xxxxxxxxxxx", "type": "string" }, "label": { "description": "Instruction to show the user. Carries the reviewer's note verbatim when there is one.", "example": "Bank Statement or a check for account ending in 4242", "type": "string" }, "optional": { "description": "`true` when the item can be skipped.", "example": true, "type": "boolean" }, "options": { "description": "The values `value` may take on a `select` item. On an `id_document` item these are the ID types accepted, and the chosen one decides which `documents` slots to send. Absent when the item has no choice to make.", "items": { "example": "sole_proprietorship", "type": "string" }, "type": "array" }, "requirement": { "description": "What is needed: a document name such as `bank_statement`, or a field key such as `ssn` or `identity_document`. Handle unrecognized values by `type`.", "example": "bank_statement", "type": "string" }, "response_type": { "description": "Optional native input format for a text response.", "enum": [ "yes_no", "yes_no_na", "date", "url", "number", "tel" ], "example": "yes_no", "type": "string" }, "selection_mode": { "description": "Whether a question with `options` accepts one value or multiple values.", "enum": [ "single", "multiple" ], "example": "single", "type": "string" }, "supporting_documents": { "description": "Documents supplied with the requirement for context.", "items": { "$ref": "#/components/schemas/File" }, "type": "array" }, "supporting_files_explanation_allowed": { "description": "Whether a written explanation may replace required supporting files.", "type": "boolean" }, "supporting_files_required": { "description": "Whether this requirement also needs supporting files.", "type": "boolean" }, "supporting_files_visible_for": { "description": "Selected option values that make the supporting-file input visible.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), `text_with_files` (send `value` and optional `files`), `address` (send `address`), or `liveness` (open `action_url`, then send `value` as `true` after completion).", "example": "files", "type": "string" } }, "required": [ "id", "requirement", "type", "label" ], "type": "object" }, "type": "array" }, "required_documents": { "description": "Documents for a document-upload verification and their progress. Present only on individual verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.", "items": { "properties": { "document": { "description": "Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.", "example": "id_card_front", "type": "string" }, "rejection_reason": { "description": "Why the previous submission was rejected, when the provider requested new documents or declined the verification.", "example": "Document image was too blurry to read.", "type": [ "string", "null" ] }, "status": { "description": "`pending_upload` until the document has been relayed for review; `submitted` afterwards.", "enum": [ "pending_upload", "submitted" ], "example": "pending_upload", "type": "string" } }, "type": "object" }, "type": "array" }, "session_url": { "description": "Hosted verification session URL for the user to complete identity checks. Expires 7 days after creation.", "example": "https://sumsub.com/session/abc", "type": [ "string", "null" ] }, "status": { "description": "Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.", "enum": [ "not_started", "pending", "processing", "manual_review", "approved", "rejected", "action_required" ], "example": "action_required", "type": "string" }, "updated_at": { "description": "When the verification profile was last updated, as an ISO 8601 timestamp.", "example": "2026-06-02T12:00:00.000Z", "type": "string" } }, "required": [ "owners" ], "type": "object" } } }, "description": "verification updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "the request body has unsupported fields" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required identity-write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no verification with that ID is visible to the credential" } }, "security": [ { "bearerAuth": [ "identity:write" ] } ], "summary": "Update Verification", "tags": [ "Verifications" ], "x-whop-credentials": [ "account_api_key", "account_token", "account_user_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/waitlist_entries": { "get": { "description": "Lists the waitlist signups you can see. `waitlist_entry:read` returns your own signups, and `plan:waitlist:read` returns signups to the seller accounts you are authorized on; with both, you get both sets. Signups submitted on behalf of an account are not in this list; pass `buyer_account_id` to list them instead, which needs `waitlist_entry:read` on that account. Account credentials see the signups submitted to their own account, and pass their own account as `buyer_account_id` to see the ones it submitted.", "operationId": "listWaitlistEntries", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "Only return signups for this variant, prefixed `plan_`.", "in": "query", "name": "variant_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return signups submitted to this seller account, prefixed `biz_`.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return signups for variants on this product, prefixed `prod_`.", "in": "query", "name": "product_id", "required": false, "schema": { "type": "string" } }, { "description": "List the signups submitted on behalf of this account, prefixed `biz_`, instead of your own and seller signups. Requires `waitlist_entry:read` on the account. The other filters still apply.", "in": "query", "name": "buyer_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return signups in this state. Canceled signups are returned only when `status` is `canceled`.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "approved", "denied", "canceled" ], "type": "string" } }, { "description": "Search signups by the user's name or username, or the name of the account they were submitted on behalf of. An account ID, prefixed `biz_`, matches signups submitted on behalf of that account, and an exact email address matches that user's signups.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Only return signups submitted at or before this ISO 8601 timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date_time", "type": "string" } }, { "description": "Only return signups submitted at or after this ISO 8601 timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date_time", "type": "string" } }, { "description": "The field to sort results by. Defaults to `created_at`.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at" ], "type": "string" } }, { "description": "The sort direction for results. Defaults to descending.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WaitlistEntry" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "has_next_page", "has_previous_page", "start_cursor", "end_cursor" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "own signups only" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid status" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "not signed in" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown plan" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Waitlist Entries", "tags": [ "Waitlist Entries" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Joins a free waitlist variant as the authenticated user, or on behalf of an account with `buyer_account_id`. Requires `waitlist_entry:create`, on that account when one is given. Joining again returns the existing pending signup, or the approved one while its membership is valid. Paid variants are rejected; joining collects no payment method and grants no membership.", "operationId": "createWaitlistEntry", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "buyer_account_id": { "description": "The account to join on behalf of, prefixed `biz_`. Leave it out to join as yourself. Required with an account credential, which passes its own account and records the account's owner as the user who joined.", "type": "string" }, "custom_field_responses": { "description": "Answers to the variant's checkout questions. Every required question must be answered.", "items": { "properties": { "answer": { "description": "The buyer's answer.", "type": "string" }, "custom_field_id": { "description": "The checkout question being answered, prefixed `field_`.", "type": "string" } }, "required": [ "custom_field_id", "answer" ], "type": "object" }, "type": "array" }, "metadata": { "description": "Custom key-value pairs to store on the signup. Max 50 keys, 100 chars per key, 500 chars per string value. Ignored when the request returns an existing signup.", "type": "object" }, "variant_id": { "description": "The free waitlist variant to join, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "variant_id" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistEntry" } } }, "description": "joined" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "paid plan refused" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "not signed in" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown plan" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create Waitlist Entry", "tags": [ "Waitlist Entries" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/waitlist_entries/approve_all": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Queues approval of every pending signup for an account, optionally narrowed to a variant. Requires `plan:waitlist:manage`. Paid signups may charge saved payment methods. Approval runs asynchronously: list signups with `status` set to `pending` to follow progress, and retrieve a signup to read its outcome. Signups created after this request are excluded.", "operationId": "approveAllWaitlistEntries", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The seller account whose pending signups to approve, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "variant_id": { "description": "Only approve signups for this variant, prefixed `plan_`. Omit to include every waitlist variant on the account.", "type": "string" } }, "required": [ "account_id" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The seller account whose signups were queued, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "queued": { "description": "Whether any pending signups were queued for approval. `false` when there were none.", "example": true, "type": "boolean" }, "variant_id": { "description": "The variant the request was narrowed to, prefixed `plan_`, or `null` when every waitlist variant on the account was included.", "example": null, "type": [ "string", "null" ] } }, "required": [ "account_id", "variant_id", "queued" ], "type": "object" } } }, "description": "approval queued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "not signed in" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [] } ], "summary": "Approve All Waitlist Entries", "tags": [ "Waitlist Entries" ] }, "x-whop-surface": "native" }, "/waitlist_entries/{id}": { "get": { "description": "Retrieves your own signup or one submitted on behalf of an account you hold `waitlist_entry:read` on, or one submitted to an account you can read, with `plan:waitlist:read`.", "operationId": "retrieveWaitlistEntry", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistEntry" } } }, "description": "signup" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "not signed in" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "not visible" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve Waitlist Entry", "tags": [ "Waitlist Entries" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Waitlist signup ID, prefixed `entry_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/waitlist_entries/{id}/approve": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Waitlist signup ID, prefixed `entry_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Queues approval of a pending signup. Requires `plan:waitlist:manage` on its seller account. Paid signups may charge their saved payment method. Returns the signup's current state; retrieve it to read `status` and `approval_failure_reason` after processing.", "operationId": "approveWaitlistEntry", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistEntry" } } }, "description": "current signup state" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "not signed in" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown signup" }, "409": { "$ref": "#/components/responses/Conflict", "description": "not pending" } }, "security": [ { "bearerAuth": [] } ], "summary": "Approve Waitlist Entry", "tags": [ "Waitlist Entries" ] }, "x-whop-surface": "native" }, "/waitlist_entries/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Waitlist signup ID, prefixed `entry_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Withdraws a pending signup: your own, or one submitted on behalf of an account you hold `waitlist_entry:cancel` on. Requires `waitlist_entry:cancel`, on that account for an account's signup. Does not cancel an approved membership.", "operationId": "cancelWaitlistEntry", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistEntry" } } }, "description": "current signup state" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "not signed in" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown signup" }, "409": { "$ref": "#/components/responses/Conflict", "description": "not pending" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancel Waitlist Entry", "tags": [ "Waitlist Entries" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "oauth_token" ] }, "x-whop-surface": "native" }, "/waitlist_entries/{id}/deny": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Waitlist signup ID, prefixed `entry_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Denies a pending signup. Requires `plan:waitlist:manage` on its seller account.", "operationId": "denyWaitlistEntry", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistEntry" } } }, "description": "current signup state" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "not signed in" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "missing write scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown signup" }, "409": { "$ref": "#/components/responses/Conflict", "description": "not pending" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deny Waitlist Entry", "tags": [ "Waitlist Entries" ] }, "x-whop-surface": "native" }, "/webhooks": { "get": { "description": "Returns a paginated list of webhook endpoints configured for an account, ordered by most recently created.", "operationId": "listWebhooks", "parameters": [ { "description": "The unique identifier of the account to list webhooks for.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return webhooks attached to this app. Omit to list the account's own webhooks.", "in": "query", "name": "app_id", "required": false, "schema": { "type": "string" } }, { "description": "Also return webhooks attached to the account's apps, not just the account's own. Cannot be combined with `app_id`.", "in": "query", "name": "include_app_webhooks", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return webhooks whose endpoint is currently failing — every delivery since the current failure streak began has been rejected. Clears as soon as a delivery succeeds.", "in": "query", "name": "has_failures", "required": false, "schema": { "type": "boolean" } }, { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of results to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Return results before this cursor. Use `page_info.start_cursor` from the previous response to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookListItem" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": null, "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": "WyJjdXJzb3IiLDFd", "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "webhooks listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing account_id" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no account with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "List Webhooks", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a webhook endpoint that receives event notifications via HTTP POST.", "operationId": "createWebhook", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version_date": { "description": "The dated API version (Api-Version-Date) to pin this webhook's payloads to. Omit to leave the webhook unpinned, tracking the current payload shape.", "example": "2026-10-27-3", "type": [ "string", "null" ] }, "child_resource_events": { "description": "Whether to send events for child resources. For example, if the webhook is created for an account, enabling this sends events only from its connected accounts.", "example": true, "type": "boolean" }, "enabled": { "description": "Whether or not the webhook is enabled. Defaults to `true`.", "example": true, "type": "boolean" }, "events": { "description": "The events to send the webhook for, in dot form (for example `payment.succeeded`).", "items": { "enum": [ "account.updated", "account.financing_approved", "account.financing_denied", "account.financing_disabled", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "membership.updated", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "financial_activity.funds_available", "transfer.created", "transfer.completed", "transfer.failed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "course_lesson_interaction.completed", "domain.created", "domain.updated", "domain.deleted", "payout_method.created", "verification.succeeded", "identity_profile.approved", "identity_profile.rejected", "identity_profile.needs_action", "identity_profile.updated", "payout_account.status_updated", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "member.updated", "ad_campaign.created", "ad_campaign.payment_failed", "ad_campaign.updated", "ad_campaign.events", "ad_group.created", "ad_group.updated", "ad.created", "ad.updated", "app_installation.created", "app_installation.deleted", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "payment.requires_action", "dispute.created", "dispute.updated", "refund.created", "refund.updated", "dispute_alert.created", "membership.cancel_at_period_end_changed" ], "example": "payment.succeeded", "type": "string" }, "type": "array" }, "resource_id": { "description": "The account or app to create the webhook for. Defaults to the current account.", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "title": { "description": "A label for the webhook, shown in the dashboard. Up to 255 characters.", "example": "Production", "maxLength": 255, "type": [ "string", "null" ] }, "url": { "description": "The URL to send the webhook to.", "example": "https://example.com/hooks", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "webhook created" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "api_version is no longer an input" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no resource with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Create Webhook", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "x-whop-surface": "native" }, "/webhooks/{id}": { "delete": { "description": "Permanently deletes a webhook endpoint. To stop deliveries without deleting it, set `enabled` to `false` with `PATCH /webhooks/:id`.", "operationId": "deleteWebhook", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always `true`: the resource was deleted.", "example": true, "type": "boolean" }, "id": { "description": "The ID of the deleted resource.", "example": "hook_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "deleted", "id" ], "type": "object" } } }, "description": "webhook deleted" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Delete Webhook", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "get": { "description": "Retrieves the details of an existing webhook.", "operationId": "retrieveWebhook", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "legacy webhook testable events use dot-form names" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Retrieve Webhook", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Updates a webhook endpoint's URL, subscribed events, pinned payload version, or enabled state.", "operationId": "updateWebhook", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_version_date": { "description": "The dated API version (Api-Version-Date) to pin this webhook's payloads to. Only valid for `v1` webhooks. Omit to leave the current pin unchanged, or pass `null` to unpin and track the current payload shape.", "example": "2026-10-27-3", "type": [ "string", "null" ] }, "child_resource_events": { "description": "Whether or not to send events for child resources.", "example": true, "type": "boolean" }, "enabled": { "description": "Whether or not the webhook is enabled.", "example": false, "type": "boolean" }, "events": { "description": "The events to send the webhook for, in dot form (for example `payment.succeeded`).", "items": { "enum": [ "account.updated", "account.financing_approved", "account.financing_denied", "account.financing_disabled", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "membership.updated", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "financial_activity.funds_available", "transfer.created", "transfer.completed", "transfer.failed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "course_lesson_interaction.completed", "domain.created", "domain.updated", "domain.deleted", "payout_method.created", "verification.succeeded", "identity_profile.approved", "identity_profile.rejected", "identity_profile.needs_action", "identity_profile.updated", "payout_account.status_updated", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "member.updated", "ad_campaign.created", "ad_campaign.payment_failed", "ad_campaign.updated", "ad_campaign.events", "ad_group.created", "ad_group.updated", "ad.created", "ad.updated", "app_installation.created", "app_installation.deleted", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "payment.requires_action", "dispute.created", "dispute.updated", "refund.created", "refund.updated", "dispute_alert.created", "membership.cancel_at_period_end_changed" ], "example": "payment.failed", "type": "string" }, "type": "array" }, "title": { "description": "A label for the webhook, shown in the dashboard. Up to 255 characters. Pass `null` or an empty string to remove it.", "example": "Staging", "maxLength": 255, "type": [ "string", "null" ] }, "url": { "description": "The URL to send the webhook to.", "example": "https://example.com/shine-time/whop-updated", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "description": "webhook updated" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "api_version is no longer an input" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Update Webhook", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "x-whop-surface": "native" }, "/webhooks/{id}/deliveries": { "get": { "description": "Returns a paginated list of delivery attempts for a webhook, ordered by most recent first. Includes the request payload, response body, response code, and timing for each attempt. Filtered queries use a bounded read budget, so a page may be partial or empty. Continue with `page_info.end_cursor` while `page_info.has_next_page` is `true`.", "operationId": "listWebhookDeliveries", "parameters": [ { "description": "Number of results to return from the start of the range.", "in": "query", "name": "first", "required": false, "schema": { "default": 50, "maximum": 100, "type": "integer" } }, { "description": "Return results after this cursor. Use `page_info.end_cursor` from the previous response to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Only deliveries sent at or after this ISO 8601 timestamp. Deliveries are retained for 30 days.", "in": "query", "name": "sent_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only deliveries sent at or before this ISO 8601 timestamp.", "in": "query", "name": "sent_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only deliveries of these event types. Repeat the parameter to pass several.", "in": "query", "name": "events", "required": false, "schema": { "items": { "enum": [ "account.updated", "account.financing_approved", "account.financing_denied", "account.financing_disabled", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "membership.updated", "entry.created", "entry.approved", "entry.denied", "entry.deleted", "export.completed", "export.failed", "setup_intent.requires_action", "setup_intent.succeeded", "setup_intent.canceled", "ledger_account.funds_available", "swap.completed", "deposit.succeeded", "financial_activity.funds_available", "transfer.created", "transfer.completed", "transfer.failed", "withdrawal.created", "withdrawal.updated", "withdrawal.reversed", "payout.created", "payout.updated", "payout.reversed", "card_transaction.created", "card_transaction.updated", "card_transaction.completed", "card_transaction.declined", "card_transaction.reversed", "card.created", "card.updated", "card.frozen", "card.canceled", "card_application.created", "card_application.updated", "card_application.approved", "card_application.denied", "course_lesson_interaction.completed", "domain.created", "domain.updated", "domain.deleted", "payout_method.created", "verification.succeeded", "identity_profile.approved", "identity_profile.rejected", "identity_profile.needs_action", "identity_profile.updated", "payout_account.status_updated", "payment.authorized", "payment.canceled", "resolution_center_case.created", "resolution_center_case.updated", "resolution_center_case.decided", "product.created", "product.updated", "product.deleted", "product.published", "product.unpublished", "plan.created", "plan.updated", "plan.deleted", "shipment.created", "shipment.updated", "member.created", "member.updated", "ad_campaign.created", "ad_campaign.payment_failed", "ad_campaign.updated", "ad_campaign.events", "ad_group.created", "ad_group.updated", "ad.created", "ad.updated", "app_installation.created", "app_installation.deleted", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "payment.requires_action", "dispute.created", "dispute.updated", "refund.created", "refund.updated", "dispute_alert.created", "membership.cancel_at_period_end_changed", "membership.went_valid", "membership.went_invalid", "membership.metadata_updated", "resolution.created", "resolution.updated", "resolution.decided", "payment.affiliate_reward_created", "membership.experience_claimed", "app_membership.went_valid", "app_membership.went_invalid", "app_payment.created", "app_payment.succeeded", "app_payment.failed", "app_payment.pending", "app_payment.requires_action", "app_membership.cancel_at_period_end_changed" ], "example": "payment.succeeded", "type": "string" }, "type": "array" } }, { "description": "Only deliveries with this outcome: `success` for a 2xx response, `error` otherwise.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "success", "error" ], "type": "string" } }, { "description": "Only deliveries triggered by this resource.", "in": "query", "name": "resource_id", "required": false, "schema": { "example": "pay_xxxxxxxxxxxxx", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "example": null, "type": [ "string", "null" ] } }, "required": [ "end_cursor", "start_cursor", "has_next_page", "has_previous_page" ], "type": "object" } }, "required": [ "data", "page_info" ], "type": "object" } } }, "description": "deliveries listed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "invalid filter value" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "List Deliveries", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "x-whop-surface": "native" }, "/webhooks/{id}/deliveries/{delivery_id}/replay": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Delivery ID, prefixed `whdel_`, from the List Deliveries endpoint.", "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Re-sends the exact payload of a past delivery to the webhook's current URL and returns the delivery result. The replay keeps the original `webhook-id` unless you pass `regenerate_id`, so consumers that deduplicate on it can drop events they already processed. Only available for enabled webhooks on API version `v1`; deliveries are retained for 30 days.", "operationId": "replayWebhookDelivery", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "regenerate_id": { "description": "Re-send the delivery under a freshly generated `webhook-id` (in both the envelope and the signed headers) instead of the original one. Defaults to false. Use this when your endpoint deduplicates on `webhook-id` and you want it to process the replay as a new message.", "example": true, "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "example": { "body": "OK", "status": 200, "success": true }, "properties": { "body": { "description": "The body your endpoint returned for the replayed request, as raw text. Empty when the endpoint could not be reached.", "example": "OK", "type": "string" }, "status": { "description": "The HTTP response code your endpoint returned for the replayed request, or 0 when it could not be reached (timeout, DNS, or connection failure).", "example": 200, "type": "integer" }, "success": { "description": "Whether your endpoint acknowledged the replay with a 2xx response.", "example": true, "type": "boolean" } }, "required": [ "status", "body", "success" ], "type": "object" } } }, "description": "delivery replayed" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "webhook is not on API version v1" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no delivery with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Replay Delivery", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "x-whop-surface": "native" }, "/webhooks/{id}/replay": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Re-sends the webhook's past deliveries within a time window, optionally limited to specific events or to failed deliveries. Use it to recover events your endpoint missed. The replay runs asynchronously and nothing about it is stored: each re-send appears as a new entry in the webhook's delivery log. Each matching message is re-sent once, with its original `webhook-id` unless you pass `regenerate_ids`. Only available for enabled webhooks on API version `v1`; deliveries are retained for 30 days.", "operationId": "replayWebhook", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "events": { "description": "Only replay these event types, in dot form (for example `payment.succeeded`). Omit to include every event.", "items": { "type": "string" }, "type": "array" }, "failed_only": { "description": "Only replay messages whose most recent delivery attempt in the window failed. Defaults to false. Best-effort: a message whose attempts span processing batches can still be re-sent — replays keep the original `webhook-id` by default, so consumers that deduplicate are unaffected.", "example": true, "type": "boolean" }, "regenerate_ids": { "description": "Re-send each replayed message under a freshly generated `webhook-id` (in both the envelope and the signed headers) instead of its original one. Defaults to false. Use this when your endpoint deduplicates on `webhook-id` and you want it to process the replays as new messages.", "example": true, "type": "boolean" }, "sent_after": { "description": "Start of the delivery window to replay, as an ISO 8601 timestamp. Clamped to the 30-day delivery retention.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "sent_before": { "description": "End of the delivery window to replay, as an ISO 8601 timestamp. Defaults to now.", "type": "string" } }, "required": [ "sent_after" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "example": { "queued": true }, "properties": { "queued": { "description": "Whether the replay was accepted. Watch the webhook's delivery log for the re-sends.", "example": true, "type": "boolean" } }, "required": [ "queued" ], "type": "object" } } }, "description": "replay queued" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing sent_after" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Replay Deliveries in a Range", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "x-whop-surface": "native" }, "/webhooks/{id}/test": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Sends a sample payload for the given event to the webhook's URL and returns the delivery result.", "operationId": "testWebhook", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "event": { "description": "The event to test the webhook for, in dot form (for example `payment.succeeded`).", "example": "payment.succeeded", "type": "string" } }, "required": [ "event" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "The body of the webhook response.", "example": "OK" }, "status": { "description": "The HTTP response code of this request.", "example": 200, "type": "integer" }, "success": { "description": "Whether or not the webhook test was successful.", "example": true, "type": "boolean" } }, "required": [ "status", "body", "success" ], "type": "object" } } }, "description": "test event sent" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "missing event" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential lacks the required webhook-management scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no webhook with that ID" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "developer:manage_webhook" ] } ], "summary": "Send Test Event", "tags": [ "Webhooks" ], "x-whop-credentials": [ "account_api_key", "app_api_key", "account_token", "account_user_token" ] }, "x-whop-surface": "native" } }, "servers": [ { "description": "Production Whop API", "url": "https://api.whop.com/api/v1" }, { "description": "Sandbox Whop API", "url": "https://sandbox-api.whop.com/api/v1" } ], "tags": [ { "description": "An Account represents a person or business on Whop that can have its own profile, wallet, and account-scoped settings. Use accounts for customers, creators, merchants, sellers, or connected businesses your integration supports.\n\nUse the Accounts API to create accounts, list accounts visible to your credentials, retrieve or update an account, suspend or delete a connected account managed by your platform, and retrieve the account associated with the current API key.\n", "name": "Accounts", "x-whop-summary": "A business on Whop: profile, wallet, capabilities, settings." }, { "description": "A User represents a person on Whop. Users have a public profile and can buy products, join accounts, and access experiences.\n\nUse the Users API to search for users, retrieve or update profiles, and check whether a user has access to an account, product, or experience.\n", "name": "Users", "x-whop-summary": "A person on Whop: profile and connected identities." }, { "description": "A Member is one buyer's relationship with an account: one record per customer, however many memberships they hold. It tracks whether they have joined or left, their access level, and when they last opened the account's content.\n\nUse the Members API to list and search an account's members, retrieve a single member, and read a member's activity log. Member rows are created and maintained by the membership lifecycle; to grant or revoke access, work with memberships instead.\n", "name": "Members", "x-whop-summary": "One buyer's relationship with an account, across all their purchases." }, { "description": "A Team Member is a member of an account's team: the link between a user and an account, carrying the role that controls what they can do. Roles are either system roles (like `admin` or `moderator`) or `custom` roles managed from the dashboard.\n\nUse the Team Members API to list an account's team, add a user to the team with a system role, change a member's role, and remove members. Adding a user who has not yet accepted sends an invitation instead.\n", "name": "Team Members", "x-whop-summary": "An account's team members and the roles that scope their access." }, { "description": "An External Account represents an account on another platform linked to a Whop account or user, such as a Facebook page, Instagram account, TikTok account, or Klaviyo account. You connect it through OAuth or an API key, or Whop creates it for you. A connected social profile lets Whop run [ads](/api-reference/beta/ads/ad) under that profile's identity and promote its existing posts. External account IDs are prefixed `sacc_`.\n\nUse the External Accounts API to list connected accounts, [connect a profile through OAuth](/api-reference/beta/external-accounts/connect-an-external-account), [create a Whop-managed Facebook page or TikTok account, or connect a Klaviyo account with its API key](/api-reference/beta/external-accounts/create-an-external-account), disconnect an external account, list a connected profile's posts or a Facebook page's lead forms, and manage the creators an Instagram account runs partnership ads with.\n", "name": "External Accounts", "x-whop-summary": "Accounts on other platforms linked to an account or user." }, { "description": "Social Accounts is the former public name for External Accounts. Existing integrations can keep calling these deprecated endpoints while they migrate; every response points to the matching External Accounts endpoint.\n\nUse the External Accounts API for all new integrations. External account IDs keep their `sacc_` prefix, and the underlying resource is unchanged.\n", "name": "Social Accounts", "x-whop-summary": "Deprecated compatibility endpoints for external accounts." }, { "description": "A Payment is one charge against a buyer, for one or more variants. Create an on-session payment with a `confirmation_token` for the method the buyer selected, or an off-session payment with an existing member's stored payment method.\n\nUse the Payments API to charge buyers, list and retrieve payments, and refund, void, capture, or retry them. Collection runs in the background, so the create response is not the outcome. Poll [Retrieve status](/api-reference/beta/payments/retrieve-payment-status) for how far the payment has gone and, while it is `requires_action`, what the buyer must do next: follow a redirect, complete 3D Secure, display transfer instructions, or link a bank account. Update the payment's `return_url` to change where they land afterwards, up until they come back.\n", "name": "Payments", "x-whop-summary": "A charge against a buyer, and the step they still owe." }, { "description": "An Invoice is a receipt with an invoice number. Create a draft from variant-backed items, set its recipient and due date, and edit it until it is sent. Its `pay_` ID is also the payment ID when collected.\n\nDraft creation does not create access or charge the buyer. The recipient's contact details live on the account's member. Financial fields and caller metadata can only be edited in draft.\n", "name": "Invoices", "x-whop-summary": "A payment request that keeps the same receipt from draft through collection." }, { "description": "A Confirmation Token is a single-use, short-lived reference to a payment method and billing details collected from a buyer. Its response never returns the underlying payment credential.\n\nWhop Elements mint the token in your buyer-facing collection flow and hand you its `ctok_` ID to send to the Payments API from your server. Retrieve a token to display its payment method and billing preview or check whether it is still usable.\n", "name": "Confirmation Tokens", "x-whop-summary": "A short-lived reference to payment details collected from a buyer." }, { "description": "A Payment Quote prices a purchase exactly as a payment for it will be charged: the same line pricing, promo code, and tax, for a buyer located by the address, country, or IP address you send. A quote is priced once, can be consumed by one payment, and expires.\n\nUse the Payment Quotes API to show a buyer the total, tax, and currency before they pay, then pass the quote's `id` as `quote_id` when you create the payment to charge exactly that quote. Quote again whenever the cart, promo code, or address changes.\n", "name": "Payment Quotes", "x-whop-summary": "A purchase priced before it is paid: its lines, promo code and tax." }, { "description": "A Setup Intent saves a buyer's payment method for later without taking money now. Create one from a confirmation token the payment elements collected in setup mode, or from a payment method already on file to re-verify it. It runs the same collection flow a payment does, so the buyer may still owe a step: 3D Secure on a card, a hosted enrollment, or linking a bank account.\n\nThe create response is the setup intent as created, not its outcome. Hand its `client_secret` to the elements' `handleNextAction`, or poll [Retrieve status](/api-reference/beta/setup-intents/retrieve-setup-status) for how far the setup has gone and what is outstanding. Once it reaches `succeeded`, `payment_method_id` names the saved method and Create Payment charges it.\n", "name": "Setup Intents", "x-whop-summary": "Saving a buyer's payment method without charging it." }, { "description": "A Refund is one full or partial reversal of a payment, issued with [Refund Payment](/api-reference/beta/payments/refund-payment). It records how much moved, through which provider, and whether it succeeded.\n\nUse the Refunds API to list the refunds on a payment or across an account, and to retrieve a single refund.\n", "name": "Refunds", "x-whop-summary": "Money returned to a buyer from a payment." }, { "description": "A Resolution Center Case is opened by a buyer when something is wrong with a purchase, such as an unwanted renewal, an item that never arrived, or a charge they don't recognize. It is the step before a chargeback: the buyer and merchant work it out directly, and Whop decides the case if they can't.\n\nUse the Resolution Center Cases API from either side: as the buyer, open, reply to, appeal, or withdraw a case; as the merchant, accept it (refunding the payment), deny it, or ask the buyer for more information.\n", "name": "Resolution Center Cases", "x-whop-summary": "File or respond to a case against a payment, as the buyer or the merchant." }, { "description": "A Dispute alert is an early warning from a card issuer that a settled payment is being questioned, ahead of any chargeback. `type` separates fraud reports (`early_fraud_warning`), pre-dispute notices (`dispute_alert`), and Visa RDR cases the network already closed by refunding (`rapid_dispute_resolution`).\n\nUse the Dispute alerts API to list alerts for an account, filter them by type or payment, and read `actionable` to see whether refunding can still avoid the chargeback.\n", "name": "Dispute alerts", "x-whop-summary": "Issuer warnings that arrive before a chargeback does." }, { "description": "A Dispute is a chargeback a customer files against a payment through their bank, or an inquiry that may become one. It carries the disputed payment, a deadline to respond, your evidence, and the outcome once the processor rules.\n\nUse the Disputes API to list disputes, edit the evidence packet while a dispute is still contestable, and submit it for review, or accept a chargeback you don't want to contest.\n", "name": "Disputes", "x-whop-summary": "Chargebacks filed against an account, with evidence and outcomes." }, { "description": "A Payment Rule lets an account act on its own payments before they reach the bank: block them, let them through, send them to review, or ask the buyer for 3D Secure. Each rule matches on a small set of payment attributes, and every condition must hold for it to apply.\n\nA rule's definition is fixed once created, so the payments it decided keep naming the rule that decided them. Use [Replace](/api-reference/beta/payment-rules/replace-a-payment-rule) to change one, and [List fields](/api-reference/beta/payment-rules/list-fields) for the attributes, operators and values a condition can use.\n", "name": "Payment Rules", "x-whop-summary": "Rules an account writes to decide its own payments." }, { "description": "To accept payment-financing methods, an account applies through a financing application: a request to review the account for payment financing, not a loan or business capital. Create an application, save answers to its requirements, then submit it for review. You can manage applications for your own account and its direct connected accounts.\n", "name": "Financing Applications", "x-whop-summary": "An account's request to accept buy-now-pay-later payment methods." }, { "description": "Deposits describe the ways to add funds to an account or user balance: a hosted deposit page, bank transfer instructions, and crypto wallet addresses.\n\nUse the Deposits API to get deposit instructions for an account or user, such as a crypto address to send funds to or bank details for a transfer.\n", "name": "Deposits", "x-whop-summary": "Add funds to a balance." }, { "description": "A Transfer moves money between Whop balances: from one account or user to another, from an account's wallet to a person or address, or into a claim link anyone with the URL can redeem.\n\nUse the Transfers API to send money, find recipients you can pay, list and retrieve transfers when reconciling money movement, and preview or redeem claim links.\n\nSubscribe to `transfer.completed` and `transfer.failed` for outcomes instead of polling. Each participating account can subscribe to these events. `transfer.created` is also emitted on success, not when processing starts. A failed transfer can be retried under the same ID and later succeed; retrieve the transfer to reconcile its current status.\n\nA successful balance transfer credits the recipient's available balance unless a release date applies. Transfers funded from pending balance retain a release date and credit pending balance; applicable recipient reserves or fraud holds can keep funds unavailable. `succeeded` confirms the transfer completed, not that all funds are withdrawable.\n", "name": "Transfers", "x-whop-summary": "Move funds between Whop accounts and users." }, { "description": "Payouts represent money sent from an account or user balance to an external destination, such as a bank account, wallet, or other saved payout method.\n\nUse the Payouts API to create and track payouts, manage saved payout methods, and show expected arrival details for funds leaving Whop.\n", "name": "Payouts", "x-whop-summary": "Send money from a balance to a bank or wallet." }, { "description": "A Financial Activity row is a single movement of money in or out of an account's or user's balance: a payment, payout, refund, transfer, on-chain deposit, swap, or card transaction. Each row carries a typed `resource` and `source` so you can present and link the event without extra lookups.\n\nUse the Financial Activity API to build a statement or transaction feed for an account or user, and financial reports to summarize balance activity, income, and balances over a date range, then break a report total down into what drove it.\n", "name": "Ledgers", "x-whop-docs-title": "Financial Activity", "x-whop-summary": "The activity feed behind an account or user's balance." }, { "description": "Cards represent virtual payment cards that spend from an account or user balance. Cards can be assigned to cardholders and configured with spending limits for controlled spending.\n\nUse the Cards API to issue cards, list cards for an account or user, retrieve active card details such as the card number and CVC, and list the transactions made with them.\n", "name": "Cards", "x-whop-summary": "Issue cards that spend from a balance." }, { "description": "A Cashback Rule pays a platform's direct connected accounts back a share of their card spend, funded by the platform. Each rule sets a rate, an eligibility window, and optional merchant filters, and can be limited to one connected account.\n\nUse the Cashback Rules API to create, update, and list the rules your platform funds, then pay out cashback on demand from your available USD balance.\n", "name": "Cashback Rules", "x-whop-summary": "Configure platform-sponsored card cashback." }, { "description": "A Swap converts value between supported tokens, chains, or wallet destinations, or between fiat currencies at the mid-market rate, for an account or user. A swap quote previews the expected output, fees, and approval requirements before you create the swap.\n\nUse the Swaps API to quote a conversion, create the swap, list recent swaps, and retrieve a swap's status until it completes.\n", "name": "Swaps", "x-whop-summary": "Convert a balance between currencies." }, { "description": "A Trade is one request on an account's or user's Whop-managed wallet. An `order` places one order from the trading balance, bridging the USDT0 it needs from the wallet first when the balance is short. A `close` closes the whole position in one market; when the account is then flat, a `withdraw` trade sends the trading balance back to the wallet. A `deposit` or `withdraw` moves money between the wallet and the trading balance. Orders trade Hyperliquid perpetuals and spot pairs priced in USDC.\n\nUse the Trades API to list the markets you can trade, place orders, close positions and move funds, and follow each trade until it finishes. Trades run in the background; an order that bridged money in and does not fill sends that money back to the wallet, and `funds_location` says where the money is.\n\nThe trading API, including `include_trading` on accounts and users, is in beta. It can change without a new API version date.\n", "name": "Trades", "x-whop-summary": "Place orders, close positions, and move funds for perpetual and spot trading from a Whop-managed wallet." }, { "description": "A Verification represents a legal identity for a person or business. Accounts and users complete verification when Whop needs to confirm who they are before enabling payouts or compliance-sensitive workflows.\n\nUse the Verifications API to start or resume a hosted verification session, check review status, and submit requested details or documents. If `requested_information` contains items, submit answers with [Update Verification](/api-reference/beta/verifications/update-verification).\n", "name": "Verifications", "x-whop-summary": "Legal identity required before payouts and card issuing." }, { "description": "A Product is a digital good or service sold on Whop. Products contain variants for pricing and may contain experiences for content delivery.\n\nUse the Products API to search the public marketplace, list an account's products, retrieve a product, and create, update, or delete products.\n", "name": "Products", "x-whop-summary": "The things you sell. Each owns variants and a store page." }, { "description": "A Variant is one purchasable configuration of a product. It controls price, billing cadence, stock, SKU, attributes, tax behavior, checkout fields, and purchase visibility. Variant IDs remain prefixed `plan_`.\n\nUse the Variants API to create variants for products, list existing variants, retrieve or update variant configuration, calculate tax for checkout, and delete variants that should no longer be offered.\n", "name": "Variants", "x-whop-summary": "Purchasable configurations of a product." }, { "description": "A Promo Code is a discount a buyer enters at checkout, either a percentage or a fixed amount off. It belongs to an account, can be limited to one product, and controls who can redeem it, how many times, until when, and for how many billing periods the discount lasts.\n\nUse the Promo Codes API to create codes for an account, list and retrieve them, deactivate a code to pause redemptions or activate it again, and archive codes you no longer offer.\n", "name": "Promo Codes", "x-whop-summary": "Discounts that creators configure for checkout." }, { "description": "A Checkout Configuration is a reusable checkout link owned by an account. In `payment` mode it sells a specific variant; in `setup` mode it collects and saves payment details without charging. Each configuration can also override which payment methods are accepted and how 3D Secure is enforced for that checkout.\n\nUse the Checkout Configurations API to create checkout links for an existing or inline variant, list configurations for an account, retrieve the configuration behind a checkout URL, and delete links that should no longer be used.\n", "name": "Checkout Configurations", "x-whop-summary": "Turn a variant into a shareable, prefilled checkout link." }, { "description": "A Waitlist Entry is a user's signup for a variant that requires seller approval. Joining doesn't grant a membership or charge a payment method; the seller approves or denies each signup.\n\nUse the Waitlist Entries API to join a waitlist, read or cancel your own signups, and approve or deny the signups for accounts you operate.\n", "name": "Waitlist Entries", "x-whop-summary": "Join waitlists and manage customer signups awaiting approval." }, { "description": "A Membership is a customer's purchase of a variant: the subscription or one-time grant that gives them access to a product. It tracks billing state (`active`, `trialing`, `past_due`, and so on), the current period, pending cancellations, custom metadata, and the software license key when the product includes licensing.\n\nUse the Memberships API to list an account's memberships or your own, retrieve one by ID or license key, invite a recipient to join through a free variant, and manage the lifecycle: cancel immediately or at period end, reverse a scheduled cancellation, pause and resume payment collection, extend or reactivate access, apply a promo code or affiliate, change renewal cadence, resync access, generate a transfer link, and update metadata.\n", "name": "Memberships", "x-whop-summary": "A customer's purchase of a variant, from checkout through cancellation." }, { "description": "A Shipment attaches a carrier tracking number to a payment and follows the package from label creation to delivery, exposing the current delivery status and a customer-facing tracking URL.\n\nUse the Shipments API to list an account's shipments, retrieve one by its ID or the payment it fulfills, attach a tracking number to a payment, and update the tracking number on an existing shipment.\n", "name": "Shipments", "x-whop-summary": "Track the delivery of an order by its carrier tracking number." }, { "description": "A Review is a customer's star rating and optional written feedback on a product, shown on the product's store page.\n\nUse the Reviews API to list a product's reviews, filtered by star rating or creation date, and retrieve a review by ID.\n", "name": "Reviews", "x-whop-summary": "Customer star ratings and written feedback on a product." }, { "description": "A Product Affiliate represents a user's enrollment in a product's affiliate program. An enrollment can exist before the user makes a referral or earns a reward.\n\nUse the Product Affiliates API to list product affiliates for an account, search by affiliate name or username, and narrow the results by product, enrollment status, or signup date.\n", "name": "Product Affiliates", "x-whop-summary": "Users enrolled to promote a product, including affiliates with no referrals." }, { "description": "Plans is the former public name for Variants. Existing integrations can keep calling these deprecated endpoints while they migrate; every response points to the matching Variants endpoint.\n\nUse the Variants API for all new integrations. Variant IDs retain their existing `plan_` prefix, and the underlying resource is unchanged.\n", "name": "Plans", "x-whop-summary": "Deprecated compatibility endpoints for variants." }, { "description": "A Domain is a hostname an account holds on Whop. Its capabilities set what Whop does with it: `registration` buys the domain through Whop, runs its DNS, and renews it every year; `verification` connects a domain registered elsewhere once you publish the DNS records it returns, and expires if ownership is not proven within 48 hours; `website` serves one of the account's apps on it.\n\nUse the Domains API to search for a domain to buy, buy or connect one, serve a website on it, and check its DNS, payment, and renewal state. Thirty days before a bought domain expires, Whop opens a renewal charge at `purchase_url` and, while `auto_renew` is on, charges the saved card. An unpaid domain stops serving when it expires but stays renewable at `purchase_url` until the registry's grace period ends, and is then removed.\n", "name": "Domains", "x-whop-summary": "Custom domains assigned to hosted apps." }, { "description": "An App is software you build on Whop. It can be a hosted web app served at its domains, such as a `whop.site` address or a custom domain, or an API integration installed as an experience, and it belongs to the account that owns its credentials, settings, builds, and runtime logs.\n\nUse the Apps API to manage app configuration, deploy an app's working copy and follow the run on the app's `deployment` field, and, for hosted apps, read server runtime logs for console output, uncaught exceptions, and failed requests.\n\nApps are also reusable blueprints. List official blueprints with `app_type=website&verified=true&order=template_usage`, or community blueprints with `app_type=website&verified=false&recommended=true&order=template_usage`. Pass the returned App `id` as `blueprint_id` when creating an Account.\n", "name": "Apps", "x-whop-summary": "Apps you build on Whop: metadata, hosted builds, runtime logs." }, { "description": "An App Build is a versioned artifact uploaded for an app — a hosted web archive, or an iOS/Android bundle. Builds start as drafts, go through review, and one approved build per platform is served to users as the production build.\n\nUse the App Builds API to upload a build for an app, list an app's builds with platform and status filters, retrieve a build, and promote a draft or approved build to production.\n", "name": "App Builds", "x-whop-summary": "Versioned build artifacts deployed to an app's platforms." }, { "description": "An App Installation represents one install of your app on one account. An account installs an app once, however many experiences it adds, so an installation holds state that belongs to the account rather than to one experience, such as a sync cursor or the ID of the account it's linked to in another system.\n\nUse the App Installations API to [list the accounts your app is installed on](/api-reference/beta/app-installations/list-app-installations), [retrieve one](/api-reference/beta/app-installations/retrieve-app-installation), and [update](/api-reference/beta/app-installations/update-app-installation) the `metadata` and `external_id` your app keeps on it. An account can also list the apps installed on it, and a developer every installation of their app. Only the app and its developer see `metadata` and `external_id`, and only the app can change them.\n", "name": "App Installations", "x-whop-summary": "Your app's installations on accounts, and the data it keeps about each one." }, { "description": "An Experiment is a feature flag or A/B test owned by an account. Treatments take stable percentage ranges of traffic and everyone else gets control, so growing an allocation never moves an existing user to another arm.\n\nUse the Experiments API to create a draft, configure its weights, targeting, and resource bindings, then activate, pause, or end it, and to evaluate which arm a user, account, or anonymous visitor gets. Managing experiments requires `experiment:read` or `experiment:manage`; evaluation works without authentication.\n", "name": "Experiments", "x-whop-summary": "Feature flags and A/B experiments for gradual rollout." }, { "description": "The Payment Method Domains API is deprecated. Add, check, and remove Apple Pay domains with the `apple_pay` capability of the [Domains API](/api-reference/beta/domains/domain) instead. These endpoints keep working and return `Deprecation` and successor `Link` headers. A domain keeps its ID, so `/domains/{id}` takes the `dom_` or `pmd_` ID these endpoints return.\n\nA Payment Method Domain registers a hostname with a wallet provider so its payment methods can appear at a checkout served from that domain. The domain proves ownership by hosting the provider's association file — for Apple Pay, at `/.well-known/apple-developer-merchantid-domain-association` — and `status` reports whether verification has completed. Embedded surfaces like the [Express Checkout element](/elements/beta/checkout/expressCheckout) only render Apple Pay, Google Pay and PayPal express on a `verified` domain (first-party whop.com pages are pre-approved).\n\n| Payment Method Domains API | Domains API |\n| --- | --- |\n| `GET /payment_method_domains?status=verified` | `GET /domains?apple_pay=ready`, or `apple_pay=any` for every Apple Pay domain |\n| `?hostname=` | `?domain=` |\n| `GET /payment_method_domains/{id}` | `GET /domains/{id}` |\n| `POST /payment_method_domains` with `hostname` and `account_id` | `POST /domains` with `domain`, `account_id`, and `apple_pay: {}`. If the account already has the domain, `PATCH /domains/{id}` with `apple_pay: {}` |\n| `POST /payment_method_domains/{id}/verify` | `POST /domains/{id}/check` |\n| `DELETE /payment_method_domains/{id}` | `PATCH /domains/{id}` with `apple_pay: null` |\n| `hostname` | `domain` |\n| `status: verified` | `apple_pay.state: ready` |\n| `status: pending` | `apple_pay.state: pending` while Whop registers the domain, or `action_required` until you host the association file and check the domain |\n| `provider` | No field: every Apple Pay domain is registered with Apple |\n\nRegistration runs in the background, so creating or checking a domain returns `pending`: retrieve the domain until `apple_pay.state` is `ready` or `action_required`. The Domains API needs the `domain:read` and `domain:manage` permissions instead of `company:manage_checkout`, so give API keys those scopes. `DELETE /domains/{id}` removes the whole domain, including any website on it, so use `PATCH` to remove only Apple Pay.\n", "name": "Payment Method Domains", "x-whop-summary": "Deprecated: domains verified to show Apple Pay at checkout. Use Domains instead." }, { "description": "An Ad Campaign is the top-level container for paid ads on an ad network. It sets the platform, objective, and budget strategy shared by its [ad groups](/api-reference/beta/ad-groups/ad-group) and ads.\n\nUse the Ad Campaigns API to create campaigns, list campaigns for an account, retrieve or update campaign settings, and pause or resume campaign delivery.\n\nAds billing combines eligible spend across the account's campaigns. A failed payment blocks delivery with `delivery_status: payment_failed` while preserving the configured active/paused `status`. Fix the account's payment method and [retry its ads payment](/api-reference/beta/accounts/retry-failed-ads-payments) once for the account. The retry is asynchronous: acceptance does not confirm payment. Successful settlement clears the block; active campaigns can resume if otherwise eligible, while paused campaigns stay paused. See [billing and retries](/developer/ads/overview#paying-for-ads).\n", "name": "Ad Campaigns", "x-whop-summary": "Platform, objective, and budget for a set of ads." }, { "description": "An Ad Group sits inside an [ad campaign](/api-reference/beta/ad-campaigns/ad-campaign) and controls delivery for [ads](/api-reference/beta/ads/ad). It sets the audience, placements, schedule, budget, and optimization goal for its ads.\n\nUse the Ad Groups API to create ad groups in campaigns, list or retrieve targeting and delivery settings, update budgets or targeting, delete groups that should stop running, and pause or resume delivery. It can also search the ad platform's targeting taxonomy for options to target and estimate how many people a draft targeting spec can reach.\n", "name": "Ad Groups", "x-whop-summary": "Audience, placements, and schedule within a campaign." }, { "description": "An Ad is the individual creative unit delivered by an [ad group](/api-reference/beta/ad-groups/ad-group). It holds the copy, creative assets, and destination URL for one ad.\n\nUse the Ads API to list ads for an account, create ads inside ad groups, retrieve or update creative details, delete ads that should stop running, and pause or resume delivery.\n", "name": "Ads", "x-whop-summary": "The creative: copy, assets, and destination URL." }, { "description": "An Audience is a reusable group of people to include or exclude when targeting ads. Build custom audiences from customer lists, Whop People data, or social engagement, and create lookalikes to reach people similar to an existing audience.\n\nUse the Audiences API to create audiences, add people to an uploaded customer list, rename or refilter an audience, and monitor asynchronous processing. Engagement sources on Meta include videos, lead forms, Instagram profiles, and Facebook pages, and their membership updates on Meta; Whop People audiences can refresh automatically or keep a snapshot.\n", "name": "Audiences", "x-whop-summary": "Reusable targeting lists for ad groups." }, { "description": "An Ad Pixel connects a pixel you own on an ad platform to a business whose campaigns you claimed through the advertiser supplier program. Whop sends that pixel the conversions credited to your claimed campaigns for that business, using the access token you provide.\n\nUse the Ad Pixels API to add one pixel per business on each ad platform, list or retrieve your pixels, replace an access token the ad platform rejected, and remove a pixel to stop deliveries.\n", "name": "Ad Pixels", "x-whop-summary": "Your own pixels that receive conversions from campaigns you claimed." }, { "description": "A conversion value rule changes the conversion values Whop sends to ad networks while Whop keeps recording the accurate values. Each rule belongs to an account and applies one value adjustment to a set of targets (the account, an ad campaign, an ad group, or an ad) and events. Every selected event applies to every selected target, and the most specific rule applies.\n\nUse the Ad Conversion Value Rules API to create, edit, pause, resume, and delete rules, and to find the rules that cover a campaign, ad group, or ad. Each write succeeds or fails as one transaction, and each conversion send uses the rules saved at that moment.\n", "name": "Ad Conversion Value Rules", "x-whop-summary": "Modify how conversion events are delivered to ad networks." }, { "description": "Stats represent aggregated activity for an account over time. They help you understand revenue, transactions, disputes, members, referrals, and advertising performance across reporting periods like days, weeks, or months.\n\nUse the Stats API to list the metrics you can chart and retrieve one as a time series over a date range, or list reports and retrieve aggregates that are not bucketed over time, such as platform-wide payment trends.\n", "name": "Stats", "x-whop-summary": "Aggregated financial, audience, and traffic reporting." }, { "description": "A Report is a pre-built analytics payload for an account, assembled from pixel events. Reports cover traffic today — page views and visitors over time, top pages, sources, devices, countries, and weekday activity.\n\nUse the Reports API to list the available reports and their accepted parameters, then retrieve one report for a date range.\n", "name": "Reports", "x-whop-summary": "Pre-built traffic analytics tables and series." }, { "description": "A Person is an identity-linked profile of a visitor or customer of an account, assembled from every [event](/api-reference/beta/events/event) the person generated, such as pixel page views, ad clicks, leads, and payments.\n\nUse the People API to list and segment the people of an account by activity, purchases, traffic source, or marketing touch, and to retrieve one person by person ID, user ID, email address, or phone number.\n", "name": "People", "x-whop-summary": "Visitors and customers of an account, with identity, purchase, and traffic profiles." }, { "description": "An Event records conversion or engagement activity for an account, such as page views, purchases, or leads. Each event ties the action to the [person](/api-reference/beta/people/person) who took it, so activity can be attributed to the ads and links that drove it.\n\nUse the Events API to send new tracking events, list recent identity-linked events for an account, and inspect the events recorded for a person. The resource also exposes an anonymized read mode — the pulse feed — a platform-wide snapshot of recent purchases that carries nothing identifying. The pulse feed is public; other Events endpoints require authentication and are scoped to an account.\n\nEvents are only as good as the pixel sending them, so [Validate Pixel](/api-reference/beta/events/validate-pixel) answers whether an account's pixel is working: it reads the events the pixel has sent, and when you pass a `url` whose page hasn't sent any lately, it fetches that page and looks for the pixel in its source. Use it before launching an ad to confirm its destination is tracked, or in a setup flow to tell a merchant whether their install is live.\n", "name": "Events", "x-whop-summary": "Conversion and engagement events tracked for attribution." }, { "description": "An Export is a CSV of one of an account's dashboard tables, such as members, payments, or disputes. Exports are generated in the background, so a new export starts `pending` and becomes `completed` with a download link.\n\nUse the Exports API to start an export, poll it until `download_url` is set, and list an account's past exports. Each table requires its own export scope, and finished files are deleted after 30 days.\n", "name": "Exports", "x-whop-summary": "Asynchronous CSV dumps of an account's dashboard data." }, { "description": "Economic Intelligence is Whop's recommendation engine for an account. Each recommendation is one action: a title the owner sees, a step-by-step brief Whop AI carries out, and the result it expects. Whop generates them from the account's sales, site, ads, and what its owner has said.\n\nUse the Economic Intelligence API to list an account's recommendations, request new ones for a specific goal, and follow each one from `queued` to `ready`, then to `executed` once the owner runs it or `superseded` when a newer one replaces it or you retire it.\n\nRead `economic_intelligence_offers` from account preferences and send one of its keys as `economic_intelligence_duration_key` to turn it on.\n", "name": "Economic Intelligence", "x-whop-summary": "What an account should do next to grow, generated from its own data." }, { "description": "A Message contains Markdown and optional attachments, a poll or a reply. Read history, synchronize edits and deletions, or fetch a window around a message. Existing permissions govern sending, editing, pinning and deletion.\n\nAdd or remove an emoji reaction, list who reacted, and vote once on a message poll. Messages include aggregate reaction and vote counts and whether you reacted or voted, without exposing other voters.\n", "name": "Messages", "x-whop-summary": "Chat messages, attachments, reactions and polls." }, { "description": "A Livestream represents a live video broadcast in an experience. After a recorded livestream ends, members can watch the replay, and moderators can pin the best recordings to feature them.\n\nUse the Livestreams API to [list an experience's livestreams](/api-reference/beta/livestreams/list-livestreams), [retrieve one](/api-reference/beta/livestreams/retrieve-livestream) with its recording, and [pin](/api-reference/beta/livestreams/pin-livestream) or [unpin](/api-reference/beta/livestreams/unpin-livestream) recordings.\n", "name": "Livestreams", "x-whop-summary": "Live video broadcasts in an experience, and their recordings." }, { "description": "A Notification is a message delivered to a user, such as a new post, a payment, or a mention. Each one comes from an experience the user belongs to or a team they are on, and falls under a topic, like new sales, that users set preferences on.\n\nUse the Notifications API to list a user's feed, read and clear unread badges, send notifications from your app to an experience's users or an account's team, and list the topic catalog that notification preferences reference.\n", "name": "Notifications", "x-whop-summary": "The user's notification feed: unread badges, mark-read, app sends, and the topic catalog." }, { "description": "An Email address is a mailbox on one of the account's domains, such as support@example.com. The domain needs the `email` capability in the `ready` state first. A mailbox either belongs to one team member, who alone can read it and send from it, or is shared by the account, where `email:read` and `email:send` decide who can use it.\n\nUse the Email addresses API to create, list, reassign and delete mailboxes, read the password mail apps sign in with, and download a configuration profile that adds the mailbox to Mail on Apple devices. Deleting an address keeps its mail, and creating it again in the same account brings the mailbox back.\n", "name": "Email addresses", "x-whop-summary": "Mailboxes on an account's domains, for sending and receiving email." }, { "description": "Get started at [whop.com/network](https://whop.com/network). A Partner is a user who refers people and businesses to Whop. The partner profile includes enrollment, active direct business referral counts, and default payout terms.\n\nRetrieve your profile with `/partners/me`. Use `/partner_referral_requests` to create and manage referral links and their rewards. You can also enroll in the partner program, review referred users and businesses, track earnings, and see the partner leaderboard.\n", "name": "Partners", "x-whop-summary": "Your partner profile, referral links, payout rates, and referred businesses." }, { "description": "A Partner Referral Request is a partner's referral link, or a request to be credited as the referrer of an existing business or user. An attribution request takes effect only when the recipient accepts it.\n\nUse the Partner Referral Requests API to create referral links, send attribution requests, list the links and requests you've sent or received, and accept, decline, or cancel a pending request.\n", "name": "Partner Referral Requests", "x-whop-summary": "Request business or partner attribution and manage approval." }, { "description": "A Bounty is a paid task posted by an account or user. The reward is held in escrow when the bounty publishes, workers submit proof of completed work, and each accepted submission is paid out until every winner slot fills.\n\nUse the Bounties API to create and publish a bounty, list an account's bounties for reporting or dashboards, list the bounties a user can work or has participated in, and retrieve a single bounty by ID.\n", "name": "Bounties", "x-whop-summary": "Paid tasks with reviewed submissions and escrowed rewards." }, { "description": "A Bounty Submission is one worker's attempt on a bounty. It starts as an in-progress attempt, enters the review queue when proof is submitted, and ends approved (paid from the bounty's escrowed pool) or denied.\n\nUse the Bounty Submissions API to submit proof of completed work to a bounty, list the submissions you authored, and review the submissions on your bounties — across every bounty or narrowed to one.\n", "name": "Bounty Submissions", "x-whop-summary": "Work submitted to a bounty, from attempt to payout." }, { "description": "A File is an uploaded document or media object, identified by a `file_` ID. Creating a file returns a presigned destination; upload the bytes there and the file becomes `ready`.\n\nUse the Files API to create a file, upload its content directly to storage (in one PUT, or in parts for large files), and retrieve it while polling for readiness. A ready file's ID can be attached wherever Whop accepts files.\n", "name": "Files", "x-whop-summary": "Upload files and attach them wherever Whop accepts documents." }, { "description": "A Media Asset is an AI-generated image or video created from a prompt and billed from an account balance. When generation finishes, the asset includes a file that can be attached anywhere Whop accepts files.\n\nUse the Media API to start a generation job and retrieve the asset while it processes or after it is ready.\n", "name": "Media", "x-whop-summary": "AI-generated assets, billed from a balance, attachable wherever files are accepted." }, { "description": "An API Key is a programmatic credential owned by an account or app. Each key carries its own permissions policy — explicit permission statements or an inherited system role — and can be restricted with an expiration date and an IP allowlist.\n\nUse the API Keys API to list an account or app's keys, create a key (the full secret is returned once, on creation), inspect a key's effective grants, update its name or restrictions, rotate its secret, and revoke it. These endpoints require a user session — they cannot be called with an API key.\n", "name": "API Keys", "x-whop-summary": "Programmatic credentials for an account or app." }, { "description": "A Webhook is an endpoint on your server that Whop sends signed HTTP POST requests to when events happen, such as a payment succeeding or a membership going active. A webhook is attached to an account or an app and subscribes to the events you choose.\n\nUse the Webhooks API to create and update endpoints, send a test event, inspect the delivery log, and replay deliveries your server missed. See [Webhooks & Events](/developer/guides/webhooks) for verifying signatures and handling retries.\n", "name": "Webhooks", "x-whop-summary": "Event notifications pushed to your server as things happen." }, { "description": "A Permission is one action, such as `stats:read`, paired with whether your credential is granted it on a given resource. It answers for whatever you authenticated with, so you can decide what to show or attempt instead of discovering a `403`.\n\nUse the Permissions API to check an account, product, experience, or app, narrowing to the actions you care about. It reports only your own access — to manage who else can reach an account, use the Team Members API.\n", "name": "Permissions", "x-whop-summary": "What your credential is allowed to do on a resource." }, { "description": "An Api Log is a record of a single request made to Whop's API using one of your account's API keys — the programmatic counterpart to the dashboard audit log, which only records actions taken by signed-in team members. Reads and failed requests are logged too.\n\nUse the Api Logs API to see what your integrations are doing on Whop: the operation, HTTP method and status, outcome, and timing of each request, newest first.\n", "name": "Api Logs", "x-whop-summary": "Requests made to Whop's API with your account's API keys." }, { "description": "A feedback submission sends an issue, confusing behavior, documentation gap, or unanswered question to Whop. It is recorded under the authenticated user, account, or app, with an optional account for context, and reviewed by Whop.\n\nUser, account, and app credentials can all submit. The response is a receipt with an `fbk_` ID: Whop does not reply to submissions, and they cannot be listed or retrieved through the API.\n", "name": "Feedback", "x-whop-summary": "Issues and unanswered questions sent to Whop for review." } ], "webhooks": { "account.financing_approved": { "post": { "description": "Sent when the account is approved for financing and buy-now-pay-later options unlock at checkout\n\nRequired permissions:\n - `webhook_receive:accounts`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "ads_spend_usd": null, "balances": [], "banner_image_url": null, "business_address": null, "business_name": null, "business_type": "software", "can_transfer_pending_balance_to_children": false, "cancellation_policy": null, "capabilities": { "accept_bank_payments": "active", "accept_bnpl_payments": "inactive", "accept_card_payments": "active", "bank_deposit": "inactive", "card_deposit": "inactive", "card_issuing": "inactive", "crypto_deposit": "active", "crypto_payout": "inactive", "instant_payout": "inactive", "run_ads": "inactive", "standard_payout": "inactive", "transfer": "inactive" }, "cards": null, "collect_vat_id": false, "company_formation": { "status": "draft" }, "country": "us", "created_at": "2026-01-01T12:00:00.000Z", "customers_l30d": null, "description": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "dispute_fighter_enabled": false, "economic_intelligence": false, "email": "marcus@shinetime.example", "eula": null, "financing": null, "home_preferences": [], "id": "biz_xxxxxxxxxxxxxx", "industry_type": null, "invoice_prefix": "SHINE", "level": null, "logo_url": null, "metadata": { "external_id": "shop_4417", "region": "austin" }, "onboarding_type": "seller", "opengraph_image_url": null, "opengraph_image_variant": null, "orchestration_enabled": true, "other_business_description": null, "other_industry_description": null, "owner": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "parent_account": null, "payment_controls": { "dispute_alert_auto_refund": { "locked": false, "threshold_usd": 500 }, "dispute_alert_fee_usd": 29, "enforce_3ds": false, "financing_disabled": false, "high_risk_processing_fee_percentage": 0, "pending_auto_topup_fee_percentage": 2.0, "pending_balance_delay_days": 0, "reserve": { "hold_period_days": 90, "percentage": null }, "resolution_center_auto_refund": { "card_threshold_usd": null, "financing_threshold_usd": null, "locked": false, "paypal_threshold_usd": null }, "restricted_payment_methods": [], "undated_pending_reason": null, "withdrawal_schedule": { "day": null, "frequency": "manual", "next_payout_date": null } }, "platform_credits": [], "privacy_policy": null, "product_tax_code": null, "recommended_actions": null, "require_2fa": false, "required_actions": [ { "action": "verify_identity", "blocked_capabilities": [], "cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/balance/", "cta_label": "Verify now", "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "icon_url": null, "status": "required", "title": "Ceramic Coating Package" } ], "return_policy": null, "route": "biz_xxxxxxxxxxxxxx", "send_customer_emails": true, "shipping_policy": null, "show_joined_whops": true, "show_reviews_dtc": true, "show_user_directory": true, "social_links": [ { "id": "social_1", "title": null, "url": "https://instagram.com/shinetimedetailing", "website": "instagram" } ], "status": "active", "status_reason": null, "store_page_config": { "accent_color": "blue", "layout": "featured", "profile_variant": null, "whop_affiliate_link": false }, "target_audience": "Owners of new and enthusiast vehicles in Austin, TX", "tax_collection_enabled_states": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "tax_identifiers": [], "tax_remitted_by": "whop", "tax_type": null, "terms_of_service": null, "three_ds_level": null, "title": "Shine Time Auto Detailing", "total_earned_usd": 0.0, "total_usd": null, "trading": null, "use_logo_as_opengraph_image_fallback": false, "verification": { "business": null, "individual": null }, "volume_l30d_usd": null, "volume_usd": 0.0, "wallet": null, "website": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "account.financing_approved" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Account" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "account.financing_approved", "description": "The webhook event type", "example": "account.financing_approved", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Account Financing approved", "tags": [ "Financing Applications" ] }, "x-whop-surface": "native" }, "account.financing_denied": { "post": { "description": "Sent when the account's financing application is denied\n\nRequired permissions:\n - `webhook_receive:accounts`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "ads_spend_usd": null, "balances": [], "banner_image_url": null, "business_address": null, "business_name": null, "business_type": "software", "can_transfer_pending_balance_to_children": false, "cancellation_policy": null, "capabilities": { "accept_bank_payments": "active", "accept_bnpl_payments": "inactive", "accept_card_payments": "active", "bank_deposit": "inactive", "card_deposit": "inactive", "card_issuing": "inactive", "crypto_deposit": "active", "crypto_payout": "inactive", "instant_payout": "inactive", "run_ads": "inactive", "standard_payout": "inactive", "transfer": "inactive" }, "cards": null, "collect_vat_id": false, "company_formation": { "status": "draft" }, "country": "us", "created_at": "2026-01-01T12:00:00.000Z", "customers_l30d": null, "description": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "dispute_fighter_enabled": false, "economic_intelligence": false, "email": "marcus@shinetime.example", "eula": null, "financing": null, "home_preferences": [], "id": "biz_xxxxxxxxxxxxxx", "industry_type": null, "invoice_prefix": "SHINE", "level": null, "logo_url": null, "metadata": { "external_id": "shop_4417", "region": "austin" }, "onboarding_type": "seller", "opengraph_image_url": null, "opengraph_image_variant": null, "orchestration_enabled": true, "other_business_description": null, "other_industry_description": null, "owner": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "parent_account": null, "payment_controls": { "dispute_alert_auto_refund": { "locked": false, "threshold_usd": 500 }, "dispute_alert_fee_usd": 29, "enforce_3ds": false, "financing_disabled": false, "high_risk_processing_fee_percentage": 0, "pending_auto_topup_fee_percentage": 2.0, "pending_balance_delay_days": 0, "reserve": { "hold_period_days": 90, "percentage": null }, "resolution_center_auto_refund": { "card_threshold_usd": null, "financing_threshold_usd": null, "locked": false, "paypal_threshold_usd": null }, "restricted_payment_methods": [], "undated_pending_reason": null, "withdrawal_schedule": { "day": null, "frequency": "manual", "next_payout_date": null } }, "platform_credits": [], "privacy_policy": null, "product_tax_code": null, "recommended_actions": null, "require_2fa": false, "required_actions": [ { "action": "verify_identity", "blocked_capabilities": [], "cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/balance/", "cta_label": "Verify now", "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "icon_url": null, "status": "required", "title": "Ceramic Coating Package" } ], "return_policy": null, "route": "biz_xxxxxxxxxxxxxx", "send_customer_emails": true, "shipping_policy": null, "show_joined_whops": true, "show_reviews_dtc": true, "show_user_directory": true, "social_links": [ { "id": "social_1", "title": null, "url": "https://instagram.com/shinetimedetailing", "website": "instagram" } ], "status": "active", "status_reason": null, "store_page_config": { "accent_color": "blue", "layout": "featured", "profile_variant": null, "whop_affiliate_link": false }, "target_audience": "Owners of new and enthusiast vehicles in Austin, TX", "tax_collection_enabled_states": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "tax_identifiers": [], "tax_remitted_by": "whop", "tax_type": null, "terms_of_service": null, "three_ds_level": null, "title": "Shine Time Auto Detailing", "total_earned_usd": 0.0, "total_usd": null, "trading": null, "use_logo_as_opengraph_image_fallback": false, "verification": { "business": null, "individual": null }, "volume_l30d_usd": null, "volume_usd": 0.0, "wallet": null, "website": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "account.financing_denied" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Account" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "account.financing_denied", "description": "The webhook event type", "example": "account.financing_denied", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Account Financing denied", "tags": [ "Financing Applications" ] }, "x-whop-surface": "native" }, "account.financing_disabled": { "post": { "description": "Sent when dispute-rate enforcement removes BNPL feature access from an account. The payload captures the triggering provider and the payment methods affected at removal time. It does not change the financing application's review status. Parent platforms can subscribe with child_resource_events enabled\n\nRequired permissions:\n - `webhook_receive:accounts`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "disabled_at": "2026-01-01T12:00:00.000Z", "disabled_payment_methods": [ "klarna", "oney", "oney_3x", "oney_4x" ], "object": "financing_access_change", "provider": "klarna", "reason": "high_dispute_rate" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "account.financing_disabled" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/FinancingAccessChange" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "account.financing_disabled", "description": "The webhook event type", "example": "account.financing_disabled", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Account Financing disabled", "tags": [ "Financing Applications" ] }, "x-whop-surface": "native" }, "account.updated": { "post": { "description": "Sent when an account is updated\n\nRequired permissions:\n - `webhook_receive:accounts`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "ads_spend_usd": null, "balances": [], "banner_image_url": null, "business_address": null, "business_name": null, "business_type": "software", "can_transfer_pending_balance_to_children": false, "cancellation_policy": null, "capabilities": { "accept_bank_payments": "active", "accept_bnpl_payments": "inactive", "accept_card_payments": "active", "bank_deposit": "inactive", "card_deposit": "inactive", "card_issuing": "inactive", "crypto_deposit": "active", "crypto_payout": "inactive", "instant_payout": "inactive", "run_ads": "inactive", "standard_payout": "inactive", "transfer": "inactive" }, "cards": null, "collect_vat_id": false, "company_formation": { "status": "draft" }, "country": "us", "created_at": "2026-01-01T12:00:00.000Z", "customers_l30d": null, "description": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "dispute_fighter_enabled": false, "economic_intelligence": false, "email": "marcus@shinetime.example", "eula": null, "financing": null, "home_preferences": [], "id": "biz_xxxxxxxxxxxxxx", "industry_type": null, "invoice_prefix": "SHINE", "level": null, "logo_url": null, "metadata": { "external_id": "shop_4417", "region": "austin" }, "onboarding_type": "seller", "opengraph_image_url": null, "opengraph_image_variant": null, "orchestration_enabled": true, "other_business_description": null, "other_industry_description": null, "owner": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "parent_account": null, "payment_controls": { "dispute_alert_auto_refund": { "locked": false, "threshold_usd": 500 }, "dispute_alert_fee_usd": 29, "enforce_3ds": false, "financing_disabled": false, "high_risk_processing_fee_percentage": 0, "pending_auto_topup_fee_percentage": 2.0, "pending_balance_delay_days": 0, "reserve": { "hold_period_days": 90, "percentage": null }, "resolution_center_auto_refund": { "card_threshold_usd": null, "financing_threshold_usd": null, "locked": false, "paypal_threshold_usd": null }, "restricted_payment_methods": [], "undated_pending_reason": null, "withdrawal_schedule": { "day": null, "frequency": "manual", "next_payout_date": null } }, "platform_credits": [], "privacy_policy": null, "product_tax_code": null, "recommended_actions": null, "require_2fa": false, "required_actions": [ { "action": "verify_identity", "blocked_capabilities": [], "cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/balance/", "cta_label": "Verify now", "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "icon_url": null, "status": "required", "title": "Ceramic Coating Package" } ], "return_policy": null, "route": "biz_xxxxxxxxxxxxxx", "send_customer_emails": true, "shipping_policy": null, "show_joined_whops": true, "show_reviews_dtc": true, "show_user_directory": true, "social_links": [ { "id": "social_1", "title": null, "url": "https://instagram.com/shinetimedetailing", "website": "instagram" } ], "status": "active", "status_reason": null, "store_page_config": { "accent_color": "blue", "layout": "featured", "profile_variant": null, "whop_affiliate_link": false }, "target_audience": "Owners of new and enthusiast vehicles in Austin, TX", "tax_collection_enabled_states": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "tax_identifiers": [], "tax_remitted_by": "whop", "tax_type": null, "terms_of_service": null, "three_ds_level": null, "title": "Shine Time Auto Detailing", "total_earned_usd": 0.0, "total_usd": null, "trading": null, "use_logo_as_opengraph_image_fallback": false, "verification": { "business": null, "individual": null }, "volume_l30d_usd": null, "volume_usd": 0.0, "wallet": null, "website": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "previous_attributes": { "title": "Webb's Mobile Detailing" }, "timestamp": "2025-01-01T00:00:00.000Z", "type": "account.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Account" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "example": { "title": "Webb's Mobile Detailing" }, "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "account.updated", "description": "The webhook event type", "example": "account.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Account Updated", "tags": [ "Accounts" ] }, "x-whop-surface": "native" }, "ad.updated": { "post": { "description": "Sent when an ad's status or delivery_status changes, including the in_review and rejected verdicts from ad review. previous_attributes carries the values they changed from; the payload carries no performance stats\n\nRequired permissions:\n - `webhook_receive:ads`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "ad_campaign": { "id": "adcamp_xxxxxxxxxxxxxx" }, "ad_group": { "id": "adgrp_xxxxxxxxxxxxxx" }, "call_to_action": null, "created_at": "2026-01-01T12:00:00.000Z", "creatives": [], "delivery_status": "in_review", "descriptions": [], "existing_post_id": null, "external_accounts": [], "headlines": [], "id": "ad_xxxxxxxxxxxxxx", "issues": [], "lead_form": null, "lead_form_id": null, "messaging_config": null, "multi_advertiser_ads": true, "platform": "meta", "post_id": null, "post_source": null, "post_thumbnail_url": null, "primary_texts": [], "status": "rejected", "title": "Ceramic Coating Package", "translations": null, "updated_at": "2026-01-01T12:00:00.000Z", "url": null, "url_parameters": {} }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "previous_attributes": { "status": "in_review" }, "timestamp": "2025-01-01T00:00:00.000Z", "type": "ad.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "ad_campaign": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad campaign this ad belongs to." }, "ad_group": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad group this ad belongs to." }, "call_to_action": { "description": "The call-to-action button shown on the ad.", "enum": [ "learn_more", "shop_now", "sign_up", "subscribe", "get_started", "book_now", "apply_now", "contact_us", "download", "order_now", "buy_now", "get_quote", "message_page", "whatsapp_message", "instagram_message", "call_now", "get_directions", "send_updates", "get_offer", "watch_more", "listen_now", "play_game", "open_link", "no_button", "get_offer_view", "get_event_tickets", "see_menu", "request_time", "event_rsvp", "see_details", "view_instagram_profile", "donate_now", "see_more", "visit_site", null ], "example": "learn_more", "type": [ "string", "null" ] }, "created_at": { "description": "When the ad was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "creatives": { "items": { "$ref": "#/components/schemas/AdCreative", "description": "The creative assets used by this ad. The original asset has a null format; square, vertical, and horizontal entries are placement-specific variants. A carousel ad returns one format-null entry per attachment, in order." }, "type": "array" }, "delivery_status": { "description": "Whether the ad is delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.", "enum": [ "in_appeal", "rejected", "in_review", "draft", "campaign_paused", "ad_group_paused", "paused", "processing", "issues", "scheduled", "learning_limited", "learning", "active" ], "example": "paused", "type": "string" }, "descriptions": { "items": { "$ref": "#/components/schemas/AdText", "description": "The description shown on the ad. Entries with a null language are the ad's own copy; a Meta ad with translations also carries one entry per other language." }, "type": "array" }, "existing_post_id": { "description": "The post you pointed this ad at, when it promotes one you already published — a Facebook post, Instagram media, or TikTok video ID. `null` when the ad uses uploaded creatives.", "example": "xxxxxxxxxxxxxxxx_98765", "type": [ "string", "null" ] }, "external_accounts": { "items": { "$ref": "#/components/schemas/AdEntityReference", "description": "The external accounts the ad runs under — its Facebook page and Instagram profile — each referenced by ID, prefixed `sacc_`." }, "type": "array" }, "headlines": { "items": { "$ref": "#/components/schemas/AdText", "description": "The headline shown on the ad. Entries with a null language are the ad's own copy; a Meta ad with translations also carries one entry per other language." }, "type": "array" }, "id": { "description": "Unique identifier for the ad, prefixed `ad_`.", "example": "ad_xxxxxxxxxxxxxx", "type": "string" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting this ad. Empty when there are none." }, "type": "array" }, "lead_form": { "description": "The instant lead form shown when someone taps this ad. `null` when the ad group's conversion_location is not an instant-form destination.", "oneOf": [ { "$ref": "#/components/schemas/AdLeadForm" }, { "type": "null" } ] }, "lead_form_id": { "description": "The ad platform's ID for the instant form the ad uses. Set when the ad references an existing form via `lead_form_id`, or once a form built from `lead_form` has been created on the platform.", "example": "1037724182084885", "type": [ "string", "null" ] }, "messaging_config": { "description": "Welcome message for click-to-message ads, shown when the conversation opens. `null` when the ad has none.", "oneOf": [ { "$ref": "#/components/schemas/AdMessagingConfig" }, { "type": "null" } ] }, "multi_advertiser_ads": { "description": "Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.", "example": true, "type": "boolean" }, "music": { "description": "The advertiser-uploaded MP3 a TikTok carousel ad plays. TikTok-only; `null` elsewhere and for non-carousel ads.", "oneOf": [ { "$ref": "#/components/schemas/AdMusic" }, { "type": "null" } ] }, "platform": { "description": "The ad platform this ad runs on.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" }, "post_id": { "description": "The post the ad network serves for this ad, as `pageID_postID` on Meta — the post Meta created for an uploaded creative, or the post being promoted. Use it to open the live post, or to promote the same post from another ad. `null` until the network has created the post.", "example": "xxxxxxxxxxxxxxxx_98765", "type": [ "string", "null" ] }, "post_source": { "description": "Identifies the network that owns `existing_post_id`; `null` when the ad uses uploaded creatives.", "enum": [ "facebook", "instagram", null ], "example": "facebook", "type": [ "string", "null" ] }, "post_thumbnail_url": { "description": "Preview image of the post named by `existing_post_id`. `null` for ads that use uploaded creatives, or until the post's media has been fetched from the network.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "type": [ "string", "null" ] }, "primary_texts": { "items": { "$ref": "#/components/schemas/AdText", "description": "The primary text shown in the ad body. Entries with a null language are the ad's own copy (several make text variations); a Meta ad with translations also carries one entry per other language." }, "type": "array" }, "status": { "description": "Whether the ad is enabled. `active` and `paused` are set by you; `in_review` and `rejected` come from ad review.", "enum": [ "active", "paused", "in_review", "rejected" ], "example": "paused", "type": "string" }, "title": { "description": "Display title of the ad.", "example": "Ceramic coating — new ad group", "type": [ "string", "null" ] }, "translations": { "description": "The languages a Meta ad runs in besides its own. Each viewer sees the version for their language, or the ad's own copy. `null` when the ad runs in one language.", "oneOf": [ { "$ref": "#/components/schemas/AdTranslations" }, { "type": "null" } ] }, "updated_at": { "description": "When the ad was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "url": { "description": "The URL the ad links to, without its query string. Parameters belong in `url_parameters`; any you send on `url` are moved there.", "example": "https://shinetime.example/ceramic-coating", "type": [ "string", "null" ] }, "url_parameters": { "description": "Every query parameter appended to the URL, keyed by parameter name — including any you sent on `url` itself. Whop adds its own click-attribution parameters on top; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.", "example": {}, "type": "object" } }, "required": [ "id", "title", "platform", "status", "delivery_status", "primary_texts", "headlines", "descriptions", "call_to_action", "url", "url_parameters", "post_id", "existing_post_id", "post_source", "post_thumbnail_url", "ad_group", "ad_campaign", "creatives", "external_accounts", "created_at", "updated_at", "issues" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "example": { "status": "in_review" }, "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "ad.updated", "description": "The webhook event type", "example": "ad.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Ad Updated", "tags": [ "Ads" ] }, "x-whop-surface": "native" }, "ad_campaign.payment_failed": { "post": { "description": "Sent when an ad campaign's payment fails and its ads stop delivering. The payload carries no performance stats; read the campaign for those\n\nRequired permissions:\n - `webhook_receive:ad_campaigns`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "bid_type": null, "budget_amount": 50.0, "budget_amount_local": 50.0, "budget_currency": "usd", "budget_optimization": null, "budget_type": "daily", "campaign_type": "standard", "created_at": "2026-01-01T12:00:00.000Z", "delivery_status": "payment_failed", "id": "adcamp_xxxxxxxxxxxxxx", "issues": [], "objective": null, "optimization_goal": null, "platform": "meta", "special_ad_categories": [], "status": "payment_failed", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "ad_campaign.payment_failed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "bid_type": { "description": "How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, and `maximum_target` never bids above a cap.", "enum": [ "minimum_cost", "average_target", "maximum_target", null ], "example": "average_target", "type": [ "string", "null" ] }, "budget_amount": { "description": "The campaign's budget in USD, which is what it is stored and billed in. `null` when each ad group sets its own budget instead.", "example": 50.0, "type": [ "number", "null" ] }, "budget_amount_local": { "description": "The same budget stated in `budget_currency` at today's exchange rate, for display in the account's ads reporting currency. `null` when `budget_amount` is.", "example": 50.0, "type": [ "number", "null" ] }, "budget_currency": { "description": "The ISO 4217 code `budget_amount_local` is in: the account's `ads_reporting_currency` preference. `usd` unless the account changed it.", "example": "usd", "type": "string" }, "budget_optimization": { "description": "Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`).", "enum": [ "ad_campaign", "ad_group", null ], "example": "ad_group", "type": [ "string", "null" ] }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the campaign's full run (`lifetime`).", "enum": [ "daily", "lifetime", null ], "example": "daily", "type": [ "string", "null" ] }, "campaign_type": { "description": "The kind of campaign, fixed at creation. `standard` is the ad network's standard campaign; `search` shows text ads on search results for the ad groups' keywords.", "enum": [ "standard", "search" ], "example": "standard", "type": "string" }, "created_at": { "description": "When the campaign was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "delivery_status": { "description": "Whether the campaign's ads are delivering right now, and if not, why. Content review is in_review; a campaign waiting to start is processing. Account billing failures set payment_failed without changing the configured status. Successful payment retry clears that block and recalculates delivery. When several states apply at once, the highest-precedence one is returned.", "enum": [ "payment_failed", "in_appeal", "all_ads_rejected", "draft", "no_ad_groups", "no_ads", "paused", "in_review", "learning", "processing", "issues", "scheduled", "completed", "ad_groups_off", "active" ], "example": "issues", "type": "string" }, "desired_cost_per_result": { "description": "The cost per result, in USD, the advertiser wants this campaign to achieve. A target only: it is not a bid, cost cap, or bid cap, and doesn't change how the campaign's ads bid. `null` when no target is set.", "example": 4.5, "type": [ "number", "null" ] }, "ends_at": { "description": "Google only: when the campaign stops delivering, as an ISO 8601 timestamp. `null` runs it until paused.", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the ad campaign, prefixed `adcamp_`.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting the campaign and its descendant ad groups and ads." }, "type": "array" }, "objective": { "description": "The goal the campaign optimizes toward.", "enum": [ "awareness", "traffic", "engagement", "leads", "sales", null ], "example": "leads", "type": [ "string", "null" ] }, "optimization_goal": { "description": "The event the campaign optimizes for when a single goal is set campaign-wide. `null` when each ad group sets its own optimization_goal.", "example": null, "type": [ "string", "null" ] }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" }, "special_ad_categories": { "items": { "description": "Regulated categories the campaign is declared under. Ads in these categories are subject to extra targeting restrictions. Empty when none apply.", "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "employment", "type": "string" }, "type": "array" }, "starts_at": { "description": "Google only: when the campaign starts delivering, as an ISO 8601 timestamp. `null` starts it as soon as it launches.", "type": [ "string", "null" ] }, "status": { "description": "The configured lifecycle status of the ad campaign. Billing failures preserve active or paused here and set delivery_status to payment_failed.", "enum": [ "active", "paused", "inactive", "stale", "pending_refund", "payment_failed", "draft", "in_review", "flagged", "importing", "imported", "duplicating" ], "example": "active", "type": "string" }, "title": { "description": "Display name of the ad campaign.", "example": "Ceramic coating — Austin leads", "type": "string" }, "updated_at": { "description": "When the campaign was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "title", "status", "delivery_status", "platform", "campaign_type", "objective", "special_ad_categories", "optimization_goal", "budget_amount", "budget_amount_local", "budget_currency", "budget_type", "budget_optimization", "created_at", "updated_at", "issues" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "ad_campaign.payment_failed", "description": "The webhook event type", "example": "ad_campaign.payment_failed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Ad Campaign Payment failed", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "ad_campaign.updated": { "post": { "description": "Sent when an ad campaign's status or delivery_status changes. previous_attributes carries the values they changed from; the payload carries no performance stats\n\nRequired permissions:\n - `webhook_receive:ad_campaigns`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "bid_type": null, "budget_amount": 50.0, "budget_amount_local": 50.0, "budget_currency": "usd", "budget_optimization": null, "budget_type": "daily", "campaign_type": "standard", "created_at": "2026-01-01T12:00:00.000Z", "delivery_status": "active", "id": "adcamp_xxxxxxxxxxxxxx", "issues": [], "objective": null, "optimization_goal": null, "platform": "meta", "special_ad_categories": [], "status": "paused", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "previous_attributes": { "status": "active" }, "timestamp": "2025-01-01T00:00:00.000Z", "type": "ad_campaign.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "bid_type": { "description": "How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, and `maximum_target` never bids above a cap.", "enum": [ "minimum_cost", "average_target", "maximum_target", null ], "example": "average_target", "type": [ "string", "null" ] }, "budget_amount": { "description": "The campaign's budget in USD, which is what it is stored and billed in. `null` when each ad group sets its own budget instead.", "example": 50.0, "type": [ "number", "null" ] }, "budget_amount_local": { "description": "The same budget stated in `budget_currency` at today's exchange rate, for display in the account's ads reporting currency. `null` when `budget_amount` is.", "example": 50.0, "type": [ "number", "null" ] }, "budget_currency": { "description": "The ISO 4217 code `budget_amount_local` is in: the account's `ads_reporting_currency` preference. `usd` unless the account changed it.", "example": "usd", "type": "string" }, "budget_optimization": { "description": "Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`).", "enum": [ "ad_campaign", "ad_group", null ], "example": "ad_group", "type": [ "string", "null" ] }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the campaign's full run (`lifetime`).", "enum": [ "daily", "lifetime", null ], "example": "daily", "type": [ "string", "null" ] }, "campaign_type": { "description": "The kind of campaign, fixed at creation. `standard` is the ad network's standard campaign; `search` shows text ads on search results for the ad groups' keywords.", "enum": [ "standard", "search" ], "example": "standard", "type": "string" }, "created_at": { "description": "When the campaign was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "delivery_status": { "description": "Whether the campaign's ads are delivering right now, and if not, why. Content review is in_review; a campaign waiting to start is processing. Account billing failures set payment_failed without changing the configured status. Successful payment retry clears that block and recalculates delivery. When several states apply at once, the highest-precedence one is returned.", "enum": [ "payment_failed", "in_appeal", "all_ads_rejected", "draft", "no_ad_groups", "no_ads", "paused", "in_review", "learning", "processing", "issues", "scheduled", "completed", "ad_groups_off", "active" ], "example": "issues", "type": "string" }, "desired_cost_per_result": { "description": "The cost per result, in USD, the advertiser wants this campaign to achieve. A target only: it is not a bid, cost cap, or bid cap, and doesn't change how the campaign's ads bid. `null` when no target is set.", "example": 4.5, "type": [ "number", "null" ] }, "ends_at": { "description": "Google only: when the campaign stops delivering, as an ISO 8601 timestamp. `null` runs it until paused.", "type": [ "string", "null" ] }, "id": { "description": "Unique identifier for the ad campaign, prefixed `adcamp_`.", "example": "adcamp_xxxxxxxxxxxxxx", "type": "string" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting the campaign and its descendant ad groups and ads." }, "type": "array" }, "objective": { "description": "The goal the campaign optimizes toward.", "enum": [ "awareness", "traffic", "engagement", "leads", "sales", null ], "example": "leads", "type": [ "string", "null" ] }, "optimization_goal": { "description": "The event the campaign optimizes for when a single goal is set campaign-wide. `null` when each ad group sets its own optimization_goal.", "example": null, "type": [ "string", "null" ] }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" }, "special_ad_categories": { "items": { "description": "Regulated categories the campaign is declared under. Ads in these categories are subject to extra targeting restrictions. Empty when none apply.", "enum": [ "housing", "employment", "financial_products", "politics" ], "example": "employment", "type": "string" }, "type": "array" }, "starts_at": { "description": "Google only: when the campaign starts delivering, as an ISO 8601 timestamp. `null` starts it as soon as it launches.", "type": [ "string", "null" ] }, "status": { "description": "The configured lifecycle status of the ad campaign. Billing failures preserve active or paused here and set delivery_status to payment_failed.", "enum": [ "active", "paused", "inactive", "stale", "pending_refund", "payment_failed", "draft", "in_review", "flagged", "importing", "imported", "duplicating" ], "example": "active", "type": "string" }, "title": { "description": "Display name of the ad campaign.", "example": "Ceramic coating — Austin leads", "type": "string" }, "updated_at": { "description": "When the campaign was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "title", "status", "delivery_status", "platform", "campaign_type", "objective", "special_ad_categories", "optimization_goal", "budget_amount", "budget_amount_local", "budget_currency", "budget_type", "budget_optimization", "created_at", "updated_at", "issues" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "example": { "status": "active" }, "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "ad_campaign.updated", "description": "The webhook event type", "example": "ad_campaign.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Ad Campaign Updated", "tags": [ "Ad Campaigns" ] }, "x-whop-surface": "native" }, "ad_group.updated": { "post": { "description": "Sent when an ad group's status, delivery_status, or budget changes. previous_attributes carries the values they changed from; the payload carries no performance stats\n\nRequired permissions:\n - `webhook_receive:ad_groups`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "ad_campaign": { "id": "adcamp_xxxxxxxxxxxxxx" }, "audiences": { "exclude": [], "include": [] }, "bid_type": null, "budget_amount": 25.0, "budget_amount_local": 25.0, "budget_currency": "usd", "budget_type": "daily", "conversion_event": null, "conversion_location": null, "created_at": "2026-01-01T12:00:00.000Z", "delivery_schedule": null, "delivery_status": "active", "demographics": { "automatic": false, "gender": "all", "maximum_age": null, "minimum_age": null }, "desired_cost_per_result": null, "detailed_targeting": { "behaviors": [], "demographics": [], "interests": [] }, "devices": { "operating_systems": [], "platforms": [] }, "dynamic_creative": false, "ends_at": null, "frequency_cap": null, "id": "adgrp_xxxxxxxxxxxxxx", "issues": [], "languages": [], "learning_progress": null, "message_apps": [], "minimum_daily_spend": null, "optimization_goal": null, "placements": [], "platform": "meta", "regions": { "exclude": { "cities": [], "countries": [], "country_groups": [], "custom_locations": [], "regions": [], "zips": [] }, "include": { "cities": [], "countries": [ "US" ], "country_groups": [], "custom_locations": [], "regions": [], "zips": [] } }, "starts_at": null, "status": "paused", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "previous_attributes": { "status": "active" }, "timestamp": "2025-01-01T00:00:00.000Z", "type": "ad_group.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "ad_campaign": { "$ref": "#/components/schemas/AdEntityReference", "description": "The ad campaign this ad group belongs to." }, "audiences": { "$ref": "#/components/schemas/AdGroupAudiences", "description": "Saved audiences this ad group delivers to or excludes." }, "bid_type": { "description": "How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.", "enum": [ "minimum_cost", "average_target", "maximum_target", null ], "example": "average_target", "type": [ "string", "null" ] }, "budget_amount": { "description": "This ad group's budget in USD, which is what it is stored and billed in. `null` when the budget is set on the campaign instead.", "example": 60.0, "type": [ "number", "null" ] }, "budget_amount_local": { "description": "The same budget stated in `budget_currency` at today's exchange rate, for display in the account's ads reporting currency. `null` when `budget_amount` is.", "example": 60.0, "type": [ "number", "null" ] }, "budget_currency": { "description": "The ISO 4217 code `budget_amount_local` is in: the account's `ads_reporting_currency` preference. `usd` unless the account changed it.", "example": "usd", "type": "string" }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the ad group's full run (`lifetime`). A `lifetime` ad group also needs `ends_at`, at least 24 hours after it starts.", "enum": [ "daily", "lifetime", null ], "example": "daily", "type": [ "string", "null" ] }, "conversion_event": { "$ref": "#/components/schemas/ConversionEvent" }, "conversion_location": { "description": "Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission.", "enum": [ "website", "profile", "instagram_and_facebook", "instagram_profile", "messaging", "on_ad", "instant_forms", "instant_forms_and_messenger", "website_and_instant_forms", null ], "example": "website", "type": [ "string", "null" ] }, "created_at": { "description": "When the ad group was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "delivery_schedule": { "description": "Hours the ad group delivers in each week, keyed by day. Days it doesn't deliver are omitted. `null` when it delivers at every hour. Some platforms need a lifetime `budget_type` for a schedule, on the ad group or on its campaign when the campaign holds the budget.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupDeliverySchedule" }, { "type": "null" } ] }, "delivery_status": { "description": "Whether ads in this ad group are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.", "enum": [ "in_appeal", "all_ads_rejected", "rejected", "draft", "no_ads", "campaign_paused", "paused", "processing", "issues", "scheduled", "completed", "ads_off", "learning_limited", "learning", "active" ], "example": "no_ads", "type": "string" }, "demographics": { "$ref": "#/components/schemas/AdGroupDemographics", "description": "Age, gender, and automatic-audience targeting." }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`). `null` for `minimum_cost` bidding.", "example": 40.0, "type": [ "number", "null" ] }, "detailed_targeting": { "$ref": "#/components/schemas/AdGroupDetailedTargeting", "description": "Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. Can't be combined with automatic audience targeting. Special ad category campaigns are limited to approved interests." }, "devices": { "$ref": "#/components/schemas/AdGroupDevices", "description": "Device platforms and operating systems targeted." }, "dynamic_creative": { "description": "Whether the ad platform automatically mixes and matches this ad group's creatives and copy to find the best-performing combinations.", "example": false, "type": "boolean" }, "ends_at": { "description": "When the ad group stops delivering, as an ISO 8601 timestamp. `null` when it runs until paused.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "frequency_cap": { "description": "Cap on how often one person sees ads from this ad group, or from the whole campaign under a campaign budget, where every ad group shares it. Only available when the ad group optimizes for reach or ThruPlay; `null` when uncapped.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupFrequencyCap" }, { "type": "null" } ] }, "id": { "description": "Unique identifier for the ad group, prefixed `adgrp_`.", "example": "adgrp_xxxxxxxxxxxxxx", "type": "string" }, "issues": { "items": { "$ref": "#/components/schemas/AdPlatformIssue", "description": "Open issues affecting this ad group and its ads. Empty when there are none." }, "type": "array" }, "keywords": { "items": { "$ref": "#/components/schemas/AdGroupKeyword", "description": "Search terms this ad group's ads can show for, and terms they never show for. Search campaigns only, where each ad group needs at least one before launch." }, "type": "array" }, "languages": { "items": { "description": "Languages targeted, as ISO 639 codes such as `en` or `es`. A region-specific locale with no ISO code appears as its numeric platform locale key. Empty targets all languages.", "example": "en", "type": "string" }, "type": "array" }, "learning_progress": { "description": "Progress toward the ad platform's learning conversion threshold for this ad group. Null unless it is learning or learning limited and the platform reports valid counts. Reaching the threshold does not determine delivery status.", "oneOf": [ { "$ref": "#/components/schemas/AdGroupLearningProgress" }, { "type": "null" } ] }, "message_apps": { "items": { "description": "Apps the conversation opens in when `conversion_location` is `messaging`. Empty for other conversion locations.", "enum": [ "messenger", "instagram", "whatsapp" ], "example": "instagram", "type": "string" }, "type": "array" }, "minimum_daily_spend": { "description": "Minimum the ad group tries to spend each day. `null` when no floor is set.", "example": 25.0, "type": [ "number", "null" ] }, "optimization_goal": { "description": "The result the ad group's delivery is optimized to get the most of.", "enum": [ "conversions", "link_clicks", "landing_page_views", "reach", "impressions", "engagement", "conversations", "video_views", "two_second_views", "page_likes", "social_profile", "ad_recall_lift", "event_responses", "reminders_set", "lead_generation", "quality_lead", "value", "profile_and_page_engagement", null ], "example": "conversions", "type": [ "string", "null" ] }, "placements": { "items": { "$ref": "#/components/schemas/AdGroupPlacement", "description": "Where ads can appear, per platform. Empty when placements are chosen automatically." }, "type": "array" }, "platform": { "description": "The ad platform this ad group runs on.", "enum": [ "meta", "tiktok", "google" ], "example": "meta", "type": "string" }, "regions": { "$ref": "#/components/schemas/AdGroupRegions", "description": "Locations targeted and excluded." }, "starts_at": { "description": "When the ad group starts delivering, as an ISO 8601 timestamp. `null` when it starts as soon as it's active.", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "status": { "description": "Whether the ad group is enabled. `active` and `paused` are set by you; `rejected` means it failed ad review; `duplicating` is a copy still being filled in.", "enum": [ "active", "paused", "rejected", "duplicating" ], "example": "active", "type": "string" }, "title": { "description": "Display name of the ad group.", "example": "Austin ceramic coating — repeat customers", "type": [ "string", "null" ] }, "updated_at": { "description": "When the ad group was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" } }, "required": [ "id", "title", "platform", "status", "delivery_status", "learning_progress", "optimization_goal", "conversion_event", "budget_amount", "budget_amount_local", "budget_currency", "budget_type", "bid_type", "desired_cost_per_result", "starts_at", "ends_at", "delivery_schedule", "regions", "demographics", "detailed_targeting", "audiences", "languages", "devices", "frequency_cap", "placements", "ad_campaign", "created_at", "updated_at", "issues" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "example": { "status": "active" }, "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "ad_group.updated", "description": "The webhook event type", "example": "ad_group.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Ad Group Updated", "tags": [ "Ad Groups" ] }, "x-whop-surface": "native" }, "app_installation.created": { "post": { "description": "Sent to your app's own webhooks when an account installs your app, including when an account that removed it installs it again. A reinstall keeps the installation's `id`, `created_at`, and `metadata`. The envelope's `account_id` is the installing account\n\nRequired permissions:\n - `webhook_receive:app_installations`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxx2", "title": "Shine Time Auto Detailing" }, "app": { "developer": { "id": "biz_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "icon": { "url": "https://pub-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.dev/custom-perk-icon.svg" }, "id": "app_xxxxxxxxxxxxxx", "name": "Marcus Webb" }, "created_at": "2026-01-01T12:00:00.000Z", "external_id": "shinetime", "id": "aag_xxxxxxxxxxxxxx", "metadata": { "last_synced_at": "2026-01-01T12:00:00.000Z", "store_handle": "shinetime" }, "requesting_reauthorization": false, "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "app_installation.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/AppInstallation" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "app_installation.created", "description": "The webhook event type", "example": "app_installation.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "App Installation Created", "tags": [ "App Installations" ] }, "x-whop-surface": "native" }, "app_installation.deleted": { "post": { "description": "Sent to your app's own webhooks when an account removes your app. The installation stops appearing in `GET /app_installations`, and your app can no longer act on that account. The envelope's `account_id` is the account that removed it\n\nRequired permissions:\n - `webhook_receive:app_installations`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxx2", "title": "Shine Time Auto Detailing" }, "app": { "developer": { "id": "biz_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "icon": { "url": "https://pub-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.dev/custom-perk-icon.svg" }, "id": "app_xxxxxxxxxxxxxx", "name": "Marcus Webb" }, "created_at": "2026-01-01T12:00:00.000Z", "external_id": "shinetime", "id": "aag_xxxxxxxxxxxxxx", "metadata": { "last_synced_at": "2026-01-01T12:00:00.000Z", "store_handle": "shinetime" }, "requesting_reauthorization": false, "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "app_installation.deleted" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/AppInstallation" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "app_installation.deleted", "description": "The webhook event type", "example": "app_installation.deleted", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "App Installation Deleted", "tags": [ "App Installations" ] }, "x-whop-surface": "native" }, "card.canceled": { "post": { "description": "Sent when a card is canceled\n\nRequired permissions:\n - `webhook_receive:cards`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "billing": null, "canceled_at": null, "created_at": "2026-01-01T12:00:00.000Z", "expiration_month": null, "expiration_year": null, "id": "icrd_xxxxxxxxxxxxxx", "last4": "4242", "limit": null, "name": null, "object": "card", "spent_last_month": 0, "status": "active", "type": "virtual", "user_id": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card.canceled" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card.canceled", "description": "The webhook event type", "example": "card.canceled", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Canceled", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card.created": { "post": { "description": "Sent when a card is created\n\nRequired permissions:\n - `webhook_receive:cards`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "billing": null, "canceled_at": null, "created_at": "2026-01-01T12:00:00.000Z", "expiration_month": null, "expiration_year": null, "id": "icrd_xxxxxxxxxxxxxx", "last4": "4242", "limit": null, "name": null, "object": "card", "spent_last_month": 0, "status": "active", "type": "virtual", "user_id": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card.created", "description": "The webhook event type", "example": "card.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Created", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card.frozen": { "post": { "description": "Sent when a card is frozen\n\nRequired permissions:\n - `webhook_receive:cards`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "billing": null, "canceled_at": null, "created_at": "2026-01-01T12:00:00.000Z", "expiration_month": null, "expiration_year": null, "id": "icrd_xxxxxxxxxxxxxx", "last4": "4242", "limit": null, "name": null, "object": "card", "spent_last_month": 0, "status": "active", "type": "virtual", "user_id": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card.frozen" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card.frozen", "description": "The webhook event type", "example": "card.frozen", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Frozen", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card.updated": { "post": { "description": "Sent when a card is updated\n\nRequired permissions:\n - `webhook_receive:cards`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "billing": null, "canceled_at": null, "created_at": "2026-01-01T12:00:00.000Z", "expiration_month": null, "expiration_year": null, "id": "icrd_xxxxxxxxxxxxxx", "last4": "4242", "limit": null, "name": null, "object": "card", "spent_last_month": 0, "status": "active", "type": "virtual", "user_id": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "billing": { "description": "The billing address.", "properties": { "city": { "description": "Billing city.", "example": "Austin", "type": [ "string", "null" ] }, "country_code": { "description": "Billing country code.", "example": "US", "type": [ "string", "null" ] }, "line1": { "description": "Street address line 1.", "example": "4180 Burnet Rd", "type": [ "string", "null" ] }, "line2": { "description": "Street address line 2.", "example": "Suite 210", "type": [ "string", "null" ] }, "postal_code": { "description": "Billing postal code.", "example": "78756", "type": [ "string", "null" ] }, "region": { "description": "Billing region or state.", "example": "TX", "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country_code" ], "type": [ "object", "null" ] }, "canceled_at": { "description": "When the card was canceled.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the card was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "expiration_month": { "description": "Card expiration month.", "example": "12", "type": [ "string", "null" ] }, "expiration_year": { "description": "Card expiration year.", "example": "2027", "type": [ "string", "null" ] }, "id": { "description": "Card ID, prefixed `icrd_`.", "example": "icrd_xxxxxxxxxxxxxx", "type": "string" }, "last4": { "description": "Last four digits of the card number. `null` for pending invitation cards.", "example": "4242", "type": [ "string", "null" ] }, "limit": { "description": "The spending limit configuration.", "properties": { "amount": { "description": "The limit amount in dollars.", "example": 50.0, "type": "number" }, "frequency": { "description": "The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.", "enum": [ "daily", "weekly", "monthly", "one_time", "per_transaction" ], "example": "daily", "type": "string" } }, "required": [ "amount", "frequency" ], "type": [ "object", "null" ] }, "name": { "description": "Card display name.", "example": "Bay rent card", "type": [ "string", "null" ] }, "object": { "enum": [ "card" ], "example": "card", "type": "string" }, "secrets": { "description": "Sensitive card details. Present only on `GET /cards/:id` for active cards; `null` when the card is inactive or details cannot be retrieved.", "properties": { "card_number": { "description": "Full card number.", "example": "4242424242424242", "type": "string" }, "cvc": { "description": "Card verification code.", "example": "123", "type": "string" }, "name_on_card": { "description": "Cardholder name printed on the card.", "example": "Tanya Cole", "type": [ "string", "null" ] }, "pin": { "description": "The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.", "example": "1234", "type": [ "string", "null" ] } }, "required": [ "card_number", "cvc", "name_on_card", "pin" ], "type": [ "object", "null" ] }, "spent_last_month": { "description": "Total spend in the last 30 days, in cents.", "example": 1234, "type": [ "integer", "null" ] }, "status": { "description": "The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.", "enum": [ null, "active", "frozen", "canceled", "invited", "denied" ], "example": "active", "type": [ "string", "null" ] }, "type": { "description": "The card type.", "enum": [ null, "virtual", "physical" ], "example": "virtual", "type": [ "string", "null" ] }, "user_id": { "description": "Cardholder user ID, prefixed `user_`, when assigned.", "example": "user_xxxxxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "type", "status", "last4", "expiration_month", "expiration_year", "user_id", "spent_last_month", "limit", "billing", "created_at", "canceled_at" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card.updated", "description": "The webhook event type", "example": "card.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Updated", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_application.approved": { "post": { "description": "Sent when a card application is approved\n\nRequired permissions:\n - `webhook_receive:card_applications`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "hosted_url": null, "id": "ciac_xxxxxxxxxxxxxx", "object": "card_application", "status": "approved" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_application.approved" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_application.approved", "description": "The webhook event type", "example": "card_application.approved", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Application Approved", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_application.created": { "post": { "description": "Sent when a card application is created\n\nRequired permissions:\n - `webhook_receive:card_applications`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "hosted_url": null, "id": "ciac_xxxxxxxxxxxxxx", "object": "card_application", "status": "approved" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_application.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_application.created", "description": "The webhook event type", "example": "card_application.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Application Created", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_application.denied": { "post": { "description": "Sent when a card application is denied\n\nRequired permissions:\n - `webhook_receive:card_applications`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "hosted_url": null, "id": "ciac_xxxxxxxxxxxxxx", "object": "card_application", "status": "approved" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_application.denied" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_application.denied", "description": "The webhook event type", "example": "card_application.denied", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Application Denied", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_application.updated": { "post": { "description": "Sent when a card application is updated\n\nRequired permissions:\n - `webhook_receive:card_applications`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "hosted_url": null, "id": "ciac_xxxxxxxxxxxxxx", "object": "card_application", "status": "approved" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_application.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "hosted_url": { "description": "URL where the applicant completes additional identity verification.", "example": "https://verify.raincards.xyz/onboarding/shine-time-auto-detailing", "type": [ "string", "null" ] }, "id": { "description": "Card application ID, prefixed `ciac_`.", "example": "ciac_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "card_application" ], "example": "card_application", "type": "string" }, "status": { "description": "The application status.", "enum": [ "approved", "pending", "manual_review", "denied", "locked", "canceled", "needs_verification", "needs_information" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "status", "hosted_url" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_application.updated", "description": "The webhook event type", "example": "card_application.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Application Updated", "tags": [ "Cards" ] }, "x-whop-surface": "native" }, "card_transaction.completed": { "post": { "description": "Sent when a card transaction is completed\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 0.25, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": null, "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": "2026-01-02T12:00:00.000Z", "status": "completed", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_transaction.completed", "description": "The webhook event type", "example": "card_transaction.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Transaction Completed", "tags": [ "Cards" ], "x-group-title": "Cards" }, "x-whop-surface": "native" }, "card_transaction.created": { "post": { "description": "Sent when a card transaction is created\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": null, "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": null, "status": "pending", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_transaction.created", "description": "The webhook event type", "example": "card_transaction.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Transaction Created", "tags": [ "Cards" ], "x-group-title": "Cards" }, "x-whop-surface": "native" }, "card_transaction.declined": { "post": { "description": "Sent when a card transaction is declined\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": "Insufficient funds", "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": null, "status": "declined", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.declined" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_transaction.declined", "description": "The webhook event type", "example": "card_transaction.declined", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Transaction Declined", "tags": [ "Cards" ], "x-group-title": "Cards" }, "x-whop-surface": "native" }, "card_transaction.reversed": { "post": { "description": "Sent when a card transaction is reversed\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": null, "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": "2026-01-02T12:00:00.000Z", "status": "reversed", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.reversed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_transaction.reversed", "description": "The webhook event type", "example": "card_transaction.reversed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Transaction Reversed", "tags": [ "Cards" ], "x-group-title": "Cards" }, "x-whop-surface": "native" }, "card_transaction.updated": { "post": { "description": "Sent when a card transaction is updated\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:card_transactions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 0.25, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "declined_reason": null, "id": "citx_xxxxxxxxxxxxxx", "international": false, "local_amount": 12.5, "merchant_category": "Auto Parts & Accessories", "merchant_category_code": "5533", "merchant_icon_url": null, "merchant_name": "Austin Detail Supply", "posted_at": "2026-01-02T12:00:00.000Z", "status": "completed", "transaction_type": "spend", "usd_amount": 12.5 }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "card_transaction.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CardTransaction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "card_transaction.updated", "description": "The webhook event type", "example": "card_transaction.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Card Transaction Updated", "tags": [ "Cards" ], "x-group-title": "Cards" }, "x-whop-surface": "native" }, "chat.message.created": { "post": { "description": "Sent when a chat event is created\n\nRequired permissions:\n - `webhook_receive:chat`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "audience": { "type": "channel", "user_ids": [ "user_xxxxxxxxxxxxxx", "user_xxxxxxxxxxxxxx" ] }, "channel": { "experience_id": "exp_xxxxxxxxxxxxxx", "id": "feed_xxxxxxxxxxxxxx", "type": "chat" }, "message": { "content": "Hey, are you available for a **quick call**?", "created_at": "2023-12-01T05:00:00.401Z", "id": "some_string", "is_edited": true, "is_pinned": true, "mentions": [ "some_string", "some_string" ], "mentions_everyone": true, "message_type": "regular", "poll": { "options": [ { "id": "some_string", "text": "some_string" }, { "id": "some_string", "text": "some_string" } ] }, "poll_votes": [ { "count": 42, "option_id": "some_string" }, { "count": 42, "option_id": "some_string" } ], "reaction_counts": [ { "count": 42, "emoji": "some_string" }, { "count": 42, "emoji": "some_string" } ], "replying_to_message_id": "some_string", "updated_at": "2023-12-01T05:00:00.401Z", "user": { "id": "user_xxxxxxxxxxxxx", "name": "John Doe", "username": "johndoe42" }, "view_count": 42 }, "reason": "channel_message" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "chat.message.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "audience": { "properties": { "type": { "enum": [ "channel", "users" ], "example": "channel", "type": "string" }, "user_ids": { "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "type" ], "type": "object" }, "channel": { "properties": { "experience_id": { "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "example": "feed_xxxxxxxxxxxxxx", "type": "string" }, "type": { "enum": [ "chat", "direct_message", "support" ], "example": "chat", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "message": { "$ref": "#/components/schemas/Message" }, "reason": { "example": "channel_message", "type": "string" } }, "required": [ "reason", "audience", "channel", "message" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "chat.message.created", "description": "The webhook event type", "example": "chat.message.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Chat Message Created", "tags": [ "Messages" ] } }, "chat.reaction.created": { "post": { "description": "Sent when a chat event is created\n\nRequired permissions:\n - `webhook_receive:chat`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "audience": { "type": "channel", "user_ids": [ "user_xxxxxxxxxxxxxx", "user_xxxxxxxxxxxxxx" ] }, "channel": { "experience_id": "exp_xxxxxxxxxxxxxx", "id": "feed_xxxxxxxxxxxxxx", "type": "chat" }, "message": { "content": "Hey, are you available for a **quick call**?", "created_at": "2023-12-01T05:00:00.401Z", "id": "some_string", "is_edited": true, "is_pinned": true, "mentions": [ "some_string", "some_string" ], "mentions_everyone": true, "message_type": "regular", "poll": { "options": [ { "id": "some_string", "text": "some_string" }, { "id": "some_string", "text": "some_string" } ] }, "poll_votes": [ { "count": 42, "option_id": "some_string" }, { "count": 42, "option_id": "some_string" } ], "reaction_counts": [ { "count": 42, "emoji": "some_string" }, { "count": 42, "emoji": "some_string" } ], "replying_to_message_id": "some_string", "updated_at": "2023-12-01T05:00:00.401Z", "user": { "id": "user_xxxxxxxxxxxxx", "name": "John Doe", "username": "johndoe42" }, "view_count": 42 }, "reaction": { "emoji": ":heart:", "id": "reac_xxxxxxxxxxxxxxxxxxxxxx", "resource_id": "some_string", "user": { "id": "user_xxxxxxxxxxxxx", "name": "John Doe", "username": "johndoe42" } }, "reason": "message_reaction" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "chat.reaction.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "audience": { "properties": { "type": { "enum": [ "channel", "users" ], "example": "channel", "type": "string" }, "user_ids": { "items": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "type" ], "type": "object" }, "channel": { "properties": { "experience_id": { "example": "exp_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "id": { "example": "feed_xxxxxxxxxxxxxx", "type": "string" }, "type": { "enum": [ "chat", "direct_message", "support" ], "example": "chat", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "message": { "$ref": "#/components/schemas/Message" }, "reaction": { "$ref": "#/components/schemas/Reaction" }, "reason": { "example": "message_reaction", "type": "string" } }, "required": [ "reason", "audience", "channel", "message", "reaction" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "chat.reaction.created", "description": "The webhook event type", "example": "chat.reaction.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Chat Reaction Created", "tags": [ "Reactions" ] } }, "course_lesson_interaction.completed": { "post": { "description": "Sent when a course lesson interaction is completed\n\nRequired permissions:\n - `courses:read`\n - `course_analytics:read`\n - `webhook_receive:courses`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "completed": true, "course": { "experience": { "id": "exp_xxxxxxxxxxxxxx" }, "id": "cors_xxxxxxxxxxxxx", "title": "Introduction to Technical Analysis" }, "created_at": "2023-12-01T05:00:00.401Z", "id": "crsli_xxxxxxxxxxxx", "lesson": { "chapter": { "id": "chap_xxxxxxxxxxxxx" }, "id": "lesn_xxxxxxxxxxxxx", "title": "Understanding Candlestick Patterns" }, "user": { "id": "user_xxxxxxxxxxxxx", "name": "John Doe", "username": "johndoe42" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "course_lesson_interaction.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/CourseLessonInteraction" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "course_lesson_interaction.completed", "description": "The webhook event type", "example": "course_lesson_interaction.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "CourseLessonInteraction Completed", "tags": [ "Course lesson interactions" ], "x-group-title": "Courses" } }, "deposit.succeeded": { "post": { "description": "Sent when a crypto or bank deposit is credited to a business account's balance. A crypto deposit has line_type `onchain_deposit` and an `onchain_transaction` source; a bank deposit has line_type `topup` and a `bank_deposit` source. Deposits to personal accounts, payouts into the account's own Whop wallet, and ledger corrections are not sent\n\nRequired permissions:\n - `webhook_receive:deposits`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": "75000000000", "available_at": null, "currency": { "code": "usdc", "precision": "100000000" }, "id": "line_5", "line_type": "onchain_deposit", "object": "ledger_activity", "posted_at": "2026-01-02T12:00:00.000Z", "resource": null, "source": { "chain": "plasma", "id": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "object": "onchain_transaction", "sender_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "tx_hash": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }, "usd_amount": "750.0" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "deposit.succeeded" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/LedgerActivity" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "deposit.succeeded", "description": "The webhook event type", "example": "deposit.succeeded", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Deposit Succeeded", "tags": [ "Deposits" ] }, "x-whop-surface": "native" }, "dispute.created": { "post": { "description": "Sent when a dispute is created\n\nRequired permissions:\n - `payment:dispute:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `company:basic:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `webhook_receive:disputes`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "acceptable": true, "account_id": "biz_xxxxxxxxxxxxxx", "amount": 150.0, "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy_attachment": null, "cancellation_policy_disclosure": null, "customer_communication_attachment": null, "customer_email_address": null, "customer_name": null, "documents": [], "notes": null, "product_description": null, "refund_policy_attachment": null, "refund_policy_disclosure": null, "refund_refusal_explanation": null, "service_date": null, "uncategorized_attachment": null }, "evidence_due_at": "2026-01-01T12:00:00.000Z", "evidence_editable": true, "evidence_locked_reason": null, "evidence_submitted_at": null, "fee": null, "id": "dspt_xxxxxxxxxxxxxx", "inquiry": false, "issuer_comments": [], "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": null, "subtotal": null, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "payment": { "amount": 0.0, "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "id": "pay_xxxxxxxxxxxxxx", "payment_instrument": null, "payment_method_type": null, "payment_processor": null }, "product_id": "prod_xxxxxxxxxxxxxx", "reason": "fraudulent", "reason_code": null, "status": "needs_response", "updated_at": "2026-01-01T12:00:00.000Z", "variant_id": "plan_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "dispute.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Dispute" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "dispute.created", "description": "The webhook event type", "example": "dispute.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Dispute Created", "tags": [ "Disputes" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "dispute.updated": { "post": { "description": "Sent when a dispute is updated\n\nRequired permissions:\n - `payment:dispute:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `company:basic:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `webhook_receive:disputes`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "acceptable": false, "account_id": "biz_xxxxxxxxxxxxxx", "amount": 150.0, "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy_attachment": null, "cancellation_policy_disclosure": null, "customer_communication_attachment": null, "customer_email_address": "marcus@shinetime.example", "customer_name": "Dana Whitfield", "documents": [], "notes": null, "product_description": "Two-day ceramic coating service, completed as scheduled on the booked date.", "refund_policy_attachment": null, "refund_policy_disclosure": null, "refund_refusal_explanation": null, "service_date": "2026-01-01", "uncategorized_attachment": null }, "evidence_due_at": "2026-01-01T12:00:00.000Z", "evidence_editable": false, "evidence_locked_reason": "submitted", "evidence_submitted_at": "2026-01-01T12:00:00.000Z", "fee": null, "id": "dspt_xxxxxxxxxxxxxx", "inquiry": false, "issuer_comments": [], "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": null, "subtotal": null, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "payment": { "amount": 0.0, "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "id": "pay_xxxxxxxxxxxxxx", "payment_instrument": null, "payment_method_type": null, "payment_processor": null }, "product_id": "prod_xxxxxxxxxxxxxx", "reason": "fraudulent", "reason_code": null, "status": "under_review", "updated_at": "2026-01-01T12:00:00.000Z", "variant_id": "plan_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "dispute.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Dispute" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "dispute.updated", "description": "The webhook event type", "example": "dispute.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Dispute Updated", "tags": [ "Disputes" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "dispute_alert.created": { "post": { "description": "Sent when a dispute alert is created\n\nRequired permissions:\n - `payment:dispute_alert:read`\n - `payment:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `payment:dispute:read`\n - `webhook_receive:disputes`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": null, "amount": 25.0, "auto_refunded": false, "card_brand": "visa", "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "fee": null, "fee_charged": false, "id": "dspa_xxxxxxxxxxxxxx", "issuer": null, "payment_id": null, "product_id": null, "reported_at": "2026-01-01T12:00:00.000Z", "source": "cdrn", "transaction_at": "2026-01-01T12:00:00.000Z", "type": "dispute_alert", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "dispute_alert.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/DisputeAlert" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "dispute_alert.created", "description": "The webhook event type", "example": "dispute_alert.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Dispute Alert Created", "tags": [ "Dispute alerts" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "domain.created": { "post": { "description": "Sent when a domain is added to the account, including domains Whop adds itself, such as an Apple Pay domain registered when checkout loads on a new site or a site the Whop pixel sees traffic from, and a deleted domain that comes back\n\nRequired permissions:\n - `webhook_receive:domains`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "apple_pay": null, "availability": null, "created_at": "2026-01-01T12:00:00.000Z", "domain": "checkout.webbsdetailing.com", "email": null, "id": "dom_xxxxxxxxxxxxxx", "issues": [], "metadata": {}, "owned_by": null, "pixel": null, "platform": null, "public_record": null, "registration": null, "stats": { "unique_visitors_last_7_days": 0 }, "status": "idle", "transfer": null, "updated_at": "2026-01-01T12:00:00.000Z", "verification": null, "website": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "domain.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Domain" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "domain.created", "description": "The webhook event type", "example": "domain.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Domain Created", "tags": [ "Domains" ] }, "x-whop-surface": "native" }, "domain.deleted": { "post": { "description": "Sent when a domain is deleted, including when Whop removes a domain it added once nothing uses it. The payload is the domain as it was when it was deleted\n\nRequired permissions:\n - `webhook_receive:domains`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "apple_pay": null, "availability": null, "created_at": "2026-01-01T12:00:00.000Z", "domain": "checkout.webbsdetailing.com", "email": null, "id": "dom_xxxxxxxxxxxxxx", "issues": [], "metadata": {}, "owned_by": null, "pixel": null, "platform": null, "public_record": null, "registration": null, "stats": { "unique_visitors_last_7_days": 0 }, "status": "idle", "transfer": null, "updated_at": "2026-01-01T12:00:00.000Z", "verification": null, "website": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "domain.deleted" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Domain" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "domain.deleted", "description": "The webhook event type", "example": "domain.deleted", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Domain Deleted", "tags": [ "Domains" ] }, "x-whop-surface": "native" }, "domain.updated": { "post": { "description": "Sent when a domain's fields change, such as its status or a capability's state, verification, or issues. previous_attributes carries the previous values of the fields that changed\n\nRequired permissions:\n - `webhook_receive:domains`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "apple_pay": null, "availability": null, "created_at": "2026-01-01T12:00:00.000Z", "domain": "checkout.webbsdetailing.com", "email": null, "id": "dom_xxxxxxxxxxxxxx", "issues": [], "metadata": {}, "owned_by": null, "pixel": null, "platform": null, "public_record": null, "registration": null, "stats": { "unique_visitors_last_7_days": 0 }, "status": "idle", "transfer": null, "updated_at": "2026-01-01T12:00:00.000Z", "verification": null, "website": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "domain.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Domain" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "domain.updated", "description": "The webhook event type", "example": "domain.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Domain Updated", "tags": [ "Domains" ] }, "x-whop-surface": "native" }, "entry.approved": { "post": { "description": "Sent when a entry is approved\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`\n - `webhook_receive:entries`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "created_at": "2026-01-01T12:00:00.000Z", "custom_field_responses": [ { "answer": "2022 Tesla Model 3, white", "id": "cfrp_xxxxxxxxxxxxxx", "question": "What vehicle are we detailing?" } ], "id": "entry_xxxxxxxxxxxxxx", "plan": { "id": "plan_xxxxxxxxxxxxxx" }, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "approved", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "entry.approved" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "entry.approved", "description": "The webhook event type", "example": "entry.approved", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Entry Approved", "tags": [ "Entries" ], "x-group-title": "CRM" } }, "entry.created": { "post": { "description": "Sent when a entry is created\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`\n - `webhook_receive:entries`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "created_at": "2026-01-01T12:00:00.000Z", "custom_field_responses": [ { "answer": "2022 Tesla Model 3, white", "id": "cfrp_xxxxxxxxxxxxxx", "question": "What vehicle are we detailing?" } ], "id": "entry_xxxxxxxxxxxxxx", "plan": { "id": "plan_xxxxxxxxxxxxxx" }, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "pending", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "entry.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "entry.created", "description": "The webhook event type", "example": "entry.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Entry Created", "tags": [ "Entries" ], "x-group-title": "CRM" } }, "entry.deleted": { "post": { "description": "Sent when a entry is deleted\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`\n - `webhook_receive:entries`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "created_at": "2026-01-01T12:00:00.000Z", "custom_field_responses": [ { "answer": "2022 Tesla Model 3, white", "id": "cfrp_xxxxxxxxxxxxxx", "question": "What vehicle are we detailing?" } ], "id": "entry_xxxxxxxxxxxxxx", "plan": { "id": "plan_xxxxxxxxxxxxxx" }, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "pending", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "entry.deleted" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "entry.deleted", "description": "The webhook event type", "example": "entry.deleted", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Entry Deleted", "tags": [ "Entries" ], "x-group-title": "CRM" } }, "entry.denied": { "post": { "description": "Sent when a entry is denied\n\nRequired permissions:\n - `plan:waitlist:read`\n - `member:email:read`\n - `webhook_receive:entries`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "created_at": "2026-01-01T12:00:00.000Z", "custom_field_responses": [ { "answer": "2022 Tesla Model 3, white", "id": "cfrp_xxxxxxxxxxxxxx", "question": "What vehicle are we detailing?" } ], "id": "entry_xxxxxxxxxxxxxx", "plan": { "id": "plan_xxxxxxxxxxxxxx" }, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "denied", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "entry.denied" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Entry" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "entry.denied", "description": "The webhook event type", "example": "entry.denied", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Entry Denied", "tags": [ "Entries" ], "x-group-title": "CRM" } }, "export.completed": { "post": { "description": "Sent when an export is completed\n\nRequired permissions:\n - `webhook_receive:exports`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "created_at": "2026-01-01T12:00:00.000Z", "download_url": "https://s3.amazonaws.com/uploads/exports/members-export.csv", "expires_at": "2026-01-01T12:00:00.000Z", "id": "exprt_xxxxxxxxxxxxxx", "progress_percent": null, "resource": "members", "status": "completed", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "export.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Export" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "export.completed", "description": "The webhook event type", "example": "export.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Export Completed", "tags": [ "Exports" ] }, "x-whop-surface": "native" }, "export.failed": { "post": { "description": "Sent when an export is failed\n\nRequired permissions:\n - `webhook_receive:exports`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "created_at": "2026-01-01T12:00:00.000Z", "download_url": null, "expires_at": "2026-01-01T12:00:00.000Z", "id": "exprt_xxxxxxxxxxxxxx", "progress_percent": null, "resource": "members", "status": "failed", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "export.failed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Export" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "export.failed", "description": "The webhook event type", "example": "export.failed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Export Failed", "tags": [ "Exports" ] }, "x-whop-surface": "native" }, "financial_activity.funds_available": { "post": { "description": "Sent when a settlement moves one release date's pending funds into the account's available balance — one event per release date that cleared, carrying that settlement's ledger line. Its posted_at is the release date at midnight UTC, the same value as settlement_time_at on every payment it clears\n\nRequired permissions:\n - `webhook_receive:financial_activity`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": "512345000000", "available_at": "2026-01-01T12:00:00.000Z", "currency": { "code": "usd", "precision": "100000000" }, "id": "line_7", "line_type": "account_settlement", "object": "ledger_activity", "posted_at": "2026-01-02T12:00:00.000Z", "resource": null, "source": { "id": "wallet_release_date_settlement|ldgr_xxxxxxxxxxxxxx|2026-01-01|usd", "object": "settlement", "release_date": "2026-01-01", "settled_at": "2026-01-01T12:00:00.000Z" }, "usd_amount": "5123.45" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "financial_activity.funds_available" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/LedgerActivity" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "financial_activity.funds_available", "description": "The webhook event type", "example": "financial_activity.funds_available", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Financial Activity Funds available", "tags": [ "Ledgers" ] }, "x-whop-surface": "native" }, "identity_profile.updated": { "post": { "description": "Sent whenever an identity profile changes state — a verification is approved, needs action, or is rejected, or a Whop review opens or clears. Every other identity_profile event is also delivered as an identity_profile.updated, so you can subscribe to this single event and re-fetch the verification to read its current status.\n\nRequired permissions:\n - `identity:read`\n - `webhook_receive:identity_profiles`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "id": "idpf_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "identity_profile.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "id": { "description": "The identity profile id (`idpf_`). Re-fetch `GET /verifications` for its current state.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "identity_profile.updated", "description": "The webhook event type", "example": "identity_profile.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "IdentityProfile Updated", "tags": [ "Verifications" ], "x-group-title": "Payouts" }, "x-whop-surface": "native" }, "invoice.created": { "post": { "description": "Sent when a invoice is created\n\nRequired permissions:\n - `invoice:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `payment:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx", "logo": null, "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "billing_period": 30, "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "initial_price": 0.0, "plan_type": "renewal", "renewal_price": 50.0, "trial_period_days": null }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "open", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/InvoiceLegacy" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.created", "description": "The webhook event type", "example": "invoice.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Created", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "invoice.marked_uncollectible": { "post": { "description": "Sent when a invoice is marked uncollectible\n\nRequired permissions:\n - `invoice:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `payment:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx", "logo": null, "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "billing_period": 30, "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "initial_price": 0.0, "plan_type": "renewal", "renewal_price": 50.0, "trial_period_days": null }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "uncollectible", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.marked_uncollectible" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/InvoiceLegacy" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.marked_uncollectible", "description": "The webhook event type", "example": "invoice.marked_uncollectible", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Marked uncollectible", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "invoice.paid": { "post": { "description": "Sent when a invoice is paid\n\nRequired permissions:\n - `invoice:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `payment:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx", "logo": null, "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "billing_period": 30, "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "initial_price": 0.0, "plan_type": "renewal", "renewal_price": 50.0, "trial_period_days": null }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "paid", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.paid" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/InvoiceLegacy" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.paid", "description": "The webhook event type", "example": "invoice.paid", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Paid", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "invoice.past_due": { "post": { "description": "Sent when a invoice is past due\n\nRequired permissions:\n - `invoice:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `payment:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx", "logo": null, "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "billing_period": 30, "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "initial_price": 0.0, "plan_type": "renewal", "renewal_price": 50.0, "trial_period_days": null }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "past_due", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.past_due" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/InvoiceLegacy" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.past_due", "description": "The webhook event type", "example": "invoice.past_due", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Past due", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "invoice.voided": { "post": { "description": "Sent when a invoice is voided\n\nRequired permissions:\n - `invoice:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `payment:basic:read`\n - `webhook_receive:invoices`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "automatically_finalizes_at": null, "charge_buyer_fee": false, "collection_method": "send_invoice", "company": { "id": "biz_xxxxxxxxxxxxxx", "logo": null, "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "current_plan": { "billing_period": 30, "currency": "usd", "description": "One maintenance wash per week, any vehicle on file.", "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "initial_price": 0.0, "plan_type": "renewal", "renewal_price": 50.0, "trial_period_days": null }, "customer_name": "Dana Whitfield", "due_date": "2026-01-01T12:00:00.000Z", "email_address": "marcus@shinetime.example", "fetch_invoice_token": "example_invoice_token", "id": "inv_xxxxxxxxxxxxxx", "line_items": [ { "label": "Two-stage paint correction", "position": 0, "quantity": 1.0, "total": 199.0, "unit_price": 199.0 }, { "label": "Interior shampoo add-on", "position": 1, "quantity": 1.0, "total": 49.0, "unit_price": 49.0 } ], "mailing_address": null, "member": { "id": "mber_xxxxxxxxxxxxxx" }, "number": "INV-0001", "pay_online_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "payment": null, "payment_processing": false, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "status": "void", "subscription_billing_anchor_at": null, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "invoice.voided" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/InvoiceLegacy" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "invoice.voided", "description": "The webhook event type", "example": "invoice.voided", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Invoice Voided", "tags": [ "Invoices" ], "x-group-title": "Payins" } }, "ledger_account.funds_available": { "post": { "description": "Sent when a ledger account is funds available\n\nRequired permissions:\n - `company:balance:read`\n - `payout:account:read`\n - `webhook_receive:ledger_accounts`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "balances": [ { "balance": 1837.5, "currency": "usd", "pending_balance": 245.0, "reserve_balance": 0.0 } ], "id": "ldgr_xxxxxxxxxxxxxx", "ledger_type": "primary", "owner": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing", "typename": "Company" }, "payments_approval_status": null, "payout_account_details": null, "payout_quote_required": false, "settlement_time_at": "2026-01-01T12:00:00.000Z", "transfer_fee": 3.0, "treasury_balance": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "ledger_account.funds_available" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/LedgerAccount" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "ledger_account.funds_available", "description": "The webhook event type", "example": "ledger_account.funds_available", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "LedgerAccount Funds available", "tags": [ "Ledger accounts" ], "x-group-title": "Payouts" } }, "member.created": { "post": { "description": "Sent when a member is created\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `member:phone:read`\n - `webhook_receive:members`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "access_level": "customer", "account_id": "biz_xxxxxxxxxxxxxx", "created_at": "2026-01-01T12:00:00.000Z", "display_name": "Jack Sharkey the 149th", "earnings_usd": { "last_24_hours": "0.00", "last_30_days": "0.00", "last_7_days": "0.00", "lifetime": "0.00" }, "email": null, "id": "mber_xxxxxxxxxxxxxx", "joined_at": "2026-01-01T12:00:00.000Z", "last_accessed_at": "2026-01-01T12:00:00.000Z", "most_recent_action": "joined", "most_recent_action_at": "2026-01-01T12:00:00.000Z", "phone_number": null, "status": "joined", "token_balance": 0.0, "usd_total_spent": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "member.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Member" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "member.created", "description": "The webhook event type", "example": "member.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Member Created", "tags": [ "Members" ], "x-group-title": "CRM" }, "x-whop-surface": "native" }, "member.updated": { "post": { "description": "Sent when a member is updated\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `member:phone:read`\n - `webhook_receive:members`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "access_level": "customer", "account_id": "biz_xxxxxxxxxxxxxx", "created_at": "2026-01-01T12:00:00.000Z", "display_name": "Jack Sharkey the 151st", "earnings_usd": { "last_24_hours": "0.00", "last_30_days": "0.00", "last_7_days": "0.00", "lifetime": "0.00" }, "email": null, "id": "mber_xxxxxxxxxxxxxx", "joined_at": "2026-01-01T12:00:00.000Z", "last_accessed_at": "2026-01-01T12:00:00.000Z", "most_recent_action": null, "most_recent_action_at": null, "phone_number": null, "status": "joined", "token_balance": 0.0, "usd_total_spent": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "member.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Member" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "member.updated", "description": "The webhook event type", "example": "member.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Member Updated", "tags": [ "Members" ], "x-group-title": "CRM" }, "x-whop-surface": "native" }, "membership.activated": { "post": { "description": "Sent when a membership is activated\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:memberships`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "affiliate": null, "billing_period_days": 30, "cancel_at_period_end": false, "cancel_option": null, "canceled_at": null, "cancellation_reason": null, "collection_method": null, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "current_period_start": "2026-01-01T12:00:00.000Z", "expires_at": null, "feedback_option": null, "id": "mem_xxxxxxxxxxxxxx", "initial_price": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "license_key": null, "manage_url": null, "member": null, "member_id": "mber_xxxxxxxxxxxxxx", "metadata": {}, "most_recent_action": null, "most_recent_action_at": null, "phone_number": null, "product": { "id": "prod_xxxxxxxxxxxxxx", "logo_url": null, "title": "Ceramic Coating Package" }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "renewal_price": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "split_pay_current_payments": null, "split_pay_required_payments": null, "status": "active", "updated_at": "2026-01-01T12:00:00.000Z", "user_id": "user_xxxxxxxxxxxxxx", "variant_id": "plan_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.activated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "membership.activated", "description": "The webhook event type", "example": "membership.activated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Membership Activated", "tags": [ "Memberships" ], "x-group-title": "CRM" }, "x-whop-surface": "native" }, "membership.trial_ending_soon": { "post": { "description": "Sent when a membership is trial ending soon\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:memberships`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "affiliate": null, "billing_period_days": 30, "cancel_at_period_end": false, "cancel_option": null, "canceled_at": null, "cancellation_reason": null, "collection_method": null, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "current_period_start": "2026-01-01T12:00:00.000Z", "expires_at": null, "feedback_option": null, "id": "mem_xxxxxxxxxxxxxx", "initial_price": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "license_key": null, "manage_url": null, "member": null, "member_id": "mber_xxxxxxxxxxxxxx", "metadata": {}, "most_recent_action": null, "most_recent_action_at": null, "phone_number": null, "product": { "id": "prod_xxxxxxxxxxxxxx", "logo_url": null, "title": "Ceramic Coating Package" }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "renewal_price": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "split_pay_current_payments": null, "split_pay_required_payments": null, "status": "trialing", "updated_at": "2026-01-01T12:00:00.000Z", "user_id": "user_xxxxxxxxxxxxxx", "variant_id": "plan_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.trial_ending_soon" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "membership.trial_ending_soon", "description": "The webhook event type", "example": "membership.trial_ending_soon", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Membership Trial ending soon", "tags": [ "Memberships" ], "x-group-title": "CRM" }, "x-whop-surface": "native" }, "membership.updated": { "post": { "description": "Sent whenever a membership changes: it activates or deactivates, cancel_at_period_end flips, or the seller edits its billing period, price or renewal date. previous_attributes carries the values that changed from. membership.activated is also delivered as a membership.updated, so you can subscribe to this single event and read the current status from the payload.\n\nRequired permissions:\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:memberships`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "affiliate": null, "billing_period_days": 30, "cancel_at_period_end": false, "cancel_option": null, "canceled_at": null, "cancellation_reason": null, "collection_method": null, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "current_period_start": "2026-01-01T12:00:00.000Z", "expires_at": null, "feedback_option": null, "id": "mem_xxxxxxxxxxxxxx", "initial_price": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "license_key": null, "manage_url": null, "member": null, "member_id": "mber_xxxxxxxxxxxxxx", "metadata": {}, "most_recent_action": null, "most_recent_action_at": null, "phone_number": null, "product": { "id": "prod_xxxxxxxxxxxxxx", "logo_url": null, "title": "Ceramic Coating Package" }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "renewal_price": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "split_pay_current_payments": null, "split_pay_required_payments": null, "status": "active", "updated_at": "2026-01-01T12:00:00.000Z", "user_id": "user_xxxxxxxxxxxxxx", "variant_id": "plan_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Membership" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "membership.updated", "description": "The webhook event type", "example": "membership.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Membership Updated", "tags": [ "Memberships" ], "x-group-title": "CRM" }, "x-whop-surface": "native" }, "payment.authorized": { "post": { "description": "Sent when a payment is authorized\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `shipment:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_capture_at": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "capture_expires_at": "2026-01-06T12:00:00.000Z", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_email": "marcus@shinetime.example", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "dispute_created_at": null, "failure_message": null, "financing_installments_count": null, "holds": [], "id": "pay_xxxxxxxxxxxxxx", "ip_address": null, "last_payment_attempt_at": null, "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": "CERAMIC-COAT-3YR", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "member_id": "mber_xxxxxxxxxxxxxx", "membership_id": "mem_xxxxxxxxxxxxxx", "metadata": {}, "needs_tracking": false, "next_payment_attempt_at": null, "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "exp_month": null, "exp_year": null, "issuer_identification_number": null, "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method_id": null, "payment_method_type": "card", "payment_rule_matches": [], "payments_failed": 0, "presentment_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "presentment_tax_amount": null, "presentment_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "quote_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_at": null, "response_due_at": null, "retryable": false, "risk_score": null, "risk_signals": null, "settlement_time_at": null, "shipment_id": null, "shipping_address": null, "status": "authorized", "substatus": "requires_capture", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "three_ds_verified": false, "total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "variant_id": "plan_xxxxxxxxxxxxxx", "verification_checks": null, "voidable": true }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.authorized" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.authorized", "description": "The webhook event type", "example": "payment.authorized", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Authorized", "tags": [ "Payments" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "payment.canceled": { "post": { "description": "Sent when a payment is canceled\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `shipment:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_capture_at": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "capture_expires_at": "2026-01-06T12:00:00.000Z", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_email": "marcus@shinetime.example", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "dispute_created_at": null, "failure_message": null, "financing_installments_count": null, "holds": [], "id": "pay_xxxxxxxxxxxxxx", "ip_address": null, "last_payment_attempt_at": null, "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": "CERAMIC-COAT-3YR", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "member_id": "mber_xxxxxxxxxxxxxx", "membership_id": "mem_xxxxxxxxxxxxxx", "metadata": {}, "needs_tracking": false, "next_payment_attempt_at": null, "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "exp_month": null, "exp_year": null, "issuer_identification_number": null, "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method_id": null, "payment_method_type": "card", "payment_rule_matches": [], "payments_failed": 0, "presentment_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "presentment_tax_amount": null, "presentment_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "quote_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_at": null, "response_due_at": null, "retryable": false, "risk_score": null, "risk_signals": null, "settlement_time_at": null, "shipment_id": null, "shipping_address": null, "status": "void", "substatus": "canceled", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "three_ds_verified": false, "total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "variant_id": "plan_xxxxxxxxxxxxxx", "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.canceled" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.canceled", "description": "The webhook event type", "example": "payment.canceled", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Canceled", "tags": [ "Payments" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "payment.created": { "post": { "description": "Sent when a payment is created\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `shipment:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_capture_at": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "capture_expires_at": null, "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_email": "marcus@shinetime.example", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "dispute_created_at": null, "failure_message": null, "financing_installments_count": null, "holds": [], "id": "pay_xxxxxxxxxxxxxx", "ip_address": null, "last_payment_attempt_at": null, "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": "CERAMIC-COAT-3YR", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "member_id": "mber_xxxxxxxxxxxxxx", "membership_id": "mem_xxxxxxxxxxxxxx", "metadata": {}, "needs_tracking": false, "next_payment_attempt_at": null, "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "exp_month": null, "exp_year": null, "issuer_identification_number": null, "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method_id": null, "payment_method_type": "card", "payment_rule_matches": [], "payments_failed": 0, "presentment_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "presentment_tax_amount": null, "presentment_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "quote_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_at": null, "response_due_at": null, "retryable": true, "risk_score": null, "risk_signals": null, "settlement_time_at": null, "shipment_id": null, "shipping_address": null, "status": "open", "substatus": "incomplete", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "three_ds_verified": false, "total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "variant_id": "plan_xxxxxxxxxxxxxx", "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.created", "description": "The webhook event type", "example": "payment.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Created", "tags": [ "Payments" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "payment.failed": { "post": { "description": "Sent when a payment is failed\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `shipment:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_capture_at": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "capture_expires_at": null, "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_email": "marcus@shinetime.example", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "dispute_created_at": null, "failure_message": "Your card was declined.", "financing_installments_count": null, "holds": [], "id": "pay_xxxxxxxxxxxxxx", "ip_address": null, "last_payment_attempt_at": "2026-01-01T12:00:00.000Z", "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": "CERAMIC-COAT-3YR", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "member_id": "mber_xxxxxxxxxxxxxx", "membership_id": "mem_xxxxxxxxxxxxxx", "metadata": {}, "needs_tracking": false, "next_payment_attempt_at": "2026-01-01T12:00:00.000Z", "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "exp_month": null, "exp_year": null, "issuer_identification_number": null, "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method_id": null, "payment_method_type": "card", "payment_rule_matches": [], "payments_failed": 1, "presentment_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "presentment_tax_amount": null, "presentment_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "quote_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_at": null, "response_due_at": null, "retryable": true, "risk_score": null, "risk_signals": null, "settlement_time_at": null, "shipment_id": null, "shipping_address": null, "status": "open", "substatus": "failed", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "three_ds_verified": false, "total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "variant_id": "plan_xxxxxxxxxxxxxx", "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.failed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.failed", "description": "The webhook event type", "example": "payment.failed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Failed", "tags": [ "Payments" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "payment.pending": { "post": { "description": "Sent when a payment is pending\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `shipment:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_capture_at": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "capture_expires_at": null, "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_email": "marcus@shinetime.example", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "dispute_created_at": null, "failure_message": null, "financing_installments_count": null, "holds": [], "id": "pay_xxxxxxxxxxxxxx", "ip_address": null, "last_payment_attempt_at": null, "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": "CERAMIC-COAT-3YR", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "member_id": "mber_xxxxxxxxxxxxxx", "membership_id": "mem_xxxxxxxxxxxxxx", "metadata": {}, "needs_tracking": false, "next_payment_attempt_at": null, "paid_at": null, "payment_instrument": { "card": null, "display_name": "ACH", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/ach/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/ach/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/ach/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/ach/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/ach/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/ach/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/ach/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/ach/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/ach/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/ach/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/ach/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/ach/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/ach/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/ach/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/ach/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/ach/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "us_bank_account" }, "payment_method_id": null, "payment_method_type": "us_bank_account", "payment_rule_matches": [], "payments_failed": 0, "presentment_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "presentment_tax_amount": null, "presentment_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "quote_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_at": null, "response_due_at": null, "retryable": false, "risk_score": null, "risk_signals": null, "settlement_time_at": null, "shipment_id": null, "shipping_address": null, "status": "pending", "substatus": "pending", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "three_ds_verified": false, "total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "variant_id": "plan_xxxxxxxxxxxxxx", "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.pending" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.pending", "description": "The webhook event type", "example": "payment.pending", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Pending", "tags": [ "Payments" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "payment.requires_action": { "post": { "description": "Sent when the bank asks the buyer to verify an off-session charge, such as a subscription renewal or a saved-card payment your server made. `data.recovery_url` is the Whop link where the buyer signs in and completes 3D Secure; the event is only sent while that link exists, so it is null only when you lack `member:basic:read`. Then handle `payment.succeeded` or `payment.failed` for the outcome.\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `shipment:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_capture_at": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "capture_expires_at": null, "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_email": "marcus@shinetime.example", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "dispute_created_at": null, "failure_message": null, "financing_installments_count": null, "holds": [], "id": "pay_xxxxxxxxxxxxxx", "ip_address": null, "last_payment_attempt_at": null, "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": "CERAMIC-COAT-3YR", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "member_id": "mber_xxxxxxxxxxxxxx", "membership_id": null, "metadata": {}, "needs_tracking": false, "next_payment_attempt_at": null, "paid_at": null, "payment_instrument": { "card": { "brand": "visa", "exp_month": null, "exp_year": null, "issuer_identification_number": null, "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method_id": null, "payment_method_type": "card", "payment_rule_matches": [], "payments_failed": 0, "presentment_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "presentment_tax_amount": null, "presentment_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "quote_id": null, "recovery_url": "https://whop.com/billing/manage/mber_xxxxxxxxxxxxxx/verify-payment/", "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_at": null, "response_due_at": null, "retryable": false, "risk_score": null, "risk_signals": null, "settlement_time_at": null, "shipment_id": null, "shipping_address": null, "status": "open", "substatus": "incomplete", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "three_ds_verified": false, "total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "variant_id": "plan_xxxxxxxxxxxxxx", "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.requires_action" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.requires_action", "description": "The webhook event type", "example": "payment.requires_action", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Requires action", "tags": [ "Payments" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "payment.succeeded": { "post": { "description": "Sent when a payment is succeeded\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `promo_code:basic:read`\n - `shipment:basic:read`\n - `payment:dispute:read`\n - `payment:resolution_center_case:read`\n - `webhook_receive:payments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_capture_at": null, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "capture_expires_at": null, "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_email": "marcus@shinetime.example", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "dispute_created_at": null, "failure_message": null, "financing_installments_count": null, "holds": [], "id": "pay_xxxxxxxxxxxxxx", "ip_address": null, "last_payment_attempt_at": null, "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": "CERAMIC-COAT-3YR", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "member_id": "mber_xxxxxxxxxxxxxx", "membership_id": "mem_xxxxxxxxxxxxxx", "metadata": {}, "needs_tracking": false, "next_payment_attempt_at": null, "paid_at": "2026-01-01T12:00:00.000Z", "payment_instrument": { "card": { "brand": "visa", "exp_month": null, "exp_year": null, "issuer_identification_number": null, "last4": "4242" }, "display_name": "Visa •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/visa/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/visa/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/visa/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/visa/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/visa/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method_id": null, "payment_method_type": "card", "payment_rule_matches": [], "payments_failed": 0, "presentment_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "presentment_tax_amount": null, "presentment_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "quote_id": null, "recovery_url": null, "refundable": true, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_at": null, "response_due_at": null, "retryable": false, "risk_score": null, "risk_signals": null, "settlement_time_at": null, "shipment_id": null, "shipping_address": null, "status": "paid", "substatus": "succeeded", "subtotal": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "three_ds_verified": false, "total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "updated_at": "2026-01-01T12:00:00.000Z", "usd_total": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" }, "variant_id": "plan_xxxxxxxxxxxxxx", "verification_checks": null, "voidable": false }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payment.succeeded" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Payment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payment.succeeded", "description": "The webhook event type", "example": "payment.succeeded", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payment Succeeded", "tags": [ "Payments" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "payout.created": { "post": { "description": "Sent when a payout is created (this event family replaces withdrawal.*)\n\nRequired permissions:\n - `webhook_receive:withdrawals`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": "10.0", "cancelable": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "destination_amount": null, "destination_currency": null, "estimated_arrival": null, "exchange_rate": null, "failure": null, "fee_amount": "0.0", "fee_paid_by": "self", "id": "wdrl_xxxxxxxxxxxxxx", "markup_fee": "0.0", "metadata": {}, "net_amount": "10.0", "notes": null, "object": "payout", "payer_name": null, "payout_method": { "nickname": "Shine Time business checking", "supported_payout_method": { "delivery_type": "bank_deposit", "icon_url": null, "payer_name": "Next Day Bank Deposit" } }, "payout_request_id": null, "source": null, "speed": "standard", "statement_descriptor": null, "status": "in_review", "status_detail": "risk_review", "trace_code": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "cancelable": { "description": "Whether `POST /payouts/{id}/cancel` would act on this payout right now: `true` while it is `in_review`, while it is `processing` with nothing yet submitted to the payout provider, or while a submitted payout can still be asked to cancel at the provider. `false` once the money has arrived or the payout has already ended.", "example": true, "type": "boolean" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a payout funded by a conversion request it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled payout funded by a conversion request can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. Match it to the settled payout in `GET /payouts`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "The payment description sent with the payout, or `null` if no descriptor was set. When set, 5-80 printable ASCII characters.", "example": "MYCOMPANY", "maxLength": 80, "minLength": 5, "type": [ "string", "null" ] }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "cancelable", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "statement_descriptor", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payout.created", "description": "The webhook event type", "example": "payout.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payout Created", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "payout.reversed": { "post": { "description": "Sent when a settled payout is reversed and the funds return to the balance (this event family replaces withdrawal.*)\n\nRequired permissions:\n - `webhook_receive:withdrawals`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": "10.0", "cancelable": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "destination_amount": null, "destination_currency": null, "estimated_arrival": null, "exchange_rate": null, "failure": { "code": null, "funds_returned_at": "2026-01-01T12:00:00.000Z", "message": null }, "fee_amount": "0.0", "fee_paid_by": "self", "id": "wdrl_xxxxxxxxxxxxxx", "markup_fee": "0.0", "metadata": {}, "net_amount": "10.0", "notes": null, "object": "payout", "payer_name": null, "payout_method": null, "payout_request_id": null, "source": null, "speed": "standard", "statement_descriptor": null, "status": "reversed", "status_detail": "reversed", "trace_code": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout.reversed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "cancelable": { "description": "Whether `POST /payouts/{id}/cancel` would act on this payout right now: `true` while it is `in_review`, while it is `processing` with nothing yet submitted to the payout provider, or while a submitted payout can still be asked to cancel at the provider. `false` once the money has arrived or the payout has already ended.", "example": true, "type": "boolean" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a payout funded by a conversion request it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled payout funded by a conversion request can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. Match it to the settled payout in `GET /payouts`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "The payment description sent with the payout, or `null` if no descriptor was set. When set, 5-80 printable ASCII characters.", "example": "MYCOMPANY", "maxLength": 80, "minLength": 5, "type": [ "string", "null" ] }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "cancelable", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "statement_descriptor", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payout.reversed", "description": "The webhook event type", "example": "payout.reversed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payout Reversed", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "payout.updated": { "post": { "description": "Sent when a payout's status changes (this event family replaces withdrawal.*)\n\nRequired permissions:\n - `webhook_receive:withdrawals`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": "10.0", "cancelable": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "destination_amount": null, "destination_currency": null, "estimated_arrival": null, "exchange_rate": null, "failure": null, "fee_amount": "0.0", "fee_paid_by": "self", "id": "wdrl_xxxxxxxxxxxxxx", "markup_fee": "0.0", "metadata": {}, "net_amount": "10.0", "notes": null, "object": "payout", "payer_name": null, "payout_method": null, "payout_request_id": null, "source": null, "speed": "standard", "statement_descriptor": null, "status": "completed", "status_detail": "completed", "trace_code": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "amount": { "description": "The payout amount in whole currency units, as a decimal string.", "example": "500.0", "format": "decimal", "type": "string" }, "cancelable": { "description": "Whether `POST /payouts/{id}/cancel` would act on this payout right now: `true` while it is `in_review`, while it is `processing` with nothing yet submitted to the payout provider, or while a submitted payout can still be asked to cancel at the provider. `false` once the money has arrived or the payout has already ended.", "example": true, "type": "boolean" }, "created_at": { "description": "When the payout was created.", "example": "2026-07-29T18:22:00.000Z", "format": "date-time", "type": "string" }, "currency": { "description": "Payout currency.", "example": "usd", "type": "string" }, "destination_amount": { "description": "The amount delivered in the destination currency, as a decimal string. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded conversion.", "example": "461.7", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method when the payout is created. On a payout funded by a conversion request it follows the settlement payout minted alongside it — the `GET /payouts` row carrying this payout's id as `payout_request_id` — and is `null` only when no settlement payout exists.", "example": "eur", "type": [ "string", "null" ] }, "estimated_arrival": { "description": "Estimated time the funds become available in the destination account.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency. Assigned when the payout is processed, so it is `null` before then and on payouts without a recorded rate.", "example": 0.9234, "format": "float", "type": [ "number", "null" ] }, "failure": { "description": "Why the payout ended without paying, or why it reversed after settlement. Present on failed, canceled, denied, and reversed payouts; `null` otherwise.", "properties": { "code": { "description": "Classified failure code from the maintained error catalog.", "example": "beneficiary_name_mismatch", "type": [ "string", "null" ] }, "funds_returned_at": { "description": "The effective time of the reversal that put the funds back in the balance — `null` if they never left it or have not returned yet. Set only once the return is confirmed in the ledger; the ledger posting itself can land moments after this time.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure. Callers holding `payout:destination:read` may receive text personalized to the destination; other callers get the generic catalog message.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "funds_returned_at" ], "type": [ "object", "null" ] }, "fee_amount": { "description": "The fee charged for the payout, in the payout currency, as a decimal string.", "example": "0.25", "format": "decimal", "type": "string" }, "fee_paid_by": { "description": "Who bore the payout fee: the account itself, or its parent platform.", "enum": [ "self", "platform" ], "example": "self", "type": "string" }, "id": { "description": "Payout ID, prefixed `wdrl_`.", "example": "wdrl_xxxxxxxxxxxxx", "type": "string" }, "markup_fee": { "description": "Whop's markup on the provider fee, in the payout currency, as a decimal string. `\"0.0\"` when none applies.", "example": "0.0", "format": "decimal", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Key-value data attached at creation and echoed on every read. At most 50 keys, key names up to 40 characters, string values up to 500 characters.", "example": { "batch_id": "2026-08-18" }, "type": "object" }, "net_amount": { "description": "The planned net for the destination, in the payout currency: amount minus fee_amount minus markup_fee when fee_paid_by is `self`; equal to amount when the platform covers the fees. A payout that ends denied, canceled, or failed delivered nothing — most keep the planned figure and `failure` says where the funds are, but a canceled payout funded by a conversion request can report the settled outcome instead: `amount` carries what stayed in the balance, fees are zero because none were charged, and `net_amount` is 0 because nothing was delivered.", "example": "49.75", "format": "decimal", "type": "string" }, "notes": { "description": "Free-form notes attached by the payout creator, or `null` when none were provided. Maximum 255 characters.", "example": "Detailing supplies restock", "maxLength": 255, "type": [ "string", "null" ] }, "object": { "enum": [ "payout" ], "example": "payout", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "payout_method": { "description": "The saved payout method used. Requires payout:destination:read; null without it.", "properties": { "nickname": { "description": "Saved payout method nickname.", "example": "Business checking", "type": [ "string", "null" ] }, "supported_payout_method": { "description": "Supported payout method display details.", "properties": { "delivery_type": { "description": "How the funds are delivered to the recipient.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "payer_name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] } }, "required": [ "payer_name", "icon_url", "delivery_type" ], "type": [ "object", "null" ] } }, "required": [ "nickname", "supported_payout_method" ], "type": [ "object", "null" ] }, "payout_request_id": { "description": "Payout request ID, prefixed `cofr_`, returned by `POST /payouts`. Match it to the settled payout in `GET /payouts`. Returns `null` for payouts not created by `POST /payouts`.", "example": "cofr_xxxxxxxxxxxxx", "type": [ "string", "null" ] }, "source": { "description": "How the payout was created. `automatic` means a scheduled auto-payout; `null` on payouts created before source tracking or through internal tooling.", "enum": [ "api", "dashboard", "automatic", null ], "example": "api", "type": [ "string", "null" ] }, "speed": { "description": "Payout delivery speed.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "The payment description sent with the payout, or `null` if no descriptor was set. When set, 5-80 printable ASCII characters.", "example": "MYCOMPANY", "maxLength": 80, "minLength": 5, "type": [ "string", "null" ] }, "status": { "description": "Current payout status.", "enum": [ "requested", "in_review", "processing", "completed", "reversed", "canceled", "failed", "denied" ], "example": "in_review", "type": "string" }, "status_detail": { "description": "The finest machine phase under `status` — for example `awaiting_provider_acceptance` vs `in_transit` under `processing`, or the conversion phase under `requested`. Informational vocabulary: values can be added without a version bump; `status` is the versioned contract.", "example": "awaiting_provider_acceptance", "type": "string" }, "trace_code": { "description": "ACH trace number the recipient's bank can use to locate this payout. Assigned when the payout is submitted to the bank, so it is `null` before then and on payouts not sent over ACH.", "example": "021000021234567", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "cancelable", "amount", "currency", "destination_currency", "destination_amount", "exchange_rate", "fee_amount", "speed", "created_at", "estimated_arrival", "payer_name", "trace_code", "notes", "statement_descriptor", "net_amount", "markup_fee", "fee_paid_by", "source", "metadata", "failure", "payout_method" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payout.updated", "description": "The webhook event type", "example": "payout.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Payout Updated", "tags": [ "Payouts" ] }, "x-whop-surface": "native" }, "payout_account.status_updated": { "post": { "description": "Sent when a payout account is status updated\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:payout_accounts`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "address": { "city": "Austin", "country": "USA", "line1": "2201 Barton Springs Rd", "line2": "Suite 4", "postal_code": "78704", "state": "TX" }, "business_name": null, "business_representative": { "date_of_birth": "1988-04-12", "first_name": "Marcus", "last_name": "Webb", "middle_name": null }, "email": "marcus@shinetime.example", "id": "poact_xxxxxxxxxxxxxx", "latest_verification": null, "phone": "+1 512 555 0194", "status": "connected" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout_account.status_updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/PayoutAccount" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payout_account.status_updated", "description": "The webhook event type", "example": "payout_account.status_updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "PayoutAccount Status updated", "tags": [ "Payout accounts" ], "x-group-title": "Payouts" } }, "payout_method.created": { "post": { "description": "Sent when a payout method is created\n\nRequired permissions:\n - `payout:destination:read`\n - `webhook_receive:payout_methods`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_reference": "4483", "bank_verification_state": null, "created_at": "2026-01-01T12:00:00.000Z", "destination_currency": "usd", "estimated_arrival": null, "fee_structure": null, "id": "potk_xxxxxxxxxxxxxx", "institution_name": "Frost Bank", "is_clone": false, "is_default": true, "last_paid_out_at": null, "linked_via_plaid": false, "needs_plaid_reconnect": false, "nickname": "Shine Time business checking", "object": "payout_method", "payer_name": "Next Day Bank Deposit", "quote": null, "status": "created", "status_reason": null, "supported_payout_method": { "country_code": "USA", "delivery_type": "bank_deposit", "icon_url": null, "name": "Next Day Bank Deposit", "supports_instant_delivery": false, "supports_plaid": true, "supports_standard_delivery": true }, "unavailable_reason": null }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "payout_method.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "properties": { "account_reference": { "description": "Masked identifier for the destination, such as the last four digits of a bank account.", "example": "••••6789", "type": [ "string", "null" ] }, "bank_verification_state": { "description": "Lifecycle trust state: `checking` (verification still running), `verified` (bank confirmed ownership or a payout already completed to it), `no_data` (verification unavailable or bank returned no ownership data), `warning` (bank could not confirm the destination's owner), `broken` (payouts failed with a permanent account error), `null` (never checked).", "enum": [ "checking", "verified", "no_data", "warning", "broken", null ], "example": "verified", "type": [ "string", "null" ] }, "created_at": { "description": "When the payout method was added.", "example": "2026-06-15T09:00:00.000Z", "format": "date-time", "type": "string" }, "destination_currency": { "description": "Currency payouts are delivered in for this method.", "example": "usd", "type": "string" }, "estimated_arrival": { "description": "Estimated arrival times before an amount-specific quote is requested. Null when the method is not currently eligible.", "properties": { "instant": { "description": "Estimated instant-delivery arrival, or null when unavailable.", "example": "2026-07-30T12:30:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "standard": { "description": "Estimated standard-delivery arrival, or null when unavailable.", "example": "2026-08-03T00:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "standard", "instant" ], "type": [ "object", "null" ] }, "fee_structure": { "description": "Configured fee terms for this payout method. Null when the method is not currently eligible. An amount-specific quote remains authoritative.", "properties": { "currency": { "description": "Currency code of fixed_amount.", "example": "usd", "type": "string" }, "fixed_amount": { "description": "Fixed fee charged, denominated in `currency`.", "example": 0.25, "format": "float", "type": "number" }, "percentage": { "description": "Percentage of the payout amount charged as a fee.", "example": 0.0, "format": "float", "type": "number" } }, "required": [ "percentage", "fixed_amount", "currency" ], "type": [ "object", "null" ] }, "id": { "description": "Payout method ID.", "example": "pyot_xxxxxxxxxxxxx", "type": "string" }, "institution_name": { "description": "Name of the bank or institution receiving payouts.", "example": "Frost Bank", "type": [ "string", "null" ] }, "is_clone": { "description": "Whether this method is a copy of one saved on another of the payer's accounts.", "example": false, "type": "boolean" }, "is_default": { "description": "Whether this is the default payout method for the account.", "example": true, "type": "boolean" }, "last_paid_out_at": { "description": "When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. `null` when nothing has been paid out to it yet.", "example": "2026-08-02T15:30:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "linked_via_plaid": { "description": "Whether the payer added this method by signing in to their bank rather than typing account details.", "example": false, "type": "boolean" }, "needs_plaid_reconnect": { "description": "Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.", "example": false, "type": "boolean" }, "nickname": { "description": "User-defined label for the payout method.", "example": "Business checking", "type": [ "string", "null" ] }, "object": { "enum": [ "payout_method" ], "example": "payout_method", "type": "string" }, "payer_name": { "description": "Display name of the payout rail, such as `ACH Bank Deposit`.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "quote": { "description": "Fee and delivery estimate for paying out the requested amount through this method. Null unless an amount was provided, or when the estimate is unavailable.", "properties": { "amount": { "description": "The payout amount the quote is for.", "example": 500.0, "format": "float", "type": "number" }, "currency": { "description": "Currency of the quoted amount.", "example": "usd", "type": "string" }, "exchange_rate": { "description": "Exchange rate from the payout currency to the destination currency.", "example": 1.0, "format": "float", "type": "number" }, "instant": { "description": "Instant-delivery estimate. Null if the method does not support instant delivery, instant delivery is unavailable for the account, or the amount does not cover the fee.", "properties": { "fee": { "description": "Total fee charged, in the payout currency.", "example": 5.25, "format": "float", "type": "number" }, "total_received": { "description": "Amount remaining after fees, in the payout currency.", "example": 494.75, "format": "float", "type": "number" } }, "required": [ "fee", "total_received" ], "type": [ "object", "null" ] }, "instant_unavailable_reason": { "description": "Why instant delivery is unavailable for this method. `minimum_crypto_sales_not_met` means the account has not reached the total sales required for instant cryptocurrency payouts. `null` when this restriction does not apply.", "enum": [ "minimum_crypto_sales_not_met", null ], "example": "minimum_crypto_sales_not_met", "type": [ "string", "null" ] }, "max_limit": { "description": "Maximum payout amount for this method, in the payout currency.", "example": 25000.0, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount for this method, in the payout currency.", "example": 1.0, "format": "float", "type": "number" }, "standard": { "description": "Standard-delivery estimate. Null if the method does not support standard delivery, or the amount does not cover the fee.", "properties": { "fee": { "description": "Total fee charged, in the payout currency.", "example": 0.25, "format": "float", "type": "number" }, "total_received": { "description": "Amount remaining after fees, in the payout currency.", "example": 499.75, "format": "float", "type": "number" } }, "required": [ "fee", "total_received" ], "type": [ "object", "null" ] } }, "required": [ "amount", "currency", "exchange_rate", "min_limit", "max_limit", "instant_unavailable_reason", "standard", "instant" ], "type": [ "object", "null" ] }, "recipient": { "description": "The recipient of a third-party payout method. Present only for recipient payout methods.", "properties": { "country": { "description": "ISO 3166-1 alpha-3 country code.", "type": "string" }, "email": { "example": "jane.doe@example.com", "format": "email", "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } }, "required": [ "email", "first_name", "last_name", "country" ], "type": "object" }, "status": { "description": "Lifecycle status: `created` means saved but unused, `active` means a payout succeeded through it, `broken` means a payout failure disabled it; a later successful payout returns it to `active`.", "enum": [ "created", "active", "broken" ], "example": "active", "type": "string" }, "status_reason": { "description": "Machine-readable code for why the method is `broken` — the newest disabling failure recorded through it, whether a payout error or a pre-payout rejection. `null` unless the method is broken, or when it was disabled without a recorded failure.", "example": null, "type": [ "string", "null" ] }, "supported_payout_method": { "description": "The supported payout method this saved method was created from.", "properties": { "country_code": { "description": "ISO 3166-1 alpha-3 country the destination pays out to.", "example": "USA", "type": [ "string", "null" ] }, "delivery_type": { "description": "How funds are delivered.", "enum": [ "cash_pickup", "bank_deposit", "home_delivery", "mobile_wallet", "card", "check", "bill", "cryptocurrency", "unknown" ], "example": "bank_deposit", "type": "string" }, "icon_url": { "description": "Supported payout method icon URL.", "example": "https://cdn.whop.com/payouts/ach.png", "type": [ "string", "null" ] }, "name": { "description": "Supported payout method display name.", "example": "ACH Bank Deposit", "type": [ "string", "null" ] }, "supports_instant_delivery": { "example": false, "type": "boolean" }, "supports_plaid": { "description": "Whether the payer can link this method by signing in to their bank instead of typing account details.", "example": true, "type": "boolean" }, "supports_standard_delivery": { "example": true, "type": "boolean" } }, "required": [ "name", "icon_url", "delivery_type", "country_code", "supports_standard_delivery", "supports_instant_delivery", "supports_plaid" ], "type": [ "object", "null" ] }, "unavailable_reason": { "description": "Why this method is unavailable: `destination_retired` means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. `null` means no unavailability reason is known.", "enum": [ "destination_retired", null ], "example": null, "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "status_reason", "is_default", "nickname", "account_reference", "bank_verification_state", "linked_via_plaid", "needs_plaid_reconnect", "is_clone", "institution_name", "payer_name", "destination_currency", "created_at", "last_paid_out_at", "unavailable_reason", "supported_payout_method", "fee_structure", "estimated_arrival", "quote" ], "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "payout_method.created", "description": "The webhook event type", "example": "payout_method.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "PayoutMethod Created", "tags": [ "Payouts" ], "x-group-title": "Payouts" }, "x-whop-surface": "native" }, "plan.created": { "post": { "description": "Sent when a variant is created\n\nRequired permissions:\n - `webhook_receive:plans`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "allow_multiple_quantity": false, "attributes": null, "billing_period": 30, "billing_type": "renewal", "cancel_discount_intervals": null, "cancel_discount_percentage": null, "checkout_styling": null, "collect_tax": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "custom_fields": [], "deletable": true, "description": "One maintenance wash per week, any vehicle on file.", "effective_payment_method_configuration": { "disabled": [], "enabled": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alipay", "alipayhk", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_installments_three", "card_installments_six", "card_installments_twelve", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "duitnow_qr", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "giropay", "google_pay", "gopay", "grabpay", "id_bank_transfer", "ideal", "interac", "kakao_pay", "klarna", "klarna_pay_now", "konbini", "kr_card", "kr_market", "kriya", "kueski", "link", "mb_way", "m_pesa", "mercado_pago", "mercado_pago_ar", "mercado_pago_mx", "mobilepay", "modo", "mondu", "multibanco", "naver_pay", "nequi", "netbanking", "ng_bank", "ng_bank_transfer", "ng_card", "ng_market", "ng_ussd", "ng_wallet", "nupay", "nz_bank_account", "oney", "oney_3x", "oney_4x", "opay", "oxxo", "p24", "pago_efectivo", "pse", "pay_by_bank", "payco", "paynow", "paypal", "paypay", "payto", "payto_email", "payto_phone", "payto_bank_account", "pix", "platform_balance", "promptpay", "qris", "rapipago", "rechnung", "revolut_pay", "samsung_pay", "satispay", "scalapay", "sencillito", "sepa_debit", "sequra", "servipag", "sezzle", "shop_pay", "shopeepay", "sofort", "south_korea_market", "spei", "splitit", "sunbit", "swish", "tabby", "tamara", "touch_n_go", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "verve", "vipps", "webpay", "wechat_pay", "whop_pay", "yape", "zip" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0.0, "initial_price_due": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "invoice": null, "member_count": 0, "metadata": {}, "offer_cancel_discount": false, "payment_method_configuration": null, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50.0, "sku": null, "split_pay_required_payments": null, "stock": 0, "strike_through_initial_price": null, "strike_through_renewal_price": null, "tax_type": "unspecified", "three_ds_level": null, "title": "Unlimited Wash Club", "trial_period_days": null, "unlimited_stock": false, "updated_at": "2026-01-01T12:00:00.000Z", "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "plan.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Variant" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "plan.created", "description": "The webhook event type", "example": "plan.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Variant Created", "tags": [ "Variants" ] }, "x-whop-surface": "native" }, "plan.deleted": { "post": { "description": "Sent when a variant is deleted\n\nRequired permissions:\n - `webhook_receive:plans`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "allow_multiple_quantity": false, "attributes": null, "billing_period": 30, "billing_type": "renewal", "cancel_discount_intervals": null, "cancel_discount_percentage": null, "checkout_styling": null, "collect_tax": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "custom_fields": [], "deletable": true, "description": "One maintenance wash per week, any vehicle on file.", "effective_payment_method_configuration": { "disabled": [], "enabled": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alipay", "alipayhk", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_installments_three", "card_installments_six", "card_installments_twelve", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "duitnow_qr", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "giropay", "google_pay", "gopay", "grabpay", "id_bank_transfer", "ideal", "interac", "kakao_pay", "klarna", "klarna_pay_now", "konbini", "kr_card", "kr_market", "kriya", "kueski", "link", "mb_way", "m_pesa", "mercado_pago", "mercado_pago_ar", "mercado_pago_mx", "mobilepay", "modo", "mondu", "multibanco", "naver_pay", "nequi", "netbanking", "ng_bank", "ng_bank_transfer", "ng_card", "ng_market", "ng_ussd", "ng_wallet", "nupay", "nz_bank_account", "oney", "oney_3x", "oney_4x", "opay", "oxxo", "p24", "pago_efectivo", "pse", "pay_by_bank", "payco", "paynow", "paypal", "paypay", "payto", "payto_email", "payto_phone", "payto_bank_account", "pix", "platform_balance", "promptpay", "qris", "rapipago", "rechnung", "revolut_pay", "samsung_pay", "satispay", "scalapay", "sencillito", "sepa_debit", "sequra", "servipag", "sezzle", "shop_pay", "shopeepay", "sofort", "south_korea_market", "spei", "splitit", "sunbit", "swish", "tabby", "tamara", "touch_n_go", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "verve", "vipps", "webpay", "wechat_pay", "whop_pay", "yape", "zip" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0.0, "initial_price_due": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "invoice": null, "member_count": 0, "metadata": {}, "offer_cancel_discount": false, "payment_method_configuration": null, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50.0, "sku": null, "split_pay_required_payments": null, "stock": 0, "strike_through_initial_price": null, "strike_through_renewal_price": null, "tax_type": "unspecified", "three_ds_level": null, "title": "Unlimited Wash Club", "trial_period_days": null, "unlimited_stock": false, "updated_at": "2026-01-01T12:00:00.000Z", "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "plan.deleted" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Variant" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "plan.deleted", "description": "The webhook event type", "example": "plan.deleted", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Variant Deleted", "tags": [ "Variants" ] }, "x-whop-surface": "native" }, "plan.updated": { "post": { "description": "Sent when a variant is updated\n\nRequired permissions:\n - `webhook_receive:plans`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "allow_multiple_quantity": false, "attributes": null, "billing_period": 30, "billing_type": "renewal", "cancel_discount_intervals": null, "cancel_discount_percentage": null, "checkout_styling": null, "collect_tax": false, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "custom_fields": [], "deletable": true, "description": "One maintenance wash per week, any vehicle on file.", "effective_payment_method_configuration": { "disabled": [], "enabled": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alipay", "alipayhk", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_installments_three", "card_installments_six", "card_installments_twelve", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "duitnow_qr", "efecty", "eps", "eu_bank_transfer", "fpx", "flex_pay", "gb_bank_transfer", "gcash", "giropay", "google_pay", "gopay", "grabpay", "id_bank_transfer", "ideal", "interac", "kakao_pay", "klarna", "klarna_pay_now", "konbini", "kr_card", "kr_market", "kriya", "kueski", "link", "mb_way", "m_pesa", "mercado_pago", "mercado_pago_ar", "mercado_pago_mx", "mobilepay", "modo", "mondu", "multibanco", "naver_pay", "nequi", "netbanking", "ng_bank", "ng_bank_transfer", "ng_card", "ng_market", "ng_ussd", "ng_wallet", "nupay", "nz_bank_account", "oney", "oney_3x", "oney_4x", "opay", "oxxo", "p24", "pago_efectivo", "pse", "pay_by_bank", "payco", "paynow", "paypal", "paypay", "payto", "payto_email", "payto_phone", "payto_bank_account", "pix", "platform_balance", "promptpay", "qris", "rapipago", "rechnung", "revolut_pay", "samsung_pay", "satispay", "scalapay", "sencillito", "sepa_debit", "sequra", "servipag", "sezzle", "shop_pay", "shopeepay", "sofort", "south_korea_market", "spei", "splitit", "sunbit", "swish", "tabby", "tamara", "touch_n_go", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "verve", "vipps", "webpay", "wechat_pay", "whop_pay", "yape", "zip" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0.0, "initial_price_due": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "internal_notes": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "invoice": null, "member_count": 0, "metadata": {}, "offer_cancel_discount": false, "payment_method_configuration": null, "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50.0, "sku": null, "split_pay_required_payments": null, "stock": 0, "strike_through_initial_price": null, "strike_through_renewal_price": null, "tax_type": "unspecified", "three_ds_level": null, "title": "Unlimited Wash Club", "trial_period_days": 7, "unlimited_stock": false, "updated_at": "2026-01-01T12:00:00.000Z", "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "plan.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Variant" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "plan.updated", "description": "The webhook event type", "example": "plan.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Variant Updated", "tags": [ "Variants" ] }, "x-whop-surface": "native" }, "product.created": { "post": { "description": "Sent when a product is created\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "average_review_rating": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_variant": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "variant_attributes": null, "variants": null, "verified": false, "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "product.created", "description": "The webhook event type", "example": "product.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Created", "tags": [ "Products" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "product.deleted": { "post": { "description": "Sent when a product is deleted\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "average_review_rating": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_variant": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "variant_attributes": null, "variants": null, "verified": false, "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.deleted" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "product.deleted", "description": "The webhook event type", "example": "product.deleted", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Deleted", "tags": [ "Products" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "product.published": { "post": { "description": "Sent when a product is published\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "average_review_rating": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_variant": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "live_marketplace", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "variant_attributes": null, "variants": null, "verified": false, "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.published" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "product.published", "description": "The webhook event type", "example": "product.published", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Published", "tags": [ "Products" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "product.unpublished": { "post": { "description": "Sent when a product is unpublished\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "average_review_rating": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_variant": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "variant_attributes": null, "variants": null, "verified": false, "visibility": "hidden" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.unpublished" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "product.unpublished", "description": "The webhook event type", "example": "product.unpublished", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Unpublished", "tags": [ "Products" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "product.updated": { "post": { "description": "Sent when a product is updated\n\nRequired permissions:\n - `access_pass:basic:read`\n - `webhook_receive:products`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "average_review_rating": 0.0, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_variant": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30.0, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 0.0, "member_affiliate_status": "disabled", "member_count": 0, "metadata": {}, "owner_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "product_tax_code": null, "published_reviews_count": 0, "route": "ceramic-coating-package", "title": "Ceramic Coating Package", "updated_at": "2026-01-01T12:00:00.000Z", "variant_attributes": null, "variants": null, "verified": false, "visibility": "visible" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "product.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Product" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "product.updated", "description": "The webhook event type", "example": "product.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Product Updated", "tags": [ "Products" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "refund.created": { "post": { "description": "Sent when a refund is created\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `webhook_receive:refunds`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": 50.0, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "id": "rf_xxxxxxxxxxxxxx", "metadata": null, "payment": { "billing_reason": null, "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "dispute_alerted_at": null, "id": "pay_xxxxxxxxxxxxxx", "member": null, "membership": { "id": "mem_xxxxxxxxxxxxxx", "status": "active" }, "metadata": {}, "paid_at": "2026-01-01T12:00:00.000Z", "payment_method_type": null, "plan": { "id": "plan_xxxxxxxxxxxxxx", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {} }, "subtotal": null, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "total": null, "usd_total": null, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "provider": "stripe", "provider_created_at": "2026-01-01T12:00:00.000Z", "reference_status": null, "reference_type": null, "reference_value": null, "status": "succeeded" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "refund.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/RefundLegacy" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "refund.created", "description": "The webhook event type", "example": "refund.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Refund Created", "tags": [ "Refunds" ], "x-group-title": "Payins" } }, "refund.updated": { "post": { "description": "Sent when a refund is updated\n\nRequired permissions:\n - `payment:basic:read`\n - `plan:basic:read`\n - `access_pass:basic:read`\n - `member:email:read`\n - `member:basic:read`\n - `member:phone:read`\n - `webhook_receive:refunds`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": 50.0, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "id": "rf_xxxxxxxxxxxxxx", "metadata": null, "payment": { "billing_reason": null, "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "dispute_alerted_at": null, "id": "pay_xxxxxxxxxxxxxx", "member": null, "membership": { "id": "mem_xxxxxxxxxxxxxx", "status": "active" }, "metadata": {}, "paid_at": "2026-01-01T12:00:00.000Z", "payment_method_type": null, "plan": { "id": "plan_xxxxxxxxxxxxxx", "metadata": {} }, "product": { "id": "prod_xxxxxxxxxxxxxx", "metadata": {} }, "subtotal": null, "tax_amount": null, "tax_behavior": null, "tax_refunded_amount": 0.0, "total": null, "usd_total": null, "user": { "email": "marcus@shinetime.example", "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" } }, "provider": "stripe", "provider_created_at": "2026-01-01T12:00:00.000Z", "reference_status": "available", "reference_type": "acquirer_reference_number", "reference_value": "74850120752", "status": "succeeded" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "refund.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/RefundLegacy" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "refund.updated", "description": "The webhook event type", "example": "refund.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Refund Updated", "tags": [ "Refunds" ], "x-group-title": "Payins" } }, "resolution_center_case.created": { "post": { "description": "Sent when a resolution center case is created\n\nRequired permissions:\n - `payment:resolution_center_case:read`\n - `webhook_receive:resolutions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 0.0, "available_actions": [ "accept", "deny", "request_info" ], "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_appealed": false, "escalated": false, "id": "reso_xxxxxxxxxxxxxx", "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": null, "subtotal": null, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "outcome": null, "payment": { "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "pay_xxxxxxxxxxxxxx", "payment_method_type": null }, "product_id": "prod_xxxxxxxxxxxxxx", "reason": "product_not_received", "refund": null, "response_due_at": "2026-01-01T12:00:00.000Z", "status": "awaiting_merchant", "updated_at": "2026-01-01T12:00:00.000Z", "variant_id": "plan_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "resolution_center_case.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "resolution_center_case.created", "description": "The webhook event type", "example": "resolution_center_case.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "ResolutionCenterCase Created", "tags": [ "Resolution Center Cases" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "resolution_center_case.decided": { "post": { "description": "Sent when a resolution center case is decided\n\nRequired permissions:\n - `payment:resolution_center_case:read`\n - `webhook_receive:resolutions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 0.0, "available_actions": [], "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_appealed": false, "escalated": false, "id": "reso_xxxxxxxxxxxxxx", "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": null, "subtotal": null, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "outcome": "customer_won", "payment": { "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "pay_xxxxxxxxxxxxxx", "payment_method_type": null }, "product_id": "prod_xxxxxxxxxxxxxx", "reason": "product_not_received", "refund": "merchant", "response_due_at": null, "status": "closed", "updated_at": "2026-01-01T12:00:00.000Z", "variant_id": "plan_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "resolution_center_case.decided" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "resolution_center_case.decided", "description": "The webhook event type", "example": "resolution_center_case.decided", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "ResolutionCenterCase Decided", "tags": [ "Resolution Center Cases" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "resolution_center_case.updated": { "post": { "description": "Sent when a resolution center case is updated\n\nRequired permissions:\n - `payment:resolution_center_case:read`\n - `webhook_receive:resolutions`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 0.0, "available_actions": [], "buyer": { "email": "marcus@shinetime.example", "member_id": null, "name": "Marcus Webb", "user_id": "user_xxxxxxxxxxxxxx", "username": "marcuswebb" }, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_appealed": false, "escalated": false, "id": "reso_xxxxxxxxxxxxxx", "line_items": [ { "id": null, "label": "Ceramic Coating Package", "product_id": "prod_xxxxxxxxxxxxxx", "product_title": "Ceramic Coating Package", "quantity": 1, "sku": null, "subtotal": null, "variant_id": "plan_xxxxxxxxxxxxxx", "variant_title": null } ], "outcome": null, "payment": { "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "pay_xxxxxxxxxxxxxx", "payment_method_type": null }, "product_id": "prod_xxxxxxxxxxxxxx", "reason": "product_not_received", "refund": null, "response_due_at": "2026-01-01T12:00:00.000Z", "status": "awaiting_customer", "updated_at": "2026-01-01T12:00:00.000Z", "variant_id": "plan_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "resolution_center_case.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/ResolutionCenterCase" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "resolution_center_case.updated", "description": "The webhook event type", "example": "resolution_center_case.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "ResolutionCenterCase Updated", "tags": [ "Resolution Center Cases" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "setup_intent.canceled": { "post": { "description": "Sent when a setup intent is canceled\n\nRequired permissions:\n - `payment:setup_intent:read`\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:setup_intents`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "sint_xxxxxxxxxxxxxx", "last_setup_error": { "code": null, "message": "Your card was declined." }, "member_id": "mber_xxxxxxxxxxxxxx", "metadata": null, "payment_instrument": null, "payment_method_id": null, "payment_method_type": "card", "return_url": null, "status": "canceled", "three_ds_level": null, "three_ds_verified": false, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "setup_intent.canceled" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "setup_intent.canceled", "description": "The webhook event type", "example": "setup_intent.canceled", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "SetupIntent Canceled", "tags": [ "Setup Intents" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "setup_intent.requires_action": { "post": { "description": "Sent when a setup intent is requires action\n\nRequired permissions:\n - `payment:setup_intent:read`\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:setup_intents`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "sint_xxxxxxxxxxxxxx", "last_setup_error": null, "member_id": "mber_xxxxxxxxxxxxxx", "metadata": null, "payment_instrument": null, "payment_method_id": null, "payment_method_type": "card", "return_url": null, "status": "requires_action", "three_ds_level": null, "three_ds_verified": false, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "setup_intent.requires_action" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "setup_intent.requires_action", "description": "The webhook event type", "example": "setup_intent.requires_action", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "SetupIntent Requires action", "tags": [ "Setup Intents" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "setup_intent.succeeded": { "post": { "description": "Sent when a setup intent is succeeded\n\nRequired permissions:\n - `payment:setup_intent:read`\n - `member:basic:read`\n - `member:email:read`\n - `webhook_receive:setup_intents`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "sint_xxxxxxxxxxxxxx", "last_setup_error": null, "member_id": "mber_xxxxxxxxxxxxxx", "metadata": null, "payment_instrument": { "card": { "brand": null, "exp_month": 11, "exp_year": 2030, "issuer_identification_number": null, "last4": "4242" }, "display_name": "Card •••• 4242", "icons": { "card": { "dark": { "png_1x": "https://content.whop.com/payment_methods/card/icons/card_dark_30.png", "png_2x": "https://content.whop.com/payment_methods/card/icons/card_dark_60.png", "png_4x": "https://content.whop.com/payment_methods/card/icons/card_dark_120.png", "svg": "https://content.whop.com/payment_methods/card/icons/card_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/card/icons/card_light_30.png", "png_2x": "https://content.whop.com/payment_methods/card/icons/card_light_60.png", "png_4x": "https://content.whop.com/payment_methods/card/icons/card_light_120.png", "svg": "https://content.whop.com/payment_methods/card/icons/card_light.svg" } }, "square": { "dark": { "png_1x": "https://content.whop.com/payment_methods/card/icons/square_dark_32.png", "png_2x": "https://content.whop.com/payment_methods/card/icons/square_dark_64.png", "png_4x": "https://content.whop.com/payment_methods/card/icons/square_dark_128.png", "svg": "https://content.whop.com/payment_methods/card/icons/square_dark.svg" }, "light": { "png_1x": "https://content.whop.com/payment_methods/card/icons/square_light_32.png", "png_2x": "https://content.whop.com/payment_methods/card/icons/square_light_64.png", "png_4x": "https://content.whop.com/payment_methods/card/icons/square_light_128.png", "svg": "https://content.whop.com/payment_methods/card/icons/square_light.svg" } } }, "installment_count": null, "payment_method_type": "card" }, "payment_method_id": "payt_xxxxxxxxxxxxxx", "payment_method_type": "card", "return_url": null, "status": "succeeded", "three_ds_level": null, "three_ds_verified": false, "updated_at": "2026-01-01T12:00:00.000Z", "user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "marcuswebb" } }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "setup_intent.succeeded" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/SetupIntent" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "setup_intent.succeeded", "description": "The webhook event type", "example": "setup_intent.succeeded", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "SetupIntent Succeeded", "tags": [ "Setup Intents" ], "x-group-title": "Payins" }, "x-whop-surface": "native" }, "shipment.created": { "post": { "description": "Sent when a shipment is created\n\nRequired permissions:\n - `shipment:basic:read`\n - `payment:basic:read`\n - `webhook_receive:shipments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "carrier": "ups", "checkpoints": [], "created_at": "2026-01-01T12:00:00.000Z", "id": "ship_xxxxxxxxxxxxxx", "payment_id": "pay_xxxxxxxxxxxxxx", "status": "pre_transit", "tracking_number": "1Z999AA10123456784", "tracking_url": "https://track.aftership.com/trk_xxxxxxxxxxxxxxxxxxxxxxxx", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "shipment.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Shipment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "shipment.created", "description": "The webhook event type", "example": "shipment.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Shipment Created", "tags": [ "Shipments" ], "x-group-title": "CRM" }, "x-whop-surface": "native" }, "shipment.updated": { "post": { "description": "Sent when a shipment is updated\n\nRequired permissions:\n - `shipment:basic:read`\n - `payment:basic:read`\n - `webhook_receive:shipments`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "carrier": "ups", "checkpoints": [], "created_at": "2026-01-01T12:00:00.000Z", "id": "ship_xxxxxxxxxxxxxx", "payment_id": "pay_xxxxxxxxxxxxxx", "status": "delivered", "tracking_number": "1Z999AA10123456784", "tracking_url": "https://track.aftership.com/trk_xxxxxxxxxxxxxxxxxxxxxxxx", "updated_at": "2026-01-01T12:00:00.000Z" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "shipment.updated" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Shipment" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "shipment.updated", "description": "The webhook event type", "example": "shipment.updated", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Shipment Updated", "tags": [ "Shipments" ], "x-group-title": "CRM" }, "x-whop-surface": "native" }, "swap.completed": { "post": { "description": "Sent when a swap is completed\n\nRequired permissions:\n - `webhook_receive:swaps`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "object": "account", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": "2375000000", "available_at": "2026-01-01T12:00:00.000Z", "currency": { "code": "usd", "precision": "100000000" }, "id": "line_3", "ledger_account_id": "ldgr_xxxxxxxxxxxxxx", "line_type": "payment_gross", "object": "ledger_activity", "payment": { "amount": { "amount": "-1234.56", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "card_brand": "some_string", "card_last4": "some_string", "created_at": "2026-01-01T12:00:00.000Z", "id": "some_string", "object": "payment", "payment_method_type": "some_string", "payment_processor": "some_string", "plan": { "id": "some_string", "name": "some_string" }, "product": { "id": "some_string", "name": "some_string" }, "user": { "email": "some_string", "id": "some_string", "name": "some_string" } }, "payment_id": "some_string", "plan_id": "some_string", "plan_name": "some_string", "posted_at": "2026-01-01T12:00:00.000Z", "product_id": "some_string", "product_name": "some_string", "resource": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "object": "account", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "source": { "amount_float": 1500.0, "card_brand": "some_string", "chain": "plasma", "claim_url": "https://whop.com/claim", "created_at": "2026-01-01T12:00:00.000Z", "created_by_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Dana Whitfield", "profile_picture": { "url": "https://ui-avatars.com/api/" }, "username": "danawhitfield" }, "estimated_arrival": "2026-01-01T12:00:00.000Z", "fee_amount": { "amount": "-1234.56", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "fee_kind": "swap", "fee_type": "exclusive", "from_amount": "502.51", "from_currency": "usdt", "id": "airdrp_xxxxxxxxxxxxxx", "notes": null, "object": "airdrop_link", "payer_name": "MassPay", "payment_amount": { "amount": "-1234.56", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "payment_method_type": "some_string", "payment_processor": "some_string", "payout_amount": { "amount": "-1234.56", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "payout_destination": { "icon_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-activity-icon", "payer_name": "ACH Bank Deposit" }, "payout_token_nickname": "Ops checking", "reason": "bounty_payout", "risk_review_hold": true, "sender_address": "0x8a4de51b9c37f2e6a0d1b8c94e5f7a2d3c6b0e19", "status": "fully_claimed", "to_amount": "500.0", "to_currency": "usd", "trace_code": null, "tx_hash": "0x5d84a1c7e2f9b036d48c5a7e1b9f2d6c3a8e0b4f7c1d9e5a2b6f8c0d3e7a1b52" }, "usd_amount": "23.75", "user_email": "some_string", "user_id": "some_string", "user_name": "some_string" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "swap.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/LedgerActivity" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "swap.completed", "description": "The webhook event type", "example": "swap.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Swap Completed", "tags": [ "Swaps" ] }, "x-whop-surface": "native" }, "transfer.completed": { "post": { "description": "Sent to participating accounts when a transfer succeeds, including when a previously failed transfer succeeds after a retry.\n\nRequired permissions:\n - `webhook_receive:transfers`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": { "amount": "250.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "created_at": "2026-01-01T12:00:00.000Z", "destination": { "id": "biz_xxxxxxxxxxxxx2", "logo_url": null, "name": "Shine Time Auto Detailing", "object": "account" }, "failed_at": null, "failure_code": null, "failure_reason": null, "fee": { "amount": "7.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "id": "ctt_xxxxxxxxxxxxxx", "metadata": { "invoice": "SHINE-1042" }, "notes": "Detailing supplies restock", "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "name": "Marcus Webb", "object": "account" }, "status": "succeeded", "status_changed_at": null, "succeeded_at": null, "tracking_url": "https://whop.com/ctt_xxxxxxxxxxxxxx/" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "transfer.completed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "description": "A transfer between Whop accounts or users.", "properties": { "amount": { "description": "Amount credited to the recipient. Null while the transfer has not succeeded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination": { "description": "Business account or user receiving the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": null, "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "user", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "failed_at": { "description": "Recorded failure time. Null unless the transfer has failed.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable failure code. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "failure_reason": { "description": "Failure explanation. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "fee": { "description": "All applicable transfer fees, including platform markup. Null when the authoritative total is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": "object" }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Business account or user sending the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "account", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "status": { "description": "Current transfer status. A transfer can be created `processing` and settle a few seconds later; poll Retrieve Transfer or listen for the `transfer.completed` and `transfer.failed` webhooks instead of treating the create response as final. `succeeded` and `failed` are final.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" }, "status_changed_at": { "description": "Recorded time of the current transition. Null when the historical transition time is unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "succeeded_at": { "description": "Recorded success time. Null when unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "tracking_url": { "description": "Tracking page for the transfer. Viewing it requires sign-in and access to the transfer.", "example": "https://whop.com/ctt_xxxxxxxxxxxxxx/", "format": "uri", "type": "string" } }, "required": [ "object", "id", "status", "origin", "destination", "amount", "fee", "created_at", "status_changed_at", "succeeded_at", "failed_at", "failure_code", "failure_reason", "notes", "metadata", "tracking_url" ], "title": "Transfer", "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "transfer.completed", "description": "The webhook event type", "example": "transfer.completed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Transfer Completed", "tags": [ "Transfers" ] }, "x-whop-surface": "native" }, "transfer.created": { "post": { "description": "Sent to participating accounts when a transfer succeeds, alongside `transfer.completed`. This event does not indicate entry into `processing`.\n\nRequired permissions:\n - `webhook_receive:transfers`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": { "amount": "250.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "created_at": "2026-01-01T12:00:00.000Z", "destination": { "id": "biz_xxxxxxxxxxxxx2", "logo_url": null, "name": "Shine Time Auto Detailing", "object": "account" }, "failed_at": null, "failure_code": null, "failure_reason": null, "fee": { "amount": "7.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "id": "ctt_xxxxxxxxxxxxxx", "metadata": { "invoice": "SHINE-1042" }, "notes": "Detailing supplies restock", "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "name": "Marcus Webb", "object": "account" }, "status": "succeeded", "status_changed_at": null, "succeeded_at": null, "tracking_url": "https://whop.com/ctt_xxxxxxxxxxxxxx/" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "transfer.created" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "description": "A transfer between Whop accounts or users.", "properties": { "amount": { "description": "Amount credited to the recipient. Null while the transfer has not succeeded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination": { "description": "Business account or user receiving the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": null, "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "user", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "failed_at": { "description": "Recorded failure time. Null unless the transfer has failed.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable failure code. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "failure_reason": { "description": "Failure explanation. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "fee": { "description": "All applicable transfer fees, including platform markup. Null when the authoritative total is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": "object" }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Business account or user sending the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "account", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "status": { "description": "Current transfer status. A transfer can be created `processing` and settle a few seconds later; poll Retrieve Transfer or listen for the `transfer.completed` and `transfer.failed` webhooks instead of treating the create response as final. `succeeded` and `failed` are final.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" }, "status_changed_at": { "description": "Recorded time of the current transition. Null when the historical transition time is unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "succeeded_at": { "description": "Recorded success time. Null when unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "tracking_url": { "description": "Tracking page for the transfer. Viewing it requires sign-in and access to the transfer.", "example": "https://whop.com/ctt_xxxxxxxxxxxxxx/", "format": "uri", "type": "string" } }, "required": [ "object", "id", "status", "origin", "destination", "amount", "fee", "created_at", "status_changed_at", "succeeded_at", "failed_at", "failure_code", "failure_reason", "notes", "metadata", "tracking_url" ], "title": "Transfer", "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "transfer.created", "description": "The webhook event type", "example": "transfer.created", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Transfer Created", "tags": [ "Transfers" ] }, "x-whop-surface": "native" }, "transfer.failed": { "post": { "description": "Sent to participating accounts when an existing transfer enters `failed`. The payload includes `failure_code`, `failure_reason`, and `failed_at`; a retry may later succeed under the same transfer ID.\n\nRequired permissions:\n - `webhook_receive:transfers`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "amount": null, "created_at": "2026-01-01T12:00:00.000Z", "destination": { "id": "biz_xxxxxxxxxxxxx2", "logo_url": null, "name": "Shine Time Auto Detailing", "object": "account" }, "failed_at": "2026-01-01T12:00:00.000Z", "failure_code": "send_reverted", "failure_reason": "Transfer reverted", "fee": null, "id": "ctt_xxxxxxxxxxxxxx", "metadata": {}, "notes": null, "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "name": "Marcus Webb", "object": "account" }, "status": "failed", "status_changed_at": null, "succeeded_at": null, "tracking_url": "https://whop.com/ctt_xxxxxxxxxxxxxx/" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "transfer.failed" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "description": "A transfer between Whop accounts or users.", "properties": { "amount": { "description": "Amount credited to the recipient. Null while the transfer has not succeeded.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "destination": { "description": "Business account or user receiving the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": null, "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "user", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "failed_at": { "description": "Recorded failure time. Null unless the transfer has failed.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable failure code. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "failure_reason": { "description": "Failure explanation. Null unless the transfer has failed.", "example": null, "type": [ "string", "null" ] }, "fee": { "description": "All applicable transfer fees, including platform markup. Null when the authoritative total is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "id": { "description": "Transfer ID.", "example": "ctt_xxxxxxxxxxxxxx", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Custom metadata attached to the transfer.", "example": { "order_id": "SHINE-1042" }, "type": "object" }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Business account or user sending the transfer.", "properties": { "id": { "description": "Account or user ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "logo_url": { "description": "Business logo or user avatar URL. Null when no image is available.", "example": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/shine-time-logo", "type": [ "string", "null" ] }, "name": { "description": "Business or user display name.", "example": "Shine Time Auto Detailing", "type": [ "string", "null" ] }, "object": { "description": "Whether the profile is a business account or a user.", "enum": [ "account", "user" ], "example": "account", "type": "string" } }, "required": [ "object", "id", "name", "logo_url" ], "title": "TransferParty", "type": [ "object", "null" ] }, "status": { "description": "Current transfer status. A transfer can be created `processing` and settle a few seconds later; poll Retrieve Transfer or listen for the `transfer.completed` and `transfer.failed` webhooks instead of treating the create response as final. `succeeded` and `failed` are final.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" }, "status_changed_at": { "description": "Recorded time of the current transition. Null when the historical transition time is unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "succeeded_at": { "description": "Recorded success time. Null when unknown.", "example": null, "format": "date-time", "type": [ "string", "null" ] }, "tracking_url": { "description": "Tracking page for the transfer. Viewing it requires sign-in and access to the transfer.", "example": "https://whop.com/ctt_xxxxxxxxxxxxxx/", "format": "uri", "type": "string" } }, "required": [ "object", "id", "status", "origin", "destination", "amount", "fee", "created_at", "status_changed_at", "succeeded_at", "failed_at", "failure_code", "failure_reason", "notes", "metadata", "tracking_url" ], "title": "Transfer", "type": "object" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "transfer.failed", "description": "The webhook event type", "example": "transfer.failed", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Transfer Failed", "tags": [ "Transfers" ] }, "x-whop-surface": "native" }, "verification.succeeded": { "post": { "description": "Sent when a verification is succeeded\n\nRequired permissions:\n - `payout:account:read`\n - `webhook_receive:verifications`", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "description": "A unique identifier for this webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "description": "The signature of the webhook request with the webhook version prepended", "example": "v1,BASE64ENCODEDSIGNATURE", "type": "string" } }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "description": "The timestamp in seconds since the Unix epoch that the webhook was sent at on the server", "example": "1727606400", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "api_version": "v1", "api_version_date": "2026-10-27-3", "data": { "id": "verf_xxxxxxxxxxxxxx", "last_error_code": null, "last_error_reason": null, "status": "verified" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "verification.succeeded" }, "schema": { "properties": { "account_id": { "description": "The account ID that this webhook event is associated with", "example": "biz_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "api_version": { "const": "v1", "description": "The API version for this webhook", "example": "v1", "type": "string" }, "api_version_date": { "description": "The dated API version (Api-Version-Date) the payload is serialized to", "example": "2026-07-20", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/Verification" }, "id": { "description": "A unique ID for every single webhook request", "example": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "previous_attributes": { "description": "For some `.updated` events, the old values of the payload fields that changed, keyed by field name. Omitted when no capture is available for the event", "type": "object" }, "timestamp": { "description": "The timestamp in ISO 8601 format that the webhook was sent at on the server", "example": "2025-01-01T00:00:00.000Z", "format": "date-time", "type": "string" }, "type": { "const": "verification.succeeded", "description": "The webhook event type", "example": "verification.succeeded", "type": "string" } }, "required": [ "id", "api_version", "api_version_date", "timestamp", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "summary": "Verification Succeeded", "tags": [ "Verifications" ], "x-group-title": "Payouts" } } }, "x-tagGroups": [ { "description": "The accounts and people everything else hangs off.", "name": "Core Resources", "tags": [ "Accounts", "Users", "Members", "Team Members", "External Accounts", "Social Accounts" ] }, { "description": "Accept payments from buyers and handle what comes after.", "name": "Payments", "tags": [ "Payments", "Invoices", "Confirmation Tokens", "Payment Quotes", "Setup Intents", "Refunds", "Resolution Center Cases", "Dispute alerts", "Disputes", "Payment Rules", "Financing Applications" ] }, { "description": "Balances and banking: every way funds move in or out.", "name": "Money", "tags": [ "Deposits", "Transfers", "Payouts", "Ledgers", "Cards", "Cashback Rules", "Swaps", "Trades", "Verifications" ] }, { "description": "Sell products and get paid.", "name": "Commerce", "tags": [ "Products", "Variants", "Promo Codes", "Checkout Configurations", "Waitlist Entries", "Memberships", "Shipments", "Reviews", "Product Affiliates", "Plans" ] }, { "description": "Hosted apps, their builds and domains, and the experiments that run on them.", "name": "Websites", "tags": [ "Domains", "Apps", "App Builds", "App Installations", "Experiments", "Payment Method Domains" ] }, { "description": "Run and measure ad campaigns from your integration.", "name": "Ads", "tags": [ "Ad Campaigns", "Ad Groups", "Ads", "Audiences", "Ad Pixels", "Ad Conversion Value Rules" ] }, { "description": "Who visits, what converts, and how an account is performing.", "name": "Analytics", "tags": [ "Stats", "Reports", "People", "Events", "Exports", "Economic Intelligence" ] }, { "description": "Channels, the messages exchanged within them, livestreams, the notifications users receive, and email mailboxes.", "name": "Communication", "tags": [ "Messages", "Livestreams", "Notifications", "Email addresses" ] }, { "description": "Refer users and businesses to Whop and track what you earn.", "name": "Partners", "tags": [ "Partners", "Partner Referral Requests" ] }, { "description": "Post paid tasks and pay people for completed work.", "name": "Workforce", "tags": [ "Bounties", "Bounty Submissions" ] }, { "description": "Generate media assets from your integration.", "name": "Media", "tags": [ "Files", "Media" ] }, { "description": "Credentials, webhooks, and logs for integrating with the Whop API.", "name": "Developer", "tags": [ "API Keys", "Webhooks", "Permissions", "Api Logs", "Feedback" ] } ] }