{ "openapi": "3.1.0", "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-09-06" }, "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 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 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": "A Member is one buyer's relationship with an account — one record per customer regardless of how many memberships they hold. It carries relationship-level state: whether they have joined or left, their access level (`customer`, `admin`, or `no_access`), when they joined, and when they last opened the account's content.\n\nUse the Members API to list an account's members with filtering by access level, status, join date, and name or username search, and to retrieve a single member. 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." }, { "name": "Webhooks", "x-whop-summary": "Event notifications pushed to your server as things happen." }, { "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 available metrics and their filterable properties, then retrieve time-series values for a date range.\n", "name": "Stats", "x-whop-summary": "Aggregated financial, audience, and traffic reporting." }, { "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": "An Export is an asynchronous CSV of one resource for one account — members, payments, disputes, ads, and the other tables the Whop dashboard can export. Generating a full table takes longer than a request, so an export is created in `pending`, moves through `processing`, and lands on `completed` with a download link. Each resource requires that resource's own export scope.\n\nUse the Exports API to start an export, poll it until `download_url` is set, and list the exports already requested for an account. Finished CSVs are retained for 30 days, after which the file is deleted and the export moves to `expired`.\n", "name": "Exports", "x-whop-summary": "Asynchronous CSV dumps of an account's dashboard data." }, { "description": "A Notification is a message delivered to a user — a new post, a payment, a mention. Every notification comes from an experience the user belongs to or a team they are on, and users control what they receive with notification preferences.\n\nEvery notification belongs to a topic: the category it falls under, such as new sales or account activity. Topics carry a default, so a user only needs a preference row where they diverge from it. `GET /notifications/topics` lists the platform's visible topics, and a topic's `id` is what the notification preference endpoints take as `topic_id` — the catalog is the only place those ids come from, so read it rather than hardcoding. Each topic also carries an `identifier` such as `new-follower`, which is stable across environments and is the value to match on in code.\n\nUse the Notifications API to list the authenticated user's feed, read per-experience unread badges, mark an experience (or everything) as read, send notifications from your app to an experience's users or an account's team, and list the topic catalog.\n", "name": "Notifications", "x-whop-summary": "The user's notification feed: unread badges, mark-read, app sends, and the topic catalog." }, { "description": "A Payment is one charge against a buyer. 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\nCollection runs in the background, so the create response is not the outcome. Poll [Retrieve status](/api-reference/beta/payments/retrieve-status) for how far the payment has got 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. Use the return_url operation 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": "A Refund is one reversal of a payment, full or partial. Refunds are issued with `POST /payments/{id}/refund`; this resource is the record of each one — how much moved, through which provider, and where it stands (`pending`, `succeeded`, `failed`).\n\nList a payment's refunds with `?payment_id=`, or every refund an account issued with `?account_id=`. `amount` is stated in the payment's settlement currency so it nets against the payment's `total`; `original_amount` is what the processor moved.\n", "name": "Refunds", "x-whop-summary": "Money returned to a buyer from a payment." }, { "description": "A Confirmation Token is a single-use, short-lived reference to a payment method and billing details collected from a buyer. Its response contains only a display-safe preview and never returns the underlying payment credential.\n\nCreate a confirmation token in a buyer-facing collection flow, then send its `ctok_` ID 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 Setup Intent saves a buyer's payment method for later without taking money now. 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\nPoll [Retrieve status](/api-reference/beta/setup-intents/retrieve-status) for how far the setup has got and what is outstanding. Once it reaches `succeeded` the method is on file and can be charged.\n", "name": "Setup Intents", "x-whop-summary": "Saving a buyer's payment method without charging it." }, { "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.\n", "name": "Disputes", "x-whop-summary": "Chargebacks filed against an account, with evidence and outcomes." }, { "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 Resolution Center Case is opened by a buyer when something is wrong with a purchase — an unwanted renewal, an item that never arrived, or a charge they don't recognize. It is the step before a chargeback: the two sides work it out directly, and Whop decides the case if they can't. Each case carries a reason, a status naming which side it is waiting on, a timeline of events, and the actions available to whoever is reading it.\n\nUse the Resolution Center Cases API from either side: as the buyer, open a case, reply, appeal a decision, or withdraw it; as the merchant, accept it (refunding the payment), deny it, or ask the buyer for more information. Both sides read the same case, page its timeline, and summarize the cases they can see.\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 Ledger Activity row is a single financial event on an account's ledger — a payment, payout, refund, transfer, on-chain deposit, swap, or card transaction. Each row is derived from the underlying ledger lines and carries a typed `resource` and `source` so you can present and link the event without extra lookups.\n\nUse Ledger Activity to build a statement or transaction feed for an account or user. Reconcile against your own records with `amount` (signed, in the currency's smallest precision units) and `posted_at`, and use `available_at` to know when inflows became withdrawable.\n", "name": "Ledgers", "x-whop-docs-title": "Financial Activity", "x-whop-summary": "The activity feed behind an account or user's balance." }, { "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": "Cards represent Whop-issued 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, and retrieve active card details such as the card number and CVC.\n", "name": "Cards", "x-whop-summary": "Issue cards that spend from a balance." }, { "description": "Transfers move value between identities on Whop. They are used for account-to-account money movement, user payouts inside Whop, crypto transfers, and claim links depending on the destination type.\n\nUse the Transfers API to create a transfer, list previous transfers, and retrieve a transfer by ID when reconciling money movement between accounts or users.\n", "name": "Transfers", "x-whop-summary": "Move funds between Whop accounts and users." }, { "description": "Deposits describe ways to add funds to an account balance, including hosted deposit pages, bank deposit instructions, and supported crypto wallet addresses.\n\nUse the Deposits API to create deposit instructions for an account. Crypto deposits require a $10 minimum.\n", "name": "Deposits", "x-whop-summary": "Add funds to a balance." }, { "description": "Swaps convert value between supported tokens, chains, or wallet destinations for an account. A swap quote describes 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 status until the transaction completes.\n", "name": "Swaps", "x-whop-summary": "Convert a balance between currencies." }, { "description": "A Product is a digital good or service sold on Whop. Products may contain plans for pricing and/or 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 plans and a store page." }, { "description": "A Plan defines how customers buy a product. It controls pricing, billing cadence, availability, tax behavior, checkout fields, and purchase visibility.\n\nUse the Plans API to create plans for products, list existing plans, retrieve or update plan configuration, calculate tax for checkout, and delete plans that should no longer be offered.\n", "name": "Plans", "x-whop-summary": "Pricing for a product: one-time, recurring, trials, stock." }, { "name": "Promo Codes", "x-whop-summary": "Discounts that creators configure for checkout." }, { "description": "A Membership is a customer's purchase of a plan: 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 the caller's own, retrieve one by ID or license key, invite a recipient to join through a free plan, and manage the lifecycle: cancel immediately or at period end, reverse a scheduled period-end cancellation, pause and resume payment collection, extend with free days, generate a transfer link, and update metadata.\n", "name": "Memberships", "x-whop-summary": "A customer's purchase of a plan, from checkout through cancellation." }, { "description": "A Checkout Configuration is a reusable checkout link owned by an account. In `payment` mode it sells a specific plan; 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 plan, 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 plan into a shareable, prefilled checkout link." }, { "description": "A 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.\n\nUse the Payment Method Domains API to register domains for your account or its connected accounts, retry verification once the association file is hosted, and remove domains that should no longer serve wallet payments. A domain a platform shares with its connected accounts at checkout is listed on the platform's account, not on each connected account.\n\nWallet buttons at checkout depend on this: embedded surfaces like the [Express Checkout element](/elements/beta/checkout/expressCheckout) only render Apple Pay on a `verified` domain (first-party whop.com pages are pre-approved). To verify a domain, [create it](/api-reference/beta/payment-method-domains/create-payment-method-domain), host the association file at the path above, then [retry verification](/api-reference/beta/payment-method-domains/verify-payment-method-domain) until `status` is `verified`.\n", "name": "Payment Method Domains", "x-whop-summary": "Domains verified to show wallet payment methods like Apple Pay at checkout." }, { "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": "The Partners API covers your Whop partner activity: the users you referred onto Whop, the businesses you referred and the earnings generated from their processing volume, and the partner leaderboard.\n\nUse it to enroll as a Whop partner, list the users you referred, list your referred businesses and review their earnings, and see the partner leaderboard.\n", "name": "Partners", "x-whop-summary": "The users and businesses you referred to Whop, and what you earn from them." }, { "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 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 — pixel page views, ad clicks, leads, identifies, and payments. Each profile carries the person's known identities (names, emails, phones, user IDs), purchase history and LTV, geo/device profile, traffic sources, and the first and last marketing touches that reached them.\n\nUse the People API to list and segment the people of an account — filter by activity, purchases, traffic source, location, or marketing touch, and sort by value — or 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": "A Recommended Action Chain is a short, ordered sequence of dashboard actions — create a product, price it, publish it — suggested for an account based on what it already has. Seeded chains come from hand-written presets; generated chains, produced per account, share the same shape.\n\nUse the Recommended Actions API to list the chains recommended for an account and to record that a chain was run. Running a chain executes nothing server-side — the client follows each step's CTA itself; the run endpoint records the `recommended_action_chain.executed` analytics event.\n", "name": "Recommended Actions", "x-whop-summary": "Suggested next-step action chains for an account." }, { "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 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", "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 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, list, and delete audiences and monitor asynchronous processing. Meta engagement sources include videos, lead forms, Instagram profiles, and Facebook pages. Engagement 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": "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": "A Social Account represents an external profile connected to a Whop account or user, such as a Facebook page or Instagram account. Connecting a social account lets Whop run [ads](/api-reference/beta/ads/ad) under that profile's identity and promote its existing posts.\n\nUse the Social Accounts API to list connected accounts, create a Whop-managed Facebook page, start an OAuth connection, disconnect a social account, and list a connected profile's posts or a Facebook page's lead forms.\n", "name": "Social Accounts", "x-whop-summary": "Connected Facebook and Instagram accounts that run ads." }, { "description": "An App is software you build on Whop. It can be a hosted web app served at `.whop.site` 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. Logs are retained for 7 days and can be filtered by build, level, time window, and message text.\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 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": "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 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." } ], "x-tagGroups": [ { "description": "The accounts and people everything else hangs off.", "name": "Core Resources", "tags": [ "Accounts", "Users", "Team Members", "Members", "Webhooks", "Stats", "Verifications", "Exports" ] }, { "description": "What users get told about, and how they tune it.", "name": "Notifications", "tags": [ "Notifications" ] }, { "description": "Accept payments from buyers and handle what comes after.", "name": "Payments", "tags": [ "Payments", "Refunds", "Confirmation Tokens", "Setup Intents", "Disputes", "Dispute alerts", "Resolution Center Cases" ] }, { "description": "Balances and banking: every way funds move in or out.", "name": "Money", "tags": [ "Ledgers", "Payouts", "Cards", "Transfers", "Deposits", "Swaps" ] }, { "description": "Sell products and get paid.", "name": "Commerce", "tags": [ "Products", "Plans", "Promo Codes", "Memberships", "Checkout Configurations", "Payment Method Domains", "Shipments" ] }, { "description": "Refer users and businesses to Whop and track what you earn.", "name": "Partners", "tags": [ "Partners" ] }, { "description": "Post paid tasks and pay people for completed work.", "name": "Workforce", "tags": [ "Bounties", "Bounty Submissions" ] }, { "description": "Who visits and what converts, captured by the pixel.", "name": "Tracking", "tags": [ "People", "Events", "Reports", "Recommended Actions" ] }, { "description": "Run and measure ad campaigns from your integration.", "name": "Ads", "tags": [ "Ads", "Ad Campaigns", "Ad Groups", "Audiences" ] }, { "description": "Generate media assets from your integration.", "name": "Media", "tags": [ "Files", "Media" ] }, { "description": "Accounts connected from other platforms.", "name": "Identity", "tags": [ "Social Accounts" ] }, { "description": "Build, host, and observe apps on the Whop platform.", "name": "Developer", "tags": [ "Apps", "App Builds", "API Keys", "Api Logs", "Permissions", "Experiments" ] } ], "paths": { "/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. Pass `parent_account_id` to return only that parent account's connected accounts.", "operationId": "listAccounts", "parameters": [ { "description": "The number of accounts to return (default 10, max 50).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns accounts after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of accounts to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns accounts before this position.", "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" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Account" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const account of client.accounts.list()) {\n console.log(account.id);\n}" } ] }, "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": "The username, if any, of the partner who referred this account", "example": "random-username-47-xxxxxxxx", "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" }, "email": { "description": "The email address of the account owner. Required for Account API key requests.", "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" }, "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": "Shine Time Auto Detailing", "type": "string" } }, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst account = await client.accounts.create();\n\nconsole.log(account.id);" } ] } }, "/accounts/{account_id}/preferences": { "get": { "description": "Retrieves the account's preferences: a singleton settings document keyed by preference name.", "operationId": "retrieveAccountPreferences", "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": "signed", "type": "string" } }, "required": [ "status", "agreement_version", "printed_name", "accepted_at" ], "type": "object" }, "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.", "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 connected Shopify store domain spend is reported for, such as `acme.myshopify.com`. `null` when no store is connected.", "example": "shinetime.myshopify.com", "type": [ "string", "null" ] }, "status": { "description": "Where the integration stands. `requires_shopify_store` means no Shopify store is connected — Triple Whale keys records by Shopify shop, so no spend is reported until one is.", "enum": [ "connected", "not_connected", "requires_shopify_store" ], "example": "connected", "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" }, "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" } }, "required": [ "ads_payment_methods", "ads_reporting_currency", "ads_scheduling_timezone", "ads_agreement", "ads_triple_whale_integration", "cards_auto_top_up", "cards_notifications", "dispute_fighter_enabled" ], "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" ] } ], "summary": "Retrieve Account Preferences", "tags": [ "Accounts" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve Preferences" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst preference = await client.accounts.preferences.retrieve('account_id');\n\nconsole.log(preference.ads_agreement);" } ] }, "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. `ads_triple_whale_integration` takes the Data-In API key to connect with, or `null` to disconnect. `ads_payment_methods` always requires a `primary` entry. `backup` is optional and any pairing is allowed — two cards, `card`+`platform_balance`, or a single method — so a card-only advertiser can fund ads without a platform balance. The `primary` and `backup` must be different sources. A `platform_balance` entry may omit `id` to use the account's default Whop balance. Configuring a `card` requires a user token; account API keys can set up platform-balance billing only.", "operationId": "updateAccountPreferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ads_payment_methods": { "description": "How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when the primary fails.", "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`.", "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.", "example": "PST8PDT", "type": "string" }, "ads_triple_whale_integration": { "description": "Connects or disconnects the Triple Whale integration. Requires a connected Shopify store, since Triple Whale keys spend records by Shopify shop.", "properties": { "api_key": { "description": "A Triple Whale Data-In API key with the `Data-In Write: Ads` 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.", "example": "tw_live_key_1234", "type": [ "string", "null" ] } }, "required": [ "api_key" ], "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.", "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.", "example": true, "type": "boolean" }, "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": true, "type": "boolean" } }, "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_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.", "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 connected Shopify store domain spend is reported for, such as `acme.myshopify.com`. `null` when no store is connected.", "example": "shinetime.myshopify.com", "type": [ "string", "null" ] }, "status": { "description": "Where the integration stands. `requires_shopify_store` means no Shopify store is connected — Triple Whale keys records by Shopify shop, so no spend is reported until one is.", "enum": [ "connected", "not_connected", "requires_shopify_store" ], "example": "requires_shopify_store", "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" }, "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" } }, "required": [ "ads_payment_methods", "ads_reporting_currency", "ads_scheduling_timezone", "ads_agreement", "ads_triple_whale_integration", "cards_auto_top_up", "cards_notifications", "dispute_fighter_enabled" ], "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" } }, "security": [ { "bearerAuth": [ "ad_campaign:create" ] }, { "bearerAuth": [ "payout:account:update" ] } ], "summary": "Update Account Preferences", "tags": [ "Accounts" ], "x-mint": { "metadata": { "sidebarTitle": "Update Preferences" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst preference = await client.accounts.preferences.update('account_id');\n\nconsole.log(preference.ads_agreement);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "List Reserves" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst reserves = await client.accounts.reserves.list('account_id');\n\nconsole.log(reserves.data);" } ] } }, "/accounts/{id}": { "get": { "description": "Retrieves a single account by ID or public route when it is visible to the credential, including its crypto wallet. The reserved id `me` retrieves the account associated with the current Account API key; user tokens have no single account, so they must address one by ID or route.", "operationId": "retrieveAccount", "parameters": [ { "description": "Account ID, prefixed `biz_`, its public route, or `me` for the account associated with the current API key.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "description": "account settling on stablecoin rails" }, "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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst account = await client.accounts.retrieve('id');\n\nconsole.log(account.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates an account. User tokens can update business accounts; Account API keys can update connected accounts. The reserved id `me` — accepted on Retrieve Account — resolves to the requesting account, which an Account API key cannot edit, so updates must name the connected account by its `biz_` id.", "operationId": "updateAccount", "parameters": [ { "description": "Account ID, prefixed `biz_`.", "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" ] }, "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.", "enum": [ "education_program", "coaching", "software", "paid_group", "newsletter", "agency", "physical_products", "brick_and_mortar", "events", "coaching_and_courses", "other", "services", "gig_economy", "marketplace", "telehealth", "class_action_settlement", "physical_product", "saas", "course", "community", null ], "example": "other", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "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" ] }, "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" }, "industry_group": { "description": "Account industry group. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "enum": [ "academic_and_test_prep", "accessories", "agriculture_and_farming", "ai_and_automation_agencies", "ai_and_automation_software", "arts_and_crafts", "automotive", "b2b_and_professional_marketplaces", "baby_and_kids", "bars_and_breweries", "beauty_and_personal_care", "beauty_and_wellness", "business_and_entrepreneurship", "business_and_money_groups", "cafes_and_quick_service", "career_and_professional", "charity_and_cause_events", "class_action_settlement", "clothing_and_apparel", "communication_and_messaging_software", "community_and_education_software", "conference_and_expo_events", "consulting", "content_and_clipping_agencies", "creative_and_content_creation", "creative_and_content_groups", "creative_and_education", "creative_gigs", "creative_services", "customer_support_agencies", "dating_and_relationships", "delivery_and_logistics", "dental_and_vision", "dermatology_and_skin", "design_and_creative_agencies", "developer_and_technical_tools", "development_agencies", "digital_and_education_marketplaces", "digital_goods_and_accounts", "e_commerce_software", "education_and_childcare", "educational_training_events", "electronics_and_gadgets", "entertainment_and_leisure", "family_and_community_events", "finance_and_investing", "fitness_and_athletics", "fitness_and_health_groups", "fitness_and_recreation", "fitness_equipment_and_gear", "food_and_beverages", "food_and_hospitality_marketplaces", "funeral_and_death_care", "gaming_and_entertainment_software", "gaming_groups", "genetic_and_specialized", "government_and_public", "health_and_wellness", "health_and_wellness_services", "healthcare", "healthcare_and_wellness_software", "hobbies_and_lifestyle", "hobby_and_interest_groups", "home_and_living", "home_and_trade_services", "home_and_trade_storefronts", "home_improvement_and_tools", "home_services_gigs", "hospitality_and_lodging", "industrial_and_manufacturing", "industry_specific_software", "language_and_communication", "legal_and_compliance", "lifestyle_and_culture", "lifestyle_and_personal_growth", "lifestyle_and_personal_growth_groups", "lifestyle_and_wellness_events", "logistics_and_transportation_services", "marketing_agencies", "marketing_and_advertising", "marketing_and_sales_software", "media_and_publishing_companies", "mental_health_and_behavioral", "miscellaneous", "music_and_performing_arts", "news_and_politics", "nonprofit_and_charity", "office_and_business_supplies", "outdoor_and_sports", "performance_and_show_events", "personal_development", "personal_finance", "personal_services", "pet_services", "pets_and_animals", "primary_and_general_care", "product_marketplaces", "productivity_and_business_ops", "professional_gigs", "professional_services", "professional_services_storefront", "publishing_and_info_products", "real_estate", "real_estate_software", "recruiting_and_staffing", "rehabilitation_and_therapy", "religion_and_faith", "rental_marketplaces", "restaurants", "retail", "sales_agencies", "sales_and_revenue", "security_and_investigations", "security_and_privacy_software", "service_marketplaces", "sleep_and_chronic_conditions", "social_and_networking_events", "social_entertainment_events", "specialized_gigs", "specialty_medical_care", "spirituality_and_mindfulness", "spirituality_and_personal_growth", "sports_and_fitness_events", "sports_betting_and_gambling", "sports_betting_groups", "supplements_and_nutrition", "sustainability_and_eco_products", "task_and_errands", "tech_and_ai", "tech_and_dev_groups", "tech_and_development", "trading_and_finance_software", "trading_and_investing", "trading_and_investing_groups", "transportation", "veterinary", "video_games_and_esports", "weight_and_metabolic_health", "wellness_and_alternative", "womens_and_mens_health", null ], "example": "automotive", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "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.", "enum": [ "trading", "sports_betting", "reselling", "fitness", "amazon_fba", "real_estate", "kindle_book_publishing", "dating", "agencies", "health_and_wellness", "social_media", "sales", "business", "ecommerce", "video_games", "home_services", "ai", "public_speaking", "personal_finance", "careers", "travel", "clipping", "spirituality", "vas", "personal_development", "software", "other", "marketing_agency", "sales_agency", "ai_agency", "design_agency", "coaching_agency", "development_agency", "recruiting_agency", "customer_support_agency", "clipping_agency", "clothing", "supplements", "beauty_and_personal_care", "fitness_gear", "accessories", "home_goods", "electronics_and_gadgets", "food_and_beverages", "gym", "restaurant", "retail_store", "coffee_shop", "salon_spa", "medical_dentist_office", "hotel_lodging", "auto_repair_shop", "masterminds", "webinars", "bootcamps", "convention", "concerts", "meetups", "parties", "forex_trading", "stock_trading", "options_trading", "crypto_trading", "futures_trading", "day_trading", "swing_trading", "algorithmic_trading", "prop_firm_trading", "value_investing", "real_estate_investing", "alternative_investments", "penny_stock_trading", "dividend_investing", "index_fund_investing", "gold_precious_metals", "venture_capital_education", "private_equity_education", "technical_analysis", "forex_scalping", "ict_smc_trading", "personalized_investment_advice", "forex_signals_group", "stock_signals_group", "crypto_signals_group", "options_alerts_group", "futures_signals_group", "trading_education_group", "investing_community", "prediction_markets_group", "nft_alpha_group", "penny_stock_group", "dividend_investing_group", "real_estate_investing_group", "prop_firm_group", "forex_trading_bot", "stock_trading_platform", "crypto_trading_bot", "futures_trading_bot", "options_flow_tool", "portfolio_tracker", "financial_modeling_software", "accounting_software", "invoicing_software", "tax_software", "risk_management_software", "prop_trading_platform", "backtesting_software", "trading_indicators", "market_data_feed", "stock_research_tool", "banking_software", "lending_platform", "insurance_software", "bnpl_service", "check_cashing_service", "cloud_mining_schemes", "consumer_lending", "credit_repair_service", "crypto_exchange_brokerage", "crypto_trading_tools_software", "debt_collection_agency", "debt_relief_settlement", "escrow_service", "foreign_exchange_service", "non_custodial_wallet_tools", "payment_facilitation", "prediction_market_exchange", "stablecoin_issuance", "token_sales_ico", "tokenized_rwa", "yield_staking_products", "sports_betting_picks", "fantasy_sports", "horse_racing", "poker_coaching", "esports_betting", "sports_analytics", "nfl_betting", "nba_betting", "mlb_betting", "soccer_betting", "mma_ufc_betting", "sports_picks_group", "dfs_group", "horse_racing_group", "esports_picks_group", "nfl_picks_group", "nba_picks_group", "soccer_picks_group", "mlb_picks_group", "mma_picks_group", "prop_bets_group", "fantasy_sports_free_to_play", "licensed_gambling_operations", "unlicensed_gambling", "bodybuilding_coaching", "strength_training", "weight_loss_coaching", "athletic_performance", "yoga_instruction", "martial_arts_instruction", "running_coaching", "calisthenics", "flexibility_mobility", "nutrition_coaching", "swimming_coaching", "cycling_coaching", "boxing_coaching", "mma_coaching", "jiu_jitsu_coaching", "wrestling_coaching", "gymnastics_coaching", "pilates_instruction", "sports_nutrition", "body_recomposition", "golf_coaching", "tennis_coaching", "basketball_training", "soccer_training", "racket_sports_coaching", "fitness_accountability", "nutrition_community", "weight_loss_group", "bodybuilding_community", "running_community", "martial_arts_community", "mental_health_group", "biohacking_community", "addiction_support_group", "yoga_community", "crossfit_community", "longevity_community", "womens_fitness_community", "postpartum_fitness_group", "chronic_illness_support", "skincare_community", "mental_health_coaching", "life_coaching", "biohacking", "holistic_health", "addiction_recovery_coaching", "breathwork", "meditation_mindfulness", "gut_health_coaching", "longevity_coaching", "womens_health_coaching", "mens_health_coaching", "fertility_wellness", "stress_management", "grief_coaching", "trauma_recovery_coaching", "adhd_coaching", "biomarker_health_coaching", "telehealth_platform", "ehr_software", "practice_management", "mental_health_app", "fitness_app", "nutrition_tracking_app", "wellness_app", "patient_engagement", "medical_billing_software", "pharmacy_management", "lab_management", "clinical_trial_software", "dental_software", "veterinary_software", "health_data_platform", "fitness_newsletter", "mental_health_newsletter", "longevity_newsletter", "medical_newsletter", "biohacking_newsletter", "womens_health_newsletter", "mens_health_newsletter", "pharma_biotech_newsletter", "ecommerce_education", "amazon_fba_coaching", "dropshipping_coaching", "print_on_demand_coaching", "retail_arbitrage", "wholesale_coaching", "startup_coaching", "business_strategy", "agency_building", "smma_coaching", "consulting_business", "saas_entrepreneurship", "local_business_coaching", "cleaning_business_coaching", "trucking_business_coaching", "vending_machine_business", "atm_business_coaching", "car_wash_business", "airbnb_business_coaching", "private_label_coaching", "etsy_coaching", "merch_business_coaching", "licensing_business", "business_acquisition", "women_entrepreneurship", "affiliate_marketing_education", "coaching_business_coaching", "ecommerce_community", "agency_community", "saas_community", "saas_marketing_community", "real_estate_community", "sales_community", "affiliate_community", "reselling_community", "amazon_seller_community", "dropshipping_community", "freelancer_community", "startup_founder_community", "ceo_executive_community", "women_business_community", "marketing_community", "ai_business_community", "content_business_community", "local_business_community", "private_equity_community", "wholesaling_community", "coaching_business_community", "make_money_online_community", "startup_newsletter", "ecommerce_newsletter", "marketing_newsletter", "sales_newsletter", "small_business_newsletter", "leadership_newsletter", "agency_newsletter", "saas_newsletter", "hr_people_newsletter", "legal_business_newsletter", "real_estate_business_newsletter", "solopreneur_newsletter", "high_ticket_sales", "b2b_sales_coaching", "door_to_door_sales", "sales_funnel_coaching", "appointment_setting_coaching", "insurance_sales_coaching", "car_sales_coaching", "retail_sales_coaching", "solar_sales_coaching", "lead_generation_agency", "cold_email_agency", "cold_calling_agency", "sales_outsourcing", "crm_implementation", "appointment_setting_agency", "sales_training_agency", "revenue_operations_agency", "inbound_teleservices", "outbound_telemarketing", "facebook_ads", "google_ads", "tiktok_marketing", "youtube_marketing", "instagram_growth", "seo_coaching", "email_marketing_coaching", "copywriting_coaching", "affiliate_marketing", "local_seo", "ai_marketing", "webinar_marketing", "event_marketing", "saas_marketing_coaching", "digital_marketing", "smma", "performance_marketing_agency", "seo_agency", "content_marketing_agency", "email_marketing_agency", "influencer_marketing_agency", "pr_agency", "branding_agency", "video_marketing_agency", "amazon_marketing_agency", "podcast_marketing_agency", "tiktok_agency", "linkedin_agency", "local_marketing_agency", "dental_marketing_agency", "real_estate_marketing_agency", "restaurant_marketing_agency", "ecommerce_marketing_agency", "b2b_marketing_agency", "growth_marketing_agency", "affiliate_management_agency", "conversion_optimization_agency", "event_marketing_agency", "click_farm_service", "data_scraping_service", "lead_list_sales", "social_media_bot_farm", "crm_software", "email_marketing_software", "sms_marketing_software", "seo_tool", "landing_page_builder", "ad_management_tool", "affiliate_tracking", "review_management", "analytics_dashboard", "lead_gen_software", "link_in_bio_tool", "influencer_platform", "webinar_platform", "ab_testing_tool", "chatbot_marketing", "video_sales_tool", "proposal_software", "competitive_intelligence", "social_listening_tool", "whatsapp_marketing_tool", "standalone_tipping", "video_editing_education", "photography_coaching", "music_production", "ui_ux_design_education", "clipping_education", "ugc_creation", "3d_modeling_education", "dj_education", "youtube_automation", "blog_monetization", "wedding_photography_education", "calligraphy_lettering", "illustration_education", "fashion_design_education", "interior_design_education", "influencer_education", "ai_content_creator_education", "ai_nsfw_content_generation_education", "web_design_agency", "graphic_design_agency", "ui_ux_agency", "motion_design_agency", "product_design_agency", "logo_design_agency", "presentation_design_agency", "3d_visualization_agency", "fashion_design_agency", "video_clipping_agency", "video_production_agency", "ugc_agency", "content_writing_agency", "translation_agency", "social_media_management", "ghostwriting_agency", "podcast_editing_agency", "thumbnail_design_agency", "scriptwriting_agency", "seo_content_agency", "technical_writing_agency", "photography_service", "videography_service", "music_production_service", "voice_over_service", "event_photography", "drone_services", "commercial_photography", "portrait_photography_service", "real_estate_photography", "food_photography_service", "live_event_production", "podcast_production_service", "freelance_design_gig", "freelance_writing_gig", "freelance_dev_gig", "music_performance_gig", "event_staffing_gig", "model_talent_gig", "photography_gig", "videography_gig", "voiceover_gig", "illustration_gig", "social_media_gig", "dj_gig", "face_painting_gig", "clipping_gig", "content_creator_community", "video_editing_community", "music_producer_community", "photography_community", "writing_community", "design_community", "youtube_creator_community", "tiktok_creator_community", "podcast_community", "filmmaker_community", "clipping_community", "youtube_automation_community", "pirated_digital_content", "web_development_education", "ai_ml_education", "data_science_education", "cybersecurity_education", "cloud_computing_education", "blockchain_education", "no_code_education", "automation_education", "game_development_education", "prompt_engineering", "python_programming", "javascript_programming", "react_development", "database_engineering", "aws_certification", "data_engineering", "robotics_education", "vr_ar_development", "linux_sysadmin", "wordpress_development", "ai_agent_building", "web_development_agency", "mobile_app_agency", "saas_development_agency", "ecommerce_development", "blockchain_development_agency", "game_development_agency", "devops_agency", "ai_development_agency", "wordpress_agency", "shopify_agency", "api_integration_agency", "cybersecurity_agency", "data_engineering_agency", "vr_ar_development_agency", "hacking_tools_malware", "stalkerware_monitoring", "developer_community", "ai_community", "cybersecurity_community", "no_code_community", "indie_hacker_community", "devops_community", "data_science_community", "product_community", "open_source_community", "api_management", "hosting_platform", "database_tool", "devops_tool", "monitoring_tool", "testing_tool", "code_editor", "no_code_builder", "cdn_platform", "error_tracking", "documentation_tool", "webhook_tool", "3d_weapon_files", "background_check_services", "document_falsification", "fake_id_services", "fake_reference_services", "real_estate_wholesaling", "house_flipping", "property_development", "rental_property", "airbnb_str", "commercial_real_estate", "land_investing", "section_8_housing", "mobile_home_investing", "multifamily_investing", "self_storage_investing", "property_management_education", "vacation_rental_management", "real_estate_crm", "property_management_software", "deal_analysis_tool", "mls_search_tool", "virtual_tour_software", "real_estate_marketing_software", "construction_management", "home_valuation_tool", "credit_repair_education", "budgeting_coaching", "tax_strategy_education", "wealth_building", "student_loan_strategy", "credit_card_optimization", "career_coaching", "executive_coaching", "management_coaching", "tech_career_coaching", "medical_career_coaching", "trade_skills_education", "va_training", "bookkeeping_education", "data_career_coaching", "cybersecurity_career", "consulting_career", "investment_banking_career", "law_career_coaching", "nursing_career_coaching", "teaching_career_coaching", "personal_branding_career", "mens_dating_coaching", "womens_dating_coaching", "relationship_coaching", "marriage_coaching", "communication_coaching", "masculinity_coaching", "femininity_coaching", "breakup_recovery", "manifestation_coaching", "astrology_coaching", "energy_healing", "spiritual_coaching", "faith_based_coaching", "psychic_development", "numerology_coaching", "chakra_healing", "shamanic_healing", "biblical_coaching", "islamic_coaching", "productivity_coaching", "public_speaking_coaching", "mindset_coaching", "stoicism_philosophy", "mens_self_improvement", "womens_self_improvement", "leadership_development", "anger_management", "neurolinguistic_programming", "appearance_and_grooming_coaching", "amazon_kdp", "self_publishing", "audiobook_publishing", "course_creation", "digital_product_creation", "ghostwriting_business", "template_creation", "ai_book_publishing", "language_learning", "tutoring", "college_admissions_coaching", "cpa_exam_prep", "bar_exam_prep", "real_estate_exam_prep", "medical_board_prep", "pmp_certification_prep", "aws_certification_prep", "comptia_certification", "ap_exam_prep", "graduate_school_prep", "scholarship_coaching", "homeschool_education", "stem_education", "financial_certification", "coding_bootcamp_prep", "cooking_culinary", "travel_coaching", "parenting_coaching", "pet_training", "gardening_education", "diy_crafts", "survival_prepping", "baking_pastry", "wine_sommelier", "beer_brewing", "mixology_bartending", "woodworking", "pottery_ceramics", "knitting_crocheting", "jewelry_making", "aquarium_fishkeeping", "bird_watching", "astronomy_education", "magic_illusion", "car_restoration", "motorcycle_riding", "sailing_boating", "scuba_diving", "rock_climbing", "skiing_snowboarding", "surfing_education", "homesteading", "tiny_house_living", "van_life", "fashion_styling", "floral_design", "travel_planning_service", "collectibles_coaching", "car_enthusiast_community", "sneakerhead_community", "watch_collector_community", "wine_enthusiast_community", "cigar_community", "cooking_community", "gardening_community", "fishing_community", "hunting_community", "diy_maker_community", "golf_community", "collectibles_community", "sweepstakes_raffles", "event_ticket_community", "esports_coaching", "game_specific_coaching", "gaming_community", "game_account_selling", "unauthorized_ingame_currency", "legal_education", "music_theory", "music_business", "acting_coaching", "dance_instruction", "voice_acting", "english_coaching", "spanish_coaching", "mandarin_coaching", "french_coaching", "german_coaching", "japanese_coaching", "korean_coaching", "arabic_coaching", "sign_language_education", "accent_reduction", "business_english", "ai_chatbot_agency", "ai_automation_agency", "ai_consulting", "workflow_automation_agency", "data_analytics_agency", "ai_voice_agent_agency", "ai_content_agency", "machine_learning_agency", "computer_vision_agency", "tech_recruiting_agency", "executive_recruiting", "staffing_agency", "remote_staffing", "healthcare_recruiting", "va_placement_agency", "sales_recruiting", "creative_recruiting", "finance_recruiting", "legal_recruiting", "construction_staffing", "hospitality_staffing", "customer_support_outsourcing", "live_chat_agency", "technical_support_agency", "call_center_agency", "multilingual_support_agency", "community_management_agency", "management_consulting", "financial_consulting", "hr_consulting", "operations_consulting", "it_consulting", "sustainability_consulting", "legal_consulting", "compliance_consulting", "supply_chain_consulting", "change_management_consulting", "digital_transformation_consulting", "healthcare_consulting", "real_estate_consulting", "franchise_consulting", "export_trade_consulting", "nonprofit_consulting", "education_consulting", "cannabis_consulting", "restaurant_consulting", "m_and_a_consulting", "pricing_strategy_consulting", "brand_strategy_consulting", "saas_marketing_consulting", "done_for_you_services", "prop_firm_passing_service", "trading_account_management", "done_for_you_trading", "accounting_bookkeeping", "tax_preparation", "legal_services", "notary_services", "insurance_brokerage", "financial_planning_service", "real_estate_services", "property_management", "mortgage_brokerage", "immigration_services", "patent_trademark_services", "business_formation_services", "shell_company_formation", "payroll_services", "audit_services", "forensic_accounting", "actuarial_services", "appraisal_services", "mediation_arbitration", "bail_bond_services", "crowdfunding_platform", "essay_mill_paper_mill", "government_service_facilitation", "immigration_services_unlicensed", "licensed_legal_services", "personalized_tax_services", "private_investigation", "repossession_services", "unlicensed_legal_services", "record_label", "book_publishing_house", "news_media_outlet", "radio_broadcasting", "tv_production_company", "film_studio", "magazine_publisher", "music_licensing_agency", "talent_management_agency", "advertising_network", "ad_tech_platform", "cleaning_service", "landscaping_service", "plumbing_service", "electrical_service", "hvac_service", "roofing_service", "painting_service", "moving_service", "handyman_service", "pest_control", "pool_service", "solar_installation", "home_renovation", "pressure_washing", "junk_removal", "garage_door_service", "fencing_service", "concrete_masonry", "tree_service", "window_cleaning", "gutter_service", "flooring_service", "cabinet_countertop", "home_inspection", "septic_service", "waterproofing_service", "insulation_service", "chimney_service", "locksmith_service", "glass_window_service", "epoxy_coating", "private_security_guard_service", "armored_car_transport", "executive_protection_bodyguard", "event_security_service", "alarm_system_installation", "cctv_installation", "private_investigation_agency", "background_check_provider", "locksmith_commercial", "bounty_hunter_bail_enforcement", "personal_styling", "personal_chef", "personal_assistant_service", "tutoring_service", "pet_services", "wedding_planning", "concierge_service", "personal_training_service", "nanny_service", "elder_care_service", "errand_service", "life_organization", "relocation_service", "adult_dating_services", "escort_services", "hotel_accommodation_bookings", "mail_order_spouse", "psychic_fortune_telling", "timeshare_sales", "freight_brokerage", "courier_service", "warehousing_service", "last_mile_delivery", "auto_transport", "international_shipping", "cold_chain_logistics", "commercial_airline_tickets", "cruise_line_bookings", "contract_manufacturing", "cnc_machining_service", "3d_printing_service_commercial", "plastic_injection_molding", "metal_fabrication", "pcba_assembly", "chemical_manufacturing", "textile_manufacturing", "food_processing_facility", "packaging_manufacturing", "industrial_automation_integrator", "mining_and_extraction", "oil_and_gas_services", "renewable_energy_generation", "waste_management_recycling", "hazardous_waste_disposal", "aerospace_defense_contracting", "personal_training_studio", "nutrition_consulting", "mental_health_counseling", "physical_therapy_service", "occupational_therapy_service", "speech_therapy_service", "chiropractic_service", "acupuncture_service", "massage_therapy_service", "midwifery_doula", "lactation_consulting", "dietitian_service", "addiction_recovery_services", "dtc_lab_testing", "iv_therapy_infusion", "medspa_aesthetic_services", "prescription_delivery_services", "registered_dietitian_services", "unlicensed_therapy_counseling", "streetwear", "athleisure", "luxury_fashion", "kids_clothing", "custom_apparel", "workwear", "swimwear", "lingerie_intimates", "vintage_clothing", "plus_size_fashion", "maternity_clothing", "sleepwear_loungewear", "denim_brand", "outerwear_jackets", "socks_hosiery", "costumes_cosplay", "scrubs_medical_apparel", "dance_performance_wear", "hunting_camo_apparel", "casual_everyday_clothing", "protein_supplements", "vitamins_minerals", "pre_workout", "nootropics", "herbal_supplements", "weight_management_supplements", "gut_health", "cbd_products", "mushroom_supplements", "collagen_supplements", "testosterone_boosters", "sleep_supplements", "immune_support", "joint_bone_health", "greens_powder", "creatine_supplements", "electrolyte_hydration", "prenatal_supplements", "kids_supplements", "pet_supplements", "ayurvedic_supplements", "keto_supplements", "cannabis_thc_products", "cbd_hemp_products_compliant", "delta8_thc_products", "dietary_supplements", "drug_precursor_chemicals", "illegal_drugs", "kratom_kava_products", "medical_treatment_claims_product", "nutraceutical_products", "otc_medication_sales", "performance_enhancing_drugs", "research_chemicals_dangerous", "research_peptides", "sexual_enhancement_products", "tobacco_products", "unlicensed_rx_sales", "skincare", "haircare", "cosmetics_makeup", "mens_grooming", "fragrance", "oral_care", "sunscreen_spf", "hair_growth_products", "body_care", "deodorant", "lip_care", "acne_treatment", "men_skincare", "baby_skincare", "tattoo_aftercare", "intimate_care", "home_gym_equipment", "yoga_equipment", "combat_sports_gear", "outdoor_fitness_gear", "wearable_fitness", "recovery_equipment", "weightlifting_equipment", "cardio_equipment", "gymnastics_equipment", "swimming_gear", "jump_rope_equipment", "grip_strength_tools", "sauna_cold_plunge", "posture_correctors", "jewelry", "sunglasses_eyewear", "bags_wallets", "hats_headwear", "phone_accessories", "travel_accessories", "scarves_wraps", "belts", "hair_accessories", "tech_accessories", "keychains_charms", "custom_engraved_accessories", "cannabis_accessories_non_drug", "drug_paraphernalia", "high_value_goods_over_500", "precious_metals_stones", "replica_counterfeit_goods", "home_decor", "candles_scents", "kitchenware", "bedding_linens", "smart_home", "cleaning_products", "outdoor_furniture", "organization_storage", "wall_art_prints", "rugs_carpets", "lighting_fixtures", "planters_garden_decor", "bathroom_accessories", "luxury_home_goods", "seasonal_holiday_decor", "pet_home_products", "home_fragrance_diffusers", "hazardous_chemicals_b2c", "pre_orders_delayed_delivery", "audio_equipment", "camera_equipment", "gaming_hardware", "drones_robotics", "ev_accessories", "charging_power", "smart_wearables", "home_security_devices", "3d_printers", "projectors_displays", "streaming_devices", "vr_headsets", "e_readers", "portable_tech", "hardware_wallets", "regulated_medical_devices", "signal_jamming_devices", "spy_cameras_hidden_recording", "specialty_coffee_tea", "health_food", "snacks_treats", "sauces_condiments", "alcohol_spirits", "meal_kits", "baked_goods", "beverages", "pet_food_treats", "protein_bars_snacks", "jerky_meat_snacks", "chocolate_confections", "honey_sweeteners", "olive_oil_vinegar", "hot_sauce", "dried_fruit_nuts", "baby_food", "plant_based_food", "gluten_free_food", "keto_food_products", "subscription_food_box", "kombucha_fermented", "alcohol_sales", "baby_products", "kids_toys", "kids_educational", "baby_clothing_accessories", "nursery_decor", "kids_outdoor_play", "kids_books", "baby_safety_products", "kids_arts_crafts", "camping_hiking", "fishing_gear", "hunting_gear", "cycling_gear", "water_sports_gear", "golf_equipment", "snow_sports_gear", "climbing_gear", "archery_equipment", "skateboarding_gear", "pickleball_equipment", "tennis_equipment", "equestrian_gear", "tactical_gear", "overlanding_gear", "explosives_fireworks", "firearms_sales", "self_defense_products", "weapon_components", "craft_kits", "sewing_textiles", "stationery", "scrapbooking_supplies", "beading_jewelry_supplies", "pottery_supplies", "printmaking_supplies", "car_accessories", "detailing_products", "motorcycle_gear", "truck_accessories", "off_road_parts", "car_audio_electronics", "performance_parts", "car_care_products", "ev_charging_accessories", "auto_repair_service", "auto_body_shop", "car_dealership", "car_wash", "tire_shop", "oil_change_shop", "auto_parts_store", "motorcycle_shop", "ev_charging_station", "transmission_shop", "muffler_exhaust_shop", "auto_glass_shop", "auto_upholstery_shop", "car_audio_shop", "smog_emissions_shop", "truck_repair_shop", "rv_repair_shop", "boat_repair_shop", "used_car_lot", "auto_auction", "dog_products", "cat_products", "aquarium_supplies", "bird_supplies", "reptile_supplies", "horse_supplies", "pet_apparel", "pet_tech", "pet_grooming_products", "hand_tools", "power_tools_and_accessories", "hardware_and_fasteners", "workshop_equipment_and_storage", "safety_and_work_gear", "painting_and_building_supplies", "office_supplies", "desk_accessories", "printing_supplies", "shipping_packaging", "reusable_products", "solar_powered_products", "christian_books_bibles", "christian_apparel", "christian_jewelry", "christian_home_decor", "jewish_judaica", "jewish_books_torah", "jewish_apparel", "islamic_books_quran", "islamic_apparel", "islamic_prayer_goods", "hindu_puja_supplies", "hindu_books_texts", "buddhist_meditation_goods", "buddhist_books_texts", "sikh_religious_goods", "other_religious_products", "handmade_goods_marketplace", "vintage_resale_marketplace", "electronics_marketplace", "auto_parts_marketplace", "luxury_goods_marketplace", "collectibles_marketplace", "wholesale_marketplace", "local_goods_marketplace", "sneaker_marketplace", "book_marketplace", "furniture_marketplace", "musical_instrument_marketplace", "art_marketplace", "ticket_marketplace", "industrial_equipment_marketplace", "craft_supply_marketplace", "baby_kids_marketplace", "outdoor_gear_marketplace", "pet_marketplace", "sustainable_goods_marketplace", "cultural_artifacts_looted", "dropshipping_operations", "endangered_animal_products", "human_body_parts_tissue", "nft_marketplace", "penny_auction", "primary_event_ticketing", "freelancer_marketplace", "home_services_marketplace", "tutoring_marketplace", "legal_services_marketplace", "healthcare_marketplace", "wedding_services_marketplace", "creative_and_content_creation_marketplace", "beauty_services_marketplace", "fitness_trainer_marketplace", "pet_services_marketplace", "childcare_marketplace", "elder_care_marketplace", "translation_marketplace", "coaching_marketplace", "therapy_marketplace", "photography_marketplace", "dj_entertainment_marketplace", "auto_services_marketplace", "freelance_marketplace_operator", "equipment_rental_marketplace", "vehicle_rental_marketplace", "space_rental_marketplace", "vacation_rental_marketplace", "clothing_rental_marketplace", "camera_gear_rental", "rv_camper_rental", "boat_rental_marketplace", "storage_rental_marketplace", "office_coworking_rental", "parking_rental_marketplace", "restaurant_marketplace", "grocery_marketplace", "catering_marketplace", "homemade_food_marketplace", "meal_prep_marketplace", "bakery_marketplace", "farm_produce_marketplace", "chef_booking_marketplace", "course_marketplace", "template_marketplace", "stock_media_marketplace", "music_beats_marketplace", "ebook_marketplace", "plugin_theme_marketplace", "3d_model_marketplace", "prompt_marketplace", "code_snippet_marketplace", "affiliate_marketing_platform", "game_cheats_hacks", "weapon_blueprint_distribution", "saas_marketplace", "agency_marketplace", "manufacturing_marketplace", "logistics_marketplace", "commercial_real_estate_marketplace", "business_for_sale_marketplace", "food_delivery", "grocery_delivery", "package_delivery", "moving_labor", "alcohol_delivery", "pharmacy_delivery", "flower_delivery_gig", "furniture_delivery_gig", "catering_delivery", "rideshare", "chauffeur_service", "bike_scooter_rental", "boat_charter_gig", "moving_truck_rental_gig", "assembly_installation", "waiting_line_service", "personal_shopping", "grocery_shopping_gig", "gift_wrapping_gig", "notary_gig", "laundry_gig", "car_wash_gig", "cleaning_gig", "lawn_care_gig", "handyman_gig", "pet_care_gig", "childcare_gig", "elder_care_gig", "painting_gig", "snow_removal_gig", "pool_cleaning_gig", "organizing_gig", "pressure_washing_gig", "junk_removal_gig", "consulting_gig", "accounting_gig", "legal_gig", "healthcare_gig", "teaching_gig", "translation_gig", "data_entry_gig", "research_gig", "virtual_assistant_gig", "sales_gig", "recruiting_gig", "mystery_shopping", "focus_group_gig", "product_testing_gig", "drone_pilot_gig", "fitness_instruction_gig", "tour_guide_gig", "dating_community", "personal_development_community", "spirituality_community", "parenting_community", "travel_community", "networking_community", "faith_community", "mens_community", "womens_community", "expat_community", "adult_community_nsfw", "hate_violence_communities", "personal_fundraising", "political_fundraising", "political_organizations", "pornographic_content", "registered_501c3", "religious_organization", "unregistered_charities", "ai_outreach_tool", "ai_chatbot_software", "ai_writing_tool", "ai_image_generator", "ai_video_tool", "ai_voice_tool", "ai_data_analysis", "ai_code_assistant", "ai_meeting_assistant", "workflow_automation_software", "ai_sales_tool", "ai_customer_support", "ai_recruiting_tool", "ai_translation_tool", "ai_music_tool", "ai_presentation_tool", "ai_research_tool", "ai_seo_tool", "ai_social_media_tool", "ai_phone_agent", "ai_legal_tool", "ai_healthcare_tool", "llm_api_platform", "ai_agent_platform", "generative_ai_platform", "celebrity_impersonation", "deepfake_service", "ai_nsfw_content_generator", "ecommerce_platform", "product_research_tool", "price_tracker", "shipping_software", "print_on_demand_software", "marketplace_seller_tool", "resale_arbitrage_tool", "reseller_management_tool", "product_review_software", "returns_management", "product_feed_management", "checkout_optimization", "wholesale_ordering", "project_management_software", "team_communication", "video_conferencing", "document_collaboration", "time_tracking_software", "scheduling_software", "hr_software", "knowledge_base_software", "form_survey_builder", "note_taking_app", "task_management", "contract_management", "expense_management", "okr_goal_tracking", "employee_engagement", "onboarding_software", "applicant_tracking", "asset_management", "facility_management", "visitor_management", "community_platform", "event_management_software", "webinar_software", "school_management", "newsletter_platform", "podcast_hosting", "forum_software", "virtual_classroom", "restaurant_pos", "salon_software", "gym_management_software", "auto_shop_software", "legal_practice_software", "church_management", "nonprofit_software", "logistics_software", "agriculture_software", "field_service_software", "marina_management", "hotel_pms", "childcare_management", "cleaning_business_software", "roofing_software", "landscaping_software", "pest_control_software", "tattoo_studio_software", "cannabis_software", "password_manager", "cybersecurity_software", "identity_verification", "backup_recovery", "endpoint_protection", "email_security", "access_management", "compliance_software", "data_privacy_tool", "vpn_services", "people_search_tool", "game_mod_tool", "streaming_tool", "game_server_hosting", "music_software", "video_editing_software", "photo_editing_software", "animation_software", "audio_editing_software", "screen_recording_software", "sports_betting_tool", "fantasy_sports_paid_entry", "iptv_pirated_streaming", "loot_boxes_gacha", "skill_contests_free_entry", "skill_contests_paid_entry", "only_fans_management_software", "pornography_platform", "business_phone_system", "customer_messaging", "digital_key_reselling", "streaming_account_reselling", "subscription_account_sharing", "account_generation_tool", "primary_care_telehealth", "urgent_care_telehealth", "pediatric_telehealth", "geriatric_telehealth", "family_medicine_telehealth", "internal_medicine_telehealth", "preventive_care_telehealth", "licensed_online_pharmacy", "telemedicine_practitioner_services", "dermatology_telehealth", "acne_telehealth", "psoriasis_eczema_telehealth", "skin_cancer_screening_tele", "cosmetic_dermatology_tele", "therapy_telehealth", "psychiatry_telehealth", "addiction_telehealth", "couples_therapy_telehealth", "child_psychology_telehealth", "eating_disorder_telehealth", "ptsd_trauma_telehealth", "adhd_telehealth", "anxiety_depression_telehealth", "ocd_telehealth", "grief_counseling_telehealth", "anger_management_telehealth", "family_therapy_telehealth", "group_therapy_telehealth", "licensed_psychedelic_therapy", "womens_health_telehealth", "mens_health_telehealth", "sexual_health_telehealth", "fertility_telehealth", "hormone_therapy_telehealth", "menopause_telehealth", "prenatal_telehealth", "postpartum_telehealth", "erectile_dysfunction_tele", "hair_loss_telehealth", "birth_control_telehealth", "sti_testing_telehealth", "dental_telehealth", "orthodontics_telehealth", "optometry_telehealth", "oral_surgery_consultation", "vision_therapy_telehealth", "cardiology_telehealth", "endocrinology_telehealth", "neurology_telehealth", "orthopedic_telehealth", "allergy_telehealth", "ent_telehealth", "rheumatology_telehealth", "gastroenterology_telehealth", "infectious_disease_telehealth", "pulmonology_telehealth", "nephrology_telehealth", "oncology_telehealth", "hematology_telehealth", "urology_telehealth", "weight_management_telehealth", "glp1_weight_loss_tele", "diabetes_management_tele", "metabolic_health_tele", "bariatric_telehealth", "physical_therapy_telehealth", "occupational_therapy_tele", "speech_therapy_telehealth", "pain_management_telehealth", "cardiac_rehab_telehealth", "pelvic_floor_telehealth", "vestibular_telehealth", "sleep_medicine_telehealth", "chronic_disease_management", "chronic_pain_telehealth", "migraine_telehealth", "asthma_copd_telehealth", "nutrition_telehealth", "naturopathic_telehealth", "functional_medicine_telehealth", "acupuncture_telehealth", "health_coaching_telehealth", "integrative_medicine_tele", "ayurvedic_telehealth", "genetic_counseling_telehealth", "pharmacogenomics_tele", "rare_disease_telehealth", "second_opinion_telehealth", "vet_telehealth", "pet_behavior_telehealth", "exotic_pet_telehealth", "equine_telehealth", "veterinary_services", "class_action_settlement", "mastermind_event", "webinar_event", "virtual_summit", "bootcamp_event", "workshop_seminar", "hackathon", "corporate_training_event", "training_certification_event", "convention_expo", "conference_summit", "industry_awards_event", "product_launch_event", "investor_demo_day", "panel_discussion_event", "pitch_competition", "meetup_event", "dinner_event", "alumni_event", "community_gathering", "singles_event", "professional_happy_hour", "women_networking_event", "founders_dinner", "industry_mixer", "concert_event", "comedy_show", "theater_performance", "film_screening", "music_festival", "cultural_festival", "fashion_show", "drag_show", "magic_show", "dance_performance", "poetry_spoken_word", "art_exhibition", "party_event", "trivia_night", "wine_tasting_event", "beer_festival", "car_show", "food_festival", "fitness_challenge_event", "marathon_race", "tournament_event", "fight_event", "yoga_retreat_event", "outdoor_adventure_event", "esports_tournament", "obstacle_course_race", "cycling_event", "swim_meet", "golf_tournament", "pickleball_tournament", "crossfit_competition", "martial_arts_tournament", "surfing_competition", "wellness_retreat", "spiritual_retreat", "couples_retreat", "plant_medicine_retreat", "luxury_experience_event", "detox_retreat", "silent_retreat", "creative_retreat", "leadership_retreat", "mens_retreat", "womens_retreat", "digital_detox_retreat", "fundraiser_event", "awareness_event", "volunteer_event", "charity_auction", "benefit_concert", "charity_run_walk", "environmental_cleanup", "family_festival", "kids_event", "holiday_event", "farmers_market_event", "block_party", "graduation_ceremony", "memorial_event", "stock_market_newsletter", "crypto_newsletter", "personal_finance_newsletter", "real_estate_newsletter", "fintech_newsletter", "venture_capital_newsletter", "options_trading_newsletter", "forex_newsletter", "macro_economics_newsletter", "alternative_investing_newsletter", "tax_strategy_newsletter", "ai_newsletter", "tech_industry_newsletter", "cybersecurity_newsletter", "developer_newsletter", "product_newsletter", "devops_newsletter", "open_source_newsletter", "robotics_newsletter", "climate_tech_newsletter", "travel_newsletter", "fashion_newsletter", "parenting_newsletter", "sports_newsletter", "gaming_newsletter", "music_entertainment_newsletter", "book_reading_newsletter", "dating_relationships_newsletter", "home_design_newsletter", "pet_newsletter", "wine_spirits_newsletter", "automotive_newsletter", "political_newsletter", "geopolitics_newsletter", "media_journalism_newsletter", "defense_security_newsletter", "legal_policy_newsletter", "design_newsletter", "education_newsletter", "science_newsletter", "philosophy_newsletter", "sustainability_newsletter", "architecture_newsletter", "history_newsletter", "psychology_newsletter", "career_newsletter", "spirituality_newsletter", "self_improvement_newsletter", "productivity_newsletter", "faith_newsletter", "gym_facility", "crossfit_box", "yoga_studio", "pilates_studio", "martial_arts_gym", "boxing_gym", "climbing_gym", "dance_studio", "swimming_pool", "sports_facility", "golf_course", "bowling_alley", "skating_rink", "trampoline_park", "tennis_club", "pickleball_facility", "gymnastics_center", "spin_studio", "barre_studio", "personal_training_studio_bm", "recovery_studio", "indoor_soccer", "batting_cage", "shooting_range", "archery_range", "equestrian_center", "fine_dining", "fast_casual_restaurant", "steakhouse", "seafood_restaurant", "pizza_shop", "sushi_restaurant", "deli_sandwich_shop", "bbq_restaurant", "mexican_restaurant", "italian_restaurant", "chinese_restaurant", "indian_restaurant", "thai_restaurant", "korean_restaurant", "mediterranean_restaurant", "vegan_vegetarian_restaurant", "brunch_restaurant", "ramen_noodle_shop", "poke_bowl_shop", "ethnic_restaurant", "coffee_shop_cafe", "bakery", "juice_smoothie_bar", "ice_cream_shop", "donut_shop", "bubble_tea_shop", "food_truck", "fast_food", "ghost_kitchen", "food_hall_vendor", "catering_kitchen", "butcher_shop", "cheese_shop", "farmers_market_stall", "bar_lounge", "brewery_taproom", "winery_tasting", "wine_bar", "cocktail_bar", "sports_bar", "hookah_lounge", "distillery", "commercial_farming", "livestock_ranching", "hydroponic_vertical_farming", "forestry_logging", "aquaculture_fisheries", "vineyard_winery_production", "cannabis_cultivation", "hemp_farming", "grain_production", "agricultural_cooperative", "fertilizer_pesticide_sales", "farm_equipment_sales", "boutique_store", "clothing_store", "shoe_store", "jewelry_store", "electronics_store", "bookstore", "pet_store", "toy_store", "sporting_goods_store", "thrift_store", "smoke_shop", "cannabis_dispensary", "convenience_store", "grocery_store", "liquor_store", "florist", "gift_shop", "furniture_store", "home_improvement_store", "art_gallery_retail", "music_instrument_store", "outdoor_recreation_store", "phone_repair_store", "watch_store", "bridal_shop", "maternity_store", "kids_store", "sneaker_store", "vintage_store", "comic_book_store", "record_store", "craft_supply_store", "fabric_store", "health_food_store", "vitamin_supplement_store", "optical_store", "mattress_store", "appliance_store", "kitchen_bath_store", "tile_flooring_store", "paint_store", "garden_center", "gun_store", "pawn_shop", "dollar_store", "hair_salon", "nail_salon", "day_spa", "med_spa", "massage_studio", "tattoo_parlor", "tanning_salon", "beauty_supply_store", "lash_brow_studio", "waxing_studio", "sauna_bathhouse", "cryotherapy_studio", "float_sensory_studio", "iv_therapy_lounge", "teeth_whitening_studio", "microblading_studio", "spray_tan_studio", "blowout_bar", "mens_barbershop", "kids_salon", "medical_office", "dental_office", "chiropractic_office", "physical_therapy_clinic", "optometry_office", "dermatology_clinic", "urgent_care_clinic", "pharmacy", "veterinary_clinic", "mental_health_clinic", "fertility_clinic", "acupuncture_clinic", "hearing_aid_center", "orthopedic_clinic", "pediatric_clinic", "cosmetic_surgery_center", "allergy_clinic", "pain_management_clinic", "dialysis_center", "imaging_center", "lab_testing_center", "sleep_clinic", "weight_loss_clinic", "hormone_therapy_clinic", "addiction_treatment_center", "rehabilitation_center", "occupational_therapy_clinic", "speech_therapy_clinic", "wound_care_center", "funeral_home_mortuary", "crematory_service", "cemetery_memorial_park", "casket_urn_retailer", "pet_cremation_service", "biohazard_cleanup", "estate_liquidation", "hotel", "motel", "boutique_hotel", "bed_and_breakfast", "hostel", "resort", "campground_rv", "vacation_rental_property", "extended_stay", "glamping_site", "cabin_rental", "eco_lodge", "retreat_center", "tutoring_center", "daycare_center", "preschool", "learning_center", "music_school", "art_school", "driving_school", "language_school", "trade_school", "coding_bootcamp_location", "montessori_school", "after_school_program", "swim_school", "cooking_school", "test_prep_center", "special_needs_center", "adult_education_center", "flight_school", "cosmetology_school", "movie_theater", "escape_room", "arcade", "mini_golf", "laser_tag", "go_kart", "amusement_park", "museum", "zoo_aquarium", "theater_venue", "nightclub", "karaoke_bar", "comedy_club", "live_music_venue", "axe_throwing", "virtual_reality_arcade", "board_game_cafe", "cat_cafe", "haunted_house", "water_park", "indoor_playground", "concert_venue", "drive_in_theater", "billiards_hall", "dart_bar", "indoor_skydiving", "law_office", "real_estate_office", "insurance_office", "accounting_office", "bank_credit_union", "printing_shop", "shipping_center", "dry_cleaner", "laundromat", "storage_facility", "coworking_space", "check_cashing", "title_company", "travel_agency_storefront", "staffing_office", "financial_advisor_office", "immigration_office", "bail_bonds_office", "pet_grooming", "dog_daycare", "pet_boarding", "dog_training_facility", "pet_spa", "aquatic_pet_store", "pet_bakery", "pet_photography_studio", "plumbing_showroom", "hvac_showroom", "solar_showroom", "kitchen_design_showroom", "bath_design_showroom", "window_door_showroom", "pool_spa_showroom", "fireplace_showroom", "countertop_showroom", "nonprofit_organization", "charity_foundation", "political_campaign", "community_organization", "environmental_nonprofit", "education_nonprofit", "health_nonprofit", "animal_welfare_nonprofit", "arts_culture_nonprofit", "social_justice_nonprofit", "veterans_nonprofit", "youth_nonprofit", "disaster_relief_nonprofit", "food_bank", "housing_nonprofit", "government_agency", "public_utility", "public_library", "public_school", "municipal_service", "military_installation", "embassy_consulate", "niche_service", "niche_product", "hybrid_business", "other_general", "holding_company", "family_office", "cooperative", "social_enterprise", "incubator_accelerator", "coworking_community", "media_company", "research_lab", null ], "example": "other", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "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" ] }, "other_business_description": { "description": "The description of the business type when business_type is other.", "example": "Mobile auto detailing", "type": [ "string", "null" ] }, "other_industry_description": { "description": "The description of the industry type when industry_type is other.", "example": "Automotive services", "type": [ "string", "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" }, "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" }, "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" }, "three_ds_level": { "description": "Account-level 3D Secure behavior. Set `mandate_challenge` to require cardholder verification on supported card payments, or `null` to use the standard checkout flow.", "enum": [ "mandate_challenge" ], "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" } }, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst account = await client.accounts.update('id');\n\nconsole.log(account.id);" } ] } }, "/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. Defaults to an LLC; set `entity_type` to `c_corp` to form a C-Corp, which additionally requires `share_structure` and officer `roles` on every founder. On submission, 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_type": "brick_and_mortar", "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" } ], "industry_group": "automotive", "industry_type": "car_wash", "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_type": { "description": "High-level business category, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary).", "example": "brick_and_mortar", "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" }, "industry_group": { "description": "Industry group, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary).", "example": "automotive", "type": "string" }, "industry_type": { "description": "Specific industry vertical, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary).", "example": "car_wash", "type": "string" }, "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", "business_type", "industry_group", "industry_type", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.accounts.formCompany('id', {\n business_name: 'Shine Time Auto Detailing',\n business_type: 'brick_and_mortar',\n formation_state: 'TX',\n founders: [\n {\n address: {\n city: 'Austin',\n country: 'US',\n line1: '907 Ridgemont Dr',\n postal_code: '78704',\n state: 'TX',\n },\n email: 'marcus@shinetime.example',\n first_name: 'Marcus',\n is_primary: true,\n last_name: 'Webb',\n phone: '+15125550142',\n },\n ],\n industry_group: 'automotive',\n industry_type: 'car_wash',\n});\n\nconsole.log(response.checkout_session_id);" } ] } }, "/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" ] } }, "/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.", "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" }, "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" }, "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" ] } ], "summary": "Transfer Account Ownership", "tags": [ "Accounts" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.accounts.transferOwnership('id', {\n identifier: 'marcus@shinetime.example',\n});\n\nconsole.log(response.success);" } ] } }, "/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.", "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 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": "The number of campaigns to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of campaigns to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const adCampaign of client.adCampaigns.list()) {\n console.log(adCampaign.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an ad campaign for an account.", "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 the ad account's currency. Required when budget_optimization is `ad_campaign`; omit when each ad group sets its own budget.", "example": 25, "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" }, "desired_cost_per_result": { "description": "Cost per result to aim for (`average_target`) or never exceed (`maximum_target`). Only for campaigns that own the budget.", "example": 4.5, "type": "number" }, "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": [ "meta" ], "example": "meta", "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adCampaign = await client.adCampaigns.create({\n objective: 'leads',\n platform: 'meta',\n title: 'Now hiring mobile detailers — Austin',\n});\n\nconsole.log(adCampaign.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adCampaign = await client.adCampaigns.delete('id');\n\nconsole.log(adCampaign.id);" } ] }, "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adCampaign = await client.adCampaigns.retrieve('id');\n\nconsole.log(adCampaign.id);" } ] }, "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 editable fields (title, budget, schedule, bid strategy, special ad categories, and, before launch, budget type and budget optimization), and launches a draft campaign by setting status to active. Objective and desired cost per result are fixed at creation and cannot be changed.", "operationId": "updateAdCampaign", "parameters": [], "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 the account's currency. Interpreted as daily or lifetime per the campaign's budget type, including a budget_type sent in the same request.", "example": 40, "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" }, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adCampaign = await client.adCampaigns.update('id');\n\nconsole.log(adCampaign.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.adCampaigns.duplicate('id');\n\nconsole.log(response.data);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Pause" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adCampaign = await client.adCampaigns.pause('id');\n\nconsole.log(adCampaign.id);" } ] } }, "/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": { "description": "Retries billing for an ad campaign whose payment previously failed.", "operationId": "retryAdCampaignPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdCampaign" } } }, "description": "payment retried" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "campaign is not in payment_failed status" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Retry a Failed Ad Campaign Payment", "tags": [ "Ad Campaigns" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adCampaign = await client.adCampaigns.retryPayment('id');\n\nconsole.log(adCampaign.id);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Unpause" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adCampaign = await client.adCampaigns.unpause('id');\n\nconsole.log(adCampaign.id);" } ] } }, "/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.", "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": "The number of ad groups to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of ad groups to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const adGroup of client.adGroups.list()) {\n console.log(adGroup.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates an ad group (ad set) in a campaign.", "operationId": "createAdGroup", "parameters": [ { "$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 the ad account's currency. Omit when the budget is set on the campaign instead.", "example": 40, "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" }, "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, "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 on campaigns with the `awareness` objective.", "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" }, "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, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adGroup = await client.adGroups.create({ ad_campaign_id: 'adcamp_xxxxxxxxxxxxxx' });\n\nconsole.log(adGroup.id);" } ] } }, "/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 — `regions`, `demographics`, `detailed_targeting`, `audiences`, `languages`, and `devices` — 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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst reachEstimate = await client.adGroups.estimateReach({ platform: 'meta' });\n\nconsole.log(reachEstimate.users_lower_bound);" } ] } }, "/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. A blank `query` browses the small fixed lists (behaviors, browse demographic categories, languages); interests, work employers, job titles, schools, majors, and locations need a search term.", "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 fixed lists; 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" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.adGroups.searchTargetingOptions({ platform: 'meta' });\n\nconsole.log(response.data);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/ad_groups/{id}": { "delete": { "description": "Deletes an ad group.", "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" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adGroup = await client.adGroups.delete('id');\n\nconsole.log(adGroup.id);" } ] }, "get": { "description": "Retrieves a single ad group.", "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adGroup = await client.adGroups.retrieve('id');\n\nconsole.log(adGroup.id);" } ] }, "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": [], "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 the ad account's currency. Omit when the budget is set on the campaign instead.", "example": 40, "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" }, "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, "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 on campaigns with the `awareness` objective.", "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" }, "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, "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" } }, "security": [ { "bearerAuth": [ "ad_campaign:update" ] } ], "summary": "Update an Ad Group", "tags": [ "Ad Groups" ], "x-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adGroup = await client.adGroups.update('id');\n\nconsole.log(adGroup.id);" } ] } }, "/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": "Creates copies of the ad group in `duplicating` status and returns them — into its own campaign, or into target_ad_campaign_id (which must belong to the same account and be compatible with the ad group's targeting and goals); each copy transitions to its final status (matching the source's active/paused state) once duplication completes. Poll each returned ad group until it leaves `duplicating` — a copy that 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. 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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.adGroups.duplicate('id');\n\nconsole.log(response.data);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Pause" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adGroup = await client.adGroups.pause('id');\n\nconsole.log(adGroup.id);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Unpause" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst adGroup = await client.adGroups.unpause('id');\n\nconsole.log(adGroup.id);" } ] } }, "/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.", "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": "The number of ads to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of ads to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const ad of client.ads.list()) {\n console.log(ad.id);\n}" } ] }, "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/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, "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", "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", "send_updates", "shop_now", "sign_up", "subscribe", "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" } }, "type": "object" }, "type": "array" }, "descriptions": { "description": "The description variants shown on the ad.", "items": { "example": "Two-stage paint correction included", "type": "string" }, "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" }, "headlines": { "description": "The headline variants shown on the ad.", "items": { "example": "Showroom shine, guaranteed", "type": "string" }, "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; url sets the follow-up website button.", "properties": { "button_text": { "example": "See our work", "type": "string" }, "description": { "example": "We book coatings two days out, so pick a slot when we ring.", "type": "string" }, "headline": { "example": "Thanks — we will call you today", "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 variants shown in the ad body.", "items": { "example": "Three-year ceramic coating, booked online in under a minute.", "type": "string" }, "type": "array" }, "social_accounts": { "description": "The social accounts the ad runs under — a connected Facebook page and, optionally, an Instagram profile.", "items": { "properties": { "id": { "description": "Social account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "title": { "description": "The display name of the ad.", "example": "Interior deep clean — DM us", "type": "string" }, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ad = await client.ads.create();\n\nconsole.log(ad.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ad = await client.ads.delete('id');\n\nconsole.log(ad.id);" } ] }, "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ad = await client.ads.retrieve('id');\n\nconsole.log(ad.id);" } ] }, "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": [], "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", "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", "send_updates", "shop_now", "sign_up", "subscribe", "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" } }, "type": "object" }, "type": "array" }, "descriptions": { "description": "The description variants shown on the ad.", "items": { "example": "Paint correction included", "type": "string" }, "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" }, "headlines": { "description": "The headline variants shown on the ad.", "items": { "example": "Austin's mobile detailers", "type": "string" }, "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; url sets the follow-up website button.", "properties": { "button_text": { "example": "See our work", "type": "string" }, "description": { "example": "We book coatings two days out, so pick a slot when we ring.", "type": "string" }, "headline": { "example": "Thanks — we will call you today", "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 variants shown in the ad body.", "items": { "example": "Book a two-day ceramic coating and keep the shine for three years.", "type": "string" }, "type": "array" }, "social_accounts": { "description": "The social accounts the ad runs under — a connected Facebook page and, optionally, an Instagram profile.", "items": { "properties": { "id": { "description": "Social account ID, prefixed `sacc_`.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "type": "object" }, "type": "array" }, "title": { "description": "The display name of the ad.", "example": "Ceramic coating — spring hook v2", "type": "string" }, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ad = await client.ads.update('id');\n\nconsole.log(ad.id);" } ] } }, "/ads/{id}/duplicate": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ad ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Copies the ad into its own ad group, or into target_ad_group_id (which must belong to the same account and be compatible with the ad). Copies keep the source ad's active/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. 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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.ads.duplicate('id');\n\nconsole.log(response.data);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Pause" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ad = await client.ads.pause('id');\n\nconsole.log(ad.id);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Unpause" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst ad = await client.ads.unpause('id');\n\nconsole.log(ad.id);" } ] } }, "/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": "The number of API keys to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns API keys after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of API keys to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns API keys before this position.", "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": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const apiKey of client.apiKeys.list({\n resource_id: 'resource_id',\n resource_type: 'account',\n})) {\n console.log(apiKey.id);\n}" } ] }, "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" ], "example": "2026-09-06", "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst apiKey = await client.apiKeys.create({\n name: 'Shine Time Booking (production)',\n permissions: {},\n resource_id: 'biz_xxxxxxxxxxxxxx',\n resource_type: 'account',\n});\n\nconsole.log(apiKey.id);" } ] } }, "/api_keys/permissions": { "get": { "description": "Lists the catalog of permission actions that can be granted to users, apps, and API keys — the source for the dashboard's permission pickers. 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": { "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "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" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.apiKeys.listPermissions();\n\nconsole.log(response.data);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/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-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst apiKey = await client.apiKeys.delete('id');\n\nconsole.log(apiKey.id);" } ] }, "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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst apiKey = await client.apiKeys.retrieve('id');\n\nconsole.log(apiKey.id);" } ] }, "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" ], "example": "2026-09-06", "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst apiKey = await client.apiKeys.update('id');\n\nconsole.log(apiKey.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst apiKey = await client.apiKeys.rotate('id');\n\nconsole.log(apiKey.id);" } ] } }, "/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 logs to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 25, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "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": { "nullable": true, "type": "string" }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List", "title": "List API Logs" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/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": "The number of builds to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns builds after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of builds to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns builds before this position.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const appBuild of client.appBuilds.list({ app_id: 'app_id' })) {\n console.log(appBuild.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Uploads a new build artifact for an app. Upload the file first (POST /files or a direct upload), then reference it here; iOS and Android take a .zip bundle, web takes a JavaScript file or a .zip archive of the hosted site.", "operationId": "createAppBuild", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ai_prompt_id": { "description": "The AI prompt that generated this build, if applicable.", "example": "prmt_xxxxxxxxxxxxxx", "type": "string" }, "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: `{ id }` for an existing file or `{ direct_upload_id }` for a completed 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 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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst appBuild = await client.appBuilds.create({\n attachment: {},\n checksum: 'xxxxxxxxxxxxxxx',\n platform: 'web',\n});\n\nconsole.log(appBuild.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst appBuild = await client.appBuilds.retrieve('id');\n\nconsole.log(appBuild.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App build ID, prefixed `abld_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst appBuild = await client.appBuilds.promote('id');\n\nconsole.log(appBuild.id);" } ] } }, "/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.", "in": "query", "name": "order", "required": false, "schema": { "default": "discoverable_at", "enum": [ "created_at", "discoverable_at", "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": "The number of apps to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns apps after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of apps to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns apps before this position.", "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const appListResponse of client.apps.list()) {\n console.log(appListResponse.id);\n}" } ] }, "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`.", "example": "https://booking.shinetime.example", "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" }, "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": { "description": "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst app = await client.apps.create({ name: 'Shine Time Booking' });\n\nconsole.log(app.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst app = await client.apps.delete('id');\n\nconsole.log(app.id);" } ] }, "get": { "description": "Retrieves an app by ID, claimed route, or proxy domain id. Credential fields (api_key, default_api_key, secrets) render `null` unless the caller has the corresponding 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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst app = await client.apps.retrieve('id');\n\nconsole.log(app.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "App ID (prefixed `app_`), the app's claimed route, or its proxy domain id.", "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://booking.shinetime.example", "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" }, "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" ] }, "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" }, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst app = await client.apps.update('id');\n\nconsole.log(app.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.apps.deploy('id');\n\nconsole.log(response.app_id);" } ] } }, "/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": "The number of log lines to return (max 500).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor for fetching logs after a previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for fetching logs before a later 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-mint": { "metadata": { "sidebarTitle": "List Logs" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.apps.logs('id');\n\nconsole.log(response.data);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Update Permissions" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst app = await client.apps.updatePermissions('id', {\n requested_permissions: [\n {\n action: 'company:basic:read',\n is_required: true,\n justification: 'Reads basic account info to render the dashboard home.',\n },\n ],\n});\n\nconsole.log(app.id);" } ] } }, "/audiences": { "get": { "description": "List custom and lookalike audiences for an account. Pass `audience_id` to return a specific audience.", "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 audiences to return. Defaults to 20; maximum 100.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "Cursor for the next page of audiences.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const audience of client.audiences.list({ account_id: 'account_id' })) {\n console.log(audience.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Create an audience from a customer list, your account's Whop People data, or engagement with videos, lead forms, Instagram profiles, or Facebook pages. Create lookalike audiences to reach people similar to an existing audience. Processing runs asynchronously. Custom creation returns one audience; lookalike creation 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", "object": "facebook_page", "retention_days": 30, "social_account_id": "sacc_xxxxxxxxxxxxxx" } ], "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\"}`. Date filters must be rolling windows — `first_seen_within_days` or `last_seen_within_days` — so the audience re-anchors on every refresh; fixed dates such as `first_seen_after` are rejected. 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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst audience = await client.audiences.create({ account_id: 'biz_xxxxxxxxxxxxxx' });\n\nconsole.log(audience);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst audience = await client.audiences.delete('id');\n\nconsole.log(audience.success);" } ] }, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst audience = await client.audiences.update('id');\n\nconsole.log(audience.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst audience = await client.audiences.addPeople('id', { file_id: 'file_xxxxxxxxxxxxxx' });\n\nconsole.log(audience.id);" } ] } }, "/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 bounties to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of bounties to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const bountyListItem of client.bounties.list()) {\n console.log(bountyListItem.id);\n}" } ] }, "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, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst bounty = await client.bounties.create({\n description:\n 'Record one continuous pass of a full interior detail, dash to trunk, on a customer vehicle.',\n gross_reward_amount: 40,\n title: 'Record interior detailing passes',\n});\n\nconsole.log(bounty.id);" } ] } }, "/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 submissions to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of submissions to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\n// Automatically fetches more pages as needed.\nfor await (const publicBountySubmission of client.bounties.submissions.list('bounty_id')) {\n console.log(publicBountySubmission.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/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" } ] }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst bounty = await client.bounties.retrieve('id');\n\nconsole.log(bounty.id);" } ] }, "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, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst bounty = await client.bounties.update('id');\n\nconsole.log(bounty.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst bounty = await client.bounties.cancel('id');\n\nconsole.log(bounty.id);" } ] } }, "/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 submissions to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of submissions to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const bountySubmission of client.bountySubmissions.list()) {\n console.log(bountySubmission.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a submission on a workforce bounty. Include a `deliverable` payload — any combination of links and uploaded files, with at least one of the two — 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 the separate submit endpoint 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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst bountySubmission = await client.bountySubmissions.create({\n bounty_id: 'bnty_xxxxxxxxxxxxxx',\n});\n\nconsole.log(bountySubmission.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst bountySubmission = await client.bountySubmissions.delete('id');\n\nconsole.log(bountySubmission.id);" } ] }, "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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst bountySubmission = await client.bountySubmissions.retrieve('id');\n\nconsole.log(bountySubmission.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The bounty submission to act on (`btys_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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 an optional `deliverable` — links, files, and a caption in any combination; if the attempt already went to review when its stream ended, the payload attaches to it once, until reviewers start voting. 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 the submission. Combine `urls`, `file_ids`, and `caption` freely; all are optional.", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst bountySubmission = await client.bountySubmissions.submit('id');\n\nconsole.log(bountySubmission.id);" } ] } }, "/card_transactions": { "get": { "description": "Lists an account's card transactions, newest first. Defaults to the account the credential belongs to. 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_`. Defaults to the credential's account.", "in": "query", "name": "account_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": "The number of card transactions to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns card transactions after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of card transactions to return, counting back from the end.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns card transactions before this position.", "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": { "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-mint": { "metadata": { "sidebarTitle": "List Transactions" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const cardTransaction of client.cardTransactions.list()) {\n console.log(cardTransaction.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/card_transactions/{id}": { "get": { "description": "Fetches a single card transaction by its `citx_` identifier. The owner defaults to the account the credential belongs to.", "operationId": "retrieveCardTransaction", "parameters": [ { "description": "The account that owns the transaction, prefixed `biz_`. Defaults to the credential's account.", "in": "query", "name": "account_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-mint": { "metadata": { "sidebarTitle": "Retrieve Transaction" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst cardTransaction = await client.cardTransactions.retrieve('id');\n\nconsole.log(cardTransaction.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The card transaction ID, prefixed `citx_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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, "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst cards = await client.cards.list();\n\nconsole.log(cards.data);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Issue a virtual card, or apply 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.", "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, and whenever a company API key files an account's first card application.", "example": "user_xxxxxxxxxxxxxx", "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.", "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, "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": { "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, or onboarding invitation sent" }, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst card = await client.cards.create();\n\nconsole.log(card.id);" } ] } }, "/cards/{id}": { "get": { "description": "Retrieve a single card.", "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, "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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst card = await client.cards.retrieve('id');\n\nconsole.log(card.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Card ID to retrieve, prefixed `icrd_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Update, freeze, or cancel 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, "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, "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, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst card = await client.cards.update('id');\n\nconsole.log(card.id);" } ] } }, "/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 plan ID, prefixed `plan_`.", "in": "query", "name": "plan_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 checkout configurations to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "Cursor for the next page of results.", "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 plan'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 plan 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" ] }, "plan": { "description": "Plan used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan 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 plans.", "example": 30, "type": [ "integer", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based plans.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the plan currency.", "example": 0, "type": "number" }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "release_method": { "description": "Sales method for the plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59, "type": "number" }, "three_ds_level": { "description": "3D Secure behavior for this plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "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": "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 this checkout, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "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" } }, "required": [ "id", "created_at", "updated_at", "account_id", "mode" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List", "title": "List Checkout Configurations" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const checkoutConfigurationListResponse of client.checkoutConfigurations.list({\n account_id: 'account_id',\n})) {\n console.log(checkoutConfigurationListResponse.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a reusable checkout configuration for an existing or inline plan.", "operationId": "createCheckoutConfiguration", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "plan_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 plan 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" ] }, "plan": { "description": "Plan attributes used to create or find a plan for this checkout configuration. Mutually exclusive with `plan_id`.", "properties": { "account_id": { "description": "Account ID for the inline plan, 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" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "example": "usd", "type": [ "string", "null" ] }, "description": { "description": "Customer-visible plan 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 plans.", "example": 365, "type": [ "integer", "null" ] }, "force_create_new_plan": { "description": "Whether to create a new plan instead of reusing a matching one.", "example": true, "type": [ "boolean", "null" ] }, "initial_price": { "description": "Initial purchase price in the plan currency.", "example": 249, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value metadata stored on the plan.", "example": { "bay": "2" }, "type": [ "object", "null" ] }, "override_tax_type": { "description": "Tax classification override for this plan.", "example": "inclusive", "type": [ "string", "null" ] }, "payment_method_configuration": { "description": "Payment method overrides for the inline plan. `null` uses platform defaults.", "properties": { "disabled": { "description": "Payment methods explicitly disabled for this plan.", "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "description": "Payment methods explicitly enabled for this plan.", "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" ] }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time", null ], "example": "one_time", "type": [ "string", "null" ] }, "product_id": { "description": "Product ID the inline plan should belong to, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "release_method": { "description": "Sales method for the plan.", "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 the inline plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "Plan 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 plan has unlimited stock.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link", null ], "example": "visible", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "plan_id": { "description": "Existing plan ID, prefixed `plan_`. Mutually exclusive with `plan`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "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 this checkout.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "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 plan'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": { "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": "setup", "type": "string" }, "payment_method_configuration": { "description": "Payment method overrides for this checkout. `null` when it uses the plan 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" ] }, "plan": { "description": "Plan used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan 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 plans.", "example": 30, "type": [ "integer", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based plans.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the plan currency.", "example": 0, "type": "number" }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "release_method": { "description": "Sales method for the plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59, "type": "number" }, "three_ds_level": { "description": "3D Secure behavior for this plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "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": "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 this checkout, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", 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" } }, "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-mint": { "metadata": { "sidebarTitle": "Create", "title": "Create a Checkout Configuration" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst checkoutConfiguration = await client.checkoutConfigurations.create();\n\nconsole.log(checkoutConfiguration.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Delete", "title": "Delete a Checkout Configuration" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst checkoutConfiguration = await client.checkoutConfigurations.delete('id');\n\nconsole.log(checkoutConfiguration.id);" } ] }, "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 plan'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 plan 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" ] }, "plan": { "description": "Plan used for payment checkout. `null` in setup mode.", "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan 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 plans.", "example": 30, "type": [ "integer", "null" ] }, "currency": { "description": "Three-letter ISO currency code for the plan's prices.", "example": "usd", "type": "string" }, "expiration_days": { "description": "Access duration in days for expiration-based plans.", "example": 365, "type": [ "integer", "null" ] }, "id": { "description": "Plan ID, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "description": "Initial purchase price in the plan currency.", "example": 0, "type": "number" }, "plan_type": { "description": "Billing model for the plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "release_method": { "description": "Sales method for the plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged each billing period.", "example": 59, "type": "number" }, "three_ds_level": { "description": "3D Secure behavior for this plan, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "trial_period_days": { "description": "Free trial days before the first renewal charge.", "example": 7, "type": [ "integer", "null" ] }, "visibility": { "description": "Whether the plan is visible to customers or hidden from public view.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "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": "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 this checkout, or `null` to use the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "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" } }, "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve", "title": "Retrieve a Checkout Configuration" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst checkoutConfiguration = await client.checkoutConfigurations.retrieve('id');\n\nconsole.log(checkoutConfiguration.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the checkout configuration.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/confirmation_tokens": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Mints a single-use, short-lived confirmation token from what the buyer entered on your collection surface: the payment method payload, billing details, and attested save consent. Public and rate-limited — the account_id in the body scopes the token but does not authenticate. Confirm it with POST /payments from your server.", "operationId": "createConfirmationToken", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "billing_details": { "address": { "city": "Austin", "country": "US", "line1": "123 Main St", "postal_code": "78701" }, "email": "buyer@example.com", "name": "Buyer Name" }, "payment_method": { "card": { "brand": "visa", "last4": "4242", "token_intent": "bt_ti_123" }, "category": "card", "type": "card" }, "setup_future_usage": "off_session" }, "properties": { "account_id": { "description": "The account (biz_) this token is scoped to — the publishable identity.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "billing_details": { "description": "Billing details collected with the method. `email` is always required; cards additionally require `name` and an address with `line1` and `country`.", "properties": { "address": { "example": { "city": "Austin", "country": "US", "line1": "123 Main St", "postal_code": "78701" }, "type": [ "object", "null" ] }, "email": { "example": "marcus@shinetime.example", "type": "string" }, "name": { "example": "Buyer Name", "type": [ "string", "null" ] }, "phone": { "example": "+xxxxxxxxxxx", "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, "browser_info": { "description": "Screen/runtime facts from the buyer's browser (platform, screen dimensions, language, ...) used for authentication ceremonies. Header-derived fields are captured server-side.", "example": { "browser_time_difference": 0, "java_enabled": false, "javascript_enabled": false, "language": "de-DE" }, "type": [ "object", "null" ] }, "payment_method": { "description": "The collected method: `type` names the payment method, `category` names the payload shape, and the category-keyed object carries the payload. Wallets are the exception: their payload rides the type key (`apple_pay` / `google_pay`). Send exactly the one payload arm the category selects — extra arms are rejected. Redirect-flow methods (category `redirect`, `bank_transfer`, `voucher`, and redirect wallets like `cashapp`) collect nothing and send no payload arm.", "properties": { "apple_pay": { "description": "Type `apple_pay` (category `wallet`) only.", "properties": { "merchant_identifier": { "description": "The merchant identifier the Apple Pay sheet validated with — the same hostname-matched value from the type's `merchants` list the session ceremony used. Apple encrypts the wallet token for the certificate attached to this exact identifier, so the charge needs it to decrypt. Omit it when the ceremony omitted it; must be one the account has registered.", "example": "merchant.whop.com.y.uno", "type": [ "string", "null" ] }, "token_intent": { "description": "The Basis Theory token intent the Apple Pay sheet flow vaulted the raw wallet token into.", "example": "bt_ti_apple_789", "type": "string" } }, "required": [ "token_intent" ], "type": "object" }, "balance": { "description": "Category `balance` only. Names one of the buyer's spendable platform balances. Requires a buyer credential — whether the caller may spend the wallet is checked against their own grants, so another user's id reads as not found.", "properties": { "id": { "description": "The balance to spend — a balance id (ldgr_) from GET /balances.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id" ], "type": "object" }, "bank_debit": { "description": "Category `bank_debit` only. A type that declares a secure field (`sepa_debit`) sends the element's tokenized credential as `token`. `us_bank_account` sends nothing here — the buyer links the account after confirm, through the hosted bank-connection flow the payment parks behind.", "properties": { "token": { "description": "The Basis Theory token the element vaulted the account details into. Required for types declaring a secure field; rejected for types that collect after confirm.", "example": "bt_tok_sepa", "type": "string" } }, "type": "object" }, "card": { "description": "Category `card` only. Exactly one of `token` or `token_intent`; display fields ride alongside.", "properties": { "brand": { "description": "Display-safe card brand from the collection surface, e.g. `visa`.", "example": "visa", "type": [ "string", "null" ] }, "last4": { "description": "Display-safe last four digits from the collection surface.", "example": "4242", "type": [ "string", "null" ] }, "token": { "description": "An element-assembled, expiring Basis Theory token. Provide this or token_intent.", "example": "bt_tok_456", "type": "string" }, "token_intent": { "description": "A Basis Theory token intent. Provide this or token.", "example": "bt_ti_123", "type": "string" } }, "type": "object" }, "category": { "description": "The payload shape the surface collected. Must be the category the type resolves to — it is derived server-side and a mismatch is rejected. `saved` and `balance` are the exceptions: they name a method already on file or a spendable balance rather than one collected here.", "enum": [ "card", "wallet", "bank_debit", "bank_transfer", "voucher", "redirect", "crypto", "balance", "in_app_purchase", "saved" ], "example": "card", "type": "string" }, "google_pay": { "description": "Type `google_pay` (category `wallet`) only.", "properties": { "token_intent": { "description": "The Basis Theory token intent the Google Pay sheet flow vaulted the raw wallet token into.", "type": "string" } }, "required": [ "token_intent" ], "type": "object" }, "payer_document": { "description": "The buyer's identity document when the charge currency has a payer_document_requirements entry for this method, such as ARS card, MODO, or Rapipago. This is independent of the method category.", "properties": { "token": { "description": "The Basis Theory token containing the identity-document number.", "example": "20123456", "type": "string" }, "type": { "description": "The selected identity-document type from the method's payer_document_requirements entry.", "enum": [ "dni", "cuil", "cuit", "passport", "cc", "ci", "rut", "curp", "rfc" ], "example": "dni", "type": "string" } }, "required": [ "type", "token" ], "type": "object" }, "redirect": { "description": "Category `redirect` only. Empty unless the method declares redirect-specific fields.", "properties": {}, "type": "object" }, "saved": { "description": "Category `saved` only. Names one of the buyer's own stored payment methods. Requires a buyer credential — the wallet read is scoped to that account, so another user's id reads as not found.", "properties": { "payment_method": { "description": "The stored payment method to charge — a payment method id from GET /payment_methods.", "example": "payt_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "payment_method" ], "type": "object" }, "type": { "description": "The payment method type, for example `card` or `ideal`. Required for every category except `saved` and `balance`, where it is read from the referenced method.", "example": "card", "type": "string" } }, "required": [ "category" ], "type": "object" }, "return_url": { "description": "Where redirect flows send the buyer, carried onto the confirm that consumes this token.", "type": [ "string", "null" ] }, "setup_future_usage": { "description": "The save-consent state your surface displayed when the buyer confirmed. Confirm may vault only if attested here.", "enum": [ "off_session", "on_session", null ], "example": "off_session", "type": [ "string", "null" ] } }, "required": [ "account_id", "payment_method" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationToken" } } }, "description": "confirmation token created from a card token intent" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "a token on a method that collects after confirm" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "saved method requested without a credential" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "credential does not carry the payment methods scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown account" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ {}, { "bearerAuth": [ "member:payment_methods:use" ] } ], "summary": "Create Confirmation Token", "tags": [ "Confirmation Tokens" ], "x-mint": { "metadata": { "sidebarTitle": "Create" } } } }, "/confirmation_tokens/{id}": { "get": { "description": "Retrieves a token's display-safe preview — never the underlying payment credential. Public and rate-limited: the account_id query param must match the account the token was minted for.", "operationId": "retrieveConfirmationToken", "parameters": [ { "description": "The account (biz_) the token was minted for.", "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": [], "summary": "Retrieve Confirmation Token", "tags": [ "Confirmation Tokens" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Confirmation token ID, prefixed `ctok_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/deposits": { "post": { "description": "Retrieve the deposit methods for an account, including crypto and bank transfer. Crypto deposits require a $10 minimum.", "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.", "example": 50, "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" } }, "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 code for international wires, when available.", "example": "CRBAUS33", "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" ] }, "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", "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/ethereum.svg", "type": [ "string", "null" ] }, "name": { "description": "Token symbol.", "enum": [ "ARB", "BNB", "ETH", "EURC", "HYPE", "PYUSD", "SOL", "USD1", "USDC", "USDC.e", "USDG", "USDT", "USDT0", "USDe", "USDm", "XO", "XPL", "pUSD", "wETH" ], "example": "wETH", "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" ], "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" ] } ], "summary": "Create Deposit", "tags": [ "Deposits" ], "x-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst deposit = await client.deposits.create({ destination: 'string' });\n\nconsole.log(deposit.account_id);" } ] } }, "/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": "The number of alerts to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns alerts after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of alerts to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns alerts before this position.", "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": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const disputeAlert of client.disputeAlerts.list()) {\n console.log(disputeAlert.id);\n}" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst disputeAlert = await client.disputeAlerts.retrieve('id');\n\nconsole.log(disputeAlert.id);" } ] } }, "/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": "The number of disputes to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns disputes after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of disputes to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns disputes before this position.", "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. Covers both chargebacks and inquiries at each stage. 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", "under_review", "won", "lost", "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" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Dispute" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const dispute of client.disputes.list()) {\n console.log(dispute.id);\n}" } ] } }, "/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", "under_review", "won", "lost", "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" } } ], "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": { "closed": { "example": 0, "type": "integer" }, "lost": { "example": 0, "type": "integer" }, "needs_response": { "example": 1, "type": "integer" }, "under_review": { "example": 0, "type": "integer" }, "won": { "example": 0, "type": "integer" } }, "required": [ "needs_response", "under_review", "won", "lost", "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-mint": { "metadata": { "sidebarTitle": "Retrieve Summary" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.disputes.summary();\n\nconsole.log(response.groups);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst dispute = await client.disputes.retrieve('id');\n\nconsole.log(dispute.id);" } ] }, "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. Sending it is a separate call.", "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.", "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" ] }, "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.", "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst dispute = await client.disputes.update('id');\n\nconsole.log(dispute.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst dispute = await client.disputes.submit('id');\n\nconsole.log(dispute.id);" } ] } }, "/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. 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. Send every document the packet should carry — up to 10, 10MB each and 25MB in total; an empty list removes them all. Accepted content types: application/pdf, application/json, image/jpeg, image/png, image/webp — any other type is rejected.", "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. Replaces all previously uploaded documents.", "items": { "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "type": "string" }, "document_type": { "description": "What kind of evidence the document is.", "enum": [ "return_policy", "shipping_policy", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription" ], "example": "product_image", "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. Replaces all previously uploaded documents.", "items": { "properties": { "direct_upload_id": { "description": "The ID returned by a direct upload.", "type": "string" }, "document_type": { "description": "What kind of evidence the document is.", "enum": [ "return_policy", "shipping_policy", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription" ], "example": "product_image", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst dispute = await client.disputes.uploadEvidence('id', {\n documents: [{ document_type: 'product_image' }],\n});\n\nconsole.log(dispute.id);" } ] } }, "/events": { "get": { "description": "Lists identity-linked events, most recent first by default. Pass identifier for one person's journey, or omit it to list events for an account within an explicit time range. Pass direction=asc to read a journey forwards from where it starts. Events are shaped like the POST /events intake: attribution in context, identity in user.", "operationId": "listEvents", "parameters": [ { "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": "The number of events to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor for fetching events after a previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for fetching events before a later 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). Restricts the list to conversion targets attributed to that source — the debuggability twin of a metric cell's source parameter. A whop:... source combined with non-conversion event names (event=pixel.page) instead lists the events whose ad click resolved to that entity — the page views an ad drove.", "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" ] }, "recommended_action_chain_id": { "type": [ "string", "null" ] }, "recommended_action_shown_position": { "type": [ "integer", "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": "meta", "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" }, "provider": { "example": "stripe", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "plan": { "properties": { "billing_period": { "example": 30, "type": [ "integer", "null" ] }, "currency": { "example": "usd", "type": [ "string", "null" ] }, "id": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "initial_price": { "example": 0, "type": [ "number", "null" ] }, "renewal_price": { "example": 59, "type": [ "number", "null" ] }, "title": { "example": "Unlimited Wash Club", "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" ] } }, "type": [ "object", "null" ] }, "total_usd_amount": { "example": 249, "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, "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const eventListResponse of client.events.list()) {\n console.log(eventListResponse.id);\n}" } ] }, "post": { "description": "Tracks a conversion or engagement event for an account.", "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 plan 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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst event = await client.events.create({\n account_id: 'biz_xxxxxxxxxxxxxx',\n event_name: 'coating_deposit_paid',\n});\n\nconsole.log(event.id);" } ] } }, "/events/pulse": { "get": { "description": "Returns a fully anonymized feed of recent platform-wide money movement, most recent first: purchases, affiliate commissions, card and ad spend, app revenue, off-platform sales, wallet deposits, card loads, claimed drops, transfers between accounts, and referral bonuses. Items carry only a `type`, the underlying event name, a USD amount, a coarse location under `user`, and a timestamp coarsened to the start of the minute; missing fields are omitted, not nulled. The payload is identical for every caller; no auth is required.", "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": "The number of events to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor for fetching events after a previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for fetching events before a later 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" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst response = await client.events.pulse();\n\nconsole.log(response.data);" } ], "x-mint": { "metadata": { "title": "Retrieve the Pulse Feed", "sidebarTitle": "Retrieve the Pulse Feed" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/events/validate_pixel": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Checks whether the Whop pixel is installed for an account. Recent pixel events count as proof on their own, so an account that has sent data lately comes back installed without a `url`. Pass a `url` and events from that page settle it; conversion events are also read across the hostname because they commonly fire on a later confirmation page. If the requested page hasn't sent any events lately, it is fetched and read for the pixel and conversion events wired on it. `installed` is only true when the pixel was actually seen — in the account's events or in the page.", "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 read for the pixel, e.g. an ad destination. 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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst pixelValidation = await client.events.validatePixel();\n\nconsole.log(pixelValidation.firing_data_ok);" } ] } }, "/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", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "content_rewards_submissions", "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": { "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": [ "content_rewards:basic:export" ] }, { "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: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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst exports = await client.exports.list();\n\nconsole.log(exports.data);" } ] }, "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.\n\n
\nFilters by resource (25)\n\n
\nad_campaigns (4)\n\nMirrors the filtering query params of `GET /api/v1/ad_campaigns`.\n\n- `created_after` `string` — Only return campaigns created after this timestamp.\n- `created_before` `string` — Only return campaigns created before this timestamp.\n- `query` `string` — Filter campaigns by a title or ID substring.\n- `status` `string` — Only return campaigns with this status. One of `draft`, `active`, `paused`, `payment_failed`.\n\n
\n
\nad_groups (6)\n\nMirrors the filtering query params of `GET /api/v1/ad_groups`.\n\n- `ad_campaign_id` `string` — Filter to ad groups in this campaign.\n- `ad_campaign_ids` `string[]` — Filter to ad groups in these campaigns (max 100). Repeat the parameter for each id (ad_campaign_ids=a&ad_campaign_ids=b).\n- `created_after` `string` — Only return ad groups created after this timestamp.\n- `created_before` `string` — Only return ad groups created before this timestamp.\n- `query` `string` — Filter ad groups by a title or ID substring.\n- `status` `string` — Filter to ad groups with this status. One of `active`, `paused`, `rejected`, `duplicating`.\n\n
\n
\nads (8)\n\nMirrors the filtering query params of `GET /api/v1/ads`.\n\n- `ad_campaign_id` `string` — Only return ads in this ad campaign.\n- `ad_campaign_ids` `string[]` — Only return ads in these ad campaigns (max 100). Repeat the parameter for each id (ad_campaign_ids=a&ad_campaign_ids=b).\n- `ad_group_id` `string` — Only return ads in this ad group.\n- `ad_group_ids` `string[]` — Only return ads in these ad groups (max 100). Repeat the parameter for each id (ad_group_ids=a&ad_group_ids=b).\n- `created_after` `string` — Only return ads created after this timestamp.\n- `created_before` `string` — Only return ads created before this timestamp.\n- `query` `string` — Filter ads by a title or ID substring.\n- `status` `string` — Only return ads with this status. One of `active`, `paused`, `in_review`, `rejected`.\n\n
\n
\napps (6)\n\nMirrors the filtering query params of `GET /api/v1/apps`.\n\n- `app_type` `string` — 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. One of `b2b_app`, `b2c_app`, `company_app`, `component`, `website`.\n- `query` `string` — A search string matched against app names.\n- `recommended` `boolean` — Only return apps Whop recommends (or, with `false`, only those it does not), independently of verification status.\n- `verified` `boolean` — Only return apps whose Whop verification status matches this value. Omit this filter to include every verification status the caller can see.\n- `verified_apps_only` `boolean` — 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.\n- `view_type` `string` — Only return apps supporting this view type, such as `dashboard` or `hub`. One of `hub`, `discover`, `dash`, `dashboard`, `analytics`, `skills`, `openapi`.\n\n
\n
\naudiences (3)\n\nMirrors the filtering query params of `GET /api/v1/audiences`.\n\n- `audience_id` `string` — Audience ID, prefixed `adaud_`, used to filter the response to one audience.\n- `audience_type` `string` — Filter by custom or lookalike audiences. One of `custom`, `lookalike`.\n- `source_type` `string` — Filter by uploaded customer lists, Whop People filters, or social engagement. One of `csv_upload`, `people_filter`, `engagement`.\n\n
\n
\nbounties (8)\n\nMirrors the filtering query params of `GET /api/v1/bounties`.\n\n- `business_goal_type` `string` — Filter by the poster's declared goal. Bounties created before the goal taxonomy carry no goal and never match this filter. One of `clipping`, `post_engagement`, `owned_account_growth`, `ugc_content`, `local_activation`, `data_capture`, `other`.\n- `country` `string` — 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.\n- `created_after` `string` — Only bounties created after this ISO 8601 timestamp.\n- `created_before` `string` — Only bounties created before this ISO 8601 timestamp.\n- `experience_id` `string` — Only bounties posted to this forum experience, prefixed `exp_`. An unknown experience, or one outside the caller's scope, matches nothing.\n- `query` `string` — Substring match on the bounty title or ID.\n- `status` `string` — Filter by lifecycle state. One of `scheduled`, `open`, `closed`, `completed`, `canceled`.\n- `user_id` `string` — List the bounties this user participated in (`user_` tag). Must be the authenticated user.\n\n
\n
\nbounty_submissions (4)\n\nMirrors the filtering query params of `GET /api/v1/bounty_submissions`.\n\n- `bounty_id` `string` — Only submissions on this bounty (`bnty_` tag).\n- `created_after` `string` — Only submissions created after this ISO 8601 timestamp.\n- `created_before` `string` — Only submissions created before this ISO 8601 timestamp.\n- `status` `string` — Filter by lifecycle state. One of `in_progress`, `submitted`, `approved`, `denied`.\n\n
\n
\ncard_transactions (6)\n\nMirrors the filtering query params of `GET /api/v1/card_transactions`.\n\n- `card_id` `string[]` — Return only transactions charged to these cards, each prefixed `icrd_`.\n- `cardholder_id` `string[]` — Return only transactions on cards assigned to these users, each prefixed `user_`.\n- `created_after` `string` — Return only transactions authorized at or after this ISO 8601 timestamp.\n- `created_before` `string` — Return only transactions authorized at or before this ISO 8601 timestamp.\n- `status` `string` — Return only transactions with this status. One of `pending`, `completed`, `reversed`, `declined`.\n- `transaction_ids` `string[]` — Return only these card transactions, each prefixed `citx_`. Repeat the parameter, or pass one comma-separated value.\n\n
\n
\ncheckout_configurations (3)\n\nMirrors the filtering query params of `GET /api/v1/checkout_configurations`.\n\n- `created_after` `string` — Only return checkout configurations created after this ISO 8601 timestamp.\n- `created_before` `string` — Only return checkout configurations created before this ISO 8601 timestamp.\n- `plan_id` `string` — Only return checkout configurations for this plan ID, prefixed `plan_`.\n\n
\n
\ndisputes (4)\n\nMirrors the filtering query params of `GET /api/v1/disputes`.\n\n- `created_after` `string` — Only disputes opened after this ISO 8601 timestamp.\n- `created_before` `string` — Only disputes opened before this ISO 8601 timestamp.\n- `currency` `string` — Only disputes in this three-letter ISO currency.\n- `status` `string[]` — Only disputes in these statuses. Repeat the parameter to pass several — one paginated list covers all of them. Covers both chargebacks and inquiries at each stage. A `needs_response` dispute whose evidence deadline has passed reports and filters as `under_review` instead.\n\n
\n
\nevents (14)\n\nMirrors the filtering query params of `GET /api/v1/events`.\n\n- `attribution_model` `string` — Attribution model for the source filter (defaults to last_touch). One of `last_touch`, `first_touch`.\n- `browser` `string` — Browser families to filter by, comma-separated (e.g. Chrome, Mobile Safari).\n- `city` `string` — Cities to filter by, comma-separated.\n- `country` `string` — Country codes to filter by, comma-separated.\n- `device` `string` — Device families to filter by, comma-separated (e.g. iPhone, Mac).\n- `event` `string` — Full event names to filter by, comma-separated (payment.completed, pixel.lead, pixel.page, pixel.custom:) — the same vocabulary the events / people metrics use.\n- `from` `string` — Start of the time range as an ISO 8601 timestamp. Required when identifier is omitted.\n- `hostname` `string` — Page hostnames to filter by, comma-separated.\n- `identifier` `string` — 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.\n- `os` `string` — Operating system families to filter by, comma-separated (e.g. iOS, Windows).\n- `page` `string` — Page paths to filter by, comma-separated.\n- `source` `string` — Canonical source path, exact or with a trailing :* prefix (whop::*, ext:meta:*, referrer:, direct). Restricts the list to conversion targets attributed to that source — the debuggability twin of a metric cell's source parameter. A whop:... source combined with non-conversion event names (event=pixel.page) instead lists the events whose ad click resolved to that entity — the page views an ad drove.\n- `to` `string` — End of the time range as an ISO 8601 timestamp. Required when identifier is omitted; otherwise defaults to now.\n- `utm_source` `string` — utm_source values to filter by, comma-separated.\n\n
\n
\nfinancial-activity (12)\n\nMirrors the filtering query params of `GET /api/v1/financial-activity`.\n\n- `activity_id` `string` — Optional ledger activity ID (for example `line_3`). Returns at most that one activity.\n- `available_after` `string` — Only include rows whose funds became withdrawable on or after this `YYYY-MM-DD` settlement date (UTC), distinct from posted_at. Requires currency.\n- `available_before` `string` — Only include rows whose funds became withdrawable on or before this `YYYY-MM-DD` settlement date (UTC). Set equal to available_after for a single day. Requires currency.\n- `currency` `string` — Optional currency code filter, for example `usd`.\n- `exclude_internal_movements` `boolean` — Whether to exclude balance reservations and balanced movements between the account's own balances.\n- `include_owned_accounts` `boolean` — 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`.\n- `include_resource` `boolean` — 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.\n- `line_types` `string[]` — 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.\n- `posted_after` `string` — Only include rows posted after this ISO 8601 timestamp.\n- `posted_before` `string` — Only include rows posted before this ISO 8601 timestamp.\n- `resource_id` `string` — Optional prefixed resource ID. Returns activity associated with that resource.\n- `user_id` `string` — The owning user ID (a user_ identifier). Provide this or account_id.\n\n
\n
\nmembers (6)\n\nMirrors the filtering query params of `GET /api/v1/members`.\n\n- `access_level` `string` — Filter by what the member can reach on the account. One of `no_access`, `admin`, `customer`.\n- `created_after` `string` — Only members who joined after this ISO 8601 timestamp.\n- `created_before` `string` — Only members who joined before this ISO 8601 timestamp.\n- `query` `string` — Search members by name or username. An exact email address also matches when the credential holds the member:email:read scope.\n- `status` `string` — Filter by whether the member is still part of the account. One of `joined`, `left`.\n- `user_ids` `string[]` — Only return members whose users match these `user_` identifiers.\n\n
\n
\nmemberships (6)\n\nMirrors the filtering query params of `GET /api/v1/memberships`.\n\n- `created_after` `string` — Only memberships created after this ISO 8601 timestamp.\n- `created_before` `string` — Only memberships created before this ISO 8601 timestamp.\n- `plan_id` `string` — Filter to memberships of this plan (`plan_` tag). Repeat as plan_ids[] for several.\n- `product_id` `string` — Filter to memberships of this product (`prod_` tag). Repeat as product_ids[] for several.\n- `status` `string` — Filter by billing state. `canceling` matches active memberships set to cancel at period end; `paused` matches memberships with payment collection paused. One of `active`, `trialing`, `past_due`, `completed`, `canceled`, `expired`, `canceling`, `paused`.\n- `user_id` `string` — 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.\n\n
\n
\npayouts (7)\n\nMirrors the filtering query params of `GET /api/v1/payouts`.\n\n- `created_after` `string` — Only payouts created at or after this ISO 8601 time (inclusive).\n- `created_before` `string` — Only payouts created before this ISO 8601 time (exclusive).\n- `currency` `string` — Optional currency code filter, for example `usd`.\n- `payout_method_id` `string` — Filter to payouts sent to one saved payout method (a pytk_ identifier). An unknown id matches nothing.\n- `source` `string` — Filter by how the payout was created. Payouts created before source tracking or through internal tooling carry no source and never match. One of `api`, `dashboard`, `automatic`.\n- `status` `string` — 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. One of `requested`, `in_review`, `processing`, `completed`, `reversed`, `canceled`, `failed`, `denied`.\n- `user_id` `string` — The owning user ID (a user_ identifier). Provide this or account_id.\n\n
\n
\npeople (20)\n\nMirrors the filtering query params of `GET /api/v1/people`.\n\n- `attribution_model` `string` — Attribution model the source filter matches against (defaults to last_touch). One of `last_touch`, `first_touch`.\n- `audience_id` `string` — 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.\n- `contactable` `boolean` — true for people who have an email address or phone number — the ones an ad platform can match.\n- `country` `string` — Only include people whose most recent visit came from this ISO 3166-1 alpha-2 country code.\n- `custom_event` `string` — Only include people who fired this custom pixel event.\n- `email` `string` — Only include the person linked to this email address.\n- `event_from` `string` — With event_to plus an event or source filter, switches to exact-population mode: person ids are resolved and paginated on the events side within this window (the same query the people metric counts), then hydrated per page.\n- `event_name` `string[]` — Only include people who fired any of these events, e.g. payment.completed or page.checkout.view.\n- `event_to` `string` — The inclusive end of the event window for exact-population mode.\n- `first_seen_after` `string` — Only include people first seen at or after this ISO 8601 timestamp.\n- `first_seen_before` `string` — Only include people first seen before this ISO 8601 timestamp.\n- `first_seen_within_days` `integer` — Only include people first seen within this many days, as a rolling window.\n- `has_purchased` `boolean` — true for customers only, false for people who have never purchased.\n- `last_seen_after` `string` — Only include people last seen at or after this ISO 8601 timestamp.\n- `last_seen_before` `string` — Only include people last seen before this ISO 8601 timestamp.\n- `last_seen_within_days` `integer` — Only include people last seen within this many days, as a rolling window.\n- `phone` `string` — Only include the person linked to this phone number.\n- `query` `string` — Search people by name, email, phone, or whop user ID (case-insensitive substring match).\n- `source` `string[]` — 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.\n- `user_id` `string` — Only include the person linked to this whop user ID.\n\n
\n
\nplans (6)\n\nMirrors the filtering query params of `GET /api/v1/plans`.\n\n- `created_after` `string` — Only return plans created after this timestamp.\n- `created_before` `string` — Only return plans created before this timestamp.\n- `plan_types` `string[]` — Filter to only plans matching these billing types.\n- `product_ids` `string[]` — Filter to only plans belonging to these product identifiers. When `account_id` is omitted, this is required and the response is publicly readable: only visible, non-invoice plans are returned.\n- `release_methods` `string[]` — Filter to only plans matching these release methods.\n- `visibilities` `string[]` — Filter to only plans matching these visibility states.\n\n
\n
\nproducts (10)\n\nMirrors the filtering query params of `GET /api/v1/products`.\n\n- `access_pass_types` `string[]` — Filter to only products matching these types.\n- `created_after` `string` — Only return products created after this ISO 8601 timestamp.\n- `created_before` `string` — Only return products created before this ISO 8601 timestamp.\n- `labels` `string[]` — Filter to only products carrying all of these labels. Labels are matched lowercased.\n- `marketplace_category_route` `string` — Only return marketplace products assigned to this category route, such as `trading`.\n- `plan_types` `string[]` — Filter to products with a buyable plan of these billing models, such as `one_time` or `renewal`.\n- `price_maximum` `number` — Only return products whose advertised buyable plan has a displayed price of at most this amount. Recurring plans use renewal price.\n- `price_minimum` `number` — Only return products whose advertised buyable plan has a displayed price of at least this amount. Recurring plans use renewal price.\n- `query` `string` — Ranked search against product title and headline. Omit to browse by recency.\n- `visibilities` `string[]` — Filter to only products matching these visibility states. Ignored on the public marketplace list, which only returns visible products.\n\n
\n
\npromo_codes (5)\n\nMirrors the filtering query params of `GET /api/v1/promo_codes`.\n\n- `created_after` `string` — Only promo codes created after this ISO 8601 timestamp.\n- `created_before` `string` — Only promo codes created before this ISO 8601 timestamp.\n- `plan_ids` `string[]` — Only promo codes scoped to these plan IDs.\n- `product_ids` `string[]` — Only promo codes scoped to these product IDs.\n- `status` `string` — Promo-code status. `expired` groups inactive and archived codes. One of `active`, `inactive`, `archived`, `expired`.\n\n
\n
\nresolution_center_cases (6)\n\nMirrors the filtering query params of `GET /api/v1/resolution_center_cases`.\n\n- `created_after` `string` — Only cases created after this ISO 8601 timestamp.\n- `created_before` `string` — Only cases created before this ISO 8601 timestamp.\n- `outcome` `string[]` — Only closed cases that ended these ways. Repeat the parameter to pass several.\n- `reason` `string[]` — Only cases opened for these reasons. Repeat the parameter to pass several.\n- `status` `string[]` — Only cases in these statuses. Repeat the parameter to pass several — one paginated list covers all of them.\n- `user_id` `string` — 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.\n\n
\n
\nshipments (4)\n\nMirrors the filtering query params of `GET /api/v1/shipments`.\n\n- `created_after` `string` — Return shipments created after this ISO 8601 timestamp.\n- `created_before` `string` — Return shipments created before this ISO 8601 timestamp.\n- `payment_id` `string[]` — 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.\n- `status` `string` — Filter to shipments with this delivery status. One of `unknown`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `available_for_pickup`, `return_to_sender`, `failure`, `cancelled`, `error`.\n\n
\n
\nsocial_accounts (4)\n\nMirrors the filtering query params of `GET /api/v1/social_accounts`.\n\n- `platform` `string` — Only return social accounts for the platform that is specified. One of `x`, `instagram`, `youtube`, `tiktok`, `facebook`, `discord`, `telegram`.\n- `scopes` `string[]` — Only return social accounts that have these scopes.\n- `user_id` `string` — The User that the social accounts are connected to. Provide either this or account_id.\n- `verified` `boolean` — Only return social accounts that are verified on the platform.\n\n
\n
\nteam_members (5)\n\nMirrors the filtering query params of `GET /api/v1/team_members`.\n\n- `created_after` `string` — Only return members added after this ISO 8601 timestamp.\n- `created_before` `string` — Only return members added before this ISO 8601 timestamp.\n- `role` `string` — Only return members with this role. `custom` matches members on a dashboard-managed custom role. One of `owner`, `admin`, `sales_manager`, `moderator`, `advertiser`, `app_manager`, `support`, `manager`, `workforce`, `custom`.\n- `status` `string` — Only return members with this status: `joined` (accepted members) or `pending` (pending invites). Both are returned by default. One of `joined`, `pending`.\n- `user_id` `string` — Only return the membership for this user ID, prefixed `user_`.\n\n
\n
\ntransfers (4)\n\nMirrors the filtering query params of `GET /api/v1/transfers`.\n\n- `created_after` `string` — Only transfers created strictly after this ISO 8601 timestamp.\n- `created_before` `string` — Only transfers created strictly before this ISO 8601 timestamp.\n- `destination_id` `string` — Filter to transfers received by this account. Provide this or origin_id.\n- `origin_id` `string` — Filter to transfers sent from this account. Provide this or destination_id.\n\n
\n
\nwebhooks (3)\n\nMirrors the filtering query params of `GET /api/v1/webhooks`.\n\n- `app_id` `string` — Only return webhooks attached to this app. Omit to list the account's own webhooks.\n- `has_failures` `boolean` — 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.\n- `include_app_webhooks` `boolean` — Also return webhooks attached to the account's apps, not just the account's own. Cannot be combined with `app_id`.\n\n
\n
", "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", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "content_rewards_submissions", "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": [ "content_rewards:basic:export" ] }, { "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: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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst _export = await client.exports.create({ resource: 'transfers' });\n\nconsole.log(_export.id);" } ] } }, "/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": [ "content_rewards:basic:export" ] }, { "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: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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst _export = await client.exports.retrieve('id');\n\nconsole.log(_export.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The export ID, prefixed `exprt_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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. A request for up to 100 IDs answers in a single page by default; a larger batch pages at up to 100 files per response — 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": "The number of files to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns files after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of files to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns files before this position.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } } }, "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-mint": { "metadata": { "sidebarTitle": "Create" } } } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the file, prefixed `file_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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" ] } }, "/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": [ "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", "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", "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_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "orchestration_percentage_fee", "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_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_earning", "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": "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": "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 rows whose funds became withdrawable on or after this `YYYY-MM-DD` settlement date (UTC), distinct from posted_at. Requires currency.", "in": "query", "name": "available_after", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Only include rows whose funds became withdrawable on or before this `YYYY-MM-DD` settlement 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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst financialActivities = await client.financialActivity.list();\n\nconsole.log(financialActivities.data);" } ] } }, "/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.", "in": "query", "name": "group_by", "required": false, "schema": { "default": "month", "enum": [ "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": [ "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", "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", "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_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "orchestration_percentage_fee", "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_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_earning", "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" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "beginning_balance": { "example": 11480.02, "type": [ "number", "null" ] }, "currencies": { "description": "Every lifetime cashflow currency, ordered by cashflow volume in the requested period.", "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", "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_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", "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", "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_swap_offset", "onchain_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "onchain_withdrawal_offset", "orchestration_percentage_fee", "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_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_earning", "platform_earning_settlement", "platform_earning_unreconciled_clearing", "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_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_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", "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" ] } }, "/financial_reports/breakdown": { "get": { "description": "Returns the top entities behind one high-level financial report bucket and an aggregate remainder.", "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", "swaps" ], "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": [ "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", "swaps" ], "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" }, { "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" ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Generate Asset" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst mediaAsset = await client.media.generate({\n prompt: 'A 9:16 product showcase of a cordless power scrubber',\n type: 'video',\n});\n\nconsole.log(mediaAsset.id);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Retrieve Asset" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst mediaAsset = await client.media.retrieve('id');\n\nconsole.log(mediaAsset.id);" } ] } }, "/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": "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.", "in": "query", "name": "order", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "joined_at", "last_accessed_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 members to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of members to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const member of client.members.list()) {\n console.log(member.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst member = await client.members.retrieve('id');\n\nconsole.log(member.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Member ID (`mber_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/members/{id}/logs": { "get": { "description": "Lists activity for a member and all of their non-drafted memberships, most recent first.", "operationId": "listMemberLogs", "parameters": [ { "description": "Number of log entries to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of log entries to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List Logs" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const logListResponse of client.members.logs.list('id')) {\n console.log(logListResponse.action);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Member ID (`mber_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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": "Filter by billing state. `canceling` matches active memberships set to cancel at period end; `paused` matches memberships with payment collection paused.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "trialing", "past_due", "completed", "canceled", "expired", "canceling", "paused" ], "type": "string" } }, { "description": "Filter to memberships of this product (`prod_` tag). Repeat as product_ids[] for several.", "in": "query", "name": "product_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to memberships of this plan (`plan_` tag). Repeat as plan_ids[] for several.", "in": "query", "name": "plan_id", "required": false, "schema": { "type": "string" } }, { "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 memberships to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of memberships to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const membership of client.memberships.list()) {\n console.log(membership.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/memberships/invite": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Sends an email inviting one recipient to join the account through a free plan. Identify the recipient by exactly one of `user_id` or `email`. 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": { "plan_id": { "description": "Free plan whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "Recipient user ID, prefixed `user_`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "plan_id", "user_id" ], "title": "InviteMembershipByUser", "type": "object" }, { "properties": { "email": { "description": "Recipient email address.", "example": "marcus@shinetime.example", "format": "email", "type": "string" }, "plan_id": { "description": "Free plan whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "plan_id", "email" ], "title": "InviteMembershipByEmail", "type": "object" } ], "properties": { "email": { "description": "Recipient email address. Mutually exclusive with `user_id`.", "example": "marcus@shinetime.example", "format": "email", "type": "string" }, "plan_id": { "description": "Free plan whose membership the recipient is invited to, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "user_id": { "description": "Recipient user ID, prefixed `user_`. Mutually exclusive with `email`.", "example": "user_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "plan_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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.memberships.invite({\n plan_id: 'plan_xxxxxxxxxxxxxx',\n user_id: 'user_xxxxxxxxxxxxxx',\n});\n\nconsole.log(response.invitation_sent);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst membership = await client.memberships.retrieve('id');\n\nconsole.log(membership.id);" } ] }, "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: merge metadata key-value pairs, or toggle `cancel_at_period_end` — `true` schedules the cancellation for the end of the current billing period, `false` reverses a pending one.", "operationId": "updateMembership", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "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" } }, "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" ] } ], "summary": "Update Membership", "tags": [ "Memberships" ], "x-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst membership = await client.memberships.update('id');\n\nconsole.log(membership.id);" } ] } }, "/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. Pass `cancel_at_period_end: true` to stop auto-renewal and keep access until the current billing period ends. Omit it (or pass `false`) to revoke access immediately. 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" }, "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst membership = await client.memberships.cancel('id');\n\nconsole.log(membership.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst membership = await client.memberships.extend('id', { days: 7 });\n\nconsole.log(membership.id);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Pause" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst membership = await client.memberships.pause('id');\n\nconsole.log(membership.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst membership = await client.memberships.resume('id');\n\nconsole.log(membership.id);" } ] } }, "/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" ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.memberships.transfer('id');\n\nconsole.log(response.url);" } ] } }, "/notifications": { "get": { "description": "Lists the authenticated user's notifications, newest first. Requires a user credential — an account API key has no notification feed. Without filters the feed spans every experience the user belongs to plus the teams they are a member of.", "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": "The number of notifications to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor (a notification `id` from a previous page); returns notifications older than it.", "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const notification of client.notifications.list()) {\n console.log(notification.id);\n}" } ] }, "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst notification = await client.notifications.create({\n content: 'Drop off at 4180 Burnet Rd. Plan on two days for the full coating.',\n title: 'Your ceramic coating is booked',\n});\n\nconsole.log(notification.success);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "List Badges" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.notifications.badges();\n\nconsole.log(response.data);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/notifications/mark_read": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Marks the authenticated user's notifications as read: one experience's (`experience_id`) or everything (`all: true`) — exactly one of the two. Requires a user credential. Responds with the refreshed badge rows for the affected scope.", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.notifications.markRead();\n\nconsole.log(response.data);" } ] } }, "/notifications/topics": { "get": { "description": "Lists the platform's visible notification topics — the categories users can set notification preferences on. App-created topics are internal and 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": "The number of topics to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns topics after this position.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List Topics" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const notificationTopic of client.notifications.topics.list()) {\n console.log(notificationTopic.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/notifications/{id}": { "get": { "description": "Retrieves a single notification by id — either an `id` returned by List Notifications, or the ephemeral id delivered with a push/websocket event. Requires a user credential.", "operationId": "retrieveNotification", "parameters": [ { "description": "A notification `id` from List Notifications, or the id delivered with a push/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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst notification = await client.notifications.retrieve('id');\n\nconsole.log(notification.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst partner = await client.partners.create();\n\nconsole.log(partner.referral_link);" } ], "x-mint": { "metadata": { "title": "Enroll as a Whop Partner", "sidebarTitle": "Enroll as a Whop Partner" } } } }, "/partners/businesses": { "get": { "description": "Lists the businesses the authenticated user referred onto Whop, most recent first.", "operationId": "listPartnerBusinesses", "parameters": [ { "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 partner businesses to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of partner businesses to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "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": "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" } } ], "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" ] }, "created_at": { "description": "When the partner business was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "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" ] } }, "required": [ "sales", "ad_spend", "transfer", "card_interchange" ], "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" ] }, "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" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const businessListResponse of client.partners.businesses.list()) {\n console.log(businessListResponse.id);\n}" } ], "x-mint": { "metadata": { "title": "List Referred Businesses", "sidebarTitle": "List Referred Businesses" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/partners/businesses/{id}": { "get": { "description": "Retrieves a single referred business and its referral terms.", "operationId": "retrievePartnerBusiness", "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" ] }, "created_at": { "description": "When the partner business was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "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.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" ] } }, "required": [ "sales", "ad_spend", "transfer", "card_interchange" ], "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" ] }, "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" ], "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" ] } ], "summary": "Retrieve a referred business", "tags": [ "Partners" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst business = await client.partners.businesses.retrieve('id');\n\nconsole.log(business.id);" } ], "x-mint": { "metadata": { "title": "Retrieve a Referred Business", "sidebarTitle": "Retrieve a Referred Business" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The partner business ID (a coma_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/partners/businesses/{id}/earnings": { "get": { "description": "Lists the earnings Whop pays out for one referred business's activity, most recent first.", "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" ], "example": "sales", "type": "string" }, "type": "array" }, "style": "form" }, { "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "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, or Whop Card interchange.", "enum": [ "sales", "ad_spend", "transfer", "card_interchange" ], "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" ] }, "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", "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" }, { "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, or the card transaction for card interchange 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", "financial_activity", "cancelation_reason", "created_at", "payout_at", "resource" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "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" ] } ], "summary": "List referred business earnings", "tags": [ "Partners" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const earningListResponse of client.partners.businesses.earnings.list('id')) {\n console.log(earningListResponse.id);\n}" } ], "x-mint": { "metadata": { "title": "List Referred Business Earnings", "sidebarTitle": "List Referred Business Earnings" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The partner business ID (a coma_ identifier).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/partners/leaderboard": { "get": { "description": "Ranks referrers by partner business earnings — all-time by default, or over the current day, month, year, or trailing 30 days. 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" ] } }, "required": [ "leaders", "me" ], "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" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst response = await client.partners.leaderboard();\n\nconsole.log(response.leaders);" } ], "x-mint": { "metadata": { "title": "Retrieve the Leaderboard", "sidebarTitle": "Retrieve the Leaderboard" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/partners/links": { "get": { "description": "Resolves the public reward terms and whether redemption capacity remains. Immediate rewards claim capacity at business creation; qualified rewards claim it when the business reaches the threshold.", "operationId": "retrievePartnerLink", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingReward" } } }, "description": "reward link verified" }, "404": { "$ref": "#/components/responses/NotFound", "description": "reward link not found" } }, "security": [], "summary": "Retrieve a partner reward link", "tags": [ "Partners" ], "x-mint": { "metadata": { "title": "Retrieve a Partner Reward Link", "sidebarTitle": "Retrieve a Partner Reward Link" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Username from the partner link's `a` query parameter.", "in": "query", "name": "partner_username", "required": true, "schema": { "type": "string" } }, { "description": "Reward slug from the partner link's `reward` query parameter.", "in": "query", "name": "reward_slug", "required": true, "schema": { "type": "string" } } ] }, "/partners/referred_users": { "get": { "description": "Lists the users the caller referred onto Whop (newest first), each with the second-tier earnings the caller has made from that user's businesses.", "operationId": "listReferredUsers", "parameters": [ { "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": "Number of referred users to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of referred users to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "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" } }, "required": [ "total_earnings_usd", "total_volume_usd", "user" ], "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "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" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "partner:basic:read" ] }, { "bearerAuth": [ "referral:basic:read" ] } ], "summary": "List the users the caller referred", "tags": [ "Partners" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.partners.referredUsers();\n\nconsole.log(response.data);" } ], "x-mint": { "metadata": { "title": "List the Users the Caller Referred", "sidebarTitle": "List the Users the Caller Referred" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/payment_method_domains": { "get": { "description": "Lists payment method domains. Without `account_id`, returns the caller's own domains and those of every connected account.", "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 domains to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of domains to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const paymentMethodDomain of client.paymentMethodDomains.list()) {\n console.log(paymentMethodDomain.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "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 the verify endpoint.", "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.example`).", "example": "pending.shinetime.example", "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst paymentMethodDomain = await client.paymentMethodDomains.create({\n hostname: 'pending.shinetime.example',\n});\n\nconsole.log(paymentMethodDomain.id);" } ] } }, "/payment_method_domains/{id}": { "delete": { "description": "Unregisters a payment method domain so its wallet payment methods stop rendering there.", "operationId": "deletePaymentMethodDomain", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "example": true, "type": "boolean" }, "id": { "example": "pmd_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-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst paymentMethodDomain = await client.paymentMethodDomains.delete('id');\n\nconsole.log(paymentMethodDomain.id);" } ] }, "get": { "description": "Retrieves a payment method domain to check its verification status.", "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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst paymentMethodDomain = await client.paymentMethodDomains.retrieve('id');\n\nconsole.log(paymentMethodDomain.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the payment method domain, prefixed `pmd_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/payment_method_domains/{id}/verify": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The unique identifier of the payment method domain, prefixed `pmd_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "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.", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst paymentMethodDomain = await client.paymentMethodDomains.verify('id');\n\nconsole.log(paymentMethodDomain.id);" } ] } }, "/payments": { "get": { "description": "Lists payments, newest first. Without filters this is every payment the caller can read: a company credential's own account, or for a user every account they can read payments for. Filters narrow by account, buyer, product, plan, membership, status, billing reason, currency, and creation window. Filtering by `billing_reason=subscription_cycle` also matches renewals recorded as `subscription_update`. `settlement_time_at` is null on list rows — retrieve the payment for it.", "operationId": "listPayments", "parameters": [ { "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 charged for this reason.", "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_`.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Search payments by 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 user ID, membership ID, user email, name, or username. Email filtering requires the member:email:read permission.", "type": "string" } }, { "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 plan, prefixed `plan_`.", "in": "query", "name": "plan_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": "The field to sort by.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "created_at", "paid_at" ], "type": "string" } }, { "description": "The sort direction.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "The number of payments to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns payments after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of payments to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns payments before this position.", "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": { "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" } }, "security": [ { "bearerAuth": [ "payment:basic:read" ] } ], "summary": "List Payments", "tags": [ "Payments" ], "x-mint": { "metadata": { "sidebarTitle": "List" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Charges a buyer for a plan. Pass a payment method already on file (`member_id` and `payment_method_id`), or a `confirmation_token` describing a method the buyer just supplied. Collection runs in the background: the response is the payment as created, not its outcome — poll Retrieve status for how far it has got and, for a confirmation-token payment, what the buyer must still do. `plan_id` names the plan to charge for.", "operationId": "createPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The account to charge for, prefixed `biz_`.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "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.", "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": "Overrides the buyer email carried on the confirmation token, resolving or creating the user the payment belongs to. Ignored unless `confirmation_token` is provided, and when the token was created by a signed-in buyer.", "example": "dana@shinetime.example", "type": [ "string", "null" ] }, "member_id": { "description": "The member to charge, prefixed `mber_`. Required with `payment_method_id` unless `confirmation_token` is provided.", "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" ] }, "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" ] }, "plan_id": { "description": "The plan to charge for, prefixed `plan_`. It must belong to the account.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "promo_code_id": { "description": "An active promo code to apply, prefixed `promo_`. It must belong to the account and be valid for the plan.", "example": "promo_xxxxxxxxxxxxxx", "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. Ignored unless `confirmation_token` is provided.", "example": "https://shinetime.example/checkout/done", "type": [ "string", "null" ] } }, "required": [ "account_id", "plan_id" ], "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-mint": { "metadata": { "sidebarTitle": "Create" } } } }, "/payments/{id}": { "get": { "description": "Returns one payment. Related records are ids — resolve a plan, 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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment to retrieve, prefixed `pay_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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-mint": { "metadata": { "title": "Capture Payment", "sidebarTitle": "Capture Payment" } } } }, "/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": { "type": [ "string", "null" ] }, "has_next_page": { "example": false, "type": "boolean" }, "has_previous_page": { "example": false, "type": "boolean" }, "start_cursor": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List Fees" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The payment whose fees to list, prefixed `pay_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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": "Issues a full or partial refund for a payment. The refund is processed through the original payment processor and the membership status is updated accordingly.", "operationId": "refundPayment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "partial_amount": { "description": "The amount to refund. For multi-currency payments, this is in the charge currency (what the buyer paid). For single-currency, this is in the payment currency. If omitted, the full payment amount is refunded.", "example": 49, "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" ] } }, "/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": "Retries a failed or pending payment. This re-attempts the charge using the original payment method and plan details.", "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" ] } }, "/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 a payment that has not yet been settled. Voiding cancels the payment before it is captured by the payment processor.", "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" ] } }, "/payments/{payment_id}/resume": { "post": { "description": "Starts a fresh on-session attempt with the saved card for a subscription renewal that is waiting on the customer to authenticate; the bank's step then arrives in `next_action` on the following status reads. Only the payment's own customer may call it — with the payment's `client_secret` or their own session — and it is a no-op for any payment that is not a parked renewal.", "operationId": "resumePayment", "parameters": [ { "description": "The unique identifier of the payment.", "in": "path", "name": "payment_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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": [] } ], "summary": "Resume a parked renewal", "tags": [ "Payments" ], "x-mint": { "metadata": { "title": "Resume a Parked Renewal", "sidebarTitle": "Resume a Parked Renewal" } } } }, "/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`, 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": { "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": [] } ], "summary": "Update payment return URL", "tags": [ "Payments" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.payments.updateReturnURL('payment_id', {\n return_url: 'https://shinetime.example/checkout/thanks',\n});\n\nconsole.log(response.id);" } ], "x-mint": { "metadata": { "title": "Update Payment Return URL", "sidebarTitle": "Update Payment Return URL" } } } }, "/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`, 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" } } ], "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": [] } ], "summary": "Retrieve payment status", "tags": [ "Payments" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.payments.retrieveStatus('payment_id');\n\nconsole.log(response.id);" } ], "x-mint": { "metadata": { "title": "Retrieve Payment Status", "sidebarTitle": "Retrieve Payment Status" } } } }, "/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 payouts to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of payouts to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "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" }, "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 stablecoin payout 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 stablecoin payout 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": "Text that appears on the recipient's bank statement, or `null` if no descriptor was set. When set, 5-22 alphanumeric characters (A-Z, a-z, 0-9).", "example": "MYCOMPANY", "maxLength": 22, "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 stablecoin 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", "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const payoutListResponse of client.payouts.list()) {\n console.log(payoutListResponse.id);\n}" } ] }, "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, "currency": "usd", "notes": "Detailing supplies restock", "payout_method_id": "potk_xxxxxxxxxxxxxx", "speed": "standard" }, "required": [ "account_id" ] }, { "example": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 50, "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, "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" ] }, "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. Required when the ledger account's payout_quote_required is true; a payout without it is refused 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": "Text that appears on the recipient's bank statement. Must be 5-22 alphanumeric characters (A-Z, a-z, 0-9). 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": "MYCOMPANY", "maxLength": 22, "minLength": 5, "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" }, "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.", "format": "decimal", "type": [ "string", "null" ] }, "destination_currency": { "description": "Currency the funds are delivered in, taken from the payout method. On a stablecoin payout 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.", "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.", "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.", "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 stablecoin payout 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": "For a stablecoin payout, the id of the conversion request that funds it, prefixed `cofr_`; `null` on fiat 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": "instant", "type": "string" }, "statement_descriptor": { "description": "Text that appears on the recipient's bank statement, or `null` if no descriptor was set. When set, 5-22 alphanumeric characters (A-Z, a-z, 0-9).", "example": "MYCOMPANY", "maxLength": 22, "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 stablecoin 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.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "payout_request_id", "status", "status_detail", "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst payout = await client.payouts.create({ amount: 50, payout_method_id: 'potk_xxxxxxxxxxxxxx' });\n\nconsole.log(payout.id);" } ] } }, "/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, 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 payout methods to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of payout methods to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "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, "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, "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, "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, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount for this method, in the payout currency.", "example": 1, "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" ] }, "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.", "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, "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, "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", "supportability_check_payout_status_hold", "card_usage_review_payout_status_hold", "kyc_completed", "rmi_clear", "identity_rfi_clear", "ecommerce_fulfillment_connected", "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, "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": { "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const methodListResponse of client.payouts.methods.list()) {\n console.log(methodListResponse.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Saves a new place an account or user can pay out to. 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": true, "type": "boolean" }, "nickname": { "description": "A label for the payout method, unique per destination.", "example": "Personal checking", "type": "string" }, "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": "no_data", "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.", "type": [ "object", "null" ] }, "fee_structure": { "description": "Null on create. List payout methods to retrieve the configured fee terms.", "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.", "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.", "type": [ "object", "null" ] }, "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.", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst method = await client.payouts.methods.create({\n supported_payout_method_id: 'podst_xxxxxxxxxxxxxx',\n});\n\nconsole.log(method.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst method = await client.payouts.methods.delete('id');\n\nconsole.log(method.id);" } ] }, "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 or makes it the account's default payout method.", "operationId": "updatePayoutMethod", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "minProperties": 1, "properties": { "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": "no_data", "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.", "type": [ "object", "null" ] }, "fee_structure": { "description": "`null` after an update. List payout methods to retrieve the configured fee terms.", "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.", "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.", "type": [ "object", "null" ] }, "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.", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst method = await client.payouts.methods.update('id', { nickname: 'Primary checking' });\n\nconsole.log(method.id);" } ] } }, "/payouts/quotes": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a short-lived, provider-backed quote for a payout. No funds move until the returned quote_token is submitted to POST /payouts. An Idempotency-Key header is required.", "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.", "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" }, "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" }, "speed": { "default": "standard", "description": "How fast the funds should arrive.", "enum": [ "standard", "instant" ], "example": "standard", "type": "string" }, "statement_descriptor": { "description": "Text that appears on the recipient's bank statement. Must be 5-22 alphanumeric characters (A-Z, a-z, 0-9). Omit or pass `null` to use the default descriptor.", "example": "MYCOMPANY", "maxLength": 22, "minLength": 5, "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": [ "amount", "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" } }, "required": [ "object", "id", "amount", "fee", "net_amount", "destination_amount", "exchange_rate", "expires_at", "quote_token" ], "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-mint": { "metadata": { "sidebarTitle": "Create Quote" } } } }, "/payouts/supported_methods": { "get": { "description": "Lists the payout methods an account or user is eligible to add.", "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 supported payout methods to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of supported payout methods to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "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, "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, "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, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount, in the payout currency.", "example": 10, "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_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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const supportedMethodListResponse of client.payouts.supportedMethods.list()) {\n console.log(supportedMethodListResponse.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/payouts/{id}": { "get": { "description": "Fetches one payout by its `wdrl_` ID, or by the `cofr_` conversion request ID a stablecoin payout carries as `payout_request_id` — both ids answer with the same payout object.", "operationId": "retrievePayout", "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" } } ], "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" }, "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 stablecoin payout 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` or `cofr_` for a payout request returned by `POST /payouts`.", "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 stablecoin payout 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": "Text that appears on the recipient's bank statement, or `null` if no descriptor was set. When set, 5-22 alphanumeric characters (A-Z, a-z, 0-9).", "example": "MYCOMPANY", "maxLength": 22, "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 stablecoin 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", "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 found" }, "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:withdrawal:read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "payout not found" } }, "security": [ { "bearerAuth": [ "payout:withdrawal:read" ] } ], "summary": "Retrieve Payout", "tags": [ "Payouts" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst payout = await client.payouts.retrieve('id');\n\nconsole.log(payout.id);" } ] }, "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" } } ] }, "/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 that is still in review and returns the funds, fees included, to the balance. A payout can be canceled while its status is `in_review`. A `requested` payout is still being prepared (its funds may be converting) and answers 409 until it reaches review; from `processing` on, the money is on its way and the answer is 409 with error type `not_cancelable`. Canceling a payout that is already canceled succeeds and 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" }, "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 stablecoin payout 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.", "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` or `cofr_` for a payout request returned by `POST /payouts`.", "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 stablecoin payout 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": "Text that appears on the recipient's bank statement, or `null` if no descriptor was set. When set, 5-22 alphanumeric characters (A-Z, a-z, 0-9).", "example": "MYCOMPANY", "maxLength": 22, "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 stablecoin 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", "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" }, "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" ] } }, "/people": { "get": { "description": "Lists the people (visitors and customers) of an account: the identity-linked person profiles aggregated from every pixel, payment, and platform event — identities, purchases and LTV, geo/device profile, traffic sources, and first/last marketing touches.", "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": "With event_to plus an event or source filter, switches to exact-population mode: person ids are resolved and paginated on the events side within this window (the same query the people metric counts), then hydrated per page.", "in": "query", "name": "event_from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "The inclusive end of the event window for exact-population mode.", "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 whose most recent visit came 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": "The number of people to return (default 100, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor for fetching people after a previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "A cursor for fetching people before a later 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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const personListResponse of client.people.list()) {\n console.log(personListResponse.id);\n}" } ] } }, "/people/{id}": { "get": { "description": "Retrieves one person for an account. The identifier can be a person ID (prefixed `prsn_`), a user ID (prefixed `user_`), an email address, or a phone number — merged people resolve to the surviving profile.", "operationId": "retrievePerson", "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The person ID, user ID, email address, or phone number to look up.", "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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst person = await client.people.retrieve('id');\n\nconsole.log(person.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Check" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst permissions = await client.permissions.list({ resource_id: 'resource_id' });\n\nconsole.log(permissions.data);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/plans": { "get": { "description": "Returns a paginated list of plans. Omit `account_id` and pass `product_ids` to list a product's public buyable plans.", "operationId": "listPlans", "parameters": [ { "description": "The unique identifier of the account to list plans for. Required unless `product_ids` is provided for a public product-plan 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 plans matching these release methods.", "in": "query", "name": "release_methods", "required": false, "schema": { "items": { "example": "buy_now", "type": "string" }, "type": "array" } }, { "description": "Filter to only plans matching these visibility states.", "in": "query", "name": "visibilities", "required": false, "schema": { "items": { "example": "visible", "type": "string" }, "type": "array" } }, { "description": "Filter to only plans matching these billing types.", "in": "query", "name": "plan_types", "required": false, "schema": { "items": { "example": "renewal", "type": "string" }, "type": "array" } }, { "description": "Filter to only plans belonging to these product identifiers. When `account_id` is omitted, this is required and the response is publicly readable: only visible, non-invoice plans are returned.", "in": "query", "name": "product_ids", "required": false, "schema": { "items": { "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" } }, { "description": "Only return plans created before this timestamp.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Only return plans created after this timestamp.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "The number of plans to return (default and max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns plans after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of plans to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns plans before this position.", "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": { "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 plans 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 Plans", "tags": [ "Plans" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const planListResponse of client.plans.list({ account_id: 'account_id' })) {\n console.log(planListResponse.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Create a new pricing plan for a product. The plan defines the billing interval, price, and availability for customers.", "operationId": "createPlan", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The unique identifier of the account to create this plan 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 plan accepts local currency payments via adaptive pricing.", "example": true, "type": [ "boolean", "null" ] }, "billing_period": { "description": "Recurring billing interval in days, such as 30 for monthly or 365 for annual.", "example": 30, "type": [ "integer", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this plan.", "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 plan'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 plan 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 plan.", "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 plan's currency, e.g. 10.43 for $10.43. A paid fiat plan 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 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` (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 plan 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" ] }, "override_tax_type": { "description": "Override the default tax classification for this specific plan.", "example": "inclusive", "type": "string" }, "payment_method_configuration": { "description": "Explicit payment method configuration for the plan. When not provided, the account's defaults apply.", "properties": { "disabled": { "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "plan_type": { "description": "Plan billing type, such as `one_time` or `renewal`.", "example": "renewal", "type": "string" }, "product_id": { "description": "The unique identifier of the product to attach this plan to.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this plan.", "example": "buy_now", "type": "string" }, "renewal_price": { "description": "The amount charged each billing period for recurring plans, in the plan's currency. A paid fiat plan charges at least 1.00 in its currency.", "example": 59, "type": [ "number", "null" ] }, "split_pay_required_payments": { "description": "Installment payments required before the subscription pauses.", "example": 4, "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 this plan. Send `null` to inherit the account default.", "enum": [ "mandate_challenge", "frictionless" ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "The display name of the plan shown to customers on the product page.", "example": "Unlimited Wash Club", "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 plan has unlimited stock. When true, the stock field is ignored.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the plan 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/Plan" } } }, "description": "plan 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 Plan", "tags": [ "Plans" ], "x-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst plan = await client.plans.create();\n\nconsole.log(plan.id);" } ] } }, "/plans/{id}": { "delete": { "description": "Permanently delete a plan from a product. Existing memberships on this plan will not be affected.", "operationId": "deletePlan", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "Always true.", "example": true, "type": "boolean" }, "id": { "description": "ID of the deleted plan.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "plan deleted" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no plan with that id" } }, "security": [ { "bearerAuth": [ "plan:delete" ] } ], "summary": "Delete Plan", "tags": [ "Plans" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst plan = await client.plans.delete('id');\n\nconsole.log(plan.id);" } ] }, "get": { "description": "Retrieves the details of an existing plan.", "operationId": "retrievePlan", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "plan retrieved" }, "404": { "$ref": "#/components/responses/NotFound", "description": "no plan with that id" } }, "security": [ {}, { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "Retrieve Plan", "tags": [ "Plans" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst plan = await client.plans.retrieve('id');\n\nconsole.log(plan.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Plan ID, prefixed `plan_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Update a plan's pricing, billing interval, visibility, stock, and other settings.", "operationId": "updatePlan", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "adaptive_pricing_enabled": { "description": "Whether this plan accepts local currency payments via adaptive pricing.", "example": true, "type": [ "boolean", "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 many renewals the retention discount applies to. Required when `offer_cancel_discount` is true.", "example": 3, "type": [ "integer", "null" ] }, "cancel_discount_percentage": { "description": "Percentage taken off each discounted renewal. Required when `offer_cancel_discount` is true.", "example": 20, "type": [ "integer", "null" ] }, "checkout_styling": { "description": "Checkout styling overrides for this plan.", "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 plan'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 plan 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 plan.", "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 plan's currency, e.g. 10.43 for $10.43. A paid fiat plan 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 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` (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 plan 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 plan.", "example": "inclusive", "type": "string" }, "payment_method_configuration": { "description": "Explicit payment method configuration for the plan. When not provided, the account's defaults apply.", "properties": { "disabled": { "items": { "example": "paypal", "type": "string" }, "type": "array" }, "enabled": { "items": { "example": "card", "type": "string" }, "type": "array" }, "include_platform_defaults": { "example": true, "type": "boolean" } }, "type": [ "object", "null" ] }, "release_method": { "description": "Sales method for this plan.", "example": "buy_now", "type": "string" }, "renewal_price": { "description": "The amount charged each billing period for recurring plans, in the plan's currency. A paid fiat plan charges at least 1.00 in its currency.", "example": 59, "type": [ "number", "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 this plan. Send `null` to inherit the account default.", "enum": [ "mandate_challenge", "frictionless" ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "The display name of the plan shown to customers on the product page.", "example": "Unlimited Wash Club", "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 plan has unlimited stock. When true, the stock field is ignored.", "example": false, "type": [ "boolean", "null" ] }, "visibility": { "description": "Whether the plan 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/Plan" } } }, "description": "plan updated" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" } }, "security": [ { "bearerAuth": [ "plan:update" ] } ], "summary": "Update Plan", "tags": [ "Plans" ], "x-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst plan = await client.plans.update('id');\n\nconsole.log(plan.id);" } ] } }, "/plans/{id}/calculate_tax": { "parameters": [ { "description": "Plan ID, prefixed `plan_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Previews tax for a plan before checkout, based on the buyer's location.", "operationId": "calculatePlanTax", "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": "Plan 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 plan 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 plan read scope" }, "404": { "$ref": "#/components/responses/NotFound", "description": "plan not found" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "plan:basic:read" ] } ], "summary": "Calculate Tax", "tags": [ "Plans" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.plans.calculateTax('id');\n\nconsole.log(response.currency);" } ] } }, "/products": { "get": { "description": "Returns a paginated list of products. Omit `account_id` to search the public marketplace.", "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": "Ranked search against product title and headline. 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 plan of these billing models, such as `one_time` or `renewal`.", "in": "query", "name": "plan_types", "required": false, "schema": { "items": { "enum": [ "renewal", "one_time" ], "type": "string" }, "type": "array" } }, { "description": "Only return products whose advertised buyable plan has a displayed price of at least this amount. Recurring plans use renewal price.", "in": "query", "name": "price_minimum", "required": false, "schema": { "type": "number" } }, { "description": "Only return products whose advertised buyable plan has a displayed price of at most this amount. Recurring plans 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": "The number of products to return (default and max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns products after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of products to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns products before this position.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const productListItem of client.products.list({ account_id: 'account_id' })) {\n console.log(productListItem.id);\n}" } ] }, "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.", "example": "Full interior extraction, leather conditioning, and an ozone odor treatment.", "type": [ "string", "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.", "example": "Steam, shampoo, and odor removal in one visit", "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", "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst product = await client.products.create({ title: 'Interior Deep Clean' });\n\nconsole.log(product.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst product = await client.products.delete('id');\n\nconsole.log(product.id);" } ] }, "get": { "description": "Retrieves a product. Public — no credentials.", "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst product = await client.products.retrieve('id');\n\nconsole.log(product.id);" } ] }, "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.", "example": "Full interior extraction, leather conditioning, and an ozone odor treatment.", "type": [ "string", "null" ] }, "headline": { "description": "A short marketing headline for the product page.", "example": "Steam, shampoo, and odor removal in one visit", "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.", "example": "Interior Deep Clean", "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst product = await client.products.update('id');\n\nconsole.log(product.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst product = await client.products.publish('id');\n\nconsole.log(product.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst product = await client.products.unpublish('id');\n\nconsole.log(product.id);" } ] } }, "/promo_codes": { "get": { "description": "Lists promo codes for an account with cursor pagination, filters, and sorting.", "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 plan IDs.", "in": "query", "name": "plan_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 promo codes to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate forwards from.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of promo codes to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const promoCodeListResponse of client.promoCodes.list({ account_id: 'account_id' })) {\n console.log(promoCodeListResponse.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates a promo code for an account. First-party sessions may attach an affiliate.", "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" }, "plan_ids": { "items": { "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "type": "array" }, "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" } }, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst promoCode = await client.promoCodes.create({\n account_id: 'biz_xxxxxxxxxxxxxx',\n amount_off: 25,\n base_currency: 'usd',\n code: 'AFFILIATE25',\n new_users_only: true,\n promo_duration_months: 3,\n promo_type: 'percentage',\n});\n\nconsole.log(promoCode.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst promoCode = await client.promoCodes.delete('id');\n\nconsole.log(promoCode.id);" } ] }, "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst promoCode = await client.promoCodes.retrieve('id');\n\nconsole.log(promoCode.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Promo code ID (`promo_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst promoCode = await client.promoCodes.activate('id');\n\nconsole.log(promoCode.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst promoCode = await client.promoCodes.deactivate('id');\n\nconsole.log(promoCode.id);" } ] } }, "/recommended_actions": { "get": { "description": "Lists the recommended action chains for an account — short sequences of actions (create a product, price it, publish it) the account should run next, gated on what it already has.", "operationId": "listRecommendedActions", "parameters": [ { "description": "Account ID, prefixed `biz_`. Defaults to the API key's own account.", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AccountRecommendedActionChain" }, "type": "array" }, "generation_pending": { "description": "Whether generation was queued because the account has no available action chains yet.", "example": false, "type": "boolean" } }, "required": [ "data", "generation_pending" ], "type": "object" } } }, "description": "defaults to the API key's own account" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "account not visible to the credential" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "List Action Chains", "tags": [ "Recommended Actions" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst recommendedActions = await client.recommendedActions.list();\n\nconsole.log(recommendedActions.data);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/recommended_actions/{id}": { "get": { "description": "Retrieves a recommended action chain by id, including chains that have already been run. Seeded chains are reconstructed from their hard-coded chain; generated chains are read from the account's stored chain, with each step's filled-in input.", "operationId": "retrieveRecommendedAction", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRecommendedActionChain" } } }, "description": "generated chain retrieved" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown chain" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "Retrieve Action Chain", "tags": [ "Recommended Actions" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst recommendedAction = await client.recommendedActions.retrieve('id');\n\nconsole.log(recommendedAction.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Chain ID from the list endpoint, e.g. `rac_seed_start_selling_9f2c1a7b04`.", "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" } } ], "post": { "description": "Records that the caller ran a recommended action chain. Nothing is executed server-side yet — the client follows the chain's step CTAs itself; this writes the `recommended_action_chain.executed` analytics event and a `redirected` execution per step.", "operationId": "runRecommendedAction", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "chain_id": { "example": "rac_chain_xxxxxxxxxxxx", "type": "string" }, "execution": { "enum": [ "redirect", "executed" ], "example": "redirect", "type": "string" } }, "required": [ "chain_id", "execution" ], "type": "object" } } }, "description": "run recorded" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown chain" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "Execute Action Chain", "tags": [ "Recommended Actions" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.recommendedActions.run('id');\n\nconsole.log(response.chain_id);" } ] } }, "/recommended_actions/{id}/executions": { "get": { "description": "Lists the per-step record of a recommended action chain the server ran — one entry per step in position order, each carrying its current status and, once the step completed, the API response it produced. A chain that was never run server-side returns an empty list.", "operationId": "listRecommendedActionExecutions", "parameters": [ { "description": "Chain ID from the list endpoint.", "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" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "chain_id": { "description": "The chain these executions belong to.", "example": "rac_chain_xxxxxxxxxxxx", "type": "string" }, "executions": { "description": "One entry per run step, in position order.", "items": { "$ref": "#/components/schemas/RecommendedActionExecution" }, "type": "array" } }, "required": [ "chain_id", "executions" ], "type": "object" } } }, "description": "executions listed" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "missing or invalid authentication" }, "404": { "$ref": "#/components/responses/NotFound", "description": "unknown chain" } }, "security": [ { "bearerAuth": [ "company:basic:read" ] } ], "summary": "List Recommended Action Executions", "tags": [ "Recommended Actions" ], "x-mint": { "metadata": { "sidebarTitle": "List Executions" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.recommendedActions.listExecutions('id');\n\nconsole.log(response.chain_id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/refunds": { "get": { "description": "Lists refunds, newest first. Without filters this is every refund the caller can read; narrow it to one payment with `payment_id`, one account with `account_id`, or one buyer with `user_id`.", "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": "The number of refunds to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns refunds after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of refunds to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns refunds before this position.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The refund to retrieve, prefixed `rf_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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": "The number of cases to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns cases after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of cases to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns cases before this position.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const resolutionCenterCaseListResponse of client.resolutionCenterCases.list()) {\n console.log(resolutionCenterCaseListResponse.id);\n}" } ] }, "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst resolutionCenterCase = await client.resolutionCenterCases.create({\n message: 'The mobile detailer never showed up for the Ceramic Coating appointment.',\n reason: 'product_not_received',\n receipt_id: 'pay_xxxxxxxxxxxxxx',\n});\n\nconsole.log(resolutionCenterCase.id);" } ] } }, "/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-mint": { "metadata": { "sidebarTitle": "Retrieve Summary" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.resolutionCenterCases.summary();\n\nconsole.log(response.groups);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst resolutionCenterCase = await client.resolutionCenterCases.retrieve('id');\n\nconsole.log(resolutionCenterCase.id);" } ] }, "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.resolutionCenterCases.accept('id');\n\nconsole.log(response.id);" } ] } }, "/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.", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.resolutionCenterCases.appeal('id', {\n message: 'The coating is already flaking on the hood two weeks later.',\n});\n\nconsole.log(response.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.resolutionCenterCases.deny('id', {\n message: 'The ceramic coating was applied and the vehicle was collected on 2026-01-05.',\n});\n\nconsole.log(response.id);" } ] } }, "/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": "The number of events to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns events after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of events to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns events before this position.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List Events" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.resolutionCenterCases.events('id');\n\nconsole.log(response.data);" } ] }, "parameters": [ { "description": "The resolution center case ID (`reso_` tag).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.resolutionCenterCases.reply('id', {\n message: 'Here are the before and after photos from the Burnet Rd bay.',\n});\n\nconsole.log(response.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.resolutionCenterCases.requestInfo('id');\n\nconsole.log(response.id);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.resolutionCenterCases.withdraw('id');\n\nconsole.log(response.id);" } ] } }, "/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`, 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": { "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": [] } ], "summary": "Update setup return URL", "tags": [ "Setup Intents" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.setupIntents.updateReturnURL('setup_intent_id', {\n return_url: 'https://shinetime.example/checkout/thanks',\n});\n\nconsole.log(response.id);" } ], "x-mint": { "metadata": { "title": "Update Setup Return URL", "sidebarTitle": "Update Setup Return URL" } } } }, "/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`, 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" } } ], "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": [] } ], "summary": "Retrieve setup status", "tags": [ "Setup Intents" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.setupIntents.retrieveStatus('setup_intent_id');\n\nconsole.log(response.id);" } ], "x-mint": { "metadata": { "title": "Retrieve Setup Status", "sidebarTitle": "Retrieve Setup Status" } } } }, "/shipments": { "get": { "description": "Returns a paginated list of shipments for an account.", "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": "The number of shipments to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns shipments after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of shipments to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns shipments before this position.", "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": { "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const shipment of client.shipments.list()) {\n console.log(shipment.id);\n}" } ] }, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst shipment = await client.shipments.create({\n payment_id: 'pay_xxxxxxxxxxxxxx',\n tracking_number: '1Z999AA10123456784',\n});\n\nconsole.log(shipment.id);" } ] } }, "/shipments/{id}": { "get": { "description": "Retrieves a shipment by its id, or by the payment id 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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst shipment = await client.shipments.retrieve('id');\n\nconsole.log(shipment.id);" } ] }, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst shipment = await client.shipments.update('id', { tracking_number: '9400111899223456789012' });\n\nconsole.log(shipment.id);" } ] } }, "/social_accounts": { "get": { "description": "Lists the social accounts linked to an account or user.", "operationId": "listSocialAccounts", "parameters": [ { "description": "The Account that the social 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 social accounts are connected to. Provide either this or account_id.", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return social accounts for the platform that is specified.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram" ], "type": "string" } }, { "description": "Only return social accounts that are verified on the platform.", "in": "query", "name": "verified", "required": false, "schema": { "type": "boolean" } }, { "description": "Only return social accounts that have these scopes.", "in": "query", "name": "scopes", "required": false, "schema": { "items": { "enum": [ "advertise" ], "type": "string" }, "type": "array" } }, { "description": "The number of social accounts to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of social accounts to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "description": "The field to sort social 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": { "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 Social Accounts", "tags": [ "Social Accounts" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const socialAccount of client.socialAccounts.list()) {\n console.log(socialAccount.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Creates or returns a Whop-managed Facebook page or TikTok account for an account.", "operationId": "createSocialAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) to create the social 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" }, "platform": { "description": "The platform to create the social 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.", "enum": [ "facebook", "tiktok" ], "example": "facebook", "type": "string" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialAccount" } } }, "description": "social 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 a Social Account", "tags": [ "Social Accounts" ], "x-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst socialAccount = await client.socialAccounts.create({ platform: 'facebook' });\n\nconsole.log(socialAccount.id);" } ] } }, "/social_accounts/connect": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Starts an OAuth connection flow and returns an authorize_url where the user can connect a social account.", "operationId": "connectSocialAccount", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "The Account (biz_ identifier) to connect the social account for. An account-scoped API key may omit this to default to its own account.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "platform": { "description": "The platform to connect the social 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.", "enum": [ "meta_business", "tiktok" ], "example": "meta_business", "type": "string" }, "redirect_url": { "description": "Where to send the user once they finish connecting their accounts. Any `http` or `https` URL. If the connection fails, the user is redirected with a `social_account_error` query param.", "example": "https://example.com/settings/social-accounts", "type": "string" }, "scopes": { "description": "Capabilities to grant for the connected social account. `advertise` is required for both `meta_business` and `tiktok` connections — it is not conditional on whether you intend to run ads, and omitting it fails the request.", "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 a Social Account", "tags": [ "Social Accounts" ], "x-mint": { "metadata": { "sidebarTitle": "Connect" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.socialAccounts.connect({ platform: 'meta_business' });\n\nconsole.log(response.authorize_url);" } ] } }, "/social_accounts/{id}": { "delete": { "description": "Disconnects a social account from an account or user without deleting the underlying platform account.", "operationId": "deleteSocialAccount", "parameters": [ { "description": "The Account that the social 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 social 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 social account.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "user social 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 social account is the parent of others that are still connected" } }, "security": [ { "bearerAuth": [ "social_account:delete" ] } ], "summary": "Delete a Social Account", "tags": [ "Social Accounts" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst socialAccount = await client.socialAccounts.delete('id');\n\nconsole.log(socialAccount.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The ID of the social account to disconnect.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/social_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": "listSocialAccountLeadForms", "parameters": [ { "description": "The Account (a biz_ identifier) the social 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/SocialAccountLeadForm" }, "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": "social account is not linked to the account" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Account Lead Forms", "tags": [ "Social Accounts" ], "x-mint": { "metadata": { "sidebarTitle": "List Lead Forms" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.socialAccounts.leadForms('id', { account_id: 'account_id' });\n\nconsole.log(response.data);" } ] }, "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" } } ] }, "/social_accounts/{id}/posts": { "get": { "description": "Lists the existing posts of a connected Facebook page, Instagram account, or TikTok account.", "operationId": "listSocialAccountPosts", "parameters": [ { "description": "The Account (a biz_ identifier) the social 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": "The number of posts to return.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "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": "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": "social account is not linked to the account" } }, "security": [ { "bearerAuth": [ "social_account:read" ] } ], "summary": "List Social Account Posts", "tags": [ "Social Accounts" ], "x-mint": { "metadata": { "sidebarTitle": "List Posts" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.socialAccounts.posts('id', { account_id: 'account_id' });\n\nconsole.log(response.data);" } ] }, "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" } } ] }, "/stats": { "get": { "description": "Lists every metric you can query, with its unit and the properties you can filter or break it down by.", "operationId": "listMetrics", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "The available metrics.", "items": { "properties": { "description": { "description": "A short description of what the metric measures.", "example": "Share of paid receipts in the selected sales cohort disputed within 14 days of purchase.", "type": "string" }, "key": { "description": "The metric's key. Pass it to GET /stats/{metric} to query its values.", "example": "snapshot_cohorted_dispute_rate_14d_attr", "type": "string" }, "name": { "description": "Human-readable display name for the metric.", "example": "Cohorted dispute rate (14-day attribution)", "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": "percent", "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 Metrics", "tags": [ "Stats" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst stats = await client.stats.list();\n\nconsole.log(stats.data);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/stats/{metric}": { "get": { "description": "Retrieves a metric as a time series of points for an account or user over a time range. The `market_prices` metric is public and requires no authentication.", "operationId": "retrieveMetric", "parameters": [ { "description": "The account this query concerns, for example biz_AbC123.", "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.", "in": "query", "name": "to", "required": true, "schema": { "type": "string" } }, { "description": "How wide each point is. Defaults to day. Snapshot metrics are day-only.", "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.", "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. 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. Each metric lists its accepted values in the catalog.", "in": "query", "name": "snapshot_window", "required": false, "schema": { "enum": [ "7d", "28d", "30d" ], "type": "string" } }, { "description": "Filter the events metric to one or more full event names, for example payment.completed or pixel.lead. Comma-separate several to break the metric down by each event. Available on metrics that list event.", "in": "query", "name": "event", "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" }, "value": { "description": "The metric's value for this entry.", "example": 2.82, "nullable": true, "type": "number" } }, "required": [ "name", "value" ], "type": "object" }, "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.", "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 unique-people counts exist only at window level.", "items": { "properties": { "name": { "description": "The property value this total is for, or the metric's name when it isn't split by a property.", "example": "spend", "type": "string" }, "value": { "description": "The metric's whole-window value for this entry.", "example": 2.82, "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", "tags": [ "Stats" ], "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst stat = await client.stats.retrieve('metric', { from: 'from', to: 'to' });\n\nconsole.log(stat.data);" } ] }, "parameters": [ { "description": "The metric to retrieve, for example net_revenue. Use GET /stats 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" } ] }, "/swaps": { "get": { "description": "Retrieve the account's completed or pending swaps — currently just the latest one.", "operationId": "listSwaps", "parameters": [ { "description": "Business or user account ID (biz_* / user_*).", "in": "query", "name": "account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Swaps returned for this account.", "items": { "properties": { "account_id": { "description": "Account ID that owns the wallet used for the swap.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "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" } }, "required": [ "object", "id", "account_id", "status", "tx_hashes" ], "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst swaps = await client.swaps.list({ account_id: 'account_id' });\n\nconsole.log(swaps.data);" } ] }, "post": { "description": "Swaps one token for another from the account's wallet, or converts between fiat currencies in the account's ledger at the mid-market rate. Crypto swaps finish in the background — check the swap for its status.", "operationId": "createSwap", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Business or user account ID (biz_* / user_*).", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "amount": { "description": "Source token amount. Required for crypto swaps. 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" } }, "required": [ "account_id", "from_token", "to_token" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "account_id": { "description": "Account ID that owns the wallet used for the swap.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "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, "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" ] } }, "required": [ "object", "account_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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst swap = await client.swaps.create({\n account_id: 'biz_xxxxxxxxxxxxxx',\n from_token: 'usd',\n to_token: 'cad',\n});\n\nconsole.log(swap.account_id);" } ] } }, "/swaps/quote": { "post": { "description": "Previews the price of a swap. Fiat pairs quote the in-ledger mid-market conversion — the same rate creating the swap fills at. No funds move and nothing is saved.", "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-mint": { "metadata": { "sidebarTitle": "Create Quote" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst response = await client.swaps.createQuote({\n amount: '100',\n from_token: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',\n to_token: '0x1b64b9025eebb9a6239575df9ea4b9ac46d4d193',\n});\n\nconsole.log(response.bridge_fee);" } ] } }, "/swaps/{id}": { "get": { "description": "Retrieves a single swap and its status.", "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 ID that owns the wallet used for the swap.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "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" } }, "required": [ "object", "id", "account_id", "status", "tx_hashes" ], "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst swap = await client.swaps.retrieve('id');\n\nconsole.log(swap.id);" } ] } }, "/team_members": { "get": { "description": "Lists an account's team members, including pending invites (`status: \"pending\"`, `ausri_` ids; `user` is `null` for invites sent to an email with no Whop account yet). For accepted members, `email` requires the `company:authorized_user:email:read` scope and is `null` otherwise. Listing `role=workforce` is also allowed with the `bounty:create` scope.", "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", "sales_manager", "moderator", "advertiser", "app_manager", "support", "manager", "workforce", "custom" ], "type": "string" } }, { "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.", "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 members to return. Defaults to 20; maximum 100.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "Cursor for the next page of members.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of members to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 100, "type": "integer" } }, { "description": "Cursor to paginate backwards from.", "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": { "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": "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" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const teamMember of client.teamMembers.list({ account_id: 'account_id' })) {\n console.log(teamMember.id);\n}" } ] }, "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 `{ \"object\": \"team_member_invite\", \"invitation_sent\": true }`. If they already have a pending invite, the request fails with a `400`. Custom roles cannot be granted via the API. Granting the `workforce` role is also allowed with the `bounty:create` scope.", "operationId": "createTeamMember", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "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.", "enum": [ "owner", "admin", "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" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }, "description": "Team member created." }, "202": { "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": "Invitation sent — the user must accept before they join the team." }, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst teamMember = await client.teamMembers.create({\n account_id: 'biz_xxxxxxxxxxxxxx',\n role: 'sales_manager',\n});\n\nconsole.log(teamMember.id);" } ] } }, "/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" ] } ], "summary": "Delete Team Member", "tags": [ "Team Members" ], "x-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst teamMember = await client.teamMembers.delete('id');\n\nconsole.log(teamMember.success);" } ] }, "get": { "description": "Retrieves a team member by ID. `email` requires the `company:authorized_user:email:read` scope and is `null` otherwise.", "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst teamMember = await client.teamMembers.retrieve('id');\n\nconsole.log(teamMember.id);" } ] }, "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.", "enum": [ "owner", "admin", "sales_manager", "moderator", "advertiser", "workforce" ], "example": "workforce", "type": "string" } }, "required": [ "role" ], "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst teamMember = await client.teamMembers.update('id', { role: 'workforce' });\n\nconsole.log(teamMember.id);" } ] } }, "/transfers": { "get": { "description": "Lists an account's transfers.", "operationId": "listTransfer", "parameters": [ { "description": "Filter to transfers sent from this account. Provide this or destination_id.", "in": "query", "name": "origin_id", "required": false, "schema": { "type": "string" } }, { "description": "Filter to transfers received by this account. Provide this or origin_id.", "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 transfers to return from the start of the window.", "in": "query", "name": "first", "required": false, "schema": { "default": 50, "maximum": 50, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Number of transfers to return from the end of the window.", "in": "query", "name": "last", "required": false, "schema": { "maximum": 50, "type": "integer" } }, { "description": "Cursor to fetch the page before (from page_info.start_cursor).", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "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", "null" ] }, "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_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user" ], "title": "TransferListItem", "type": "object" }, "type": "array" }, "page_info": { "properties": { "end_cursor": { "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" }, "400": { "$ref": "#/components/responses/InvalidParameters", "description": "neither origin_id nor destination_id given" } }, "security": [ { "bearerAuth": [ "payout:transfer:read" ] } ], "summary": "List Transfers", "tags": [ "Transfers" ], "x-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const transferListResponse of client.transfers.list()) {\n console.log(transferListResponse.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Moves money between accounts, or into a claim link anyone with the URL can redeem.", "operationId": "createTransfer", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "The amount to move, in the transfer currency. For example 25.00.", "example": 25, "type": "number" }, "currency": { "description": "Currency, such as `usd`. Required for ledger transfers.", "example": "usd", "type": "string" }, "destination_id": { "description": "The recipient. Required for ledger and wallet_send (a user_/biz_/ldgr_ ID, or — for sends — an email). Omit for claim_link.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "expires_at": { "description": "claim_link only. 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" ] }, "feed_id": { "description": "Ledger transfers only. 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": "Ledger transfers only. 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": "Ledger transfers and wallet sends. A unique key that makes retries safe. Retrying with the same key returns the original transfer, or attaches to the original wallet send, instead of moving money twice.", "example": "shine-supplies-restock-118", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": true, "description": "Ledger transfers only. 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": "Ledger transfers only. 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" }, "redeemable_count": { "description": "claim_link only. How many different users can claim the link. Defaults to 1.", "example": 3, "type": "integer" }, "type": { "description": "The kind of money movement, which decides what comes back. Defaults to ledger. `ledger` moves credit between two Whop balances and returns a `transfer`; `wallet_send` sends USDT from the origin account's Ethereum wallet and returns a `send`; `claim_link` funds a shareable link anyone with the URL can redeem and returns a `claim_link`. A `ledger` transfer from a stablecoin-rails account settles on-chain when covered, and still returns a `transfer`.", "enum": [ "ledger", "wallet_send", "claim_link" ], "example": "wallet_send", "type": "string" } }, "required": [ "origin_id", "amount" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "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", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "title": "Transfer", "type": "object" }, { "description": "Returned for a wallet_send: an onchain USDT send to a recipient.", "properties": { "amount": { "example": "25.00", "type": "string" }, "currency": { "example": "usdt", "type": "string" }, "destination": { "properties": { "account_id": { "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "address": { "example": "0x9d2e4b6a806f1c0a3d5b2e4f8a9c7d1e0b3a5f7c", "type": "string" } }, "required": [ "account_id", "address" ], "type": "object" }, "object": { "enum": [ "send" ], "example": "send", "type": "string" }, "source": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "address": { "example": "0x6f1c0a3d5b2e4f8a9c7d1e0b3a5f7c9d2e4b6a80", "type": "string" } }, "required": [ "account_id", "address" ], "type": "object" }, "tx_hash": { "example": "0x4a7d1ed414474e4033ac29ccb8653d9bd1d3f0b2c9b0f7a4d6e8c0a2b4d6f8a0", "type": "string" } }, "required": [ "object", "tx_hash", "amount", "currency", "source", "destination" ], "title": "Send", "type": "object" }, { "description": "Returned for a claim_link: a shareable URL anyone can open to claim the funds.", "properties": { "amount": { "example": "25.00", "type": "string" }, "claim_url": { "example": "https://whop.com/claim", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "expires_at": { "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "example": "airdrp_xxxxxxxxxxxxxx", "type": "string" }, "object": { "enum": [ "claim_link" ], "example": "claim_link", "type": "string" }, "redeemable_count": { "example": 3, "type": "integer" }, "source": { "properties": { "account_id": { "example": "biz_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "account_id" ], "type": "object" }, "status": { "description": "A newly funded claim link is always `pending` — it stays claimable until it is fully claimed, canceled, or expires.", "enum": [ "pending" ], "example": "pending", "type": "string" } }, "required": [ "object", "id", "claim_url", "status", "amount", "currency", "redeemable_count", "expires_at", "source" ], "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst transfer = await client.transfers.create({ amount: 25, origin_id: 'biz_xxxxxxxxxxxxxx' });\n\nconsole.log(transfer);" } ] } }, "/transfers/recipients": { "get": { "description": "Lists the people and accounts you can send money to.", "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_`) returns that business first. 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.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Number of recipients per page. Search queries preserve the dashboard's 20-result maximum.", "in": "query", "name": "first", "required": false, "schema": { "default": 20, "maximum": 100, "type": "integer" } }, { "description": "Cursor to fetch the page after (from page_info.end_cursor).", "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": { "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-mint": { "metadata": { "sidebarTitle": "List Recipients" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const transferListRecipientsResponse of client.transfers.listRecipients({\n origin_id: 'origin_id',\n})) {\n console.log(transferListRecipientsResponse);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/transfers/{id}": { "get": { "description": "Retrieves a single transfer.", "operationId": "retrieveTransfer", "responses": { "200": { "content": { "application/json": { "schema": { "description": "A transfer of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "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", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst transfer = await client.transfers.retrieve('id');\n\nconsole.log(transfer.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "The transfer ID.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/users": { "get": { "description": "Search for users by name or username, ranked by social proximity to the authenticated user. Returns the user's most recently followed users when no query is given.", "operationId": "listUsers", "parameters": [ { "description": "A search term to filter users by name or username.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "The number of users to return (max 50).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns users after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of users to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns users before this position.", "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": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const user of client.users.list()) {\n console.log(user.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/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. The list is always the caller's own; there is no parameter for reading 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": "The number of grants to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns grants after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of grants to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns grants before this position.", "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": { "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-docs-subgroup": "OAuth Grants", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const oauthGrant of client.users.oauthGrants.list()) {\n console.log(oauthGrant.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Completes the OAuth authorization step for the authenticated user: records their consent for the scopes an app asked for and mints the authorization code to hand back to it. Returns the grant, plus a `redirect_url` carrying that code — the one and only time it is returned. Exchange the code at `POST /oauth/token` with the verifier for `code_challenge`. 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` to make a retry safe — a replay returns the original `redirect_url` and its code rather than 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.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" }, "code_challenge_method": { "description": "How `code_challenge` was derived. Only `S256` is accepted.", "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.", "example": true, "type": "boolean" }, "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", "code_challenge", "code_challenge_method" ], "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-docs-subgroup": "OAuth Grants", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst oauthGrant = await client.users.oauthGrants.create({\n client_id: 'app_xxxxxxxxxxxxxx',\n code_challenge: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',\n code_challenge_method: 'S256',\n redirect_uri: 'https://Booking.Shinetime.example:8443/oauth/Callback/',\n requested_scopes: ['profile'],\n});\n\nconsole.log(oauthGrant.id);" } ] } }, "/users/me/passkeys": { "get": { "description": "Lists the authenticated user's own passkeys, newest first. The list is always the caller's own; there is no parameter for reading 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": "The number of passkeys to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns passkeys after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of passkeys to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns passkeys before this position.", "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-docs-subgroup": "Passkeys", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const passkey of client.users.passkeys.list()) {\n console.log(passkey.id);\n}" } ] }, "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`; it is single-use and expires 5 minutes after it is issued. Requires a user session.", "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" } }, "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-docs-subgroup": "Passkeys", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst passkey = await client.users.passkeys.create({\n attestation_object: 'YXR0ZXN0YXRpb24',\n client_data_json: 'Y2xpZW50LWRhdGE',\n credential_id: 'bmV3LWNyZWRlbnRpYWw',\n nickname: 'Work laptop',\n});\n\nconsole.log(passkey.id);" } ] } }, "/users/me/passkeys/challenge": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "post": { "description": "Mints the challenge a browser needs to run a WebAuthn 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. 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.", "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": "registration", "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": { "properties": { "challenge": { "description": "The challenge to pass to the WebAuthn ceremony, base64url-encoded without padding.", "example": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" } }, "required": [ "challenge" ], "type": "object" } } }, "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-docs-subgroup": "Passkeys", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.users.passkeys.challenge({ challenge_type: 'registration' });\n\nconsole.log(response.challenge);" } ] } }, "/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-docs-subgroup": "Passkeys", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst passkey = await client.users.passkeys.delete('id', {\n authenticator_data: 'YXV0aGVudGljYXRvci1kYXRh',\n client_data_json: 'Y2xpZW50LWRhdGE',\n signature: 'c2lnbmF0dXJl',\n});\n\nconsole.log(passkey.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Passkey ID, prefixed `wcred_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/users/me/preferences": { "get": { "description": "Retrieves the authenticated user's settings document. Addressed only as `me` — the document always belongs to the session user.", "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-docs-subgroup": "Preferences", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst preference = await client.users.preferences.retrieve();\n\nconsole.log(preference.bounty_worker_onboarding_dismissed);" } ] }, "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" }, "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-docs-subgroup": "Preferences", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst preference = await client.users.preferences.update();\n\nconsole.log(preference.bounty_worker_onboarding_dismissed);" } ] } }, "/users/me/preferences/notifications": { "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Sets the authenticated user's notification preferences. Each preference is addressed by `scope`, not by id, so a scope read back from either list endpoint can be sent straight here.\n\nA scope naming an experience with no topic sets that experience's level, and accepts all three levels. Any other scope sets a topic override, which is binary — `all` or `nothing`. A topic override with no `channel` applies to every delivery channel.\n\n`level: null` clears the preference. Preferences are stored as overrides, so clearing one means the scope inherits its default again rather than being switched off.\n\nThe 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. `null` clears the preference.", "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.", "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.", "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-docs-subgroup": "Preferences/Notifications", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.users.preferences.notifications.set({\n preferences: [\n {\n level: 'nothing',\n scope: {},\n },\n ],\n});\n\nconsole.log(response.data);" } ] } }, "/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": "The number of preferences to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns preferences after this position.", "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": { "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-docs-subgroup": "Preferences/Notifications", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const experienceListResponse of client.users.preferences.notifications.experiences.list()) {\n console.log(experienceListResponse.level);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/users/me/preferences/notifications/topics": { "get": { "description": "Lists the authenticated user's topic-scoped notification preferences, plus user-agnostic platform defaults. Each filter matches preferences scoped to its value or not narrowed on that dimension. 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).", "in": "query", "name": "account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this account's team notifications (`biz_` tag).", "in": "query", "name": "team_account_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this experience (`exp_` tag).", "in": "query", "name": "experience_id", "required": false, "schema": { "type": "string" } }, { "description": "Only return preferences scoped to this notification topic (`topic_` tag).", "in": "query", "name": "topic_id", "required": false, "schema": { "type": "string" } }, { "description": "The number of preferences to return.", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns preferences after this position.", "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": { "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-docs-subgroup": "Preferences/Notifications", "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const topicListResponse of client.users.preferences.notifications.topics.list()) {\n console.log(topicListResponse.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ] }, "/users/{id}": { "get": { "description": "Retrieves a user by `user_` tag or username, or the authenticated user with the reserved id `me`. Profiles include linked social accounts — reading your own profile returns every linked account, other profiles only what is public on Whop (the primary Discord and the X account). The self-only fields are populated only when the id is `me`: `email` (email-read scope), `staff` (Whop staff only, staff-read scope), `balance` and `earnings_usd` (balance-read scope), and the opt-in `balance_history`. They are always `null` when addressing a user by tag or username.", "operationId": "retrieveUser", "parameters": [ { "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": "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" ], "x-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop();\n\nconst user = await client.users.retrieve('id');\n\nconsole.log(user.id);" } ] }, "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 account-specific profile override (account_id required).", "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst user = await client.users.update('id');\n\nconsole.log(user.id);" } ] } }, "/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" ], "x-mint": { "metadata": { "sidebarTitle": "Check Access" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.users.checkAccess('resource_id', { id: 'id' });\n\nconsole.log(response.access_level);" } ] }, "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" } } ] }, "/users/{id}/recommend_actions": { "get": { "description": "Lists the recommended actions computed for the user: personal suggestions (e.g. start a business or become an affiliate) pooled with the highest-impact actions across the accounts the user owns. Business actions are tagged with their `account_id`/`account_name`; personal actions leave those `null`. Self-only: `id` must be `me` or the authenticated user's own tag/username.", "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.users.recommendActions('id');\n\nconsole.log(response.data);" } ] }, "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" } } ] }, "/verifications": { "get": { "description": "Returns verifications for an account, including their status and any required actions.", "operationId": "listVerifications", "parameters": [ { "description": "Account or user ID whose verifications you want to list. Use a `biz_` account ID, or the caller's `user_` ID for personal verifications.", "in": "query", "name": "account_id", "required": true, "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" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "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.", "items": { "properties": { "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" }, "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`), or `address` (send `address`).", "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 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" } }, "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst verifications = await client.verifications.list({ account_id: 'account_id' });\n\nconsole.log(verifications.data);" } ] }, "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 include in the request body are used to prefill the session. Send `documents` (with `document_type`) to instead verify the person from identity documents included in this request — no hosted session involved. Send `share_token` to reuse a verification another Sumsub account has already completed for this person, instead of verifying them again. Send `verification_id` to reuse a verification the signed-in user already completed on Whop. Every mode except `verification_id` is rejected once the account has an `approved` verification — unlink it first to start a new one — while `verification_id` replaces whichever verification of that kind the account currently has.", "operationId": "createVerification", "parameters": [ { "description": "Account or user ID whose identity you want to verify. Use a `biz_` account ID for account verifications, or the caller's `user_` ID for personal verification.", "in": "query", "name": "account_id", "required": true, "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`.", "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`.", "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" }, "first_name": { "description": "First name of the business representative, used to prefill the verification session.", "example": "Marcus", "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" }, "place_of_incorporation": { "description": "State or region where the business is incorporated.", "example": "TX", "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" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "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.", "items": { "properties": { "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" }, "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`), or `address` (send `address`).", "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 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" } }, "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" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "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.", "items": { "properties": { "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" }, "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`), or `address` (send `address`).", "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 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" } }, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst verification = await client.verifications.create({ account_id: 'account_id' });\n\nconsole.log(verification.id);" } ] } }, "/verifications/{id}": { "get": { "description": "Returns verifications for an account, including their status and any required actions.", "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" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "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.", "items": { "properties": { "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" }, "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`), or `address` (send `address`).", "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 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" } }, "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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst verification = await client.verifications.retrieve('id');\n\nconsole.log(verification.id);" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" } ], "patch": { "description": "Updates editable profile details or submits answers for items returned in `requested_information`. 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`.", "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`.", "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" }, "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 — one document, as a list of its 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" }, "value": { "description": "Answer for `text`, `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" } }, "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`.", "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" }, "first_name": { "description": "First name of the business representative.", "example": "Marcus", "type": "string" }, "last_name": { "description": "Last name of the business representative.", "example": "Webb", "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`.", "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" }, "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 — one document, as a list of its 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" }, "value": { "description": "Answer for `text`, `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" } }, "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" }, "kind": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "last_name": { "example": "Webb", "type": [ "string", "null" ] }, "phone": { "description": "Phone number on the verification profile.", "example": "+15551234567", "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.", "items": { "properties": { "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" }, "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`), or `address` (send `address`).", "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 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" } }, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst verification = await client.verifications.update('id');\n\nconsole.log(verification.id);" } ] } }, "/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": true, "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": "The number of webhooks to return (default 20, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns webhooks after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "The number of webhooks to return from the end of the range.", "in": "query", "name": "last", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns webhooks before this position.", "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": { "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-mint": { "metadata": { "sidebarTitle": "List" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const webhookListResponse of client.webhooks.list({ account_id: 'account_id' })) {\n console.log(webhookListResponse.id);\n}" } ] }, "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-01-01", "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", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "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", "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", "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", "ad_campaign.payment_failed", "ad_campaign.updated", "ad.updated", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "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_membership_cancel_at_period_end_changed", "payment_created", "payment_succeeded", "payment_failed", "payment_pending", "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_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" ] }, "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-mint": { "metadata": { "sidebarTitle": "Create" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst webhook = await client.webhooks.create({ url: 'https://example.com/hooks' });\n\nconsole.log(webhook.id);" } ] } }, "/webhooks/{id}": { "delete": { "description": "Permanently deletes a webhook endpoint. Returns `true` on success, matching the legacy proxy response.", "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-mint": { "metadata": { "sidebarTitle": "Delete" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst webhook = await client.webhooks.delete('id');\n\nconsole.log(webhook.id);" } ] }, "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-mint": { "metadata": { "sidebarTitle": "Retrieve" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst webhook = await client.webhooks.retrieve('id');\n\nconsole.log(webhook.id);" } ] }, "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-01-01", "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", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "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", "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", "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", "ad_campaign.payment_failed", "ad_campaign.updated", "ad.updated", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "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_membership_cancel_at_period_end_changed", "payment_created", "payment_succeeded", "payment_failed", "payment_pending", "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_membership.cancel_at_period_end_changed" ], "example": "payment.failed", "type": "string" }, "type": "array" }, "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-mint": { "metadata": { "sidebarTitle": "Update" } }, "x-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst webhook = await client.webhooks.update('id');\n\nconsole.log(webhook.id);" } ] } }, "/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.", "operationId": "listWebhookDeliveries", "parameters": [ { "description": "The number of deliveries to return (default 50, max 100).", "in": "query", "name": "first", "required": false, "schema": { "type": "integer" } }, { "description": "A cursor; returns deliveries after this position.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "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": { "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" }, "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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const webhookListDeliveriesResponse of client.webhooks.listDeliveries('id')) {\n console.log(webhookListDeliveriesResponse.id);\n}" } ] }, "parameters": [ { "$ref": "#/components/parameters/ApiVersionDate" }, { "description": "Webhook ID, prefixed `hook_`.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/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. By default the replay keeps the original `webhook-id`, so consumers that deduplicate on it can drop events they already processed. Pass `regenerate_id` to re-send under a freshly generated `webhook-id` instead, so a deduplicating consumer processes the replay as a new message. 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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.webhooks.replayDelivery('delivery_id', { id: 'id' });\n\nconsole.log(response.body);" } ] } }, "/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 messages whose most recent delivery attempt failed. Fire and forget: nothing about the replay is stored, and each re-send appears as a new entry in the webhook's delivery log. Each matching message is re-sent once, by default with its original `webhook-id`, so consumers that deduplicate are unaffected; pass `regenerate_ids` to re-send under freshly generated ids instead. 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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.webhooks.replay('id', { sent_after: '2026-01-01T12:00:00.000Z' });\n\nconsole.log(response.queued);" } ] } }, "/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-codeSamples": [ { "lang": "JavaScript", "source": "import Whop from '@whop/sdk';\n\nconst client = new Whop({\n apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.webhooks.test('id', { event: 'payment.succeeded' });\n\nconsole.log(response.body);" } ] } } }, "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-09-06", "data": { "balances": [], "banner_image_url": null, "business_address": null, "business_name": null, "business_type": "software", "can_transfer_pending_balance_to_children": false, "capabilities": { "accept_bank_payments": "active", "accept_bnpl_payments": "inactive", "accept_card_payments": "active", "bank_deposit": "inactive", "card_deposit": "active", "card_issuing": "inactive", "crypto_deposit": "active", "crypto_payout": "inactive", "instant_payout": "inactive", "run_ads": "active", "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", "description": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "email": "marcus@shinetime.example", "eula": null, "home_preferences": [], "id": "biz_xxxxxxxxxxxxxx", "industry_group": null, "industry_type": null, "invoice_prefix": "SHINE", "logo_url": null, "metadata": { "external_id": "shop_4417", "region": "austin" }, "onboarding_type": "seller", "opengraph_image_url": null, "opengraph_image_variant": null, "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, "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 } }, "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, "show_joined_whops": true, "show_reviews_dtc": true, "show_user_directory": true, "social_links": [ { "id": "social_4", "title": null, "url": "https://instagram.com/shinetimedetailing", "website": "instagram" } ], "stablecoin_rails": false, "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, "total_usd": null, "use_logo_as_opengraph_image_fallback": false, "verification": { "business": null, "individual": null }, "volume_usd": 0, "wallet": 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": [ "Accounts" ], "x-mint": { "metadata": { "title": "Account Financing Approved", "sidebarTitle": "Account Financing Approved" } } } }, "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-09-06", "data": { "balances": [], "banner_image_url": null, "business_address": null, "business_name": null, "business_type": "software", "can_transfer_pending_balance_to_children": false, "capabilities": { "accept_bank_payments": "active", "accept_bnpl_payments": "inactive", "accept_card_payments": "active", "bank_deposit": "inactive", "card_deposit": "active", "card_issuing": "inactive", "crypto_deposit": "active", "crypto_payout": "inactive", "instant_payout": "inactive", "run_ads": "active", "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", "description": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "email": "marcus@shinetime.example", "eula": null, "home_preferences": [], "id": "biz_xxxxxxxxxxxxxx", "industry_group": null, "industry_type": null, "invoice_prefix": "SHINE", "logo_url": null, "metadata": { "external_id": "shop_4417", "region": "austin" }, "onboarding_type": "seller", "opengraph_image_url": null, "opengraph_image_variant": null, "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, "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 } }, "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, "show_joined_whops": true, "show_reviews_dtc": true, "show_user_directory": true, "social_links": [ { "id": "social_5", "title": null, "url": "https://instagram.com/shinetimedetailing", "website": "instagram" } ], "stablecoin_rails": false, "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, "total_usd": null, "use_logo_as_opengraph_image_fallback": false, "verification": { "business": null, "individual": null }, "volume_usd": 0, "wallet": 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": [ "Accounts" ], "x-mint": { "metadata": { "title": "Account Financing Denied", "sidebarTitle": "Account Financing Denied" } } } }, "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-09-06", "data": { "balances": [], "banner_image_url": null, "business_address": null, "business_name": null, "business_type": "software", "can_transfer_pending_balance_to_children": false, "capabilities": { "accept_bank_payments": "active", "accept_bnpl_payments": "inactive", "accept_card_payments": "active", "bank_deposit": "inactive", "card_deposit": "active", "card_issuing": "inactive", "crypto_deposit": "active", "crypto_payout": "inactive", "instant_payout": "inactive", "run_ads": "active", "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", "description": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "email": "marcus@shinetime.example", "eula": null, "home_preferences": [], "id": "biz_xxxxxxxxxxxxxx", "industry_group": null, "industry_type": null, "invoice_prefix": "SHINE", "logo_url": null, "metadata": { "external_id": "shop_4417", "region": "austin" }, "onboarding_type": "seller", "opengraph_image_url": null, "opengraph_image_variant": null, "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, "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 } }, "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, "show_joined_whops": true, "show_reviews_dtc": true, "show_user_directory": true, "social_links": [ { "id": "social_3", "title": null, "url": "https://instagram.com/shinetimedetailing", "website": "instagram" } ], "stablecoin_rails": false, "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, "total_usd": null, "use_logo_as_opengraph_image_fallback": false, "verification": { "business": null, "individual": null }, "volume_usd": 0, "wallet": 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" ] } }, "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-09-06", "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, "headlines": [], "id": "ad_xxxxxxxxxxxxxx", "issues": [], "lead_form": null, "lead_form_id": null, "messaging_config": null, "multi_advertiser_ads": true, "post_id": null, "post_source": null, "post_thumbnail_url": null, "primary_texts": [], "social_accounts": [], "status": "rejected", "title": "Ceramic Coating Package", "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", 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": [ "rejected", "in_review", "draft", "campaign_paused", "ad_group_paused", "paused", "processing", "issues", "scheduled", "learning_limited", "learning", "active" ], "example": "paused", "type": "string" }, "descriptions": { "items": { "description": "The description variants shown on the ad.", "example": "Paint correction included", "type": "string" }, "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" ] }, "headlines": { "items": { "description": "The headline variants shown on the ad.", "example": "Austin's mobile detailers", "type": "string" }, "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" } ] }, "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": { "description": "The primary text variants shown in the ad body.", "example": "Book a two-day ceramic coating and keep the shine for three years.", "type": "string" }, "type": "array" }, "social_accounts": { "items": { "$ref": "#/components/schemas/AdEntityReference", "description": "The social accounts the ad runs under — its Facebook page and Instagram profile — each referenced by ID, prefixed `sacc_`." }, "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" ] }, "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", "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", "social_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" ] } }, "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-09-06", "data": { "bid_type": null, "budget_amount": 50, "budget_optimization": null, "budget_type": "daily", "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 the ad account's currency. `null` when each ad group sets its own budget instead.", "example": 50, "type": [ "number", "null" ] }, "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" ] }, "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. When several states apply at once, the highest-precedence one is returned.", "enum": [ "payment_failed", "all_ads_rejected", "draft", "no_ad_groups", "no_ads", "paused", "processing", "issues", "scheduled", "completed", "ad_groups_off", "active" ], "example": "issues", "type": "string" }, "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.", "type": [ "string", "null" ] }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "meta", "tiktok" ], "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" }, "status": { "description": "The lifecycle status of the ad campaign.", "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", "objective", "special_ad_categories", "optimization_goal", "budget_amount", "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-mint": { "metadata": { "title": "Ad Campaign Payment Failed", "sidebarTitle": "Ad Campaign Payment Failed" } } } }, "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-09-06", "data": { "bid_type": null, "budget_amount": 50, "budget_optimization": null, "budget_type": "daily", "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 the ad account's currency. `null` when each ad group sets its own budget instead.", "example": 50, "type": [ "number", "null" ] }, "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" ] }, "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. When several states apply at once, the highest-precedence one is returned.", "enum": [ "payment_failed", "all_ads_rejected", "draft", "no_ad_groups", "no_ads", "paused", "processing", "issues", "scheduled", "completed", "ad_groups_off", "active" ], "example": "issues", "type": "string" }, "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.", "type": [ "string", "null" ] }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "meta", "tiktok" ], "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" }, "status": { "description": "The lifecycle status of the ad campaign.", "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", "objective", "special_ad_categories", "optimization_goal", "budget_amount", "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" ] } }, "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-09-06", "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, "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" ] } }, "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-09-06", "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, "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" ] } }, "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-09-06", "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, "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" ] } }, "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-09-06", "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, "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "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": "CardTransaction Completed", "tags": [ "Cards" ] } }, "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-09-06", "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": "CardTransaction Created", "tags": [ "Cards" ] } }, "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-09-06", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 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": "CardTransaction Declined", "tags": [ "Cards" ] } }, "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-09-06", "data": { "card_id": "icrd_xxxxxxxxxxxxxx", "cardholder_id": null, "cashback_usd_amount": 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": "CardTransaction Reversed", "tags": [ "Cards" ] } }, "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-09-06", "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": "CardTransaction Updated", "tags": [ "Cards" ] } }, "deposit.succeeded": { "post": { "description": "Sent when a deposit is succeeded\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-09-06", "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" ] } }, "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-09-06", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 150, "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, "generated_response_attachment": null, "id": "dspt_xxxxxxxxxxxxxx", "inquiry": false, "issuer_comments": [], "payment": { "amount": 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": "stripe" }, "plan_id": null, "product_id": null, "rapid_dispute_resolution": false, "reason": "fraudulent", "reason_code": null, "status": "needs_response", "updated_at": "2026-01-01T12:00:00.000Z" }, "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" ] } }, "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-09-06", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount": 150, "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", "generated_response_attachment": null, "id": "dspt_xxxxxxxxxxxxxx", "inquiry": false, "issuer_comments": [], "payment": { "amount": 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": "stripe" }, "plan_id": null, "product_id": null, "rapid_dispute_resolution": false, "reason": "fraudulent", "reason_code": null, "status": "under_review", "updated_at": "2026-01-01T12:00:00.000Z" }, "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" ] } }, "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-09-06", "data": { "account_id": null, "actionable": false, "amount": 25, "card_brand": "visa", "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "fee_charged": false, "id": "dspa_xxxxxxxxxxxxxx", "issuer": null, "not_actionable_reason": "payment_unmatched", "payment_id": null, "product_id": null, "reported_at": "2026-01-01T12:00:00.000Z", "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "data": { "access_level": "customer", "account_id": "biz_xxxxxxxxxxxxxx", "created_at": "2026-01-01T12:00:00.000Z", "id": "mber_xxxxxxxxxxxxxx", "joined_at": "2026-01-01T12:00:00.000Z", "last_accessed_at": "2026-01-01T12:00:00.000Z", "phone_number": null, "status": "joined", "token_balance": 0, "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" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "cancel_at_period_end": false, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "id": "mem_xxxxxxxxxxxxxx", "license_key": null, "member": null, "metadata": {}, "phone_number": null, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "status": "active", "user_id": "user_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" ] } }, "membership.cancel_at_period_end_changed": { "post": { "description": "Sent when a membership is cancel at period end changed\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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "cancel_at_period_end": true, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "id": "mem_xxxxxxxxxxxxxx", "license_key": null, "member": null, "metadata": {}, "phone_number": null, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "status": "active", "user_id": "user_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.cancel_at_period_end_changed" }, "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.cancel_at_period_end_changed", "description": "The webhook event type", "example": "membership.cancel_at_period_end_changed", "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 Cancel at period end changed", "tags": [ "Memberships" ], "x-mint": { "metadata": { "title": "Membership Cancel at Period End Changed", "sidebarTitle": "Membership Cancel at Period End Changed" } } } }, "membership.deactivated": { "post": { "description": "Sent when a membership is deactivated\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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "cancel_at_period_end": false, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "id": "mem_xxxxxxxxxxxxxx", "license_key": null, "member": null, "metadata": {}, "phone_number": null, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "status": "canceled", "user_id": "user_xxxxxxxxxxxxxx" }, "id": "msg_xxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2025-01-01T00:00:00.000Z", "type": "membership.deactivated" }, "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.deactivated", "description": "The webhook event type", "example": "membership.deactivated", "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 Deactivated", "tags": [ "Memberships" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "logo_url": null, "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "cancel_at_period_end": false, "created_at": "2026-01-01T12:00:00.000Z", "current_period_end": "2026-01-01T12:00:00.000Z", "id": "mem_xxxxxxxxxxxxxx", "license_key": null, "member": null, "metadata": {}, "phone_number": null, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "status": "trialing", "user_id": "user_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-mint": { "metadata": { "title": "Membership Trial Ending Soon", "sidebarTitle": "Membership Trial Ending Soon" } } } }, "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-09-06", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "failure_message": null, "financing_installments_count": null, "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt_at": 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", "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", "payments_failed": 0, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_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" }, "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" ] } }, "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-09-06", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "failure_message": null, "financing_installments_count": null, "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt_at": 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", "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", "payments_failed": 0, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_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" }, "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" ] } }, "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-09-06", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "failure_message": null, "financing_installments_count": null, "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt_at": 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", "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", "payments_failed": 0, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_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" }, "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" ] } }, "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-09-06", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "failure_message": "Your card was declined.", "financing_installments_count": null, "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt_at": "2026-01-01T12:00:00.000Z", "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", "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", "payments_failed": 1, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_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" }, "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" ] } }, "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-09-06", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "failure_message": null, "financing_installments_count": null, "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt_at": 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", "payments_failed": 0, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "recovery_url": null, "refundable": false, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_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" }, "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" ] } }, "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-09-06", "data": { "account_id": "biz_xxxxxxxxxxxxxx", "amount_after_fees": { "amount": "50.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "auto_refunded": false, "billing_address": null, "billing_reason": "subscription_cycle", "checkout_configuration_id": null, "client_secret": null, "created_at": "2026-01-01T12:00:00.000Z", "currency": "usd", "customer_phone": null, "decline_code": null, "dispute_alerted_at": null, "failure_message": null, "financing_installments_count": null, "id": "pay_xxxxxxxxxxxxxx", "last_payment_attempt_at": 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", "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", "payments_failed": 0, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "promo_code_id": null, "recovery_url": null, "refundable": true, "refunded_amount": { "amount": "0.00", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "refunded_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" }, "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" ] } }, "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-09-06", "data": { "amount": "10.0", "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": "in_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" }, "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 stablecoin payout 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 stablecoin payout 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": "Text that appears on the recipient's bank statement, or `null` if no descriptor was set. When set, 5-22 alphanumeric characters (A-Z, a-z, 0-9).", "example": "MYCOMPANY", "maxLength": 22, "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 stablecoin 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", "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" ] } }, "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-09-06", "data": { "amount": "10.0", "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" }, "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 stablecoin payout 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 stablecoin payout 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": "Text that appears on the recipient's bank statement, or `null` if no descriptor was set. When set, 5-22 alphanumeric characters (A-Z, a-z, 0-9).", "example": "MYCOMPANY", "maxLength": 22, "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 stablecoin 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", "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" ] } }, "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-09-06", "data": { "amount": "10.0", "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" }, "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 stablecoin payout 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 stablecoin payout 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": "Text that appears on the recipient's bank statement, or `null` if no descriptor was set. When set, 5-22 alphanumeric characters (A-Z, a-z, 0-9).", "example": "MYCOMPANY", "maxLength": 22, "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 stablecoin 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", "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" ] } }, "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-09-06", "data": { "account_reference": "4483", "bank_verification_state": "no_data", "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, "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, "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, "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, "format": "float", "type": [ "number", "null" ] }, "min_limit": { "description": "Minimum payout amount for this method, in the payout currency.", "example": 1, "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" ] }, "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.", "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" ] } }, "plan.created": { "post": { "description": "Sent when a plan 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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "billing_period": 30, "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", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "bizum", "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", "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", "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", "tamara", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "verve", "vipps", "webpay", "wechat_pay", "yape", "zip" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0, "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, "plan_type": "renewal", "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50, "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/Plan" }, "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": "Plan Created", "tags": [ "Plans" ] } }, "plan.deleted": { "post": { "description": "Sent when a plan 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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "billing_period": 30, "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", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "bizum", "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", "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", "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", "tamara", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "verve", "vipps", "webpay", "wechat_pay", "yape", "zip" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0, "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, "plan_type": "renewal", "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50, "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/Plan" }, "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": "Plan Deleted", "tags": [ "Plans" ] } }, "plan.updated": { "post": { "description": "Sent when a plan 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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "adaptive_pricing_enabled": true, "billing_period": 30, "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", "alma", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "bizum", "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", "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", "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", "tamara", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "verve", "vipps", "webpay", "wechat_pay", "yape", "zip" ], "include_platform_defaults": false }, "expiration_days": null, "formatted_price": "$50.00 / month", "id": "plan_xxxxxxxxxxxxxx", "image": null, "initial_price": 0, "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, "plan_type": "renewal", "product": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "release_method": "buy_now", "renewal_price": 50, "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/Plan" }, "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": "Plan Updated", "tags": [ "Plans" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 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", "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" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 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", "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" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "live_marketplace", "member_affiliate_percentage": 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", "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" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 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", "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" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "created_at": "2026-01-01T12:00:00.000Z", "custom_cta": null, "custom_cta_url": null, "custom_statement_descriptor": null, "default_plan": null, "description": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "external_identifier": null, "gallery_images": [], "global_affiliate_percentage": 30, "global_affiliate_status": "enabled", "headline": "A showroom finish that lasts three years", "id": "prod_xxxxxxxxxxxxxx", "labels": [], "marketplace_status": "not_available", "member_affiliate_percentage": 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", "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" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 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": "Multi-lateral upward-trendi...", "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "quantity": 1 } ], "outcome": null, "payment": { "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "pay_xxxxxxxxxxxxxx", "payment_method_type": null }, "plan_id": "plan_xxxxxxxxxxxxxx", "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" }, "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" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 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": "Horizontal upward-trending ...", "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "quantity": 1 } ], "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 }, "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "reason": "product_not_received", "refund": "merchant", "response_due_at": null, "status": "closed", "updated_at": "2026-01-01T12:00:00.000Z" }, "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" ] } }, "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-09-06", "data": { "account": { "id": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "amount": 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": "Business-focused directiona...", "plan_id": "plan_xxxxxxxxxxxxxx", "product_id": "prod_xxxxxxxxxxxxxx", "quantity": 1 } ], "outcome": null, "payment": { "card_brand": null, "card_last4": null, "created_at": "2026-01-01T12:00:00.000Z", "id": "pay_xxxxxxxxxxxxxx", "payment_method_type": null }, "plan_id": "plan_xxxxxxxxxxxxxx", "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" }, "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "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" ] } }, "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-09-06", "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": "-2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "card_brand": "some_string", "card_last4": "some_string", "created_at": "some_string", "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, "card_brand": "some_string", "chain": "plasma", "claim_url": "https://whop.com/claim", "created_at": "2026-01-01T12:00:00.000Z", "estimated_arrival": "2026-01-01T12:00:00.000Z", "from_amount": "502.51", "from_currency": "usdt", "id": "airdrp_xxxxxxxxxxxxxx", "notes": "some_string", "object": "airdrop_link", "payer_name": "MassPay", "payment_amount": { "amount": "-2.50", "currency": "usd", "decimals": 2, "display_decimals": 2 }, "payment_method_type": "some_string", "payment_processor": "some_string", "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": false, "sender_address": "0x8a4de51b9c37f2e6a0d1b8c94e5f7a2d3c6b0e19", "status": "fully_claimed", "to_amount": "500.0", "to_currency": "usd", "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" ] } }, "transfer.completed": { "post": { "description": "Sent when a transfer is completed\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-09-06", "data": { "amount": 250, "created_at": "2026-01-01T12:00:00.000Z", "created_by_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "currency": "usd", "destination": { "id": "biz_xxxxxxxxxxxxx2", "route": "biz_xxxxxxxxxxxxx2", "title": "Shine Time Auto Detailing", "typename": "Company" }, "destination_ledger_account_id": "ldgr_xxxxxxxxxxxxx2", "failed_at": null, "failure_code": null, "failure_reason": null, "fee_amount": 7.5, "id": "ctt_xxxxxxxxxxxxxx", "metadata": { "invoice": "SHINE-1042" }, "notes": "Detailing supplies restock", "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing", "typename": "Company" }, "origin_ledger_account_id": "ldgr_xxxxxxxxxxxxxx", "status": "succeeded" }, "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 of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "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", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "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" ] } }, "transfer.created": { "post": { "description": "Sent when a transfer is created\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-09-06", "data": { "amount": 250, "created_at": "2026-01-01T12:00:00.000Z", "created_by_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "currency": "usd", "destination": { "id": "biz_xxxxxxxxxxxxx2", "route": "biz_xxxxxxxxxxxxx2", "title": "Shine Time Auto Detailing", "typename": "Company" }, "destination_ledger_account_id": "ldgr_xxxxxxxxxxxxx2", "failed_at": null, "failure_code": null, "failure_reason": null, "fee_amount": 7.5, "id": "ctt_xxxxxxxxxxxxxx", "metadata": { "invoice": "SHINE-1042" }, "notes": "Detailing supplies restock", "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing", "typename": "Company" }, "origin_ledger_account_id": "ldgr_xxxxxxxxxxxxxx", "status": "succeeded" }, "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 of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "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", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "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" ] } }, "transfer.failed": { "post": { "description": "Sent when a transfer is failed\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-09-06", "data": { "amount": 10, "created_at": "2026-01-01T12:00:00.000Z", "created_by_user": { "id": "user_xxxxxxxxxxxxxx", "name": "Marcus Webb", "username": "marcuswebb" }, "currency": "usd", "destination": { "id": "biz_xxxxxxxxxxxxx2", "route": "biz_xxxxxxxxxxxxx2", "title": "Shine Time Auto Detailing", "typename": "Company" }, "destination_ledger_account_id": "ldgr_xxxxxxxxxxxxx2", "failed_at": null, "failure_code": null, "failure_reason": null, "fee_amount": null, "id": "ctt_xxxxxxxxxxxxxx", "metadata": null, "notes": null, "object": "transfer", "origin": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing", "typename": "Company" }, "origin_ledger_account_id": "ldgr_xxxxxxxxxxxxxx", "status": "succeeded" }, "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 of credit between two ledger accounts.", "properties": { "amount": { "description": "Transfer amount.", "example": 25, "type": "number" }, "created_at": { "description": "When the transfer was created.", "example": "2026-01-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "created_by_user": { "description": "The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.", "properties": { "id": { "description": "User ID.", "example": "user_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Marcus Webb", "type": [ "string", "null" ] }, "username": { "description": "User's username.", "example": "marcuswebb", "type": "string" } }, "required": [ "id", "username" ], "title": "TransferCreatedByUser", "type": [ "object", "null" ] }, "currency": { "description": "Transfer currency.", "example": "usd", "type": "string" }, "destination": { "description": "Account or user receiving funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "destination_ledger_account_id": { "description": "Destination ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "failed_at": { "description": "When the transfer failed, as an ISO 8601 timestamp. Null unless the transfer has failed.", "format": "date-time", "type": [ "string", "null" ] }, "failure_code": { "description": "Machine-readable code for why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "failure_reason": { "description": "Human-readable explanation of why the transfer failed. Null unless the transfer has failed.", "type": [ "string", "null" ] }, "fee_amount": { "description": "Fee charged for the transfer.", "example": 0.5, "type": [ "number", "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", "null" ] }, "notes": { "description": "Transfer note.", "example": "Refund for the rescheduled interior detail", "type": [ "string", "null" ] }, "object": { "description": "The object type. Discriminates the create response from a send or a claim link.", "enum": [ "transfer" ], "example": "transfer", "type": "string" }, "origin": { "description": "Account or user sending funds.", "discriminator": { "propertyName": "typename" }, "oneOf": [ { "properties": { "id": { "description": "Account ID.", "example": "biz_xxxxxxxxxxxxxx", "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" ] }, "typename": { "enum": [ "Company" ], "example": "Company", "type": "string" } }, "required": [ "typename", "id" ], "title": "Company", "type": "object" }, { "properties": { "id": { "description": "User ID.", "example": "biz_xxxxxxxxxxxxxx", "type": "string" }, "name": { "description": "User display name.", "example": "Dana Whitfield", "type": [ "string", "null" ] }, "typename": { "enum": [ "User" ], "example": "User", "type": "string" }, "username": { "description": "User's username.", "example": "danawhitfield", "type": "string" } }, "required": [ "typename", "id" ], "title": "User", "type": "object" } ] }, "origin_ledger_account_id": { "description": "Source ledger account ID.", "example": "ldgr_xxxxxxxxxxxxxx", "type": "string" }, "status": { "description": "Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`. A `failed` transfer may be retried under the same ID and later resolve to `succeeded`.", "enum": [ "processing", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "object", "id", "status", "amount", "currency", "created_at", "origin_ledger_account_id", "destination_ledger_account_id", "created_by_user", "origin", "destination" ], "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" ] } } }, "components": { "parameters": { "ApiVersionDate": { "description": "Pins the request to a dated API version.", "in": "header", "name": "Api-Version-Date", "required": false, "schema": { "example": "2026-09-06", "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": { "Account": { "properties": { "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.", "enum": [ "education_program", "coaching", "software", "paid_group", "newsletter", "agency", "physical_products", "brick_and_mortar", "events", "coaching_and_courses", "other", "services", "gig_economy", "marketplace", "telehealth", "class_action_settlement", "physical_product", "saas", "course", "community", null ], "example": "other", "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" }, "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. Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise, or when the account has no card application.", "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": true, "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" }, "description": { "description": "Account promotional description.", "example": "Mobile ceramic coating, paint correction, and interior detailing across the Austin metro.", "type": [ "string", "null" ] }, "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" } ] }, "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_group": { "description": "Account industry group. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values.", "enum": [ "academic_and_test_prep", "accessories", "agriculture_and_farming", "ai_and_automation_agencies", "ai_and_automation_software", "arts_and_crafts", "automotive", "b2b_and_professional_marketplaces", "baby_and_kids", "bars_and_breweries", "beauty_and_personal_care", "beauty_and_wellness", "business_and_entrepreneurship", "business_and_money_groups", "cafes_and_quick_service", "career_and_professional", "charity_and_cause_events", "class_action_settlement", "clothing_and_apparel", "communication_and_messaging_software", "community_and_education_software", "conference_and_expo_events", "consulting", "content_and_clipping_agencies", "creative_and_content_creation", "creative_and_content_groups", "creative_and_education", "creative_gigs", "creative_services", "customer_support_agencies", "dating_and_relationships", "delivery_and_logistics", "dental_and_vision", "dermatology_and_skin", "design_and_creative_agencies", "developer_and_technical_tools", "development_agencies", "digital_and_education_marketplaces", "digital_goods_and_accounts", "e_commerce_software", "education_and_childcare", "educational_training_events", "electronics_and_gadgets", "entertainment_and_leisure", "family_and_community_events", "finance_and_investing", "fitness_and_athletics", "fitness_and_health_groups", "fitness_and_recreation", "fitness_equipment_and_gear", "food_and_beverages", "food_and_hospitality_marketplaces", "funeral_and_death_care", "gaming_and_entertainment_software", "gaming_groups", "genetic_and_specialized", "government_and_public", "health_and_wellness", "health_and_wellness_services", "healthcare", "healthcare_and_wellness_software", "hobbies_and_lifestyle", "hobby_and_interest_groups", "home_and_living", "home_and_trade_services", "home_and_trade_storefronts", "home_improvement_and_tools", "home_services_gigs", "hospitality_and_lodging", "industrial_and_manufacturing", "industry_specific_software", "language_and_communication", "legal_and_compliance", "lifestyle_and_culture", "lifestyle_and_personal_growth", "lifestyle_and_personal_growth_groups", "lifestyle_and_wellness_events", "logistics_and_transportation_services", "marketing_agencies", "marketing_and_advertising", "marketing_and_sales_software", "media_and_publishing_companies", "mental_health_and_behavioral", "miscellaneous", "music_and_performing_arts", "news_and_politics", "nonprofit_and_charity", "office_and_business_supplies", "outdoor_and_sports", "performance_and_show_events", "personal_development", "personal_finance", "personal_services", "pet_services", "pets_and_animals", "primary_and_general_care", "product_marketplaces", "productivity_and_business_ops", "professional_gigs", "professional_services", "professional_services_storefront", "publishing_and_info_products", "real_estate", "real_estate_software", "recruiting_and_staffing", "rehabilitation_and_therapy", "religion_and_faith", "rental_marketplaces", "restaurants", "retail", "sales_agencies", "sales_and_revenue", "security_and_investigations", "security_and_privacy_software", "service_marketplaces", "sleep_and_chronic_conditions", "social_and_networking_events", "social_entertainment_events", "specialized_gigs", "specialty_medical_care", "spirituality_and_mindfulness", "spirituality_and_personal_growth", "sports_and_fitness_events", "sports_betting_and_gambling", "sports_betting_groups", "supplements_and_nutrition", "sustainability_and_eco_products", "task_and_errands", "tech_and_ai", "tech_and_dev_groups", "tech_and_development", "trading_and_finance_software", "trading_and_investing", "trading_and_investing_groups", "transportation", "veterinary", "video_games_and_esports", "weight_and_metabolic_health", "wellness_and_alternative", "womens_and_mens_health", null ], "example": "automotive", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "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.", "enum": [ "trading", "sports_betting", "reselling", "fitness", "amazon_fba", "real_estate", "kindle_book_publishing", "dating", "agencies", "health_and_wellness", "social_media", "sales", "business", "ecommerce", "video_games", "home_services", "ai", "public_speaking", "personal_finance", "careers", "travel", "clipping", "spirituality", "vas", "personal_development", "software", "other", "marketing_agency", "sales_agency", "ai_agency", "design_agency", "coaching_agency", "development_agency", "recruiting_agency", "customer_support_agency", "clipping_agency", "clothing", "supplements", "beauty_and_personal_care", "fitness_gear", "accessories", "home_goods", "electronics_and_gadgets", "food_and_beverages", "gym", "restaurant", "retail_store", "coffee_shop", "salon_spa", "medical_dentist_office", "hotel_lodging", "auto_repair_shop", "masterminds", "webinars", "bootcamps", "convention", "concerts", "meetups", "parties", "forex_trading", "stock_trading", "options_trading", "crypto_trading", "futures_trading", "day_trading", "swing_trading", "algorithmic_trading", "prop_firm_trading", "value_investing", "real_estate_investing", "alternative_investments", "penny_stock_trading", "dividend_investing", "index_fund_investing", "gold_precious_metals", "venture_capital_education", "private_equity_education", "technical_analysis", "forex_scalping", "ict_smc_trading", "personalized_investment_advice", "forex_signals_group", "stock_signals_group", "crypto_signals_group", "options_alerts_group", "futures_signals_group", "trading_education_group", "investing_community", "prediction_markets_group", "nft_alpha_group", "penny_stock_group", "dividend_investing_group", "real_estate_investing_group", "prop_firm_group", "forex_trading_bot", "stock_trading_platform", "crypto_trading_bot", "futures_trading_bot", "options_flow_tool", "portfolio_tracker", "financial_modeling_software", "accounting_software", "invoicing_software", "tax_software", "risk_management_software", "prop_trading_platform", "backtesting_software", "trading_indicators", "market_data_feed", "stock_research_tool", "banking_software", "lending_platform", "insurance_software", "bnpl_service", "check_cashing_service", "cloud_mining_schemes", "consumer_lending", "credit_repair_service", "crypto_exchange_brokerage", "crypto_trading_tools_software", "debt_collection_agency", "debt_relief_settlement", "escrow_service", "foreign_exchange_service", "non_custodial_wallet_tools", "payment_facilitation", "prediction_market_exchange", "stablecoin_issuance", "token_sales_ico", "tokenized_rwa", "yield_staking_products", "sports_betting_picks", "fantasy_sports", "horse_racing", "poker_coaching", "esports_betting", "sports_analytics", "nfl_betting", "nba_betting", "mlb_betting", "soccer_betting", "mma_ufc_betting", "sports_picks_group", "dfs_group", "horse_racing_group", "esports_picks_group", "nfl_picks_group", "nba_picks_group", "soccer_picks_group", "mlb_picks_group", "mma_picks_group", "prop_bets_group", "fantasy_sports_free_to_play", "licensed_gambling_operations", "unlicensed_gambling", "bodybuilding_coaching", "strength_training", "weight_loss_coaching", "athletic_performance", "yoga_instruction", "martial_arts_instruction", "running_coaching", "calisthenics", "flexibility_mobility", "nutrition_coaching", "swimming_coaching", "cycling_coaching", "boxing_coaching", "mma_coaching", "jiu_jitsu_coaching", "wrestling_coaching", "gymnastics_coaching", "pilates_instruction", "sports_nutrition", "body_recomposition", "golf_coaching", "tennis_coaching", "basketball_training", "soccer_training", "racket_sports_coaching", "fitness_accountability", "nutrition_community", "weight_loss_group", "bodybuilding_community", "running_community", "martial_arts_community", "mental_health_group", "biohacking_community", "addiction_support_group", "yoga_community", "crossfit_community", "longevity_community", "womens_fitness_community", "postpartum_fitness_group", "chronic_illness_support", "skincare_community", "mental_health_coaching", "life_coaching", "biohacking", "holistic_health", "addiction_recovery_coaching", "breathwork", "meditation_mindfulness", "gut_health_coaching", "longevity_coaching", "womens_health_coaching", "mens_health_coaching", "fertility_wellness", "stress_management", "grief_coaching", "trauma_recovery_coaching", "adhd_coaching", "biomarker_health_coaching", "telehealth_platform", "ehr_software", "practice_management", "mental_health_app", "fitness_app", "nutrition_tracking_app", "wellness_app", "patient_engagement", "medical_billing_software", "pharmacy_management", "lab_management", "clinical_trial_software", "dental_software", "veterinary_software", "health_data_platform", "fitness_newsletter", "mental_health_newsletter", "longevity_newsletter", "medical_newsletter", "biohacking_newsletter", "womens_health_newsletter", "mens_health_newsletter", "pharma_biotech_newsletter", "ecommerce_education", "amazon_fba_coaching", "dropshipping_coaching", "print_on_demand_coaching", "retail_arbitrage", "wholesale_coaching", "startup_coaching", "business_strategy", "agency_building", "smma_coaching", "consulting_business", "saas_entrepreneurship", "local_business_coaching", "cleaning_business_coaching", "trucking_business_coaching", "vending_machine_business", "atm_business_coaching", "car_wash_business", "airbnb_business_coaching", "private_label_coaching", "etsy_coaching", "merch_business_coaching", "licensing_business", "business_acquisition", "women_entrepreneurship", "affiliate_marketing_education", "coaching_business_coaching", "ecommerce_community", "agency_community", "saas_community", "saas_marketing_community", "real_estate_community", "sales_community", "affiliate_community", "reselling_community", "amazon_seller_community", "dropshipping_community", "freelancer_community", "startup_founder_community", "ceo_executive_community", "women_business_community", "marketing_community", "ai_business_community", "content_business_community", "local_business_community", "private_equity_community", "wholesaling_community", "coaching_business_community", "make_money_online_community", "startup_newsletter", "ecommerce_newsletter", "marketing_newsletter", "sales_newsletter", "small_business_newsletter", "leadership_newsletter", "agency_newsletter", "saas_newsletter", "hr_people_newsletter", "legal_business_newsletter", "real_estate_business_newsletter", "solopreneur_newsletter", "high_ticket_sales", "b2b_sales_coaching", "door_to_door_sales", "sales_funnel_coaching", "appointment_setting_coaching", "insurance_sales_coaching", "car_sales_coaching", "retail_sales_coaching", "solar_sales_coaching", "lead_generation_agency", "cold_email_agency", "cold_calling_agency", "sales_outsourcing", "crm_implementation", "appointment_setting_agency", "sales_training_agency", "revenue_operations_agency", "inbound_teleservices", "outbound_telemarketing", "facebook_ads", "google_ads", "tiktok_marketing", "youtube_marketing", "instagram_growth", "seo_coaching", "email_marketing_coaching", "copywriting_coaching", "affiliate_marketing", "local_seo", "ai_marketing", "webinar_marketing", "event_marketing", "saas_marketing_coaching", "digital_marketing", "smma", "performance_marketing_agency", "seo_agency", "content_marketing_agency", "email_marketing_agency", "influencer_marketing_agency", "pr_agency", "branding_agency", "video_marketing_agency", "amazon_marketing_agency", "podcast_marketing_agency", "tiktok_agency", "linkedin_agency", "local_marketing_agency", "dental_marketing_agency", "real_estate_marketing_agency", "restaurant_marketing_agency", "ecommerce_marketing_agency", "b2b_marketing_agency", "growth_marketing_agency", "affiliate_management_agency", "conversion_optimization_agency", "event_marketing_agency", "click_farm_service", "data_scraping_service", "lead_list_sales", "social_media_bot_farm", "crm_software", "email_marketing_software", "sms_marketing_software", "seo_tool", "landing_page_builder", "ad_management_tool", "affiliate_tracking", "review_management", "analytics_dashboard", "lead_gen_software", "link_in_bio_tool", "influencer_platform", "webinar_platform", "ab_testing_tool", "chatbot_marketing", "video_sales_tool", "proposal_software", "competitive_intelligence", "social_listening_tool", "whatsapp_marketing_tool", "standalone_tipping", "video_editing_education", "photography_coaching", "music_production", "ui_ux_design_education", "clipping_education", "ugc_creation", "3d_modeling_education", "dj_education", "youtube_automation", "blog_monetization", "wedding_photography_education", "calligraphy_lettering", "illustration_education", "fashion_design_education", "interior_design_education", "influencer_education", "ai_content_creator_education", "ai_nsfw_content_generation_education", "web_design_agency", "graphic_design_agency", "ui_ux_agency", "motion_design_agency", "product_design_agency", "logo_design_agency", "presentation_design_agency", "3d_visualization_agency", "fashion_design_agency", "video_clipping_agency", "video_production_agency", "ugc_agency", "content_writing_agency", "translation_agency", "social_media_management", "ghostwriting_agency", "podcast_editing_agency", "thumbnail_design_agency", "scriptwriting_agency", "seo_content_agency", "technical_writing_agency", "photography_service", "videography_service", "music_production_service", "voice_over_service", "event_photography", "drone_services", "commercial_photography", "portrait_photography_service", "real_estate_photography", "food_photography_service", "live_event_production", "podcast_production_service", "freelance_design_gig", "freelance_writing_gig", "freelance_dev_gig", "music_performance_gig", "event_staffing_gig", "model_talent_gig", "photography_gig", "videography_gig", "voiceover_gig", "illustration_gig", "social_media_gig", "dj_gig", "face_painting_gig", "clipping_gig", "content_creator_community", "video_editing_community", "music_producer_community", "photography_community", "writing_community", "design_community", "youtube_creator_community", "tiktok_creator_community", "podcast_community", "filmmaker_community", "clipping_community", "youtube_automation_community", "pirated_digital_content", "web_development_education", "ai_ml_education", "data_science_education", "cybersecurity_education", "cloud_computing_education", "blockchain_education", "no_code_education", "automation_education", "game_development_education", "prompt_engineering", "python_programming", "javascript_programming", "react_development", "database_engineering", "aws_certification", "data_engineering", "robotics_education", "vr_ar_development", "linux_sysadmin", "wordpress_development", "ai_agent_building", "web_development_agency", "mobile_app_agency", "saas_development_agency", "ecommerce_development", "blockchain_development_agency", "game_development_agency", "devops_agency", "ai_development_agency", "wordpress_agency", "shopify_agency", "api_integration_agency", "cybersecurity_agency", "data_engineering_agency", "vr_ar_development_agency", "hacking_tools_malware", "stalkerware_monitoring", "developer_community", "ai_community", "cybersecurity_community", "no_code_community", "indie_hacker_community", "devops_community", "data_science_community", "product_community", "open_source_community", "api_management", "hosting_platform", "database_tool", "devops_tool", "monitoring_tool", "testing_tool", "code_editor", "no_code_builder", "cdn_platform", "error_tracking", "documentation_tool", "webhook_tool", "3d_weapon_files", "background_check_services", "document_falsification", "fake_id_services", "fake_reference_services", "real_estate_wholesaling", "house_flipping", "property_development", "rental_property", "airbnb_str", "commercial_real_estate", "land_investing", "section_8_housing", "mobile_home_investing", "multifamily_investing", "self_storage_investing", "property_management_education", "vacation_rental_management", "real_estate_crm", "property_management_software", "deal_analysis_tool", "mls_search_tool", "virtual_tour_software", "real_estate_marketing_software", "construction_management", "home_valuation_tool", "credit_repair_education", "budgeting_coaching", "tax_strategy_education", "wealth_building", "student_loan_strategy", "credit_card_optimization", "career_coaching", "executive_coaching", "management_coaching", "tech_career_coaching", "medical_career_coaching", "trade_skills_education", "va_training", "bookkeeping_education", "data_career_coaching", "cybersecurity_career", "consulting_career", "investment_banking_career", "law_career_coaching", "nursing_career_coaching", "teaching_career_coaching", "personal_branding_career", "mens_dating_coaching", "womens_dating_coaching", "relationship_coaching", "marriage_coaching", "communication_coaching", "masculinity_coaching", "femininity_coaching", "breakup_recovery", "manifestation_coaching", "astrology_coaching", "energy_healing", "spiritual_coaching", "faith_based_coaching", "psychic_development", "numerology_coaching", "chakra_healing", "shamanic_healing", "biblical_coaching", "islamic_coaching", "productivity_coaching", "public_speaking_coaching", "mindset_coaching", "stoicism_philosophy", "mens_self_improvement", "womens_self_improvement", "leadership_development", "anger_management", "neurolinguistic_programming", "appearance_and_grooming_coaching", "amazon_kdp", "self_publishing", "audiobook_publishing", "course_creation", "digital_product_creation", "ghostwriting_business", "template_creation", "ai_book_publishing", "language_learning", "tutoring", "college_admissions_coaching", "cpa_exam_prep", "bar_exam_prep", "real_estate_exam_prep", "medical_board_prep", "pmp_certification_prep", "aws_certification_prep", "comptia_certification", "ap_exam_prep", "graduate_school_prep", "scholarship_coaching", "homeschool_education", "stem_education", "financial_certification", "coding_bootcamp_prep", "cooking_culinary", "travel_coaching", "parenting_coaching", "pet_training", "gardening_education", "diy_crafts", "survival_prepping", "baking_pastry", "wine_sommelier", "beer_brewing", "mixology_bartending", "woodworking", "pottery_ceramics", "knitting_crocheting", "jewelry_making", "aquarium_fishkeeping", "bird_watching", "astronomy_education", "magic_illusion", "car_restoration", "motorcycle_riding", "sailing_boating", "scuba_diving", "rock_climbing", "skiing_snowboarding", "surfing_education", "homesteading", "tiny_house_living", "van_life", "fashion_styling", "floral_design", "travel_planning_service", "collectibles_coaching", "car_enthusiast_community", "sneakerhead_community", "watch_collector_community", "wine_enthusiast_community", "cigar_community", "cooking_community", "gardening_community", "fishing_community", "hunting_community", "diy_maker_community", "golf_community", "collectibles_community", "sweepstakes_raffles", "event_ticket_community", "esports_coaching", "game_specific_coaching", "gaming_community", "game_account_selling", "unauthorized_ingame_currency", "legal_education", "music_theory", "music_business", "acting_coaching", "dance_instruction", "voice_acting", "english_coaching", "spanish_coaching", "mandarin_coaching", "french_coaching", "german_coaching", "japanese_coaching", "korean_coaching", "arabic_coaching", "sign_language_education", "accent_reduction", "business_english", "ai_chatbot_agency", "ai_automation_agency", "ai_consulting", "workflow_automation_agency", "data_analytics_agency", "ai_voice_agent_agency", "ai_content_agency", "machine_learning_agency", "computer_vision_agency", "tech_recruiting_agency", "executive_recruiting", "staffing_agency", "remote_staffing", "healthcare_recruiting", "va_placement_agency", "sales_recruiting", "creative_recruiting", "finance_recruiting", "legal_recruiting", "construction_staffing", "hospitality_staffing", "customer_support_outsourcing", "live_chat_agency", "technical_support_agency", "call_center_agency", "multilingual_support_agency", "community_management_agency", "management_consulting", "financial_consulting", "hr_consulting", "operations_consulting", "it_consulting", "sustainability_consulting", "legal_consulting", "compliance_consulting", "supply_chain_consulting", "change_management_consulting", "digital_transformation_consulting", "healthcare_consulting", "real_estate_consulting", "franchise_consulting", "export_trade_consulting", "nonprofit_consulting", "education_consulting", "cannabis_consulting", "restaurant_consulting", "m_and_a_consulting", "pricing_strategy_consulting", "brand_strategy_consulting", "saas_marketing_consulting", "done_for_you_services", "prop_firm_passing_service", "trading_account_management", "done_for_you_trading", "accounting_bookkeeping", "tax_preparation", "legal_services", "notary_services", "insurance_brokerage", "financial_planning_service", "real_estate_services", "property_management", "mortgage_brokerage", "immigration_services", "patent_trademark_services", "business_formation_services", "shell_company_formation", "payroll_services", "audit_services", "forensic_accounting", "actuarial_services", "appraisal_services", "mediation_arbitration", "bail_bond_services", "crowdfunding_platform", "essay_mill_paper_mill", "government_service_facilitation", "immigration_services_unlicensed", "licensed_legal_services", "personalized_tax_services", "private_investigation", "repossession_services", "unlicensed_legal_services", "record_label", "book_publishing_house", "news_media_outlet", "radio_broadcasting", "tv_production_company", "film_studio", "magazine_publisher", "music_licensing_agency", "talent_management_agency", "advertising_network", "ad_tech_platform", "cleaning_service", "landscaping_service", "plumbing_service", "electrical_service", "hvac_service", "roofing_service", "painting_service", "moving_service", "handyman_service", "pest_control", "pool_service", "solar_installation", "home_renovation", "pressure_washing", "junk_removal", "garage_door_service", "fencing_service", "concrete_masonry", "tree_service", "window_cleaning", "gutter_service", "flooring_service", "cabinet_countertop", "home_inspection", "septic_service", "waterproofing_service", "insulation_service", "chimney_service", "locksmith_service", "glass_window_service", "epoxy_coating", "private_security_guard_service", "armored_car_transport", "executive_protection_bodyguard", "event_security_service", "alarm_system_installation", "cctv_installation", "private_investigation_agency", "background_check_provider", "locksmith_commercial", "bounty_hunter_bail_enforcement", "personal_styling", "personal_chef", "personal_assistant_service", "tutoring_service", "pet_services", "wedding_planning", "concierge_service", "personal_training_service", "nanny_service", "elder_care_service", "errand_service", "life_organization", "relocation_service", "adult_dating_services", "escort_services", "hotel_accommodation_bookings", "mail_order_spouse", "psychic_fortune_telling", "timeshare_sales", "freight_brokerage", "courier_service", "warehousing_service", "last_mile_delivery", "auto_transport", "international_shipping", "cold_chain_logistics", "commercial_airline_tickets", "cruise_line_bookings", "contract_manufacturing", "cnc_machining_service", "3d_printing_service_commercial", "plastic_injection_molding", "metal_fabrication", "pcba_assembly", "chemical_manufacturing", "textile_manufacturing", "food_processing_facility", "packaging_manufacturing", "industrial_automation_integrator", "mining_and_extraction", "oil_and_gas_services", "renewable_energy_generation", "waste_management_recycling", "hazardous_waste_disposal", "aerospace_defense_contracting", "personal_training_studio", "nutrition_consulting", "mental_health_counseling", "physical_therapy_service", "occupational_therapy_service", "speech_therapy_service", "chiropractic_service", "acupuncture_service", "massage_therapy_service", "midwifery_doula", "lactation_consulting", "dietitian_service", "addiction_recovery_services", "dtc_lab_testing", "iv_therapy_infusion", "medspa_aesthetic_services", "prescription_delivery_services", "registered_dietitian_services", "unlicensed_therapy_counseling", "streetwear", "athleisure", "luxury_fashion", "kids_clothing", "custom_apparel", "workwear", "swimwear", "lingerie_intimates", "vintage_clothing", "plus_size_fashion", "maternity_clothing", "sleepwear_loungewear", "denim_brand", "outerwear_jackets", "socks_hosiery", "costumes_cosplay", "scrubs_medical_apparel", "dance_performance_wear", "hunting_camo_apparel", "casual_everyday_clothing", "protein_supplements", "vitamins_minerals", "pre_workout", "nootropics", "herbal_supplements", "weight_management_supplements", "gut_health", "cbd_products", "mushroom_supplements", "collagen_supplements", "testosterone_boosters", "sleep_supplements", "immune_support", "joint_bone_health", "greens_powder", "creatine_supplements", "electrolyte_hydration", "prenatal_supplements", "kids_supplements", "pet_supplements", "ayurvedic_supplements", "keto_supplements", "cannabis_thc_products", "cbd_hemp_products_compliant", "delta8_thc_products", "dietary_supplements", "drug_precursor_chemicals", "illegal_drugs", "kratom_kava_products", "medical_treatment_claims_product", "nutraceutical_products", "otc_medication_sales", "performance_enhancing_drugs", "research_chemicals_dangerous", "research_peptides", "sexual_enhancement_products", "tobacco_products", "unlicensed_rx_sales", "skincare", "haircare", "cosmetics_makeup", "mens_grooming", "fragrance", "oral_care", "sunscreen_spf", "hair_growth_products", "body_care", "deodorant", "lip_care", "acne_treatment", "men_skincare", "baby_skincare", "tattoo_aftercare", "intimate_care", "home_gym_equipment", "yoga_equipment", "combat_sports_gear", "outdoor_fitness_gear", "wearable_fitness", "recovery_equipment", "weightlifting_equipment", "cardio_equipment", "gymnastics_equipment", "swimming_gear", "jump_rope_equipment", "grip_strength_tools", "sauna_cold_plunge", "posture_correctors", "jewelry", "sunglasses_eyewear", "bags_wallets", "hats_headwear", "phone_accessories", "travel_accessories", "scarves_wraps", "belts", "hair_accessories", "tech_accessories", "keychains_charms", "custom_engraved_accessories", "cannabis_accessories_non_drug", "drug_paraphernalia", "high_value_goods_over_500", "precious_metals_stones", "replica_counterfeit_goods", "home_decor", "candles_scents", "kitchenware", "bedding_linens", "smart_home", "cleaning_products", "outdoor_furniture", "organization_storage", "wall_art_prints", "rugs_carpets", "lighting_fixtures", "planters_garden_decor", "bathroom_accessories", "luxury_home_goods", "seasonal_holiday_decor", "pet_home_products", "home_fragrance_diffusers", "hazardous_chemicals_b2c", "pre_orders_delayed_delivery", "audio_equipment", "camera_equipment", "gaming_hardware", "drones_robotics", "ev_accessories", "charging_power", "smart_wearables", "home_security_devices", "3d_printers", "projectors_displays", "streaming_devices", "vr_headsets", "e_readers", "portable_tech", "hardware_wallets", "regulated_medical_devices", "signal_jamming_devices", "spy_cameras_hidden_recording", "specialty_coffee_tea", "health_food", "snacks_treats", "sauces_condiments", "alcohol_spirits", "meal_kits", "baked_goods", "beverages", "pet_food_treats", "protein_bars_snacks", "jerky_meat_snacks", "chocolate_confections", "honey_sweeteners", "olive_oil_vinegar", "hot_sauce", "dried_fruit_nuts", "baby_food", "plant_based_food", "gluten_free_food", "keto_food_products", "subscription_food_box", "kombucha_fermented", "alcohol_sales", "baby_products", "kids_toys", "kids_educational", "baby_clothing_accessories", "nursery_decor", "kids_outdoor_play", "kids_books", "baby_safety_products", "kids_arts_crafts", "camping_hiking", "fishing_gear", "hunting_gear", "cycling_gear", "water_sports_gear", "golf_equipment", "snow_sports_gear", "climbing_gear", "archery_equipment", "skateboarding_gear", "pickleball_equipment", "tennis_equipment", "equestrian_gear", "tactical_gear", "overlanding_gear", "explosives_fireworks", "firearms_sales", "self_defense_products", "weapon_components", "craft_kits", "sewing_textiles", "stationery", "scrapbooking_supplies", "beading_jewelry_supplies", "pottery_supplies", "printmaking_supplies", "car_accessories", "detailing_products", "motorcycle_gear", "truck_accessories", "off_road_parts", "car_audio_electronics", "performance_parts", "car_care_products", "ev_charging_accessories", "auto_repair_service", "auto_body_shop", "car_dealership", "car_wash", "tire_shop", "oil_change_shop", "auto_parts_store", "motorcycle_shop", "ev_charging_station", "transmission_shop", "muffler_exhaust_shop", "auto_glass_shop", "auto_upholstery_shop", "car_audio_shop", "smog_emissions_shop", "truck_repair_shop", "rv_repair_shop", "boat_repair_shop", "used_car_lot", "auto_auction", "dog_products", "cat_products", "aquarium_supplies", "bird_supplies", "reptile_supplies", "horse_supplies", "pet_apparel", "pet_tech", "pet_grooming_products", "hand_tools", "power_tools_and_accessories", "hardware_and_fasteners", "workshop_equipment_and_storage", "safety_and_work_gear", "painting_and_building_supplies", "office_supplies", "desk_accessories", "printing_supplies", "shipping_packaging", "reusable_products", "solar_powered_products", "christian_books_bibles", "christian_apparel", "christian_jewelry", "christian_home_decor", "jewish_judaica", "jewish_books_torah", "jewish_apparel", "islamic_books_quran", "islamic_apparel", "islamic_prayer_goods", "hindu_puja_supplies", "hindu_books_texts", "buddhist_meditation_goods", "buddhist_books_texts", "sikh_religious_goods", "other_religious_products", "handmade_goods_marketplace", "vintage_resale_marketplace", "electronics_marketplace", "auto_parts_marketplace", "luxury_goods_marketplace", "collectibles_marketplace", "wholesale_marketplace", "local_goods_marketplace", "sneaker_marketplace", "book_marketplace", "furniture_marketplace", "musical_instrument_marketplace", "art_marketplace", "ticket_marketplace", "industrial_equipment_marketplace", "craft_supply_marketplace", "baby_kids_marketplace", "outdoor_gear_marketplace", "pet_marketplace", "sustainable_goods_marketplace", "cultural_artifacts_looted", "dropshipping_operations", "endangered_animal_products", "human_body_parts_tissue", "nft_marketplace", "penny_auction", "primary_event_ticketing", "freelancer_marketplace", "home_services_marketplace", "tutoring_marketplace", "legal_services_marketplace", "healthcare_marketplace", "wedding_services_marketplace", "creative_and_content_creation_marketplace", "beauty_services_marketplace", "fitness_trainer_marketplace", "pet_services_marketplace", "childcare_marketplace", "elder_care_marketplace", "translation_marketplace", "coaching_marketplace", "therapy_marketplace", "photography_marketplace", "dj_entertainment_marketplace", "auto_services_marketplace", "freelance_marketplace_operator", "equipment_rental_marketplace", "vehicle_rental_marketplace", "space_rental_marketplace", "vacation_rental_marketplace", "clothing_rental_marketplace", "camera_gear_rental", "rv_camper_rental", "boat_rental_marketplace", "storage_rental_marketplace", "office_coworking_rental", "parking_rental_marketplace", "restaurant_marketplace", "grocery_marketplace", "catering_marketplace", "homemade_food_marketplace", "meal_prep_marketplace", "bakery_marketplace", "farm_produce_marketplace", "chef_booking_marketplace", "course_marketplace", "template_marketplace", "stock_media_marketplace", "music_beats_marketplace", "ebook_marketplace", "plugin_theme_marketplace", "3d_model_marketplace", "prompt_marketplace", "code_snippet_marketplace", "affiliate_marketing_platform", "game_cheats_hacks", "weapon_blueprint_distribution", "saas_marketplace", "agency_marketplace", "manufacturing_marketplace", "logistics_marketplace", "commercial_real_estate_marketplace", "business_for_sale_marketplace", "food_delivery", "grocery_delivery", "package_delivery", "moving_labor", "alcohol_delivery", "pharmacy_delivery", "flower_delivery_gig", "furniture_delivery_gig", "catering_delivery", "rideshare", "chauffeur_service", "bike_scooter_rental", "boat_charter_gig", "moving_truck_rental_gig", "assembly_installation", "waiting_line_service", "personal_shopping", "grocery_shopping_gig", "gift_wrapping_gig", "notary_gig", "laundry_gig", "car_wash_gig", "cleaning_gig", "lawn_care_gig", "handyman_gig", "pet_care_gig", "childcare_gig", "elder_care_gig", "painting_gig", "snow_removal_gig", "pool_cleaning_gig", "organizing_gig", "pressure_washing_gig", "junk_removal_gig", "consulting_gig", "accounting_gig", "legal_gig", "healthcare_gig", "teaching_gig", "translation_gig", "data_entry_gig", "research_gig", "virtual_assistant_gig", "sales_gig", "recruiting_gig", "mystery_shopping", "focus_group_gig", "product_testing_gig", "drone_pilot_gig", "fitness_instruction_gig", "tour_guide_gig", "dating_community", "personal_development_community", "spirituality_community", "parenting_community", "travel_community", "networking_community", "faith_community", "mens_community", "womens_community", "expat_community", "adult_community_nsfw", "hate_violence_communities", "personal_fundraising", "political_fundraising", "political_organizations", "pornographic_content", "registered_501c3", "religious_organization", "unregistered_charities", "ai_outreach_tool", "ai_chatbot_software", "ai_writing_tool", "ai_image_generator", "ai_video_tool", "ai_voice_tool", "ai_data_analysis", "ai_code_assistant", "ai_meeting_assistant", "workflow_automation_software", "ai_sales_tool", "ai_customer_support", "ai_recruiting_tool", "ai_translation_tool", "ai_music_tool", "ai_presentation_tool", "ai_research_tool", "ai_seo_tool", "ai_social_media_tool", "ai_phone_agent", "ai_legal_tool", "ai_healthcare_tool", "llm_api_platform", "ai_agent_platform", "generative_ai_platform", "celebrity_impersonation", "deepfake_service", "ai_nsfw_content_generator", "ecommerce_platform", "product_research_tool", "price_tracker", "shipping_software", "print_on_demand_software", "marketplace_seller_tool", "resale_arbitrage_tool", "reseller_management_tool", "product_review_software", "returns_management", "product_feed_management", "checkout_optimization", "wholesale_ordering", "project_management_software", "team_communication", "video_conferencing", "document_collaboration", "time_tracking_software", "scheduling_software", "hr_software", "knowledge_base_software", "form_survey_builder", "note_taking_app", "task_management", "contract_management", "expense_management", "okr_goal_tracking", "employee_engagement", "onboarding_software", "applicant_tracking", "asset_management", "facility_management", "visitor_management", "community_platform", "event_management_software", "webinar_software", "school_management", "newsletter_platform", "podcast_hosting", "forum_software", "virtual_classroom", "restaurant_pos", "salon_software", "gym_management_software", "auto_shop_software", "legal_practice_software", "church_management", "nonprofit_software", "logistics_software", "agriculture_software", "field_service_software", "marina_management", "hotel_pms", "childcare_management", "cleaning_business_software", "roofing_software", "landscaping_software", "pest_control_software", "tattoo_studio_software", "cannabis_software", "password_manager", "cybersecurity_software", "identity_verification", "backup_recovery", "endpoint_protection", "email_security", "access_management", "compliance_software", "data_privacy_tool", "vpn_services", "people_search_tool", "game_mod_tool", "streaming_tool", "game_server_hosting", "music_software", "video_editing_software", "photo_editing_software", "animation_software", "audio_editing_software", "screen_recording_software", "sports_betting_tool", "fantasy_sports_paid_entry", "iptv_pirated_streaming", "loot_boxes_gacha", "skill_contests_free_entry", "skill_contests_paid_entry", "only_fans_management_software", "pornography_platform", "business_phone_system", "customer_messaging", "digital_key_reselling", "streaming_account_reselling", "subscription_account_sharing", "account_generation_tool", "primary_care_telehealth", "urgent_care_telehealth", "pediatric_telehealth", "geriatric_telehealth", "family_medicine_telehealth", "internal_medicine_telehealth", "preventive_care_telehealth", "licensed_online_pharmacy", "telemedicine_practitioner_services", "dermatology_telehealth", "acne_telehealth", "psoriasis_eczema_telehealth", "skin_cancer_screening_tele", "cosmetic_dermatology_tele", "therapy_telehealth", "psychiatry_telehealth", "addiction_telehealth", "couples_therapy_telehealth", "child_psychology_telehealth", "eating_disorder_telehealth", "ptsd_trauma_telehealth", "adhd_telehealth", "anxiety_depression_telehealth", "ocd_telehealth", "grief_counseling_telehealth", "anger_management_telehealth", "family_therapy_telehealth", "group_therapy_telehealth", "licensed_psychedelic_therapy", "womens_health_telehealth", "mens_health_telehealth", "sexual_health_telehealth", "fertility_telehealth", "hormone_therapy_telehealth", "menopause_telehealth", "prenatal_telehealth", "postpartum_telehealth", "erectile_dysfunction_tele", "hair_loss_telehealth", "birth_control_telehealth", "sti_testing_telehealth", "dental_telehealth", "orthodontics_telehealth", "optometry_telehealth", "oral_surgery_consultation", "vision_therapy_telehealth", "cardiology_telehealth", "endocrinology_telehealth", "neurology_telehealth", "orthopedic_telehealth", "allergy_telehealth", "ent_telehealth", "rheumatology_telehealth", "gastroenterology_telehealth", "infectious_disease_telehealth", "pulmonology_telehealth", "nephrology_telehealth", "oncology_telehealth", "hematology_telehealth", "urology_telehealth", "weight_management_telehealth", "glp1_weight_loss_tele", "diabetes_management_tele", "metabolic_health_tele", "bariatric_telehealth", "physical_therapy_telehealth", "occupational_therapy_tele", "speech_therapy_telehealth", "pain_management_telehealth", "cardiac_rehab_telehealth", "pelvic_floor_telehealth", "vestibular_telehealth", "sleep_medicine_telehealth", "chronic_disease_management", "chronic_pain_telehealth", "migraine_telehealth", "asthma_copd_telehealth", "nutrition_telehealth", "naturopathic_telehealth", "functional_medicine_telehealth", "acupuncture_telehealth", "health_coaching_telehealth", "integrative_medicine_tele", "ayurvedic_telehealth", "genetic_counseling_telehealth", "pharmacogenomics_tele", "rare_disease_telehealth", "second_opinion_telehealth", "vet_telehealth", "pet_behavior_telehealth", "exotic_pet_telehealth", "equine_telehealth", "veterinary_services", "class_action_settlement", "mastermind_event", "webinar_event", "virtual_summit", "bootcamp_event", "workshop_seminar", "hackathon", "corporate_training_event", "training_certification_event", "convention_expo", "conference_summit", "industry_awards_event", "product_launch_event", "investor_demo_day", "panel_discussion_event", "pitch_competition", "meetup_event", "dinner_event", "alumni_event", "community_gathering", "singles_event", "professional_happy_hour", "women_networking_event", "founders_dinner", "industry_mixer", "concert_event", "comedy_show", "theater_performance", "film_screening", "music_festival", "cultural_festival", "fashion_show", "drag_show", "magic_show", "dance_performance", "poetry_spoken_word", "art_exhibition", "party_event", "trivia_night", "wine_tasting_event", "beer_festival", "car_show", "food_festival", "fitness_challenge_event", "marathon_race", "tournament_event", "fight_event", "yoga_retreat_event", "outdoor_adventure_event", "esports_tournament", "obstacle_course_race", "cycling_event", "swim_meet", "golf_tournament", "pickleball_tournament", "crossfit_competition", "martial_arts_tournament", "surfing_competition", "wellness_retreat", "spiritual_retreat", "couples_retreat", "plant_medicine_retreat", "luxury_experience_event", "detox_retreat", "silent_retreat", "creative_retreat", "leadership_retreat", "mens_retreat", "womens_retreat", "digital_detox_retreat", "fundraiser_event", "awareness_event", "volunteer_event", "charity_auction", "benefit_concert", "charity_run_walk", "environmental_cleanup", "family_festival", "kids_event", "holiday_event", "farmers_market_event", "block_party", "graduation_ceremony", "memorial_event", "stock_market_newsletter", "crypto_newsletter", "personal_finance_newsletter", "real_estate_newsletter", "fintech_newsletter", "venture_capital_newsletter", "options_trading_newsletter", "forex_newsletter", "macro_economics_newsletter", "alternative_investing_newsletter", "tax_strategy_newsletter", "ai_newsletter", "tech_industry_newsletter", "cybersecurity_newsletter", "developer_newsletter", "product_newsletter", "devops_newsletter", "open_source_newsletter", "robotics_newsletter", "climate_tech_newsletter", "travel_newsletter", "fashion_newsletter", "parenting_newsletter", "sports_newsletter", "gaming_newsletter", "music_entertainment_newsletter", "book_reading_newsletter", "dating_relationships_newsletter", "home_design_newsletter", "pet_newsletter", "wine_spirits_newsletter", "automotive_newsletter", "political_newsletter", "geopolitics_newsletter", "media_journalism_newsletter", "defense_security_newsletter", "legal_policy_newsletter", "design_newsletter", "education_newsletter", "science_newsletter", "philosophy_newsletter", "sustainability_newsletter", "architecture_newsletter", "history_newsletter", "psychology_newsletter", "career_newsletter", "spirituality_newsletter", "self_improvement_newsletter", "productivity_newsletter", "faith_newsletter", "gym_facility", "crossfit_box", "yoga_studio", "pilates_studio", "martial_arts_gym", "boxing_gym", "climbing_gym", "dance_studio", "swimming_pool", "sports_facility", "golf_course", "bowling_alley", "skating_rink", "trampoline_park", "tennis_club", "pickleball_facility", "gymnastics_center", "spin_studio", "barre_studio", "personal_training_studio_bm", "recovery_studio", "indoor_soccer", "batting_cage", "shooting_range", "archery_range", "equestrian_center", "fine_dining", "fast_casual_restaurant", "steakhouse", "seafood_restaurant", "pizza_shop", "sushi_restaurant", "deli_sandwich_shop", "bbq_restaurant", "mexican_restaurant", "italian_restaurant", "chinese_restaurant", "indian_restaurant", "thai_restaurant", "korean_restaurant", "mediterranean_restaurant", "vegan_vegetarian_restaurant", "brunch_restaurant", "ramen_noodle_shop", "poke_bowl_shop", "ethnic_restaurant", "coffee_shop_cafe", "bakery", "juice_smoothie_bar", "ice_cream_shop", "donut_shop", "bubble_tea_shop", "food_truck", "fast_food", "ghost_kitchen", "food_hall_vendor", "catering_kitchen", "butcher_shop", "cheese_shop", "farmers_market_stall", "bar_lounge", "brewery_taproom", "winery_tasting", "wine_bar", "cocktail_bar", "sports_bar", "hookah_lounge", "distillery", "commercial_farming", "livestock_ranching", "hydroponic_vertical_farming", "forestry_logging", "aquaculture_fisheries", "vineyard_winery_production", "cannabis_cultivation", "hemp_farming", "grain_production", "agricultural_cooperative", "fertilizer_pesticide_sales", "farm_equipment_sales", "boutique_store", "clothing_store", "shoe_store", "jewelry_store", "electronics_store", "bookstore", "pet_store", "toy_store", "sporting_goods_store", "thrift_store", "smoke_shop", "cannabis_dispensary", "convenience_store", "grocery_store", "liquor_store", "florist", "gift_shop", "furniture_store", "home_improvement_store", "art_gallery_retail", "music_instrument_store", "outdoor_recreation_store", "phone_repair_store", "watch_store", "bridal_shop", "maternity_store", "kids_store", "sneaker_store", "vintage_store", "comic_book_store", "record_store", "craft_supply_store", "fabric_store", "health_food_store", "vitamin_supplement_store", "optical_store", "mattress_store", "appliance_store", "kitchen_bath_store", "tile_flooring_store", "paint_store", "garden_center", "gun_store", "pawn_shop", "dollar_store", "hair_salon", "nail_salon", "day_spa", "med_spa", "massage_studio", "tattoo_parlor", "tanning_salon", "beauty_supply_store", "lash_brow_studio", "waxing_studio", "sauna_bathhouse", "cryotherapy_studio", "float_sensory_studio", "iv_therapy_lounge", "teeth_whitening_studio", "microblading_studio", "spray_tan_studio", "blowout_bar", "mens_barbershop", "kids_salon", "medical_office", "dental_office", "chiropractic_office", "physical_therapy_clinic", "optometry_office", "dermatology_clinic", "urgent_care_clinic", "pharmacy", "veterinary_clinic", "mental_health_clinic", "fertility_clinic", "acupuncture_clinic", "hearing_aid_center", "orthopedic_clinic", "pediatric_clinic", "cosmetic_surgery_center", "allergy_clinic", "pain_management_clinic", "dialysis_center", "imaging_center", "lab_testing_center", "sleep_clinic", "weight_loss_clinic", "hormone_therapy_clinic", "addiction_treatment_center", "rehabilitation_center", "occupational_therapy_clinic", "speech_therapy_clinic", "wound_care_center", "funeral_home_mortuary", "crematory_service", "cemetery_memorial_park", "casket_urn_retailer", "pet_cremation_service", "biohazard_cleanup", "estate_liquidation", "hotel", "motel", "boutique_hotel", "bed_and_breakfast", "hostel", "resort", "campground_rv", "vacation_rental_property", "extended_stay", "glamping_site", "cabin_rental", "eco_lodge", "retreat_center", "tutoring_center", "daycare_center", "preschool", "learning_center", "music_school", "art_school", "driving_school", "language_school", "trade_school", "coding_bootcamp_location", "montessori_school", "after_school_program", "swim_school", "cooking_school", "test_prep_center", "special_needs_center", "adult_education_center", "flight_school", "cosmetology_school", "movie_theater", "escape_room", "arcade", "mini_golf", "laser_tag", "go_kart", "amusement_park", "museum", "zoo_aquarium", "theater_venue", "nightclub", "karaoke_bar", "comedy_club", "live_music_venue", "axe_throwing", "virtual_reality_arcade", "board_game_cafe", "cat_cafe", "haunted_house", "water_park", "indoor_playground", "concert_venue", "drive_in_theater", "billiards_hall", "dart_bar", "indoor_skydiving", "law_office", "real_estate_office", "insurance_office", "accounting_office", "bank_credit_union", "printing_shop", "shipping_center", "dry_cleaner", "laundromat", "storage_facility", "coworking_space", "check_cashing", "title_company", "travel_agency_storefront", "staffing_office", "financial_advisor_office", "immigration_office", "bail_bonds_office", "pet_grooming", "dog_daycare", "pet_boarding", "dog_training_facility", "pet_spa", "aquatic_pet_store", "pet_bakery", "pet_photography_studio", "plumbing_showroom", "hvac_showroom", "solar_showroom", "kitchen_design_showroom", "bath_design_showroom", "window_door_showroom", "pool_spa_showroom", "fireplace_showroom", "countertop_showroom", "nonprofit_organization", "charity_foundation", "political_campaign", "community_organization", "environmental_nonprofit", "education_nonprofit", "health_nonprofit", "animal_welfare_nonprofit", "arts_culture_nonprofit", "social_justice_nonprofit", "veterans_nonprofit", "youth_nonprofit", "disaster_relief_nonprofit", "food_bank", "housing_nonprofit", "government_agency", "public_utility", "public_library", "public_school", "municipal_service", "military_installation", "embassy_consulate", "niche_service", "niche_product", "hybrid_business", "other_general", "holding_company", "family_office", "cooperative", "social_enterprise", "incubator_accelerator", "coworking_community", "media_company", "research_lab", null ], "example": "other", "type": [ "string", "null" ], "x-whop-hide-enum-values": true }, "invoice_prefix": { "description": "Prefix used for account invoices.", "example": "SHINE", "type": [ "string", "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": "shop_4417", "region": "austin" }, "type": "object" }, "onboarding_type": { "description": "Type of onboarding the account has completed.", "enum": [ "platform", "seller", null ], "example": "seller", "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" ] }, "other_business_description": { "description": "Business type details when business_type is `other`.", "example": "Mobile auto detailing", "type": [ "string", "null" ] }, "other_industry_description": { "description": "Industry details when industry_type is `other`.", "example": "Automotive services", "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" } ] }, "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" } ] }, "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 /recommended_actions?account_id={account_id}` endpoint instead.", "items": { "$ref": "#/components/schemas/AccountRecommendedAction", "description": "Deprecated: use the `GET /recommended_actions?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": true, "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" } ] }, "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" }, "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": { "items": { "$ref": "#/components/schemas/AccountSocialLink", "description": "Account social links." }, "type": "array" }, "stablecoin_rails": { "description": "Whether the account settles on stablecoin rails — its balance is held on-chain as USDT and paid out over crypto, rather than as fiat cash.", "example": false, "type": "boolean" }, "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, in language safe to show the account owner. Computed on `retrieve`, `me`, and `suspend`; `null` otherwise, when `status` is not `suspended`, and when the suspension was recorded without a reason.", "example": "Payments are paused while we review recent chargebacks on this account.", "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": "Account-level 3D Secure behavior. `mandate_challenge` requires cardholder verification on supported card payments; `null` uses the standard checkout flow.", "enum": [ "mandate_challenge", 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, "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" ] }, "use_logo_as_opengraph_image_fallback": { "description": "Whether the account uses its logo as the fallback Open Graph image.", "example": true, "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_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" } ] } }, "required": [ "id", "email", "title", "description", "route", "logo_url", "banner_image_url", "terms_of_service", "privacy_policy", "return_policy", "eula", "business_type", "country", "home_preferences", "industry_group", "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", "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", "capabilities", "payment_controls", "cards", "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", "stablecoin_rails", "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" }, "in_transit": { "description": "Amount moving between the account's own destinations, such as a treasury sweep to its crypto wallet or 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 with no scheduled settlement day, such as a transfer in flight, is left out — so these 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" ], "type": "object" }, "AccountBalanceSettlement": { "properties": { "amount": { "description": "Amount expected that day, in native units, as a decimal string.", "example": "12.5", "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": "50.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. On-chain crypto is entirely available; good_funds and fiat cash can have pending or reserve portions." }, "icon_url": { "description": "Holding icon URL.", "example": "https://assets.whop.com/tokens/usd.png", "type": [ "string", "null" ] }, "name": { "description": "The holding's display name", "example": "US Dollar", "type": "string" }, "price_usd": { "description": "USD price per unit, or `null` when no exchange rate is available.", "example": 1, "type": [ "number", "null" ] }, "symbol": { "description": "Holding display symbol, such as `USDT`, `cbBTC`, or `EUR`.", "example": "USD", "type": "string" }, "value_usd": { "description": "Holding USD value, or `null` when no exchange rate is available.", "example": "50.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": "active", "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` while a requested ads services agreement is awaiting the account's signature.", "enum": [ "active", "inactive", "pending" ], "example": "active", "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 while `status` is `pending`.", "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`.", "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" }, "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" }, "AccountParent": { "properties": { "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" }, "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, "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" ], "example": "card_visa", "type": "string" }, "type": "array" }, "undated_pending_reason": { "description": "Why pending funds without a settlement date aren't moving yet, when it's something the merchant can act on. `null` when there's no reason to show (still clearing, or the account is held for a reason that isn't merchant-actionable).", "enum": [ "kyc_incomplete", "pending_information_request", 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" }, "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" }, "AccountRecommendedActionChain": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/AccountRecommendedActionChainStep", "description": "The chain's steps in run order" }, "type": "array" }, "description": { "description": "What running the chain accomplishes", "example": "Get your product in front of buyers", "type": "string" }, "id": { "description": "Chain ID — `rac_seed__` for seeded chains, `rac_chain_*` for generated ones", "example": "rac_chain_xxxxxxxxxxxx", "type": "string" }, "reasoning": { "description": "Why this chain was recommended, or `null` when unavailable", "example": { "summary": "No active campaigns yet" }, "type": [ "object", "null" ] }, "title": { "description": "Headline for the chain", "example": "Launch an ad campaign", "type": "string" } }, "required": [ "id", "title", "description", "reasoning", "actions" ], "type": "object" }, "AccountRecommendedActionChainStep": { "properties": { "action": { "description": "The action definition key this step runs; new values may be added, so handle unknown actions gracefully", "example": "create_ad_xxxxxxxxxxxxxx", "type": "string" }, "cta": { "description": "The URL where this step is done by hand", "example": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/marketing/ads", "type": "string" }, "cta_label": { "description": "Button label", "example": "Create campaign", "type": "string" }, "description": { "description": "Supporting copy, or empty", "example": "Pick a budget", "type": "string" }, "error": { "description": "Why the step failed, or `null`", "type": [ "string", "null" ] }, "execution_type": { "description": "Whether the client should navigate to the CTA, open the programmatic execution dialog, or run the CTA as a Whop AI prompt", "enum": [ "redirect", "programatic", "whop_ai" ], "example": "redirect", "type": "string" }, "input": { "description": "The filled-in request body for the step's endpoint, or `null` when it was not recorded", "example": { "name": "Ceramic coating — Austin launch" }, "type": [ "object", "null" ] }, "output": { "description": "The API response the step produced, or `null` until it succeeds", "type": [ "object", "null" ] }, "position": { "description": "Zero-based order of this step within the chain", "example": 0, "type": "integer" }, "reasoning": { "description": "Why this step was recommended, or `null` when unavailable", "example": { "summary": "Create the campaign first" }, "type": [ "object", "null" ] }, "status": { "description": "Where the run step currently stands, or `null` when the chain has not been run", "enum": [ "pending", "redirected", "running", "succeeded", "failed", null ], "example": "pending", "type": [ "string", "null" ] }, "title": { "description": "Headline for the step", "example": "Create a campaign", "type": "string" } }, "required": [ "position", "action", "input", "output", "status", "error", "title", "description", "reasoning", "cta_label", "cta", "execution_type" ], "type": "object" }, "AccountRequiredAction": { "properties": { "action": { "description": "What the holder must do; new values may be added, so handle unknown actions gracefully", "enum": [ "deposit_funds", "submit_information_request", "update_automatic_withdrawal_method", "reauthorize_payout_methods", "update_payout_profile", "card_usage_review", "verify_identity", "sign_formation_documents", "connect_fulfillment_tracker", "setup_apple_pay_domains", "configure_tax_remitter", "add_vat_registration" ], "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. `usd` and `usdt` 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, "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, "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" }, "date": { "description": "The day this money unlocks, as an ISO 8601 date.", "example": "2026-01-01", "type": "string" } }, "required": [ "date", "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" }, "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": "Shine Time Auto Detailing", "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`.", "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.", "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, "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", 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, "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, "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 }, "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": [ "rejected", "in_review", "draft", "campaign_paused", "ad_group_paused", "paused", "processing", "issues", "scheduled", "learning_limited", "learning", "active" ], "example": "paused", "type": "string" }, "descriptions": { "items": { "description": "The description variants shown on the ad.", "example": "Paint correction included", "type": "string" }, "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" ] }, "frequency": { "description": "Platform-reported impressions divided by reach.", "type": [ "number", "null" ] }, "headlines": { "items": { "description": "The headline variants shown on the ad.", "example": "Austin's mobile detailers", "type": "string" }, "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, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 121, "type": "number" }, "link_clicks": { "description": "Clicks on links in the ad that lead to your destination, as reported by the ad platform. A subset of clicks, which also counts likes, comments, and other interactions with the ad.", "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" } ] }, "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": { "description": "The primary text variants shown in the ad body.", "example": "Book a two-day ceramic coating and keep the shine for three years.", "type": "string" }, "type": "array" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 9462, "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, "type": "number" }, "schedules": { "description": "Whop pixel-attributed schedule events, last-click.", "example": 46, "type": "number" }, "social_accounts": { "items": { "$ref": "#/components/schemas/AdEntityReference", "description": "The social accounts the ad runs under — its Facebook page and Instagram profile — each referenced by ID, prefixed `sacc_`." }, "type": "array" }, "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, "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" ] }, "unique_click_through_rate": { "description": "Unique clicks divided by impressions, between 0 and 1.", "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, "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", "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", "social_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, "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 the ad account's currency. `null` when each ad group sets its own budget instead.", "example": 50, "type": [ "number", "null" ] }, "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" ] }, "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, "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, "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, "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, "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, "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, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Spend per 1,000 impressions; 0 when there are no impressions.", "example": 6, "type": "number" }, "cost_per_purchase": { "description": "Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.", "example": 30, "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, "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, "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, "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, "quote_requested": 0 }, "type": "object" }, "delivery_status": { "description": "Whether the campaign's ads are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.", "enum": [ "payment_failed", "all_ads_rejected", "draft", "no_ad_groups", "no_ads", "paused", "processing", "issues", "scheduled", "completed", "ad_groups_off", "active" ], "example": "issues", "type": "string" }, "frequency": { "description": "Platform-reported impressions divided by reach.", "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, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 132, "type": "number" }, "link_clicks": { "description": "Clicks on links in the ad that lead to your destination, as reported by the ad platform. A subset of clicks, which also counts likes, comments, and other interactions with the ad.", "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.", "type": [ "string", "null" ] }, "platform": { "description": "The ad network the campaign runs on.", "enum": [ "meta", "tiktok" ], "example": "meta", "type": "string" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 7920, "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, "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, "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, "type": "number" }, "spend_currency": { "description": "The ISO 4217 currency code of all monetary metrics.", "example": "usd", "type": [ "string", "null" ] }, "status": { "description": "The lifecycle status of the ad campaign.", "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, "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.", "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, "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", "objective", "special_ad_categories", "optimization_goal", "budget_amount", "budget_type", "budget_optimization", "created_at", "updated_at", "issues" ], "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" }, "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" ], "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, "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 the ad account's currency. `null` when the budget is set on the campaign instead.", "example": 60, "type": [ "number", "null" ] }, "budget_type": { "description": "Whether `budget_amount` is spent per day (`daily`) or over the ad group's full run (`lifetime`).", "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, "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, "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, "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, "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, "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, "type": [ "number", "null" ] }, "cost_per_mille": { "description": "Spend per 1,000 impressions; 0 when there are no impressions.", "example": 6, "type": "number" }, "cost_per_purchase": { "description": "Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.", "example": 30, "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, "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, "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, "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, "quote_requested": 0 }, "type": "object" }, "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": [ "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, "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.", "type": [ "number", "null" ] }, "frequency_cap": { "description": "Cap on how often one person sees ads from this ad group. Only available on campaigns with the `awareness` objective; `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" }, "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, "type": "number" }, "leads": { "description": "Whop pixel-attributed leads, last-click.", "example": 132, "type": "number" }, "link_clicks": { "description": "Clicks on links in the ad that lead to your destination, as reported by the ad platform. A subset of clicks, which also counts likes, comments, and other interactions with the ad.", "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, "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" }, "purchase_value": { "description": "USD value of pixel-attributed purchases.", "example": 7920, "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, "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, "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, "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, "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.", "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, "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", "optimization_goal", "conversion_event", "budget_amount", "budget_type", "bid_type", "desired_cost_per_result", "starts_at", "ends_at", "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": { "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, "type": "number" } }, "required": [ "latitude", "longitude", "radius", "distance_unit" ], "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": { "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" }, "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" ] }, "description": { "description": "Body text under the headline.", "example": "We book coatings two days out, so pick a slot when we ring.", "type": [ "string", "null" ] }, "headline": { "description": "Headline of the completion screen.", "example": "Thanks — we will call you today", "type": [ "string", "null" ] }, "url": { "description": "Website the follow-up button opens. `null` when the screen has no button.", "example": "https://shinetime.example/gallery", "type": [ "string", "null" ] } }, "required": [ "headline", "description", "button_text", "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" }, "AdPlatformIssue": { "properties": { "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 was rejected for unacceptable business practices. Edit the ad's content 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" } }, "required": [ "id", "message", "resource_id", "resource_type" ], "type": "object" }, "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" ], "example": "2026-09-06", "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" }, "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://booking.shinetime.example", "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" }, "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" }, "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": { "description": "Full URL where the app's hosted web build is served, or `null` if no route is claimed.", "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" }, "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" ] }, "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" ] }, "previous_hosted_urls": { "items": { "description": "URLs the hosted web build was previously served at, most recent first. Populated when the route is changed; the old URL stops serving and is not redirected, but traffic recorded against it still belongs to this app.", "example": "https://shine-time-booking.whop.site", "type": "string" }, "type": "array" }, "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": { "description": "Claimed subdomain route where hosted web builds are served (`myapp` for myapp.whop.site), or `null` if no route is claimed.", "example": "shine-time-booking", "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", "previous_hosted_urls", "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", "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", "deployment", "elements_used", "preview_token" ], "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/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": "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" }, "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.", "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.", "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.", "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.", "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" }, "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" }, "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.", "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" }, "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" }, "experience_path": { "description": "URL path for the member-facing hub view, or `null` when not configured.", "example": "/experiences/[experienceId]", "type": [ "string", "null" ] }, "hosted_url": { "description": "Full URL where the app's hosted web build is served, or `null` if no route is claimed.", "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" }, "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" ] }, "previous_hosted_urls": { "items": { "description": "URLs the hosted web build was previously served at, most recent first. Populated when the route is changed; the old URL stops serving and is not redirected, but traffic recorded against it still belongs to this app.", "type": "string" }, "type": "array" }, "route": { "description": "Claimed subdomain route where hosted web builds are served (`myapp` for myapp.whop.site), or `null` if no route is claimed.", "example": "shine-time-booking", "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": "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", "previous_hosted_urls", "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" ], "type": "object" }, "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" }, "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" }, "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" }, "social_account_id": { "description": "Connected social account ID, prefixed `sacc_`, with advertising access.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "object", "social_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" }, "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" }, "social_account_id": { "description": "Connected social account ID, prefixed `sacc_`, with advertising access.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "object", "social_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" }, "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 social 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" }, "social_account_id": { "description": "Connected social account ID, prefixed `sacc_`, with advertising access.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "object", "social_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" }, "object": { "description": "Engagement source.", "enum": [ "video" ], "example": "video", "type": "string" }, "platform_video_ids": { "items": { "description": "Numeric platform video IDs belonging to the selected social 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" }, "social_account_id": { "description": "Connected social account ID, prefixed `sacc_`, with advertising access.", "example": "sacc_xxxxxxxxxxxxxx", "type": "string" } }, "required": [ "object", "social_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, "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, "type": [ "number", "null" ] } }, "required": [ "platform", "status", "lower_bound", "upper_bound" ], "type": "object" }, "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, "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.", "type": [ "string", "null" ] }, "discussion_feed_id": { "description": "Forum feed containing the bounty's discussion thread. `null` for a bounty with no forum post.", "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.", "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, "type": "number" }, "gross_reward_amount": { "description": "Gross bounty-pool amount allocated per accepted submission, in whole currency units.", "example": 40, "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, "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, "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.", "type": [ "string", "null" ] }, "discussion_feed_id": { "description": "Forum feed containing the bounty's discussion thread. `null` for a bounty with no forum post.", "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.", "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, "type": "number" }, "gross_reward_amount": { "description": "Gross bounty-pool amount allocated per accepted submission, in whole currency units.", "example": 15, "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.", "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": { "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_3", "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" }, "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, "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, "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" }, "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" }, "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" }, "ConfirmationToken": { "properties": { "billing_details": { "description": "Enough of the billing details to raise a customer record and recognise the method — email, name, country and postal code. The street address is collected for the charge but never returned; this endpoint is a display-safe preview.", "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", "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." }, "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" }, "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" }, "Dispute": { "properties": { "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, "type": "number" }, "buyer": { "description": "The customer who filed the dispute.", "oneOf": [ { "$ref": "#/components/schemas/DisputeBuyer" }, { "type": "null" } ] }, "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. Whop reserves the last 24 hours before the processor's own cutoff to forward the submission.", "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" ] }, "generated_response_attachment": { "description": "The AI-generated representment document filed with the processor on the seller's behalf, once ready. Null until generation completes, and for disputes not using Whop Dispute Fighter.", "oneOf": [ { "$ref": "#/components/schemas/DisputeAttachment" }, { "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" }, "payment": { "description": "The payment being disputed.", "oneOf": [ { "$ref": "#/components/schemas/DisputePayment" }, { "type": "null" } ] }, "plan_id": { "description": "The plan the disputed payment was made on, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product the disputed payment was for, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "rapid_dispute_resolution": { "description": "Whether Visa Rapid Dispute Resolution settled this automatically. These refund the customer without an evidence round.", "example": false, "type": "boolean" }, "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 `closed` ended without a ruling. A dispute past its `evidence_due_at` reports `under_review` — the window to respond has closed.", "enum": [ "needs_response", "under_review", "won", "lost", "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" } }, "required": [ "id", "status", "inquiry", "amount", "currency", "reason", "reason_code", "issuer_comments", "account_id", "product_id", "plan_id", "rapid_dispute_resolution", "evidence_editable", "evidence_locked_reason", "evidence_due_at", "evidence_submitted_at", "buyer", "payment", "evidence", "generated_response_attachment", "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" ] }, "actionable": { "description": "Whether refunding the payment can still avoid a chargeback. `false` once the payment has been disputed or fully refunded, or when the alert could not be matched to a payment — `not_actionable_reason` says which.", "example": false, "type": "boolean" }, "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, "type": "number" }, "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_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": { "description": "Name of the bank that issued the card and filed the report.", "type": [ "string", "null" ] }, "not_actionable_reason": { "description": "Why refunding can no longer avoid a chargeback. `network_resolved` when a Visa RDR already closed the case, `payment_unmatched` when no payment matched, `payment_not_captured` when it never captured money, `payment_disputed` once the payment carries a dispute, `payment_refunded` once fully refunded. `null` while `actionable` is true.", "enum": [ "network_resolved", "payment_unmatched", "payment_not_captured", "payment_disputed", "payment_refunded", null ], "example": "network_resolved", "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" }, "transaction_at": { "description": "When the reported transaction was made, as an ISO 8601 timestamp.", "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", "actionable", "not_actionable_reason", "amount", "currency", "card_brand", "issuer", "account_id", "payment_id", "product_id", "fee_charged", "reported_at", "transaction_at", "created_at", "updated_at" ], "type": "object" }, "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. Falls back to Whop's platform policy when the seller has not uploaded their own.", "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 uploaded through `POST /disputes/{id}/upload_evidence`, beyond the four fixed slots. 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. Falls back to Whop's platform policy when the seller has not uploaded their own.", "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": { "content_type": { "description": "The uploaded file's MIME type. Uploads are restricted to the types the processor accepts.", "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 kind of evidence the document is.", "enum": [ "return_policy", "shipping_policy", "physical_fulfillment", "customer_order_history", "product_image", "prior_transactions", "customer_session", "digital_fulfillment", "subscription" ], "example": "customer_order_history", "type": "string" }, "filename": { "description": "The original filename, including its extension.", "example": "customer-order-history.png", "type": [ "string", "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" }, "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.", "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" } }, "required": [ "object", "id", "filename", "content_type", "size", "url", "upload_status", "visibility", "created_at", "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" }, "DisputePayment": { "properties": { "amount": { "description": "What the customer was charged, in whole units of the payment's currency.", "example": 249, "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": { "description": "The processor that handled the payment, such as `stripe`.", "example": "stripe", "type": [ "string", "null" ] } }, "required": [ "id", "amount", "currency", "payment_method_type", "payment_processor", "card_brand", "card_last4", "payment_instrument", "created_at" ], "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" }, "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", "financial-activity", "payout_methods", "payouts", "people", "plans", "products", "resolution_center_cases", "shipments", "social_accounts", "team_members", "transfers", "webhooks", "members", "receipts", "unclaimed_memberships", "memberships", "tracking_links", "promo_codes", "resolutions", "entries", "leads", "content_rewards_submissions", "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" }, "File": { "properties": { "content_type": { "description": "The file's MIME type, 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" }, "filename": { "description": "The original filename, including its extension.", "example": "evidence.pdf", "type": [ "string", "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" }, "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.", "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" } }, "required": [ "object", "id", "filename", "content_type", "size", "url", "upload_status", "visibility", "created_at" ], "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" }, "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", "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" }, "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" }, "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 these funds became (or are scheduled to become) withdrawable: the posted time for already-settled funds, or 00:00:00 UTC on the scheduled release date for pending funds. Present only on inflows entering the balance (payments, top-ups, incoming transfers/affiliate); null on payouts, refunds, disputes and on-chain rows. The available_after/before filters window on its UTC settlement date.", "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": [ "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", "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", "external_card_load_deposit", "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_swap_source", "onchain_swap_target", "onchain_wallet_transfer_incoming", "onchain_wallet_transfer_outgoing", "onchain_withdrawal", "orchestration_percentage_fee", "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_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_earning", "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", "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": "Plan associated with the payment, when applicable.", "properties": { "id": { "description": "Plan ID, prefixed `plan_`.", "type": "string" }, "name": { "description": "Plan 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 plan associated with the payment, when applicable.", "type": [ "string", "null" ] }, "plan_name": { "description": "Name of the plan 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. The ledger's USDT leg is posted 1:1 from this value.", "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.", "properties": { "amount_float": { "description": "Payout amount as a decimal number in the destination currency (payout sources only; requires payout:withdrawal:read).", "example": 1500, "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": "Public claim URL for the airdrop link (airdrop_link sources only).", "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" ] }, "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" ] }, "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 source, or null when none was provided.", "type": [ "string", "null" ] }, "object": { "example": "airdrop_link", "type": "string" }, "payer_name": { "description": "Name of the entity processing the payout (payout sources only; requires payout:withdrawal:read).", "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.", "type": [ "string", "null" ] }, "payment_processor": { "description": "Processor used by the payment source.", "type": [ "string", "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": false, "type": [ "boolean", "null" ] }, "sender_address": { "description": "Sender wallet address or onramp provider identifier (onchain_transaction sources only).", "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).", "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" ] }, "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" }, "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" }, "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" }, "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" ] }, "phone_number": { "description": "The member's phone number, or `null`. Their account number when they have shared one with this seller; otherwise the most recent number collected (or verified) at checkout.", "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": 0, "type": "number" }, "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", "token_balance", "phone_number", "joined_at", "last_accessed_at", "created_at", "user" ], "type": "object" }, "Membership": { "properties": { "account": { "$ref": "#/components/schemas/StorefrontAccount", "description": "The account (seller) this membership belongs to." }, "cancel_at_period_end": { "description": "Whether the membership is set to cancel when the current billing period ends. Only meaningful for recurring plans.", "example": false, "type": "boolean" }, "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" ] }, "id": { "description": "Membership ID, prefixed `mem_`.", "example": "mem_xxxxxxxxxxxxxx", "type": "string" }, "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" ] }, "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" } ] }, "metadata": { "description": "Custom key-value pairs stored on the membership, commonly used for software licensing.", "example": {}, "type": "object" }, "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" ] }, "plan_id": { "description": "The plan the buyer purchased, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": "string" }, "product_id": { "description": "The product this membership grants access to, prefixed `prod_`.", "example": "prod_xxxxxxxxxxxxxx", "type": "string" }, "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" }, "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" ] } }, "required": [ "id", "status", "user_id", "product_id", "plan_id", "license_key", "phone_number", "cancel_at_period_end", "current_period_end", "metadata", "created_at", "member", "account" ], "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, "type": [ "number", "null" ] } }, "required": [ "access_level", "last_accessed_at", "position" ], "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": "-2.50", "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" }, "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" }, "OnboardingReward": { "properties": { "expires_at": { "description": "When the reward stops accepting new claims and qualifying volume, as an ISO 8601 timestamp. Null when it does not expire.", "type": [ "string", "null" ] }, "id": { "description": "Onboarding reward ID, prefixed `onbr_`.", "example": "onbr_xxxxxxxxxxxxxx", "type": "string" }, "max_redemptions": { "description": "How many businesses can earn this reward in total. Null when unlimited.", "example": 1, "type": [ "integer", "null" ] }, "partner": { "$ref": "#/components/schemas/UserSummary", "description": "Partner whose link attributed this reward." }, "qualification_amount": { "description": "Required qualifying volume. Null for an immediate reward.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "qualification_income_source": { "description": "Income source whose volume qualifies the business. Null for an immediate reward.", "enum": [ "sales", "ad_spend", null ], "example": "sales", "type": [ "string", "null" ] }, "qualification_met": { "description": "Whether the attributed business met the requirement. Null before a business claims the link.", "type": [ "boolean", "null" ] }, "qualification_progress": { "description": "Qualifying volume accumulated by the attributed business. Null before a business claims the link and for immediate rewards.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "remaining_redemptions": { "description": "How many rewards are still unclaimed. For rewards with a qualification, a business claims one only when it meets the requirement, so this can reach zero while other businesses are still working toward it. Null when unlimited.", "example": 0, "type": [ "integer", "null" ] }, "reward_amount": { "$ref": "#/components/schemas/Money", "description": "Reward value delivered after qualification." }, "reward_type": { "description": "How the reward is delivered.", "enum": [ "ad_credit", "balance_credit" ], "example": "balance_credit", "type": "string" }, "rewarded": { "description": "Whether the reward was credited to the attributed business. Null before a business claims the link.", "type": [ "boolean", "null" ] }, "status": { "description": "Whether the reward can still be claimed: `available`, `fully_claimed`, `expired`, or `unavailable`.", "enum": [ "available", "fully_claimed", "expired", "unavailable" ], "example": "fully_claimed", "type": "string" } }, "required": [ "id", "status", "reward_type", "reward_amount", "qualification_income_source", "qualification_amount", "qualification_progress", "qualification_met", "rewarded", "expires_at", "max_redemptions", "remaining_redemptions", "partner" ], "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" }, "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_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" } ] }, "checkout_configuration_id": { "description": "The checkout configuration the buyer paid through, prefixed `ch_`, or null.", "type": [ "string", "null" ] }, "client_secret": { "description": "The credential a buyer's surface presents to poll this payment and set its return URL. Only on payments created from a confirmation token, 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_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.", "type": [ "string", "null" ] }, "failure_message": { "description": "Why the most recent attempt failed, in plain words, or null.", "type": [ "string", "null" ] }, "financing_installments_count": { "description": "For installment methods, how many payments the charge splits into.", "type": [ "number", "null" ] }, "id": { "description": "Payment ID, prefixed `pay_`.", "example": "pay_xxxxxxxxxxxxxx", "type": "string" }, "last_payment_attempt_at": { "description": "When the most recent charge attempt ran, or null.", "type": [ "string", "null" ] }, "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.", "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 and last four 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" } ] }, "payments_failed": { "description": "How many charge attempts have failed on this payment.", "example": 0, "type": "number" }, "plan_id": { "description": "The plan that was charged, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product the plan belongs to, prefixed `prod_`. Null for a plan with no product.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "promo_code_id": { "description": "The promo code applied at checkout, prefixed `promo_`, or null.", "type": [ "string", "null" ] }, "recovery_url": { "description": "Whop-hosted URL where the buyer can sign in and complete 3D Secure for a failed subscription renewal. Null when recovery is unavailable, you lack `member:basic:read`, or in list responses. Retrieve the payment for it.", "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.", "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 fraud risk score from 0 (lowest) to 100 (highest), or null when the payment was not scored.", "type": [ "number", "null" ] }, "risk_signals": { "description": "The factors behind `risk_score`, grouped by category, or null.", "type": [ "object", "null" ] }, "settlement_time_at": { "description": "When the funds post to the account's available balance, at midnight UTC. The `ledger_account.funds_available` webhook carries the same value. Null until the payment is paid, and always null in list responses — retrieve the payment for it.", "type": [ "string", "null" ] }, "shipment_id": { "description": "The shipment fulfilling this payment, prefixed `ship_`. Null when nothing ships or without the shipment:basic:read permission.", "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" } ] }, "verification_checks": { "description": "The issuer's address and security code check results, or null when the processor returned none.", "oneOf": [ { "$ref": "#/components/schemas/PaymentVerificationChecks" }, { "type": "null" } ] }, "voidable": { "description": "True when the payment is `open` on a past-due membership and its processor supports voiding — 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", "plan_id", "product_id", "promo_code_id", "checkout_configuration_id", "shipment_id", "currency", "total", "subtotal", "tax_amount", "tax_behavior", "refunded_amount", "tax_refunded_amount", "auto_refunded", "amount_after_fees", "usd_total", "payment_method_type", "payment_method_id", "payment_instrument", "customer_phone", "billing_address", "shipping_address", "needs_tracking", "payments_failed", "failure_message", "decline_code", "recovery_url", "three_ds_verified", "verification_checks", "risk_score", "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", "settlement_time_at", "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 receiving bank's code in the local clearing system.", "example": "684", "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", "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.", "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" ], "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" }, "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 and last four.", "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.", "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.", "example": "visa", "type": "string" }, "last4": { "description": "The card's last four digits, when captured.", "example": "4242", "type": [ "string", "null" ] } }, "required": [ "brand", "last4" ], "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", "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" }, "PaymentMethodDisplay": { "properties": { "bank_debit": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Present when the category is `bank_debit`. Carries the account's last four when the linking provider surfaced it." }, "card": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Present when the category is `card`. What the collection surface displayed — the token has not been charged, so this is the buyer's claim, not the vault's record." }, "category": { "description": "The family the type belongs to.", "enum": [ "card", "wallet", "bank_debit", "bank_transfer", "voucher", "redirect", "crypto", "balance", "in_app_purchase", "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": "Present when the category is `saved` and the stored method is a card. Unlike the other previews this is the vault's own record, not a claim from the collection surface. Absent for a balance, which has no instrument." }, "type": { "description": "The payment method type, e.g. `card`, `apple_pay`, `klarna`.", "example": "card", "type": "string" }, "wallet": { "$ref": "#/components/schemas/PaymentMethodDisplayPreview", "description": "Present when the category is `wallet`. Carries the backing card's brand and last four when the wallet surfaced them." } }, "required": [ "id", "type", "category", "display_name" ], "type": "object" }, "PaymentMethodDisplayPreview": { "properties": { "brand": { "description": "Lowercase card brand, e.g. `visa`. Absent when the method carries no brand.", "example": "visa", "type": "string" }, "last4": { "description": "Last four digits of the instrument. Absent when the method carries none.", "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.example", "type": "string" }, "id": { "description": "Payment method domain ID, prefixed `pmd_`.", "example": "pmd_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" }, "PaymentMethodTypes": { "description": "The different types of payment methods that can be used.", "enum": [ "acss_debit", "addi", "affirm", "afterpay_clearpay", "alipay", "alma", "amazon_pay", "apple", "apple_pay", "au_bank_transfer", "au_becs_debit", "bacs_debit", "bancolombia", "bancontact", "bank_wire", "billie", "bizum", "blik", "boleto", "bre_b", "ca_bank_transfer", "capchase_pay", "card", "card_installments_three", "card_installments_six", "card_installments_twelve", "cashapp", "claritypay", "coinbase", "crypto", "custom", "customer_balance", "demo_pay", "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", "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", "tamara", "twint", "upi", "us_bank_account", "us_bank_transfer", "venmo", "verve", "vipps", "webpay", "wechat_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", "display_instructions": "#/components/schemas/PaymentNextActionDisplayInstructions", "redirect": "#/components/schemas/PaymentNextActionRedirect" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/PaymentNextActionRedirect" }, { "$ref": "#/components/schemas/PaymentNextActionDisplayInstructions" }, { "$ref": "#/components/schemas/PaymentNextActionAwaitConfirmation" } ] }, "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" }, "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" }, "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" }, "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" }, "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" } ] }, "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.", "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`.", "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` — the money is moving; see `processing_details`. `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" ], "type": "object" }, "PaymentVerificationChecks": { "properties": { "address_line1": { "description": "Whether the billing street address the customer entered matched the issuer's records.", "example": "PASS", "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": "Whether the CVV / CVC matched the card.", "example": "PASS", "type": [ "string", "null" ] }, "zip_code": { "description": "Whether the billing postal code matched the issuer's records.", "example": "PASS", "type": [ "string", "null" ] } }, "required": [ "address_line1", "zip_code", "card_holder_name", "card_security_code" ], "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" }, "Permission": { "properties": { "action": { "description": "The permission action's identifier, for example `company:basic:read`.", "example": "access_pass:basic:export", "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": false, "type": "boolean" }, "category": { "description": "The category the action is grouped under, or `null` when uncategorized.", "example": "Products", "type": [ "string", "null" ] }, "description": { "description": "What granting the action allows.", "example": "Download the account's product list as a CSV.", "type": "string" }, "granted_to_system_roles": { "items": { "description": "System roles that include the permission.", "enum": [ "owner", "admin", "moderator", "sales_manager", "advertiser" ], "example": "owner", "type": "string" }, "type": "array" }, "name": { "description": "Human-readable name of the action.", "example": "Export products", "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": [ "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", "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: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: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: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:ads", "webhook_receive:products", "webhook_receive:plans", "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_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", "airdrop_link:basic:read", "airdrop_link:manage", "lead:manage", "notification:create", "user:balance:read", "user:email:read", "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:notifications:update", "user:profile:update" ], "example": "ai_prompt:create", "type": "string", "x-enumNames": [ "AiPromptCreate", "AccessPassBasicExport", "AccessPassBasicRead", "AccessPassControlCenter", "AccessPassCreate", "AccessPassDelete", "AccessPassStatsExport", "AccessPassStatsRead", "AccessPassUpdate", "AdCampaignBasicExport", "AdCampaignBasicRead", "AdCampaignConversionCreate", "AdCampaignCreate", "AdCampaignCreditCreate", "AdCampaignDelete", "AdCampaignRead", "AdCampaignStatsRead", "AdCampaignUpdate", "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", "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", "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", "WebhookReceiveTransfers", "WebhookReceiveCardTransactions", "WebhookReceiveCards", "WebhookReceiveCardApplications", "WebhookReceivePayoutMethods", "WebhookReceiveVerifications", "WebhookReceiveIdentityProfiles", "WebhookReceivePayoutAccounts", "WebhookReceiveChat", "WebhookReceiveEntries", "WebhookReceiveAdCampaigns", "WebhookReceiveAds", "WebhookReceiveProducts", "WebhookReceivePlans", "WebhookReceiveShipments", "WebhookReceiveMembers", "WebhookReceiveExports", "WebhookReceiveCourses", "WebhookReceiveMemberships", "WebhookReceivePayments", "WebhookReceiveRefunds", "WebhookReceiveDisputes", "WebhookReceiveResolutions", "WebhookReceiveAppPayments", "WebhookReceiveAppMemberships", "ShipmentCreate", "ShipmentBasicRead", "CheckoutConfigurationBasicRead", "CheckoutConfigurationCreate", "CheckoutConfigurationDelete", "CheckoutRequestCreate", "CheckoutRequestBasicRead", "CryptoWalletManage", "CryptoWalletSwap", "AirdropLinkBasicRead", "AirdropLinkManage", "LeadManage", "NotificationCreate", "UserBalanceRead", "UserEmailRead", "UserStaffRead", "OauthTokenExchange", "Openid", "Profile", "Email", "AiChatRead", "AiChatCreate", "AiChatDelete", "AiChatUpdate", "UserNotificationsRead", "UserNotificationsUpdate", "UserProfileUpdate" ] }, "PixelValidation": { "properties": { "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": true, "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/checkout/complete", "type": [ "string", "null" ] } }, "required": [ "installed", "url", "reachable", "last_seen_days", "page_events", "host_events", "native_tracking", "last_fired_days", "firing_data_ok" ], "type": "object" }, "Plan": { "properties": { "account": { "description": "Account that sells this plan; `null` for standalone invoice plans.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "adaptive_pricing_enabled": { "description": "Whether adaptive pricing is enabled for this plan. Raw setting — does not check processor compatibility or feature flags.", "example": true, "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": 30, "type": [ "number", "null" ] }, "cancel_discount_intervals": { "description": "Billing intervals the cancellation discount applies to (`0` forever, `1` first payment, or a month count). `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": "Plan-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 plan, based on the account's tax configuration.", "example": false, "type": "boolean" }, "created_at": { "description": "When the plan was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code for this plan's 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" }, "custom_fields": { "items": { "$ref": "#/components/schemas/PlanCustomField", "description": "Custom input fields collected on the checkout form." }, "type": "array" }, "deletable": { "description": "Whether the plan can be deleted (it has no memberships or waitlist entries). `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": true, "type": [ "boolean", "null" ] }, "description": { "description": "Customer-visible plan 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 plan, resolved through every layer (the plan'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 plan's own editable override.", "oneOf": [ { "$ref": "#/components/schemas/CheckoutSessionPaymentMethodConfiguration" }, { "type": "null" } ] }, "expiration_days": { "description": "Access duration in days for expiration-based plans, such as 365 for a one-year pass. `null` for plans without an expiration.", "example": 365, "type": [ "number", "null" ] }, "formatted_price": { "description": "Human-readable price for display (currency + interval), e.g. \"$10 / month\".", "example": "$59.00 / month", "type": "string" }, "id": { "description": "Plan 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 plan currency.", "example": 0, "type": "number" }, "internal_notes": { "description": "Private notes not shown to customers. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "invoice": { "description": "Invoice this plan was generated for; `null` unless created for an invoice.", "example": { "id": "inv_xxxxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "member_count": { "description": "Active memberships through this plan. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": 0, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the plan. 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 plan.", "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 plan's account.", "example": true, "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "Payment method configuration (`enabled`, `disabled`, `include_platform_defaults`); `null` when plan uses default settings.", "example": { "disabled": [ "crypto" ], "enabled": [ "card" ], "include_platform_defaults": true }, "type": [ "object", "null" ] }, "plan_type": { "description": "Billing model for this plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "product": { "description": "Product this plan belongs to; `null` for standalone plans.", "example": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "type": [ "object", "null" ] }, "purchase_url": { "description": "URL where customers can purchase this plan directly.", "example": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged every billing period.", "example": 59, "type": "number" }, "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 plan's account.", "example": 0, "type": [ "number", "null" ] }, "strike_through_initial_price": { "description": "Original initial price shown with a strikethrough, in the plan's currency. `null` when no strikethrough is set.", "example": 99, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "Original renewal price shown with a strikethrough, in the plan's currency. `null` when no strikethrough is set.", "example": 79, "type": [ "number", "null" ] }, "tax_type": { "description": "How tax is handled for this plan, 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 this plan; `null` inherits the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "Plan display name shown to customers. Maximum 30 characters. `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 plan.", "example": 7, "type": [ "number", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock. When `true`, the `stock` field is ignored; waitlist plans always report `true`.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the plan was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visibility": { "description": "Controls where this plan can be seen. When `hidden`, the plan is reachable only by its direct link.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "visibility", "plan_type", "release_method", "currency", "account", "product", "invoice", "billing_period", "title", "description", "purchase_url", "expiration_days", "initial_price", "renewal_price", "formatted_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "stock", "unlimited_stock", "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 plan; `null` for standalone invoice plans.", "oneOf": [ { "$ref": "#/components/schemas/AccountSummary" }, { "type": "null" } ] }, "adaptive_pricing_enabled": { "description": "Whether adaptive pricing is enabled for this plan. Raw setting — does not check processor compatibility or feature flags.", "example": true, "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": 30, "type": [ "number", "null" ] }, "cancel_discount_intervals": { "description": "Billing intervals the cancellation discount applies to (`0` forever, `1` first payment, or a month count). `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": "Plan-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 plan was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "currency": { "description": "Three-letter ISO currency code for this plan's prices.", "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 plan 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 plans, such as 365 for a one-year pass. `null` for plans without an expiration.", "example": 365, "type": [ "number", "null" ] }, "formatted_price": { "description": "Human-readable price for display (currency + interval), e.g. \"$10 / month\".", "example": "$59.00 / month", "type": "string" }, "id": { "description": "Plan 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 plan currency.", "example": 0, "type": "number" }, "internal_notes": { "description": "Private notes not shown to customers. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": "Maintenance tier. Upsell the interior shampoo add-on at renewal.", "type": [ "string", "null" ] }, "invoice": { "description": "Invoice this plan was generated for; `null` unless created for an invoice.", "example": { "id": "inv_xxxxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "member_count": { "description": "Active memberships through this plan. `null` unless the actor has the `plan:basic:read` scope on the plan's account.", "example": 0, "type": [ "number", "null" ] }, "metadata": { "description": "Custom key-value pairs stored on the plan. 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 plan.", "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 plan's account.", "example": true, "type": [ "boolean", "null" ] }, "payment_method_configuration": { "description": "Payment method configuration (`enabled`, `disabled`, `include_platform_defaults`); `null` when plan uses default settings.", "example": { "disabled": [ "crypto" ], "enabled": [ "card" ], "include_platform_defaults": true }, "type": [ "object", "null" ] }, "plan_type": { "description": "Billing model for this plan.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "product": { "description": "Product this plan belongs to; `null` for standalone plans.", "example": { "id": "prod_xxxxxxxxxxxxxx", "title": "Ceramic Coating Package" }, "type": [ "object", "null" ] }, "purchase_url": { "description": "URL where customers can purchase this plan directly.", "example": "https://whop.com/checkout/plan_xxxxxxxxxxxxxx", "type": "string" }, "release_method": { "description": "Sales method for this plan.", "enum": [ "buy_now", "waitlist" ], "example": "buy_now", "type": "string" }, "renewal_price": { "description": "Recurring price charged every billing period.", "example": 59, "type": "number" }, "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 plan's account.", "example": 0, "type": [ "number", "null" ] }, "strike_through_initial_price": { "description": "Original initial price shown with a strikethrough, in the plan's currency. `null` when no strikethrough is set.", "example": 99, "type": [ "number", "null" ] }, "strike_through_renewal_price": { "description": "Original renewal price shown with a strikethrough, in the plan's currency. `null` when no strikethrough is set.", "example": 79, "type": [ "number", "null" ] }, "three_ds_level": { "description": "3D Secure behavior for this plan; `null` inherits the account default.", "enum": [ "mandate_challenge", "frictionless", null ], "example": "frictionless", "type": [ "string", "null" ] }, "title": { "description": "Plan display name shown to customers. Maximum 30 characters. `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 plan.", "example": 7, "type": [ "number", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock. When `true`, the `stock` field is ignored; waitlist plans always report `true`.", "example": false, "type": "boolean" }, "updated_at": { "description": "When the plan was last updated, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "visibility": { "description": "Controls where this plan can be seen. When `hidden`, the plan is reachable only by its direct link.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "created_at", "updated_at", "visibility", "plan_type", "release_method", "currency", "account", "product", "invoice", "billing_period", "title", "description", "purchase_url", "expiration_days", "initial_price", "renewal_price", "formatted_price", "trial_period_days", "three_ds_level", "member_count", "internal_notes", "metadata", "stock", "unlimited_stock", "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" }, "Product": { "properties": { "account": { "description": "Account that sells this product.", "example": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "type": [ "object", "null" ] }, "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_plan": { "description": "Buyable plan to show and check out with. The configured default when that plan is buyable, otherwise the first buyable plan in product-page order. `null` when none is buyable.", "oneOf": [ { "$ref": "#/components/schemas/ProductPublicPlan" }, { "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, "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, "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" }, "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", "external_identifier", "metadata", "labels", "account", "default_plan", "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", "gallery_images" ], "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" }, "ProductListItem": { "properties": { "account": { "description": "Account that sells this product.", "example": { "id": "biz_xxxxxxxxxxxxxx", "route": "biz_xxxxxxxxxxxxxx", "title": "Shine Time Auto Detailing" }, "type": [ "object", "null" ] }, "created_at": { "description": "When the product was created, as an ISO 8601 timestamp.", "example": "2026-01-01T12:00:00.000Z", "type": "string" }, "default_plan": { "description": "Buyable plan to show and check out with. The configured default when that plan is buyable, otherwise the first buyable plan in product-page order. `null` when none is buyable.", "oneOf": [ { "$ref": "#/components/schemas/ProductPublicPlan" }, { "type": "null" } ] }, "description": { "description": "Written description displayed on the product page. `null` if none is set.", "example": "Two-stage paint correction, a three-year ceramic coating, and sealed wheel faces.", "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": "A showroom finish that lasts three years", "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": "ceramic-coating-package", "type": "string" }, "title": { "description": "Product display name shown to customers.", "example": "Ceramic Coating Package", "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" }, "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", "external_identifier", "metadata", "labels", "account", "default_plan", "gallery_images" ], "type": "object" }, "ProductPublicPlan": { "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": 30, "type": [ "number", "null" ] }, "expiration_days": { "description": "Access duration in days for expiration-based plans. `null` for plans without an expiration.", "type": [ "number", "null" ] }, "id": { "description": "Plan 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." }, "plan_type": { "description": "Billing model for this plan: `one_time` or `renewal`.", "enum": [ "renewal", "one_time" ], "example": "renewal", "type": "string" }, "renewal_price": { "$ref": "#/components/schemas/Money", "description": "The recurring charge every `billing_period` days. `amount` is `\"0.00\"` for one-time plans." }, "title": { "description": "Plan display name shown to customers. `null` if no title has been set.", "type": [ "string", "null" ] }, "unlimited_stock": { "description": "Whether the plan has unlimited stock.", "example": true, "type": "boolean" }, "visibility": { "description": "Where this plan can be seen. `visible` plans appear on the product page.", "enum": [ "visible", "hidden", "archived", "quick_link" ], "example": "visible", "type": "string" } }, "required": [ "id", "title", "plan_type", "billing_period", "initial_price", "renewal_price", "visibility", "unlimited_stock", "expiration_days" ], "type": "object" }, "PromoCode": { "properties": { "account": { "$ref": "#/components/schemas/AccountSummary", "description": "Account that owns the promo code." }, "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", "account" ], "type": "object" }, "PromoCodeListItem": { "properties": { "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" ], "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" }, "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" }, "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" }, "RecommendedActionExecution": { "properties": { "action": { "description": "The action definition key the step ran", "example": "create_product", "type": "string" }, "completed_at": { "description": "When the step reached a terminal status, ISO 8601", "example": "2026-01-01T12:00:00.000Z", "type": [ "string", "null" ] }, "error": { "description": "Why the step failed, or `null`", "type": [ "string", "null" ] }, "id": { "description": "Execution ID, prefixed `raex_`", "example": "raex_xxxxxxxxxxxxxx", "type": "string" }, "output": { "description": "The API response the step produced, or `null` until it succeeds", "example": { "id": "prod_xxxxxxxxxxxxxx" }, "type": [ "object", "null" ] }, "position": { "description": "Zero-based order of the step within the chain", "example": 0, "type": "integer" }, "status": { "description": "Where the step currently stands", "enum": [ "pending", "redirected", "running", "succeeded", "failed" ], "example": "succeeded", "type": "string" } }, "required": [ "id", "position", "action", "status", "output", "error", "completed_at" ], "type": "object" }, "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": "The provider's own explanation of the failure, or null.", "example": "Insufficient funds on the merchant balance.", "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": "insufficient_funds", "type": [ "string", "null" ] }, "id": { "description": "Refund ID, prefixed `rf_`.", "example": "rf_xxxxxxxxxxxxxx", "type": "string" }, "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", 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.", "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", "provider_created_at", "created_at", "updated_at" ], "type": "object" }, "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, "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/ResolutionLineItem", "description": "Everything the disputed payment charged for, in purchase order. `product_id` and `plan_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 plan implies. Empty when the payment is not linked to a plan." }, "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." }, "plan_id": { "description": "The plan the payment was made on, prefixed `plan_`.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "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" } }, "required": [ "id", "status", "escalated", "outcome", "refund", "reason", "amount", "currency", "account", "product_id", "plan_id", "line_items", "customer_appealed", "available_actions", "response_due_at", "buyer", "payment", "created_at", "updated_at" ], "type": "object" }, "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" }, "ResolutionLineItem": { "properties": { "id": { "description": "Line item ID, prefixed `li_`. Null when the payment predates item snapshots and the item is read from the payment's plan.", "type": [ "string", "null" ] }, "label": { "description": "The item's name as shown at checkout — the product title, else the plan title.", "example": "Ceramic Coating Package", "type": [ "string", "null" ] }, "plan_id": { "description": "The plan bought, prefixed `plan_`. Null when the plan has since been deleted.", "example": "plan_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "product_id": { "description": "The product the plan belongs to, prefixed `prod_`. On a payment that predates item snapshots this falls back to the plan's product, so it can be set where the case's own `product_id` is null. Null for a plan with no product.", "example": "prod_xxxxxxxxxxxxxx", "type": [ "string", "null" ] }, "quantity": { "description": "How many units were bought.", "example": 1, "type": "number" } }, "required": [ "id", "plan_id", "product_id", "label", "quantity" ], "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" }, "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 enrollment was declined by the payment provider.", "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" }, "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": "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 social account.", "example": "1234567891", "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 Auto Detailing", "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.", "oneOf": [ { "$ref": "#/components/schemas/SocialAccountParent" }, { "type": "null" } ] }, "platform": { "description": "The platform the social account exists on.", "enum": [ "x", "instagram", "youtube", "tiktok", "facebook", "discord", "telegram" ], "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/logo.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 the presence of `advertise` in this value.", "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.", "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", "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": "555111", "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" ], "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" }, "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" }, "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" } ] }, "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" }, "email": { "description": "The member's email address. For accepted members, `null` unless the caller holds the email read scope; for invites, the invited address.", "example": "marcus@shinetime.example", "type": [ "string", "null" ] }, "id": { "description": "Team member ID — `ausr_` for accepted members, `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" }, "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", "sales_manager", "moderator", "advertiser", "app_manager", "support", "manager", "workforce", "custom" ], "example": "moderator", "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", "user" ], "type": "object" }, "TeamMemberAuthorizedRole": { "properties": { "id": { "description": "Custom role ID, prefixed `aurl_`.", "type": "string" }, "name": { "description": "Custom role name.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "User": { "properties": { "balance": { "description": "The user's balance: personal cash + crypto + in-flight treasury deposits, 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.", "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" } ] }, "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" ] }, "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" }, "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_accounts": { "items": { "$ref": "#/components/schemas/SocialAccount", "description": "Social accounts linked to the user (Discord, X/Twitter, Telegram), oldest first. Reading your own profile returns every linked account; other profiles only include what is public on Whop (the primary Discord and the X account). Empty when none are linked." }, "type": "array" }, "staff": { "description": "Whop staff access flags. Populated only on the self view (retrieved with the reserved id `me`) for callers with staff-read scope; `null` there for every user who is not Whop staff, and always `null` elsewhere.", "oneOf": [ { "$ref": "#/components/schemas/UserStaffAccess" }, { "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" ] } }, "required": [ "id", "username", "name", "bio", "created_at", "profile_picture", "banner", "social_accounts", "email", "staff", "balance", "earnings_usd", "balance_history", "verification", "whop_partner_enabled_at" ], "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": "0.00", "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": "0.00", "type": "string" }, "pending_usd": { "description": "Fiat pending and in-transit balances, plus in-flight treasury deposits, in USD.", "example": "0.00", "type": "string" }, "total_usd": { "description": "The user's personal balance in USD: cash (available + pending + in-transit + reserve) + crypto + in-flight treasury deposits. Excludes account balances (see businesses_total_usd).", "example": "0.00", "type": "string" }, "treasury_pending_usd": { "description": "Balance-to-wallet USDT0 payouts 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, "type": "number" }, "pending_balance_usd": { "description": "Pending balance converted to USD.", "example": 310, "type": "number" }, "price_usd": { "description": "USD price per native currency unit, or `null` when no exchange rate is available.", "type": [ "number", "null" ] }, "reserve_balance_usd": { "description": "Reserved balance converted to USD.", "example": 125, "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": 0, "type": "number" }, "max": { "description": "Maximum value across the window, in USD.", "example": 0, "type": "number" }, "min": { "description": "Minimum value across the window, in USD.", "example": 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, "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, "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, "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": "260.00", "type": "string" }, "last_7_days": { "description": "Gross income in USD over the last 7 days.", "example": "60.00", "type": "string" }, "lifetime": { "description": "All-time gross income in USD.", "example": "4120.25", "type": "string" } }, "required": [ "lifetime", "last_30_days", "last_7_days", "last_24_hours" ], "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" }, "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" ], "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`", "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" }, "UserStaffAccess": { "properties": { "admin": { "description": "Whether the user holds the admin staff role with a valid second factor.", "example": true, "type": "boolean" }, "investigation_access": { "description": "Whether the user can open Whop-internal investigation tooling right now: a qualifying staff role plus their investigation toggle switched on.", "example": true, "type": "boolean" }, "manager": { "description": "Whether the user holds the manager staff role with a valid second factor.", "example": false, "type": "boolean" }, "support": { "description": "Whether the user holds the support staff role with a valid second factor.", "example": false, "type": "boolean" } }, "required": [ "admin", "support", "manager", "investigation_access" ], "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" }, "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-01-01", "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", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "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", "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", "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", "ad_campaign.payment_failed", "ad_campaign.updated", "ad.updated", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "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_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", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "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", "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", "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", "ad_campaign.payment_failed", "ad_campaign.updated", "ad.updated", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "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_membership.cancel_at_period_end_changed" ], "example": "account.updated", "type": "string" }, "type": "array" }, "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", "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" }, "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", "success", "total_time" ], "type": "object" }, "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-01-01", "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", "invoice.created", "invoice.marked_uncollectible", "invoice.paid", "invoice.past_due", "invoice.voided", "membership.activated", "membership.deactivated", "membership.trial_ending_soon", "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", "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", "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", "ad_campaign.payment_failed", "ad_campaign.updated", "ad.updated", "chat.message.created", "chat.reaction.created", "payment.created", "payment.succeeded", "payment.failed", "payment.pending", "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_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" }, "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", "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" } }, "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" } } } }