> ## Documentation Index > Fetch the complete documentation index at: https://docs.whop.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Checkout Session > Opens a checkout session. No credentials required. Pass exactly one of `items`, `checkout_configuration`, or `link`. The response includes `client_secret` once; later calls authenticate with it. ## OpenAPI ````yaml /openapi/api-v1-native.json post /checkout_sessions 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-08-21-1 servers: - description: Production Whop API url: https://api.whop.com/api/v1 - description: Sandbox Whop API url: https://sandbox-api.whop.com/api/v1 security: [] 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. Use the Accounts API to create accounts, list accounts visible to your credentials, retrieve or update an account, and retrieve the account associated with the current API key. 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. Use the Users API to search for users, retrieve or update profiles, and check whether a user has access to an account, product, or experience. 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. Use 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. 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. Use 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. 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. Use the Stats API to list available metrics and their filterable properties, then retrieve time-series values for a date range. 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. Use 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). 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. Use 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`. 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. Every 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. Use 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. 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 it with a payment method already on file, or with a `confirmation_token` describing a method the buyer has just supplied. Collection 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. name: Payments x-whop-summary: A charge against a buyer, and the step they still owe. - 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. Poll [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. name: Setup Intents x-whop-summary: Saving a buyer's payment method without charging it. - description: > A Ledger Activity row is a single financial event on an account's ledger — a payment, withdrawal, 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. Use 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. name: Ledgers 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. Use the Payouts API to create and track payouts, manage saved payout methods, and show expected arrival details for funds leaving Whop. 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. Use 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. 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. Use the Transfers API to create a transfer, list previous transfers, and retrieve a transfer by ID when reconciling money movement between accounts or users. name: Transfers x-whop-summary: Move funds between Whop accounts and users. - 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. Use the Disputes API to list disputes, edit the evidence packet while a dispute is still contestable, and submit it for review. 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`). Use 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. name: Dispute alerts x-whop-summary: Issuer warnings that arrive before a chargeback does. - description: > Deposits describe ways to add funds to an account balance, including hosted deposit pages, bank deposit instructions, and supported crypto wallet addresses. Use the Deposits API to create deposit instructions for an account. 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. Use the Swaps API to quote a conversion, create the swap, list recent swaps, and retrieve status until the transaction completes. name: Swaps x-whop-summary: Convert a balance between currencies. - 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. Use 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. name: Resolution Center Cases x-whop-summary: File or respond to a case against a payment, as the buyer or the merchant. - description: > A Product is a digital good or service sold on Whop. Products may contain plans for pricing and/or experiences for content delivery. Use the Products API to search the public marketplace, list an account's products, retrieve a product, and create, update, or delete products. 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. Use 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. name: Plans x-whop-summary: 'Pricing for a product: one-time, recurring, trials, stock.' - description: > A Checkout Session is a server-priced offer for one plan: item, total, currency, and an expiry. Use the Checkout Sessions API to open a session, poll the quote, collect buyer requirements, and confirm payment. name: Checkout Sessions x-whop-summary: A quotable checkout an agent or buyer can park, approve, and pay. - 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. Use 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. 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. Use 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. 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. Use 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. 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. Use 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. 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. Use 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. 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. Use 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. 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. Use 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. 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. Use 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. 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. Use 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. Events 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. 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. Use 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. 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. Use 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. 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. Use the Ad Campaigns API to create campaigns, list campaigns for an account, retrieve or update campaign settings, and pause or resume campaign delivery. 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. Use 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. name: Ad Groups x-whop-summary: Audience, placements, and schedule within a campaign. - description: > An Audience represents a customer list uploaded to Whop for ad targeting. Audiences belong to an account and sync to supported ad platforms as custom audiences. Use the Audiences API to create audiences from CSV uploads, monitor processing status, and list or delete audiences for an account. Created audiences are usable for targeting after processing reaches `ready` or `partial`. 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`. Use 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. 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. Use the Media API to start a generation job and retrieve the asset while it processes or after it is ready. 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. Use 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. 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.app` or an API integration installed as an experience, and it belongs to the account that owns its credentials, settings, builds, and runtime logs. Use 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. 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. Use 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. 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. Use 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. name: API Keys x-whop-summary: Programmatic credentials for an account or app. - 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`. Use 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. name: Permissions x-whop-summary: What your credential is allowed to do on a resource. paths: /checkout_sessions: parameters: - $ref: '#/components/parameters/ApiVersionDate' post: tags: - Checkout Sessions summary: Create Checkout Session description: >- Opens a checkout session. No credentials required. Pass exactly one of `items`, `checkout_configuration`, or `link`. The response includes `client_secret` once; later calls authenticate with it. operationId: createCheckoutSession parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: properties: affiliate_code: description: >- The affiliate this checkout is attributed to. Write-once — set it here or never. example: aff_from_caller type: - string - 'null' attribution: description: >- String-to-string acquisition context. Recognized keys: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `tracking_link_id`, `funnel_id`, `source`, `country`; anything else is dropped. type: - object - 'null' checkout_configuration: description: >- A seller's checkout configuration (`ch_…`) to open this checkout from. Its plan, mode, affiliate code, metadata, redirect URL, 3DS level and payment method configuration seed the session; anything you also send explicitly wins. example: ch_xxxxxxxxxxxxxx type: - string - 'null' items: description: >- What the buyer is purchasing. Exactly one entry today — more are refused until multi-item checkout ships; the array shape is the forward contract. Alongside a `checkout_configuration` or `link` it may only name that mount's own plan, where it sets quantity. items: properties: plan: description: >- The plan being purchased (`plan_…`). The plan is the price. example: plan_xxxxxxxxxxxxxx type: string quantity: description: How many of the plan. Defaults to 1. example: 2 maximum: 999999 minimum: 1 type: integer required: - plan type: object type: array link: description: >- Any checkout link the seller has shared, resolved for you: a plan ID, a checkout configuration ID, a vanity short link (send `page_route` with it), a membership transfer code, or a checkout link the seller handed out earlier. A link that is not a checkout link is refused with a coded message rather than a bare not-found. example: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx type: - string - 'null' metadata: additionalProperties: type: string description: >- Free-form string-to-string map, at most 40 keys. Whop never interprets it. example: campaign: summer type: - object - 'null' mode: description: >- Defaults to the checkout configuration's mode, then `payment`. `setup` sessions are not yet available and are refused. enum: - payment - setup - null example: payment type: - string - 'null' origin: description: >- Where this checkout is being opened from — the scheme and host of your page, with no path (`https://shop.example.com`). Ignored when the request carries a browser `Origin` header, which is used instead. Recorded against the session as acquisition context. type: - string - 'null' page_route: description: >- The product route a vanity `link` belongs to — the `pageRoute` in the seller's shared URL. example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx type: - string - 'null' password: description: >- The password for a password-protected plan. Right, and the gate is cleared for the session's whole life; wrong or omitted, and the session still opens — it publishes a `custom_password` requirement, the answer arrives through update, and confirm refuses until it is right. example: rotated-away type: - string - 'null' promo_code: description: A promo code to apply to the quote. type: - string - 'null' return_url: description: >- Where the buyer lands after an off-site payment step. Absolute https URL without credentials. type: - string - 'null' top_up_membership: description: >- An existing membership (`mem_…`) this checkout pays against instead of creating a new one — the buyer pays the plan's price again onto something they already own. Ownership is checked at confirm, against the buyer who confirms: a membership they do not own is refused as not found. Cannot accompany a membership transfer link. example: mem_xxxxxxxxxxxxxx type: - string - 'null' tracking_link_ids_by_account: additionalProperties: type: string description: >- First-party tracking-link candidates keyed by account ID. Ignored outside Whop's hosted checkout; an explicit `attribution.tracking_link_id` wins. type: - object - 'null' type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CheckoutSession' description: a free plan, which needs no payment method '400': $ref: '#/components/responses/InvalidParameters' description: a return_url that is not a bare https URL '404': $ref: '#/components/responses/NotFound' description: the checkout sessions flag is off '409': $ref: '#/components/responses/Conflict' description: a sold-out plan security: [] components: parameters: ApiVersionDate: description: Pins the request to a dated API version. in: header name: Api-Version-Date required: false schema: example: 2026-08-21-1 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 schemas: CheckoutSession: properties: affiliate_code: description: >- The affiliate this checkout is attributed to, or `null`. Set at create only. example: aff_from_link type: - string - 'null' available_currencies: items: description: >- Every value `display_currency` accepts: the seller's own currency, plus the buyer's local one when the seller has adaptive pricing on and Whop can price in it. Anything else is refused. A checkout that takes no money — a free plan, a transfer, a promo code that makes every charge free — offers the seller's currency alone: there is nothing to pay, so there is no currency to choose. example: usd type: string type: array branding: description: >- The seller's checkout appearance, resolved configuration first, then plan, then account. `null` when nobody set any. oneOf: - $ref: '#/components/schemas/CheckoutSessionBranding' - type: 'null' buyer_email: description: >- The buyer's email, once one has been resolved for this checkout — `null` until then. Read-only, and read it together with `buyer_identity`: an address alone does not mean the person holds it. example: marcus@shinetime.example type: - string - 'null' buyer_id: description: >- The buyer's user account (`user_…`), once one has been resolved for this checkout — `null` until then. Read-only, and read it together with `buyer_identity`: `attributed` names the account the purchase is for and proves nothing about who is at the keyboard. example: user_xxxxxxxxxxxxxx type: - string - 'null' buyer_identity: description: >- How well this checkout knows its buyer, or `null` before one is resolved. `attributed` means an account was matched from what the buyer typed — it says who the purchase is for and nothing about who is at the keyboard. `authenticated` means the person proved they hold that account during this checkout. Only `authenticated` may be handed anything that acts as the buyer, and the value only strengthens. enum: - attributed - authenticated - null example: attributed type: - string - 'null' buyer_identity_at: description: >- When the buyer's identity was last established or strengthened, as an ISO 8601 timestamp. `null` before a buyer is resolved. example: '2026-01-01T12:00:00.000Z' type: - string - 'null' buyer_identity_method: description: >- How the buyer's identity was established — the mechanism behind `buyer_identity`, so a checkout stays explicable long after it completed. `null` before a buyer is resolved. New mechanisms are added over time. enum: - confirmation_token_email - buyer_email - saved_payment_method - session_intent - post_purchase_claim - null example: confirmation_token_email type: - string - 'null' checkout_configuration: description: >- The seller's checkout configuration this session was mounted from (`ch_…`), or `null` when it was opened directly from a plan. Its presets seeded this session at create. example: ch_xxxxxxxxxxxxxx type: - string - 'null' client_secret: description: >- The session's one credential — returned by create, and echoed on a session read authenticated with it (or with the checkout's own resume cookie, which holds the same value). Every other call authenticates with it; treat it like a password for this checkout. example: >- chs_xxxxxxxxxxxxxx_secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx type: string collect_tax_id: description: >- Whether this seller offers tax ID entry on checkout (their VAT ID setting). When `false`, hide the input — a stored `tax_id` still applies either way. example: false type: boolean created_at: description: When the session was created, as an ISO 8601 timestamp. example: '2026-01-01T12:00:00.000Z' type: string cta_label: description: >- The verb for the button that confirms this checkout, so every surface names the act the same way: `pay`, `subscribe`, `start_trial`, `join_waitlist`, or `continue` when nothing is charged today (a free checkout, `setup` mode saving a payment method, or a transfer that charges nothing). Render your own wording for each value — this is a key, never display text — and fall back to a generic label on a value you do not recognize. enum: - accept_transfer - pay - continue - start_trial - subscribe - join_waitlist example: subscribe type: string custom_field_responses: items: $ref: '#/components/schemas/CheckoutSessionCustomFieldResponse' description: The buyer's answers to the plan's custom fields. type: array display_currency: description: >- The currency this checkout is priced AND charged in, lowercase. Seeded at create from where the buyer is; update it to one of `available_currencies` to price and charge in that currency instead. example: usd type: string entry: description: >- The waitlist entry the confirm created, or `null`. Only a waitlist plan produces one: joining charges nothing — the payment method is saved and the seller charges it if they accept the entry — so a completed waitlist session carries an `entry` and a `null` payment. Read it with its `status`: `succeeded` means the join stands; `failed` (the card save died — the buyer is not on the waitlist) is transient, reopening the session on the next read with the failure on `last_confirm_error`. oneOf: - $ref: '#/components/schemas/CheckoutSessionEntry' - type: 'null' expires_at: description: >- When the session expires, as an ISO 8601 timestamp. An expired session cannot be updated or confirmed — start a new one. example: '2026-01-01T12:00:00.000Z' type: string id: description: Checkout session ID, prefixed `chs_`. example: chs_xxxxxxxxxxxxxx type: string invoice_due_at: description: >- When this checkout's invoice is due, as an ISO 8601 timestamp — `null` for everything that is not an invoice checkout, and for an invoice without a due date. Present when the plan collects a seller-issued invoice; a surface should state the date, and a date in the past reads as overdue. type: - string - 'null' items: items: $ref: '#/components/schemas/CheckoutSessionItem' description: >- What the buyer is purchasing. Exactly one entry today — the array shape is the contract, and more entries are refused until multi-item checkout ships. type: array last_confirm_error: description: >- Why the most recent confirm attempt did not complete, or `null`. Only terminal refusals land here — anything the buyer can resolve is a `next_action` instead. The session stays open; fix what the code names and confirm again. oneOf: - $ref: '#/components/schemas/CheckoutSessionConfirmError' - type: 'null' metadata: additionalProperties: type: string description: >- Free-form string-to-string map set at create. Whop never interprets it. example: campaign: spring type: - object - 'null' mode: description: >- `payment` charges the items at confirm; `setup` saves a payment method for later use. enum: - payment - setup example: payment type: string next_action: description: >- The one thing to do now, or `null` when there is nothing. Do it, re-read the session, and repeat until it is `null`. A `completed` session with no `next_action` has nothing left to do — whether the checkout WENT THROUGH is the result's own `status` (`payment.status`, or `entry.status` for a waitlist join): a charge that decisively dies REOPENS the session on the next read, with the failure on `last_confirm_error` — so a `failed` result is a transient reading, never a resting state, and nothing about it may be presented as a success. `type` picks the shape, and each type carries only its own fields: switch on `type` and the payload it needs is there; a type you do not recognize is safe to skip when it is not blocking. `blocking` says whether the flow may move past it — read it rather than inferring it from the type. Before the charge, blocking means the buyer cannot pay until it is done. `complete` is the attempt's own unfinished ceremony — a 3D Secure challenge, a bank redirect — and one executor serves it whatever its `kind`: hand its `client_secret` to the payments element's `handleNextAction`. After it, `wait_for_payment` is blocking because the money is still moving and everything past that point would tell the buyer their order landed — hold, wait `poll_after_seconds`, and read again. The post-completion actions (`upgrade_authentication`, `redirect`, `await_claim`) are advisory: the purchase stands either way. After completion the action can also depend on WHO is reading: a signed-in buyer may be handed the `redirect` where an anonymous read of the same session gets `await_claim` — told to check their email to claim the purchase, or that the checkout finished on another device — and a read from outside whop.com's own pages (an embedded element) may be handed a `redirect` whose destination is whop.com's checkout-finish page instead of the seller's: execute it like any other redirect, and treat the URL as the credential it carries. This is an instruction, never the gate: confirm re-checks everything for itself, so a client that skips a blocking action is refused all the same. `upgrade_authentication` carries its own recipe (`email`, `sign_in_intent`); when its `session_intent_id` is non-null, the reader's own mid-checkout sign-in already proved the first factor and the recipe collapses to its last step — call that session intent's upgrade endpoint directly (the credential the sign-in installed authorizes it) and collect only what the login still owes. oneOf: - $ref: '#/components/schemas/CheckoutSessionNextAction' - type: 'null' object: description: Always `checkout_session`. example: checkout_session type: string payment: description: >- The payment the confirm created, or `null` while none exists. Read it with its `status`: a completed session's payment can still be `requires_action` (a step remains) or `processing` (accepted, settling). `failed` is a transient reading — a charge that decisively dies reopens the session on the next read, unbinding the dead payment and recording the failure on `last_confirm_error`. Anything the charge still needs comes through `next_action`, which is also where the payment's own credential lives. oneOf: - $ref: '#/components/schemas/CheckoutSessionPayment' - type: 'null' payment_method_configuration: description: >- The configuration governing this session, resolved through every layer — the checkout configuration it was mounted from, the plan's, and the account's. Apply it over the payment method types catalogue for the offerable set. `null` means nothing is configured at any layer: platform defaults apply. oneOf: - $ref: '#/components/schemas/CheckoutSessionPaymentMethodConfiguration' - type: 'null' payment_method_required: description: >- Whether confirm needs a `confirmation_token`. `false` when no charge will ever take money — a free plan, a transfer of a non-renewing plan, or an applied promo code that makes every charge free, now and forever: collect no payment method there and confirm without a token. Live like every session fact: applying or removing a code can flip it, so mount your payment surface off this field, never off a zero total — a checkout that charges nothing today but something later (a trial, a first-charge-only code) stays `true`. example: true type: boolean phone_number: description: >- The buyer's phone number, or `null`. Collected when the session publishes a `phone_number` requirement (the seller collects numbers), set through update, and recorded against the order. Buyer-typed and unverified — sellers who VERIFY numbers get the `verify_phone` next action instead, which writes to the buyer's account. example: +xxxxxxxxxxx type: - string - 'null' promo: description: >- What the applied code takes off and which charges it covers, or `null` when no code applies. `promo_code` is the writable field; this is its resolved semantics — the duration says which future charges the breakdown's `upcoming` amounts have the discount in. oneOf: - $ref: '#/components/schemas/CheckoutSessionPromo' - type: 'null' promo_code: description: >- The promo code applied to the quote, or `null`. Set it via update; the discount shows up in the quote. example: code2 type: - string - 'null' quote: $ref: '#/components/schemas/CheckoutSessionQuote' description: >- The current price of the items, computed by the server on every read. Confirm charges this number while it is fresh. redirect_url: description: >- Where the SELLER sends the buyer after a completed purchase, when the checkout configuration this session was mounted from sets one. Always an absolute HTTP or HTTPS URL — anything else serializes as `null`. Distinct from `return_url`, which is the payment provider's return leg. example: https://shinetime.example/thanks type: - string - 'null' requirements: items: $ref: '#/components/schemas/CheckoutSessionRequirement' description: >- What this checkout's form must collect — render every entry together on one screen. Derived on every read, not fixed when the session was created: it changes as the seller's settings change, as the session is updated, and as a buyer is resolved. Empty once the session is no longer `open`. type: array return_url: description: >- Where the buyer lands after an off-site payment step. Must be an absolute https URL without credentials (http is allowed for localhost). type: - string - 'null' seller: $ref: '#/components/schemas/CheckoutSessionSeller' description: The seller this checkout purchases from. shipping_address: description: >- Where physical goods ship, or `null`. Only the keys the buyer supplied are present. oneOf: - $ref: '#/components/schemas/CheckoutSessionShippingAddress' - type: 'null' show_promo_code_input: description: >- Whether to offer promo code entry on this checkout: `false` on a membership transfer, a checkout with nothing due, or a one-off purchase — no code can apply — and when the seller disabled codes for it, or none exists to enter. A code already on the session still discounts either way. example: true type: boolean status: description: >- `open` until a confirm succeeds (`completed`) or the session ages out (`expired`). Only an `open` session can be updated or confirmed. A `completed` session whose charge later decisively dies returns to `open` with the failure on `last_confirm_error` — the same session takes the retry. enum: - open - completed - expired example: completed type: string tax_behavior: description: >- Whether this checkout collects tax, and how its price reads when it does. `null` means no tax is collected here — skip `calculate_tax` entirely and ask for no more address than the payment method itself needs. `exclusive` means tax is ADDED to the quote, `inclusive` that the quote already contains it. Present before any address is known, so a surface can decide what to collect up front; the value is what this checkout expects to price with, and `calculate_tax` answers with the authoritative one once a location is known (tax behaviour varies by country). enum: - inclusive - exclusive - null example: inclusive type: - string - 'null' tax_id: description: >- The buyer's tax registration for a business purchase, or `null`. Set it via update (`null` clears it); a stored registration re-prices the quote's tax row — a valid EU B2B id reverse-charges EU VAT — and confirm charges tax under the same registration, so the shown total and the taken one agree. oneOf: - $ref: '#/components/schemas/CheckoutSessionTaxId' - type: 'null' three_ds_level: description: >- The 3D Secure behavior the checkout configuration asks for, or `null` to use the plan's or the account's default. enum: - mandate_challenge - frictionless - null example: frictionless type: - string - 'null' top_up_membership: description: >- The membership this checkout tops up (`mem_…`), or `null` for an ordinary purchase. Set at create only. Confirming charges the plan's price against that existing membership instead of creating a new one — no stock is taken, and for an expiring plan the paid time stacks onto what is left. The buyer must own it: confirm resolves it against the resolved buyer's own memberships and refuses anything else as not found. example: mem_xxxxxxxxxxxxxx type: - string - 'null' transfer: description: >- The membership transfer this checkout performs, or `null` for an ordinary purchase. Present when the session was mounted from a transfer link: confirming moves the linked membership to this buyer instead of creating a fresh purchase, the quote prices zero due today, and for a renewing plan the collected payment method takes over the origin's future renewals. oneOf: - $ref: '#/components/schemas/CheckoutSessionTransfer' - type: 'null' required: - id - object - status - mode - seller - checkout_configuration - items - display_currency - available_currencies - quote - transfer - top_up_membership - invoice_due_at - payment_method_required - cta_label - tax_behavior - buyer_id - buyer_email - buyer_identity - buyer_identity_method - buyer_identity_at - promo_code - promo - show_promo_code_input - affiliate_code - custom_field_responses - shipping_address - phone_number - tax_id - collect_tax_id - metadata - return_url - redirect_url - three_ds_level - payment_method_configuration - branding - payment - entry - requirements - next_action - last_confirm_error - created_at - expires_at type: object CheckoutSessionBranding: properties: background_color: description: Page background, as a `#rrggbb` hex color. type: - string - 'null' background_text_color: description: '`black` or `white`, whichever reads against the background.' type: - string - 'null' border_style: description: The corner style the seller chose. enum: - rounded - pill - rectangular - null example: rounded type: - string - 'null' button_color: description: Pay button fill, as a `#rrggbb` hex color. type: - string - 'null' button_radius: description: The CSS `border-radius` for buttons at that border style. type: - string - 'null' button_text_color: description: '`black` or `white`, whichever reads against the button.' type: - string - 'null' container_radius: description: The CSS `border-radius` for containers at that border style. type: - string - 'null' font_family: description: The font the seller chose. enum: - system - roboto - open_sans - null example: system type: - string - 'null' font_url: description: The stylesheet to load for that font, or `null` for the system font. type: - string - 'null' input_radius: description: The CSS `border-radius` for inputs at that border style. type: - string - 'null' resolved_font_family: description: >- The CSS `font-family` value for that font, or `null` for the system font. type: - string - 'null' required: - background_color - background_text_color - button_color - button_text_color - font_family - resolved_font_family - font_url - border_style - button_radius - input_radius - container_radius type: object CheckoutSessionCustomFieldResponse: properties: id: description: >- The plan custom field this answers, prefixed `field_` — the `id` of the matching entry published by the `custom_fields` requirement. example: field_xxxxxxxxxxxxxx type: string value: description: The buyer's answer, as typed. example: buyer#1234 type: string required: - id - value type: object CheckoutSessionEntry: properties: id: description: The waitlist entry created by the confirm, prefixed `entry_`. type: string status: description: >- Where the join stands. `succeeded` — the join stands (whether the seller accepts it is the entry resource's own story). `requires_action` — the card save has a step left, carried by `next_action`. `processing` — the save is being decided; hold. `failed` — the card save died: the buyer is NOT on the waitlist, and needs a fresh checkout to join. enum: - requires_action - processing - succeeded - failed example: requires_action type: string required: - id - status type: object CheckoutSessionItem: properties: description: description: >- The seller's longer description of the item, or `null`. Multi-line text as the seller wrote it, suited to a collapsible details block. example: Everything in the club, billed once. type: - string - 'null' expiration_days: description: >- How many days of access a one-time purchase grants, or `null` when access does not expire (a renewing plan's access follows its billing instead). type: - integer - 'null' headline: description: >- One line describing the item, or `null`. The checkout link's own description when the seller wrote one, otherwise the product's headline. example: Two seats, one invoice type: - string - 'null' image_url: description: >- The item's square art image URL, or `null` when the seller uploaded none. example: >- https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx type: - string - 'null' name: description: >- What this item is called, ready to render — the product's title, falling back to the seller's name. Never empty. example: Premium Access type: string plan: description: >- The plan being purchased (`plan_…`). The plan is the price — sessions never carry client-asserted amounts. example: plan_xxxxxxxxxxxxxx type: string quantity: description: How many of the plan the buyer is purchasing. At least 1. example: 1 type: integer required: - plan - name - headline - description - image_url - quantity - expiration_days type: object CheckoutSessionConfirmError: properties: code: description: >- What stopped the confirm. The session: `session_expired`, `session_completed`, `confirm_in_progress`, `attestation_required`. The price: `quote_expired` (already refreshed), `quote_changed` (the stored quote is not what this confirm would charge — the buyer who resolved at confirm prices differently, e.g. a returning buyer skipped past the plan's free trial; the session is already re-quoted, so re-read it, show the new total, and confirm again), `rate_expired` (the exchange rate behind a local-currency price aged out — re-read the session for a fresh one). The payment method: `token_invalid`, `payment_method_unsupported`, `payment_method_unavailable` (a saved method the token names no longer exists in the buyer's wallet — collect a fresh one). What is being sold, and whether it may still be sold: `seller_unavailable`, `promo_invalid`, `shipping_address_required`, `custom_field_invalid` (a required question is unanswered, or an answer names a question this product does not ask), `plan_archived`, `product_archived`, `out_of_stock`, `purchases_disabled`, `blocked_country`, `custom_password` (the plan's purchase password is unanswered — update the session's `password` and confirm again), `waitlist_unavailable` (this waitlist cannot be joined as asked — the message says why). The buyer: `user_suspended`, `user_banned_from_whop`, `email_required`, `free_plan_already_owned`, `waitlist_entry_pending`, `waitlist_already_member`, and `buyer_ineligible` — an account-state refusal read by someone who never proved they hold that account, so which state stays undisclosed. The payment itself: `payment_failed`. And `engine_unavailable` for a session whose mode this checkout cannot charge yet. Every one of these is terminal for this attempt as it stands — a refusal the buyer can resolve by doing something arrives as `next_action` instead. enum: - session_expired - session_completed - attestation_required - quote_expired - quote_changed - rate_expired - token_invalid - confirm_in_progress - engine_unavailable - seller_unavailable - promo_invalid - payment_method_unsupported - payment_method_unavailable - shipping_address_required - custom_field_invalid - payment_failed - waitlist_unavailable - purchases_disabled - plan_archived - product_archived - out_of_stock - custom_password - blocked_country - user_suspended - user_banned_from_whop - email_required - free_plan_already_owned - waitlist_entry_pending - waitlist_already_member - buyer_ineligible example: attestation_required type: string message: description: A human-readable explanation of the failure, safe to show the buyer. example: tos_accepted must be attested to confirm. type: string required: - code - message type: object CheckoutSessionNextAction: description: >- The ceremony to run. `type` picks the shape, and each type carries only the fields it needs, so switching on `type` gives you exactly that action's payload. Every type carries `blocking`, which says whether the sale depends on this one. discriminator: mapping: authenticate: $ref: '#/components/schemas/CheckoutSessionAuthenticateAction' await_claim: $ref: '#/components/schemas/CheckoutSessionAwaitClaimAction' complete: $ref: '#/components/schemas/CheckoutSessionCompleteAction' redirect: $ref: '#/components/schemas/CheckoutSessionRedirectAction' upgrade_authentication: $ref: '#/components/schemas/CheckoutSessionUpgradeAuthenticationAction' verify_phone: $ref: '#/components/schemas/CheckoutSessionVerifyPhoneAction' wait_for_payment: $ref: '#/components/schemas/CheckoutSessionWaitForPaymentAction' propertyName: type oneOf: - $ref: '#/components/schemas/CheckoutSessionAuthenticateAction' - $ref: '#/components/schemas/CheckoutSessionVerifyPhoneAction' - $ref: '#/components/schemas/CheckoutSessionCompleteAction' - $ref: '#/components/schemas/CheckoutSessionWaitForPaymentAction' - $ref: '#/components/schemas/CheckoutSessionUpgradeAuthenticationAction' - $ref: '#/components/schemas/CheckoutSessionRedirectAction' - $ref: '#/components/schemas/CheckoutSessionAwaitClaimAction' CheckoutSessionPayment: properties: id: description: The payment created by the confirm, prefixed `pay_`. example: pay_xxxxxxxxxxxxxx type: string status: description: >- Where the payment stands, and the only honest reading of a completed checkout's outcome. `requires_action` — a step remains and `next_action` carries it. `processing` — accepted and settling (or deciding); hold. `succeeded` — the money moved. `failed` — the charge died (declined, expired, voided): the checkout did not go through, whatever the session's own `status` says, and the buyer needs a fresh checkout to try again. enum: - requires_action - processing - succeeded - failed example: succeeded type: string required: - id - status 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 CheckoutSessionPromo: properties: amount_off: description: >- What each covered charge is discounted by. Percentage discounts are represented as a decimal fraction; fixed-amount discounts are in `currency`. example: 5 type: number code: description: The promo code, exactly as `promo_code` states it. example: code2 type: string currency: description: Currency of a fixed-amount discount; `null` for a percentage one. enum: - usd - sgd - inr - aud - brl - cad - dkk - eur - nok - gbp - sek - chf - hkd - huf - jpy - mxn - myr - pln - czk - nzd - aed - eth - ape - cop - ron - thb - bgn - idr - dop - php - try - krw - twd - vnd - pkr - clp - uyu - ars - zar - dzd - tnd - mad - kes - kwd - jod - all - xcd - amd - bsd - bhd - bob - bam - khr - crc - xof - egp - etb - gmd - ghs - gtq - gyd - ils - jmd - mop - mga - mur - mdl - mnt - nad - ngn - mkd - omr - pyg - pen - qar - rwf - sar - rsd - lkr - tzs - ttd - uzs - rub - btc - cny - usdt - kzt - awg - whop_usd - xau - null example: usd type: - string - 'null' duration: description: >- Which charges the discount covers: `forever` discounts every charge; `once` covers only the charge at purchase — the code is spent then even when it made that charge free, except on a free trial with nothing due today, where it holds until the trial's first real charge; `repeating` covers every charge landing within `number_of_intervals` calendar months of purchase. enum: - forever - once - repeating example: repeating type: string number_of_intervals: description: >- How many calendar months of charges a `repeating` promo covers, counted from purchase — a renewal scheduled past that window bills full price however few charges came before it. `null` for the other durations. example: 1 type: - integer - 'null' promo_type: description: Whether the discount is percentage-based or a fixed amount. enum: - percentage - flat_amount example: flat_amount type: string required: - code - duration - number_of_intervals - promo_type - amount_off - currency type: object CheckoutSessionQuote: properties: base_amount: description: >- The total in `base_currency`, before conversion — what the seller prices in. The figure that is actually charged is `breakdown.total`, in `currency`. example: 0 type: number base_currency: description: >- The seller's own currency for these items, lowercase. Equal to `currency` when no conversion applied. example: usd type: string breakdown: $ref: '#/components/schemas/CheckoutSessionBreakdown' description: >- The same total, itemized — what is being bought, what changes the price, and what is owed later. The tax adjustment arrives `pending` here and resolves through `calculate_tax`, which answers with this same shape: render whichever you hold, preferring the calculated one. currency: description: >- ISO currency the confirm will charge in, lowercase. This is the buyer's own currency whenever adaptive pricing applies — the card is charged in it, not shown a conversion of it. example: usd type: string exchange_rate: description: >- The locked rate `base_currency` was converted at, or `null` when the charge is in the seller's own currency. Fixed for the life of the quote. type: - number - 'null' expires_at: description: >- When this quote stops being chargeable, as an ISO 8601 timestamp. A converted quote expires with its exchange rate, which is sooner than an unconverted one. example: '2026-01-01T12:00:00.000Z' type: string quoted_at: description: >- When this quote was computed, as an ISO 8601 timestamp. A confirm against a stale quote is refused with `quote_expired` and the quote refreshes for the retry. example: '2026-01-01T12:00:00.000Z' type: string trial_skipped: description: >- Whether this quote priced the plan's free trial as SKIPPED: the resolved buyer has held this plan before, so no trial applies and the full first price is due today. Tell the buyer so before they pay — the trial they can see on the plan is not theirs to start. `false` for a plan with no trial, and for a session whose buyer is not resolved yet: a returning buyer resolving at confirm is refused with `quote_changed` and this re-prices to `true` for the retry. example: false type: boolean required: - currency - breakdown - base_currency - base_amount - exchange_rate - quoted_at - expires_at - trial_skipped type: object CheckoutSessionRequirement: properties: fields: items: $ref: '#/components/schemas/CheckoutSessionCustomField' description: >- The seller's questions, on the `custom_fields` requirement only — `null` on every other type. Each entry says what to render and whether an answer is mandatory. type: - array - 'null' type: description: >- What to collect. `custom_password` — the plan is password-protected: send the buyer's answer through update, and the entry disappears once it is right; confirm refuses while it stands. `email` — the buyer's email address; it identifies who the purchase is for, and confirm has no other way to resolve them. `terms` — explicit acceptance, sent as the `tos_accepted` attestation on confirm; show the seller's documents from `account.terms`. `custom_fields` — the seller's own questions, published in `fields`; answer them through `custom_field_responses`. `shipping_address` — a postal address for physical goods, set through `shipping_address`. `phone_number` — the seller collects buyer phone numbers: set one through update and it is recorded against the order; a missing number never refuses the confirm. The list is closed; new entries are added deliberately, so an unrecognized type is safe to skip. enum: - custom_password - email - terms - custom_fields - shipping_address - phone_number example: custom_fields type: string required: - type - fields type: object CheckoutSessionSeller: properties: id: description: Account ID, prefixed `biz_`. example: biz_xxxxxxxxxxxxxx type: string logo_url: description: >- The seller's logo image URL, or `null` when they have not uploaded one. example: >- https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx type: - string - 'null' redirect_purchase_url: description: >- Where this seller sends buyers after any purchase, or `null`. The plan's and the checkout configuration's own redirects take precedence over it. example: https://seller.example.com/after type: - string - 'null' route: description: >- The seller's store-page slug — the `:route` in `whop.com/joined/:route`, which is where a purchase lands when nothing more specific is configured. example: biz_xxxxxxxxxxxxxx type: string terms: $ref: '#/components/schemas/CheckoutSessionSellerTerms' description: >- The seller's checkout legal surface: whether explicit acceptance is required, and the policy documents it covers. title: description: The seller's public name, as the buyer knows them. example: Shine Time Auto Detailing type: string required: - id - title - logo_url - route - redirect_purchase_url - terms type: object CheckoutSessionShippingAddress: properties: city: description: City name. example: Austin type: string country: description: ISO 3166-1 alpha-2 country code, such as `US`. example: US type: string line1: description: First line of the street address. example: 123 Main St type: string line2: description: Second line of the street address. type: string name: description: >- The recipient's full name, as it should appear on the shipping label. example: Ada Lovelace type: string postal_code: description: Postal or ZIP code. example: '78701' type: string state: description: State, province, or region code, such as `CA`. type: string required: [] type: object CheckoutSessionTaxId: properties: type: description: The registration's type, such as `eu_vat`. enum: - ad_nrt - ao_tin - ar_cuit - al_tin - am_tin - aw_tin - au_abn - au_arn - eu_vat - az_tin - bs_tin - bh_vat - bd_bin - bb_tin - by_tin - bj_ifu - bo_tin - ba_tin - br_cnpj - br_cpf - bg_uic - bf_ifu - kh_tin - cm_niu - ca_bn - ca_gst_hst - ca_pst_bc - ca_pst_mb - ca_pst_sk - ca_qst - cv_nif - cl_tin - cn_tin - co_nit - cd_nif - cr_tin - hr_oib - do_rcn - ec_ruc - eg_tin - sv_nit - et_tin - eu_oss_vat - ge_vat - gh_tin - de_stn - gb_vat - gn_nif - hk_br - hu_tin - is_vat - in_gst - id_npwp - il_vat - jp_cn - jp_rn - jp_trn - kz_bin - ke_pin - kg_tin - la_tin - li_uid - li_vat - my_frp - my_itn - my_sst - mr_nif - mx_rfc - md_vat - me_pib - ma_vat - np_pan - nz_gst - ng_tin - mk_vat - no_vat - no_voec - om_vat - pe_ruc - ph_tin - pl_nip - ro_tin - ru_inn - ru_kpp - sa_vat - sn_ninea - rs_pib - sg_gst - sg_uen - si_tin - za_vat - kr_brn - es_cif - ch_uid - ch_vat - tw_vat - tj_tin - tz_vat - th_vat - tr_tin - ug_tin - ua_vat - ae_trn - us_ein - uy_ruc - uz_tin - uz_vat - ve_rif - vn_tin - zm_tin - zw_tin - sr_fin - xi_vat example: eu_vat type: string value: description: >- The registration number, stored as the buyer entered it (whitespace removed). example: DE123456789 type: string required: - type - value type: object CheckoutSessionTransfer: properties: code: description: >- The 40-character transfer code this checkout was opened from — the same value the link carried. example: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx type: string origin_expires_at: description: >- When the transferred membership's access expires, as an ISO 8601 timestamp, or `null` when it does not. The recipient inherits this — a transfer moves the remaining time, it does not restart it. type: - string - 'null' origin_renewal_period_end: description: >- When the transferred membership's current billing period ends, as an ISO 8601 timestamp, or `null` for a non-renewing membership. The recipient's first renewal charge falls here — nothing is charged at the transfer itself. example: '2026-01-01T12:00:00.000Z' type: - string - 'null' required: - code - origin_expires_at - origin_renewal_period_end 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 CheckoutSessionAuthenticateAction: properties: blocking: description: >- Whether the sale depends on this. `true` stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. `false` is advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. example: true type: boolean type: description: >- Always `authenticate`. Have the buyer prove who they are; it owns its own sequence (sign-in, a code, a second factor), so treat it as one step however many screens it takes. Read `blocking` rather than assuming a force from the type: today it appears before the charge and gates the sale — a seller who requires a verified phone number needs a signed-in buyer, because nothing can read a guest's verification state. The post-purchase account claim, which rode this type in an earlier release, is its own `upgrade_authentication` action now. enum: - authenticate example: authenticate type: string required: - type - blocking title: Authenticate type: object CheckoutSessionAwaitClaimAction: properties: blocking: description: >- Whether the sale depends on this. `true` stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. `false` is advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. example: false type: boolean state: description: >- `check_email` — the claim is not recorded yet: tell the buyer to check their email to claim their purchase. `handed_off` — the claim is recorded and the checkout finished on another device: this reader keeps seeing it, which is correct — the session never unlocks across devices. enum: - check_email - handed_off example: handed_off type: string type: description: >- Always `await_claim`. The purchase is complete, but the destination the flow ends on may only be handed to the buyer's own signed-in session — this reader presented the session's secret and nothing stronger, so it is told where the flow stands instead. Render what `state` says; there is no step to run here, and it never advances for this reader — only a read carrying the buyer's own whop.com session is handed the `redirect`. Always advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. enum: - await_claim example: await_claim type: string required: - type - blocking - state title: Await claim type: object CheckoutSessionCompleteAction: properties: blocking: description: >- Whether the sale depends on this. `true` stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. `false` is advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. type: boolean client_secret: description: >- The ATTEMPT's own credential — the payment's or the setup's, never the session's. Hand it to the payments element to finish the remaining ceremony. type: string kind: description: >- What the ceremony finishes: `payment` for a charge with a step left, `setup` for a payment method still being saved — a paid waitlist vaults the card without charging it. Informational: the executor is the same either way, so run the secret regardless of a `kind` you do not recognize. enum: - payment - setup example: payment type: string type: description: >- Always `complete`. Finish what the attempt still needs, a 3D Secure challenge or a bank redirect, by handing `client_secret` to the payments element's `handleNextAction` — one executor whatever the `kind`. Always gates the sale: it stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. enum: - complete example: complete type: string required: - type - blocking - client_secret - kind title: Complete type: object CheckoutSessionRedirectAction: properties: blocking: description: >- Whether the sale depends on this. `true` stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. `false` is advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. example: false type: boolean destination_url: description: >- Where to send the buyer. An absolute HTTP or HTTPS URL, resolved from the seller's post-purchase settings and already carrying the order's query parameters (`receipt_id`, `payment_id`, `checkout_status`, `status`, `state_id`) — navigate straight to it. Distinct from `return_url`, which is the payment provider's return leg. example: https://seller.example.com/after type: string type: description: >- Always `redirect`. Send the buyer to `destination_url`; it is where the flow ends. Always advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. enum: - redirect example: redirect type: string required: - type - blocking - destination_url title: Redirect type: object CheckoutSessionUpgradeAuthenticationAction: properties: blocking: description: >- Whether the sale depends on this. `true` stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. `false` is advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. type: boolean email: description: >- The address the sign-in starts with — the buyer's own, resolved by this checkout. Pass it to the session-intent create; the one-time code goes to this inbox, and holding that inbox is the entire proof. type: string session_intent_id: description: >- The continuation, when this reader can take it: the id (`ses_…`) of the buyer's own mid-checkout sign-in, named only when the read presented the credential that sign-in's verify installed and the sign-in can still be finished. Skip the create and the verify — the emailed factor is already proven — and call THIS intent's `upgrade` endpoint naming the checkout session: on a first-party page the same credential authorizes it with no bearer at all, and the login collects only what it still owes (nothing, or the account's second factor). `null` runs the full recipe; a refused continuation is answered the same way, by falling back to it. nullable: true type: string sign_in_intent: description: >- The `intent` to declare on the session-intent create. Declaring it is what keeps the verification credential checkout-scoped — the full login is minted only by the upgrade call, never by the code alone. enum: - payment example: payment type: string type: description: >- Always `upgrade_authentication`. The post-purchase account claim: the buyer paid as a guest, and this offers them the whop.com login that opens what they bought. Run it on the session-intent rail — create a session intent for `email` declaring `sign_in_intent` as its intent, have the buyer verify the emailed code, then call the intent's `upgrade` endpoint naming this checkout session as `checkout_session`. The upgrade installs the full login and records the claim, so the next read of the session moves past this action. Only offered on a completed purchase; a surface that cannot sign a buyer in to whop.com (an embedded mount on a merchant's page) safely ignores it. Always advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. enum: - upgrade_authentication example: upgrade_authentication type: string required: - type - blocking - email - sign_in_intent - session_intent_id title: Upgrade authentication type: object CheckoutSessionVerifyPhoneAction: properties: blocking: description: >- Whether the sale depends on this. `true` stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. `false` is advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. type: boolean type: description: >- Always `verify_phone`. The SMS round trip a seller who requires a verified number asks for. Always gates the sale: it stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. enum: - verify_phone example: verify_phone type: string required: - type - blocking title: Verify phone type: object CheckoutSessionWaitForPaymentAction: properties: blocking: description: >- Whether the sale depends on this. `true` stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. `false` is advisory: the purchase is already made and it stands whether or not the buyer ever does this, so the buyer may close the tab. type: boolean poll_after_seconds: description: >- How long to hold before reading the session again, in seconds. A hint for the next read's timing, not a budget: how long a surface is willing to keep the buyer waiting before saying "we'll email you when it clears" is the surface's own call. type: integer type: description: >- Always `wait_for_payment`. The charge is accepted and the money is still moving — a bank debit, a voucher, anything that settles later. There is nothing for the buyer to do: hold, wait `poll_after_seconds`, and read the session again. Always gates the sale: it stops the purchase until it is done — confirm refuses regardless of whether you ran it, so skipping it only costs the buyer an unexplained refusal. enum: - wait_for_payment example: wait_for_payment type: string required: - type - blocking - poll_after_seconds title: Wait for payment type: object CheckoutSessionBreakdown: properties: adjustments: items: $ref: '#/components/schemas/CheckoutSessionBreakdownAdjustment' description: >- WHAT changes the price, in application order — the charge discounts, then adds its fee, then taxes the lot. An adjustment that does not apply is ABSENT, never zero — a zero would claim it was computed and found to be nothing. The `buyer_fee` row assumes a payment method that carries the fee (all of them except buy-now-pay-later): re-call `calculate_breakdown` with the chosen method's `supports_buyer_fee` and the row drops out for a method that carries none, exactly as the charge will. type: array currency: description: >- ISO currency every figure below is in, lowercase. Every amount here is a Money object, never a bare number — see `subtotal`. 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 display: $ref: '#/components/schemas/CheckoutSessionBreakdownDisplay' description: >- WHAT TO RENDER — the summary's headline and itemized sections, decided server-side from the same computation as the figures above so the two cannot disagree. Render this rather than re-deriving rows from the figures; the figures stay authoritative for arithmetic. lines: items: $ref: '#/components/schemas/CheckoutSessionBreakdownLine' description: >- WHAT is being bought, priced the way the charge prices it — one entry per charged item. A renewing plan's first cycle is its own line, because the charge builds it that way and a collapsed subtotal diverges from what is charged by a rounding unit. type: array subtotal: $ref: '#/components/schemas/Money' description: The lines summed, before any adjustment. total: $ref: '#/components/schemas/Money' description: >- What confirm charges: the subtotal plus every RESOLVED `added` adjustment. A `pending` adjustment is deliberately NOT in it, so the number is never inflated by a figure the buyer cannot yet see itemized — with exclusive tax it therefore grows once tax resolves, and with inclusive tax it does not move at all. Once the session is `completed` it is what WAS charged: the fee and tax on the order's own receipt, and nothing is `pending`. upcoming: description: >- WHEN the rest is owed — empty for a purchase that is settled today. `type` picks the shape and each variant carries only its own fields. An order can carry several at once (a split-pay plan alongside a subscription upsell), which is why it is a list. items: $ref: '#/components/schemas/CheckoutSessionBreakdownUpcoming' type: array required: - currency - lines - subtotal - adjustments - total - upcoming - display type: object CheckoutSessionCustomField: properties: description: description: The seller's longer explanation of the question, or `null`. type: - string - 'null' field_type: description: What kind of input to render. `text` today. enum: - text example: text type: string id: description: >- The question's ID, prefixed `field_`. Echo it as the `id` of the matching `custom_field_responses` entry. example: field_xxxxxxxxxxxxxx type: string name: description: The question as the seller wrote it — the field's label. example: Discord handle type: string placeholder: description: Placeholder text for the input, or `null`. type: - string - 'null' required: description: >- Whether confirm refuses without an answer. An unanswered required question is refused with `custom_field_invalid`. example: true type: boolean required: - id - name - description - placeholder - field_type - required type: object CheckoutSessionSellerTerms: properties: eula_url: description: >- The seller's end-user licence agreement, or `null` if they have not published one. type: - string - 'null' privacy_policy_url: description: >- The seller's privacy policy, or `null` if they have not published one. type: - string - 'null' required: description: >- Whether the buyer must explicitly accept the seller's terms before confirming. `true` means hold the confirm behind a deliberate act of acceptance; `false` means the buyer paying through a visible disclosure is the acceptance. example: false type: boolean return_policy_url: description: >- The seller's return policy, or `null` if they have not published one. type: - string - 'null' terms_url: description: >- The seller's terms of service, or `null` if they have not published one. type: - string - 'null' required: - required - terms_url - privacy_policy_url - return_policy_url - eula_url type: object CheckoutSessionBreakdownAdjustment: properties: amount: description: >- What this adjustment does to the total — negative for a discount. `null` only while `status` is `pending`. oneOf: - $ref: '#/components/schemas/Money' - type: 'null' applied: description: >- `added` counts toward the total; `included` is already inside the lines and is shown for disclosure only (inclusive-tax markets). enum: - added - included example: added type: string kind: description: >- What changes the price: the promo's `discount`, the `buyer_fee` the charge adds, or `tax`. enum: - discount - buyer_fee - tax example: tax type: string label: description: What to show the buyer for this row. example: Tax type: string rate: description: >- The `tax` row's effective rate as a decimal fraction (`"0.0725"` is 7.25%) — the tax as a share of the base it was priced on, stated so a surface can label the row with the percentage. Present only on a resolved tax adjustment from `calculate_breakdown` or `calculate_tax`; absent on other kinds, on a `pending` row, and on a completed session's settled row. example: '0.19' type: string status: description: >- Present only on an adjustment with no figure yet — render its row in a loading state and expect `calculate_breakdown` to resolve it. An adjustment that does not apply is absent from the list entirely, never a zero row. enum: - pending example: pending type: string required: - kind - label - amount - applied type: object CheckoutSessionBreakdownDisplay: properties: headline: $ref: '#/components/schemas/CheckoutSessionBreakdownDisplayHeadline' description: >- The hero: the figure (or trial length, or the word "Free") and the one-line context under it. sections: $ref: '#/components/schemas/CheckoutSessionBreakdownDisplaySections' description: >- The itemized sections below — line items, charges, totals, and the collapsible fee breakdown. All empty on a free checkout. required: - headline - sections type: object CheckoutSessionBreakdownLine: properties: amount: $ref: '#/components/schemas/Money' description: >- The line's own total — `unit_amount` × `quantity`, before any adjustment. description: description: What to show the buyer for this line. example: Purchase type: string kind: description: >- What this line is — `plan` today. New kinds arrive as checkout learns to sell more than one thing at once. enum: - plan example: plan type: string quantity: description: How many. example: 1 type: integer unit_amount: $ref: '#/components/schemas/Money' description: Price of one, before any adjustment. required: - kind - description - quantity - unit_amount - amount 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 CheckoutSessionBreakdownUpcoming: description: >- One amount owed after today. `type` picks the shape — `one_time` is a single later charge, `recurring` an open-ended subscription, `installments` a fixed count of payments — and each variant carries only its own fields, so switching on `type` gives you exactly that entry's payload. discriminator: mapping: installments: $ref: '#/components/schemas/CheckoutSessionBreakdownUpcomingInstallments' one_time: $ref: '#/components/schemas/CheckoutSessionBreakdownUpcomingOneTime' recurring: $ref: '#/components/schemas/CheckoutSessionBreakdownUpcomingRecurring' propertyName: type oneOf: - $ref: '#/components/schemas/CheckoutSessionBreakdownUpcomingOneTime' - $ref: '#/components/schemas/CheckoutSessionBreakdownUpcomingRecurring' - $ref: '#/components/schemas/CheckoutSessionBreakdownUpcomingInstallments' CheckoutSessionBreakdownDisplayHeadline: properties: amount: description: >- The figure to headline when `kind` is `amount` — already posture-correct. `null` on the other kinds. oneOf: - $ref: '#/components/schemas/Money' - type: 'null' context: items: $ref: '#/components/schemas/CheckoutSessionBreakdownDisplayRow' description: >- The lines under the headline, in render order — the billing period, "Due today", or what follows the trial ("Then … starting …"); a stepping promo adds the price the schedule returns to, with its own start date; a waitlist face ends with its no-charge-until-accepted notice. Empty when the headline stands alone. type: array free_until: description: >- When `kind` is `free` on a renewing membership transfer: the instant the transferred paid period ends and the takeover starts billing, as an ISO 8601 timestamp — word the headline "Free until …". `null` everywhere else. type: - string - 'null' kind: description: >- The headline's face: `amount` headlines the figure in `amount`; `trial` headlines the free-trial length off `trial_days`; `free` headlines the word — the served free signal or a membership transfer collecting nothing today (a renewing transfer states when its free stretch ends in `free_until`), never derived from zero prices (a promo covering the whole first charge is not a free plan). enum: - amount - trial - free example: amount type: string original_amount: description: >- The pre-promo figure to strike through beside `amount`, or `null` when no discount moved today's charge. oneOf: - $ref: '#/components/schemas/Money' - type: 'null' text: description: >- The headline in English — the fallback for a kind the surface cannot name. A surface that knows the kind renders its own wording from `amount`/`trial_days`/`free_until`. example: $10.00 type: string trial_days: description: >- The free-trial length when `kind` is `trial`, in days. `null` on the other kinds. type: - integer - 'null' required: - kind - text - amount - original_amount - trial_days - free_until - context type: object CheckoutSessionBreakdownDisplaySections: properties: charges: items: $ref: '#/components/schemas/CheckoutSessionBreakdownDisplayRow' description: >- What is added to (or disclosed inside) today's charge — the `tax_today` row once tax is priced, pending while it is being priced, absent when this checkout taxes nothing. type: array fee_breakdown: items: $ref: '#/components/schemas/CheckoutSessionBreakdownDisplayRow' description: >- The collapsible price breakdown: the `item_subtotal` beside the `service_fee`, present only when a fee actually charges today. type: array line_items: items: $ref: '#/components/schemas/CheckoutSessionBreakdownDisplayRow' description: >- What today's charge is made of, when the headline alone cannot say: a renewal's one-off `initial_fee`, and the `renewal_fee` beside it. type: array totals: items: $ref: '#/components/schemas/CheckoutSessionBreakdownDisplayRow' description: >- The totals block, in render order: what today collects (`total_due_today`, a waitlist's `total_if_accepted`, or a renewing transfer's `total_due_starting`), then `total_after_trial`, then `post_promo`. type: array required: - line_items - charges - totals - fee_breakdown type: object CheckoutSessionBreakdownUpcomingInstallments: properties: amount: $ref: '#/components/schemas/Money' description: >- What the NEXT installment takes, priced as its receipt will be: the cycle for the quantity, the buyer service fee it carries, and the promo applied only when its duration still covers that charge. Stated before tax. charge_at: description: When the next installment is charged, as an ISO 8601 timestamp. type: string description: description: What to show the buyer for this future charge. type: string interval_days: description: Days between installments. type: integer post_promo_amount: $ref: '#/components/schemas/Money' description: >- What each installment takes once the applied promo stops covering them — the plan's own installment price, stated like `amount` (quantity, buyer fee, before tax). Present only when `amount` is discounted by a promo that expires before the remaining installments do; absent when no promo discounts the next installment, and for a `forever` code. remaining: description: >- How many of the plan's payments are LEFT after today. Only a charge that takes money consumes one — today's does when something is due now, while a free trial or a transfer leaves every payment ahead. type: integer trial_days: description: >- Free-trial days before the first installment. Absent when the plan starts billing with this purchase. type: integer type: description: >- Always `installments`: a fixed number of payments with a countable end. enum: - installments example: installments type: string required: - type - description - amount - charge_at - interval_days - remaining title: Installments type: object CheckoutSessionBreakdownUpcomingOneTime: properties: amount: $ref: '#/components/schemas/Money' description: What the charge takes. charge_at: description: When it is charged, as an ISO 8601 timestamp. type: string description: description: What to show the buyer for this future charge. type: string type: description: 'Always `one_time`: a single later charge with no cadence behind it.' enum: - one_time example: one_time type: string required: - type - description - amount - charge_at title: One-time type: object CheckoutSessionBreakdownUpcomingRecurring: properties: amount: $ref: '#/components/schemas/Money' description: >- What the NEXT charge takes, priced as its receipt will be: the renewal for the quantity, the buyer service fee it carries, and the promo applied only when its duration still covers that charge — a `forever` code discounts every cycle, a `once` or `repeating` one only the paying charges it has left. Stated before tax. charge_at: description: >- When the NEXT charge happens — a trial's end, a transfer's inherited period end, or the next cycle — as an ISO 8601 timestamp. example: '2026-01-01T12:00:00.000Z' type: string description: description: What to show the buyer for this future charge. example: Subscription type: string interval_days: description: Days between charges. example: 30 type: integer post_promo_amount: $ref: '#/components/schemas/Money' description: >- What each charge takes once the applied promo stops covering renewals — the steady price the subscription returns to, priced like `amount` (quantity, buyer fee, before tax). Present only when `amount` is discounted by a promo that expires (a `once` code covering the first real charge, or a `repeating` window the schedule outlives — `promo.duration` says which). Absent when no promo discounts the next charge, and for a `forever` code, whose discount never ends. trial_days: description: >- Free-trial days before the first charge. Absent when billing starts with this purchase — and on a membership transfer, which inherits the origin's clock and never re-trials. type: integer type: description: >- Always `recurring`: an open-ended subscription with no countable end. enum: - recurring example: recurring type: string required: - type - description - amount - charge_at - interval_days title: Recurring type: object CheckoutSessionBreakdownDisplayRow: properties: amount: description: >- The row's figure as a Money object, when it has one — what a surface formats in the buyer's locale. oneOf: - $ref: '#/components/schemas/Money' - type: 'null' detail: description: >- The typed parameters this row's wording is built from — the localization rail. Absent when the kind needs none. oneOf: - $ref: '#/components/schemas/CheckoutSessionBreakdownDisplayRowDetail' - type: 'null' kind: description: >- Which row this is. Render a kind you know from `detail` in your own wording; render one you do not from `label` and `text` verbatim — never drop it. enum: - then_starting - then_after_trial - due_today - period - one_time_payment - access_window - access_until - trial_window - waitlist_notice - waitlist_trial_notice - free_forever - tax_included - promo_free_period - initial_fee - renewal_fee - tax_today - total_due_today - total_if_accepted - total_due_starting - total_after_trial - post_promo - item_subtotal - service_fee example: tax_today type: string label: description: >- The row's left side in English — the fallback for a kind the surface cannot name. Absent on a row that is a single line rather than a label/value pair (the headline's context). example: Estimated tax due today (19%) type: string status: description: >- Present only on a row whose figure is still being calculated — render it in a loading state and expect `calculate_breakdown` to resolve it. enum: - pending example: pending type: string text: description: >- The row's value (or its whole line) in English — the fallback for a kind the surface cannot name. Absent while `status` is `pending`. example: $1.90 type: string required: - kind type: object CheckoutSessionBreakdownDisplayRowDetail: properties: access_days: description: How many days of access a one-time purchase grants, when it expires. type: integer access_until: description: >- When a transferred membership's access ends, as an ISO 8601 timestamp — the recipient gets the origin's REMAINING time, never a fresh grant of the plan's window. type: string applied: description: >- The tax row's application: `added` counts toward the total; `included` is already inside the prices and is disclosed, never added. enum: - added - included example: added type: string charge_at: description: >- The instant this row's charge lands, as an ISO 8601 timestamp — format it in the buyer's locale rather than deriving a date client-side. type: string code: description: >- The promo code (uppercased) whose coverage this row states — "Then your first month is free with FREETODAY". type: string initial_fee: $ref: '#/components/schemas/Money' description: >- The one-off fee inside today's `due_today` charge — name it ("Due today — includes a one-time $50.00 fee") so the figure does not read as the recurring rate. interval_days: description: >- Days between recurring charges, for wording the billing period (30 is monthly, 365 yearly). type: integer invoice: description: >- Present (and `true`) when this one-time payment collects a seller-issued invoice — word it as a bill ("Invoice — one-time payment.") beside the session's own due date, never as a storefront purchase. type: boolean paid_trial: description: >- Present (and `true`) when the trial this row follows charges a fee today — the wording drops the word "trial" for the neutral "after N days", exactly as the legacy checkout worded a paid trial. type: boolean rate: description: >- The tax row's effective rate as a decimal fraction (`"0.0725"` is 7.25%), when the calculation stated one. example: '0.19' type: string remaining_payments: description: >- How many payments are still AHEAD at this row's amount — today's paying receipt already consumed one of the plan's total, exactly as billing counts receipts. Word it as the future stream ("for 3 more payments"), never as the plan's total. type: integer total_payments: description: >- An installment plan's PLAN-WIDE payment count, today's paying charge included — word it as the plan's total ("for a total of 4 payments"). Mutually exclusive with `remaining_payments`: a row states whichever count it means. type: integer trial_days: description: The free-trial length this row speaks about, in days. type: integer without_tax: description: >- Present (and `true`) when this row's amount is stated before tax and the wording must say so — the checkout adds exclusive tax the future charge will carry on top. type: boolean required: [] type: object responses: 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 Conflict: content: application/json: schema: $ref: '#/components/schemas/V1ErrorResponse' description: Conflict ````