# Access Token
Source: https://docs.whop.com/api-reference/access-tokens/access-token

A short-lived access token used to authenticate API requests on behalf of a user.

<ResponseExample>
  ```json Example theme={null}
  {
  	"expires_at": "2023-12-01T05:00:00.401Z",
  	"token": "<string>"
  }
  ```
</ResponseExample>

<ResponseField name="expires_at" type="string<date-time>">
  The timestamp after which this access token is no longer valid and must be refreshed.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="token" type="string">
  The signed JWT access token string to include in API request Authorization
  headers.
</ResponseField>


# Create access token
Source: https://docs.whop.com/api-reference/access-tokens/create-access-token

/openapi/api-v1-stable.json post /access_tokens
Create a short-lived access token for authenticating API requests. When using API key authentication, provide company_id or user_id. When using OAuth, the user is derived from the token. Use this token with Whop's web and mobile embedded components.



# Account Link
Source: https://docs.whop.com/api-reference/account-links/account-link

A temporary, time-limited URL that grants a user access to an external account management page.

<ResponseExample>
  ```json Example theme={null}
  {
  	"expires_at": "2023-12-01T05:00:00.401Z",
  	"url": "https://whop.com/payouts/biz_xxxxxxxxx/verify"
  }
  ```
</ResponseExample>

<ResponseField name="expires_at" type="string<date-time>">
  The timestamp after which this account link URL is no longer valid.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="url" type="string">
  The temporary URL to redirect the user to for account access. Expires at the time specified by expires\_at.

  Example: `https://whop.com/payouts/biz_xxxxxxxxx/verify`
</ResponseField>


# Create account link
Source: https://docs.whop.com/api-reference/account-links/create-account-link

/openapi/api-v1-stable.json post /account_links
Generate a URL that directs a sub-merchant to their account portal, such as the hosted payouts dashboard or the KYC onboarding flow.



# Ad Report
Source: https://docs.whop.com/api-reference/ad-reports/ad-report

An ads performance report. Always returns a summary. The `granularity` field contains a per-bucket time series when the `granularity` arg is set; the `breakdown` field contains per-entity rows when the `breakdown` arg is set.

<ResponseExample>
  ```json Example theme={null}
  {
  	"breakdown": [
  		{
  			"granularity": [
  				{
  					"bucket_start": "2023-12-01T05:00:00.401Z",
  					"clicks": 42,
  					"granularity": "hourly",
  					"impressions": 42,
  					"reach": 42,
  					"result_count": 42,
  					"result_label_key": null,
  					"result_label_override": "<string>",
  					"spend": 6.9,
  					"spend_currency": "usd",
  					"stat_date": "2023-12-01T05:00:00.401Z",
  					"stat_hour": 42
  				}
  			],
  			"id": "<string>",
  			"level": "campaign",
  			"name": "<string>",
  			"summary": {
  				"click_through_rate": 6.9,
  				"clicks": 42,
  				"cost_per_click": 6.9,
  				"cost_per_mille": 6.9,
  				"cost_per_result": 6.9,
  				"frequency": 6.9,
  				"impressions": 42,
  				"reach": 42,
  				"result_count": 42,
  				"result_label_key": "app_installs",
  				"result_label_override": "<string>",
  				"return_on_ad_spend": 6.9,
  				"spend": 6.9,
  				"spend_currency": "usd"
  			}
  		}
  	],
  	"granularity": [
  		{
  			"bucket_start": "2023-12-01T05:00:00.401Z",
  			"clicks": 42,
  			"granularity": "hourly",
  			"impressions": 42,
  			"reach": 42,
  			"result_count": 42,
  			"result_label_key": "app_installs",
  			"result_label_override": "<string>",
  			"spend": 6.9,
  			"spend_currency": "usd",
  			"stat_date": "2023-12-01T05:00:00.401Z",
  			"stat_hour": 42
  		}
  	],
  	"summary": {
  		"click_through_rate": 6.9,
  		"clicks": 42,
  		"cost_per_click": 6.9,
  		"cost_per_mille": 6.9,
  		"cost_per_result": 6.9,
  		"frequency": 6.9,
  		"impressions": 42,
  		"reach": 42,
  		"result_count": 42,
  		"result_label_key": "app_installs",
  		"result_label_override": "<string>",
  		"return_on_ad_spend": 6.9,
  		"spend": 6.9,
  		"spend_currency": "usd"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="breakdown" type="array<object> | null">
  Per-entity rows over the date range. `null` when the `breakdown` arg on `adReport` is omitted; otherwise contains one row per ad campaign, ad group, or ad inside the requested scope at the requested level.

  <Expandable title="child attributes">
    <ResponseField name="granularity" type="array<object> | null">
      Per-bucket time series for this entity over the date range, ordered ascending by `bucketStart`. `null` when the `granularity` arg on `adReport` is omitted; otherwise contains rows at the requested grain (`daily` or `hourly`).

      <Expandable title="child attributes">
        <ResponseField name="bucket_start" type="string<date-time>">
          The bucket's start time as a real UTC instant. `(statDate, statHour)` resolved in the ad account's reporting timezone — render this in the viewer's local timezone.

          Example: `2023-12-01T05:00:00.401Z`
        </ResponseField>

        <ResponseField name="clicks" type="integer">
          Clicks in this bucket.

          Example: `42`
        </ResponseField>

        <ResponseField name="granularity" type="Granularities">
          The bucket size of this row (`hourly`, `daily`, `weekly`, or `monthly`).

          Available options: `hourly`, `daily`, `weekly`, `monthly`
        </ResponseField>

        <ResponseField name="impressions" type="integer">
          Impressions in this bucket.

          Example: `42`
        </ResponseField>

        <ResponseField name="reach" type="integer">
          Unique users reached in this bucket. Always `0` for hourly rows (Meta does not return reach at hourly grain).

          Example: `42`
        </ResponseField>

        <ResponseField name="result_count" type="integer | null">
          Count of the primary optimization result in this bucket.

          Example: `42`
        </ResponseField>

        <ResponseField name="result_label_key" type="ResultLabelKeys | null">
          The type of optimization result represented by `resultCount`.

          Available options: `app_installs`, `messaging_conversations_started`, `post_engagement`, `event_responses`, `impressions`, `website_purchases`, `landing_page_views`, `leads`, `link_clicks`, `quality_calls`, `appointments_booked`, `messaging_purchases`, `page_likes`, `instagram_profile_visits`, `reach`, `reminders_set`, `new_subscribers`, `video_views`, `registrations`, `content_views`, `searches`, `adds_to_cart`, `adds_to_wishlist`, `adds_of_payment_info`, `checkouts_initiated`, `website_schedules`, `website_submit_applications`, `website_trials_started`, `website_subscriptions`, `website_contacts`, `website_donations`, `website_find_locations`, `website_product_customizations`, `custom`
        </ResponseField>

        <ResponseField name="result_label_override" type="string | null">
          Advertiser-defined label for the result when `resultLabelKey` is `custom`.
        </ResponseField>

        <ResponseField name="spend" type="number">
          Charged spend in this bucket in the requested reporting currency — the amount billed including platform fees, not the platform-side net spend.

          Example: `6.9`
        </ResponseField>

        <ResponseField name="spend_currency" type="Currencies">
          Currency of the `spend` value.

          Available options: `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`
        </ResponseField>

        <ResponseField name="stat_date" type="string<date-time>">
          The date these stats cover (midnight UTC). For hourly rows, see `statHour` and `bucketStart`.

          Example: `2023-12-01T05:00:00.401Z`
        </ResponseField>

        <ResponseField name="stat_hour" type="integer | null">
          Hour of the day in the ad account's reporting timezone (0-23). `null` for daily rows.

          Example: `42`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="id" type="string">
      Tag of the entity (ad campaign, ad group, or ad).
    </ResponseField>

    <ResponseField name="level" type="AdReportBreakdownLevels">
      The entity level of this row — matches the `breakdown` arg.

      Available options: `campaign`, `ad_group`, `ad`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      Display name of the entity, when available.
    </ResponseField>

    <ResponseField name="summary" type="object">
      Aggregate totals and rates for this entity over the date range.

      <Expandable title="child attributes">
        <ResponseField name="click_through_rate" type="number">
          Click-through rate (clicks / impressions).

          Example: `6.9`
        </ResponseField>

        <ResponseField name="clicks" type="integer">
          Total clicks over the date range.

          Example: `42`
        </ResponseField>

        <ResponseField name="cost_per_click" type="number">
          Cost per click in the requested reporting currency.

          Example: `6.9`
        </ResponseField>

        <ResponseField name="cost_per_mille" type="number | null">
          Cost per thousand impressions in the requested reporting currency.

          Example: `6.9`
        </ResponseField>

        <ResponseField name="cost_per_result" type="number | null">
          Spend divided by `resultCount`. Null when there are no results.

          Example: `6.9`
        </ResponseField>

        <ResponseField name="frequency" type="number | null">
          Average number of times each reached user saw an ad.

          Example: `6.9`
        </ResponseField>

        <ResponseField name="impressions" type="integer">
          Total impressions over the date range.

          Example: `42`
        </ResponseField>

        <ResponseField name="reach" type="integer">
          Unique users reached, deduplicated by the external ad platform.

          Example: `42`
        </ResponseField>

        <ResponseField name="result_count" type="integer | null">
          Count of the campaign's primary optimization result (purchases, clicks, etc.) — see `resultLabelKey`.

          Example: `42`
        </ResponseField>

        <ResponseField name="result_label_key" type="ResultLabelKeys | null">
          The type of optimization result represented by `resultCount`.

          Available options: `app_installs`, `messaging_conversations_started`, `post_engagement`, `event_responses`, `impressions`, `website_purchases`, `landing_page_views`, `leads`, `link_clicks`, `quality_calls`, `appointments_booked`, `messaging_purchases`, `page_likes`, `instagram_profile_visits`, `reach`, `reminders_set`, `new_subscribers`, `video_views`, `registrations`, `content_views`, `searches`, `adds_to_cart`, `adds_to_wishlist`, `adds_of_payment_info`, `checkouts_initiated`, `website_schedules`, `website_submit_applications`, `website_trials_started`, `website_subscriptions`, `website_contacts`, `website_donations`, `website_find_locations`, `website_product_customizations`, `custom`
        </ResponseField>

        <ResponseField name="result_label_override" type="string | null">
          Advertiser-defined label for the result when `resultLabelKey` is `custom`.
        </ResponseField>

        <ResponseField name="return_on_ad_spend" type="number | null">
          Alias for `purchaseReturnOnAdSpend` — return on ad spend for purchases, as reported by the external ad platform.

          Example: `6.9`
        </ResponseField>

        <ResponseField name="spend" type="number">
          Total spend over the date range in the requested reporting currency.

          Example: `6.9`
        </ResponseField>

        <ResponseField name="spend_currency" type="Currencies | null">
          Currency of the `spend` value. Matches the requested `currency` when set.

          Available options: `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`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="granularity" type="array<object> | null">
  Per-bucket time series over the date range, ordered ascending by `bucketStart`. `null` when the `granularity` arg on `adReport` is omitted; otherwise contains rows at the requested grain (`daily` or `hourly`).

  <Expandable title="child attributes">
    <ResponseField name="bucket_start" type="string<date-time>">
      The bucket's start time as a real UTC instant. `(statDate, statHour)` resolved in the ad account's reporting timezone — render this in the viewer's local timezone.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="clicks" type="integer">
      Clicks in this bucket.

      Example: `42`
    </ResponseField>

    <ResponseField name="granularity" type="Granularities">
      The bucket size of this row (`hourly`, `daily`, `weekly`, or `monthly`).

      Available options: `hourly`, `daily`, `weekly`, `monthly`
    </ResponseField>

    <ResponseField name="impressions" type="integer">
      Impressions in this bucket.

      Example: `42`
    </ResponseField>

    <ResponseField name="reach" type="integer">
      Unique users reached in this bucket. Always `0` for hourly rows (Meta does not return reach at hourly grain).

      Example: `42`
    </ResponseField>

    <ResponseField name="result_count" type="integer | null">
      Count of the primary optimization result in this bucket.

      Example: `42`
    </ResponseField>

    <ResponseField name="result_label_key" type="ResultLabelKeys | null">
      The type of optimization result represented by `resultCount`.

      Available options: `app_installs`, `messaging_conversations_started`, `post_engagement`, `event_responses`, `impressions`, `website_purchases`, `landing_page_views`, `leads`, `link_clicks`, `quality_calls`, `appointments_booked`, `messaging_purchases`, `page_likes`, `instagram_profile_visits`, `reach`, `reminders_set`, `new_subscribers`, `video_views`, `registrations`, `content_views`, `searches`, `adds_to_cart`, `adds_to_wishlist`, `adds_of_payment_info`, `checkouts_initiated`, `website_schedules`, `website_submit_applications`, `website_trials_started`, `website_subscriptions`, `website_contacts`, `website_donations`, `website_find_locations`, `website_product_customizations`, `custom`
    </ResponseField>

    <ResponseField name="result_label_override" type="string | null">
      Advertiser-defined label for the result when `resultLabelKey` is `custom`.
    </ResponseField>

    <ResponseField name="spend" type="number">
      Charged spend in this bucket in the requested reporting currency — the amount billed including platform fees, not the platform-side net spend.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="spend_currency" type="Currencies">
      Currency of the `spend` value.

      Available options: `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`
    </ResponseField>

    <ResponseField name="stat_date" type="string<date-time>">
      The date these stats cover (midnight UTC). For hourly rows, see `statHour` and `bucketStart`.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="stat_hour" type="integer | null">
      Hour of the day in the ad account's reporting timezone (0-23). `null` for daily rows.

      Example: `42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object">
  Aggregate totals and rates over the date range.

  <Expandable title="child attributes">
    <ResponseField name="click_through_rate" type="number">
      Click-through rate (clicks / impressions).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="clicks" type="integer">
      Total clicks over the date range.

      Example: `42`
    </ResponseField>

    <ResponseField name="cost_per_click" type="number">
      Cost per click in the requested reporting currency.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="cost_per_mille" type="number | null">
      Cost per thousand impressions in the requested reporting currency.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="cost_per_result" type="number | null">
      Spend divided by `resultCount`. Null when there are no results.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="frequency" type="number | null">
      Average number of times each reached user saw an ad.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="impressions" type="integer">
      Total impressions over the date range.

      Example: `42`
    </ResponseField>

    <ResponseField name="reach" type="integer">
      Unique users reached, deduplicated by the external ad platform.

      Example: `42`
    </ResponseField>

    <ResponseField name="result_count" type="integer | null">
      Count of the campaign's primary optimization result (purchases, clicks, etc.) — see `resultLabelKey`.

      Example: `42`
    </ResponseField>

    <ResponseField name="result_label_key" type="ResultLabelKeys | null">
      The type of optimization result represented by `resultCount`.

      Available options: `app_installs`, `messaging_conversations_started`, `post_engagement`, `event_responses`, `impressions`, `website_purchases`, `landing_page_views`, `leads`, `link_clicks`, `quality_calls`, `appointments_booked`, `messaging_purchases`, `page_likes`, `instagram_profile_visits`, `reach`, `reminders_set`, `new_subscribers`, `video_views`, `registrations`, `content_views`, `searches`, `adds_to_cart`, `adds_to_wishlist`, `adds_of_payment_info`, `checkouts_initiated`, `website_schedules`, `website_submit_applications`, `website_trials_started`, `website_subscriptions`, `website_contacts`, `website_donations`, `website_find_locations`, `website_product_customizations`, `custom`
    </ResponseField>

    <ResponseField name="result_label_override" type="string | null">
      Advertiser-defined label for the result when `resultLabelKey` is `custom`.
    </ResponseField>

    <ResponseField name="return_on_ad_spend" type="number | null">
      Alias for `purchaseReturnOnAdSpend` — return on ad spend for purchases, as reported by the external ad platform.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="spend" type="number">
      Total spend over the date range in the requested reporting currency.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="spend_currency" type="Currencies | null">
      Currency of the `spend` value. Matches the requested `currency` when set.

      Available options: `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`
    </ResponseField>
  </Expandable>
</ResponseField>


# Retrieve ad report
Source: https://docs.whop.com/api-reference/ad-reports/retrieve-ad-report

/openapi/api-v1-stable.json get /ad_reports
Performance report for a company, ad campaigns, ad groups, or ads. Always returns aggregate `summary` totals summed across the scope. Set `granularity` to additionally get a time series, or set `breakdown` (`campaign`/`ad_group`/`ad`) to additionally get per-entity rows inside the requested scope. Exactly one of `companyId`, `adCampaignIds`, `adGroupIds`, or `adIds` must be provided.

Required permissions:
 - `ad_campaign:stats:read`



# Affiliate
Source: https://docs.whop.com/api-reference/affiliates/affiliate

An affiliate tracks a user's referral performance and commission earnings for a company, including retention rates, revenue metrics, and payout configurations.

<ResponseExample>
  ```json Example theme={null}
  {
  	"active_members_count": 42,
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"title": "<string>"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"customer_retention_rate": "<string>",
  	"customer_retention_rate_ninety_days": "<string>",
  	"id": "aff_xxxxxxxxxxxxxx",
  	"monthly_recurring_revenue_usd": "<string>",
  	"status": "active",
  	"total_overrides_count": 42,
  	"total_referral_earnings_usd": "<string>",
  	"total_referrals_count": 42,
  	"total_revenue_usd": "<string>",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "Jane Smith",
  		"username": "janesmith"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="active_members_count" type="integer">
  The total active members of the affiliate

  Example: `42`
</ResponseField>

<ResponseField name="company" type="object">
  The company attached to this affiliate

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The written name of the company.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the affiliate was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="customer_retention_rate" type="string">
  The percentage of referred customers who are still active members
</ResponseField>

<ResponseField name="customer_retention_rate_ninety_days" type="string">
  The percentage of referred customers who remained active over the last 90 days
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the affiliate.

  Example: `aff_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="monthly_recurring_revenue_usd" type="string">
  The monthly recurring revenue generated by this affiliate's referrals,
  formatted as a USD currency string
</ResponseField>

<ResponseField name="status" type="Status | null">
  The status of the affiliate

  Available options: `active`, `archived`, `deleted`
</ResponseField>

<ResponseField name="total_overrides_count" type="integer">
  The total count of all overrides for this affiliate

  Example: `42`
</ResponseField>

<ResponseField name="total_referral_earnings_usd" type="string">
  The total commission earnings paid to this affiliate, formatted as a USD
  currency string
</ResponseField>

<ResponseField name="total_referrals_count" type="integer">
  The total referrals of the affiliate

  Example: `42`
</ResponseField>

<ResponseField name="total_revenue_usd" type="string">
  The total revenue generated from this affiliate's referrals, formatted as a
  USD currency string
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the affiliate was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object">
  The user attached to this affiliate

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The display name set on the user's Whop profile. Null if the user has not set a name.

      Example: `Jane Smith`
    </ResponseField>

    <ResponseField name="username" type="string | null">
      The unique username chosen by the user for their Whop profile. Null if the user has not set a username.

      Example: `janesmith`
    </ResponseField>
  </Expandable>
</ResponseField>


# Archive affiliate
Source: https://docs.whop.com/api-reference/affiliates/archive-affiliate

/openapi/api-v1-stable.json post /affiliates/{id}/archive
Archives an existing Affiliate

Required permissions:
 - `affiliate:update`



# Create affiliate
Source: https://docs.whop.com/api-reference/affiliates/create-affiliate

/openapi/api-v1-stable.json post /affiliates
Creates or finds an affiliate for a company and user.

Required permissions:
 - `affiliate:create`



# Create override
Source: https://docs.whop.com/api-reference/affiliates/create-override

/openapi/api-v1-stable.json post /affiliates/{id}/overrides
Creates a commission override for an affiliate.

Required permissions:
 - `affiliate:create`



# Delete override
Source: https://docs.whop.com/api-reference/affiliates/delete-override

/openapi/api-v1-stable.json delete /affiliates/{id}/overrides/{override_id}
Deletes an affiliate override.

Required permissions:
 - `affiliate:update`



# List affiliates
Source: https://docs.whop.com/api-reference/affiliates/list-affiliates

/openapi/api-v1-stable.json get /affiliates
Returns a paginated list of affiliates for the actor in context, with optional filtering by status, search, and sorting.

Required permissions:
 - `affiliate:basic:read`



# List overrides
Source: https://docs.whop.com/api-reference/affiliates/list-overrides

/openapi/api-v1-stable.json get /affiliates/{id}/overrides
Returns a paginated list of overrides for an affiliate.

Required permissions:
 - `affiliate:basic:read`



# Retrieve affiliate
Source: https://docs.whop.com/api-reference/affiliates/retrieve-affiliate

/openapi/api-v1-stable.json get /affiliates/{id}
Retrieves the details of an existing affiliate.

Required permissions:
 - `affiliate:basic:read`



# Retrieve override
Source: https://docs.whop.com/api-reference/affiliates/retrieve-override

/openapi/api-v1-stable.json get /affiliates/{id}/overrides/{override_id}
Retrieves the details of a specific affiliate override.

Required permissions:
 - `affiliate:basic:read`



# Unarchive affiliate
Source: https://docs.whop.com/api-reference/affiliates/unarchive-affiliate

/openapi/api-v1-stable.json post /affiliates/{id}/unarchive
Unarchives an existing Affiliate

Required permissions:
 - `affiliate:update`



# Update override
Source: https://docs.whop.com/api-reference/affiliates/update-override

/openapi/api-v1-stable.json patch /affiliates/{id}/overrides/{override_id}
Updates an existing affiliate override.

Required permissions:
 - `affiliate:update`



# App Build
Source: https://docs.whop.com/api-reference/app-builds/app-build

A versioned build artifact for a Whop React Native App, submitted for review and deployment to a specific platform.

<ResponseExample>
  ```json Example theme={null}
  {
  	"checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"file_url": "https://cdn.whop.com/builds/abc123.zip",
  	"id": "apbu_xxxxxxxxxxxxx",
  	"is_production": true,
  	"platform": "ios",
  	"review_message": "App crashes on launch. Please fix and resubmit.",
  	"source_url": "https://cdn.whop.com/builds/abc123-source.zip",
  	"status": "draft",
  	"supported_app_view_types": ["hub"]
  }
  ```
</ResponseExample>

<ResponseField name="checksum" type="string">
  A SHA-256 hash of the uploaded build file, generated by the client and used to verify file integrity.

  Example: `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7…`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the app build was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="file_url" type="string">
  A URL to download the app build as a .zip archive.

  Example: `https://cdn.whop.com/builds/abc123.zip`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the app build.

  Example: `apbu_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="is_production" type="boolean">
  Whether this build is the currently active production build for its platform.
</ResponseField>

<ResponseField name="platform" type="AppBuildPlatforms">
  The target platform for this build.

  Available options: `ios`, `android`, `web`
</ResponseField>

<ResponseField name="review_message" type="string | null">
  Feedback from the reviewer explaining why the build was rejected. Null if the build has not been reviewed or was approved.

  Example: `App crashes on launch. Please fix and resubmit.`
</ResponseField>

<ResponseField name="source_url" type="string | null">
  A URL to download the compressed source code archive that produced this build. Null if the build was uploaded without a source archive.

  Example: `https://cdn.whop.com/builds/abc123-source.zip`
</ResponseField>

<ResponseField name="status" type="AppBuildStatuses">
  The current review status of this build.

  Available options: `draft`, `pending`, `approved`, `rejected`
</ResponseField>

<ResponseField name="supported_app_view_types" type="array<AppViewTypes>">
  The list of view types this build supports, as declared by the developer.

  Available options: `hub`, `discover`, `dash`, `dashboard`, `analytics`, `skills`, `openapi`
</ResponseField>


# Create app build
Source: https://docs.whop.com/api-reference/app-builds/create-app-build

/openapi/api-v1-stable.json post /app_builds
Upload a new build artifact for an app. The build must include a compiled code bundle for the specified platform.

Required permissions:
 - `developer:manage_builds`



# List app builds
Source: https://docs.whop.com/api-reference/app-builds/list-app-builds

/openapi/api-v1-stable.json get /app_builds
Returns a paginated list of build artifacts for a given app, with optional filtering by platform, status, and creation date.

Required permissions:
 - `developer:manage_builds`



# Promote app build
Source: https://docs.whop.com/api-reference/app-builds/promote-app-build

/openapi/api-v1-stable.json post /app_builds/{id}/promote
Promote an approved or draft app build to production so it becomes the active version served to users.

Required permissions:
 - `developer:manage_builds`



# Retrieve app build
Source: https://docs.whop.com/api-reference/app-builds/retrieve-app-build

/openapi/api-v1-stable.json get /app_builds/{id}
Retrieves the details of an existing app build.

Required permissions:
 - `developer:manage_builds`



# App
Source: https://docs.whop.com/api-reference/apps/app

An app is an integration built on Whop. Apps can serve consumers as experiences within products, or serve companies as business tools.

<ResponseExample>
  ```json Example theme={null}
  {
  	"api_key": {
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"id": "<string>",
  		"token": "<string>"
  	},
  	"app_type": "b2b_app",
  	"base_url": "https://myapp.example.com",
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"title": "Pickaxe"
  	},
  	"creator": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	},
  	"dashboard_path": "/experiences/[experienceId]",
  	"default_api_key": {
  		"id": "<string>",
  		"name": "<string>",
  		"obfuscated_secret_key": "<string>",
  		"secret_key": "<string>"
  	},
  	"description": "A comprehensive analytics dashboard for tracking revenue, members, and growth metrics.",
  	"discover_path": "/experiences/[experienceId]",
  	"domain_id": "ab1c2d3e4f5g6h7i8j9k",
  	"experience_path": "/experiences/[experienceId]",
  	"hosted_url": "https://myapp.whop.app",
  	"icon": {
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"id": "app_xxxxxxxxxxxxxx",
  	"marketplace_status": "not_available",
  	"name": "Courses",
  	"oauth_client_type": "public",
  	"openapi_path": "/experiences/[experienceId]",
  	"origin": "<string>",
  	"product_id": "<string>",
  	"production_web_build": {
  		"checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  		"file_url": "https://cdn.whop.com/builds/abc123.zip",
  		"id": "apbu_xxxxxxxxxxxxx",
  		"source_url": "https://cdn.whop.com/builds/abc123-source.zip",
  		"status": "draft"
  	},
  	"redirect_uris": ["<string>"],
  	"requested_permissions": [
  		{
  			"is_required": true,
  			"justification": "<string>",
  			"permission_action": {
  				"action": "<string>",
  				"name": "<string>"
  			}
  		}
  	],
  	"route": "myapp",
  	"secrets": {},
  	"skills_path": "/experiences/[experienceId]",
  	"stats": {
  		"dau": 42,
  		"mau": 42,
  		"time_spent_last24_hours": 42,
  		"wau": 42
  	},
  	"status": "live",
  	"verified": true
  }
  ```
</ResponseExample>

<ResponseField name="api_key" type="object | null">
  The API key used to authenticate requests on behalf of this app. Null if no API key has been generated. Requires the 'developer:manage\_api\_key' permission.

  <Expandable title="child attributes">
    <ResponseField name="created_at" type="string<date-time>">
      The datetime the private api key was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the private api key.
    </ResponseField>

    <ResponseField name="token" type="string">
      This is the API key used to authenticate requests
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="app_type" type="AppTypes">
  The target audience classification for this app (e.g., 'b2b\_app', 'b2c\_app', 'company\_app', 'component').

  Available options: `b2b_app`, `b2c_app`, `company_app`, `component`, `website`
</ResponseField>

<ResponseField name="base_url" type="string | null">
  The production base URL where the app is hosted. Null if no base URL is configured.

  Example: `https://myapp.example.com`
</ResponseField>

<ResponseField name="company" type="object">
  The company that owns and publishes this app.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="creator" type="object">
  The user who created and owns the company that published this app.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="dashboard_path" type="string | null">
  The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/\[experienceId]'). Null if the specified view type is not configured.

  Example: `/experiences/[experienceId]`
</ResponseField>

<ResponseField name="default_api_key" type="object | null">
  The app's default API key, used to authenticate requests on behalf of this app. Null if the app has no default key. Requires the 'developer:manage\_api\_key' permission.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the authorized api key.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      A user set name to identify an API key
    </ResponseField>

    <ResponseField name="obfuscated_secret_key" type="string">
      A masked version of the secret key used to authenticate requests. This is so
      that the owner can easily identify which key it is without being shown the
      full secret.
    </ResponseField>

    <ResponseField name="secret_key" type="string | null">
      The secret key used to authenticate requests. This is only available if the current actor would have been able to create this api key.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="description" type="string | null">
  A written description of what this app does, displayed on the app store listing page. Null if no description has been set.

  Example: `A comprehensive analytics dashboard for tracking revenue,…`
</ResponseField>

<ResponseField name="discover_path" type="string | null">
  The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/\[experienceId]'). Null if the specified view type is not configured.

  Example: `/experiences/[experienceId]`
</ResponseField>

<ResponseField name="domain_id" type="string">
  The unique subdomain identifier for this app's proxied URL on the Whop platform. Forms the URL pattern https\://\{domain\_id}.apps.whop.com.

  Example: `ab1c2d3e4f5g6h7i8j9k`
</ResponseField>

<ResponseField name="experience_path" type="string | null">
  The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/\[experienceId]'). Null if the specified view type is not configured.

  Example: `/experiences/[experienceId]`
</ResponseField>

<ResponseField name="hosted_url" type="string | null">
  The full canonical URL where this app's hosted web build is served. Null if the app has not claimed a route.

  Example: `https://myapp.whop.app`
</ResponseField>

<ResponseField name="icon" type="object | null">
  The icon image for this app, displayed on the app store, product pages, checkout, and as the default icon for experiences using this app.

  <Expandable title="child attributes">
    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the app.

  Example: `app_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="marketplace_status" type="MarketplaceStatuses | null">
  The approval status of this app's product listing on the Whop app store. Null if the app has no associated product.

  Available options: `not_available`, `pending_review`, `live_marketplace`
</ResponseField>

<ResponseField name="name" type="string">
  The display name of this app shown on the app store and in experience navigation. Maximum 30 characters.

  Example: `Courses`
</ResponseField>

<ResponseField name="oauth_client_type" type="AppOauthClientTypes">
  How this app authenticates when exchanging OAuth authorization and refresh grants.

  Available options: `public`, `confidential`
</ResponseField>

<ResponseField name="openapi_path" type="string | null">
  The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/\[experienceId]'). Null if the specified view type is not configured.

  Example: `/experiences/[experienceId]`
</ResponseField>

<ResponseField name="origin" type="string | null">
  The full origin URL for this app's proxied domain (e.g.,
  '[https://myapp.apps.whop.com](https://myapp.apps.whop.com)'). Null if no proxy domain is configured.
</ResponseField>

<ResponseField name="product_id" type="string | null" />

<ResponseField name="production_web_build" type="object | null">
  The approved app build currently served to users on web. Null if no production build is deployed for web.

  <Expandable title="child attributes">
    <ResponseField name="checksum" type="string">
      A SHA-256 hash of the uploaded build file, generated by the client and used to verify file integrity.

      Example: `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7…`
    </ResponseField>

    <ResponseField name="file_url" type="string">
      A URL to download the app build as a .zip archive.

      Example: `https://cdn.whop.com/builds/abc123.zip`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the app build.

      Example: `apbu_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="source_url" type="string | null">
      A URL to download the compressed source code archive that produced this build. Null if the build was uploaded without a source archive.

      Example: `https://cdn.whop.com/builds/abc123-source.zip`
    </ResponseField>

    <ResponseField name="status" type="AppBuildStatuses">
      The current review status of this build.

      Available options: `draft`, `pending`, `approved`, `rejected`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="redirect_uris" type="array<string>">
  The whitelisted OAuth callback URLs that users are redirected to after
  authorizing the app.
</ResponseField>

<ResponseField name="requested_permissions" type="array<object>">
  The list of permissions this app requests when installed, including both required and optional permissions with justifications.

  <Expandable title="child attributes">
    <ResponseField name="is_required" type="boolean">
      Whether the action is required for the app to function.
    </ResponseField>

    <ResponseField name="justification" type="string">
      The reason for requesting the action.
    </ResponseField>

    <ResponseField name="permission_action" type="object">
      The action that the app will request off of users when a user installs the app.

      <Expandable title="child attributes">
        <ResponseField name="action" type="string">
          The identifier of the action.
        </ResponseField>

        <ResponseField name="name" type="string">
          The human readable name of the action.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="route" type="string | null">
  The unique subdomain route where this app's hosted web builds are served, such as 'myapp' for myapp.whop.app. Null if the app has not claimed a route.

  Example: `myapp`
</ResponseField>

<ResponseField name="secrets" type="object | null">
  The app's secrets as an object of string values. Encrypted at rest and
  injected into the app's hosted server runtime as environment bindings.
  Requires the 'developer:update\_app' permission.
</ResponseField>

<ResponseField name="skills_path" type="string | null">
  The URL path template for a specific view of this app, appended to the base domain (e.g., '/experiences/\[experienceId]'). Null if the specified view type is not configured.

  Example: `/experiences/[experienceId]`
</ResponseField>

<ResponseField name="stats" type="object | null">
  Aggregate usage statistics for this app, including daily, weekly, and monthly active user counts.

  <Expandable title="child attributes">
    <ResponseField name="dau" type="integer">
      The number of unique users who have spent time in this app in the last 24 hours. Returns 0 if no usage data is available.

      Example: `42`
    </ResponseField>

    <ResponseField name="mau" type="integer">
      The number of unique users who have spent time in this app in the last 28 days. Returns 0 if no usage data is available.

      Example: `42`
    </ResponseField>

    <ResponseField name="time_spent_last24_hours" type="integer">
      The total time, in seconds, that all users have spent in this app over the last 24 hours. Returns 0 if no usage data is available.

      Example: `42`
    </ResponseField>

    <ResponseField name="wau" type="integer">
      The number of unique users who have spent time in this app in the last 7 days. Returns 0 if no usage data is available.

      Example: `42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="AppStatuses">
  The current visibility status of this app on the Whop app store. 'live' means publicly discoverable, 'unlisted' means accessible only via direct link, and 'hidden' means not visible anywhere.

  Available options: `live`, `unlisted`, `hidden`
</ResponseField>

<ResponseField name="verified" type="boolean">
  Whether this app has been verified by Whop. Verified apps are endorsed by Whop
  and displayed in the featured apps section of the app store.
</ResponseField>


# Create app
Source: https://docs.whop.com/api-reference/apps/create-app

/openapi/api-v1-stable.json post /apps
Register a new app on the Whop developer platform. Apps provide custom experiences that can be added to products.

Required permissions:
 - `developer:create_app`
 - `developer:manage_api_key`
 - `developer:update_app`



# List apps
Source: https://docs.whop.com/api-reference/apps/list-apps

/openapi/api-v1-stable.json get /apps
Returns a paginated list of apps on the Whop platform, with optional filtering by company, type, view support, and search query.



# Retrieve app
Source: https://docs.whop.com/api-reference/apps/retrieve-app

/openapi/api-v1-stable.json get /apps/{id}
Retrieves the details of an existing app.

Required permissions:
 - `developer:manage_api_key`
 - `developer:update_app`



# Update app
Source: https://docs.whop.com/api-reference/apps/update-app

/openapi/api-v1-stable.json patch /apps/{id}
Update the settings, metadata, or status of an existing app on the Whop developer platform.

Required permissions:
 - `developer:update_app`
 - `developer:manage_api_key`



# Update requested permissions
Source: https://docs.whop.com/api-reference/apps/update-requested-permissions

/openapi/api-v1-stable.json patch /apps/{app_id}/permissions
Updates the permission requirements for an app

Required permissions:
 - `developer:update_app_authorization`



# Company Token Transaction
Source: https://docs.whop.com/api-reference/company-token-transactions/company-token-transaction

A token transaction records a credit or debit to a member's token balance within a company, including transfers between members.

<ResponseExample>
  ```json Example theme={null}
  {
  	"amount": 6.9,
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"route": "<string>",
  		"title": "<string>"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"description": "Reward for completing onboarding",
  	"id": "<string>",
  	"idempotency_key": "txn_reward_usr_123_2024",
  	"linked_transaction_id": "<string>",
  	"member": {
  		"id": "<string>"
  	},
  	"transaction_type": "add",
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="amount" type="number">
  The token amount for this transaction. Always a positive value regardless of transaction type.

  Example: `6.9`
</ResponseField>

<ResponseField name="company" type="object">
  The company whose token balance this transaction affects.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="route" type="string">
      The slug/route of the company on the Whop site.
    </ResponseField>

    <ResponseField name="title" type="string">
      The written name of the company.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the company token transaction was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="description" type="string | null">
  Free-text description explaining the reason for this token transaction. Null if no description was provided.

  Example: `Reward for completing onboarding`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the company token transaction.
</ResponseField>

<ResponseField name="idempotency_key" type="string | null">
  A unique key used to prevent duplicate transactions when retrying API requests. Null if no idempotency key was provided.

  Example: `txn_reward_usr_123_2024`
</ResponseField>

<ResponseField name="linked_transaction_id" type="string | null">
  The ID of the corresponding transaction on the other side of a transfer. Null
  if this is not a transfer transaction.
</ResponseField>

<ResponseField name="member" type="object">
  The member whose token balance was affected by this transaction.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company member.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="transaction_type" type="CompanyTokenTransactionTypes">
  The direction of this token transaction (add, subtract, or transfer).

  Available options: `add`, `subtract`, `transfer`
</ResponseField>

<ResponseField name="user" type="object">
  The user whose token balance was affected by this transaction.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# Create company token transaction
Source: https://docs.whop.com/api-reference/company-token-transactions/create-company-token-transaction

/openapi/api-v1-stable.json post /company_token_transactions
Create a token transaction to add, subtract, or transfer tokens for a member within a company.

Required permissions:
 - `company_token_transaction:create`
 - `member:basic:read`
 - `company:basic:read`



# List company token transactions
Source: https://docs.whop.com/api-reference/company-token-transactions/list-company-token-transactions

/openapi/api-v1-stable.json get /company_token_transactions
Returns a paginated list of token transactions for a user or company, depending on the authenticated actor, with optional filtering by user and transaction type.

Required permissions:
 - `company_token_transaction:read`
 - `member:basic:read`
 - `company:basic:read`



# Retrieve company token transaction
Source: https://docs.whop.com/api-reference/company-token-transactions/retrieve-company-token-transaction

/openapi/api-v1-stable.json get /company_token_transactions/{id}
Retrieves the details of an existing company token transaction.

Required permissions:
 - `company_token_transaction:read`
 - `member:basic:read`
 - `company:basic:read`



# Approve entry
Source: https://docs.whop.com/api-reference/entries/approve-entry

/openapi/api-v1-stable.json post /entries/{id}/approve
Approve a pending waitlist entry, triggering the checkout process to grant the user access to the plan.

Required permissions:
 - `plan:waitlist:manage`



# Deny entry
Source: https://docs.whop.com/api-reference/entries/deny-entry

/openapi/api-v1-stable.json post /entries/{id}/deny
Deny a pending waitlist entry, preventing the user from gaining access to the plan.

Required permissions:
 - `plan:waitlist:manage`
 - `plan:basic:read`
 - `member:email:read`



# Entry
Source: https://docs.whop.com/api-reference/entries/entry

An entry represents a user's signup for a waitlisted plan.

<ResponseExample>
  ```json Example theme={null}
  {
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"custom_field_responses": [
  		{
  			"answer": "<string>",
  			"id": "cfrp_xxxxxxxxxxxxx",
  			"question": "<string>"
  		}
  	],
  	"id": "entry_xxxxxxxxxxxx",
  	"plan": {
  		"id": "plan_xxxxxxxxxxxxx"
  	},
  	"product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"title": "Pickaxe Analytics"
  	},
  	"status": "drafted",
  	"user": {
  		"email": "john.doe@example.com",
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="created_at" type="string<date-time> | null">
  The datetime the entry was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="custom_field_responses" type="array<object> | null">
  The list of responses collected from the user when submitting their waitlist entry.

  <Expandable title="child attributes">
    <ResponseField name="answer" type="string">
      The response a user gave to the specific question or field.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the custom field response.

      Example: `cfrp_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="question" type="string">
      The question asked by the custom field
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the entry.

  Example: `entry_xxxxxxxxxxxx`
</ResponseField>

<ResponseField name="plan" type="object | null">
  The waitlisted plan that this entry is a signup for.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the plan.

      Example: `plan_xxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="product" type="object | null">
  The product associated with this entry's waitlisted plan. Null if the plan is not tied to a product.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="EntryStatus">
  The current status of the waitlist entry (e.g., drafted, pending, approved, denied).

  Available options: `drafted`, `pending`, `approved`, `denied`, `any`
</ResponseField>

<ResponseField name="user" type="object">
  The user who submitted this waitlist entry.

  <Expandable title="child attributes">
    <ResponseField name="email" type="string | null">
      The user's email address. Requires the member:email:read permission to access. Null if not authorized.

      Example: `john.doe@example.com`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# List entries
Source: https://docs.whop.com/api-reference/entries/list-entries

/openapi/api-v1-stable.json get /entries
Returns a paginated list of waitlist entries for a company, with optional filtering by product, plan, status, and creation date.

Required permissions:
 - `plan:waitlist:read`
 - `member:email:read`



# Retrieve entry
Source: https://docs.whop.com/api-reference/entries/retrieve-entry

/openapi/api-v1-stable.json get /entries/{id}
Retrieves the details of an existing waitlist entry.

Required permissions:
 - `plan:waitlist:read`
 - `member:email:read`



# Create file
Source: https://docs.whop.com/api-reference/files/create-file

/openapi/api-v1-stable.json post /files
Create a new file record and receive a presigned URL for uploading content to S3.



# File
Source: https://docs.whop.com/api-reference/files/file

A file that has been uploaded or is pending upload.

<ResponseExample>
  ```json Example theme={null}
  {
  	"content_type": "image/jpeg",
  	"filename": "document.pdf",
  	"id": "file_xxxxxxxxxxxxx",
  	"size": "123.45",
  	"upload_status": "pending",
  	"url": "<string>",
  	"visibility": "public"
  }
  ```
</ResponseExample>

<ResponseField name="content_type" type="string | null">
  The MIME type of the uploaded file (e.g., image/jpeg, video/mp4, audio/mpeg).

  Example: `image/jpeg`
</ResponseField>

<ResponseField name="filename" type="string | null">
  The original filename of the uploaded file, including its file extension.

  Example: `document.pdf`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the file.

  Example: `file_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="size" type="string | null">
  The file size in bytes. Null if the file has not finished uploading.

  Example: `123.45`
</ResponseField>

<ResponseField name="upload_status" type="UploadStatuses">
  The current upload status of the file (e.g., pending, ready).

  Available options: `pending`, `processing`, `ready`, `failed`
</ResponseField>

<ResponseField name="url" type="string | null">
  The URL for accessing the file. For public files, this is a permanent CDN URL.
  For private files, this is a signed URL that expires. Null if the file has not
  finished uploading.
</ResponseField>

<ResponseField name="visibility" type="FileVisibility">
  Whether the file is publicly accessible or requires authentication.

  Available options: `public`, `private`
</ResponseField>


# Retrieve file
Source: https://docs.whop.com/api-reference/files/retrieve-file

/openapi/api-v1-stable.json get /files/{id}
Retrieves the details of an existing file.



# Create webhook
Source: https://docs.whop.com/api-reference/webhooks/create-webhook

/openapi/api-v1-stable.json post /webhooks
Creates a new webhook

Required permissions:
 - `developer:manage_webhook`



# Delete webhook
Source: https://docs.whop.com/api-reference/webhooks/delete-webhook

/openapi/api-v1-stable.json delete /webhooks/{id}
Deletes a webhook

Required permissions:
 - `developer:manage_webhook`



# List deliveries
Source: https://docs.whop.com/api-reference/webhooks/list-deliveries

/openapi/api-v1-stable.json get /webhooks/{webhook_id}/deliveries
Returns a paginated list of delivery attempts for a webhook, ordered by most recent first. Includes the request payload, response body, response code, and timing for each attempt.

Required permissions:
 - `developer:manage_webhook`



# List webhooks
Source: https://docs.whop.com/api-reference/webhooks/list-webhooks

/openapi/api-v1-stable.json get /webhooks
Returns a paginated list of webhook endpoints configured for a company, ordered by most recently created.

Required permissions:
 - `developer:manage_webhook`



# Retrieve webhook
Source: https://docs.whop.com/api-reference/webhooks/retrieve-webhook

/openapi/api-v1-stable.json get /webhooks/{id}
Retrieves the details of an existing webhook.

Required permissions:
 - `developer:manage_webhook`



# Send test event
Source: https://docs.whop.com/api-reference/webhooks/send-test-event

/openapi/api-v1-stable.json post /webhooks/{id}/test
Tests a webhook

Required permissions:
 - `developer:manage_webhook`



# Update webhook
Source: https://docs.whop.com/api-reference/webhooks/update-webhook

/openapi/api-v1-stable.json patch /webhooks/{id}
Updates a webhook

Required permissions:
 - `developer:manage_webhook`



# Webhook
Source: https://docs.whop.com/api-reference/webhooks/webhook

A webhook endpoint that receives event notifications for a company via HTTP POST.

<ResponseExample>
  ```json Example theme={null}
  {
  	"api_version": "v1",
  	"api_version_date": "<string>",
  	"child_resource_events": true,
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"enabled": true,
  	"events": ["invoice.created"],
  	"id": "hook_xxxxxxxxxxxxx",
  	"resource_id": "<string>",
  	"testable_events": ["invoice.created"],
  	"url": "https://example.com/path",
  	"webhook_secret": "whsec_abc123def456"
  }
  ```
</ResponseExample>

<ResponseField name="api_version" type="ApiVersion">
  The API version used to format payloads sent to this webhook endpoint.

  Available options: `v1`, `v2`, `v5`
</ResponseField>

<ResponseField name="api_version_date" type="string | null">
  The dated API version (Api-Version-Date) that v1 payloads for this endpoint
  are pinned to: events serialize exactly like a REST read at this version (the
  native serializer where the resource has one). Null when unpinned — legacy
  (v2/v5) webhooks, and v1 webhooks on the legacy payload shape.
</ResponseField>

<ResponseField name="child_resource_events" type="boolean">
  Whether events are sent for child resources. For example, if the webhook is on
  a company, enabling this sends events only from the company's sub-merchants
  (child companies).
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the webhook was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Whether this webhook endpoint is currently active and receiving events.
</ResponseField>

<ResponseField name="events" type="array<WebhookEvent>">
  The list of event types this webhook is subscribed to.

  Available options: `invoice.created`, `invoice.marked_uncollectible`, `invoice.paid`, `invoice.past_due`, `invoice.voided`, `membership.activated`, `membership.deactivated`, `membership.trial_ending_soon`, `entry.created`, `entry.approved`, `entry.denied`, `entry.deleted`, `export.completed`, `export.failed`, `setup_intent.requires_action`, `setup_intent.succeeded`, `setup_intent.canceled`, `ledger_account.funds_available`, `swap.completed`, `deposit.succeeded`, `transfer.created`, `transfer.completed`, `withdrawal.created`, `withdrawal.updated`, `card_transaction.created`, `card_transaction.updated`, `card_transaction.completed`, `card_transaction.declined`, `card_transaction.reversed`, `card.created`, `card.updated`, `card.frozen`, `card.canceled`, `card_application.created`, `card_application.updated`, `card_application.approved`, `card_application.denied`, `course_lesson_interaction.completed`, `payout_method.created`, `verification.succeeded`, `identity_profile.approved`, `identity_profile.rejected`, `identity_profile.needs_action`, `identity_profile.updated`, `payout_account.status_updated`, `resolution_center_case.created`, `resolution_center_case.updated`, `resolution_center_case.decided`, `product.created`, `product.updated`, `product.deleted`, `product.published`, `product.unpublished`, `plan.created`, `plan.updated`, `plan.deleted`, `shipment.created`, `shipment.updated`, `member.created`, `chat.message.created`, `chat.reaction.created`, `payment.created`, `payment.succeeded`, `payment.failed`, `payment.pending`, `dispute.created`, `dispute.updated`, `refund.created`, `refund.updated`, `dispute_alert.created`, `membership.cancel_at_period_end_changed`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the webhook.

  Example: `hook_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="resource_id" type="string">
  The ID of the resource (company or product) this webhook is attached to.
</ResponseField>

<ResponseField name="testable_events" type="array<WebhookEvent>">
  The subset of subscribed event types that support sending test payloads.

  Available options: `invoice.created`, `invoice.marked_uncollectible`, `invoice.paid`, `invoice.past_due`, `invoice.voided`, `membership.activated`, `membership.deactivated`, `membership.trial_ending_soon`, `entry.created`, `entry.approved`, `entry.denied`, `entry.deleted`, `export.completed`, `export.failed`, `setup_intent.requires_action`, `setup_intent.succeeded`, `setup_intent.canceled`, `ledger_account.funds_available`, `swap.completed`, `deposit.succeeded`, `transfer.created`, `transfer.completed`, `withdrawal.created`, `withdrawal.updated`, `card_transaction.created`, `card_transaction.updated`, `card_transaction.completed`, `card_transaction.declined`, `card_transaction.reversed`, `card.created`, `card.updated`, `card.frozen`, `card.canceled`, `card_application.created`, `card_application.updated`, `card_application.approved`, `card_application.denied`, `course_lesson_interaction.completed`, `payout_method.created`, `verification.succeeded`, `identity_profile.approved`, `identity_profile.rejected`, `identity_profile.needs_action`, `identity_profile.updated`, `payout_account.status_updated`, `resolution_center_case.created`, `resolution_center_case.updated`, `resolution_center_case.decided`, `product.created`, `product.updated`, `product.deleted`, `product.published`, `product.unpublished`, `plan.created`, `plan.updated`, `plan.deleted`, `shipment.created`, `shipment.updated`, `member.created`, `chat.message.created`, `chat.reaction.created`, `payment.created`, `payment.succeeded`, `payment.failed`, `payment.pending`, `dispute.created`, `dispute.updated`, `refund.created`, `refund.updated`, `dispute_alert.created`, `membership.cancel_at_period_end_changed`
</ResponseField>

<ResponseField name="url" type="string">
  The destination URL where webhook payloads are delivered via HTTP POST.

  Example: `https://example.com/path`
</ResponseField>

<ResponseField name="webhook_secret" type="string">
  The secret key used to sign webhook payloads for verification. Include this in your HMAC validation logic. Returned on the create response and to interactive dashboard sessions; empty for API-key and OAuth callers on later reads.

  Example: `whsec_abc123def456`
</ResponseField>


# Getting started
Source: https://docs.whop.com/developer/api/getting-started

Start programmatically accepting payments, paying other people, and building businesses.

# Use cases

1. Create a checkout configuration
2. Onboard sub-merchants
3. Verify your platform account
4. Programmatically pay out users
5. Generate payout onboarding links for your sub-merchants

<CodeGroup>
  ```bash Typescript theme={null}
  pnpm install @whop/sdk
  ```

  ```bash Python theme={null}
  pip install whop-sdk
  ```

  ```bash Ruby theme={null}
  gem install whop_sdk
  ```
</CodeGroup>

Before you begin, follow the [Quickstart](/developer/api/quickstart#create-an-api-key) to create an API key.

<Card title="Troubleshoot API requests" icon="bug" href="/developer/troubleshooting#api-authentication">
  Debug authentication failures, permission errors, retryable responses, and sandbox/production mismatches.
</Card>

<CodeGroup>
  ```python Python theme={null}
  from whop_sdk import Whop, BadRequestError
  import random

  client = Whop(
      api_key="YOUR_API_KEY",
  )

  your_company_id = "YOUR_COMPANY_ID"

  # 1. Create a checkout configuration
  checkout = client.checkout_configurations.create(
      currency="usd",
      plan={
          "initial_price": 10.0,
          "plan_type": "one_time",
          "company_id": your_company_id,
          "currency": "usd",
          "payment_method_configuration": {
              "enabled": [
                  "crypto", # low fees
                  "us_bank_transfer", # very low fees
                  "apple_pay", # standard cc rates
              ],
              "disabled": [
                  "acss_debit",
                  "affirm",
                  "afterpay_clearpay",
                  "alipay",
                  "alma",
                  "amazon_pay",
              ],
          },
      },
      metadata={
          "order_id": "order_12345",
      },
  )

  checkout_link = f"https://whop.com/checkout/{checkout.plan.id}"
  print(f"\n✅ Checkout created → {checkout_link}\n   (redirect customers here to pay or embed it)")
  input("\nPress Enter to continue...")

  # 2. Onboard sub-merchants to pay them out
  sub_merchant = client.companies.create(
      email="merchant@example.com",
      parent_company_id=your_company_id,
      title="Acme Merchant Store #" + str(random.randint(1, 200)),
      # logo=FileAttachment("https://example.com/logo.png"),
      metadata={
          "internal_user_id": "user_12345",
          "seller_tier": "gold",
      },
  )
  print(f"\n✅ Sub-merchant onboarded → {sub_merchant.id}")

  # 2.5 Verify your platform account (skip if already done)
  # Your account must be verified to send transfers.
  print(f"\n🔐 Verify your platform account:\n   https://whop.com/payouts/{your_company_id}/verify/")
  input("\nPress Enter when done...")

  # 3. Programmatically pay out users
  while True:
      try:
          transfer = client.transfers.create(
              amount=1.0,
              currency="usd",
              origin_id=your_company_id,
              destination_id=sub_merchant.id,
              metadata={"reason": "creator_payout"},
          )
          print(f"\n✅ Transfer complete → {transfer.id}")
          break
      except BadRequestError as e:
          print(f"\n❌ Transfer failed: {e}")
          input("\nFix the issue above, then press Enter to retry...")


  # 4. Generate a payout onboarding link for your sub-merchant
  # Short-lived URL — send to the sub-merchant to complete identity verification and payout setup.
  account_link = client.account_links.create(
      company_id=sub_merchant.id,
      refresh_url="https://yourapp.com/onboarding/refresh",
      return_url="https://yourapp.com/onboarding/complete",
      use_case="account_onboarding",
  )
  print(f"\n✅ Send to sub-merchant for payout setup:\n   {account_link.url}")
  ```

  ```typescript Typescript theme={null}
  import Whop from "@whop/sdk";
  import * as readline from "node:readline/promises";

  const client = new Whop({
    apiKey: "YOUR_API_KEY",
  });

  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const yourCompanyId = "YOUR_COMPANY_ID";

  // 1. Create a checkout configuration
  const checkout = await client.checkoutConfigurations.create({
    currency: "usd",
    plan: {
      initial_price: 10.0,
      plan_type: "one_time",
      company_id: yourCompanyId,
      currency: "usd",
      payment_method_configuration: {
        enabled: [
          "crypto", // low fees
          "us_bank_transfer", // very low fees
          "apple_pay", // standard cc rates
        ],
        disabled: [
          "acss_debit",
          "affirm",
          "afterpay_clearpay",
          "alipay",
          "alma",
          "amazon_pay",
        ],
      },
    },
    metadata: {
      order_id: "order_12345",
    },
  });

  const checkoutLink = `https://whop.com/checkout/${checkout.plan.id}`;
  console.log(`\n✅ Checkout created → ${checkoutLink}\n   (redirect customers here to pay or embed it)`);
  await rl.question("\nPress Enter to continue...");

  // 2. Onboard sub-merchants to pay them out
  const subMerchant = await client.companies.create({
    email: "merchant@example.com",
    parent_company_id: yourCompanyId,
    title: `Acme Merchant Store #${Math.floor(Math.random() * 200) + 1}`,
    // logo: new File([...], "logo.png"),
    metadata: {
      internal_user_id: "user_12345",
      seller_tier: "gold",
    },
  });
  console.log(`\n✅ Sub-merchant onboarded → ${subMerchant.id}`);

  // 2.5 Verify your platform account (skip if already done)
  // Your account must be verified to send transfers.
  console.log(`\n🔐 Verify your platform account:\n   https://whop.com/payouts/${yourCompanyId}/verify/`);
  await rl.question("\nPress Enter when done...");

  // 3. Programmatically pay out users
  while (true) {
    try {
      const transfer = await client.transfers.create({
        amount: 1.0,
        currency: "usd",
        origin_id: yourCompanyId,
        destination_id: subMerchant.id,
        metadata: { reason: "creator_payout" },
      });
      console.log(`\n✅ Transfer complete → ${transfer.id}`);
      break;
    } catch (err) {
      if (err instanceof Whop.BadRequestError) {
        console.log(`\n❌ Transfer failed: ${err.message}`);
        await rl.question("\nFix the issue above, then press Enter to retry...");
        continue;
      }
      throw err;
    }
  }

  // 4. Generate a payout onboarding link for your sub-merchant
  // Short-lived URL — send to the sub-merchant to complete identity verification and payout setup.
  const accountLink = await client.accountLinks.create({
    company_id: subMerchant.id,
    refresh_url: "https://yourapp.com/onboarding/refresh",
    return_url: "https://yourapp.com/onboarding/complete",
    use_case: "account_onboarding",
  });
  console.log(`\n✅ Send to sub-merchant for payout setup:\n   ${accountLink.url}`);

  rl.close();
  ```

  ```ruby Ruby theme={null}
  require "whop_sdk"

  whop = WhopSDK::Client.new(
    api_key: "YOUR_API_KEY",
  )

  your_company_id = "YOUR_COMPANY_ID"

  # 1. Create a checkout configuration
  checkout = whop.checkout_configurations.create(
    currency: "usd",
    plan: {
      initial_price: 10.0,
      plan_type: "one_time",
      company_id: your_company_id,
      currency: "usd",
      payment_method_configuration: {
        enabled: [
          "crypto", # low fees
          "us_bank_transfer", # very low fees
          "apple_pay", # standard cc rates
        ],
        disabled: [
          "acss_debit",
          "affirm",
          "afterpay_clearpay",
          "alipay",
          "alma",
          "amazon_pay",
        ],
      },
    },
    metadata: {
      order_id: "order_12345",
    },
  )

  checkout_link = "https://whop.com/checkout/#{checkout.plan.id}"
  puts "\n✅ Checkout created → #{checkout_link}\n   (redirect customers here to pay or embed it)"
  print "\nPress Enter to continue..."
  gets

  # 2. Onboard sub-merchants to pay them out
  sub_merchant = whop.companies.create(
    email: "merchant@example.com",
    parent_company_id: your_company_id,
    title: "Acme Merchant Store ##{rand(1..200)}",
    metadata: {
      internal_user_id: "user_12345",
      seller_tier: "gold",
    },
  )
  puts "\n✅ Sub-merchant onboarded → #{sub_merchant.id}"

  # 2.5 Verify your platform account (skip if already done)
  # Your account must be verified to send transfers.
  puts "\n🔐 Verify your platform account:\n   https://whop.com/payouts/#{your_company_id}/verify/"
  print "\nPress Enter when done..."
  gets

  # 3. Programmatically pay out users
  loop do
    begin
      transfer = whop.transfers.create(
        amount: 1.0,
        currency: "usd",
        origin_id: your_company_id,
        destination_id: sub_merchant.id,
        metadata: { reason: "creator_payout" },
      )
      puts "\n✅ Transfer complete → #{transfer.id}"
      break
    rescue WhopSDK::Errors::BadRequestError => e
      puts "\n❌ Transfer failed: #{e.message}"
      print "\nFix the issue above, then press Enter to retry..."
      gets
    end
  end

  # 4. Generate a payout onboarding link for your sub-merchant
  # Short-lived URL — send to the sub-merchant to complete identity verification and payout setup.
  account_link = whop.account_links.create(
    company_id: sub_merchant.id,
    refresh_url: "https://yourapp.com/onboarding/refresh",
    return_url: "https://yourapp.com/onboarding/complete",
    use_case: "account_onboarding",
  )
  puts "\n✅ Send to sub-merchant for payout setup:\n   #{account_link.url}"
  ```
</CodeGroup>

# API Keys

<AccordionGroup>
  <Accordion title="Account API keys" icon="building">
    Use Account API keys when you only want to fetch data or perform actions for your own Account
    and [connected accounts](/supported-business-models/platforms).

    1. Follow the [Quickstart API key steps](/developer/api/quickstart#create-an-api-key) and open **Account API Keys**.
    2. Click the "Create" button in the "Account API Keys" section
    3. Give your api key a name. For example "Data pipeline" or "GHL Integration"
    4. Select a role or a custom set of permissions. (You can always update this later and add more if you need)
    5. Create the api key, and copy it from the modal.
  </Accordion>

  <Accordion title="App API keys" icon="code">
    Use app API keys when you are building an app and need to access data on companies that have installed your app.

    1. Follow the [Quickstart API key steps](/developer/api/quickstart#create-an-api-key) and open **Apps**.
    2. Click the **Create app** button and give your app a name. *You can change this name later.*
    3. Your API key is the hidden text after `WHOP_API_KEY` in the `Environment variables` section.
       Use the reveal button to show the key, copy it and keep it in a safe place.
       You will need it to make API calls.
  </Accordion>

  <Accordion title="OAuth tokens" icon="user">
    Use OAuth tokens when you want users to sign in with their Whop account and grant your app permission to act on their behalf. Unlike API keys which use your app's permissions, OAuth tokens are scoped to what each individual user can access.

    Common use cases:

    * "Sign in with Whop" authentication
    * Accessing a user's memberships, purchases, or profile
    * Performing actions as a specific user (not as your app)

    OAuth tokens are obtained through the OAuth 2.1 + PKCE flow:

    1. Redirect users to Whop's authorization page
    2. User logs in and approves your requested scopes
    3. Exchange the authorization code for access and refresh tokens
    4. Use the access token as your API key in SDK calls or the `Authorization` header

    See the [OAuth guide](/developer/guides/oauth) for full implementation details.
  </Accordion>
</AccordionGroup>

# Making API calls

Our public api is available at `https://api.whop.com/api/v1`

You can test the api by using curl to fetch your public user profile data:

```bash theme={null}
# replace "j" with your own whop username
curl https://api.whop.com/api/v1/users/j
```

To make authenticated requests you need to include your API key in the `Authorization` header using the `Bearer` scheme:

```bash theme={null}
# replace "YOUR_API_KEY" with your real API key
curl https://api.whop.com/api/v1/payments?company_id=biz_xxxxxxxxxxx \
    -H "Authorization: Bearer YOUR_API_KEY"
```

# SDK Reference

* [Typescript / Javascript](https://npmjs.com/package/@whop/sdk) / [Docs](https://github.com/whopio/whopsdk-typescript)
* [Python](https://pypi.org/project/whop-sdk) / [Docs](https://github.com/whopio/whopsdk-python)
* [Ruby](https://rubygems.org/gems/whop-sdk) / [Docs](https://github.com/whopio/whopsdk-ruby)

## MCP

You can also access the API via our mcp server available at
`https://mcp.whop.com/mcp` (cursor) or `https://mcp.whop.com/sse` (claude)

[Learn more here](/developer/guides/ai_and_mcp)


# Quickstart
Source: https://docs.whop.com/developer/api/quickstart

Create your Whop account, find the dashboard, get an API key, make your first SDK call, and test a webhook.

Use this page the first time you connect Whop to your app or backend. You'll sign up, open the dashboard, create an API key, install the SDK, make your first call, and watch a webhook land on your server.

<Note>
  Keep `WHOP_API_KEY` on your server. Do not put Account API keys in browser code, mobile apps, or public repositories.
</Note>

## Set up your account

<Steps>
  <Step title="Sign up for Whop">
    Go to [whop.com/new](https://whop.com/new) and create your Whop account. The onboarding flow creates your first business, which is the Account that owns API keys, products, webhooks, and payments.
  </Step>

  <Step title="Open the dashboard">
    After onboarding, open [whop.com/dashboard](https://whop.com/dashboard). If you have more than one business, choose the one you want to build against from the business switcher.
  </Step>

  <Step title="Open Developer">
    Click **Dashboard ↗** in the top-right corner of these docs to open your developer dashboard directly.
  </Step>
</Steps>

## Create an API key

For the quickest path, create an Account API key. Use this when your server acts on behalf of your own business.

Building a Whop App? Learn when to use [App API keys](/developer/api/getting-started#app-api-keys) and [OAuth tokens](/developer/guides/oauth).

<Steps>
  <Step title="Create an Account API key">
    In **Account API Keys**, click **Create**. Name the key something you can recognize later, like `Local development` or `Production payments`.
  </Step>

  <Step title="Choose permissions">
    For the first SDK call below, use the Admin role or grant the read permissions listed on [Retrieve Requesting Account](/api-reference/beta/accounts/retrieve-requesting-account). For production, switch to a narrower custom permission set once you know exactly which endpoints you use.
  </Step>

  <Step title="Copy the key">
    Copy the key when Whop shows it. Store it in your local `.env` file as `WHOP_API_KEY`.

    <Frame>
      <img alt="Whop dashboard Account API Keys section showing a key name, masked value, and Create button" />
    </Frame>
  </Step>
</Steps>

## Install the SDK

<CodeGroup>
  ```bash TypeScript theme={null}
  pnpm add @whop/sdk
  ```

  ```bash Python theme={null}
  pip install whop-sdk
  ```

  ```bash Ruby theme={null}
  gem install whop_sdk
  ```
</CodeGroup>

Add your credentials to `.env`:

```bash theme={null}
WHOP_API_KEY=whop_xxxxxxxxxxxxxxxxx
```

## Make your first call

Retrieve the Account tied to your API key. This confirms your key and permissions are wired correctly and prints your Account ID, which starts with `biz_`.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const apiKey = process.env.WHOP_API_KEY;

  if (!apiKey) {
    throw new Error("Set WHOP_API_KEY");
  }

  const client = new Whop({
    apiKey,
  });

  const account = await client.accounts.me();

  console.log(account.id);
  ```

  ```python Python theme={null}
  import os
  from whop_sdk import Whop

  client = Whop(
      api_key=os.environ["WHOP_API_KEY"],
  )

  account = client.accounts.me()

  print(account.id)
  ```

  ```ruby Ruby theme={null}
  require "whop_sdk"

  whop = WhopSDK::Client.new(
    api_key: ENV.fetch("WHOP_API_KEY"),
  )

  account = whop.accounts.me

  puts account.id
  ```
</CodeGroup>

## See a webhook

Whop sends a webhook to your server when something happens in your business, like `payment.succeeded` or `membership.activated`.

<Steps>
  <Step title="Create a local webhook endpoint">
    Add a `POST` endpoint in your app and expose it with ngrok, Cloudflare Tunnel, or another HTTPS tunnel while developing.
  </Step>

  <Step title="Create the webhook in the dashboard">
    Open **Developer > Webhooks**, then click **Create webhook**.

    <Frame>
      <img alt="Whop Developer Webhooks page with a Create webhook button" />
    </Frame>
  </Step>

  <Step title="Enter your URL and events">
    Paste your HTTPS endpoint, keep the API version on `v1`, and select the events you want to receive.

    <Frame>
      <img alt="Create webhook form showing the endpoint URL and API version fields" />
    </Frame>

    <Frame>
      <img alt="Create webhook form showing payment_succeeded selected in the events list" />
    </Frame>
  </Step>

  <Step title="Send a test event">
    Use the webhook row actions to send a test event. When your server logs the request, your setup is complete.

    <Frame>
      <img alt="Whop dashboard test webhook menu showing Send event" />
    </Frame>
  </Step>
</Steps>

## Next steps

<CardGroup>
  <Card title="Accept payments" href="/developer/guides/accept-payments">
    Create checkout links or embedded checkout flows.
  </Card>

  <Card title="Validate webhooks" href="/developer/guides/webhooks">
    Verify signatures and handle payment events safely.
  </Card>

  <Card title="API walkthrough" href="/developer/api/getting-started">
    Explore endpoints, SDK examples, and required permissions.
  </Card>
</CardGroup>


# CLI
Source: https://docs.whop.com/developer/cli

Install the Whop CLI, sign in, and choose or create the business you want to manage from your terminal.

The Whop CLI (`whop`) lets you build and manage your Whop business from the terminal. Deploy apps, create products, set pricing, get shareable checkout links, run ads, and pull your stats — every command also works non-interactively for scripts and AI agents.

## Install

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl -fsSL https://whop.com/install.sh | sh
  ```

  ```bash Homebrew theme={null}
  brew install whopio/tap/whop
  ```

  ```bash npm theme={null}
  npm install -g @whop/cli
  ```
</CodeGroup>

<Note>
  Prebuilt binaries cover macOS and Linux. On other platforms, install via npm (requires Node.js 22 or later).
</Note>

Confirm it works:

```bash theme={null}
whop --version
```

## Get started

Run the CLI with no arguments:

```bash theme={null}
whop
```

That's it — it signs you in through your browser and lets you choose or create the business the CLI should use.

Run `whop quickstart` later to select a different business or create another one. Then use `whop --help` to choose a workflow, such as deploying an app with `whop apps deploy` or managing products and pricing directly.

## Everyday commands

```bash theme={null}
whop --help                  # all commands
whop products list           # what you're selling
whop plans create --help     # options for any command
whop checkout-configurations create --plan_id plan_xxx   # shareable checkout link
whop stats time_series       # your numbers
whop accounts get --account_id jordan   # retrieve a business by route
```

Every command takes `--format json` for structured output, and most groups follow the same shape: `whop <resource> list|get|create|update`.

Account-scoped commands use the selected business by default. Pass another business's `biz_` ID or public route with `--account_id`.

| Command group                         | What it manages                                             |
| ------------------------------------- | ----------------------------------------------------------- |
| `products`, `plans`                   | The things you sell and their pricing                       |
| `checkout-configurations`             | Shareable, prefilled checkout links                         |
| `members`, `memberships`              | Who bought from you, and the access they hold               |
| `payouts`, `transfers`, `ledgers`     | Moving money and reading balances                           |
| `disputes`, `resolution-center-cases` | Chargebacks and buyer–merchant cases                        |
| `stats`, `exports`                    | Financial time series, and CSV dumps of any dashboard table |
| `notifications`                       | The user's feed, and sends from your app                    |
| `apps`                                | Fully-hosted web apps on `*.whop.app`                       |
| `ads`, `ad-campaigns`, `ad-groups`    | Paid acquisition                                            |
| `auth`                                | Profiles, switching accounts, API keys                      |

## Deploy an app

```bash theme={null}
whop apps deploy
```

One command verifies the current directory is a Whop-ready Vite app — offering to scaffold a new one or link an existing app if not — then builds, typechecks, uploads, and promotes the build to production. Pass `--skip_promote` to upload a preview build and `whop apps builds promote <build_id>` to ship it later.

After a deploy, read your app's server logs — every `console.log`, uncaught exception, and failed request, kept for 7 days:

```bash theme={null}
whop apps logs                    # recent logs for the linked app
whop apps logs --level error --since 1h
whop apps logs --query "checkout"
```

## Use it with AI agents

The CLI is self-describing, so agents can discover and drive every command:

```bash theme={null}
whop --llms          # machine-readable manifest of all commands
whop mcp add         # automatically register with supported coding agents
whop skills add      # generate agent skills
```

For non-interactive use — CI, scripts, or headless agents — set `WHOP_API_KEY` instead of logging in. For API commands, it takes precedence over any saved CLI profile for that invocation. Create a key under **Developer → API keys** in your [dashboard](https://whop.com/dashboard).

```bash theme={null}
WHOP_API_KEY=whop_xxx whop products list --format json
```

## Update

The CLI keeps itself up to date in the background. To update immediately:

```bash theme={null}
whop upgrade
```


# Accept payments
Source: https://docs.whop.com/developer/guides/accept-payments

Accept one-time and recurring payments across 195 countries with 100+ payment methods

<ExamplesLink href="https://whop.com/network/examples?filter=checkouts" />

<iframe title="Accept payments directly in your web app with Whop" />

Accept one-time and recurring payments using checkout links or an embedded checkout component. Whop supports **100+ payment methods** across **195 countries**, and the right ones appear automatically based on the buyer's location. [See all payment methods](/payments-and-billing/local-payment-methods).

<Tip>
  Building an iOS app? The [Whop iOS Checkout SDK](/developer/guides/ios/overview) handles checkout natively with lower fees (2.7% + \$0.30 vs Apple's 15–30%). The SDK uses a scoped `iap:read` API key that's [safe to embed in your app](/developer/guides/ios/installation#step-3-create-an-api-key).
</Tip>

## Choose your integration

|                          | Checkout link              | Embedded checkout          |
| ------------------------ | -------------------------- | -------------------------- |
| **Effort**               | Low                        | Medium                     |
| **Customization**        | Limited                    | Full control               |
| **Best for**             | Sharing links, quick setup | Custom UX, dynamic pricing |
| **Server code required** | No (Dashboard) / Yes (API) | Yes                        |

## Option 1: Create a checkout link

Checkout links are the simplest way to accept payments. Create a plan to get a shareable checkout URL.

<Tabs>
  <Tab title="Dashboard">
    1. Go to your [Dashboard](https://whop.com/dashboard/links/checkout) > **Checkout links**
    2. Click **+ Create checkout link**
    3. Select a product and configure your pricing (free, one-time, or recurring)
    4. Click **Create checkout link**

    The generated link can be shared directly with customers or embedded on your website.
  </Tab>

  <Tab title="API">
    Create a plan via the API to get a `purchase_url`:

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import Whop from "@whop/sdk";

      const client = new Whop({
        apiKey: "Company API Key",
      });

      // company_id: find in Dashboard > Settings
      // access_pass_id: find in Dashboard > Products
      const plan = await client.plans.create({
        company_id: "biz_xxxxxxxxxxxxx",
        access_pass_id: "pass_xxxxxxxxxxxxx",
        initial_price: 10.0,
        plan_type: "one_time",
      });

      console.log(plan.purchase_url);
      ```

      ```python Python theme={null}
      from whop_sdk import Whop

      client = Whop(
          api_key="Company API Key",
      )

      # company_id: find in Dashboard > Settings
      # access_pass_id: find in Dashboard > Products
      plan = client.plans.create(
          company_id="biz_xxxxxxxxxxxxx",
          access_pass_id="pass_xxxxxxxxxxxxx",
          initial_price=10.0,
          plan_type="one_time",
      )

      print(plan.purchase_url)
      ```
    </CodeGroup>

    Redirect customers to the `purchase_url` to complete payment on a Whop-hosted checkout page.
  </Tab>
</Tabs>

## Option 2: Embedded checkout

For a custom checkout experience, use the embedded checkout component with a checkout configuration.

### Step 1: Create a checkout configuration

Create a checkout configuration on your server with an inline plan:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const client = new Whop({
    apiKey: "Company API Key",
  });

  const checkoutConfig = await client.checkoutConfigurations.create({
    company_id: "biz_xxxxxxxxxxxxx",
    plan: {
      initial_price: 10.0,
      plan_type: "one_time",
    },
    metadata: {
      order_id: "order_12345",
    },
  });

  console.log(checkoutConfig.id); // ch_xxxxxxxxxxxxx (session ID)
  console.log(checkoutConfig.plan?.id); // plan_xxxxxxxxxxxxx (plan ID)
  ```

  ```python Python theme={null}
  from whop_sdk import Whop

  client = Whop(
      api_key="Company API Key",
  )

  checkout_config = client.checkout_configurations.create(
      company_id="biz_xxxxxxxxxxxxx",
      plan={
          "initial_price": 10.0,
          "plan_type": "one_time",
      },
      metadata={
          "order_id": "order_12345",
      },
  )

  print(checkout_config.id)  # ch_xxxxxxxxxxxxx (session ID)
  print(checkout_config.plan.id)  # plan_xxxxxxxxxxxxx (plan ID)
  ```
</CodeGroup>

In this example:

* `company_id` is your company ID
* `plan.initial_price` is the payment amount
* `plan.plan_type` is either `one_time` or `renewal` for subscriptions
* `metadata` stores custom data for your reference

### Step 2: Render the checkout

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    import { WhopCheckoutEmbed } from "@whop/checkout/react";

    export function Checkout({ sessionId }: { sessionId: string }) {
      return (
        <WhopCheckoutEmbed
          sessionId={sessionId}
          returnUrl="https://yoursite.com/checkout/complete"
          onComplete={(paymentId) => {
            console.log("Payment complete:", paymentId);
          }}
        />
      );
    }
    ```

    Pass the `checkoutConfig.id` from step 1 as the `sessionId` prop.
  </Tab>

  <Tab title="HTML / JavaScript">
    Add the loader script to your page:

    ```html theme={null}
    <script async defer src="https://js.whop.com/static/checkout/loader.js"></script>
    ```

    Then add a checkout element with your plan ID and the `checkoutConfig.id` from step 1:

    ```html theme={null}
    <div
      data-whop-checkout-plan-id="plan_XXXXXXXXX"
      data-whop-checkout-session="ch_XXXXXXXXX"
      data-whop-checkout-return-url="https://yoursite.com/checkout/complete"
    ></div>
    ```
  </Tab>
</Tabs>

The `returnUrl` is required to handle redirects from external payment providers. When redirected, check the `status` query parameter:

* **success**: The payment succeeded. Use the receipt information to render a success page.
* **error**: The payment failed or was canceled. Remount the checkout so your customer can try again.

### Step 3: Customize the checkout

You can customize the checkout appearance and behavior:

| Prop (React)               | Attribute (HTML)                        | Description                                  |
| -------------------------- | --------------------------------------- | -------------------------------------------- |
| `theme`                    | `data-whop-checkout-theme`              | `"light"`, `"dark"`, or `"system"` (default) |
| `hidePrice`                | `data-whop-checkout-hide-price`         | Hide the price display                       |
| `themeOptions.accentColor` | `data-whop-checkout-theme-accent-color` | Custom accent color                          |

For the full list of customization options, see the [Embedded checkout reference](/payments/checkout-embed).

## Handle payment webhooks

Listen for webhooks to fulfill orders on your server. This example uses Next.js on Vercel, but the `whopsdk.webhooks.unwrap` pattern works with any framework:

```typescript theme={null}
import { waitUntil } from "@vercel/functions";
import type { Payment } from "@whop/sdk/resources.js";
import type { NextRequest } from "next/server";
import { whopsdk } from "@/lib/whop-sdk"; // your Whop SDK instance

export async function POST(request: NextRequest): Promise<Response> {
  const requestBodyText = await request.text();
  const headers = Object.fromEntries(request.headers);
  const webhookData = whopsdk.webhooks.unwrap(requestBodyText, { headers });

  if (webhookData.type === "payment.succeeded") {
    waitUntil(handlePaymentSucceeded(webhookData.data));
  }

  return new Response("OK", { status: 200 });
}

async function handlePaymentSucceeded(payment: Payment) {
  console.log("Payment succeeded:", payment.id);
}
```

Other useful webhook events: `membership.went_valid` (access granted), `payment.failed` (payment failed).

## See it work end-to-end

The fastest way to confirm everything's wired up is to run a test charge in sandbox and watch the result flow back to your server and dashboard.

### 1. Trigger a test charge

Switch your SDK and checkout to the sandbox environment, then run a checkout with a test card. The [sandbox guide](/developer/guides/sandbox) covers the URL changes and lists test cards for every payment outcome (succeeded, failed, requires action).

### 2. Inspect the webhook payload

When the test charge settles, your webhook handler receives a `payment.succeeded` event shaped like this:

```json theme={null}
{
  "id": "msg_xxxxxxxxxxxxx",
  "api_version": "v1",
  "type": "payment.succeeded",
  "timestamp": "2026-05-12T18:42:11.041Z",
  "company_id": "biz_xxxxxxxxxxxxx",
  "data": {
    "id": "pay_xxxxxxxxxxxxx",
    "status": "succeeded",
    "amount_after_fees": 9.71,
    "currency": "usd",
    "paid_at": "2026-05-12T18:42:10Z",
    "payment_method_type": "card",
    "card_brand": "visa",
    "card_last4": "4242",
    "member": { "id": "mem_xxxxxxxxxxxxx" },
    "metadata": {
      "order_id": "order_12345"
    }
  }
}
```

The `metadata.order_id` you attached when creating the checkout configuration flows straight through to the webhook handler. That's the hook you use to map the payment back to your own order record.

### 3. Verify in the sandbox dashboard

Open the sandbox dashboard at `https://sandbox.whop.com/dashboard/<your_company_id>/payments`. The test charge appears in this payments list with its status and amount; use your server logs to confirm the `metadata.order_id` you set maps back to the same order.

<img alt="Sandbox dashboard Payments page showing the payments list" />

If you see both the dashboard row and the `payment.succeeded` event on your server, the integration is live. Switch your SDK and webhook URL to production when ready.

## Next steps

<CardGroup>
  <Card title="Webhooks" icon="webhook" href="/developer/guides/webhooks">
    Handle payment events in real-time
  </Card>

  <Card title="Save payment methods" icon="credit-card" href="/developer/guides/save-payment-methods">
    Save and charge payment methods
  </Card>

  <Card title="iOS payments" icon="apple" href="/developer/guides/ios/overview">
    Accept payments in your iOS app with lower fees
  </Card>

  <Card title="Payment methods" icon="globe" href="/payments-and-billing/local-payment-methods">
    100+ payment methods across 195 countries
  </Card>
</CardGroup>


# Affiliates
Source: https://docs.whop.com/developer/guides/affiliates

Create affiliate records, assign per-plan or rev-share commission overrides, and track referral earnings.

Affiliates earn commissions for referred sales. The API flow has two parts: create an affiliate record, then add overrides that define the commission.

## How attribution works

1. You create an affiliate record for a user, then add overrides. Each override returns `product_direct_link` and `checkout_direct_link` fields. These are referral URLs the affiliate shares (they include `?a=<username>`).
2. A buyer clicks the link; Whop stores the affiliate cookie (30-day attribution window by default).
3. Buyer checks out within the window. Commission is calculated per the matching override: `standard` (per-plan, percentage or flat fee) or `rev_share` (percentage of revenue, product-specific or company-wide).
4. Commission is attributed to the affiliate and reflected in the override's `total_referral_earnings_usd` field.

<Note>
  **Refunds reverse commissions.** If a buyer refunds within the window, the affiliate's earning on that sale is clawed back automatically.
</Note>

<Note>
  **Affiliates need a Whop company to receive payouts.** Earnings accrue on the record; payouts go to their company balance via [transfers](/developer/platforms/collect-payments-for-connected-accounts#transfers). If they do not have a company yet, onboard them with [connected account enrollment](/developer/platforms/enroll-connected-accounts).
</Note>

## Create an affiliate

`user_identifier` resolves flexibly. Pass a username, email, user ID, or Discord ID. If an affiliate record already exists for the company + user pair, the existing record is returned (idempotent).

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

  const affiliate = await client.affiliates.create({
    company_id: "biz_xxxxxxxxxxxxx",
    user_identifier: "johndoe", // username, email, usr_xxx, or Discord ID
  });

  console.log(`Affiliate ${affiliate.id} created`);
  ```

  ```python Python theme={null}
  import os
  from whop_sdk import Whop

  client = Whop(api_key=os.environ["WHOP_API_KEY"])

  affiliate = client.affiliates.create(
      company_id="biz_xxxxxxxxxxxxx",
      user_identifier="johndoe",
  )

  print(f"Affiliate {affiliate.id} created")
  ```
</CodeGroup>

## Add commission overrides

An affiliate record does not set a commission by itself. Add **overrides** to decide what the affiliate gets paid.

| Override type   | What it does                                               | Required fields                                                         |
| --------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------- |
| **`standard`**  | Per-plan commission, percentage or flat fee                | `plan_id`, `commission_type`, `commission_value`, `applies_to_payments` |
| **`rev_share`** | Percentage revenue share, product-specific or company-wide | `commission_value` (always percentage); `product_id` optional           |

### Standard (per-plan)

<CodeGroup>
  ```typescript TypeScript theme={null}
  const override = await client.affiliates.createOverride(affiliate.id, {
    override_type: "standard",
    plan_id: "plan_xxxxxxxxxxxxx",
    commission_type: "percentage",      // "percentage" or "flat_fee"
    commission_value: 40,                // 40% (or $40 if flat_fee)
    applies_to_payments: "first_payment" // "first_payment" or "all_payments"
  });

  // Share these with the affiliate
  console.log(override.product_direct_link);
  console.log(override.checkout_direct_link);
  ```

  ```python Python theme={null}
  override = client.affiliates.create_override(
      affiliate.id,
      override_type="standard",
      plan_id="plan_xxxxxxxxxxxxx",
      commission_type="percentage",
      commission_value=40,
      applies_to_payments="first_payment",
  )

  print(override.product_direct_link)
  print(override.checkout_direct_link)
  ```
</CodeGroup>

`commission_value` rules:

* `"percentage"`: whole number 1–100 (`40` = 40%).
* `"flat_fee"`: dollar amount (`10` = \$10).

`applies_to_payments`:

* `"first_payment"`: affiliate earns only on the initial purchase.
* `"all_payments"`: affiliate earns on every recurring payment too.

### Rev-share (revenue percentage)

Rev-share overrides are always percentage-based. Don't pass `commission_type: "flat_fee"`.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Product-specific: affiliate earns 30% on sales of this product
  await client.affiliates.createOverride(affiliate.id, {
    override_type: "rev_share",
    product_id: "prod_xxxxxxxxxxxxx",
    commission_value: 30,
  });

  // Company-wide: affiliate earns 15% on every product
  await client.affiliates.createOverride(affiliate.id, {
    override_type: "rev_share",
    commission_value: 15,
  });
  ```

  ```python Python theme={null}
  client.affiliates.create_override(
      affiliate.id,
      override_type="rev_share",
      product_id="prod_xxxxxxxxxxxxx",
      commission_value=30,
  )

  client.affiliates.create_override(
      affiliate.id,
      override_type="rev_share",
      commission_value=15,
  )
  ```
</CodeGroup>

## Manage overrides

<CodeGroup>
  ```typescript TypeScript theme={null}
  // List all overrides for an affiliate
  const overrides = await client.affiliates.listOverrides("aff_xxxxxxxxxxxxx");

  // Filter by type
  const standardOnly = await client.affiliates.listOverrides("aff_xxxxxxxxxxxxx", {
    override_type: "standard",
  });

  // Retrieve one
  const o = await client.affiliates.retrieveOverride("aff_xxxxxxxxxxxxx", "aovr_xxxxxxxxxxxxx");

  // Update
  await client.affiliates.updateOverride("aff_xxxxxxxxxxxxx", "aovr_xxxxxxxxxxxxx", {
    commission_value: 50,
    applies_to_payments: "all_payments",
  });

  // Delete (for standard overrides, this also removes the affiliate from that plan)
  await client.affiliates.deleteOverride("aff_xxxxxxxxxxxxx", "aovr_xxxxxxxxxxxxx");
  ```

  ```python Python theme={null}
  overrides = client.affiliates.list_overrides("aff_xxxxxxxxxxxxx")

  standard_only = client.affiliates.list_overrides(
      "aff_xxxxxxxxxxxxx",
      override_type="standard",
  )

  o = client.affiliates.retrieve_override("aff_xxxxxxxxxxxxx", "aovr_xxxxxxxxxxxxx")

  client.affiliates.update_override(
      "aff_xxxxxxxxxxxxx",
      "aovr_xxxxxxxxxxxxx",
      commission_value=50,
      applies_to_payments="all_payments",
  )

  client.affiliates.delete_override("aff_xxxxxxxxxxxxx", "aovr_xxxxxxxxxxxxx")
  ```
</CodeGroup>

## Manage affiliates

<CodeGroup>
  ```typescript TypeScript theme={null}
  // List, optionally filtered by status
  for await (const page of client.affiliates.list({
    company_id: "biz_xxxxxxxxxxxxx",
    status: "active",
  })) {
    console.log(page);
  }

  const single = await client.affiliates.retrieve("aff_xxxxxxxxxxxxx");

  // Archive blocks the affiliate from earning further commissions
  await client.affiliates.archive("aff_xxxxxxxxxxxxx");
  await client.affiliates.unarchive("aff_xxxxxxxxxxxxx");
  ```

  ```python Python theme={null}
  for page in client.affiliates.list(
      company_id="biz_xxxxxxxxxxxxx",
      status="active",
  ):
      print(page)

  single = client.affiliates.retrieve("aff_xxxxxxxxxxxxx")

  client.affiliates.archive("aff_xxxxxxxxxxxxx")
  client.affiliates.unarchive("aff_xxxxxxxxxxxxx")
  ```
</CodeGroup>

## Company-level affiliate settings

Three company fields control how the affiliate program is presented to users. Update them via the Company resource.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.companies.update("biz_xxxxxxxxxxxxx", {
    affiliate_instructions: "Share your link on social. 30-day cookie window.",
    affiliate_application_required: true,
    featured_affiliate_product_id: "prod_xxxxxxxxxxxxx",
  });
  ```

  ```python Python theme={null}
  client.companies.update(
      "biz_xxxxxxxxxxxxx",
      affiliate_instructions="Share your link on social. 30-day cookie window.",
      affiliate_application_required=True,
      featured_affiliate_product_id="prod_xxxxxxxxxxxxx",
  )
  ```
</CodeGroup>

| Field                            | Description                                                         |
| -------------------------------- | ------------------------------------------------------------------- |
| `affiliate_instructions`         | Guidelines shown to affiliates promoting this company               |
| `affiliate_application_required` | Whether users must apply and be approved before becoming affiliates |
| `featured_affiliate_product_id`  | Which product to feature for affiliate promotion                    |

## Tracking earnings

Each override includes a `total_referral_earnings_usd` field that reflects cumulative earnings (in USD) for that specific override. Re-fetch the override (or list overrides on an affiliate) to get the current total.

<Note>
  There is no dedicated `affiliate.*` webhook in v1, and the public `payment` schema does not expose affiliate linkage. Poll `listOverrides` on your payout schedule and compare the latest `total_referral_earnings_usd` values with the last values you stored.
</Note>

## Override response fields

| Field                         | Description                                                                 |
| ----------------------------- | --------------------------------------------------------------------------- |
| `override_type`               | `"standard"` or `"rev_share"`                                               |
| `commission_type`             | `"percentage"` or `"flat_fee"`                                              |
| `commission_value`            | Percentage (1–100) or flat fee in dollars                                   |
| `applies_to_payments`         | `"first_payment"` or `"all_payments"` (standard only; `null` for rev-share) |
| `plan_id`                     | Plan ID (standard only)                                                     |
| `product_id`                  | Product ID (rev-share only; `null` if company-wide)                         |
| `applies_to_products`         | `"single_product"` or `"all_products"` (rev-share only)                     |
| `product_direct_link`         | Referral link to product page (standard only)                               |
| `checkout_direct_link`        | Referral link to checkout page (standard only)                              |
| `total_referral_earnings_usd` | Cumulative earnings for this override                                       |

## Next steps

<CardGroup>
  <Card title="Pay out affiliate earnings" href="/developer/platforms/collect-payments-for-connected-accounts#transfers">
    Transfer accrued commissions from your balance to affiliate companies.
  </Card>

  <Card title="Accept payments" href="/developer/guides/accept-payments">
    Checkout configurations attribute sales automatically when referral cookies are set.
  </Card>

  <Card title="Listen to webhooks" href="/developer/guides/webhooks">
    Use `payment.succeeded` for general sales telemetry; affiliate attribution still polls.
  </Card>

  <Card title="Affiliates API reference" href="/api-reference/affiliates/affiliate">
    Full resource. Endpoints, fields, and override schemas.
  </Card>
</CardGroup>


# AI and MCP
Source: https://docs.whop.com/developer/guides/ai_and_mcp

Build Whop apps with AI assistance using Model Context Protocol

Whop provides Model Context Protocol (MCP) servers to accelerate app development with AI assistance.

# Whop Docs MCP Server

Gives AI agents direct access to Whop documentation for accurate guidance while building apps.

### Quick install for Cursor

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=whop-docs\&config=eyJ1cmwiOiJodHRwczovL2RvY3Mud2hvcC5jb20vbWNwIn0%3D)

### Manual setup

<CodeGroup>
  ```json Cursor theme={null}
  // Add to: ~/.cursor/config/mcp.json
  {
    "mcpServers": {
      "whop-docs": {
        "url": "https://docs.whop.com/mcp"
      }
    }
  }
  ```

  ```json Claude Code theme={null}
  // Add to: ~/.claude/mcp.json
  {
  	"mcpServers": {
  		"whop-docs": {
  			"url": "https://docs.whop.com/mcp"
  		}
  	}
  }
  ```
</CodeGroup>

This allows your AI agent to search and read all Whop documentation, helping you implement features correctly.

# Whop API MCP Server

Allows AI agents to make direct API calls to Whop. Available via two transport methods:

* **SSE**: `mcp.whop.com/sse`
* **HTTP Streaming**: `mcp.whop.com/mcp`

### Authentication

When connecting, provide your API key in the authorization prompt:

* [**Company API Key**](/developer/api/getting-started#company-api-keys) - For accessing only your company's data
* [**App API Key**](/developer/api/getting-started#app-api-keys) - For accessing data across companies that have installed your app

### Claude.ai Guide

To connect Claude Web to this MCP server:

1. Open [Claude Web](https://claude.ai)
2. Go to Settings -> Connectors
3. Click "+ Add Custom Connector"
4. Add the MCP server URL: `https://mcp.whop.com/sse`

This enables your AI agent to list resources, create data, and explore your Whop setup interactively.


# App Views
Source: https://docs.whop.com/developer/guides/app-views

Configure how and where your app appears on Whop

App views determine where and how your app is displayed on Whop. You can configure one or more views depending on your app's functionality and target audience.

Each view serves a different purpose and appears in a different context on the platform.

## Experience View

The experience view is where members interact with your app's core features. Apps with this view appear directly in the Whop sidebar alongside native features like chat, forums, and courses.

When creators install your app, they can create one or more experiences powered by your app. Each experience maps to a single item in the sidebar and can render unique custom content.

Each instance of your experience view has a unique experience id which looks like `exp_xxxxxxxx`.

<Frame>
  <img alt="Experience View" />
</Frame>

### When to use Experience View

Experience view is ideal for consumer-focused apps that members interact with regularly:

* LIVE quizzes and polls that run directly within communities
* Custom course delivery systems with interactive content
* Gated content libraries with videos, files, or downloads
* Community games and interactive experiences
* Real-time collaboration tools for members

### Configure Experience View

<Steps>
  <Step title="Go to your app's hosting settings">
    1. Go to the [developer dashboard](https://whop.com/dashboard/developer)
    2. Create a new app or select an existing one
    3. Scroll down to the **Hosting** section

    <Frame>
      <img alt="App Settings" />
    </Frame>
  </Step>

  <Step title="Enter your path">
    Enter your path for the experience view. The recommended default path is `/experiences/[experienceId]`.

    <Frame>
      <img alt="Experience View Path" />
    </Frame>

    * `[experienceId]` is used to provide the accessed experience ID: `/experiences/[experienceId] -> /experiences/exp_***`
    * `[restPath]` is used for deep linking to specific sections of your app: `/experiences/[experienceId]/[restPath] -> /experiences/exp_***/posts/1`
  </Step>
</Steps>

### Preview Experience View

<Steps>
  <Step title="Install your app">
    Click the install button or copy the installation link and visit it in your browser. You will be prompted to install your app into your whop.

    <Frame>
      <img alt="Install App Button" />
    </Frame>

    If you've already installed your app, you can access it from your whop.

    <Frame>
      <img alt="Whop Sidebar Apps Section" />
    </Frame>
  </Step>

  <Step title="Set the environment">
    1. Open the dev tools by clicking the **cog** button
    2. Set the environment to **localhost**

    <video />
  </Step>
</Steps>

### Validate experience access

Check if a user has access to an experience using the `checkAccess` method. The experience ID is passed as a path parameter when your app loads.

```typescript theme={null}
import { headers } from "next/headers";
import { whopsdk } from "@/lib/whop-sdk";

export default async function ExperiencePage({
    params,
}: {
    params: Promise<{ experienceId: string }>;
}) {
    const { experienceId } = await params;
    const { userId } = await whopsdk.verifyUserToken(await headers());

    const access = await whopsdk.users.checkAccess(
        experienceId,
        { id: userId }
    );

    if (!access.has_access) {
        return <div>Access denied</div>;
    }

    // access.access_level can be:
    // "customer" - User has a valid membership
    // "admin" - User is a team member

    return <div>Welcome to the experience!</div>;
}
```

See [Authentication - Customer app](/developer/guides/authentication#customer-app-experience-view) for more information.

### Examples

* [Next.js](https://github.com/whopio/whop-nextjs-app-template/blob/main/app/experiences/%5BexperienceId%5D/page.tsx)
* [React Native](https://github.com/whopio/whop-sdk-ts/blob/main/packages/create-react-native/template/src/views/experience-view.tsx)

## Dashboard View

The dashboard view appears directly in the creator's business dashboard. This view is designed for apps that help businesses grow and manage their operations.

Apps with dashboard views are accessible from the dashboard sidebar under the apps section, making them easy to find when creators need to manage business operations.

<Frame>
  <img alt="Dashboard View" />
</Frame>

### When to use Dashboard View

Dashboard view is ideal for B2B apps that help creators run their business:

* Analytics dashboards showing revenue, member growth, and engagement metrics
* Customer upsell tools that send targeted offers to loyal members
* Member management interfaces for organizing and segmenting customers
* Automated marketing campaigns and email builders
* Custom admin panels for managing app-specific settings

### Configure Dashboard View

<Steps>
  <Step title="Go to your app's hosting settings">
    1. Go to the [developer dashboard](https://whop.com/dashboard/developer)
    2. Create a new app or select an existing one
    3. Scroll down to the **Hosting** section

    <Frame>
      <img alt="App Settings" />
    </Frame>
  </Step>

  <Step title="Enter your path">
    Enter your path for the dashboard view. The recommended default path is `/dashboard/[companyId]`.

    <Frame>
      <img alt="Dashboard View Path" />
    </Frame>

    * `[companyId]` is used to provide the accessed company ID: `/dashboard/[companyId] -> /dashboard/biz_***`
    * `[restPath]` is used for deep linking to specific sections of your app: `/dashboard/[companyId]/[restPath] -> /dashboard/biz_***/posts/1`
  </Step>
</Steps>

### Preview Dashboard View

<Steps>
  <Step title="Install your app">
    Click the preview button next to the field, this will take you to your app's dashboard view. You will be prompted to install your app if you haven't already.

    <Frame>
      <img alt="Preview App Button" />
    </Frame>

    If you've already installed your app, you can access it from your dashboard under the **apps** section.

    <Frame>
      <img alt="Dashboard Sidebar Apps Section" />
    </Frame>
  </Step>

  <Step title="Set the environment">
    1. Open the dev tools by clicking the **cog** button
    2. Set the environment to **localhost**

    <video />
  </Step>
</Steps>

### Validate company access

Dashboard apps should only be accessible to admins of the company. Check access using the `checkAccess` method with the company ID.

```typescript theme={null}
import { headers } from "next/headers";
import { whopsdk } from "@/lib/whop-sdk";

export default async function DashboardPage({
    params,
}: {
    params: Promise<{ companyId: string }>;
}) {
    const { companyId } = await params;
    const { userId } = await whopsdk.verifyUserToken(await headers());

    const access = await whopsdk.users.checkAccess(
        companyId,
        { id: userId }
    );

    if (access.access_level !== "admin") {
        return <div>Admin access required</div>;
    }

    return <div>Welcome to the dashboard!</div>;
}
```

See [Authentication - Dashboard app](/developer/guides/authentication#dashboard-app-dashboard-view) for more information.

### Examples

* [Next.js](https://github.com/whopio/whop-nextjs-app-template/blob/main/app/dashboard/%5BcompanyId%5D/page.tsx)
* [React Native](https://github.com/whopio/whop-sdk-ts/blob/main/packages/create-react-native/template/src/views/dashboard-view.tsx)

## Choosing the right views

You can configure multiple views for your app depending on its functionality:

* **Consumer apps**: Use Experience View to serve members with interactive features
* **Business apps**: Use Dashboard View to help creators manage operations
* **Hybrid apps**: Use both views to serve both members and creators

Configure your views in the Hosting section of your app dashboard to get started.


# Authentication
Source: https://docs.whop.com/developer/guides/authentication

Verify the current user and check their access level inside your Whop app.

Whop apps render inside an iframe on `whop.com`. To figure out *who* is making a request to your app, Whop passes a short-lived JWT in the `x-whop-user-token` header on every same-origin request. You verify this token with the SDK to get a user ID, then check what that user is allowed to see.

## Verify the iframe user token

Call `verifyUserToken` on each request. It reads the `x-whop-user-token` header, validates the JWT signature and expiry, and returns the user ID. Invalid tokens throw by default. Each SDK also has a non-throwing variant:

| Language   | Non-throwing variant                              |
| ---------- | ------------------------------------------------- |
| TypeScript | Pass `{ dontThrow: true }` as the second argument |
| Python     | Pass `dont_throw=True` as a keyword argument      |
| Ruby       | Use `verify_user_token` (without the `!`)         |

<CodeGroup>
  ```typescript JS/TS + NextJS theme={null}
  import { headers } from "next/headers";
  import { whopsdk } from "@/lib/whop-sdk";

  export default async function MyServerRenderedPage() {
  	const { userId } = await whopsdk.verifyUserToken(await headers());

      // ... the rest of your component / api route etc...
  }
  ```

  ```javascript JS/TS + ExpressJS theme={null}
  import express from "express";
  import { whopsdk } from "./lib/whop-sdk";

  const app = express();

  app.get("/my-route", async (req, res) => {
      const { userId } = await whopsdk.verifyUserToken(req.headers);

      // ... the rest of your route handler
  });
  ```

  ```python Python + FastAPI theme={null}
  from fastapi import FastAPI, Request
  from lib.whop_sdk import whopsdk

  app = FastAPI()

  @app.get("/my-route")
  async def my_route(request: Request):
      result = await whopsdk.verify_user_token(request.headers)
      user_id = result.user_id

      # ... the rest of your route handler
  ```

  ```ruby Ruby on Rails theme={null}
  class MyController < ApplicationController
    def my_action
      auth_result = whopsdk.verify_user_token!(request.headers)
      user_id = auth_result.user_id

      # ... the rest of your controller action
    end
  end
  ```
</CodeGroup>

The token is only attached to requests hitting the `window.location.origin` of your iframe. Examples:

* Relative page navigations: `<a href="/sub_page">...</a>`
* Fetches without a domain: `await fetch("/api/quizzes")`

All of these resolve to your `App.base_url` domain.

<Accordion title="My API is on a different domain">
  If your frontend runs on `example.com` but your API runs on `api.example.com`, reverse-proxy API requests through `example.com/api` so they carry the `x-whop-user-token` header.

  * **Cloudflare**: create an ["origin rule"](https://developers.cloudflare.com/rules/origin-rules/features/#dns-record) from `/api` on `example.com` to rewrite to `api.example.com/api`.
  * **Next.js**: add a [rewrite](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites) in `next.config.mjs`.
  * **nginx / Caddy**: use the rewrite primitive in your server config.

  <Note>
    This setup is required because of strict browser cross-origin cookie policies.
  </Note>
</Accordion>

## Local setup

Whop ships a local reverse proxy that matches the production iframe + cookie behavior, so the code you write works identically on `localhost` and in production. See the [dev proxy guide](/developer/guides/dev-proxy) for setup.

## Check access

Now that you know who's making the request, check what they're allowed to see. Use the [`checkAccess`](/api-reference/users/check-access) method to verify access to an Experience, Company, or Product.

<CodeGroup>
  ```typescript JS/TS theme={null}
  import { whopsdk } from "@/lib/whop-sdk";

  const response = await whopsdk.users.checkAccess(
      "resource_id",
      { id: "user_xxxxxxxxxxxxx" }
  );

  // Response:
  // {
  //   "has_access": true,
  //   "access_level": "customer"
  // }
  ```

  ```python Python theme={null}
  response = whopsdk.users.check_access(
      resource_id="resource_id",
      id="user_xxxxxxxxxxxxx",
  )

  # Response:
  # {
  #   "has_access": True,
  #   "access_level": "customer"
  # }
  ```

  ```ruby Ruby theme={null}
  response = whopsdk.users.check_access(
      "resource_id",
      id: "user_xxxxxxxxxxxxx"
  )

  # Response:
  # {
  #   "has_access": true,
  #   "access_level": "customer"
  # }
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.whop.com/api/v1/users/{id}/access/{resource_id} \
    --header 'Authorization: Bearer <token>'
  ```
</CodeGroup>

### Resource IDs and access levels

| `resource_id` prefix | Checks access to |
| -------------------- | ---------------- |
| `biz_xxxx`           | Company          |
| `prod_xxxx`          | Product          |
| `exp_xxxx`           | Experience       |

The response's `access_level` is one of:

| Level       | Meaning                                                                                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `customer`  | User has a valid membership. For an experience, they have a membership to any product connected to it. For a product, to that specific product. For a company, to any product on it. |
| `admin`     | User is a team member of the company (any role, including moderator).                                                                                                                |
| `no_access` | User has no access (`has_access` is `false`).                                                                                                                                        |

### Customer app (Experience View)

Customer apps should gate on the `experienceId` passed in path params. Return `no_access` or redirect if the viewer doesn't have a valid membership.

```typescript theme={null}
import { headers } from "next/headers";
import { whopsdk } from "@/lib/whop-sdk";

export default async function ExperiencePage({
    params,
}: {
    params: Promise<{ experienceId: string }>;
}) {
    const { experienceId } = await params;
    const { userId } = await whopsdk.verifyUserToken(await headers());

    const access = await whopsdk.users.checkAccess(
        experienceId,
        { id: userId }
    );

    if (!access.has_access) {
        return <div>Access denied</div>;
    }

    return <div>Welcome to the experience!</div>;
}
```

The same pattern works in an API route. Swap `headers()` for `request.headers` and return a `403 Response` instead of JSX.

### Dashboard app (Dashboard View)

Dashboard apps should gate on `access_level === "admin"` so only company team members can load the view.

```typescript theme={null}
import { headers } from "next/headers";
import { whopsdk } from "@/lib/whop-sdk";

export default async function DashboardPage({
    params,
}: {
    params: Promise<{ companyId: string }>;
}) {
    const { companyId } = await params;
    const { userId } = await whopsdk.verifyUserToken(await headers());

    const access = await whopsdk.users.checkAccess(
        companyId,
        { id: userId }
    );

    if (access.access_level !== "admin") {
        return <div>Admin access required</div>;
    }

    return <div>Welcome to the dashboard!</div>;
}
```

Same pattern in an API route. Swap `headers()` for `request.headers` and return a `403 Response` instead of JSX.

## Next steps

<CardGroup>
  <Card title="Run a local dev proxy" href="/developer/guides/dev-proxy">
    Match the production iframe + cookie setup on localhost.
  </Card>

  <Card title="Request permissions" href="/developer/guides/permissions">
    Add the scopes your app needs before publishing.
  </Card>

  <Card title="Listen to webhooks" href="/developer/guides/webhooks">
    Receive payment, membership, and entry events on your server.
  </Card>

  <Card title="Build an app view" href="/developer/guides/app-views">
    Set up dashboard views, experiences, and discover listings.
  </Card>
</CardGroup>


# Chat
Source: https://docs.whop.com/developer/guides/chat

Send messages, manage channels, and react to events in any Whop community.

Use the Chat API to send messages, manage channels, open support conversations, and read reactions. Channels are identified by `experience_id` or `channel_id`.

<Tip>
  This page covers the **server-side Chat API**, for calling Whop from your backend to post, read, or moderate messages. If you want to render a live Whop chat UI inside your own frontend, see the [embedded chat quickstart](/developer/guides/chat/quickstart) instead.
</Tip>

## Initialize the SDK

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const client = new Whop({
    appID: "app_xxxxxxxxxxxxx",
    apiKey: process.env.WHOP_API_KEY,
  });
  ```

  ```python Python theme={null}
  import os
  from whop_sdk import Whop

  client = Whop(
      app_id="app_xxxxxxxxxxxxx",
      api_key=os.environ["WHOP_API_KEY"],
  )
  ```
</CodeGroup>

## Send a message

Messages support Markdown and optional attachments uploaded via the [Files API](/developer/guides/upload-files).

<CodeGroup>
  ```typescript TypeScript theme={null}
  const message = await client.messages.create({
    channel_id: "chat_feed_xxxxxxxxxxxxx", // or an experience_id
    content: "Hello! **Markdown** is supported.",
    attachments: [
      { id: "file_xxxxxxxxxxxxx" }, // upload via the Files API first
    ],
  });
  ```

  ```python Python theme={null}
  message = client.messages.create(
      channel_id="chat_feed_xxxxxxxxxxxxx",
      content="Hello! **Markdown** is supported.",
      attachments=[
          {"id": "file_xxxxxxxxxxxxx"},
      ],
  )
  ```
</CodeGroup>

## Read messages

List operations auto-paginate. Iterate the response and the SDK fetches additional pages for you.

<CodeGroup>
  ```typescript TypeScript theme={null}
  for await (const page of client.messages.list({
    channel_id: "chat_feed_xxxxxxxxxxxxx",
    direction: "desc",
    first: 20,
  })) {
    console.log(page);
  }

  const single = await client.messages.retrieve("msg_xxxxxxxxxxxxx");
  ```

  ```python Python theme={null}
  for page in client.messages.list(
      channel_id="chat_feed_xxxxxxxxxxxxx",
      direction="desc",
      first=20,
  ):
      print(page)

  single = client.messages.retrieve("msg_xxxxxxxxxxxxx")
  ```
</CodeGroup>

## Manage channels

Update moderation settings (banned words, cooldowns, who can post or react) or list every channel on a company.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const channel = await client.chatChannels.update("chat_feed_xxxxxxxxxxxxx", {
    ban_media: false,
    ban_urls: false,
    banned_words: ["spam", "scam"],
    user_posts_cooldown_seconds: 10,
    who_can_post: "members_only",
    who_can_react: "everyone",
  });

  for await (const page of client.chatChannels.list({
    company_id: "biz_xxxxxxxxxxxxx",
    first: 10,
  })) {
    console.log(page);
  }
  ```

  ```python Python theme={null}
  channel = client.chat_channels.update(
      "chat_feed_xxxxxxxxxxxxx",
      ban_media=False,
      ban_urls=False,
      banned_words=["spam", "scam"],
      user_posts_cooldown_seconds=10,
      who_can_post="members_only",
      who_can_react="everyone",
  )

  for page in client.chat_channels.list(
      company_id="biz_xxxxxxxxxxxxx",
      first=10,
  ):
      print(page)
  ```
</CodeGroup>

`who_can_post` and `who_can_react` accept `everyone`, `members_only`, or `admins_only`.

## React to a message

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.reactions.create({
    resource_id: "msg_xxxxxxxxxxxxx",
    emoji: "😀", // Unicode or ':heart:' shortcode
  });
  ```

  ```python Python theme={null}
  client.reactions.create(
      resource_id="msg_xxxxxxxxxxxxx",
      emoji="😀",
  )
  ```
</CodeGroup>

## Support channels

Support channels are 1:1 threads between a user and a company, useful for help desks or concierge flows. `create` returns the existing channel if one already exists for the user.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const support = await client.supportChannels.create({
    company_id: "biz_xxxxxxxxxxxxx",
    user_id: "user_xxxxxxxxxxxxx",
  });

  for await (const page of client.supportChannels.list({
    company_id: "biz_xxxxxxxxxxxxx",
    open: true,
    order: "last_post_sent_at",
    direction: "desc",
    first: 10,
  })) {
    console.log(page);
  }
  ```

  ```python Python theme={null}
  support = client.support_channels.create(
      company_id="biz_xxxxxxxxxxxxx",
      user_id="user_xxxxxxxxxxxxx",
  )

  for page in client.support_channels.list(
      company_id="biz_xxxxxxxxxxxxx",
      open=True,
      order="last_post_sent_at",
      direction="desc",
      first=10,
  ):
      print(page)
  ```
</CodeGroup>

## Required permissions

Add these from the [Permissions guide](/developer/guides/permissions) before publishing your app.

| Permission            | Needed for                            |
| --------------------- | ------------------------------------- |
| `chat:read`           | Reading messages, channels, reactions |
| `chat:message:create` | Posting messages                      |
| `chat:moderate`       | Updating channel settings             |
| `support_chat:create` | Opening support channels              |
| `support_chat:read`   | Reading support channels              |

<Accordion title="Message object shape">
  ```typescript theme={null}
  {
    id: string;
    content: string | null;
    created_at: string;
    is_edited: boolean;
    is_pinned: boolean;
    message_type: "text" | "image" | "video" | "poll";
    poll: { options: Array<{ id: string; text: string }> | null } | null;
    poll_votes: Array<{ count: number; option_id: string | null }>;
    reaction_counts: Array<{ count: number; emoji: string | null }>;
    replying_to_message_id: string | null;
    updated_at: string;
    user: { id: string; name: string | null; username: string };
  }
  ```

  Full schema: see the [Messages API reference](/api-reference/messages/message).
</Accordion>

## Next steps

<CardGroup>
  <Card title="Listen to events with webhooks" href="/developer/guides/webhooks">
    Receive chat events on your server instead of polling.
  </Card>

  <Card title="Send notifications" href="/developer/guides/notifications">
    Push notifications to users who aren't live in chat.
  </Card>

  <Card title="Upload files" href="/developer/guides/upload-files">
    Attach images and videos to messages.
  </Card>

  <Card title="Embed chat in your app" href="/developer/guides/chat/quickstart">
    Drop-in Whop chat UI for your frontend (separate product).
  </Card>
</CardGroup>


# Authentication
Source: https://docs.whop.com/developer/guides/chat/authentication

Authenticate users for embedded chat with company-scoped tokens or OAuth

Before using the chat SDK, you need to authenticate users. Pick one of two approaches:

| Approach                                                      | Best for                                                                                            |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **[Company-scoped user tokens](#company-scoped-user-tokens)** | Apps that already have their own users. Your server mints Whop tokens for them — no sign-in needed. |
| **[OAuth](/developer/guides/chat/oauth)**                     | Apps that want users to sign in to Whop themselves via a sign-in page or webview.                   |

## Company-scoped user tokens

Use this approach if **your app already has its own users** (via your own auth / session system). You keep your existing login flow and mint a Whop token for whichever user is currently signed in — no extra sign-in step.

Your server exchanges your Whop API key for a short-lived user token on demand and returns it to the client. You decide which user the token is for.

### 1. Gather your credentials

You'll need three things:

1. **API key** — create one at the [Whop Developer Dashboard](https://whop.com/dashboard/developer). Treat it like a password and keep it on your server only.
2. **Company ID** — find it in your dashboard URL: `whop.com/dashboard/biz_XXXXXXXXX/`.
3. **User ID** — the user you want to authenticate. In production, derive this from your own auth / session system.

<Note>
  For embedded chat, both `company_id` and `user_id` are required together when minting a token.
</Note>

### 2. Create a token endpoint on your server

Add an endpoint that calls `POST https://api.whop.com/api/v1/access_tokens` with your API key and returns the resulting token to the client.

<Tabs>
  <Tab title="Next.js">
    ```typescript app/api/chat/token/route.ts theme={null}
    import { NextResponse } from "next/server";
    import Whop from "@whop/sdk";

    const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

    export async function POST() {
      // Derive these from your own auth / session in production.
      const user_id = "user_XXXXXXXXXXXX";
      const company_id = "biz_XXXXXXXXXXXXX";

      const { token } = await client.accessTokens.create({
        company_id,
        user_id,
        scoped_actions: [
          "chat:message:create",
          "chat:read",
          "dms:read",
          "dms:message:manage",
          "dms:channel:manage",
          "support_chat:read",
          "support_chat:message:create",
        ],
      });

      return NextResponse.json({ token });
    }
    ```
  </Tab>

  <Tab title="Express">
    ```typescript server.ts theme={null}
    import express from "express";
    import Whop from "@whop/sdk";

    const app = express();
    app.use(express.json());

    const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

    app.post("/api/chat/token", async (_req, res) => {
      // Derive these from your own auth / session in production.
      const user_id = "user_XXXXXXXXXXXX";
      const company_id = "biz_XXXXXXXXXXXXX";

      const { token } = await client.accessTokens.create({
        company_id,
        user_id,
        scoped_actions: [
          "chat:message:create",
          "chat:read",
          "dms:read",
          "dms:message:manage",
          "dms:channel:manage",
          "support_chat:read",
          "support_chat:message:create",
        ],
      });

      res.json({ token });
    });

    app.listen(3000);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.whop.com/api/v1/access_tokens \
      -H "Authorization: Bearer $WHOP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "company_id": "biz_XXXXXXXXXXXXX",
        "user_id": "user_XXXXXXXXXXXX",
        "scoped_actions": [
          "chat:message:create",
          "chat:read",
          "dms:read",
          "dms:message:manage",
          "dms:channel:manage",
          "support_chat:read",
          "support_chat:message:create"
        ]
      }'
    ```
  </Tab>
</Tabs>

### 3. Fetch the token from your app

Provide the SDK with a token callback that fetches from your endpoint. The chat elements call this whenever they need to authenticate, and again automatically when the token expires.

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    async function getToken() {
      const response = await fetch("/api/chat/token", { method: "POST" });
      const data = await response.json();
      return data.token;
    }
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    async function getToken() {
      const response = await fetch("/api/chat/token", { method: "POST" });
      const data = await response.json();
      return data.token;
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import WhopElements

    class WhopAPITokenProvider: WhopTokenProvider {
        private let serverURL = URL(string: "https://your-server.com")!

        func getToken() async -> WhopTokenResponse {
            do {
                var req = URLRequest(url: serverURL.appendingPathComponent("api/chat/token"))
                req.httpMethod = "POST"

                let (data, _) = try await URLSession.shared.data(for: req)
                let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
                return WhopTokenResponse(accessToken: json["token"] as? String ?? "")
            } catch {
                return WhopTokenResponse(accessToken: "")
            }
        }
    }
    ```

    Pass the token provider to the SDK on app launch:

    ```swift theme={null}
    .task {
        await WhopSDK.configure(tokenProvider: WhopAPITokenProvider())
    }
    ```
  </Tab>
</Tabs>

### Required scopes

Request these scopes when creating the token:

| Scope                                                  | Purpose         |
| ------------------------------------------------------ | --------------- |
| `chat:message:create`, `chat:read`                     | Channels        |
| `dms:read`, `dms:message:manage`, `dms:channel:manage` | Direct messages |
| `support_chat:read`, `support_chat:message:create`     | Support chats   |

<Note>
  If your app owns the user accounts and mints company-scoped chat tokens, sync those users before passing their `user_id` here. User syncing is not part of OAuth.
</Note>

<Card title="Sync your users" icon="user-plus" href="/developer/guides/chat/sync-users">
  Create or map Whop users before minting company-scoped chat tokens.
</Card>

## OAuth

OAuth lives on its own page so this guide can stay focused on company-scoped user tokens.

Use OAuth when your app wants users to sign in to Whop themselves through a sign-in page or iOS webview. This is the right choice when your app needs access to a user-owned Whop account, or when you do not want your backend to mint Whop user tokens.

<Card title="OAuth" icon="user-lock" href="/developer/guides/chat/oauth">
  Set up OAuth scopes, redirect URIs, web token endpoints, and SDK-managed OAuth on iOS.
</Card>


# Channels
Source: https://docs.whop.com/developer/guides/chat/channels

Use channels for shared chat rooms connected to products and memberships

Channels are shared chat rooms for many users. Use them for communities, cohorts, event rooms, member-only announcements, or any conversation where access should follow a product membership.

A channel is powered by a Chat experience. Customers can access the channel when they have access to a product that contains that experience.

## When to use channels

Use a channel when you want a room that belongs to a product or community, not a private conversation between a few users.

Examples:

* A paid community's main chat room
* A course cohort discussion room
* An announcements channel where only admins can post
* A VIP room attached to a higher-tier product
* A live event chat for members who bought access

### What makes channels different

Channels are the chat type for product-backed rooms and communities.

* They are powered by Chat experiences and can be attached to products.
* Access follows product membership, so everyone with access to the product can participate.
* They are designed for large rooms and communities, without the 50-member cap that applies to DMs.
* They include moderation controls for media, links, reactions, blocked words, posting permissions, and cooldowns.
* They can be read-only or announcement-style by limiting posting to admins.

### Constraints

* Users need access to the product that contains the Chat experience before they can participate.
* Channels do not appear in the DMs list. Render them directly with the [Chat element](/developer/guides/chat/chat-element).
* Channels are not for private user-to-user or small group conversations. Use [direct messages](/developer/guides/chat/direct-messages) for that.
* Channels do not include a support inbox or open/resolved workflow. Use [support chats](/developer/guides/chat/support-chats) for customer support.

## Access model

Channels are usually membership-gated:

1. Create a Chat experience.
2. Attach the experience to a product.
3. Give users access to the product through checkout or a free membership.
4. Render the channel with the `ChatElement` using the channel ID.

<Note>
  Channel IDs start with `chat_feed_`. You can also retrieve a channel by the Chat experience ID, which starts with `exp_`.
</Note>

## Set up a channel

<Steps>
  <Step title="Create or choose a product">
    Create the product that should grant access to the channel. Users get access to channel experiences through products and memberships.
  </Step>

  <Step title="Create a Chat experience">
    Create an experience for the Chat app. In the dashboard, this is the Chat app you add to a product. Through the API, use [Create Experience](/api-reference/experiences/create-experience).
  </Step>

  <Step title="Attach the experience to the product">
    Attach the experience with [Attach Experience](/api-reference/experiences/attach-experience). This makes the channel available to customers with access to that product.
  </Step>

  <Step title="Grant users access">
    Let users buy the product through checkout, or grant access with [Create Membership](/api-reference/memberships/create-membership) if you are giving access through a free plan.
  </Step>

  <Step title="Render the channel">
    Pass the channel ID to the [Chat element](/developer/guides/chat/chat-element). If you only have the experience ID, retrieve the channel with [Retrieve Chat Channel](/api-reference/chat-channels/retrieve-chat-channel).
  </Step>
</Steps>

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    <ChatElement
      options={{ channelId: "chat_feed_XXXXXXXXXXXXXX" }}
      style={{ height: "100dvh", width: "100%" }}
    />
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    const chatElement = session.createElement("chat-element", {
      channelId: "chat_feed_XXXXXXXXXXXXXX",
    });

    chatElement.mount("#chat-container");
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    WhopChatView(
        channelId: "chat_feed_XXXXXXXXXXXXXX",
        style: .imessage
    )
    ```
  </Tab>
</Tabs>

## Manage channels

Channels support moderation tools for controlling who can participate and what members can post. For example, you can make an announcements channel where only admins can send messages, limit media or links, block words, or slow down noisy conversations with cooldowns.

Use [Update Chat Channel](/api-reference/chat-channels/update-chat-channel) for the full list of moderation options.

## Next steps

<CardGroup>
  <Card title="Chat element" icon="message" href="/developer/guides/chat/chat-element">
    Render a channel, DM, or support chat in your app.
  </Card>

  <Card title="Authentication" icon="key" href="/developer/guides/chat/authentication">
    Mint tokens with the scopes needed to read and send channel messages.
  </Card>
</CardGroup>


# Chat element
Source: https://docs.whop.com/developer/guides/chat/chat-element

Display a chat in your app

The chat element renders a real-time chat UI connected to a specific channel.

### Basic usage

Pass a `channelId` to connect to a specific channel, DM, or support chat.

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    "use client";

    import { useMemo } from "react";
    import {
    	ChatElement,
    	ChatSession,
    	Elements,
    } from "@whop/embedded-components-react-js";
    import { loadWhopElements } from "@whop/embedded-components-vanilla-js";
    import type { ChatElementOptions } from "@whop/embedded-components-vanilla-js/types";

    const elements = loadWhopElements();

    async function getToken() {
    	const response = await fetch("/api/token");
    	const data = await response.json();
    	return data.token;
    }

    export function ChatPage() {
    	const chatOptions: ChatElementOptions = useMemo(() => {
    		return {
    			channelId: "chat_feed_XXXXXXXXXXXXXX",
    		};
    	}, []);

    	return (
    		<Elements elements={elements}>
    			<ChatSession token={getToken}>
    				<ChatElement
    					options={chatOptions}
    					style={{ height: "100dvh", width: "100%" }}
    				/>
    			</ChatSession>
    		</Elements>
    	);
    }
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    import { loadWhopElements } from "@whop/embedded-components-vanilla-js";

    async function getToken() {
    	const response = await fetch("/api/token");
    	const data = await response.json();
    	return data.token;
    }

    const whopElements = await loadWhopElements();

    const session = whopElements.createChatSession({
    	token: getToken,
    });

    const chatElement = session.createElement("chat-element", {
    	channelId: "chat_feed_XXXXXXXXXXXXXX",
    });

    chatElement.mount("#chat-container");
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import SwiftUI
    import WhopElements

    struct ChatView: View {
        var body: some View {
            WhopChatView(
                channelId: "chat_feed_XXXXXXXXXXXXXX",
                style: .imessage
            )
        }
    }
    ```
  </Tab>
</Tabs>

### Deeplinking to messages

To scroll to and highlight a specific message, pass `deeplinkToPostId`. The view will automatically navigate to that message.

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    const chatOptions: ChatElementOptions = useMemo(() => {
    	return {
    		channelId: "chat_feed_XXXXXXXXXXXXXX",
    		deeplinkToPostId: "post_XXXXXXXXXXXXXX",
    	};
    }, []);

    <ChatElement options={chatOptions} />;
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    const chatElement = session.createElement("chat-element", {
    	channelId: "chat_feed_XXXXXXXXXXXXXX",
    	deeplinkToPostId: "post_XXXXXXXXXXXXXX",
    });

    chatElement.mount("#chat-container");
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    struct ChatView: View {
        @State private var targetPostId: String? = nil

        var body: some View {
            WhopChatView(
                channelId: "chat_feed_XXXXXXXXXXXXXX",
                deeplinkToPostId: targetPostId,
                style: .imessage
            )
        }
    }
    ```
  </Tab>
</Tabs>

### Event handling

Listen to user interactions like profile clicks, link clicks, and sent messages using the event callback for your platform.

<Tabs>
  <Tab title="React">
    | Event             | Detail                                               | Description                                           |
    | ----------------- | ---------------------------------------------------- | ----------------------------------------------------- |
    | `profileClick`    | `{ id: string }`                                     | Emitted when the user clicks on a profile             |
    | `linkClick`       | `{ url: string }`                                    | Emitted when the user clicks on a link                |
    | `messageSent`     | `{ id: string, content: string, channelId: string }` | Emitted when the user sends a message                 |
    | `experienceClick` | `{ id: string }`                                     | Emitted when the user clicks on an experience mention |

    ```tsx theme={null}
    import { useCallback, useMemo } from "react";
    import type {
    	ChatElementEvent,
    	ChatElementOptions,
    } from "@whop/embedded-components-vanilla-js/types";

    const handleChatEvent = useCallback((event: ChatElementEvent) => {
    	switch (event.type) {
    		case "profileClick":
    			console.log("Profile clicked:", event.detail.id);
    			break;

    		case "linkClick":
    			console.log("Link clicked:", event.detail.url);
    			break;

    		case "messageSent":
    			console.log("Message sent:", event.detail.id, event.detail.content, event.detail.channelId);
    			break;

    		case "experienceClick":
    			console.log("Experience clicked:", event.detail.id);
    			break;
    	}
    }, []);

    const chatOptions: ChatElementOptions = useMemo(() => {
    	return {
    		channelId: "chat_feed_XXXXXXXXXXXXXX",
    		onEvent: handleChatEvent,
    	};
    }, [handleChatEvent]);

    <ChatElement options={chatOptions} />;
    ```
  </Tab>

  <Tab title="Vanilla JS">
    | Event             | Detail                                               | Description                                           |
    | ----------------- | ---------------------------------------------------- | ----------------------------------------------------- |
    | `profileClick`    | `{ id: string }`                                     | Emitted when the user clicks on a profile             |
    | `linkClick`       | `{ url: string }`                                    | Emitted when the user clicks on a link                |
    | `messageSent`     | `{ id: string, content: string, channelId: string }` | Emitted when the user sends a message                 |
    | `experienceClick` | `{ id: string }`                                     | Emitted when the user clicks on an experience mention |

    ```typescript theme={null}
    const chatElement = session.createElement("chat-element", {
    	channelId: "chat_feed_XXXXXXXXXXXXXX",
    });

    chatElement.on("profileClick", (ev) => {
    	console.log("Profile clicked:", ev.detail.id);
    });

    chatElement.on("linkClick", (ev) => {
    	console.log("Link clicked:", ev.detail.url);
    });

    chatElement.on("messageSent", (ev) => {
    	console.log("Message sent:", ev.detail.id, ev.detail.content, ev.detail.channelId);
    });

    chatElement.on("experienceClick", (ev) => {
    	console.log("Experience clicked:", ev.detail.id);
    });

    chatElement.mount("#chat-container");
    ```
  </Tab>

  <Tab title="Swift">
    | Event          | Detail                               | Description                             |
    | -------------- | ------------------------------------ | --------------------------------------- |
    | `.profileTap`  | `username: String`                   | Emitted when the user taps on a profile |
    | `.urlTap`      | `url: String`                        | Emitted when the user taps on a link    |
    | `.messageSent` | `content: String, messageId: String` | Emitted when the user sends a message   |

    ```swift theme={null}
    WhopChatView(
        channelId: "chat_feed_XXXXXXXXXXXXXX",
        style: .imessage,
        onEvent: { event in
            switch event {
            case let .profileTap(username):
                print("Profile tapped: \(username)")
            case let .urlTap(url):
                print("URL tapped: \(url)")
            case let .messageSent(content, messageId):
                print("Message sent: \(messageId) - \(content)")
            }
        }
    )
    ```
  </Tab>
</Tabs>


# Direct messages
Source: https://docs.whop.com/developer/guides/chat/direct-messages

Use DMs for private and group conversations between users

Direct messages are private conversations between two or more users. Use them when your app already has users and you want private messaging inside your product.

For embedded chat, DMs belong to your company context by default. That means users only see conversations created for your app, not unrelated Whop messages.

## When to use direct messages

Use direct messages when the conversation should be limited to specific members.

Examples:

* Buyer-to-seller messaging inside your app
* A private coaching thread between a coach and client
* A small group conversation for a project, cohort, or team
* A marketplace conversation between two matched users
* User-to-user messaging inside your app

### What makes DMs different

DMs are the chat type for private conversations between specific users.

* They can be one-on-one or group conversations with up to 50 members.
* Only the users added as members can see and participate in the conversation.
* They appear in the [DMs list element](/developer/guides/chat/dms-list-element), so users can browse and open their recent conversations.
* They can be scoped to your company, giving your embedded app its own inbox separate from unrelated Whop messages.
* They support custom conversation names and member management.

### Constraints

* DMs do not grant access based on product membership. Add or remove members directly when access changes.
* DMs do not have admin-only, read-only, or room-level moderation controls. Use [channels](/developer/guides/chat/channels) for moderated rooms.
* DMs do not include a support inbox or open/resolved workflow. Use [support chats](/developer/guides/chat/support-chats) for customer support.
* DMs are not designed for large communities, announcements, or member-wide rooms. Use [channels](/developer/guides/chat/channels) for that.

## Access model

Each DM has members. Those members are the only users who can see and participate in the conversation.

When you create DMs for embedded chat, keep them tied to your company. This gives your app its own inbox and keeps conversations separate from the rest of Whop.

<Note>
  DM channel IDs start with `feed_`.
</Note>

## Set up a direct message

<Steps>
  <Step title="Sync or create users">
    Make sure every participant has a Whop user ID. If your app has its own users, map them to Whop users first. See [Sync your users](/developer/guides/chat/sync-users).
  </Step>

  <Step title="Create the DM channel">
    Use [Create DM Channel](/api-reference/dm-channels/create-dm-channel) to create the conversation with its initial members.
  </Step>

  <Step title="Add more members when needed">
    Use [Create DM Member](/api-reference/dm-members/create-dm-member) to add a user to an existing DM. Use [Delete DM Member](/api-reference/dm-members/delete-dm-member) to remove one.
  </Step>

  <Step title="Render the conversation or list">
    Use the [Chat element](/developer/guides/chat/chat-element) for a single DM, or the [DMs list element](/developer/guides/chat/dms-list-element) to let users pick from their conversations.
  </Step>
</Steps>

Then render the DM with the returned channel ID:

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    <ChatElement
      options={{ channelId: "feed_XXXXXXXXXXXXXX" }}
      style={{ height: "100dvh", width: "100%" }}
    />
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    const chatElement = session.createElement("chat-element", {
      channelId: "feed_XXXXXXXXXXXXXX",
    });

    chatElement.mount("#chat-container");
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    WhopChatView(
        channelId: "feed_XXXXXXXXXXXXXX",
        style: .imessage
    )
    ```
  </Tab>
</Tabs>

## Manage direct messages

Use [List DM Channels](/api-reference/dm-channels/list-dm-channels), [Update DM Channel](/api-reference/dm-channels/update-dm-channel), and [Delete DM Channel](/api-reference/dm-channels/delete-dm-channel) to manage conversations.

Use [List DM Members](/api-reference/dm-members/list-dm-members), [Create DM Member](/api-reference/dm-members/create-dm-member), and [Delete DM Member](/api-reference/dm-members/delete-dm-member) to manage participants.

<Tip>
  If you use the DMs list element, keep it tied to your company so users only see conversations for your embedded chat experience.
</Tip>

## Next steps

<CardGroup>
  <Card title="DMs list element" icon="inbox" href="/developer/guides/chat/dms-list-element">
    Show DM conversations and handle channel selection.
  </Card>

  <Card title="Sync your users" icon="user-plus" href="/developer/guides/chat/sync-users">
    Create or map Whop users before creating DM channels.
  </Card>
</CardGroup>


# DMs list element
Source: https://docs.whop.com/developer/guides/chat/dms-list-element

Display a list of direct message conversations

The DMs list element renders a navigable list of the user's direct message conversations.

### Basic usage

Mount the DMs list and listen for channel selection events to navigate users into a conversation.

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    "use client";

    import { useCallback, useMemo, useState } from "react";
    import {
    	ChatSession,
    	DmsListElement,
    	Elements,
    } from "@whop/embedded-components-react-js";
    import { loadWhopElements } from "@whop/embedded-components-vanilla-js";
    import type {
    	DmsListElementEvent,
    	DmsListElementOptions,
    } from "@whop/embedded-components-vanilla-js/types";

    const elements = loadWhopElements();

    async function getToken() {
    	const response = await fetch("/api/token");
    	const data = await response.json();
    	return data.token;
    }

    export function MessagesPage() {
    	const [channelId, setChannelId] = useState<string>();

    	const handleDmsEvent = useCallback((event: DmsListElementEvent) => {
    		switch (event.type) {
    			case "channelSelected":
    				setChannelId(event.detail.id);
    				break;
    		}
    	}, []);

    	const dmsOptions: DmsListElementOptions = useMemo(() => {
    		return {
    			selectedChannel: channelId,
    			onEvent: handleDmsEvent,
    		};
    	}, [channelId, handleDmsEvent]);

    	return (
    		<Elements elements={elements}>
    			<ChatSession token={getToken}>
    				<DmsListElement options={dmsOptions} />
    			</ChatSession>
    		</Elements>
    	);
    }
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    import { loadWhopElements } from "@whop/embedded-components-vanilla-js";

    async function getToken() {
    	const response = await fetch("/api/token");
    	const data = await response.json();
    	return data.token;
    }

    const whopElements = await loadWhopElements();

    const session = whopElements.createChatSession({
    	token: getToken,
    });

    const dmsListElement = session.createElement("dms-list-element", {});

    dmsListElement.on("channelSelected", (ev) => {
    	console.log("Channel selected:", ev.detail.id);
    });

    dmsListElement.mount("#dms-list-container");
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    struct MessagesView: View {
        @State private var selectedChannel: DMChannel?

        var body: some View {
            WhopDMsListView(
                onEvent: { event in
                    switch event {
                    case let .channelSelected(channel):
                        selectedChannel = channel
                    }
                }
            )
            .navigationDestination(item: $selectedChannel) { channel in
                WhopChatView(
                    channelId: channel.id,
                    style: .imessage
                )
                .navigationBarTitleDisplayMode(.inline)
                .navigationTitle(channel.name)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Company scoping

Filter the DMs list to only show conversations belonging to a specific company by passing a `companyId`. To programmatically create DMs, use the [Create DM Channel](/api-reference/dm-channels/create-dm-channel) endpoint — make sure to pass the same `companyId` so the DM appears in the scoped list.

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    const dmsOptions: DmsListElementOptions = useMemo(() => {
    	return {
    		companyId: "biz_xxxx",
    		selectedChannel: channelId,
    		onEvent: handleDmsEvent,
    	};
    }, [channelId, handleDmsEvent]);

    return (
    	<Elements elements={elements}>
    		<ChatSession token={getToken}>
    			<DmsListElement options={dmsOptions} />
    		</ChatSession>
    	</Elements>
    );
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    const dmsListElement = session.createElement("dms-list-element", {
    	companyId: "biz_xxxx",
    });

    dmsListElement.mount("#dms-list-container");
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    WhopDMsListView(
        companyId: "biz_xxxx",
        onEvent: { event in
            switch event {
            case let .channelSelected(channel):
                selectedChannel = channel
            }
        }
    )
    ```
  </Tab>
</Tabs>

### Event handling

Listen for channel selection to open the corresponding chat view.

<Tabs>
  <Tab title="React">
    | Event             | Detail           | Description                            |
    | ----------------- | ---------------- | -------------------------------------- |
    | `channelSelected` | `{ id: string }` | Emitted when the user clicks a channel |

    ```tsx theme={null}
    const handleDmsEvent = useCallback((event: DmsListElementEvent) => {
    	switch (event.type) {
    		case "channelSelected":
    			setChannelId(event.detail.id);
    			break;
    	}
    }, []);
    ```
  </Tab>

  <Tab title="Vanilla JS">
    | Event             | Detail           | Description                            |
    | ----------------- | ---------------- | -------------------------------------- |
    | `channelSelected` | `{ id: string }` | Emitted when the user clicks a channel |

    ```typescript theme={null}
    dmsListElement.on("channelSelected", (ev) => {
    	console.log("Channel selected:", ev.detail.id);
    });
    ```
  </Tab>

  <Tab title="Swift">
    | Event              | Detail               | Description                          |
    | ------------------ | -------------------- | ------------------------------------ |
    | `.channelSelected` | `channel: DMChannel` | Emitted when the user taps a channel |

    ```swift theme={null}
    WhopDMsListView(
        onEvent: { event in
            switch event {
            case let .channelSelected(channel):
                selectedChannel = channel
            }
        }
    )
    .navigationDestination(item: $selectedChannel) { channel in
        WhopChatView(
            channelId: channel.id,
            style: .imessage
        )
        .navigationBarTitleDisplayMode(.inline)
        .navigationTitle(channel.name)
    }
    ```
  </Tab>
</Tabs>


# OAuth
Source: https://docs.whop.com/developer/guides/chat/oauth

Authenticate embedded chat users with Whop OAuth and SDK-managed sign-in.

With OAuth, users sign in to Whop themselves through a sign-in page or an iOS webview. Your app receives Whop user tokens that can authenticate embedded chat and act on behalf of the signed-in user.

Use OAuth when your app needs access to the user's Whop account, or when you do not want to mint company-scoped user tokens from your own backend.

<Card title="Full OAuth guide" icon="key" href="/developer/guides/oauth">
  See the general OAuth guide for the complete OAuth 2.1 + PKCE flow, token exchange, refresh, and revocation details.
</Card>

## Setup

<Tabs>
  <Tab title="API">
    Use the [Create App](/api-reference/apps/create-app) endpoint to create an OAuth app programmatically:

    ```typescript theme={null}
    import Whop from "@whop/sdk";

    const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

    const app = await client.apps.create({
      name: "My App",
      redirect_uris: [
        "http://localhost:3000/api/auth/callback/whop",
        "https://myapp.com/api/auth/callback/whop"
      ],
    });

    console.log(app.id);            // App ID
    console.log(app.client_secret); // Client Secret
    ```

    Update redirect URIs later with the [Update App](/api-reference/apps/update-app) endpoint.
  </Tab>

  <Tab title="Dashboard">
    <Steps>
      <Step title="Create or select your app">
        Register your app in the [Whop Dashboard](https://whop.com/dashboard/) > Developer to get an app ID.
      </Step>

      <Step title="Add a redirect URL">
        Inside the app you just created, go to OAuth and add a redirect URL.

        * For React or vanilla JavaScript apps, use your app's callback URL, such as `https://yourapp.com/oauth/callback`.
        * For Swift apps, use your bundle ID, such as `com.yourapp.bundle://oauth/callback`, or configure a custom redirect URI.
      </Step>

      <Step title="Select scopes">
        On the same page, copy the required scopes from "View available scopes".
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Required scopes

Your OAuth configuration should include these scopes:

| Scope                                                  | Purpose            |
| ------------------------------------------------------ | ------------------ |
| `openid`, `profile`, `email`                           | Basic profile info |
| `chat:message:create`, `chat:read`                     | Channels           |
| `dms:read`, `dms:message:manage`, `dms:channel:manage` | Direct messages    |
| `support_chat:read`, `support_chat:message:create`     | Support chats      |

## Web token endpoint

Your server needs to provide a token endpoint that returns a valid OAuth token with the required scopes. The React and vanilla JavaScript chat elements call this function whenever they need to authenticate.

```typescript theme={null}
async function getToken() {
  const response = await fetch("/api/token");
  const data = await response.json();
  return data.token;
}
```

See the [OAuth guide](/developer/guides/oauth) for implementing the server-side token exchange.

## SDK-managed OAuth on iOS

Call `configureWithOAuth` on app launch. The SDK handles the entire flow: showing a sign-in webview, obtaining tokens, and refreshing them automatically.

```swift theme={null}
.task {
    await WhopSDK.configureWithOAuth(
        appId: "app_XXXXXXXXXXXXXX",
        scopes: [
            "openid", "profile", "email",
            "chat:message:create", "chat:read",
            "dms:read", "dms:message:manage", "dms:channel:manage",
            "support_chat:read", "support_chat:message:create",
        ]
    )
}
```

By default, the SDK uses your bundle identifier for the redirect URI (`com.yourapp.bundle://oauth/callback`). You can customize this:

```swift theme={null}
await WhopSDK.configureWithOAuth(
    appId: "app_XXXXXXXXXXXXXX",
    redirectUri: "myapp://auth/callback",
    scopes: [
        "openid", "profile", "email",
        "chat:message:create", "chat:read",
        "dms:read", "dms:message:manage", "dms:channel:manage",
        "support_chat:read", "support_chat:message:create",
    ]
)
```

Make sure the redirect URI matches what you configured in the [Whop Dashboard](https://whop.com/dashboard/) > Developer > App > OAuth.

When a user navigates to a chat view, the OAuth flow is triggered automatically if they're not already authenticated. You can also trigger sign-in and sign-out manually:

```swift theme={null}
// Sign in
try await WhopSDK.signIn()

// Sign out
WhopSDK.signOut()
```

### Tracking authentication state

Use the `.whopAuthState` modifier to reactively track whether the user is signed in:

```swift theme={null}
struct ChatView: View {
    @State private var isAuthenticated = false

    var body: some View {
        VStack {
            if isAuthenticated {
                Text("Signed In")
            } else {
                Text("Not Signed In")
            }
        }
        .whopAuthState($isAuthenticated)
    }
}
```

### Pre-filling tokens

If you already have the user's Whop tokens from another source, such as a web OAuth flow or tokens synced from your backend, you can pre-fill them to skip the sign-in webview on first launch. This is optional and only relevant if your users have already authenticated with Whop elsewhere.

```swift theme={null}
let tokens = await myBackend.getWhopTokens(for: currentUser)

try await WhopSDK.preSignIn(
    accessToken: tokens.accessToken,
    refreshToken: tokens.refreshToken
)
```

The SDK extracts the token expiration from the JWT and handles refresh automatically. If the pre-filled tokens expire and can't be refreshed, the normal OAuth flow kicks in.

## Next steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/developer/guides/chat/authentication">
    Compare OAuth with company-scoped tokens for embedded chat.
  </Card>

  <Card title="General OAuth guide" icon="user-lock" href="/developer/guides/oauth">
    Implement the full OAuth flow, token exchange, refresh, and revocation.
  </Card>

  <Card title="Chat element" icon="message" href="/developer/guides/chat/chat-element">
    Learn the props, events, styles, and deeplinking options for the chat UI.
  </Card>

  <Card title="Embedded chat quickstart" icon="bolt" href="/developer/guides/chat/quickstart">
    Render your first embedded chat experience.
  </Card>
</CardGroup>


# Playground
Source: https://docs.whop.com/developer/guides/chat/playground

Interactive playground for embedded chat components

<Embed />


# Quickstart
Source: https://docs.whop.com/developer/guides/chat/quickstart

Give your users a real-time messaging chat on web and native iOS. Support many types of conversations. Whop handles the messages, realtime updates, media uploads and UI.

<iframe title="Embed Whop chat in your app" />

<div>
  <span>1</span>
  <h2>Create an API key</h2>
</div>

Create an API key in the [Whop Developer Dashboard](https://whop.com/dashboard/developer) and save it on your server as `WHOP_API_KEY`.

This key will allow you to perform actions within the context of your company. Keep it on the server. Never put it in browser, mobile, or client-side code.

<div>
  <span>2</span>
  <h2>Install packages</h2>
</div>

Install the SDK in your backend:

<Tabs>
  <Tab title="Next.js">
    ```bash theme={null}
    pnpm add @whop/sdk
    ```
  </Tab>

  <Tab title="Express">
    ```bash theme={null}
    pnpm add @whop/sdk
    ```
  </Tab>

  <Tab title="cURL">
    You can also check [the API reference](/developer/api/quickstart) if you prefer to make the requests yourself.
  </Tab>
</Tabs>

Install the elements packages in your frontend:

<Tabs>
  <Tab title="React">
    ```bash theme={null}
    pnpm add @whop/embedded-components-react-js @whop/embedded-components-vanilla-js
    ```
  </Tab>

  <Tab title="HTML">
    ```html theme={null}
    <script src="https://apollo.elements.whop.com/release/elements.js"></script>
    ```
  </Tab>

  <Tab title="iOS">
    Add this Swift package in Xcode:

    ```text theme={null}
    https://github.com/whopio/whopsdk-elements-swift
    ```

    Chat supports photos, videos, and voice messages, so add these permissions to your app's `Info.plist`:

    ```xml Info.plist theme={null}
    <key>NSCameraUsageDescription</key>
    <string>Allow camera access to take photos and videos in chat</string>
    <key>NSMicrophoneUsageDescription</key>
    <string>Allow microphone access to record voice messages in chat</string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>Allow photo library access to share photos and videos in chat</string>
    ```
  </Tab>
</Tabs>

<div>
  <span>3</span>
  <h2>Get a user ID for your users</h2>
</div>

Enroll your own users as connected accounts before minting chat tokens. This creates a Whop account you can map back to your platform user.

<Tabs>
  <Tab title="Next.js">
    ```typescript theme={null}
    import Whop from "@whop/sdk";

    const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

    const company = await client.companies.create({
      email: "user@example.com",
      parent_company_id: "biz_XXXXXXXXXXXXX", // your platform's company ID
      title: "Jane Doe",
      metadata: {
        internal_user_id: "user_12345", // your platform's user ID
      },
    });
    ```
  </Tab>

  <Tab title="Express">
    ```typescript theme={null}
    import Whop from "@whop/sdk";

    const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

    const company = await client.companies.create({
      email: "user@example.com",
      parent_company_id: "biz_XXXXXXXXXXXXX", // your platform's company ID
      title: "Jane Doe",
      metadata: {
        internal_user_id: "user_12345", // your platform's user ID
      },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.whop.com/api/v1/companies \
      -H "Authorization: Bearer $WHOP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "email": "user@example.com",
        "parent_company_id": "biz_XXXXXXXXXXXXX",
        "title": "Jane Doe",
        "metadata": {
          "internal_user_id": "user_12345"
        }
      }'
    ```
  </Tab>
</Tabs>

Save the resulting Whop user ID (`owner_user.id` in the response) on your side and pass it as `user_id` when you create chat access tokens.

See [company-specific profiles](/developer/guides/chat/sync-users#2-set-a-company-specific-name-and-profile-picture) for more details on how to update users avatars and display names.

<div>
  <span>4</span>
  <h2>Create a token endpoint on your server</h2>
</div>

Add an endpoint that calls `POST https://api.whop.com/api/v1/access_tokens` with your API key and returns the resulting token to the client.

<Tabs>
  <Tab title="Next.js">
    ```typescript app/api/chat/token/route.ts theme={null}
    import { NextResponse } from "next/server";
    import Whop from "@whop/sdk";

    const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

    export async function POST() {
      // Derive these from your own auth / session in production.
      const user_id = "user_XXXXXXXXXXXX";
      const company_id = "biz_XXXXXXXXXXXXX";

      const { token } = await client.accessTokens.create({
        company_id,
        user_id,
        scoped_actions: [
          "chat:message:create",
          "chat:read",
          "dms:read",
          "dms:message:manage",
          "dms:channel:manage",
          "support_chat:read",
          "support_chat:message:create",
        ],
      });

      return NextResponse.json({ token });
    }
    ```
  </Tab>

  <Tab title="Express">
    ```typescript server.ts theme={null}
    import express from "express";
    import Whop from "@whop/sdk";

    const app = express();
    app.use(express.json());

    const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

    app.post("/api/chat/token", async (_req, res) => {
      // Derive these from your own auth / session in production.
      const user_id = "user_XXXXXXXXXXXX";
      const company_id = "biz_XXXXXXXXXXXXX";

      const { token } = await client.accessTokens.create({
        company_id,
        user_id,
        scoped_actions: [
          "chat:message:create",
          "chat:read",
          "dms:read",
          "dms:message:manage",
          "dms:channel:manage",
          "support_chat:read",
          "support_chat:message:create",
        ],
      });

      res.json({ token });
    });

    app.listen(3000);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.whop.com/api/v1/access_tokens \
      -H "Authorization: Bearer $WHOP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "company_id": "biz_XXXXXXXXXXXXX",
        "user_id": "user_XXXXXXXXXXXX",
        "scoped_actions": [
          "chat:message:create",
          "chat:read",
          "dms:read",
          "dms:message:manage",
          "dms:channel:manage",
          "support_chat:read",
          "support_chat:message:create"
        ]
      }'
    ```
  </Tab>
</Tabs>

<div>
  <span>5</span>
  <h2>Create or fetch a channel, DM, or support chat</h2>
</div>

All chat types use real-time messaging and can render in the Chat element. Pick the type based on your needs:

<CardGroup>
  <Card title="Channels" icon="messages" href="/developer/guides/chat/channels">
    A shared chat for public or large group conversations. Rooms with moderation, read-only options, and no fixed member cap.
  </Card>

  <Card title="Direct messages" icon="inbox" href="/developer/guides/chat/direct-messages">
    A private conversation between users. They show in the DMs list and can include up to 50 members.
  </Card>

  <Card title="Support chat" icon="headset" href="/developer/guides/chat/support-chats">
    A one-on-one support conversation between a user and your company. Customers see them like DMs; admins manage them through a support inbox instead of the DMs list.
  </Card>
</CardGroup>

Before rendering chat, get the channel ID you want to open.

* [**Channels**](/developer/guides/chat/channels) IDs start with `chat_feed_`.
* [**DMs**](/developer/guides/chat/direct-messages) and [**support chats**](/developer/guides/chat/support-chats) IDs start with `feed_`.

<div>
  <span>6</span>
  <h2>Render chat in your app</h2>
</div>

This will use the token endpoint you created to fetch a token and render the chat element. The SDK is responsible of managing the token and refreshing it when necessary.

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    "use client";

    import {
      ChatElement,
      ChatSession,
      Elements,
    } from "@whop/embedded-components-react-js";
    import { loadWhopElements } from "@whop/embedded-components-vanilla-js";

    const elements = loadWhopElements();

    async function getToken() {
      const res = await fetch("https://your-server.com/api/chat/token", { method: "POST" });
      const data = await res.json();
      return data.token;
    }

    export function Chat() {
      return (
        <Elements elements={elements}>
          <ChatSession token={getToken}>
            <ChatElement
              options={{ channelId: "chat_feed_XXXXXXXXXXXXXX" }}
              style={{ height: "100dvh", width: "100%" }}
            />
          </ChatSession>
        </Elements>
      );
    }
    ```
  </Tab>

  <Tab title="HTML">
    ```html theme={null}
    <div id="chat" style="height: 100vh"></div>

    <script>
      const elements = new WhopElements();

      async function getToken() {
        const res = await fetch("https://your-server.com/api/chat/token", { method: "POST" });
        const data = await res.json();
        return data.token;
      }

      const session = elements.createChatSession({ token: getToken });
      const chat = session.createElement("chat-element", {
        channelId: "chat_feed_XXXXXXXXXXXXXX",
      });

      chat.mount("#chat");
    </script>
    ```
  </Tab>

  <Tab title="iOS">
    ```swift theme={null}
    import SwiftUI
    import WhopElements

    struct ContentView: View {
      var body: some View {
        WhopChatView(
          channelId: "chat_feed_XXXXXXXXXXXXXX",
          style: .imessage
        )
        // This should be done as soon as you know your user is authenticated so its
        // prepared and ready to use without delays.
        .task {
          await WhopSDK.configure(tokenProvider: WhopAPITokenProvider())
        }
      }
    }

    class WhopAPITokenProvider: WhopTokenProvider {
      func getToken() async -> WhopTokenResponse {
        let url = URL(string: "https://your-server.com/api/chat/token")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"

        do {
          let (data, _) = try await URLSession.shared.data(for: request)
          let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
          return WhopTokenResponse(accessToken: json["token"] as? String ?? "")
        } catch {
          return WhopTokenResponse(accessToken: "")
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Next steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/developer/guides/chat/authentication">
    Choose between company-scoped tokens and OAuth for embedded chat.
  </Card>

  <Card title="Sync your users" icon="user-plus" href="/developer/guides/chat/sync-users">
    Create or map Whop users before minting company-scoped chat tokens.
  </Card>

  <Card title="Chat element" icon="message" href="/developer/guides/chat/chat-element">
    Learn the props, events, styles, and deeplinking options for the chat UI.
  </Card>

  <Card title="DMs list element" icon="inbox" href="/developer/guides/chat/dms-list-element">
    Show a list of a user's direct message conversations.
  </Card>
</CardGroup>


# Support chats
Source: https://docs.whop.com/developer/guides/chat/support-chats

Use support chats for one-on-one customer support conversations with your company

Support chats are one-on-one conversations between a customer and your company. Use them when the conversation is official support, needs to be visible to team members, or should have an open/resolved workflow.

Unlike direct messages, support chats are organized around a customer support relationship with your company. They are best for customer service, not peer-to-peer messaging.

## When to use support chats

Use support chats when your team needs to respond to customers as the company.

Examples:

* A help inbox for paid members
* A billing or account support conversation
* A buyer support thread after checkout
* A creator-to-customer support line
* An escalation path from your app into Whop-hosted chat UI

### What makes support chats different

Support chats are the chat type for official customer-to-company conversations.

* Each support chat connects one customer with your company.
* For the customer, the conversation behaves like a normal DM-style chat and can appear in their DMs list.
* For team members, support chats are organized around a support inbox with open and resolved states.
* Team members can list, sort, and filter support chats by customer, status, and admin/team view.
* Moderators can help respond to support chats without getting full company admin access.

### Constraints

* Support chats are not for group user-to-user conversations. Use [direct messages](/developer/guides/chat/direct-messages) for that.
* Support chats do not appear in the DMs list component for admins. Build a support inbox with the support channels API instead.
* Support chats do not grant product or membership room access. Use [channels](/developer/guides/chat/channels) for member-only rooms.
* Support chats are not peer-to-peer DMs. Use [direct messages](/developer/guides/chat/direct-messages) when users should message each other directly.

## Access model

A support chat belongs to a company and a customer. Team members with support access can list and respond to support chats for the company. The customer can render and participate in their own support chat when authenticated with the required support scopes.

If someone on your team should help manage support chats without getting full admin access, add them as a team member with the moderator role. Moderators can help handle customer conversations while keeping broader company settings locked down.

<Note>
  Support chat IDs start with `feed_`.
</Note>

## Set up a support chat

<Steps>
  <Step title="Sync or identify the customer">
    You need the customer's Whop user ID or username. If your app has its own user system, map users first with [Sync your users](/developer/guides/chat/sync-users).
  </Step>

  <Step title="Create the support channel">
    Use [Create Support Channel](/api-reference/support-channels/create-support-channel). Whop returns the existing support chat if one already exists for that customer.
  </Step>

  <Step title="Render the conversation">
    Pass the returned support channel ID to the [Chat element](/developer/guides/chat/chat-element).
  </Step>

  <Step title="List support chats for your team">
    Use [List Support Channels](/api-reference/support-channels/list-support-channels) to build an inbox for your team.
  </Step>
</Steps>

Then render the support chat with the returned channel ID:

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    <ChatElement
      options={{ channelId: "feed_XXXXXXXXXXXXXX" }}
      style={{ height: "100dvh", width: "100%" }}
    />
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    const chatElement = session.createElement("chat-element", {
      channelId: "feed_XXXXXXXXXXXXXX",
    });

    chatElement.mount("#chat-container");
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    WhopChatView(
        channelId: "feed_XXXXXXXXXXXXXX",
        style: .imessage
    )
    ```
  </Tab>
</Tabs>

## Manage support chats

Use [Create Support Channel](/api-reference/support-channels/create-support-channel), [List Support Channels](/api-reference/support-channels/list-support-channels), and [Retrieve Support Channel](/api-reference/support-channels/retrieve-support-channel) to manage support chats.

Support chats also support inbox-style workflows. You can build views for open conversations, resolved conversations, customer-visible conversations, and team/admin views. See [List Support Channels](/api-reference/support-channels/list-support-channels) for the available filters.

## Next steps

<CardGroup>
  <Card title="Chat element" icon="message" href="/developer/guides/chat/chat-element">
    Render a support chat after you create or retrieve it.
  </Card>

  <Card title="Authentication" icon="key" href="/developer/guides/chat/authentication">
    Add support chat scopes to your token endpoint.
  </Card>
</CardGroup>


# Sync your users
Source: https://docs.whop.com/developer/guides/chat/sync-users

Create or map Whop users with your own platform users.

Sync users before you mint company-scoped user tokens for embedded chat. The user you pass as `user_id` must exist on Whop, and you can set a company-specific name and profile picture that appears for that user in chat.

<Note>
  This is **not needed for OAuth**. If you use OAuth, the user signs in to Whop and the OAuth token identifies their Whop account.
</Note>

## 1. Enroll users as connected accounts

Create a connected account for each user on your platform. This is the same flow used by the [payouts SDK](/developer/platforms/render-payout-portal) — see the [Enroll connected accounts](/developer/platforms/enroll-connected-accounts) guide for the full walkthrough.

```typescript theme={null}
import Whop from "@whop/sdk";

const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

const company = await client.companies.create({
  email: "user@example.com",
  parent_company_id: "biz_XXXXXXXXXXXXX", // your platform's company ID
  title: "Jane Doe",
  metadata: {
    internal_user_id: "user_12345", // your platform's user ID
  },
});
```

Save the resulting user ID on your side — you'll pass it when minting company-scoped chat tokens.

## 2. Set a company-specific name and profile picture

Call the [Update user](/api-reference/users/update-user) endpoint with your company ID to set overrides shown for that user in the context of your company. Without a company ID, the fields update the user's global profile instead.

Avatars are uploaded via the [Create file](/api-reference/files/create-file) endpoint — pass the returned file ID as the profile picture.

Call this whenever a user's profile changes on your platform so Whop stays in sync.

<Note>
  The Update user endpoint requires the `user:profile:update` permission on the API key making the request. Use a company API key with **owner-level** access, or a key that includes the `user:profile:update` scope.
</Note>

## Next steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/developer/guides/chat/authentication">
    Mint company-scoped user tokens for embedded chat.
  </Card>

  <Card title="OAuth" icon="user-lock" href="/developer/guides/chat/oauth">
    Use Whop sign-in instead of syncing users yourself.
  </Card>

  <Card title="Chat element" icon="message" href="/developer/guides/chat/chat-element">
    Render a live chat UI once your users are authenticated.
  </Card>

  <Card title="Enroll connected accounts" icon="user-plus" href="/developer/platforms/enroll-connected-accounts">
    Learn the full connected-account enrollment flow.
  </Card>
</CardGroup>


# Theming & styles
Source: https://docs.whop.com/developer/guides/chat/theming-and-styles

Customize the appearance of chat elements

## Theming

Customize the appearance of chat elements with a theme. On web, pass a `theme` through the Elements appearance options. On Swift, create a `WhopTheme` and apply it with `.whopTheme()`.

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    <Elements
    	elements={elements}
    	appearance={{
    		theme: {
    			appearance: "dark",
    			accentColor: "blue",
    			grayColor: "gray",
    			dangerColor: "red",
    			warningColor: "amber",
    			successColor: "green",
    			infoColor: "sky",
    		},
    	}}
    >
    	<ChatSession token={getToken}>
    		<ChatElement options={chatOptions} />
    	</ChatSession>
    </Elements>
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    const whopElements = await loadWhopElements();

    whopElements.updateOptions({
    	appearance: {
    		theme: {
    			appearance: "dark",
    			accentColor: "blue",
    			grayColor: "gray",
    			dangerColor: "red",
    			warningColor: "amber",
    			successColor: "green",
    			infoColor: "sky",
    		},
    	},
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    struct ThemedMessagesView: View {
        @State private var selectedChannel: DMChannel?

        let theme = WhopTheme(
            accent: .plum,
            neutral: .gray,
            danger: .tomato,
            warning: .violet
        )

        var body: some View {
            WhopDMsListView(
                onEvent: { event in
                    switch event {
                    case let .channelSelected(channel):
                        selectedChannel = channel
                    }
                }
            )
            .whopTheme(theme)
            .navigationDestination(item: $selectedChannel) { channel in
                WhopChatView(
                    channelId: channel.id,
                    style: .imessage
                )
                .whopTheme(theme)
                .navigationBarTitleDisplayMode(.inline)
                .navigationTitle(channel.name)
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Theme properties

| Purpose    | Web option     | Swift option | Description                                                                            |
| ---------- | -------------- | ------------ | -------------------------------------------------------------------------------------- |
| Appearance | `appearance`   | —            | Light or dark mode (`"light"`, `"dark"`) on web. Swift follows the app's color scheme. |
| Accent     | `accentColor`  | `accent`     | Primary interactive elements, links, and selection highlights                          |
| Neutral    | `grayColor`    | `neutral`    | Text, borders, and backgrounds                                                         |
| Danger     | `dangerColor`  | `danger`     | Destructive actions and error states                                                   |
| Warning    | `warningColor` | `warning`    | Warning states                                                                         |
| Success    | `successColor` | `success`    | Success states                                                                         |
| Info       | `infoColor`    | `info`       | Informational highlights                                                               |

### Available colors

All color properties accept these tints. Use strings on web, such as `"blue"`, and enum values on Swift, such as `.blue`.

`amber` · `blue` · `bronze` · `brown` · `crimson` · `cyan` · `gold` · `grass` · `gray` · `green` · `indigo` · `iris` · `jade` · `lemon` · `lime` · `magenta` · `mint` · `orange` · `pink` · `plum` · `purple` · `red` · `ruby` · `sky` · `teal` · `tomato` · `violet` · `yellow`

## Chat styles

Choose between Discord-style or iMessage-style chat. iMessage style (bubble chat) is the default if not provided.

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    const chatOptions: ChatElementOptions = useMemo(() => {
    	return {
    		channelId: "chat_feed_XXXXXXXXXXXXXX",
    		style: "discord", // or "imessage" (default)
    	};
    }, []);
    ```
  </Tab>

  <Tab title="Vanilla JS">
    ```typescript theme={null}
    const chatElement = session.createElement("chat-element", {
    	channelId: "chat_feed_XXXXXXXXXXXXXX",
    	style: "discord", // or "imessage" (default)
    });
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    // iMessage style (bubble chat)
    WhopChatView(
        channelId: "chat_feed_XXXXXXXXXXXXXX",
        style: .imessage
    )

    // Discord style (full-width messages)
    WhopChatView(
        channelId: "chat_feed_XXXXXXXXXXXXXX",
        style: .discord
    )
    ```
  </Tab>
</Tabs>


# Development Proxy
Source: https://docs.whop.com/developer/guides/dev-proxy

Run the Whop development proxy to replicate production authentication and iframe behavior during development.

In production, your app runs inside the Whop iframe behind a reverse proxy that injects the `x-whop-user-token` header on every request. Every Whop app verifies that token via [`whopsdk.verifyUserToken`](/developer/guides/authentication), so you need the same header on `localhost` to test against real users. The dev proxy injects it for you.

## Pick your setup

Two installation modes. Both ship the same proxy binary; the difference is whether the proxy spawns your dev server or runs alongside it.

|                 | Wrapped (Node/JS)                                       | Standalone                                                       |
| --------------- | ------------------------------------------------------- | ---------------------------------------------------------------- |
| **Best for**    | Next.js, Express, anything with a node-based dev script | Python, Ruby, Go, anything non-JS                                |
| **How it runs** | `whop-proxy --command 'next dev'` spawns your server    | Your server runs separately on a port; the proxy forwards to it  |
| **Port**        | One port (proxy + server)                               | Two ports (proxy on 3000, server on e.g. 5000)                   |
| **Install**     | `pnpm add -D @whop-apps/dev-proxy`                      | `pnpm dlx @whop-apps/dev-proxy --standalone` (no install needed) |

## NextJS / Javascript app

<Steps>
  <Step title="Add the proxy as a dev dependency">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm add -D @whop-apps/dev-proxy
      ```

      ```bash bun theme={null}
      bun install -D @whop-apps/dev-proxy
      ```

      ```bash npm theme={null}
      npm install -D @whop-apps/dev-proxy
      ```

      ```bash yarn theme={null}
      yarn add -D @whop-apps/dev-proxy
      ```
    </CodeGroup>
  </Step>

  <Step title="Update your package.json dev script">
    Update your `package.json` dev script to include the proxy.

    ```json theme={null}
    "scripts": {
        "dev": "whop-proxy --command 'next dev --turbopack'",
    }
    ```

    <Note>
      You can update the dev command to match your framework requirements.
      You can also wrap other commands with the proxy in a similar way.
    </Note>
  </Step>

  <Step title="Run the proxy">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm dev
      ```

      ```bash npm theme={null}
      npm run dev
      ```

      ```bash yarn theme={null}
      yarn dev
      ```
    </CodeGroup>
  </Step>
</Steps>

## Standalone mode (other frameworks)

<Steps>
  <Step title="Run your app locally">
    Run your app on your local machine on some port, for example 5000.

    <CodeGroup>
      ```bash Python + FastAPI theme={null}
      uvicorn main:app --port 5000
      ```

      ```bash Ruby on Rails theme={null}
      rails server -p 5000
      ```

      ```bash Go theme={null}
      go run main.go --port 5000
      ```
    </CodeGroup>
  </Step>

  <Step title="Run the proxy in standalone mode">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm dlx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
      ```

      ```bash bun theme={null}
      bunx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
      ```

      ```bash npm theme={null}
      npx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
      ```

      ```bash yarn theme={null}
      yarn dlx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
      ```
    </CodeGroup>

    <Note>
      This will run the proxy as an independent process. It will start a server on
      port 3000 and forward requests to port 5000 and append the user token in the
      headers.
    </Note>
  </Step>
</Steps>

## Proxy Command Options

The proxy can be configured using the following command line options:

```bash theme={null}
Usage: pnpm dlx @whop-apps/dev-proxy [options]

Options:

--proxyPort <port>      The port the proxy should listen on (3000 by default)
--upstreamPort <port>   The port the upstream server is listening on (set automatically by default)
--npmCommand <command>  The npm command to run to start the upstream server (dev by default)
--command <command>     The command to run to start the upstream server (npm run dev by default)
--standalone            Run the proxy as an independent process proxying requests from one port to another port. Ignores the command / npmCommand options.
```

## Next steps

<CardGroup>
  <Card title="Authentication" href="/developer/guides/authentication">
    Verify the iframe user token in the same code locally and in production.
  </Card>

  <Card title="Listen to webhooks" href="/developer/guides/webhooks">
    Forward Whop webhooks to localhost while developing (use ngrok or Cloudflare Tunnel).
  </Card>

  <Card title="Build app views" href="/developer/guides/app-views">
    Set up the iframe entry points your app will render inside.
  </Card>

  <Card title="Request permissions" href="/developer/guides/permissions">
    Configure the scopes your app needs before publishing.
  </Card>
</CardGroup>


# Forums
Source: https://docs.whop.com/developer/guides/forums

Create forum posts, fetch threads, and add comments or reactions inside any Whop community.

Use the Forums API to publish posts, comment on existing threads, and react to posts inside a Whop community's forum experience. Forum content is scoped by `experience_id`, so each forum tile in a community sidebar is a separate experience.

## Initialize the SDK

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const client = new Whop({
    appID: "app_xxxxxxxxxxxxx",
    apiKey: process.env.WHOP_API_KEY,
  });
  ```

  ```python Python theme={null}
  import os
  from whop_sdk import Whop

  client = Whop(
      app_id="app_xxxxxxxxxxxxx",
      api_key=os.environ["WHOP_API_KEY"],
  )
  ```
</CodeGroup>

## Create a post

Posts support Markdown. Optional fields let you pin the post, paywall it, or mark it as a mention.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const post = await client.forumPosts.create({
    experience_id: "exp_xxxxxxxxxxxxx",
    content: "This is the post body in **Markdown**.",
    title: "Optional title for paywalled posts",
    pinned: false,
    is_mention: false,
    paywall_amount: 0, // cents; 500 = $5.00
  });
  ```

  ```python Python theme={null}
  post = client.forum_posts.create(
      experience_id="exp_xxxxxxxxxxxxx",
      content="This is the post body in **Markdown**.",
      title="Optional title for paywalled posts",
      pinned=False,
      is_mention=False,
      paywall_amount=0,
  )
  ```
</CodeGroup>

## Read posts

List operations auto-paginate.

<CodeGroup>
  ```typescript TypeScript theme={null}
  for await (const page of client.forumPosts.list({
    experience_id: "exp_xxxxxxxxxxxxx",
    first: 10,
  })) {
    console.log(page);
  }

  const post = await client.forumPosts.retrieve("post_xxxxxxxxxxxxx");
  ```

  ```python Python theme={null}
  for page in client.forum_posts.list(
      experience_id="exp_xxxxxxxxxxxxx",
      first=10,
  ):
      print(page)

  post = client.forum_posts.retrieve("post_xxxxxxxxxxxxx")
  ```
</CodeGroup>

## Comment on a post

Comments are posts with a `parent_id`. Fetch them by passing the parent's ID to `list`.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const comment = await client.forumPosts.create({
    experience_id: "exp_xxxxxxxxxxxxx",
    content: "Great post!",
    parent_id: "post_xxxxxxxxxxxxx",
  });

  for await (const page of client.forumPosts.list({
    experience_id: "exp_xxxxxxxxxxxxx",
    parent_id: "post_xxxxxxxxxxxxx",
    first: 10,
  })) {
    console.log(page);
  }
  ```

  ```python Python theme={null}
  comment = client.forum_posts.create(
      experience_id="exp_xxxxxxxxxxxxx",
      content="Great post!",
      parent_id="post_xxxxxxxxxxxxx",
  )

  for page in client.forum_posts.list(
      experience_id="exp_xxxxxxxxxxxxx",
      parent_id="post_xxxxxxxxxxxxx",
      first=10,
  ):
      print(page)
  ```
</CodeGroup>

## Like a post

<Note>
  Forum reactions are always `:heart:`. Chat messages accept any emoji, but forum reactions ignore other values.
</Note>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.reactions.create({
    resource_id: "post_xxxxxxxxxxxxx",
    emoji: ":heart:",
  });
  ```

  ```python Python theme={null}
  client.reactions.create(
      resource_id="post_xxxxxxxxxxxxx",
      emoji=":heart:",
  )
  ```
</CodeGroup>

## Advanced features

### Pinned posts

Pinned posts appear above the feed. Set `pinned: true` on create.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.forumPosts.create({
    experience_id: "exp_xxxxxxxxxxxxx",
    content: "Important announcement!",
    pinned: true,
  });
  ```

  ```python Python theme={null}
  client.forum_posts.create(
      experience_id="exp_xxxxxxxxxxxxx",
      content="Important announcement!",
      pinned=True,
  )
  ```
</CodeGroup>

### Mention users

Use `<@username>` inline. Mentioned users get notified.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.forumPosts.create({
    experience_id: "exp_xxxxxxxxxxxxx",
    content: "Hey <@username> check this out!",
  });
  ```

  ```python Python theme={null}
  client.forum_posts.create(
      experience_id="exp_xxxxxxxxxxxxx",
      content="Hey <@username> check this out!",
  )
  ```
</CodeGroup>

### Paywalled posts

`paywall_amount` is in cents. Readers must pay to see the full content.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.forumPosts.create({
    experience_id: "exp_xxxxxxxxxxxxx",
    title: "Premium post",
    content: "Exclusive content here",
    paywall_amount: 500, // $5.00
  });
  ```

  ```python Python theme={null}
  client.forum_posts.create(
      experience_id="exp_xxxxxxxxxxxxx",
      title="Premium post",
      content="Exclusive content here",
      paywall_amount=500,
  )
  ```
</CodeGroup>

### Pagination with cursors

Beyond auto-pagination, you can step through pages manually using the `cursor` returned on each response.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const first = await client.forumPosts.list({
    experience_id: "exp_xxxxxxxxxxxxx",
    first: 10,
  });

  const next = await client.forumPosts.list({
    experience_id: "exp_xxxxxxxxxxxxx",
    first: 10,
    before: first.cursor,
  });
  ```

  ```python Python theme={null}
  first = client.forum_posts.list(
      experience_id="exp_xxxxxxxxxxxxx",
      first=10,
  )

  next_page = client.forum_posts.list(
      experience_id="exp_xxxxxxxxxxxxx",
      first=10,
      before=first.cursor,
  )
  ```
</CodeGroup>

## Required permissions

Add these to your app's permission list from the [Permissions guide](/developer/guides/permissions) before publishing.

| Permission          | Needed for                     |
| ------------------- | ------------------------------ |
| `forum:read`        | Reading posts and comments     |
| `forum:post:create` | Creating posts and comments    |
| `chat:read`         | Creating and reading reactions |

<Accordion title="Post object shape">
  ```typescript theme={null}
  {
    id: string;
    comment_count: number;
    content: string | null;
    is_edited: boolean;
    is_pinned: boolean;
    is_poster_admin: boolean;
    like_count: number | null;
    parent_id: string | null; // null = top-level, set = comment
    title: string | null;
    view_count: number | null;
    user: { id: string; name: string | null; username: string };
  }
  ```

  Full schema: see the [Forum posts API reference](/api-reference/forum-posts/forum-post).
</Accordion>

## Next steps

<CardGroup>
  <Card title="Build a chat bot" href="/developer/guides/chat">
    Pair forum posts with live chat messages in the same community.
  </Card>

  <Card title="Listen to events with webhooks" href="/developer/guides/webhooks">
    React to forum posts and comments in realtime on your server.
  </Card>

  <Card title="Send notifications" href="/developer/guides/notifications">
    Push users back to your forum when there's something new.
  </Card>

  <Card title="Upload files" href="/developer/guides/upload-files">
    Attach images and videos to posts.
  </Card>
</CardGroup>


# Frosted UI
Source: https://docs.whop.com/developer/guides/frosted_ui

Use our UI kit and tailwind design system.

Frosted UI is Whop's comprehensive React component library and design system. It provides 60+ accessible components, a sophisticated color system, typography scale, and seamless dark mode support—all built on top of Radix UI primitives and Tailwind CSS.

## Installation

<Steps>
  <Step title="Install the package">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm add @whop/react
      ```

      ```bash npm theme={null}
      npm install @whop/react
      ```

      ```bash yarn theme={null}
      yarn add @whop/react
      ```

      ```bash bun theme={null}
      bun install @whop/react
      ```
    </CodeGroup>

    <Note>
      The `@whop/react` package includes Frosted UI and all necessary dependencies.
    </Note>
  </Step>

  <Step title="Set up the WhopApp provider">
    Wrap your application with the `WhopApp` component in your root layout. This sets up the theme and iframe SDK.

    ```tsx theme={null}
    // app/layout.tsx
    import { WhopApp } from "@whop/react";

    export default function RootLayout({
        children,
    }: {
        children: React.ReactNode;
    }) {
        return (
            <html lang="en">
                <body>
                    <WhopApp accentColor="blue" appearance="inherit">
                        {children}
                    </WhopApp>
                </body>
            </html>
        );
    }
    ```
  </Step>

  <Step title="Configure Next.js (optional)">
    Use the `withWhopAppConfig` wrapper in your Next.js configuration:

    ```typescript theme={null}
    // next.config.ts
    import type { NextConfig } from "next";
    import { withWhopAppConfig } from "@whop/react/next.config";

    const nextConfig: NextConfig = {
        // your config options
    };

    export default withWhopAppConfig(nextConfig);
    ```

    <Note>
      This configures server actions and optimizes Frosted UI imports.
    </Note>
  </Step>

  <Step title="Set up Tailwind (optional)">
    If you're using Tailwind CSS, add the Frosted UI plugin to access design tokens:

    ```javascript theme={null}
    // tailwind.config.js
    import { frostedThemePlugin } from "@whop/react/tailwind";

    export default {
        content: ["./src/**/*.{js,ts,jsx,tsx}"],
        plugins: [frostedThemePlugin()],
    };
    ```
  </Step>
</Steps>

<Check>Frosted UI is now set up and ready to use!</Check>

***

## Typography

Frosted UI provides a comprehensive typography system with two main components: `Heading` and `Text`.

### Type Scale

Both components use a 10-step size scale (0-9):

| Size | Font Size | Usage               |
| ---- | --------- | ------------------- |
| 0    | 10px      | Smallest text       |
| 1    | 12px      | Small labels        |
| 2    | 14px      | Body text (small)   |
| 3    | 16px      | Body text (default) |
| 4    | 18px      | Emphasized text     |
| 5    | 20px      | Subheadings         |
| 6    | 24px      | Headings            |
| 7    | 28px      | Large headings      |
| 8    | 32px      | Display text        |
| 9    | 40px      | Hero text           |

### Text Component

```tsx theme={null}
import { Text } from "@whop/react";

<Text size="3" weight="medium">
    This is body text
</Text>

<Text size="1" color="gray">
    Small muted text
</Text>

<Text as="label" size="2" weight="bold">
    Form Label
</Text>
```

**Props:**

* `size`: `"0"` through `"9"` (default: `"3"`)
* `weight`: `"light"` | `"regular"` | `"medium"` | `"bold"`
* `align`: `"left"` | `"center"` | `"right"`
* `color`: Any accent color or `"gray"`
* `highContrast`: Increases contrast for accessibility
* `as`: `"span"` | `"div"` | `"p"` | `"label"`

### Heading Component

```tsx theme={null}
import { Heading } from "@whop/react";

<Heading size="6" as="h1">
    Page Title
</Heading>

<Heading size="4" as="h2" weight="medium">
    Section Heading
</Heading>
```

**Props:**

* `size`: `"0"` through `"9"` (default: `"6"`)
* `weight`: `"light"` | `"regular"` | `"medium"` | `"bold"`
* `align`: `"left"` | `"center"` | `"right"`
* `as`: `"h1"` | `"h2"` | `"h3"` | `"h4"` | `"h5"` | `"h6"`
* `color`: Any accent color or `"gray"`
* `highContrast`: Increases contrast for accessibility

### Other Typography Components

```tsx theme={null}
import { Code, Strong, Em, Kbd } from "@whop/react";

<Code>const example = "code";</Code>
<Strong>Bold text</Strong>
<Em>Italic text</Em>
<Kbd>⌘ K</Kbd>
```

***

## Colors

Frosted UI uses Radix color scales, providing 12-step color palettes with both solid and alpha variants.

### Accent Colors

27 accent colors are available:

**Regular Colors:** `tomato`, `red`, `ruby`, `crimson`, `pink`, `plum`, `purple`, `violet`, `iris`, `indigo`, `blue`, `cyan`, `teal`, `jade`, `green`, `grass`, `brown`, `orange`

**Bright Colors:** `sky`, `mint`, `lime`, `yellow`, `amber`, `lemon`, `magenta`

**Metallic Colors:** `gold`, `bronze`

### Gray Colors

6 gray scales with different color temperatures:

* `gray` - Pure neutral gray
* `mauve` - Slightly purple-tinted
* `slate` - Cool blue-tinted
* `sage` - Subtle green-tinted
* `olive` - Warm olive-tinted
* `sand` - Warm sandy-tinted
* `auto` - Automatically matches accent color

### Semantic Colors

Pre-configured colors for common use cases:

* **Danger:** `red` (default), `tomato`, `ruby`
* **Warning:** `amber` (default), `yellow`
* **Success:** `green` (default), `teal`, `jade`, `grass`
* **Info:** `sky` (default), `blue`

### Using Colors

```tsx theme={null}
import { Button, Badge, Text } from "@whop/react";

<Button color="blue">Primary Action</Button>
<Button color="red">Delete</Button>
<Badge color="green">Active</Badge>
<Text color="gray">Muted text</Text>
```

### Tailwind Color Classes

With the Tailwind plugin, you can use Frosted UI colors directly:

```tsx theme={null}
<div className="bg-blue-2 text-blue-11 border border-blue-6">
    Blue themed box
</div>

<div className="bg-red-a3 text-red-11">
    Red with alpha background
</div>
```

**Color Scale:**

* Steps 1-3: Backgrounds and subtle fills
* Steps 4-6: Borders and separators
* Steps 7-9: Interactive elements
* Steps 10-12: Text and high contrast elements

**Alpha Variants:**

* Use `{color}-a1` through `{color}-a12` for transparency

<Warning>
  With the `frostedUiPlugin()` added to your tailwind config, the default
  tailwind colors like `bg-blue-200` DO NOT WORK. Use `bg-blue-2` instead
  according to the above documentation.
</Warning>

***

## Dark Mode

Frosted UI includes automatic dark mode support that respects system preferences and user choices.

### How It Works

Dark mode is managed through three appearance modes:

* `"inherit"` (default) - Respects system preference
* `"light"` - Forces light mode
* `"dark"` - Forces dark mode

The theme preference is stored in a cookie (`whop-frosted-theme`) and falls back to system preference if not set.

### Configuration

Set the appearance in your `WhopApp` component:

```tsx theme={null}
<WhopApp appearance="dark">{children}</WhopApp>
```

Or create nested themes with different appearances:

```tsx theme={null}
import { Theme } from "@whop/react";

<Theme appearance="light">
    <div>This section is always light</div>
</Theme>

<Theme appearance="dark">
    <div>This section is always dark</div>
</Theme>
```

### Tailwind Dark Mode Classes

Use the `dark:` prefix for dark mode styles:

```tsx theme={null}
<div className="bg-white dark:bg-black text-black dark:text-white">
	Adapts to theme
</div>
```

***

## Breakpoints

Frosted UI uses a mobile-first responsive system with 5 breakpoints.

### Breakpoint Scale

| Name      | Min Width | Usage            |
| --------- | --------- | ---------------- |
| `initial` | 0px       | Mobile (default) |
| `xs`      | 520px     | Large mobile     |
| `sm`      | 768px     | Tablet           |
| `md`      | 1024px    | Small desktop    |
| `lg`      | 1280px    | Desktop          |
| `xl`      | 1640px    | Large desktop    |

### Responsive Props

Many components support responsive values using an object syntax:

```tsx theme={null}
import { Text, Box } from "@whop/react";

<Text size={{ initial: "2", md: "4", lg: "6" }}>Responsive text size</Text>;
```

### Tailwind Responsive Classes

```tsx theme={null}
<div className="p-2 md:p-4 lg:p-8">
    Responsive padding
</div>

<div className="text-2 sm:text-3 md:text-4">
    Responsive text
</div>
```

***

## Icons

Frosted UI includes an icon system through the `@frosted-ui/icons` package.

### Using Icons

```tsx theme={null}
import { IconButton } from "@whop/react";
import { MagnifyingGlassIcon, Cross2Icon } from "@frosted-ui/icons";

<IconButton>
    <MagnifyingGlassIcon />
</IconButton>

<IconButton color="red">
    <Cross2Icon />
</IconButton>
```

### Common Icons

Frosted UI uses Radix Icons, which includes icons like:

* Navigation: `ChevronRightIcon`, `ChevronDownIcon`, `ArrowRightIcon`
* Actions: `Cross2Icon`, `CheckIcon`, `PlusIcon`, `MinusIcon`
* UI: `MagnifyingGlassIcon`, `GearIcon`, `PersonIcon`
* And many more...

***

## Tailwind Plugin

The Frosted UI Tailwind plugin provides design tokens as Tailwind utilities.

### What's Included

**Typography:**

```tsx theme={null}
<p className="text-3 leading-3 font-medium tracking-2">
	Styled with Frosted UI tokens
</p>
```

**Colors:**

```tsx theme={null}
<div className="bg-blue-2 text-blue-11 border-blue-6">Blue themed</div>
```

**Spacing & Layout:**

```tsx theme={null}
<div className="p-4 md:p-6 lg:p-8">Responsive padding</div>
```

### Key Differences from Standard Tailwind

1. **Font Size Scale:** Uses 0-9 instead of xs/sm/base/lg
2. **Line Height Scale:** Matches font size scale (0-9)
3. **Color System:** 12-step Radix color scales with alpha variants
4. **Semantic Colors:** Built-in danger, warning, success, info colors
5. **Design Tokens:** All values use CSS variables for theme consistency

***

## Common Components

### Button

```tsx theme={null}
import { Button } from "@whop/react";

<Button size="2" variant="solid" color="blue">
    Primary Action
</Button>

<Button size="2" variant="soft" color="gray">
    Secondary
</Button>

<Button size="2" variant="ghost" color="red">
    Danger
</Button>
```

**Props:**

* `size`: `"1"` | `"2"` | `"3"` | `"4"`
* `variant`: `"solid"` | `"soft"` | `"surface"` | `"ghost"` | `"classic"`
* `color`: Any accent color
* `highContrast`: Enhanced contrast
* `loading`: Shows loading spinner
* `disabled`: Disables interaction

### Input

```tsx theme={null}
import { TextInput, TextArea } from "@whop/react";

<TextInput
    size="2"
    placeholder="Enter text..."
    variant="surface"
/>

<TextArea
    size="2"
    placeholder="Enter multiple lines..."
    rows={4}
/>
```

### Card

```tsx theme={null}
import { Card } from "@whop/react";

<Card size="2" variant="surface">
	<Heading size="4">Card Title</Heading>
	<Text>Card content goes here</Text>
</Card>;
```

### Badge

```tsx theme={null}
import { Badge } from "@whop/react";

<Badge color="green" variant="soft">Active</Badge>
<Badge color="red" variant="solid">Error</Badge>
<Badge color="gray" variant="surface">Draft</Badge>
```

### Dialog

```tsx theme={null}
import { Dialog, Button } from "@whop/react";

<Dialog.Root>
	<Dialog.Trigger>
		<Button>Open Dialog</Button>
	</Dialog.Trigger>
	<Dialog.Content>
		<Dialog.Title>Dialog Title</Dialog.Title>
		<Dialog.Description>This is the dialog content</Dialog.Description>
		<Dialog.Close>
			<Button>Close</Button>
		</Dialog.Close>
	</Dialog.Content>
</Dialog.Root>;
```

### Select

```tsx theme={null}
import { Select } from "@whop/react";

<Select.Root defaultValue="1">
	<Select.Trigger />
	<Select.Content>
		<Select.Item value="1">Option 1</Select.Item>
		<Select.Item value="2">Option 2</Select.Item>
		<Select.Item value="3">Option 3</Select.Item>
	</Select.Content>
</Select.Root>;
```

### Checkbox & Radio

```tsx theme={null}
import { Checkbox, RadioGroup } from "@whop/react";

<Checkbox size="2" color="blue">
    Accept terms
</Checkbox>

<RadioGroup.Root defaultValue="1">
    <RadioGroup.Item value="1">Option 1</RadioGroup.Item>
    <RadioGroup.Item value="2">Option 2</RadioGroup.Item>
</RadioGroup.Root>
```

***

## Advanced Usage

### Theme Customization

Customize the theme with multiple options:

```tsx theme={null}
<WhopApp
	appearance="dark"
	accentColor="violet"
	grayColor="mauve"
	dangerColor="ruby"
	warningColor="amber"
	successColor="jade"
	infoColor="sky"
>
	{children}
</WhopApp>
```

### Nested Themes

Create sections with different themes:

```tsx theme={null}
import { Theme } from "@whop/react";

<div>
	<Theme accentColor="blue">
		<Button>Blue button</Button>
	</Theme>

	<Theme accentColor="red" appearance="dark">
		<Button>Red button in dark mode</Button>
	</Theme>
</div>;
```

### Accessing Theme Context

```tsx theme={null}
import { useThemeContext } from "@whop/react";

function ThemedComponent() {
	const theme = useThemeContext();

	console.log(theme.appearance); // "light" | "dark"
	console.log(theme.accentColor); // "blue" | "red" | ...

	return <div>Current theme: {theme.appearance}</div>;
}
```

***

## Component Library

Frosted UI includes 60+ components organized by category:

**Layout:** `Box`, `Flex`, `Grid`, `Container`, `Section`, `AspectRatio`, `Inset`

**Typography:** `Heading`, `Text`, `Code`, `Strong`, `Em`, `Kbd`, `Quote`, `Blockquote`

**Forms:** `TextInput`, `TextArea`, `Checkbox`, `RadioGroup`, `Select`, `Switch`, `Slider`, `DatePicker`, `OTPField`

**Buttons:** `Button`, `IconButton`

**Display:** `Card`, `Avatar`, `AvatarGroup`, `Badge`, `Callout`, `Table`, `DataList`, `Skeleton`

**Navigation:** `Tabs`, `Breadcrumbs`, `Link`, `SegmentedControl`

**Overlay:** `Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `Popover`, `HoverCard`, `Tooltip`, `DropdownMenu`, `ContextMenu`

**Feedback:** `Progress`, `CircularProgress`, `Spinner`

**Utilities:** `ScrollArea`, `Separator`, `Portal`, `VisuallyHidden`, `AccessibleIcon`

<Info>
  All components are built on Radix UI primitives and follow accessibility best
  practices.
</Info>

***

## Resources

* [Radix UI Documentation](https://www.radix-ui.com/) - Component primitives
* [Radix Colors](https://www.radix-ui.com/colors) - Color system documentation
* [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework


# Iframe SDK
Source: https://docs.whop.com/developer/guides/iframe

Interact with the whop website from within your app.

Whop apps are embedded into the site using iFrames. This SDK provides a type-safe way for you to communicate with the Whop application using a request/response style API powered by `window.postMessage`.

Since this package relies on `window.postMessage`, it only works in **Client Components** or client side javascript.

### Relevant Packages

* `@whop/iframe` - The main package for the iframe SDK.
* `@whop/react` - A React wrapper for Whop Apps including helpers for the iframe SDK.

***

## Setup

The main function exported from the `@whop/iframe` package is the `createSdk` function. When called, this function sets up a listener for messages from the main Whop site, using `window.on('message', ...)`. It is also exposed through the `WhopIframeSdkProvider` component from `@whop/react`.

### React

If you're using React, it is recommended to use the `WhopIframeSdkProvider` component from `@whop/react` to provide the iframe SDK to all child components.

<Steps>
  <Step title="Mount provider in root layout">
    ```javascript theme={null}
    // app/layout.tsx
    import { WhopIframeSdkProvider } from "@whop/react";

    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode,
    }) {
      return (
        <html lang="en">
          <body>
            <WhopIframeSdkProvider>{children}</WhopIframeSdkProvider>
          </body>
        </html>
      );
    }
    ```
  </Step>

  <Step title="Consume the iframe SDK in a component">
    ```javascript theme={null}
    // components/example.tsx
    import { useIframeSdk } from "@whop/react";

    export const Example = () => {
      const iframeSdk = useIframeSdk();

      return (
        <button
          onClick={() => iframeSdk.openExternalUrl({ url: "https://example.com" })}
        >
          Open External URL
        </button>
      );
    };
    ```
  </Step>
</Steps>

### Other Frameworks

For other frameworks, you can use the `createSdk` function from `@whop/iframe` to create an instance of the iframe SDK.

<Steps>
  <Step title="Create the iframe SDK instance">
    ```javascript theme={null}
    // lib/iframe-sdk.ts
    import { createSdk } from "@whop/iframe";

    export const iframeSdk = createSdk({
      appId: process.env.NEXT_PUBLIC_WHOP_APP_ID,
    });
    ```
  </Step>

  <Step title="Use the iframe SDK instance">
    ```javascript theme={null}
    // index.ts
    import { iframeSdk } from "@/lib/iframe-sdk";

    const navigationButtonElement = document.querySelector("button");

    if (navigationButtonElement) {
      navigationButtonElement.addEventListener("click", () => {
        iframeSdk.openExternalUrl({ url: "https://example.com" });
      });
    }
    ```
  </Step>
</Steps>

<Check>We have now setup the SDK and iFrame.</Check>

## Opening External Links

Once the iframe SDK is initialized, you can use it to open external links. This will close your app and navigate to a new website.

<CodeGroup>
  ```javascript React theme={null}
  "use client";
  import { useIframeSdk } from "@whop/react";

  export default function Home() {
  	const iframeSdk = useIframeSdk();

      function openLink() {
      	iframeSdk.openExternalUrl({ url: "https://google.com" });
      }

      return <button onClick={openLink}>Click me to open Google</button>;

  }

  ```

  ```javascript Vanilla JS theme={null}
  import { iframeSdk } from "@/lib/iframe-sdk";

  const navigationButtonElement = document.querySelector("button");

  if (navigationButtonElement) {
    navigationButtonElement.addEventListener("click", () => {
      iframeSdk.openExternalUrl({ url: "https://google.com" });
    });
  }
  ```
</CodeGroup>

### Opening User Profiles

If you want to display a Whop user profile, you can use the `openExternalUrl` method and pass their profile page link which looks like `https://whop.com/@username`.

The Whop app will intercept this and display a modal containing their user profile instead of navigating away.

<CodeGroup>
  ```javascript React theme={null}
  "use client";
  import { useIframeSdk } from "@whop/react";

  export default function Home() {
  	const iframeSdk = useIframeSdk();

      function openProfile() {
      	iframeSdk.openExternalUrl({ url: "https://whop.com/@j" });
      }

      return <button onClick={openProfile}>View Profile</button>;

  }

  ```

  ```javascript Vanilla JS theme={null}
  import { iframeSdk } from "@/lib/iframe-sdk";

  const profileButtonElement = document.querySelector("button");

  if (profileButtonElement) {
    profileButtonElement.addEventListener("click", () => {
      iframeSdk.openExternalUrl({ url: "https://whop.com/@j" });
    });
  }
  ```
</CodeGroup>

<Info>
  You can also use a user ID instead of username. The final link should look
  like this: `https://whop.com/@user_XXXXXXXX`
</Info>

## In-App Purchases

The iframe SDK provides a method to trigger in-app purchases directly within your app. This allows you to accept payments for one-time purchases or subscriptions using Whop's checkout.

To process in-app purchases, you'll need to:

1. Create a checkout configuration on your server (with plan details and metadata)
2. Use the iframe SDK's `inAppPurchase` method to open the payment modal
3. Handle the response and validate the payment via webhooks

<CodeGroup>
  ```tsx React theme={null}
  "use client";
  import { useIframeSdk } from "@whop/react";
  import { useState } from "react";

  export default function PaymentButton() {
      const iframeSdk = useIframeSdk();
      const [paymentId, setPaymentId] = useState<string>();

      async function handlePurchase() {
          // 1. Create checkout configuration on server
          //    (in this example this is a nextjs server action, but it could also be a plain API route)
          const checkoutConfiguration = await createCheckoutConfiguration(/* can pass options here */);

          // 2. Open payment modal
          const res = await iframeSdk.inAppPurchase({
              planId: checkoutConfiguration.plan.id,
              id: checkoutConfiguration.id
          });

          if (res.status === "ok") {
              setPaymentId(res.data.receipt_id);
          } else {
              // handle errors
          }
      }

      return <button onClick={handlePurchase}>Purchase</button>;

  }

  ```

  ```javascript Vanilla JS theme={null}
  import { iframeSdk } from "@/lib/iframe-sdk";

  const paymentButton = document.querySelector("button#payment-button");

  paymentButton.addEventListener(
      "click",
      async function onPaymentButtonClick() {
          // 1. Create checkout configuration on server
          const checkoutConfiguration = await createCheckoutConfiguration(/* can pass options here */);

          // 2. Open payment modal
          const res = await iframeSdk.inAppPurchase({
              planId: checkoutConfiguration.plan.id,
              id: checkoutConfiguration.id
          });

          if (res.status === "ok") {
              const paymentId = res.data.receipt_id;
              // Send this id to your backend to validate, or rely on webhooks.
              // User has purchased the item, and it can be unlocked.
          } else {
              // handle errors
          }
      }
  );
  ```
</CodeGroup>

<Info>
  For a complete guide on setting up in-app purchases including creating
  checkout configurations, handling webhooks, and validating payments, see the
  [Accept payments documentation](/developer/guides/accept-payments).
</Info>


# Accept one-time payments
Source: https://docs.whop.com/developer/guides/ios/accept-one-time-payments

Sell physical goods and real-world services with native Apple Pay through Whop (2.7% + $0.30 fees)

<iframe title="Accept one-time payments on iOS with Whop" />

Use `Checkout.ApplePayButton` to accept one-time payments for physical goods or real-world services using Apple Pay. Payments are processed by Whop at **2.7% + \$0.30** instead of Apple's 15–30% in-app purchase fees.

<Tip>
  Selling on the web too? Use [checkout links or embedded checkout](/developer/guides/accept-payments) for **100+ payment methods** across **195 countries**.
</Tip>

<Warning>
  **Apple Pay is not for digital content.** Only use `Checkout.ApplePayButton` if your app sells physical goods (merch, food, hardware) or real-world services (event tickets, deliveries). Apps selling digital content — premium features, subscriptions, in-app currency, content unlocks — must use StoreKit. See the [Apple Pay eligibility](/developer/guides/ios/checkout-reference#apple-pay-eligibility) section for details.
</Warning>

## What you'll build

* A product detail screen with a native Apple Pay button
* A purchase flow that handles success, failure, and cancellation
* Plan configuration in the Whop dashboard for your physical goods

## Prerequisites

* [Install the WhopCheckout SDK](/developer/guides/ios/installation)
* An API key scoped to `iap:read` — see [Create an API key](/developer/guides/ios/installation#step-3-create-an-api-key)
* A Whop product with a one-time plan (see [Step 5](#step-5-set-up-your-plan))

## Step 1: Configure the SDK

Initialize the SDK at app launch. For one-time physical goods you don't need `planMappings` — that's only used for StoreKit fallback on subscriptions.

```swift theme={null}
import SwiftUI
import WhopCheckout

@main
struct DropsApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(Checkout.shared)
                .task {
                    try? await Checkout.shared.configure(
                        // companyId: find in Dashboard URL (starts with biz_)
                        companyId: "biz_xxxxxxxxxxxxxx",
                        // apiKey: create in Dashboard > Developer with iap:read permission
                        apiKey: "your_api_key_here"
                    )
                }
        }
    }
}
```

See the [installation guide](/developer/guides/ios/installation) for the full setup and security notes on the API key.

## Step 2: Add the Apple Pay button

Drop `Checkout.ApplePayButton` into your product view. The component renders Apple's official, HIG-compliant Apple Pay button — you can't substitute a custom-styled button.

```swift theme={null}
import SwiftUI
import WhopCheckout

struct ProductDetailView: View {
    let product: MerchItem
    @State private var purchaseComplete = false

    var body: some View {
        ScrollView {
            // product image, title, price, size picker...

            Checkout.ApplePayButton(
                // planId: find in Dashboard > Products > [product] > Plans
                planId: product.planId,
                label: .buy,
                onCompletion: { result in
                    switch result {
                    case .success(let purchase):
                        // purchase.receiptId, purchase.membership
                        purchaseComplete = true
                    case .failure(let error):
                        print("Purchase failed: \(error.localizedDescription)")
                    }
                }
            )
            .frame(height: 48)
            .padding(.horizontal)
        }
    }
}
```

When the user taps, they get the native Apple Pay sheet. Face ID or double-click confirms, and the payment flows through Whop.

<Info>
  `onCompletion` is **not called** when the user cancels — the sheet just dismisses. No cleanup needed.
</Info>

## Step 3: Choose a button label

The `label` parameter controls the text on the button. Pick the one that fits the action:

| Label       | Button text          | Use for                                 |
| ----------- | -------------------- | --------------------------------------- |
| `.buy`      | Buy with Apple Pay   | One-time merch and physical goods       |
| `.checkout` | Check out with…      | Cart-style checkout flows               |
| `.order`    | Order with Apple Pay | Food, deliveries, made-to-order items   |
| `.book`     | Book with Apple Pay  | Reservations, appointments, events      |
| `.continue` | Continue with…       | Multi-step flows where this isn't final |
| `.plain`    | (Apple Pay logo)     | Fallback when no verb fits              |

The full list comes from Apple's `PayWithApplePayButtonLabel` — see [Apple's documentation](https://developer.apple.com/documentation/passkit/paywithapplepaybuttonlabel) for every option.

## Step 4: Handle the purchase result

`onCompletion` receives a `Result<CheckoutPurchaseResult, Error>`. On success you get back:

| Property     | Type                  | Description                                  |
| ------------ | --------------------- | -------------------------------------------- |
| `receiptId`  | `String`              | Unique receipt ID for this purchase          |
| `membership` | `CheckoutMembership?` | The membership Whop created for the purchase |

Use this to show a confirmation screen, kick off shipping, or store the receipt for your own records.

```swift theme={null}
onCompletion: { result in
    switch result {
    case .success(let purchase):
        // Persist the receipt for your fulfillment flow
        OrderStore.shared.record(
            receiptId: purchase.receiptId,
            membershipId: purchase.membership?.id,
            product: product
        )
        showConfirmation = true
    case .failure(let error):
        showError(error.localizedDescription)
    }
}
```

## Step 5: Set up your plan

Each purchasable item needs a plan in your Whop dashboard:

<Steps>
  <Step title="Create a plan">
    Go to your [Dashboard](https://whop.com/dashboard) > Products > select your product > **Plans** > **Create plan**.
  </Step>

  <Step title="Set it to one-time">
    Choose **One-time payment** and set the price.
  </Step>

  <Step title="(Optional) Set inventory limits">
    For limited drops, set a stock cap. The checkout enforces it automatically — when stock runs out, purchases stop.
  </Step>

  <Step title="Copy the plan ID">
    The ID starts with `plan_`. Pass it to `Checkout.ApplePayButton(planId:)`.
  </Step>
</Steps>

## Handle fulfillment with webhooks

For physical goods, you'll need a server-side webhook to trigger shipping after a successful purchase. Listen for the `payment.succeeded` event:

```typescript theme={null}
import { whopsdk } from "@/lib/whop-sdk";

export async function POST(request: Request) {
  const body = await request.text();
  const headers = Object.fromEntries(request.headers);
  const event = whopsdk.webhooks.unwrap(body, { headers });

  if (event.type === "payment.succeeded") {
    // Trigger your shipping/fulfillment flow
    await fulfillOrder(event.data);
  }

  return new Response("OK", { status: 200 });
}
```

<Info>
  The client-side `onCompletion` callback confirms the payment to the user, but your **server** should handle fulfillment via webhooks — don't rely on the client alone. See the full [webhooks guide](/developer/guides/webhooks) for setup.
</Info>

## Complete example

A minimal merch detail view with size selection and Apple Pay:

```swift theme={null}
import SwiftUI
import WhopCheckout

struct ProductDetailView: View {
    let product: MerchItem
    @State private var selectedSize: String?
    @State private var showConfirmation = false

    var body: some View {
        ScrollView {
            VStack(alignment: .leading, spacing: 16) {
                AsyncImage(url: product.imageURL) { image in
                    image.resizable().scaledToFit()
                } placeholder: {
                    Color.gray.opacity(0.1)
                }
                .frame(maxWidth: .infinity)

                Text(product.title)
                    .font(.title)
                    .bold()

                Text(product.price, format: .currency(code: "USD"))
                    .font(.title2)

                // Size picker
                HStack {
                    ForEach(product.sizes, id: \.self) { size in
                        Button(size) {
                            selectedSize = size
                        }
                        .buttonStyle(.bordered)
                        .tint(selectedSize == size ? .accentColor : .secondary)
                    }
                }

                Checkout.ApplePayButton(
                    planId: product.planId,
                    label: .buy,
                    onCompletion: { result in
                        switch result {
                        case .success(let purchase):
                            print("Receipt: \(purchase.receiptId)")
                            showConfirmation = true
                        case .failure(let error):
                            print("Purchase failed: \(error.localizedDescription)")
                        }
                    }
                )
                .frame(height: 48)
                .disabled(selectedSize == nil)
            }
            .padding()
        }
        .sheet(isPresented: $showConfirmation) {
            OrderConfirmationView(product: product, size: selectedSize ?? "")
        }
    }
}
```

## Next steps

<CardGroup>
  <Card title="Webhooks" icon="webhook" href="/developer/guides/webhooks">
    Handle payment events and trigger fulfillment
  </Card>

  <Card title="Apple Pay eligibility" icon="shield-check" href="/developer/guides/ios/checkout-reference#apple-pay-eligibility">
    Confirm your app qualifies under App Store Review Guidelines
  </Card>

  <Card title="Build a paywall" icon="credit-card" href="/developer/guides/ios/build-a-paywall">
    Sell subscriptions instead of one-time purchases
  </Card>

  <Card title="API reference" icon="book" href="/developer/guides/ios/checkout-reference">
    Full SDK documentation
  </Card>
</CardGroup>


# Build a Paywall
Source: https://docs.whop.com/developer/guides/ios/build-a-paywall

Display subscription plans and handle purchases in your iOS app

This guide shows you how to build a paywall that displays your subscription plans and handles the purchase flow. By the end, you'll have a working paywall that lets users subscribe to your product.

## What you'll build

* A paywall screen that displays available plans with pricing
* A purchase flow that handles payments through Whop
* Error handling for cancelled or failed purchases

## Prerequisites

* [Install the SDK](/developer/guides/ios/installation)
* A Whop company with at least one product and plan
* An API key scoped to `iap:read` — see [Create an API key](/developer/guides/ios/installation#step-3-create-an-api-key) for setup

<Info>
  The `iap:read` permission is designed for client-side use and only grants access to in-app purchase operations. It's safe to embed in your app bundle. Never ship a key with broader permissions.
</Info>

## Step 1: Configure the SDK

Initialize the SDK in your app's entry point with your API key:

```swift theme={null}
import SwiftUI
import WhopCheckout

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(Checkout.shared)
                .task {
                    try? await Checkout.shared.configure(
                        // companyId: find in Dashboard URL (starts with biz_)
                        companyId: "biz_xxxxxxxxxxxxxx",
                        // apiKey: create in Dashboard > Developer with iap:read permission
                        apiKey: "your_api_key_here",
                        planMappings: [
                            .init(whopId: "plan_xxxxx", appleId: "monthly_sub"),
                            .init(whopId: "plan_yyyyy", appleId: "yearly_sub")
                        ]
                    )
                }
        }
    }
}
```

<Info>
  Find your company ID in the URL of your [Whop
  Dashboard](https://whop.com/dashboard) (starts with `biz_`). Find your plan
  IDs in the Products tab under each plan (starts with `plan_`).
</Info>

## Step 2: Display available plans

Use the `plans` property to show available subscription options:

```swift theme={null}
struct PaywallView: View {
    @Environment(Checkout.self) var checkout

    var body: some View {
        VStack(spacing: 20) {
            Text("Choose a Plan")
                .font(.title)
                .bold()

            ForEach(checkout.plans) { plan in
                PlanCard(plan: plan)
            }
        }
        .padding()
    }
}

struct PlanCard: View {
    let plan: CheckoutPlan
    @Environment(Checkout.self) var checkout

    var body: some View {
        VStack(alignment: .leading, spacing: 8) {
            Text(plan.title ?? "Plan")
                .font(.headline)

            Text(plan.initialPrice, format: .currency(code: plan.baseCurrency))
                .font(.title2)
                .bold()

            Button("Subscribe") {
                Task {
                    await purchase(plan)
                }
            }
            .buttonStyle(.borderedProminent)
        }
        .padding()
        .background(.ultraThinMaterial)
        .cornerRadius(12)
    }

    func purchase(_ plan: CheckoutPlan) async {
        do {
            let result = try await checkout.purchase(plan.id)
            // Purchase successful!
            print("Purchased: \(result.receiptId)")
        } catch WhopCheckoutError.cancelled {
            // User dismissed the checkout
        } catch {
            // Handle other errors
            print("Purchase failed: \(error)")
        }
    }
}
```

## Step 3: Handle the purchase flow

When a user taps "Subscribe", the SDK automatically:

1. Presents a checkout sheet with the Whop payment flow
2. Handles payment processing
3. Dismisses the sheet when complete
4. Returns the result or throws an error

```swift theme={null}
func purchase(_ planId: String) async {
    do {
        let result = try await checkout.purchase(planId)
        // Success - user now has an active membership
        print("Receipt ID: \(result.receiptId)")
    } catch WhopCheckoutError.cancelled {
        // User dismissed the checkout sheet
    } catch WhopCheckoutError.paymentFailed(let message) {
        // Payment failed - show error to user
        showError(message)
    } catch {
        // Other errors
        showError("Something went wrong. Please try again.")
    }
}
```

## Complete example

Here's a full paywall implementation:

```swift theme={null}
struct PaywallView: View {
    @Environment(Checkout.self) var checkout
    @Environment(\.dismiss) var dismiss
    @State private var selectedPlanId: String?
    @State private var isPurchasing = false

    var body: some View {
        NavigationStack {
            ScrollView {
                VStack(spacing: 24) {
                    // Header
                    VStack(spacing: 8) {
                        Image(systemName: "crown.fill")
                            .font(.system(size: 48))
                            .foregroundStyle(.yellow)

                        Text("Unlock Premium")
                            .font(.title)
                            .bold()

                        Text("Get access to all features")
                            .foregroundStyle(.secondary)
                    }
                    .padding(.top, 32)

                    // Plans
                    ForEach(checkout.plans) { plan in
                        Button {
                            selectedPlanId = plan.id
                        } label: {
                            HStack {
                                VStack(alignment: .leading, spacing: 4) {
                                    Text(plan.title ?? "Plan")
                                        .font(.headline)
                                    Text(plan.initialPrice, format: .currency(code: plan.baseCurrency))
                                        .foregroundStyle(.secondary)
                                }
                                Spacer()
                            }
                            .padding()
                            .background(plan.id == selectedPlanId ? Color.accentColor.opacity(0.1) : Color(.secondarySystemBackground))
                            .cornerRadius(12)
                            .overlay {
                                RoundedRectangle(cornerRadius: 12)
                                    .stroke(plan.id == selectedPlanId ? Color.accentColor : .clear, lineWidth: 2)
                            }
                        }
                        .buttonStyle(.plain)
                    }

                    // Purchase button
                    Button {
                        guard let planId = selectedPlanId else { return }
                        Task { await purchase(planId) }
                    } label: {
                        Group {
                            if isPurchasing {
                                ProgressView().tint(.white)
                            } else {
                                Text("Continue")
                            }
                        }
                        .font(.headline)
                        .foregroundStyle(.white)
                        .frame(maxWidth: .infinity)
                        .padding(.vertical, 14)
                        .background(Color.accentColor, in: RoundedRectangle(cornerRadius: 12))
                    }
                    .disabled(selectedPlanId == nil || isPurchasing)
                    .opacity(selectedPlanId == nil ? 0.5 : 1)
                }
                .padding()
            }
            .navigationTitle("Subscribe")
            .navigationBarTitleDisplayMode(.inline)
            .toolbar {
                ToolbarItem(placement: .cancellationAction) {
                    Button("Close") { dismiss() }
                }
            }
        }
    }

    func purchase(_ planId: String) async {
        isPurchasing = true
        defer { isPurchasing = false }

        do {
            _ = try await checkout.purchase(planId)
            dismiss()
        } catch WhopCheckoutError.cancelled {
            // User cancelled
        } catch {
            print("Purchase failed: \(error.localizedDescription)")
        }
    }
}
```

## Next steps

<CardGroup>
  <Card title="Check Entitlements" icon="shield-check" href="/developer/guides/ios/check-entitlements">
    Learn how to gate content based on subscription status
  </Card>

  <Card title="API Reference" icon="book" href="/developer/guides/ios/checkout-reference">
    Explore all available methods and properties
  </Card>
</CardGroup>


# Check Entitlements
Source: https://docs.whop.com/developer/guides/ios/check-entitlements

Verify subscription status and gate premium content in your iOS app

This guide shows you how to check if a user has an active subscription and gate premium content accordingly. You'll also learn how to handle user login/logout to sync subscriptions across devices.

## What you'll learn

* Check if a user has access to a product
* Gate content based on subscription status
* Sync subscriptions across devices with user login

## Prerequisites

* [Install the SDK](/developer/guides/ios/installation)
* [Configure the SDK](/developer/guides/ios/build-a-paywall#step-1-configure-the-sdk)

## Check subscription status

Use `hasAccess(to:)` to check if the user has access to a specific product:

```swift theme={null}
struct ContentView: View {
    @Environment(Checkout.self) var checkout

    var body: some View {
        VStack {
            // Basic features always available
            BasicFeaturesView()

            // Premium features for subscribers
            if checkout.hasAccess(to: "prod_xxxxxxxxxxxxxx") {
                PremiumFeaturesView()
            }

            // If you have multiple tiers, check each product separately
            if checkout.hasAccess(to: "prod_yyyyyyyyyyyyyy") {
                EnterpriseFeaturesView()
            }
        }
    }
}
```

Or use `isSubscribed` to check if the user has any active subscription:

```swift theme={null}
if checkout.isSubscribed {
    // User has at least one active membership
}
```

## View active memberships

Access the `memberships` array to show subscription details:

```swift theme={null}
struct SubscriptionStatusView: View {
    @Environment(Checkout.self) var checkout

    var body: some View {
        List {
            if checkout.memberships.isEmpty {
                Text("No active subscriptions")
                    .foregroundStyle(.secondary)
            } else {
                ForEach(checkout.memberships) { membership in
                    MembershipRow(membership: membership)
                }
            }
        }
    }
}

struct MembershipRow: View {
    let membership: CheckoutMembership

    var body: some View {
        VStack(alignment: .leading) {
            Text("Subscription")
                .font(.headline)

            if let expiresAt = membership.expiresAt {
                Text("Renews \(expiresAt, style: .date)")
                    .foregroundStyle(.secondary)
            }

            Text("Status: \(membership.status.rawValue)")
                .font(.caption)
                .foregroundStyle(.secondary)
        }
    }
}
```

## User login and logout

User IDs allow subscriptions to sync across devices. When a user logs in, the SDK automatically claims any unclaimed memberships from the current device and loads their existing memberships.

### Log in a user

```swift theme={null}
func handleLogin(userId: String) async {
    do {
        try await checkout.logIn(appUserId: userId)
        // Memberships are now synced for this user
    } catch {
        print("Login failed: \(error)")
    }
}
```

### Log out a user

```swift theme={null}
func handleLogout() {
    checkout.logOut()
    // User is now logged out, memberships cleared
}
```

### Check the current user

```swift theme={null}
if let userId = checkout.appUserId {
    Text("Logged in as \(userId)")
} else {
    Text("Not logged in")
}
```

## Guest purchases

Users can purchase subscriptions even without logging in. The SDK tracks these purchases by device ID and automatically claims them when the user logs in.

```swift theme={null}
struct PurchaseFlow: View {
    @Environment(Checkout.self) var checkout
    @State private var showingLogin = false

    var body: some View {
        VStack {
            if checkout.appUserId == nil {
                // User not logged in - they can still purchase
                Text("Purchase as guest or log in to sync across devices")

                Button("Continue as Guest") {
                    // Purchase will be tied to device
                    Task { try? await checkout.purchase("plan_xxx") }
                }

                Button("Log In") {
                    showingLogin = true
                }
            } else {
                // User logged in - purchase tied to their account
                Button("Subscribe") {
                    Task { try? await checkout.purchase("plan_xxx") }
                }
            }
        }
        .sheet(isPresented: $showingLogin) {
            // Your login view here
        }
    }
}
```

## Complete example

Here's a complete example showing entitlement checking with user auth:

```swift theme={null}
struct MainView: View {
    @Environment(Checkout.self) var checkout
    @State private var showingPaywall = false
    @State private var showingLogin = false

    var body: some View {
        NavigationStack {
            Group {
                if !checkout.isInitialized {
                    ProgressView("Loading...")
                } else if checkout.hasAccess(to: "prod_xxxxxxxxxxxxxx") {
                    PremiumContentView()
                } else {
                    FreeContentView(onUpgrade: { showingPaywall = true })
                }
            }
            .toolbar {
                ToolbarItem(placement: .topBarTrailing) {
                    Menu {
                        if let userId = checkout.appUserId {
                            Text("Signed in as \(userId)")
                            Button("Sign Out", action: signOut)
                        } else {
                            Button("Sign In") { showingLogin = true }
                        }

                        Divider()

                        if checkout.hasAccess(to: "prod_xxxxxxxxxxxxxx") {
                            Button("Manage Subscription") {
                                // Show subscription management
                            }
                        }
                    } label: {
                        Image(systemName: "person.circle")
                    }
                }
            }
            .sheet(isPresented: $showingPaywall) {
                PaywallView()
            }
            .sheet(isPresented: $showingLogin) {
                LoginView { userId in
                    Task {
                        try? await checkout.logIn(appUserId: userId)
                        showingLogin = false
                    }
                }
            }
        }
    }

    func signOut() {
        checkout.logOut()
    }
}

struct FreeContentView: View {
    let onUpgrade: () -> Void

    var body: some View {
        VStack(spacing: 20) {
            Text("Free Content")
                .font(.title)

            Text("Upgrade to access premium features")
                .foregroundStyle(.secondary)

            Button("Upgrade Now", action: onUpgrade)
                .buttonStyle(.borderedProminent)
        }
    }
}

struct PremiumContentView: View {
    var body: some View {
        VStack {
            Image(systemName: "crown.fill")
                .font(.largeTitle)
                .foregroundStyle(.yellow)

            Text("Premium Content")
                .font(.title)

            Text("Thanks for subscribing!")
        }
    }
}
```

## Reactive updates

The SDK automatically updates views when subscription status changes. Since `Checkout` is `@Observable`, any view using `@Environment(Checkout.self)` will re-render when:

* A purchase completes
* A user logs in or out
* Memberships are loaded or updated

No manual refresh is needed.

## Next steps

<CardGroup>
  <Card title="Build a Paywall" icon="credit-card" href="/developer/guides/ios/build-a-paywall">
    Display plans and handle purchases
  </Card>

  <Card title="API Reference" icon="book" href="/developer/guides/ios/checkout-reference">
    Explore all available methods and properties
  </Card>
</CardGroup>


# API Reference
Source: https://docs.whop.com/developer/guides/ios/checkout-reference

Complete API documentation for WhopCheckout

This page documents all classes, methods, properties, and types available in the WhopCheckout SDK.

<Info>
  Looking for guides? See [Build a
  Paywall](/developer/guides/ios/build-a-paywall) or [Check
  Entitlements](/developer/guides/ios/check-entitlements).
</Info>

## Checkout

The main class for managing in-app purchases. An `@Observable` class that can be used with SwiftUI's environment system.

```swift theme={null}
@MainActor @Observable
public class Checkout
```

***

### shared

The shared Checkout instance. Use this singleton to configure the SDK and manage purchases.

```swift theme={null}
static let shared: Checkout
```

**Example:**

```swift theme={null}
import WhopCheckout

// Configure at app startup
try await Checkout.shared.configure(...)

// Pass through SwiftUI environment
ContentView()
    .environment(Checkout.shared)

// Access in views
@Environment(Checkout.self) var checkout
```

***

### configure(companyId:apiKey:planMappings:)

Configures and initializes the SDK. Call this once at app startup.

```swift theme={null}
func configure(
    companyId: String,
    apiKey: String,
    planMappings: [PlanMapping] = []
) async throws
```

**Parameters:**

| Parameter      | Type            | Description                                                                                                                                                                       |
| -------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyId`    | `String`        | Your Whop company ID (starts with `biz_`)                                                                                                                                         |
| `apiKey`       | `String`        | Your API key. Must be scoped to `iap:read` only — see [Create an API key](/developer/guides/ios/installation#step-3-create-an-api-key) for why this is safe to embed in your app. |
| `planMappings` | `[PlanMapping]` | Mapping of Whop plan IDs to Apple StoreKit product IDs. Pass an empty array if you don't need StoreKit fallback.                                                                  |

**Example:**

```swift theme={null}
try await Checkout.shared.configure(
    companyId: "biz_xxxxxxxxxxxxxx",
    apiKey: "your_api_key_here",
    planMappings: [
        .init(whopId: "plan_xxxxx", appleId: "monthly_sub"),
        .init(whopId: "plan_yyyyy", appleId: "yearly_sub")
    ]
)
```

***

### isInitialized

Indicates whether the SDK has finished initializing.

```swift theme={null}
var isInitialized: Bool { get }
```

**Example:**

```swift theme={null}
if checkout.isInitialized {
    // SDK ready to use
}
```

***

### deviceId

The unique device identifier managed by the SDK. Persists across app launches using the iOS Keychain.

```swift theme={null}
var deviceId: String { get }
```

***

### appUserId

The current logged-in user ID, or `nil` if no user is logged in.

```swift theme={null}
var appUserId: String? { get }
```

***

### plans

Array of available subscription plans for the configured products.

```swift theme={null}
var plans: [CheckoutPlan] { get }
```

**Example:**

```swift theme={null}
ForEach(checkout.plans) { plan in
    Text(plan.title ?? "Plan")
}
```

***

### memberships

Array of active memberships for the current user or device.

```swift theme={null}
var memberships: [CheckoutMembership] { get }
```

***

### isSubscribed

Whether the user has any active membership.

```swift theme={null}
var isSubscribed: Bool { get }
```

**Example:**

```swift theme={null}
if checkout.isSubscribed {
    // Show premium content
}
```

***

### supportsExternalPurchases

Whether the current App Store region supports external (non-StoreKit) purchases. Currently `true` for US users, `false` elsewhere.

```swift theme={null}
var supportsExternalPurchases: Bool { get }
```

When `true`, the SDK defaults to Whop web checkout (lower fees). When `false`, it defaults to StoreKit.

***

### refreshPlans()

Refreshes the available plans from the server.

```swift theme={null}
@discardableResult
func refreshPlans() async throws -> [CheckoutPlan]
```

**Returns:** The refreshed plans with current pricing.

**Throws:** `WhopCheckoutError` if the refresh fails.

Call this to update pricing or plan availability after initialization. The `plans` property will also be updated with the latest data.

**Example:**

```swift theme={null}
// Refresh and use the return value
let plans = try await Checkout.shared.refreshPlans()

// Or just refresh (plans property updates automatically)
try await Checkout.shared.refreshPlans()
```

***

### hasAccess(to:)

Checks if the user has access to a specific product.

```swift theme={null}
func hasAccess(to productId: String) -> Bool
```

**Parameters:**

| Parameter   | Type     | Description                                   |
| ----------- | -------- | --------------------------------------------- |
| `productId` | `String` | The product ID to check (starts with `prod_`) |

**Returns:** `true` if the user has an active membership for the product

**Example:**

```swift theme={null}
// Replace with your product ID from the Whop dashboard
if checkout.hasAccess(to: "prod_xxxxxxxxxxxxxx") {
    // Show pro features
}
```

***

### purchase(\_:method:)

Initiates a purchase flow for a plan. By default, uses Whop web checkout in the US (lower fees) and StoreKit elsewhere.

```swift theme={null}
func purchase(_ whopPlanId: String, method: PaymentMethod? = nil) async throws -> CheckoutPurchaseResult
```

**Parameters:**

| Parameter    | Type             | Description                                            |
| ------------ | ---------------- | ------------------------------------------------------ |
| `whopPlanId` | `String`         | The Whop plan ID to purchase (starts with `plan_`)     |
| `method`     | `PaymentMethod?` | Override the payment method. Defaults based on region. |

**Returns:** `CheckoutPurchaseResult` containing the receipt ID and membership information

**Throws:**

* `WhopCheckoutError.cancelled` if the user dismisses the checkout
* `WhopCheckoutError.notConfigured` if the SDK is not configured
* `WhopCheckoutError.paymentFailed(String)` if the payment fails

**Example:**

```swift theme={null}
do {
    // Use default payment method (Whop in US, StoreKit elsewhere)
    let result = try await checkout.purchase("plan_xxxxxxxxxxxxxx")
    print("Success! Receipt: \(result.receiptId)")
} catch WhopCheckoutError.cancelled {
    // User cancelled
} catch {
    // Handle error
}

// Or explicitly choose a payment method
let result = try await checkout.purchase("plan_xxx", method: .storeKit)
```

<Info>
  For Apple Pay, use [`Checkout.ApplePayButton`](#checkoutapplepaybutton), or
  [`presentApplePay(_:)`](#presentapplepay) when your UI triggers Apple Pay
  from a custom interaction.
</Info>

***

### logIn(appUserId:)

Logs in a user and claims any unclaimed memberships associated with the device.

```swift theme={null}
func logIn(appUserId: String) async throws
```

**Parameters:**

| Parameter   | Type     | Description                                              |
| ----------- | -------- | -------------------------------------------------------- |
| `appUserId` | `String` | Your app's user ID (should not change for the same user) |

**Example:**

```swift theme={null}
try await checkout.logIn(appUserId: "user_123")
```

***

### logOut()

Logs out the current user and clears their memberships from the local state.

```swift theme={null}
func logOut()
```

**Example:**

```swift theme={null}
checkout.logOut()
```

***

### restorePurchases()

Restores purchases from both StoreKit and Whop.

```swift theme={null}
func restorePurchases() async throws -> Bool
```

**Returns:** `true` if any active subscription was found

**Example:**

```swift theme={null}
Button("Restore Purchases") {
    Task {
        let restored = try await checkout.restorePurchases()
        if restored {
            print("Purchases restored!")
        }
    }
}
```

***

## Types

### CheckoutPurchaseResult

The result of a successful purchase.

```swift theme={null}
struct CheckoutPurchaseResult {
    let receiptId: String
    let membership: CheckoutMembership?
}
```

| Property     | Type                  | Description                             |
| ------------ | --------------------- | --------------------------------------- |
| `receiptId`  | `String`              | The unique receipt ID for this purchase |
| `membership` | `CheckoutMembership?` | The membership created by this purchase |

<Accordion title="When is membership nil?">
  The `membership` property depends on the payment method used:

  | Payment Method    | Region     | `membership` value    |
  | ----------------- | ---------- | --------------------- |
  | Whop web checkout | US         | Populated immediately |
  | StoreKit          | Outside US | `nil` initially       |

  **Why StoreKit purchases return nil:**
  StoreKit transactions are processed asynchronously by Apple. When the purchase completes, the SDK may not yet have the Whop membership synced. The SDK tracks StoreKit entitlements separately, so `checkout.isSubscribed` will still return `true`.

  **How to handle both cases:**

  ```swift theme={null}
  do {
      let result = try await checkout.purchase("plan_xxx")

      // Always check isSubscribed - works for both payment methods
      if checkout.isSubscribed {
          // Grant access
      }

      // Optionally use membership details if available
      if let membership = result.membership {
          print("Membership ID: \(membership.id)")
          print("Expires: \(membership.expiresAt?.formatted() ?? "N/A")")
      }
  } catch WhopCheckoutError.cancelled {
      // User cancelled
  }
  ```

  **Key point:** Don't rely on `membership` being non-nil to grant access. Always use `checkout.isSubscribed` or `checkout.hasAccess(to:)` to check subscription status.
</Accordion>

***

### PlanMapping

A mapping between a Whop plan and an Apple StoreKit product, used during SDK configuration. This tells the SDK which Apple product to use for StoreKit purchases outside the US.

<Info>
  **PlanMapping vs CheckoutPlan:** `PlanMapping` is for SDK configuration
  (mapping IDs). `CheckoutPlan` is what you display in your UI (has pricing,
  titles, etc.). You create `PlanMapping` objects in `configure()`, then access
  `CheckoutPlan` objects via `checkout.plans`.
</Info>

```swift theme={null}
struct PlanMapping: Sendable {
    let whopId: String
    let appleId: String

    init(whopId: String, appleId: String)
}
```

| Property  | Type     | Description                                                               |
| --------- | -------- | ------------------------------------------------------------------------- |
| `whopId`  | `String` | The Whop plan ID (e.g., `plan_xxx`)                                       |
| `appleId` | `String` | The Apple product ID from App Store Connect (e.g., `com.yourapp.monthly`) |

**Example:**

```swift theme={null}
// Used in configure() - just maps IDs
try await Checkout.shared.configure(
    companyId: "biz_xxx",
    apiKey: "your_key",
    planMappings: [
        .init(whopId: "plan_monthly", appleId: "com.app.monthly"),
        .init(whopId: "plan_yearly", appleId: "com.app.yearly")
    ]
)

// After configuration, use checkout.plans (CheckoutPlan array) for UI
ForEach(checkout.plans) { plan in  // These are CheckoutPlan objects
    Text(plan.title ?? "Plan")
    Text(plan.whopDisplayPrice)
}
```

<Tip>
  Your Whop plans and Apple products should have matching pricing and billing
  periods. See [Setup → Plan
  Mappings](/developer/guides/ios/checkout/setup#plan-mappings) for details.
</Tip>

***

### PaymentMethod

The payment method to use for a purchase.

```swift theme={null}
enum PaymentMethod: Sendable {
    case whop      // Web checkout via Whop (lower fees)
    case storeKit  // StoreKit in-app purchase via the App Store
}
```

| Case       | Description                                                                                |
| ---------- | ------------------------------------------------------------------------------------------ |
| `whop`     | Web checkout via Whop. 2.7% + \$0.30 fees (vs Apple's 15-30%). Available in the US.        |
| `storeKit` | StoreKit in-app purchase via the App Store (15-30% fees). Used as fallback outside the US. |

<Info>
  Apple Pay is not included in `PaymentMethod` — it has its own surfaces:
  [`Checkout.ApplePayButton`](#checkoutapplepaybutton) and
  [`presentApplePay(_:)`](#presentapplepay).
</Info>

***

### Checkout.ApplePayButton

A pre-built SwiftUI view that renders Apple's official Apple Pay button and handles the entire purchase flow. **You must use this component** (or `PKPaymentButton` / `PayWithApplePayButton`) when offering Apple Pay — custom-styled buttons are not permitted by Apple's Human Interface Guidelines.

```swift theme={null}
struct ApplePayButton: View {
    init(
        planId: String,
        label: PayWithApplePayButtonLabel = .plain,
        onCompletion: @escaping (Result<CheckoutPurchaseResult, Error>) -> Void
    )
}
```

**Parameters:**

| Parameter      | Type                         | Description                                                                              |
| -------------- | ---------------------------- | ---------------------------------------------------------------------------------------- |
| `planId`       | `String`                     | The Whop plan ID to purchase                                                             |
| `label`        | `PayWithApplePayButtonLabel` | Button label style: `.plain`, `.buy`, `.subscribe`, `.checkout`, `.book`, `.order`, etc. |
| `onCompletion` | `(Result) -> Void`           | Called on success or failure. **Not called** when the user cancels.                      |

**Example:**

```swift theme={null}
Checkout.ApplePayButton(planId: "plan_xxx", label: .subscribe) { result in
    switch result {
    case .success(let purchase):
        print("Receipt: \(purchase.receiptId)")
    case .failure(let error):
        showError(error.localizedDescription)
    }
}
.frame(height: 48)
```

<Warning>
  **Apple Pay is not for digital content.** Only use `Checkout.ApplePayButton`
  if your app sells physical goods or real-world services. Apps selling digital
  content (subscriptions to premium features, in-app currency, etc.) must use
  StoreKit. See the [Apple Pay eligibility](#apple-pay-eligibility) section
  below.
</Warning>

### presentApplePay(\_:)

Presents the Apple Pay sheet directly, for UIs that initiate Apple Pay from a custom interaction (for example a slide-to-pay control) instead of the pre-built button.

```swift theme={null}
func presentApplePay(_ planId: String) async throws -> CheckoutPurchaseResult
```

Call it only in direct response to a user interaction — Apple permits presenting a payment sheet only when the user has explicitly asked to pay. Throws `WhopCheckoutError.cancelled` when the user dismisses the sheet.

```swift theme={null}
let result = try await checkout.presentApplePay("plan_xxx")
```

The same [Apple Pay eligibility](#apple-pay-eligibility) rules apply as for `Checkout.ApplePayButton`.

***

### CheckoutPlan (Display)

A subscription plan available for purchase, accessed via `checkout.plans`. Use this for displaying plan information in your UI and for making purchases.

<Info>
  **CheckoutPlan vs Plan:** `CheckoutPlan` contains full plan details (pricing,
  titles, trial info) for your UI. `Plan` is just an ID mapping used during SDK
  configuration. You never create `CheckoutPlan` objects—they come from
  `checkout.plans` after configuration.
</Info>

```swift theme={null}
struct CheckoutPlan: Identifiable {
    let id: String
    let productId: String?
    let title: String?
    let description: String?
    let planType: PlanType
    let billingPeriodDays: Int?
    let baseCurrency: String
    let initialPrice: Double
    let renewalPrice: Double
    let trialPeriodDays: Int?

    var renewalPeriod: RenewalPeriod? { get }
    var whopDisplayPrice: String { get }
    var appleDisplayPrice: String? { get }
}

enum PlanType: String {
    case oneTime = "one_time"
    case renewal
    case unknown
}

enum RenewalPeriod: Equatable {
    case weekly      // 7 days
    case monthly     // 30 days
    case quarterly   // 90 days
    case semiAnnual  // 180 days
    case yearly      // 365 days
    case custom(Int) // Custom period in days
}
```

| Property            | Type             | Description                                                  |
| ------------------- | ---------------- | ------------------------------------------------------------ |
| `id`                | `String`         | The plan ID                                                  |
| `productId`         | `String?`        | The product this plan belongs to                             |
| `title`             | `String?`        | Display name of the plan                                     |
| `description`       | `String?`        | Description text for the plan                                |
| `planType`          | `PlanType`       | Whether this is a one-time or recurring plan                 |
| `billingPeriodDays` | `Int?`           | Number of days in billing cycle (30 = monthly, 365 = yearly) |
| `baseCurrency`      | `String`         | Currency code (e.g., "usd")                                  |
| `initialPrice`      | `Double`         | Initial price of the plan                                    |
| `renewalPrice`      | `Double`         | Price for renewals                                           |
| `trialPeriodDays`   | `Int?`           | Number of days in trial period                               |
| `renewalPeriod`     | `RenewalPeriod?` | Computed renewal period (`.monthly`, `.yearly`, etc.)        |
| `whopDisplayPrice`  | `String`         | Formatted Whop price (e.g., "\$9.99")                        |
| `appleDisplayPrice` | `String?`        | Localized StoreKit price, if a plan mapping exists           |

***

### CheckoutMembership

An active subscription membership.

```swift theme={null}
struct CheckoutMembership: Identifiable {
    let id: String
    let productId: String
    let planId: String
    let status: Status
    let isClaimed: Bool
    let createdAt: Date
    let expiresAt: Date?
    let renewalPeriodEnd: Date?
    let cancelAtPeriodEnd: Bool
    let receiptId: String?

    var isActive: Bool { get }
}

enum Status: String {
    case active
    case canceled
    case canceling
    case completed
    case drafted
    case expired
    case pastDue = "past_due"
    case trialing
    case unresolved
    case unknown
}
```

| Property            | Type      | Description                                                                                               |
| ------------------- | --------- | --------------------------------------------------------------------------------------------------------- |
| `id`                | `String`  | The membership ID                                                                                         |
| `productId`         | `String`  | The product this membership belongs to                                                                    |
| `planId`            | `String`  | The plan this membership is for                                                                           |
| `status`            | `Status`  | Current status of the membership                                                                          |
| `isActive`          | `Bool`    | Whether the membership grants access (true for `active`, `trialing`, `canceling`, `pastDue`, `completed`) |
| `isClaimed`         | `Bool`    | Whether the membership has been claimed by a user                                                         |
| `createdAt`         | `Date`    | When the membership was created                                                                           |
| `expiresAt`         | `Date?`   | When the membership expires                                                                               |
| `renewalPeriodEnd`  | `Date?`   | End of the current renewal period                                                                         |
| `cancelAtPeriodEnd` | `Bool`    | Whether the membership will cancel at period end                                                          |
| `receiptId`         | `String?` | The receipt ID for this membership                                                                        |

***

### WhopCheckoutError

Errors thrown by the SDK.

```swift theme={null}
enum WhopCheckoutError: Error {
    case cancelled
    case notConfigured
    case paymentFailed(String)
}
```

| Case                    | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `cancelled`             | User dismissed the checkout sheet without completing purchase     |
| `notConfigured`         | SDK is not configured. Call `Checkout.shared.configure()` first.  |
| `paymentFailed(String)` | Payment failed. The associated string contains the error message. |

***

## Apple Pay Eligibility

<Warning>
  **Most apps should NOT use Apple Pay.** Apple Pay via the WhopCheckout SDK is
  only for apps that sell physical goods or real-world services — not digital
  content, subscriptions to app features, or in-app currency.
</Warning>

### App Store Review Guidelines

Apple's [App Store Review Guideline 3.1.1](https://developer.apple.com/app-store/review/guidelines/#in-app-purchase) requires that **digital goods and services** (premium features, subscriptions, content unlocks, virtual currency) must use In-App Purchase (StoreKit). Apple Pay is explicitly prohibited for these transactions.

Apple Pay is permitted under [Guideline 3.1.3(e)](https://developer.apple.com/app-store/review/guidelines/#multiplatform-services) and the [Apple Pay guidelines](https://developer.apple.com/apple-pay/) for purchasing **physical goods and real-world services**.

### Qualifying Apps

Apps that **can** use Apple Pay (`Checkout.ApplePayButton`):

| Category              | Examples                                             |
| --------------------- | ---------------------------------------------------- |
| E-commerce            | Clothing, electronics, physical merchandise          |
| Food & delivery       | Meal delivery, grocery orders                        |
| Transportation        | Ride-hailing, car rentals, parking                   |
| Travel & hospitality  | Hotel bookings, flight tickets, event tickets        |
| Professional services | Tutoring sessions, consulting, home repair bookings  |
| Fitness & wellness    | In-person class bookings, personal training sessions |

Apps that **must** use StoreKit (`.storeKit`) or Whop web checkout (`.whop`):

| Category              | Examples                                   |
| --------------------- | ------------------------------------------ |
| Digital subscriptions | Premium app features, pro tiers            |
| Digital content       | E-books, music, video streaming            |
| Virtual goods         | In-app currency, cosmetic items, power-ups |
| Online courses        | Video courses, digital workshops           |
| SaaS features         | Cloud storage upgrades, API access tiers   |

### How to Choose

```
Is the user paying for a physical good or real-world service?
├── YES → You can use Checkout.ApplePayButton (or .whop / .storeKit)
└── NO  → You must use .whop or .storeKit (not Apple Pay)
```

If your app qualifies, use `Checkout.ApplePayButton`. If you're unsure whether your app qualifies, default to `.whop` (US) or `.storeKit` (elsewhere) — the SDK handles this automatically when you call `purchase()` without specifying a method.

***

## Requirements

* iOS 17.0+
* Xcode 15.0+
* Swift 5.10+


# Installation
Source: https://docs.whop.com/developer/guides/ios/installation

Install the WhopCheckout SDK and configure it with an iap:read API key

Whop's iOS SDKs are distributed as separate Swift packages — **WhopCheckout** for payments and **WhopElements** for embedded chat and payouts. Install only what you need.

## WhopCheckout (In-App Purchases)

The WhopCheckout package handles subscriptions and payments in your app.

### Step 1: Add Package Dependency

In Xcode, go to **File** → **Add Package Dependencies...**

Enter the package URL:

```
https://github.com/whopio/whopsdk-checkout-swift
```

### Step 2: Select Version

Choose the latest version or specify a version range:

* **Up to Next Major**: Recommended for production
* **Exact Version**: For stability

### Step 3: Create an API key

The SDK requires an API key scoped to the `iap:read` permission. This permission is designed for client-side use, so the key is safe to embed in your app bundle.

<Steps>
  <Step title="Open Developer Settings">
    Go to [Whop Developer Settings](https://whop.com/dashboard/developer) and select your app.
  </Step>

  <Step title="Create the API key">
    Click **Create API Key** and select **only** the `iap:read` permission.
  </Step>

  <Step title="Copy the key">
    Copy the generated key — you'll pass it to `Checkout.shared.configure()` in the next step.
  </Step>
</Steps>

<Warning>
  Only grant the `iap:read` permission. It's the only permission designed for client-side use and limits the key to in-app purchase operations. Never ship a key with broader permissions inside your app.
</Warning>

### Step 4: Import and configure

```swift theme={null}
import SwiftUI
import WhopCheckout

@main
struct YourApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(Checkout.shared)
                .task {
                    try? await Checkout.shared.configure(
                        // companyId: find in Dashboard URL (starts with biz_)
                        companyId: "biz_xxxxxxxxxxxxxx",
                        // apiKey: create in Dashboard > Developer with iap:read permission
                        apiKey: "your_api_key_here",
                        planMappings: [
                            .init(whopId: "plan_xxxxx", appleId: "monthly_sub")
                        ]
                    )
                }
        }
    }
}
```

<Card title="Build a Paywall" icon="credit-card" href="/developer/guides/ios/build-a-paywall">
  Continue with the full setup guide
</Card>

***

## WhopElements (embedded Chat, Payouts...)

Use WhopElements to embed Whop chat channels in your app.

### Step 1: Add Package Dependency

In Xcode, go to **File** → **Add Package Dependencies...**

Enter the package URL:

```
https://github.com/whopio/whopsdk-elements-swift
```

### Step 2: Select Version

Choose the latest version or specify a version range.

### Step 3: Import and Configure the specific element

```swift theme={null}
import SwiftUI
import WhopElements

@main
struct YourApp: App {
    var body: some Scene {
        WindowGroup {
            NavigationStack {
                WhopChatView(channelId: "chat_feed_XXXXXXXXXXXXXX")
            }
            .task {
                await WhopSDK.configureWithOAuth(appId: "app_XXXXXXXXXXXXXX")
            }
        }
    }
}
```

<Card title="Embedded Chat" icon="message" href="/developer/guides/chat/quickstart">
  Continue with the chat integration guide
</Card>

<Card title="Embedded Payouts" icon="money-bill-transfer" href="/developer/platforms/render-payout-portal">
  Continue with the chat integration guide
</Card>

***

## Requirements

* iOS 17.0+
* Xcode 15.0+
* Swift 5.10+

## Next steps

<CardGroup>
  <Card title="Build a Paywall" icon="credit-card" href="/developer/guides/ios/build-a-paywall">
    Add subscriptions and payments
  </Card>

  <Card title="Check Entitlements" icon="shield-check" href="/developer/guides/ios/check-entitlements">
    Gate content based on subscription status
  </Card>

  <Card title="Embedded Chat" icon="message" href="/developer/guides/chat/quickstart">
    Add Whop chat to your app
  </Card>

  <Card title="Embedded Payouts" icon="money-bill-transfer" href="/developer/platforms/render-payout-portal">
    Enable connected account payouts
  </Card>

  <Card title="API Reference" icon="book" href="/developer/guides/ios/checkout-reference">
    Full SDK documentation
  </Card>
</CardGroup>


# iOS Checkout SDK
Source: https://docs.whop.com/developer/guides/ios/overview

Sell in-app purchases and subscriptions natively on iOS (2.7% + $0.30 vs Apple's 15-30%)

The Whop iOS Checkout SDK lets you sell in-app purchases and subscriptions in your native iOS app. It automatically uses Whop's payment processing in the US (2.7% + \$0.30 vs Apple's 15-30%) and falls back to Apple's StoreKit elsewhere for global coverage.

<Tip>
  The SDK is configured with a scoped `iap:read` API key that's safe to ship in your app bundle. See [Create an API key](/developer/guides/ios/installation#step-3-create-an-api-key) for setup.
</Tip>

## What you can build

<CardGroup>
  <Card title="Build a Paywall" icon="credit-card" href="/developer/guides/ios/build-a-paywall">
    Display subscription plans and handle purchases in your app
  </Card>

  <Card title="Check Entitlements" icon="shield-check" href="/developer/guides/ios/check-entitlements">
    Verify subscription status and gate premium content
  </Card>
</CardGroup>

## Related iOS SDKs

Whop also ships separate SDKs for embedded experiences:

<CardGroup>
  <Card title="Embedded Chat" icon="message" href="/developer/guides/chat/quickstart">
    Add Whop chat channels directly in your app
  </Card>

  <Card title="Embedded Payouts" icon="money-bill-transfer" href="/developer/platforms/render-payout-portal">
    Render the connected-account payout portal
  </Card>
</CardGroup>

## Quick example

Here's a complete example showing the SDK in action:

```swift theme={null}
import SwiftUI
import WhopCheckout

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(Checkout.shared)
                .task {
                    try? await Checkout.shared.configure(
                        // companyId: find in Dashboard URL (starts with biz_)
                        companyId: "biz_xxxxxxxxxxxxxx",
                        // apiKey: create in Dashboard > Developer with iap:read permission
                        apiKey: "your_api_key_here",
                        planMappings: [
                            .init(whopId: "plan_xxxxx", appleId: "monthly_sub")
                        ]
                    )
                }
        }
    }
}

struct ContentView: View {
    @Environment(Checkout.self) var checkout

    var body: some View {
        if checkout.isSubscribed {
            Text("Welcome, premium user!")
        } else {
            Button("Upgrade to Premium") {
                Task {
                    try? await checkout.purchase("plan_xxxxx")
                }
            }
        }
    }
}
```

## Getting started

<Steps>
  <Step title="Install the SDK">
    Add the WhopCheckout package to your Xcode project via Swift Package Manager.

    [Installation guide →](/developer/guides/ios/installation)
  </Step>

  <Step title="Get your API key">
    Create an API key with the `iap:read` permission in your [Developer Settings](https://whop.com/dashboard/developer). [Why this is safe to embed →](/developer/guides/ios/installation#step-3-create-an-api-key)
  </Step>

  <Step title="Configure the SDK">
    Initialize the SDK with your company ID, API key, and plan mappings via `Checkout.shared.configure()`.
  </Step>

  <Step title="Build your paywall">
    Display plans and handle purchases. The SDK automatically uses Whop checkout in the US and StoreKit elsewhere.

    [Build a paywall →](/developer/guides/ios/build-a-paywall)
  </Step>
</Steps>

## Reference

<Card title="API Reference" icon="book" href="/developer/guides/ios/checkout-reference">
  Complete API documentation for all Checkout classes, methods, and types
</Card>

## Requirements

* iOS 17.0+
* Xcode 15.0+
* Swift 5.10+


# Wallet Stats API
Source: https://docs.whop.com/developer/guides/ledger-stats

Query aggregated financial time-series from your Fragment ledger

The Wallet Stats API gives you access to financial analytics powered by your Fragment ledger — the same data that powers the Whop dashboard charts. The wallet is resolved automatically from your API key's auth context. See the [API Reference](/api-reference/beta/ledger-stats/time-series) for the full list of parameters and allowed values.

<Note>
  The `time_series` endpoint requires the `company:balance:read` permission. See
  [Permissions](/developer/guides/permissions) to learn how to request
  permissions for your app.
</Note>

## Discover available filters

Before building queries, call the **schema** endpoint to get the full taxonomy of reporting categories, groupings, and line categories with human-readable descriptions. No authentication required.

```bash theme={null}
curl "https://api.whop.com/api/v1/stats/schema?resource_type=wallet"
```

The response tells you:

* **`reporting_categories`** — predefined report scopes (e.g. `gross_income`, `net_activity`) and which line categories each one includes
* **`groupings`** — logical buckets (e.g. `payments`, `refunds`, `disputes`) and their line categories
* **`line_categories`** — every active transaction type with its description, grouping, and which reports it belongs to

Use this to understand what filters to pass to the `time_series` endpoint. See the [Schema API Reference](/api-reference/beta/ledger-stats/schema) for the full response schema.

## Time Series

```
GET https://api.whop.com/api/v1/stats/time_series?resource_type=wallet
```

Returns total `amount` and `line_count` per period. Filter with `reporting_category`, `grouping`, or `line_category` to narrow results.

The wallet is resolved from your API key's auth context — no account ID needed in the URL.

### Parameters

| Parameter            | Type      | Default | Required | Description                                                                                                                               |
| -------------------- | --------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `resource_type`      | string    | —       | yes      | Must be `wallet`                                                                                                                          |
| `account_id`         | string    | —       | no       | Query a sub-account's wallet (e.g. `biz_xxx`). Pass `global` for platform-wide queries (admin only). Omit to use the caller's own wallet. |
| `from`               | date      | —       | yes      | Start date, ISO 8601 (e.g. `2025-01-01`)                                                                                                  |
| `to`                 | date      | —       | yes      | End date, ISO 8601 (e.g. `2025-12-31`)                                                                                                    |
| `group_by`           | string    | `month` | no       | Granularity: `day`, `week`, or `month`                                                                                                    |
| `reporting_category` | string    | all     | no       | Filter to a reporting category: `net_activity`, `gtv`, `gross_income`, `net_income`, `payment_processing_fees`                            |
| `grouping`           | string\[] | all     | no       | Filter by grouping(s): `payments`, `refunds`, `fees`, `disputes`, `withdrawals`, etc.                                                     |
| `line_category`      | string\[] | all     | no       | Filter by transaction type(s) (e.g. `payment_gross`, `payment_refund`)                                                                    |
| `currency`           | string    | all     | no       | Filter to a single currency (e.g. `usd`)                                                                                                  |
| `convert_currency`   | string    | —       | no       | Convert all amounts to this currency using historical exchange rates                                                                      |
| `timezone`           | string    | `UTC`   | no       | IANA timezone for period boundaries                                                                                                       |

### Example

```bash theme={null}
curl "https://api.whop.com/api/v1/stats/time_series?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&convert_currency=usd" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "period": "2025-01-01",
      "amount": 14550.35,
      "line_count": 342
    }
  ],
  "metadata": {
    "wallet_id": "ldgr_xxx",
    "from": "2025-01-01",
    "to": "2025-06-01",
    "group_by": "month",
    "convert_currency": "usd",
    "timezone": "UTC"
  }
}
```

### Filtering

Use `reporting_category` to scope to a predefined set of line categories (e.g. only income-related activity):

```bash theme={null}
curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&reporting_category=gross_income" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

Use `grouping` to narrow to specific groupings (e.g. only payments and refunds):

```bash theme={null}
curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&grouping[]=payments&grouping[]=refunds" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

Use `line_category` for the most granular filtering:

```bash theme={null}
curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&line_category[]=payment_gross&line_category[]=payment_refund" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

All three filters can be combined — they are applied in order: `reporting_category` first, then `grouping`, then `line_category`.

### Global queries

Pass `account_id=global` to query aggregated data across all wallets. This requires admin access.

```bash theme={null}
curl "https://api.whop.com/api/v1/stats/time_series?resource_type=wallet&account_id=global&from=2025-01-01&to=2025-06-01&group_by=month&convert_currency=usd" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

Global queries omit `wallet_id` from the response metadata since data spans all wallets.

### Currency handling

There are two separate currency controls: **filter** and **convert**.

**Filter** — `currency` restricts rows to a single currency:

```bash theme={null}
curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&currency=usd" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

**Convert** — `convert_currency` converts all amounts to a target currency using historical exchange rates, collapsing multi-currency rows into one per period:

```bash theme={null}
curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&convert_currency=usd" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

When neither is set, rows include a `currency` field and you may get multiple rows per period (one per currency):

```json theme={null}
{
  "data": [
    { "period": "2025-01-01", "currency": "usd", "amount": 14550.35, "line_count": 300 },
    { "period": "2025-01-01", "currency": "eur", "amount": 3200.00, "line_count": 42 }
  ]
}
```

You can combine both: `currency=eur&convert_currency=usd` filters to EUR rows then converts them to USD.

### Errors

| Status | Cause                                                                                        |
| ------ | -------------------------------------------------------------------------------------------- |
| 400    | Missing or invalid parameters (including missing `resource_type`)                            |
| 401    | Missing or invalid API key                                                                   |
| 403    | API key lacks `company:balance:read` permission, or `account_id=global` without admin access |


# Push notifications
Source: https://docs.whop.com/developer/guides/notifications

Send push notifications to users in your app, scoped by experience or company.

Send push notifications to users in your app. Notifications appear in the Whop mobile app and web interface.

## Pick your notification type

|                              | Experience notification                        | Company notification                            |
| ---------------------------- | ---------------------------------------------- | ----------------------------------------------- |
| **Audience**                 | Users with access to an experience             | Team members of a company                       |
| **Best for**                 | Customer-facing apps (alerts, social, fitness) | Dashboard apps (admin actions, reports, alerts) |
| **Required keying field**    | `experience_id`                                | `company_id`                                    |
| **Filter to specific users** | `user_ids` (must have experience access)       | `user_ids` (must be team members)               |

<Info>
  Sending notifications requires the `notification:create` permission. Add it from the [Permissions guide](/developer/guides/permissions). The experience must belong to your app, or the company must have your app installed.
</Info>

## Send to everyone in an experience

Send notifications to all users with access to an experience:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await client.notifications.create({
    experience_id: 'exp_xxxxxxxxxxxxxx',
    title: 'New Feature Available',
    subtitle: 'Check it out now',
    content: 'We just released a new feature that helps you track your progress better.',
  });

  console.log(result.success); // true

  ```

  ```python Python theme={null}
  result = client.notifications.create(
      experience_id="exp_xxxxxxxxxxxxxx",
      title="New Feature Available",
      subtitle="Check it out now",
      content="We just released a new feature that helps you track your progress better.",
  )

  print(result.success)  # True
  ```

  ```ruby Ruby theme={null}
  result = client.notifications.create(
    experience_id: "exp_xxxxxxxxxxxxxx",
    title: "New Feature Available",
    subtitle: "Check it out now",
    content: "We just released a new feature that helps you track your progress better."
  )

  puts result.success  # true
  ```
</CodeGroup>

<Note>
  **Example use case:** If you're building a fitness tracking app, you could
  send a notification to everyone when a new workout program is released, or
  send targeted notifications to users who completed a 7-day streak to celebrate
  their achievement.
</Note>

## Send to specific users

Use the `user_ids` parameter to send notifications only to specific users. These users must also have access to the experience.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await client.notifications.create({
    experience_id: 'exp_xxxxxxxxxxxxxx',
    title: 'Complete your daily workout',
    content: 'You\'re 50% of the way to your goal. Finish strong!',
    user_ids: ['user_abc123', 'user_def456'],
  });
  ```

  ```python Python theme={null}
  result = client.notifications.create(
      experience_id="exp_xxxxxxxxxxxxxx",
      title="Complete your daily workout",
      content="You're 50% of the way to your goal. Finish strong!",
      user_ids=["user_abc123", "user_def456"],
  )
  ```

  ```ruby Ruby theme={null}
  result = client.notifications.create(
    experience_id: "exp_xxxxxxxxxxxxxx",
    title: "Complete your daily workout",
    content: "You're 50% of the way to your goal. Finish strong!",
    user_ids: ["user_abc123", "user_def456"]
  )
  ```
</CodeGroup>

## Send to company team members

Send notifications to all team members of a company (dashboard app users):

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await client.notifications.create({
    company_id: 'biz_xxxxxxxxxxxxxx',
    title: 'Monthly Report Ready',
    subtitle: 'October 2024',
    content: 'Your monthly analytics report has been generated and is ready to view.',
  });
  ```

  ```python Python theme={null}
  result = client.notifications.create(
      company_id="biz_xxxxxxxxxxxxxx",
      title="Monthly Report Ready",
      subtitle="October 2024",
      content="Your monthly analytics report has been generated and is ready to view.",
  )
  ```

  ```ruby Ruby theme={null}
  result = client.notifications.create(
    company_id: "biz_xxxxxxxxxxxxxx",
    title: "Monthly Report Ready",
    subtitle: "October 2024",
    content: "Your monthly analytics report has been generated and is ready to view."
  )
  ```
</CodeGroup>

<Note>
  **Example use case:** If you're building a tax filing dashboard, you could
  send notifications to all team members when a filing deadline is approaching,
  or send targeted reminders to specific users who still need to complete steps
  in the filing process.
</Note>

## Send to specific team members

Use the `user_ids` parameter to send notifications only to specific team members. These users must also be team members of the company.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await client.notifications.create({
    company_id: 'biz_xxxxxxxxxxxxxx',
    title: 'Action Required',
    content: 'Please review and approve the pending invoices.',
    user_ids: ['user_manager1', 'user_manager2'],
  });
  ```

  ```python Python theme={null}
  result = client.notifications.create(
      company_id="biz_xxxxxxxxxxxxxx",
      title="Action Required",
      content="Please review and approve the pending invoices.",
      user_ids=["user_manager1", "user_manager2"],
  )
  ```

  ```ruby Ruby theme={null}
  result = client.notifications.create(
    company_id: "biz_xxxxxxxxxxxxxx",
    title: "Action Required",
    content: "Please review and approve the pending invoices.",
    user_ids: ["user_manager1", "user_manager2"]
  )
  ```
</CodeGroup>

## Deep link with rest\_path

Direct users to specific pages in your app when they tap a notification using the `rest_path` parameter.

## Setting up your app path

First, configure your app path in the dashboard to handle the dynamic route parameter:

1. Go to your app settings in the [developer dashboard](https://whop.com/dashboard/developer)
2. In the hosting section, update your "App path" to include `[restPath]`

**For experience apps:**

```
/experiences/[experienceId]/[restPath]
```

**For dashboard apps:**

```
/companies/[companyId]/[restPath]
```

## Sending notifications with deep links

Add the `rest_path` parameter to your notification. This will be appended to your app's base URL.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Experience app: Direct to a specific workout
  await client.notifications.create({
    experience_id: 'exp_xxxxxxxxxxxxxx',
    title: 'Today\'s Recommended Workout',
    content: 'Based on your progress, we recommend this HIIT session.',
    rest_path: '/workouts/hiit-advanced-1',
  });

  // Dashboard app: Direct to a specific report
  await client.notifications.create({
    company_id: 'biz_xxxxxxxxxxxxxx',
    title: 'Unusual Activity Detected',
    content: 'Review the flagged transactions in your dashboard.',
    rest_path: '/reports/flagged-transactions',
  });

  ```

  ```python Python theme={null}
  # Experience app: Direct to a specific workout
  client.notifications.create(
      experience_id="exp_xxxxxxxxxxxxxx",
      title="Today's Recommended Workout",
      content="Based on your progress, we recommend this HIIT session.",
      rest_path="/workouts/hiit-advanced-1",
  )

  # Dashboard app: Direct to a specific report
  client.notifications.create(
      company_id="biz_xxxxxxxxxxxxxx",
      title="Unusual Activity Detected",
      content="Review the flagged transactions in your dashboard.",
      rest_path="/reports/flagged-transactions",
  )
  ```

  ```ruby Ruby theme={null}
  # Experience app: Direct to a specific workout
  client.notifications.create(
    experience_id: "exp_xxxxxxxxxxxxxx",
    title: "Today's Recommended Workout",
    content: "Based on your progress, we recommend this HIIT session.",
    rest_path: "/workouts/hiit-advanced-1"
  )

  # Dashboard app: Direct to a specific report
  client.notifications.create(
    company_id: "biz_xxxxxxxxxxxxxx",
    title: "Unusual Activity Detected",
    content: "Review the flagged transactions in your dashboard.",
    rest_path: "/reports/flagged-transactions"
  )
  ```
</CodeGroup>

## Handling the route in your app

When a user taps the notification, they'll be directed to the full URL constructed from your app path and the `rest_path`.

**Example for experience app:**

If your app is hosted at `https://your-app.com` and you send:

```typescript theme={null}
rest_path: "/posts/post_123";
```

The user will open:

```
https://your-app.com/experiences/exp_xxxxxxxxxxxxxx/posts/post_123
```

**In Next.js**, create a file at:

```
app/experiences/[experienceId]/posts/[postId]/page.tsx
```

**In Express**, handle the route:

```typescript theme={null}
app.get("/experiences/:experienceId/posts/:postId", (req, res) => {
	// Handle the notification deep link
});
```

You can also use query parameters:

```typescript theme={null}
rest_path: "?action=review&id=123";
```

## Custom notification icons

By default, notifications display your experience or company avatar. Customize the icon by providing a Whop user ID whose profile picture will be used.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.notifications.create({
    experience_id: 'exp_xxxxxxxxxxxxxx',
    title: 'New Comment',
    content: 'Sarah replied to your post: "Great progress!"',
    icon_user_id: 'user_sarah123',
    rest_path: '/posts/my-post-123',
  });
  ```

  ```python Python theme={null}
  client.notifications.create(
      experience_id="exp_xxxxxxxxxxxxxx",
      title="New Comment",
      content='Sarah replied to your post: "Great progress!"',
      icon_user_id="user_sarah123",
      rest_path="/posts/my-post-123",
  )
  ```

  ```ruby Ruby theme={null}
  client.notifications.create(
    experience_id: "exp_xxxxxxxxxxxxxx",
    title: "New Comment",
    content: 'Sarah replied to your post: "Great progress!"',
    icon_user_id: "user_sarah123",
    rest_path: "/posts/my-post-123"
  )
  ```
</CodeGroup>

This is useful for social features where you want to show who performed an action (commented, liked, followed, etc).

## Next steps

<CardGroup>
  <Card title="Build a chat bot" href="/developer/guides/chat">
    Pair notifications with in-app messages so users get pinged regardless of where they are.
  </Card>

  <Card title="Listen to webhooks" href="/developer/guides/webhooks">
    Trigger notifications off `payment.succeeded`, `membership.activated`, and other server events.
  </Card>

  <Card title="Forums" href="/developer/guides/forums">
    Notify users when new posts or comments land in your forum experience.
  </Card>

  <Card title="Request permissions" href="/developer/guides/permissions">
    Confirm your app's permission setup so notifications send successfully.
  </Card>
</CardGroup>


# OAuth
Source: https://docs.whop.com/developer/guides/oauth

Add "Sign in with Whop" to your site with OAuth 2.1 + PKCE.

Use OAuth 2.1 + PKCE with OpenID Connect (OIDC) to let users sign in with Whop on your website or app. The returned access tokens let you access data and act on behalf of those users.

<Info>OAuth endpoints live at `https://api.whop.com/oauth/`.</Info>

## Step 1: Create your OAuth app

<Tabs>
  <Tab title="API">
    Use the [Create App](/api-reference/apps/create-app) endpoint to create an OAuth app programmatically:

    ```typescript theme={null}
    import Whop from "@whop/sdk";

    const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

    const app = await client.apps.create({
      name: "My App",
      redirect_uris: [
        "http://localhost:3000/api/auth/callback/whop",
        "https://myapp.com/api/auth/callback/whop"
      ],
    });

    console.log(app.id);            // NEXT_PUBLIC_WHOP_APP_ID
    console.log(app.client_secret); // WHOP_CLIENT_SECRET
    ```

    Update redirect URIs later with the [Update App](/api-reference/apps/update-app) endpoint.
  </Tab>

  <Tab title="Dashboard">
    <Steps>
      <Step title="Create or select your app">
        Go to the [Developer Dashboard](https://whop.com/dashboard/developer), create a new app or select an existing one.
      </Step>

      <Step title="Add redirect URIs">
        In the OAuth section, add every redirect URI you plan to use (exact match required).
      </Step>

      <Step title="Copy credentials">
        Copy your `client_id` (looks like `app_xxxxx`) and `client_secret`.
      </Step>

      <Step title="Select your scopes">
        Select your available OAuth scopes from the "View available scopes" button and select only the ones you need.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Step 2: Send users to authorize

In your web or mobile client, use PKCE to securely redirect users to Whop's OAuth flow.

```typescript expandable theme={null}
const STORAGE_KEY = "whop_oauth_pkce";

function base64url(bytes: Uint8Array) {
	return btoa(String.fromCharCode(...bytes)).replace(
		/[+/=]/g,
		(c) => ({ "+": "-", "/": "_", "=": "" })[c]!,
	);
}

function randomString(len: number) {
	return base64url(crypto.getRandomValues(new Uint8Array(len)));
}

async function sha256(str: string) {
	return base64url(
		new Uint8Array(
			await crypto.subtle.digest("SHA-256", new TextEncoder().encode(str)),
		),
	);
}

async function startWhopOAuth(
	clientId: string,
	redirectUri: string,
	scope = "openid profile email",
	companyId?: string,
) {
	const pkce = {
		codeVerifier: randomString(32),
		state: randomString(16),
		nonce: randomString(16),
	};
	sessionStorage.setItem(STORAGE_KEY, JSON.stringify(pkce));

	const params = new URLSearchParams({
		response_type: "code",
		client_id: clientId,
		redirect_uri: redirectUri,
		scope,
		state: pkce.state,
		nonce: pkce.nonce,
		code_challenge: await sha256(pkce.codeVerifier),
		code_challenge_method: "S256",
		...(companyId && { company_id: companyId }),
	});

	window.location.href = `https://api.whop.com/oauth/authorize?${params}`;
}
```

Call `startWhopOAuth` to redirect the user:

```typescript theme={null}
await startWhopOAuth(
	"app_xxxxxxxxx",
	"https://yourapp.com/oauth/callback",
	"openid profile email", // optionally specify more custom scopes here
	"biz_xxxxx", // optionally specify a scoped company id here
);
```

If the user is not logged in, Whop will prompt for login, then show the consent screen.
If the user has already approved your application for the requested scopes,
they will be automatically redirected back without needing to confirm twice.

<Note>
  If you provide `companyId`, tokens are company-scoped for a specific user,
  meaning you will only have access to resources that that particular user can
  control on the specified Whop company.
</Note>

## Step 3: Handle the callback and exchange the code

Whop redirects back to your `redirect_uri` with `code` and `state`. Use this function to verify the state, exchange the code for tokens, and retrieve credentials:

```typescript expandable theme={null}
const STORAGE_KEY = "whop_oauth_pkce";

interface WhopTokens {
	access_token: string;
	refresh_token: string;
	id_token?: string; // only present if "openid" scope was requested
	token_type: string;
	expires_in: number;
	obtained_at: number; // we add this client-side for refresh logic
}

async function handleWhopCallback(
	clientId: string,
	redirectUri: string,
): Promise<WhopTokens> {
	const params = new URLSearchParams(window.location.search);
	const [code, returnedState, error] = [
		params.get("code"),
		params.get("state"),
		params.get("error"),
	];
	if (error)
		throw new Error(
			`OAuth error: ${error} - ${params.get("error_description") || ""}`,
		);

	const stored = JSON.parse(sessionStorage.getItem(STORAGE_KEY) || "null");
	sessionStorage.removeItem(STORAGE_KEY);
	if (!stored || returnedState !== stored.state)
		throw new Error("Invalid state - possible CSRF");

	const res = await fetch("https://api.whop.com/oauth/token", {
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify({
			grant_type: "authorization_code",
			code,
			redirect_uri: redirectUri,
			client_id: clientId,
			code_verifier: stored.codeVerifier,
		}),
	});

	if (!res.ok) {
		const err = await res.json().catch(() => ({}));
		throw new Error(
			`Token exchange failed: ${err.error_description || res.status}`,
		);
	}

	const tokens = await res.json();
	return { ...tokens, obtained_at: Date.now() };
}

function storeTokens(tokens: WhopTokens) {
	document.cookie = `whop_tokens=${encodeURIComponent(JSON.stringify(tokens))}; path=/; max-age=${60 * 60 * 24 * 30}; secure; samesite=strict`;
}

function getTokens(): WhopTokens | null {
	const match = document.cookie.match(/whop_tokens=([^;]+)/);
	return match ? JSON.parse(decodeURIComponent(match[1])) : null;
}

function clearTokens() {
	document.cookie = "whop_tokens=; path=/; max-age=0";
}
```

On your callback page:

```typescript theme={null}
const tokens = await handleWhopCallback(
	"app_xxxxxxxxx",
	"https://yourapp.com/oauth/callback",
);
storeTokens(tokens);
```

## Step 4: Use the tokens

Initialize the Whop SDK with the user's access token:

```typescript theme={null}
import Whop from "@whop/sdk";

const tokens = getTokens();

const client = new Whop({
	apiKey: tokens.access_token,
});
```

View our [API Reference](/api-reference) to see all available endpoints.

## Step 5: Refresh tokens

Access tokens expire after 1 hour. Use the refresh token to get new credentials:

```typescript expandable theme={null}
async function refreshTokens(
	clientId: string,
	companyId?: string,
): Promise<WhopTokens> {
	const tokens = getTokens();
	if (!tokens?.refresh_token) throw new Error("No refresh token available");

	const res = await fetch("https://api.whop.com/oauth/token", {
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify({
			grant_type: "refresh_token",
			refresh_token: tokens.refresh_token,
			client_id: clientId,
			...(companyId && { company_id: companyId }),
		}),
	});

	if (!res.ok) {
		const error = await res.json().catch(() => ({}));
		if (res.status === 401 || error.error === "invalid_grant") {
			clearTokens();
			throw new Error("Session expired - please log in again");
		}
		throw new Error(
			`Token refresh failed: ${error.error_description || res.status}`,
		);
	}

	const newTokens = await res.json();
	const stored = { ...newTokens, obtained_at: Date.now() };
	storeTokens(stored);
	return stored;
}

async function getValidAccessToken(clientId: string): Promise<string> {
	const tokens = getTokens();
	if (!tokens) throw new Error("Not logged in");

	const expiresAt = tokens.obtained_at + tokens.expires_in * 1000;
	const needsRefresh = Date.now() > expiresAt - 5 * 60 * 1000; // 5 min buffer

	if (needsRefresh) {
		const refreshed = await refreshTokens(clientId);
		return refreshed.access_token;
	}

	return tokens.access_token;
}
```

Usage:

```typescript theme={null}
const accessToken = await getValidAccessToken("app_xxxxxxxxx");
```

<Note>
  Refresh tokens rotate on each use. Always store the new tokens returned from
  the refresh endpoint. If you provided `company_id` during authorization, you
  must provide the same `company_id` when refreshing.
</Note>

## Step 6: Userinfo and revoke

### Get user info

Fetch the authenticated user's profile using the userinfo endpoint:

```typescript theme={null}
interface WhopUserInfo {
	sub: string; // user tag (e.g. "user_xxxxx")
	name?: string; // requires "profile" scope
	preferred_username?: string; // requires "profile" scope
	picture?: string; // requires "profile" scope
	email?: string; // requires "email" scope
	email_verified?: boolean; // requires "email" scope
}

async function getUserInfo(accessToken: string): Promise<WhopUserInfo> {
	const res = await fetch("https://api.whop.com/oauth/userinfo", {
		headers: { Authorization: `Bearer ${accessToken}` },
	});
	if (!res.ok) throw new Error(`Failed to fetch user info: ${res.status}`);
	return res.json();
}
```

<Note>
  The fields returned depend on the scopes granted. `openid` is required,
  `profile` adds name/username/picture, `email` adds email fields.
</Note>

### Revoke tokens on logout

When a user logs out, revoke their refresh token. Access tokens expire after 1 hour and cannot be server-revoked.

```typescript theme={null}
async function logout(clientId: string) {
	const tokens = getTokens();
	if (tokens?.refresh_token) {
		await fetch("https://api.whop.com/oauth/revoke", {
			method: "POST",
			headers: { "Content-Type": "application/json" },
			body: JSON.stringify({
				token: tokens.refresh_token,
				client_id: clientId,
			}),
		});
	}
	clearTokens();
}
```

<Warning>
  Always revoke tokens when users log out. This invalidates the refresh token
  immediately, preventing unauthorized access even if the token was compromised.
</Warning>

## Error handling

OAuth errors follow the standard format:

```json theme={null}
{
	"error": "invalid_grant",
	"error_description": "Authorization code has expired"
}
```

Common error codes:

* `invalid_request`: missing or invalid parameter.
* `invalid_grant`: code or token expired or revoked.
* `invalid_client`: unknown `client_id`.
* `insufficient_scope`: token doesn't have the required scope.
* `rate_limit_exceeded`: too many requests (check the `Retry-After` header).

## Next steps

<CardGroup>
  <Card title="API reference" href="/api-reference">
    Every endpoint a granted access token can call.
  </Card>

  <Card title="Accept payments" href="/developer/guides/accept-payments">
    Pair sign-in with checkout for end-to-end purchase flows.
  </Card>

  <Card title="Listen to webhooks" href="/developer/guides/webhooks">
    React to payment, membership, and entry events server-side.
  </Card>

  <Card title="Request permissions" href="/developer/guides/permissions">
    Configure the OAuth scopes your app actually needs.
  </Card>
</CardGroup>


# Permissions
Source: https://docs.whop.com/developer/guides/permissions

Configure the permissions your app needs and request approval from the creators who install it.

Apps use permissions to access company data and act on behalf of users. Every API call requires the matching permission. You declare the ones you need in your app's settings, creators approve them at install, and your SDK calls succeed only when those permissions are granted.

<Tip>
  Find the required permissions for any endpoint in the API reference. Each operation page lists them under "Required permissions."
</Tip>

## Required vs optional permissions

You can mark each permission as required or optional. The choice changes the install experience for creators.

| Type         | Creator can disable at install? | Use when                                                                   |
| ------------ | ------------------------------- | -------------------------------------------------------------------------- |
| **Required** | No                              | The app cannot function without this scope                                 |
| **Optional** | Yes                             | The scope powers a side feature, not the core flow (e.g. analytics opt-in) |

Optional permissions are good for opt-in functionality. If a creator declines an optional permission, your app should still work, just without that feature.

## Set up permissions

<Warning>
  The permissions flow is required even for testing on your own company. Same flow on install or self-test, so you catch missing scopes early.
</Warning>

<Steps>
  <Step title="Open your app's permissions tab">
    1. Go to the [Developer dashboard](https://whop.com/dashboard/developer).
    2. Select or create an app.
    3. Click the **Permissions** tab.

    <Frame>
      <img alt="Permissions Settings" />
    </Frame>
  </Step>

  <Step title="Add the permissions you need">
    Click **Add permissions**, select what your app needs, and confirm.

    Cross-reference the API endpoints you plan to call and add every permission they require.
  </Step>

  <Step title="Configure each permission">
    For each one:

    1. Write a short justification explaining why the app needs it. Creators see this at install.
    2. Mark it **required** or **optional**.

    <Frame>
      <img alt="Permissions Justification" />
    </Frame>
  </Step>

  <Step title="Save">
    <Frame>
      <img alt="Save Permissions Settings" />
    </Frame>
  </Step>

  <Step title="Install on a test company">
    Visit your direct install link: `https://whop.com/apps/app_xxxxxxxxx/install`.

    Pick a company, review the permission prompt, and approve.

    <Frame>
      <img alt="Permissions Prompt" />
    </Frame>
  </Step>
</Steps>

## Update permissions later

Permissions can change as the app evolves. When you add a new one:

* Existing installs see a **Re-approve** button next to your app.
* API calls that need the new permission fail until each creator re-approves.

<Note>
  When you add a permission, re-approve on your own test company too. New scopes don't carry over until you accept them in [Authorized apps](https://whop.com/dashboard/settings/authorized-apps).
</Note>

Creators can manage granted permissions any time at `Dashboard → Settings → Authorized apps`.

<video />

## FAQ

<AccordionGroup>
  <Accordion title="How many permissions can I request?">
    Up to 100 per app.
  </Accordion>

  <Accordion title="How do I find the right permissions for an endpoint?">
    Each endpoint in the [API reference](/api-reference/payments/list-payments) lists its required permissions inline.

    <Frame>
      <img alt="SDK Reference Permissions" />
    </Frame>
  </Accordion>

  <Accordion title="Can I request additional permissions afterwards?">
    Yes. You can request additional permissions and the creator will be asked to re-approve them.

    <Note>
      Keep in mind that until the permissions are re-approved, API requests requiring the **newly requested** permissions will fail. Make sure to handle these errors gracefully in your code.
    </Note>

    <Warning>
      When developing your app, make sure you re-approve the permissions yourself in your [Authorized apps](https://whop.com/dashboard/settings/authorized-apps) settings.

      See [Configure your permissions](/developer/guides/permissions#updating-your-permissions) for more information.
    </Warning>
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Authentication" href="/developer/guides/authentication">
    Verify the user behind a request and check their access level.
  </Card>

  <Card title="Listen to webhooks" href="/developer/guides/webhooks">
    Receive payment, membership, and entry events. Webhooks need their own `webhook_receive:*` scopes.
  </Card>

  <Card title="Build app views" href="/developer/guides/app-views">
    Set up dashboard views, experiences, and discover listings.
  </Card>

  <Card title="Run a local dev proxy" href="/developer/guides/dev-proxy">
    Match the production iframe + cookie setup on localhost.
  </Card>
</CardGroup>


# Install the Whop pixel
Source: https://docs.whop.com/developer/guides/pixel

Add the whop.track snippet to your funnel to measure page views, identify visitors, and attribute conversions from first-party data.

The Whop pixel is a lightweight JavaScript snippet you add to your website. It measures page views, links visitors to their purchases, and attributes conversions back to your ads — using Whop's first-party payment data instead of third-party cookies. Once installed, everything shows up live in your [pixel dashboard](https://whop.com/dashboard/biz_xxxxxxxxxxxxx/pixel).

<Note>
  You only need your **company ID** (`biz_xxxxxxxxxxxxx`) to install the pixel. Find it in the URL of your dashboard, or on the pixel page at `https://whop.com/dashboard/{biz_id}/pixel`.
</Note>

## Install the snippet

Paste this snippet inside the `<head>` of **every page** in your funnel — landing pages, advertorials, checkouts, and thank-you pages, not just your homepage. Replace `biz_xxxxxxxxxxxxx` with your own company ID.

```html Pixel snippet theme={null}
<script>
!function(w,d,s,u,n,a,b){if(w[n])return;a=w[n]={q:[],t:+new Date,s:[],o:u,track:function(){a.q.push([+new Date].concat([].slice.call(arguments)))},setScope:function(){a.s=[].slice.call(arguments).filter(function(x){return typeof x==="string"});a.q.push([+new Date,"setScope"].concat(a.s))},scope:function(){var c=[].slice.call(arguments);return{track:function(){a.q.push([+new Date].concat([].slice.call(arguments)).concat([{__scope:c}]))}}}};b=d.createElement(s);b.async=1;b.src=u+"/s.js";d.getElementsByTagName(s)[0].parentNode.insertBefore(b,d.getElementsByTagName(s)[0])}(window,document,"script","https://t.whop.tw","whop");
whop.setScope("biz_xxxxxxxxxxxxx");
whop.track("page");
</script>
```

<Tip>
  If your platform (Shopify, Webflow, Framer, WordPress, etc.) has a dedicated field for custom header or `<head>` code, paste the snippet there so it ships on every page template automatically.
</Tip>

<Note>
  For most brands — especially ecommerce stores that send traffic to Whop checkout — this snippet is all you need. Whop automatically tracks page views, checkout views, purchases, subscriptions, and trials. You only need extra event code if you want to track steps Whop cannot see, like a lead form on your own site.
</Note>

## Verify the install

Open `https://whop.com/dashboard/{biz_id}/pixel` and watch **Step 1 — Install the pixel**. Page views appear within about a minute of the first visit, and the status turns green once data is flowing. Domains the pixel reports from are listed there too.

## Track events

Most brands can skip this section. Add extra `whop.track` calls only when your funnel has an important step outside Whop checkout — for example a lead form, call booking, application, or quiz.

The most common setup is to fire `whop.track("lead")` either:

* when the lead form submits successfully
* on the thank-you page or confirmation page the visitor sees after submitting

```javascript Tracking events theme={null}
whop.track("lead");                                      // a standard event
whop.track("schedule", { value: 50, currency: "USD" });  // optionally with a value
whop.track("quiz_completed");                            // or your own event name
```

### Standard event names

Use these names for common funnel moments. Each one optionally accepts a `value` (number) and `currency` (ISO 4217 code).

| Event                   | When to fire it                                    |
| ----------------------- | -------------------------------------------------- |
| `lead`                  | A visitor submits contact info or an opt-in form   |
| `schedule`              | A call or appointment is booked                    |
| `submit_application`    | An application is submitted                        |
| `contact`               | A visitor starts a conversation or contact request |
| `complete_registration` | A signup or registration finishes                  |
| `view_content`          | A key page or piece of content is viewed           |
| `add_to_cart`           | An item is added to a cart                         |

### Your own event names

Anything else your funnel does can be tracked under a name you choose — pass it as the event name. It shows up under that name in your ads reporting, and takes the same `value`, `currency`, and customer fields as a standard event.

```javascript Custom event theme={null}
whop.track("watched_vsl");
whop.track("quiz_completed", { value: 25, currency: "USD" });
```

Keep names short, stable, and reuse a small set. Names are stored up to 250 characters, but only names under \~34 characters are forwarded to Meta as a custom conversion — longer ones still appear in Whop reporting.

<Note>
  The older two-field form, `whop.track("custom", { name: "watched_vsl" })`, still works and reports identically, so existing installs need no changes.
</Note>

<Tip>
  **Where to put the tracking call depends on what happens after the action.**

  * **The action does not redirect** (e.g. a form that submits in place and shows an inline success message) — fire the event in the action's success handler, like the form's `onSubmit` callback, after it succeeds:

  ```javascript Track on submit (no redirect) theme={null}
  form.addEventListener("submit", async (e) => {
  	e.preventDefault();
  	await submitForm();
  	whop.track("watched_vsl");
  });
  ```

  * **The action redirects** (e.g. a form that sends the visitor to a new page on submit) — fire the event on the page they land on, like the thank-you or confirmation page. Just make sure the pixel snippet is installed on that page too.
</Tip>

### Attach customer fields

You usually do **not** need to attach extra customer fields. Whop can often match events from the pixel, checkout activity, browser signals, and first-party payment data automatically.

If you already have customer details available when an event fires, you can attach them for extra matching coverage. It does not hurt to include them, and it can improve matching. These fields can be attached to any event type, and you can send only the fields you have.

```javascript Lead with customer fields theme={null}
whop.track("lead", {
  email: "visitor@example.com",
  first_name: "Jane",
  last_name: "Doe",
  name: "Jane Doe",
  phone: "+15551234567",
  external_id: "customer_123",
  city: "New York",
  state: "NY",
  postal_code: "10001",
  country: "US",
});
```

| Field         | Description                  |
| ------------- | ---------------------------- |
| `email`       | Visitor's email address      |
| `first_name`  | Visitor's first name         |
| `last_name`   | Visitor's last name          |
| `name`        | Visitor's full display name  |
| `phone`       | Visitor's phone number       |
| `external_id` | Your own user/customer ID    |
| `city`        | Visitor's city               |
| `state`       | Visitor's state or region    |
| `postal_code` | Visitor's postal or ZIP code |
| `country`     | Visitor's country            |

<Note>
  **Don't track purchases, subscriptions, or trials.** Whop records every checkout view, purchase, subscription, and trial start server-side with zero configuration, and the pixel will not accept duplicates. Only send the events Whop cannot see, like leads or bookings on your own infrastructure.
</Note>

## Send events from your server

If you want to send events from your backend instead of (or in addition to) the browser — ad blockers can't touch server-side events, and they're more reliable for high-value conversions — use the [Events API](/api-reference/beta/events/create-event). Attach as much customer information as you have so the event attributes correctly.

<Card title="Events API reference" href="/api-reference/beta/events/create-event" icon="server">
  Create conversion events from your server with an API key. Full endpoint, fields, and examples.
</Card>

## Advanced: multiple companies on one page

Most brands can ignore this. It only applies if the same website or landing page is intentionally tracking events for more than one Whop business.

In that case, set a default scope with multiple IDs, or scope an individual call.

```javascript Scoping theme={null}
// Default scope for every subsequent event
whop.setScope("biz_companyA", "biz_companyB");
whop.track("lead");

// Or scope a single call
whop.scope("biz_companyA").track("lead");
```

## Next steps

<CardGroup>
  <Card title="Events API" href="/api-reference/beta/events/create-event">
    Send conversions from your server when browser tracking is not enough — ad blockers cannot touch them.
  </Card>

  <Card title="Whop Ads & the Whop Pixel" href="/manage-your-business/growth-marketing/ads">
    How first-party attribution powers ad measurement.
  </Card>

  <Card title="Tracking integrations" href="/manage-your-business/growth-marketing/tracking-integrations">
    Pipe Whop sales data into Meta, Google, Hyros, and other platforms.
  </Card>

  <Card title="Tracking links" href="/manage-your-business/growth-marketing/tracking-links">
    Build branded links to attribute traffic and conversions across channels.
  </Card>
</CardGroup>


# React Native
Source: https://docs.whop.com/developer/guides/react-native

Build cross-platform mobile and web apps for Whop using React Native.

Build native iOS, Android, and web experiences for Whop using a single React Native codebase. Your apps run directly inside the Whop mobile app and can access native platform features.

## How it Works

Whop React Native apps are embedded experiences that run on multiple platforms:

* **Mobile (iOS/Android)**: Apps run natively inside the Whop mobile app with full platform integration
* **Web**: Apps run in the browser with automatic fallbacks for platform-specific features
* **Universal Code**: Write once, deploy everywhere with platform-specific optimizations

Your app receives authenticated user context and can make API calls through the Whop SDK. The build system automatically handles platform-specific bundling using Metro for mobile and esbuild for web.

***

## Getting Started

### System Requirements

Before you begin, make sure your system meets the following requirements:

* [Node.js 22](https://nodejs.org/) or later
* [pnpm 9.15](https://pnpm.io/) or later

To check, run `node -v` and `pnpm -v`.

### Create Your App

Create a new Whop React Native app using the CLI:

```bash theme={null}
pnpm create @whop/react-native@latest
```

This sets up a new project with the following structure:

```
my-app/
├── src/
│   └── views/
│       ├── experience-view.tsx    # Experience view
│       ├── dashboard-view.tsx     # Company dashboard view
│       └── discover-view.tsx      # Discovery/marketplace view (optional)
├── .env.local                     # Environment variables
├── package.json
└── babel.config.js
```

### Configure Environment Variables

Create a `.env.local` file in the root directory:

```env theme={null}
WHOP_API_KEY=your_api_key
NEXT_PUBLIC_WHOP_APP_ID=your_app_id
NEXT_PUBLIC_WHOP_AGENT_USER_ID=your_agent_user_id
NEXT_PUBLIC_WHOP_COMPANY_ID=your_company_id
```

Get these credentials from the [Whop Developer Dashboard](https://whop.com/dashboard/developer):

1. Go to the Whop Developer Dashboard
2. Create a new app or select an existing one
3. Copy the environment variables from the app settings

***

## Views

<Frame>
  <img alt="Project Structure" />
</Frame>

Whop apps use different "views" depending on where they're displayed. Each view receives authenticated context as props.

### Experience View

The main view for experience apps. This is where users interact with your app content.

```tsx theme={null}
// src/views/experience-view.tsx
import React from "react";
import { View, Text, ScrollView } from "react-native";
import type { ExperienceViewProps } from "@whop/react-native";

export function ExperienceView(props: ExperienceViewProps) {
	const { experienceId, companyId, currentUserId, path, params } = props;

	return (
		<ScrollView>
			<Text>Experience: {experienceId}</Text>
			<Text>User: {currentUserId}</Text>
		</ScrollView>
	);
}
```

**Props:**

* `experienceId` - The experience ID
* `companyId` - The company that owns this experience
* `currentUserId` - The authenticated user (or `null` if not logged in)
* `path` - Navigation path as array (e.g., `["courses", "123"]`)
* `params` - Query parameters as object

### Dashboard View

For company dashboard integrations where sellers manage their business.

```tsx theme={null}
// src/views/dashboard-view.tsx
import React from "react";
import { View, Text } from "react-native";
import type { DashboardViewProps } from "@whop/react-native";

export function DashboardView(props: DashboardViewProps) {
	const { companyId, currentUserId, path, params } = props;

	return (
		<View>
			<Text>Dashboard for company: {companyId}</Text>
		</View>
	);
}
```

**Props:**

* `companyId` - The company ID
* `currentUserId` - The authenticated user
* `path` - Navigation path as array
* `params` - Query parameters

### Discover View (Optional)

For marketplace/discovery experiences where users browse content.

```tsx theme={null}
// src/views/discover-view.tsx
import React from "react";
import type { DiscoverViewProps } from "@whop/react-native";

export function DiscoverView(props: DiscoverViewProps) {
	const { currentUserId, path, params } = props;

	// Your discovery UI
}
```

***

## Fetching Data

### Using the Whop SDK

<Warning>
  This still uses the deprecated SDK - we will update and changes this very soon
  to be 10x better!
</Warning>

The Whop SDK is available out of the box for client-side data fetching:

```tsx theme={null}
import { whopSdk } from "@whop/react-native";
import { useQuery } from "@tanstack/react-query";

export function UserProfile() {
	const { data: user } = useQuery({
		queryKey: ["user"],
		queryFn: () => whopSdk.users.getCurrentUser(),
	});

	return <Text>{user?.name}</Text>;
}
```

<Info>
  We recommend using [TanStack Query](https://tanstack.com/query/latest) for
  data fetching as it handles caching, loading states, and refetching
  automatically.
</Info>

<Warning>
  Some SDK operations are "server only" and must be called from your API. Check
  the [Quickstart](/developer/api/quickstart) for which methods require
  server-side execution.
</Warning>

### Making Authenticated API Requests

For server-side operations, create API routes and call them from your React Native app:

<Steps>
  <Step title="Set your API base URL">
    Configure your API origin in the [developer dashboard](https://whop.com/dashboard/developer) under "Base URL".

    <Frame>
      <img alt="Base URL" />
    </Frame>
  </Step>

  <Step title="Create an API endpoint">
    ```tsx theme={null}
    // app/api/user/route.ts
    import { whopSdk } from "@/lib/whop";

    export async function GET(request: Request) {
      const { userId } = await whopSdk.verifyUserToken(request.headers);
      const user = await whopSdk.users.getUser({ userId });

      return Response.json(user, { status: 200 });
    }
    ```

    See [Set up the API client](/developer/api/getting-started) for SDK configuration.
  </Step>

  <Step title="Call from React Native">
    Use the `apiOrigin` to make authenticated requests:

    ```tsx theme={null}
    import { useQuery } from "@tanstack/react-query";
    import { __internal_execSync } from "@whop/react-native";

    const { apiOrigin } = __internal_execSync("getAppApiOrigin", {});

    export function User() {
      const { data: user, isPending } = useQuery({
        queryKey: ["user"],
        queryFn: () => fetch(`${apiOrigin}/api/user`).then((res) => res.json()),
      });

      if (isPending) return <Text>Loading...</Text>;

      return <Text>{user?.name}</Text>;
    }
    ```
  </Step>
</Steps>

<Note>
  It's important to use the `apiOrigin` for authenticated requests. This ensures
  requests go through Whop's proxy with proper authentication headers.
</Note>

### Example: Check Access to an Experience

```tsx theme={null}
// Component
import { useQuery } from "@tanstack/react-query";
import { __internal_execSync } from "@whop/react-native";

const { apiOrigin } = __internal_execSync("getAppApiOrigin", {});

export function ProtectedContent({ experienceId }: { experienceId: string }) {
	const { data: access, isPending } = useQuery({
		queryKey: ["access", experienceId],
		queryFn: () =>
			fetch(`${apiOrigin}/api/access?experienceId=${experienceId}`).then(
				(res) => res.json(),
			),
	});

	if (isPending) return <Text>Loading...</Text>;
	if (!access?.hasAccess) return <Text>Access Denied</Text>;

	return <Text>Welcome! You have access.</Text>;
}
```

<Warning>
  This still uses the deprecated SDK - we will update and changes this very soon
  to be 10x better!
</Warning>

```tsx theme={null}
// app/api/access/route.ts
import { whopSdk } from "@/lib/whop";
import { NextRequest } from "next/server";

export async function GET(request: NextRequest) {
	const experienceId = request.nextUrl.searchParams.get("experienceId");
	if (!experienceId) {
		return new Response("Experience ID required", { status: 400 });
	}

	const { userId } = await whopSdk.verifyUserToken(request.headers);

	const access = await whopSdk.access.checkIfUserHasAccessToExperience({
		experienceId,
		userId,
	});

	return Response.json(access, { status: 200 });
}
```

***

## Styling

### Color Themes

React Native provides a `useColorScheme` hook to detect the device's color scheme. This works automatically in Whop apps:

```tsx theme={null}
import { useColorScheme } from "react-native";

export function ThemedView() {
	const colorScheme = useColorScheme();
	const backgroundColor = colorScheme === "dark" ? "#000" : "#fff";

	return <View style={{ backgroundColor }} />;
}
```

### Using Radix UI Colors

For a comprehensive color system with automatic dark mode, use the `useColors` hook pattern with Radix UI colors:

```bash theme={null}
pnpm add @radix-ui/colors
```

```tsx theme={null}
// hooks/use-colors.ts
import { useColorScheme } from "react-native";
import {
	gray,
	grayA,
	grayDark,
	grayDarkA,
	blue,
	blueA,
	blueDark,
	blueDarkA,
	red,
	redA,
	redDark,
	redDarkA,
	green,
	greenA,
	greenDark,
	greenDarkA,
	amber,
	amberA,
	amberDark,
	amberDarkA,
} from "@radix-ui/colors";

export function useColors() {
	const colorScheme = useColorScheme();
	const isDark = colorScheme === "dark";

	return {
		transparent: "transparent" as const,
		...(isDark ? grayDark : gray),
		...(isDark ? grayDarkA : grayA),
		...(isDark ? blueDark : blue),
		...(isDark ? blueDarkA : blueA),
		...(isDark ? redDark : red),
		...(isDark ? redDarkA : redA),
		...(isDark ? greenDark : green),
		...(isDark ? greenDarkA : greenA),
		...(isDark ? amberDark : amber),
		...(isDark ? amberDarkA : amberA),
	};
}
```

**Usage:**

```tsx theme={null}
export function StyledComponent() {
	const colors = useColors();

	return (
		<View style={{ backgroundColor: colors.gray1 }}>
			<Text style={{ color: colors.gray12 }}>Themed text</Text>
		</View>
	);
}
```

***

## Navigation

Use the internal navigation APIs to navigate between screens and present modals:

### Navigate to a New Screen

```tsx theme={null}
import { __internal_execSync } from "@whop/react-native";

function navigateToPage() {
	__internal_execSync("routerPush", {
		path: ["courses", "123"],
		params: { section: "intro" },
	});
}
```

The `path` and `params` are passed as props to your view component.

### Go Back

```tsx theme={null}
import { __internal_execSync } from "@whop/react-native";

function goBack() {
	__internal_execSync("routerPop", {});
}
```

### Present a Sheet/Modal

```tsx theme={null}
import { __internal_execSync } from "@whop/react-native";

function showModal() {
	__internal_execSync("routerPresentSheet", {
		path: ["modal", "settings"],
		params: {},
	});
}

function hideModal() {
	__internal_execSync("routerDismissSheet", {});
}
```

### Get Current Route

```tsx theme={null}
import { __internal_execSync } from "@whop/react-native";

const currentRoute = __internal_execSync("routerGetCurrent", {});
console.log(currentRoute.path); // ["courses", "123"]
console.log(currentRoute.params); // { section: "intro" }
```

***

## Platform-Specific Features

### Navigation Bar

Set the navigation bar title and description:

```tsx theme={null}
import { __internal_execSync } from "@whop/react-native";

__internal_execSync("setNavigationBarData", {
	title: "Course Details",
	description: "Learn React Native",
});
```

### Screen Orientation

Control the screen orientation:

```tsx theme={null}
import { __internal_execSync } from "@whop/react-native";

// Lock to portrait
__internal_execSync("setScreenOrientationMode", {
	targetScreenOrientationMode: "portrait",
});

// Lock to landscape
__internal_execSync("setScreenOrientationMode", {
	targetScreenOrientationMode: "landscape",
});

// Allow rotation
__internal_execSync("setScreenOrientationMode", {
	targetScreenOrientationMode: "rotate",
});
```

### Haptic Feedback

Provide haptic feedback on mobile devices:

```tsx theme={null}
import { Haptics } from "@whop/react-native";

async function triggerHaptic() {
	await Haptics.trigger("impactMedium", {
		enableVibrateFallback: true,
		ignoreAndroidSystemSettings: false,
	});
}
```

**Available haptic types:**

* `"selection"` - Light selection feedback
* `"impactLight"` | `"impactMedium"` | `"impactHeavy"` - Impact feedback
* `"notificationSuccess"` | `"notificationWarning"` | `"notificationError"` - Notification feedback

### Local Caching

Store data locally on the device:

```tsx theme={null}
import { __internal_execSync } from "@whop/react-native";

// Save data
__internal_execSync("cacheSet", {
	key: "user_preferences",
	data: JSON.stringify({ theme: "dark" }),
});

// Retrieve data
const result = __internal_execSync("cacheGet", {
	key: "user_preferences",
});
const preferences = JSON.parse(result.data || "{}");
```

### Host App Details

Get information about the Whop app:

```tsx theme={null}
import { __internal_execSync } from "@whop/react-native";

const hostDetails = __internal_execSync("getHostAppDetails", {});
console.log(hostDetails.platform); // "ios" | "android" | "web"
console.log(hostDetails.version); // "1.2.3"
console.log(hostDetails.build); // "123"
console.log(hostDetails.buildType); // "appstore" | "testflight" | "debug"
```

***

## In-App Purchases

Accept payments directly within your app:

```tsx theme={null}
import { __internal_execAsync } from "@whop/react-native";

async function handlePurchase(planId: string) {
	try {
		const result = await __internal_execAsync("inAppPurchase", {
			planId: planId,
			id: "optional-checkout-config-id",
		});

		console.log("Payment successful!");
		console.log("Session ID:", result.sessionId);
		console.log("Receipt ID:", result.receiptId);

		// Unlock content for user
	} catch (error) {
		console.error("Payment failed:", error);
	}
}
```

For a complete guide on accepting payments, see the [Accept payments documentation](/developer/guides/accept-payments).

***

## Using Third-Party Libraries

Most React Native libraries work out of the box. Here are the recommended versions for common libraries:

```json theme={null}
{
	"dependencies": {
		"@react-native-async-storage/async-storage": "2.1.0",
		"@react-native-community/netinfo": "12.0.3",
		"@shopify/flash-list": "1.7.2",
		"burnt": "0.13.2",
		"react-native-mmkv": "3.1.0",
		"react-native-safe-area-context": "5.5.2",
		"react-native-screens": "4.6.0",
		"react-native-svg": "15.12.0",
		"react-native-gesture-handler": "2.27.2",
		"react-native-reanimated": "3.18.0",
		"react-native-haptic-feedback": "2.3.3",
		"lottie-react-native": "7.3.2"
	}
}
```

<Warning>
  When adding new libraries, make sure they're compatible with React Native.
  Some npm packages are web-only and won't work on mobile platforms.
</Warning>

***

## Deploying

### Build and Deploy

The `ship` command builds your app for all platforms and uploads it as a development build:

```bash theme={null}
pnpm ship
```

Build for specific platforms:

```bash theme={null}
pnpm ship --ios           # iOS only
pnpm ship --android       # Android only
pnpm ship --web          # Web only
pnpm ship --ios --android # iOS and Android
```

<Info>
  The `ship` command deploys as a **development build**, which is safe to run on
  existing production apps. It won't affect your live users.
</Info>

### Development vs Production Builds

**Development Builds:**

* Deployed with `pnpm ship`
* Only visible when "dev mode" is enabled (shake phone)
* Safe to test without affecting production users
* Can be deployed anytime

**Production Builds:**

* Promoted from development builds via the dashboard
* Visible to all users
* Requires approval/review
* Should be thoroughly tested first

### Preview Your App

After deploying a development build, preview it on your device:

```bash theme={null}
pnpm preview
```

This generates a QR code that installs your app.

<Warning>
  To preview development builds, you must **SHAKE YOUR PHONE** to enable "dev
  mode" in the Whop app. This allows you to see non-production builds.
</Warning>

### Build Commands

Additional commands for managing builds:

```bash theme={null}
pnpm build         # Build without uploading
pnpm upload        # Upload previously built files
pnpm clean         # Clean build directory
```

### Promoting to Production

1. Deploy a development build: `pnpm ship`
2. Test thoroughly in dev mode (shake to enable)
3. Go to your [app dashboard](https://whop.com/dashboard/developer)
4. Navigate to the Builds tab
5. Select your development build
6. Click "Promote to Production"

<Frame>
  <img alt="Promote to production" />
</Frame>

Your app will be reviewed and deployed to all users once approved.

### Rollback

From the builds screen you can also instantly rollback to a previous production build which will be pushed live to all users across Whop.

<Frame>
  <img alt="Rollback" />
</Frame>

***

## CLI Reference

The `@whop/react-native` CLI provides commands for building and deploying your app:

### Commands

```bash theme={null}
pnpm ship [--ios] [--android] [--web]    # Build + upload development build
pnpm build [--ios] [--android] [--web]   # Build only (no upload)
pnpm upload [--ios] [--android] [--web]  # Upload existing build/
pnpm clean                                # Clean build directory
pnpm preview                              # Generate install QR code
```

### Build Process

When you run `pnpm ship`, the CLI:

1. **Generates Entrypoints** - Creates platform-specific entry files that register your views
2. **Bundles Code**:
   * **Mobile (iOS/Android)**: Uses Metro bundler + Hermes bytecode compiler
   * **Web**: Uses esbuild with React Native Web aliases
3. **Packages Assets** - Collects and optimizes images and other assets
4. **Uploads to Whop** - Creates a development build in your app dashboard
5. **Generates Install Link** - Provides QR code for testing

### Build Output

```
build/
├── entrypoints/        # Generated entry files
│   ├── ios/
│   ├── android/
│   └── web/
├── output/            # Compiled bundles
│   ├── ios/
│   │   └── main_js_bundle.hbc
│   ├── android/
│   │   └── main_js_bundle.hbc
│   └── web/
│       ├── main.js
│       └── index.html
└── app_build_*.zip   # Packaged builds
```

***

## Troubleshooting

### Development Build Not Showing

**Problem**: You deployed a development build but can't see it in the app.

**Solution**: Shake your phone to enable "dev mode". Development builds are only visible when dev mode is active.

### Build Failures

**Problem**: Build fails with Metro or esbuild errors.

**Solutions**:

* Run `pnpm clean` to clear build cache
* Check that all dependencies are installed: `pnpm install`
* Verify Node.js version: `node -v` (should be 22+)
* Check for syntax errors in your views

### API Requests Not Working

**Problem**: API requests return 401 or authentication errors.

**Solutions**:

* Verify you're using `apiOrigin` from `__internal_execSync("getAppApiOrigin", {})`
* Check that `WHOP_API_KEY` is set in `.env.local`
* Ensure your API endpoint calls `whopSdk.verifyUserToken(request.headers)`
* Verify the Base URL is set correctly in the dashboard

### Views Not Found

**Problem**: Build succeeds but views don't render.

**Solutions**:

* Check that view files exist in `src/views/`
* Verify exports match: `export function ExperienceView(props: ExperienceViewProps)`
* Make sure view files end with `.tsx` or `.jsx`

### Libraries Not Working

**Problem**: Third-party library causes crashes on mobile.

**Solutions**:

* Verify the library supports React Native (not just web)
* Use recommended versions from the [Using Libraries](#using-third-party-libraries) section
* Check if the library requires native modules (if so and not in recommended, it is not supported)

### Platform-Specific Issues

**Problem**: App works on one platform but not another.

**Solutions**:

* Use `Platform.OS` to detect platform and provide fallbacks
* Test on all platforms before promoting to production
* Check if you're using platform-specific APIs incorrectly

***

## Next Steps

* [Set up authentication](/developer/guides/authentication) for your API routes
* [Accept payments](/developer/guides/accept-payments) with in-app purchases
* [Use webhooks](/developer/guides/webhooks) to handle events
* Explore the [SDK reference](/developer/api/getting-started) for available APIs


# Save payment methods
Source: https://docs.whop.com/developer/guides/save-payment-methods

Save customer payment methods to charge them later

Use saved payment methods to charge customers automatically for subscriptions, renewals, or usage-based billing. The customer saves their card once using a Whop hosted or embedded flow, and you can charge it any time after.

<Tip>
  Pair this guide with [webhooks](/developer/guides/webhooks): listen for `setup_intent.succeeded` to confirm the save, then for `payment.succeeded` / `payment.failed` to track future charges.
</Tip>

## Pick your save flow

Two paths, depending on whether the user is also paying right now.

|                           | Setup mode (collect-only)                                                                                                  | Save during checkout                                          |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Charges the user now?** | No                                                                                                                         | Yes                                                           |
| **Use case**              | Free trial signup, on-file card before usage-based billing                                                                 | Subscription that renews after the first paid checkout        |
| **API**                   | [Create checkout configuration](/api-reference/checkout-configurations/create-checkout-configuration) with `mode: "setup"` | Pass `setupFutureUsage: "off_session"` on `WhopCheckoutEmbed` |
| **Webhook to listen for** | `setup_intent.succeeded`                                                                                                   | `payment.succeeded` (the `payment_method` is on the result)   |

The rest of this page covers setup mode end-to-end, then shows how to charge a saved method later.

## Save a payment method

<Steps>
  <Step title="Create a checkout configuration in setup mode">
    [Create a checkout configuration](/api-reference/checkout-configurations/create-checkout-configuration) without a plan to collect payment details without charging. Add metadata to be able to link the member and payment method to a customer in your system.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const checkoutConfiguration = await whopsdk.checkoutConfigurations.create({
        company_id: "biz_XXXXXX",
        mode: "setup",
        redirect_url: "https://mywebsite.com/return_location",
        metadata: { customer_id: "my_internal_user_id" },
      });
      ```

      ```python Python theme={null}
      checkout_configuration = whopsdk.checkout_configurations.create(
          company_id="biz_XXXXXX",
          mode="setup",
          redirect_url="https://mywebsite.com/return_location",
          metadata={"customer_id": "my_internal_user_id"},
      )
      ```

      ```ruby Ruby theme={null}
      checkout_configuration = whopsdk.checkout_configurations.create(
        company_id: "biz_XXXXXX",
        mode: "setup",
        redirect_url: "https://mywebsite.com/return_location",
        metadata: { customer_id: "my_internal_user_id" },
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Direct the user to checkout">
    Use embedded checkout or redirect the user to save their payment method.

    <Tabs>
      <Tab title="Embedded">
        ```tsx theme={null}
        import { WhopCheckoutEmbed } from "@whop/checkout/react";

        export default function SavePayment() {
          return (
            <WhopCheckoutEmbed
              sessionId={checkoutConfiguration.id}
              returnUrl="https://yoursite.com/setup/complete"
              onComplete={(sessionId, setupIntentId, result) => {
                // payt_XXXXXXXXX — charge this any time
                saveForLater(result.payment_method_id);
              }}
            />
          );
        }
        ```

        The saved payment method is on the `onComplete` result, so a virtual
        terminal can charge it right away instead of waiting for a webhook. Whop
        only completes the checkout once the method is stored, so
        `payment_method_id` is always set here in setup mode.
      </Tab>

      <Tab title="Redirect">
        ```typescript theme={null}
        window.location.href = checkoutConfiguration.purchase_url;
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Handle completion">
    Listen for the `setup_intent.succeeded` webhook to get the payment method ID. The CheckoutConfiguration and its metadata will be included on the SetupIntent, which you can use to link the member and payment method to a customer in your system.

    <Note>
      Keep the webhook even if you read `payment_method_id` from `onComplete` — it is the only path that survives a closed tab, and the one that fires for the redirect flow.
    </Note>

    <Tip>
      The example uses `waitUntil` from `@vercel/functions` to run the handler after responding `200`. On other runtimes (Bun, Cloudflare Workers, Fastify, Hono) swap it for your framework's equivalent background-task primitive or a job queue. See the [webhooks guide](/developer/guides/webhooks) for Python and Ruby handler equivalents.
    </Tip>

    ```typescript theme={null}
    import { waitUntil } from "@vercel/functions";
    import type { NextRequest } from "next/server";
    import { whopsdk } from "@/lib/whop-sdk";

    export async function POST(request: NextRequest): Promise<Response> {
      const requestBodyText = await request.text();
      const headers = Object.fromEntries(request.headers);
      const webhookData = whopsdk.webhooks.unwrap(requestBodyText, { headers });

      if (webhookData.type === "setup_intent.succeeded") {
        waitUntil(handleSetupSucceeded(webhookData.data));
      }

      return new Response("OK", { status: 200 });
    }

    async function handleSetupSucceeded(setupIntent) {
      console.log("Payment method ID:", setupIntent.payment_method.id);
      console.log("Member ID:", setupIntent.member.id);
      console.log("Metadata:", setupIntent.metadata);
    }
    ```

    The payment method is now saved and authorized for this member.
  </Step>
</Steps>

## Charge a saved payment method

<Steps>
  <Step title="Get the payment method">
    [List saved payment methods](/api-reference/payment-methods/list-payment-methods) for a member or use the payment method ID from the setup intent in the previous step.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const payment_methods = await whopsdk.paymentMethods.list({
        member_id: "mber_XXXXXXXX",
      });

      const payment_method = payment_methods.data[0];
      ```

      ```python Python theme={null}
      payment_methods = whopsdk.payment_methods.list(member_id="mber_XXXXXXXX")
      payment_method = payment_methods.data[0]
      ```

      ```ruby Ruby theme={null}
      payment_methods = whopsdk.payment_methods.list(member_id: "mber_XXXXXXXX")
      payment_method = payment_methods.data.first
      ```
    </CodeGroup>
  </Step>

  <Step title="Create an off-session payment">
    Charge the payment method without customer interaction. The [create payment endpoint](/api-reference/payments/create-payment) returns a payment object immediately and processes the charge asynchronously.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const payment = await whopsdk.payments.create({
        plan: { initial_price: 40.00, currency: "usd", plan_type: "one_time" },
        company_id: "biz_XXXXXXXX",
        member_id: "mber_XXXXXXXX",
        payment_method_id: "payt_XXXXXXXXX",
      });

      console.log("Payment:", payment.id);
      ```

      ```python Python theme={null}
      payment = whopsdk.payments.create(
          plan={"initial_price": 40.00, "currency": "usd", "plan_type": "one_time"},
          company_id="biz_XXXXXXXX",
          member_id="mber_XXXXXXXX",
          payment_method_id="payt_XXXXXXXXX",
      )

      print("Payment:", payment.id)
      ```

      ```ruby Ruby theme={null}
      payment = whopsdk.payments.create(
        plan: { initial_price: 40.00, currency: "usd", plan_type: "one_time" },
        company_id: "biz_XXXXXXXX",
        member_id: "mber_XXXXXXXX",
        payment_method_id: "payt_XXXXXXXXX",
      )

      puts "Payment: #{payment.id}"
      ```
    </CodeGroup>

    <Tip>
      To apply a discount, pass the ID of one of your [promo codes](/manage-your-business/growth-marketing/promo-codes) as `promo_code_id` and Whop calculates the discounted price for you. The promo code must be active and valid for the plan, and the plan must belong to a product.
    </Tip>
  </Step>

  <Step title="Handle payment events">
    Listen for payment webhooks to track success or failure.

    ```typescript theme={null}
    if (webhookData.type === "payment.succeeded") {
      await fulfillOrder(webhookData.data);
    }

    if (webhookData.type === "payment.failed") {
      await notifyCustomer(webhookData.data.member.email, webhookData.data.failure_message);
    }
    ```
  </Step>
</Steps>

## Save during checkout

To save a payment method while processing a payment, add `setupFutureUsage: "off_session"` to the embedded checkout.

```tsx theme={null}
<WhopCheckoutEmbed
	planId="plan_XXXXXXXX"
	returnUrl="https://yoursite.com/checkout/complete"
	setupFutureUsage="off_session"
/>
```

The payment method will be saved after successful payment.

## Next steps

<CardGroup>
  <Card title="Accept payments" href="/developer/guides/accept-payments">
    One-time and subscription checkouts to pair with your save flow.
  </Card>

  <Card title="Embedded checkout" href="/payments/checkout-embed">
    Drop checkout into your own site without redirects.
  </Card>

  <Card title="Listen to webhooks" href="/developer/guides/webhooks">
    Track `setup_intent.succeeded`, `payment.succeeded`, and `payment.failed`.
  </Card>

  <Card title="Billing portal" href="/payments-and-billing/manage-billing/billing-portal">
    Let customers manage and remove their saved payment methods.
  </Card>
</CardGroup>


# Webhooks
Source: https://docs.whop.com/developer/guides/webhooks

Receive payment, membership, and event notifications from Whop in realtime.

Webhooks are `POST` requests from Whop to your server. Use them to react to events like `payment.succeeded`, `membership.activated`, or `entry.created`.

<Tip>
  Webhooks follow the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) spec. Our SDKs handle unwrapping and signature verification for you.
</Tip>

## Set up a webhook

<Steps>
  <Step title="Create the webhook in the dashboard">
    Navigate to the [Developer tab in your dashboard](https://whop.com/dashboard/developer).

    Click **Create Webhook** in the top right corner.
  </Step>

  <Step title="Choose events and URL">
    Enter your webhook URL and select the events that you want to receive.
    Ensure that you are on API version `v1`.

    <Info>
      When testing locally, use ngrok or Cloudflare Tunnel to forward requests to your local development environment.
    </Info>
  </Step>

  <Step title="Store the webhook secret">
    Copy the webhook secret from the dashboard and store it as `WHOP_WEBHOOK_SECRET`.
  </Step>

  <Step title="Handle events on your server">
    Your endpoint now receives `POST` requests for every event you selected. See [Validating webhooks](#validating-webhooks) for example handlers.
  </Step>
</Steps>

## Validating webhooks

Always verify webhook signatures before you trust the payload. Otherwise someone could send your endpoint a fake event.

<Steps>
  <Step title="Set up your SDK client">
    Pass the secret into the SDK client on construction:

    <CodeGroup>
      ```typescript Typescript theme={null}
      import { Whop } from "@whop/sdk";

      export const whopsdk = new Whop({
         	apiKey: process.env.WHOP_API_KEY,
         	webhookKey: btoa(process.env.WHOP_WEBHOOK_SECRET || ""),
      });
      ```

      ```python Python theme={null}
      import base64
      import os
      from whop_sdk import Whop

      # webhook_key must be base64-encoded — the SDK passes it
      # straight to the Standard Webhooks verifier, which expects b64.
      whopsdk = Whop(
          api_key=os.environ["WHOP_API_KEY"],
          webhook_key=base64.b64encode(os.environ["WHOP_WEBHOOK_SECRET"].encode()).decode(),
      )
      ```

      ```ruby Ruby theme={null}
      require "base64"
      require "whop_sdk"

      # webhook_key must be base64-encoded — the SDK passes it
      # straight to the Standard Webhooks verifier, which expects b64.
      whopsdk = WhopSDK::Client.new(
        api_key: ENV["WHOP_API_KEY"],
        webhook_key: Base64.strict_encode64(ENV["WHOP_WEBHOOK_SECRET"]),
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Set up your API handler">
    Create a route that accepts HTTP `POST` requests. Use the same URL you entered during webhook creation.

    <Note>
      Our SDK unwraps and verifies the signature in one call. A bad signature raises; your handler won't see tampered events.
    </Note>

    <Tip>
      The TypeScript example uses `waitUntil` from `@vercel/functions` to run the handler after responding `200`. On other runtimes (Bun, Cloudflare Workers, Fastify, Hono) swap it for your framework's equivalent background-task primitive, or a job queue. The Python and Ruby examples show framework-native equivalents.
    </Tip>

    <CodeGroup>
      ```typescript Typescript + NextJS theme={null}
      import { waitUntil } from "@vercel/functions";
      import type { Payment } from "@whop/sdk/resources.js";
      import type { NextRequest } from "next/server";
      import { whopsdk } from "@/lib/whop-sdk";

      export async function POST(request: NextRequest): Promise<Response> {
         	// Validate the webhook to ensure it's from Whop
         	const requestBodyText = await request.text();
         	const headers = Object.fromEntries(request.headers);
         	const webhookData = whopsdk.webhooks.unwrap(requestBodyText, { headers });

         	// Handle the webhook event
         	if (webhookData.type === "payment.succeeded") {
        		waitUntil(handlePaymentSucceeded(webhookData.data));
         	}

         	// Make sure to return a 2xx status code quickly. Otherwise the webhook will be retried.
         	return new Response("OK", { status: 200 });
      }

      async function handlePaymentSucceeded(invoice: Payment) {
         	// This is a placeholder for a potentially long running operation
         	// In a real scenario, you might need to fetch user data, update a database, etc.
         	console.log("[PAYMENT SUCCEEDED]", invoice);
      }
      ```

      ```python Python + FastAPI theme={null}
      from fastapi import BackgroundTasks, FastAPI, Request, Response
      from lib.whop_sdk import whopsdk

      app = FastAPI()

      @app.post("/api/webhooks/whop")
      async def whop_webhook(request: Request, background: BackgroundTasks):
          # Unwrap + verify signature in one call. Raises on invalid signatures.
          body = (await request.body()).decode()
          event = whopsdk.webhooks.unwrap(body, headers=dict(request.headers))

          if event.type == "payment.succeeded":
              background.add_task(handle_payment_succeeded, event.data)

          # Respond 2xx quickly or Whop will retry.
          return Response(status_code=200)


      def handle_payment_succeeded(payment):
          # Replace with your fulfillment logic.
          print(f"[PAYMENT SUCCEEDED] {payment.id}")
      ```

      ```ruby Ruby on Rails theme={null}
      class Api::WebhooksController < ApplicationController
        skip_before_action :verify_authenticity_token

        def whop
          # Unwrap + verify signature in one call. Raises on invalid signatures.
          event = whopsdk.webhooks.unwrap(
            request.raw_post,
            headers: request.headers.to_h,
          )

          if event.type == "payment.succeeded"
            HandlePaymentSucceededJob.perform_later(event.data.id)
          end

          # Respond 2xx quickly or Whop will retry.
          head :ok
        end
      end
      ```

      ```bash cURL (verify manually) theme={null}
      # Standard Webhooks signatures live in these headers:
      #   webhook-id        — unique event id
      #   webhook-timestamp — unix seconds
      #   webhook-signature — v1,<base64-hmac-sha256>
      #
      # To verify manually: signed_content = "{id}.{timestamp}.{body}"
      # then HMAC-SHA256 with your base64-decoded secret and
      # compare base64-encoded output to the signature.
      curl -X POST https://your-domain.com/webhooks/whop \
        -H "webhook-id: msg_..." \
        -H "webhook-timestamp: 1735689600" \
        -H "webhook-signature: v1,..." \
        -H "content-type: application/json" \
        -d '{"type":"payment.succeeded","data":{...}}'
      ```
    </CodeGroup>
  </Step>
</Steps>

## Delivery guarantees

* **At-least-once delivery.** You may receive the same event more than once. Make your handler idempotent. Use the `webhook-id` header (or a unique field in the event body) as a dedup key.
* **Retries on non-2xx responses.** Whop makes the initial delivery attempt, then retries up to 3 times after 10 seconds, 20 seconds, and 40 seconds if your endpoint errors or does not return a 2xx in time. Failed deliveries stop after that short retry window.
* **Ordering is not guaranteed.** An event created later may arrive before an earlier one. Don't assume sequential delivery.
* **Respond fast.** Do the minimum work needed to acknowledge the event (verify + enqueue), then return 2xx. Long-running fulfillment belongs in a background task.

<Card title="Troubleshoot webhook delivery" icon="bug" href="/developer/troubleshooting#webhook-delivery">
  Fix signature failures, retries, duplicate events, and local tunnel issues.
</Card>

## Available webhooks

Every webhook Whop sends is documented in the [API Reference](/api-reference/). Within each resource, the `hook` pages specify the event name and the exact payload schema.

Common events:

* [`payment.succeeded`](/api-reference/payments/payment-succeeded): a payment is successfully processed.
* [`ledger_account.funds_available`](/api-reference/ledger-accounts/ledger-account): pending funds clear and your withdrawable balance increases.
* [`membership.activated`](/api-reference/memberships/membership-activated): someone joins your community on a product.
* [`membership.deactivated`](/api-reference/memberships/membership-deactivated): a membership goes invalid (failed payment, cancellation, or leaving).
* [`membership.trial_ending_soon`](/api-reference/memberships/membership-activated): a free trial ends within \~72 hours.
* [`entry.created`](/api-reference/entries/entry-created): someone joins a waitlist.
* [`refund.created`](/api-reference/refunds/refund-created): a payment is refunded.
* [`dispute.created`](/api-reference/disputes/dispute-created): a buyer opens a chargeback.

## Next steps

<CardGroup>
  <Card title="Accept payments" href="/developer/guides/accept-payments">
    Pair `payment.succeeded` webhooks with checkout to fulfill orders.
  </Card>

  <Card title="Save payment methods" href="/developer/guides/save-payment-methods">
    Use setup intents + webhooks to charge customers later.
  </Card>

  <Card title="API walkthrough" href="/developer/api/getting-started">
    See where webhooks fit alongside checkout, transfers, and KYC.
  </Card>

  <Card title="Run a local dev proxy" href="/developer/guides/dev-proxy">
    Forward Whop webhooks to localhost while developing.
  </Card>
</CardGroup>


# Add funds to your balance
Source: https://docs.whop.com/developer/platforms/add-funds-to-your-balance

Top up your platform balance to pay out connected accounts

<Steps>
  <Step title="Create your first top up in the dashboard">
    Before using the API, you need to create a top up from the [Dashboard](https://whop.com/dashboard/balance/). This saves a payment method that you can reuse programmatically.
  </Step>

  <Step title="Get payment methods">
    List saved payment methods for your company:

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const paymentMethods = await client.paymentMethods.list({
        company_id: "biz_xxxxxxxxxxxxx",
      });

      const paymentMethod = paymentMethods.data[0];
      ```

      ```python Python theme={null}
      payment_methods = client.payment_methods.list(
          company_id="biz_xxxxxxxxxxxxx",
      )

      payment_method = payment_methods.data[0]
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a top up">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      const topup = await client.topups.create({
        company_id: "biz_xxxxxxxxxxxxx",
        amount: 1000.0,
        currency: "usd",
        payment_method_id: paymentMethod.id,
      });

      console.log(topup.id);
      ```

      ```python Python theme={null}
      topup = client.topups.create(
          company_id="biz_xxxxxxxxxxxxx",
          amount=1000.0,
          currency="usd",
          payment_method_id=payment_method.id,
      )

      print(topup.id)
      ```
    </CodeGroup>

    In this example:

    * `company_id` is your platform's company ID
    * `amount` is the amount to add to your balance
    * `currency` is the currency of the top up
    * `payment_method_id` is the saved payment method to charge
  </Step>

  <Step title="Handle payment events">
    Listen for payment webhooks to confirm the top up was successful:

    ```typescript theme={null}
    if (webhookData.type === "payment.succeeded") {
      const payment = webhookData.data;
      console.log("Top up successful:", payment.id);
    }

    if (webhookData.type === "payment.failed") {
      const payment = webhookData.data;
      console.log("Top up failed:", payment.failure_message);
    }
    ```
  </Step>
</Steps>

## Related resources

<CardGroup>
  <Card title="Collect payments for connected accounts" icon="arrow-right-arrow-left" href="/developer/platforms/collect-payments-for-connected-accounts">
    Transfer funds to connected accounts
  </Card>

  <Card title="Render payout portal" icon="browser" href="/developer/platforms/render-payout-portal">
    Let users withdraw their funds
  </Card>
</CardGroup>


# Collect payments for connected accounts
Source: https://docs.whop.com/developer/platforms/collect-payments-for-connected-accounts

Direct charges and transfers for connected accounts

There are two ways to collect payments for connected accounts:

1. **Direct charges**: Create a checkout for the connected account and collect an application fee.
2. **Transfers**: Collect payment to your platform account and transfer funds to connected accounts later.

## Direct charges

Create a checkout configuration with a connected account's company ID to charge customers directly on the connected account. The connected account is responsible for Whop fees, refunds, and disputes.

### How it works

1. Create a checkout configuration for your connected account with an `application_fee_amount`
2. When a customer purchases, the charge is created directly on the connected account
3. Your platform collects the application fee, and the remaining amount goes to the connected account
4. The connected account handles any disputes or refunds for the transaction

### Example

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const client = new Whop({
  	apiKey: "Company API Key",
  });

  const checkoutConfig = await client.checkoutConfigurations.create({
  	company_id: "biz_xxxxxxxxxxxxx", // Connected account's company ID
  	plan: {
  		initial_price: 10.0,
  		plan_type: "one_time",
  		application_fee_amount: 1.23,
  	},
  });

  console.log(checkoutConfig.purchase_url);
  ```

  ```python Python theme={null}
  from whop_sdk import Whop

  client = Whop(
      api_key="my_api_key",
  )

  checkout_config = client.checkout_configurations.create(
      company_id="biz_xxxxxxxxxxxxx",  # Connected account's company ID
      plan={
          "initial_price": 10.0,
          "plan_type": "one_time",
          "application_fee_amount": 1.23,
      },
  )

  print(checkout_config.purchase_url)
  ```
</CodeGroup>

In this example:

* `company_id` is the connected account's company ID where the charge will be created
* `plan.initial_price` is the total payment amount (10.00 USD)
* `plan.application_fee_amount` is the fee your platform collects (1.23 USD)
* The connected account receives 8.77 USD (10.00 - 1.23)

### Limitations

* The `application_fee_amount` must be positive and less than the total payment amount
* The application fee collected is capped at the captured amount of the payment

## Transfers

Use transfers when your platform collects the payment first, or when your backend decides how much and when each connected account should be paid.

### Before you transfer

* **Origin company**: the company sending funds must complete KYC and have enough balance for the transfer. You can top up the balance from the dashboard or via [Add funds to your balance](/developer/platforms/add-funds-to-your-balance).
* **Destination company**: the recipient must already have a Whop company. If they do not, onboard them first with [Enroll connected accounts](/developer/platforms/enroll-connected-accounts).
* **Settlement ownership**: with transfers, your platform is the merchant of record for the original payment. Your platform handles fees, disputes, and refunds on that payment.

### Example

Collect payment to your platform company, then transfer the connected account's share:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const client = new Whop({
  	apiKey: "Company API Key",
  });

  const transfer = await client.transfers.create({
  	amount: 90.0,
  	currency: "usd",
  	origin_id: "biz_yyyyyyyyyyyyy", // Platform's company ID
  	destination_id: "biz_xxxxxxxxxxxxx", // Connected account's company ID
  	metadata: {
  		order_id: "order_12345",
  	},
  });

  console.log(transfer.id);
  ```

  ```python Python theme={null}
  from whop_sdk import Whop

  client = Whop(
      api_key="my_api_key",
  )

  transfer = client.transfers.create(
      amount=90.0,
      currency="usd",
      origin_id="biz_yyyyyyyyyyyyy",  # Platform's company ID
      destination_id="biz_xxxxxxxxxxxxx",  # Connected account's company ID
      metadata={
          "order_id": "order_12345",
      },
  )

  print(transfer.id)
  ```
</CodeGroup>

In this example:

* `origin_id` is your platform's company ID (where funds are deducted from)
* `destination_id` is the connected account's company ID (where funds are credited to)
* `amount` is the amount to transfer
* `metadata` stores custom data for your reference

### Handle transfer failures

Transfers fail if the origin company is not verified, the origin balance is too low, or the destination company cannot receive funds yet. Fix the underlying cause before retrying. Do not blindly retry failed transfers.

### Common uses

* Scheduled creator payouts
* Affiliate payouts
* Marketplace splits after an order settles

## Which flow should I use?

|              | Direct charges                     | Transfers                 |
| ------------ | ---------------------------------- | ------------------------- |
| **Fees**     | Connected account pays Whop fees   | Platform pays Whop fees   |
| **Disputes** | Connected account handles disputes | Platform handles disputes |
| **Refunds**  | Connected account handles refunds  | Platform handles refunds  |

Use transfers when your backend controls payout timing and amount. Use direct charges when the connected account should own fees, disputes, and refunds from the original purchase.

## API Reference

<CardGroup>
  <Card title="Create Checkout Configuration" icon="code" href="/api-reference/checkout-configurations/create-checkout-configuration">
    Create checkout configurations with application fees
  </Card>

  <Card title="Create Transfer" icon="code" href="/api-reference/transfers/create-transfer">
    Transfer funds between accounts
  </Card>
</CardGroup>

## Related resources

<CardGroup>
  <Card title="Accept payments" icon="credit-card" href="/developer/guides/accept-payments">
    Learn about checkout links and embedded checkout
  </Card>

  <Card title="Enroll connected accounts" icon="users" href="/developer/platforms/enroll-connected-accounts">
    Create recipient companies and finish onboarding before paying them
  </Card>
</CardGroup>


# Enroll connected accounts
Source: https://docs.whop.com/developer/platforms/enroll-connected-accounts

Onboard businesses or individuals to your platform and facilitate payments

To enroll a connected account on your platform, create a Company object for them under your platform company. That company can then accept direct charges, receive transfers, and use Whop payout flows.

## Example

Create a company for the connected account:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const client = new Whop({
  	apiKey: "Company API Key",
  });

  const company = await client.companies.create({
  	email: "merchant@example.com",
  	parent_company_id: "biz_xxxxxxxxxxxxx",
  	title: "Acme Merchant Store",
  	metadata: {
  		internal_user_id: "user_12345",
  		seller_tier: "gold",
  	},
  });

  console.log(company.id);
  ```

  ```python Python theme={null}
  from whop_sdk import Whop

  client = Whop(
      api_key="my_api_key",
  )

  company = client.companies.create(
      email="merchant@example.com",
      parent_company_id="biz_xxxxxxxxxxxxx",
      title="Acme Merchant Store",
      metadata={
          "internal_user_id": "user_12345",
          "seller_tier": "gold",
      },
  )

  print(company.id)
  ```
</CodeGroup>

In this example:

* `email` is the connected account's email address. This is used to identify the connected account and send them important notifications about their account.
* `parent_company_id` is your platform's company ID (the parent company)
* `title` is the display name for the connected account. This is required.
* `metadata` contains custom key-value pairs:
  * `internal_user_id`: Your platform's internal identifier for this connected account
  * `seller_tier`: A classification or tier level for the connected account (e.g., "bronze", "silver", "gold")
* The response includes a `company.id` that you can use to reference this connected account in future API calls

<Tip>
  The email address should belong to the connected account (business or
  individual) who will be managing the account. This person will receive account
  setup and payment notifications.
</Tip>

## Finish onboarding

If the recipient does not already have a Whop company, send them an account onboarding link after you create the company. They complete KYC through that link, and then the company can receive transfers and other payout flows.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const accountLink = await client.accountLinks.create({
  	company_id: company.id,
  	refresh_url: "https://yourapp.com/onboarding/refresh",
  	return_url: "https://yourapp.com/onboarding/complete",
  	use_case: "account_onboarding",
  });

  console.log(accountLink.url);
  ```

  ```python Python theme={null}
  account_link = client.account_links.create(
      company_id=company.id,
      refresh_url="https://yourapp.com/onboarding/refresh",
      return_url="https://yourapp.com/onboarding/complete",
      use_case="account_onboarding",
  )

  print(account_link.url)
  ```
</CodeGroup>

After the recipient completes onboarding, you can:

* create checkout flows for them with application fees.
* transfer funds to their company balance.
* let them withdraw funds with the payout portal.

## Getting started

Before you can enroll connected accounts, you need to set up your platform account:

1. **Sign up for a platform account**: Create a Company account at [whop.com/dashboard](https://whop.com/dashboard)
2. **Generate a Company API key**: Go to your developer settings page and generate a Company API key
3. **Use the API key for authentication**: This API key is how you authenticate with the Whop API and control your connected accounts

The Company API key provides the necessary permissions to create and manage connected accounts (companies) under your platform account.

## Custom metadata

You can attach custom metadata to companies when creating them. Metadata allows you to store additional information about each connected account as key-value pairs. This is useful for:

* Storing your internal user or merchant identifiers
* Tracking connected account tiers or classifications
* Linking to your platform's database records

Metadata is stored on the Company object and can be retrieved later for reporting, filtering, or integration purposes.

## API Reference

<Card title="Create Company API" icon="code" href="/api-reference/companies/create-company">
  See the full API reference for creating companies and all available parameters
</Card>

## Next steps

After creating a Company for a connected account:

<CardGroup>
  <Card title="Collect and split payments" icon="arrow-right-arrow-left" href="/developer/platforms/collect-payments-for-connected-accounts">
    Choose between direct charges and transfers
  </Card>

  <Card title="Render payout portal" icon="money-bill-transfer" href="/developer/platforms/render-payout-portal">
    Let connected accounts withdraw their funds
  </Card>
</CardGroup>


# Manual payouts to connected accounts
Source: https://docs.whop.com/developer/platforms/manual-payouts

Onboard connected accounts and programmatically pay them out

Send payouts directly to your connected accounts from your platform balance. Connected accounts must complete identity verification and add a payout method before they can receive funds.

<Steps>
  <Step title="Complete KYC verification">
    Before a user can receive payouts, they must complete identity verification (KYC). Use the hosted account onboarding flow to guide users through this process:

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import Whop from "@whop/sdk";

      const client = new Whop({
        apiKey: "Company API Key",
      });

      const accountLink = await client.accountLinks.create({
        company_id: "biz_xxxxxxxxxxxxx",
        use_case: "account_onboarding",
        return_url: "https://yourapp.com/onboarding/complete",
        refresh_url: "https://yourapp.com/onboarding/refresh",
      });

      // Redirect the user to complete KYC
      console.log(accountLink.url);
      ```

      ```python Python theme={null}
      from whop_sdk import Whop

      client = Whop(
          api_key="my_api_key",
      )

      account_link = client.account_links.create(
          company_id="biz_xxxxxxxxxxxxx",
          use_case="account_onboarding",
          return_url="https://yourapp.com/onboarding/complete",
          refresh_url="https://yourapp.com/onboarding/refresh",
      )

      # Redirect the user to complete KYC
      print(account_link.url)
      ```
    </CodeGroup>

    Redirect the user to the `url` returned in the response. After completing verification, they will be redirected back to your `return_url`.
  </Step>

  <Step title="Add a payout method">
    Before creating a payout, the account needs a payout method. Use the embedded component to let users add a payout method:

    <CodeGroup>
      ```tsx React theme={null}
      "use client";

      import {
        Elements,
        PayoutsSession,
        PayoutMethodElement,
      } from "@whop/embedded-components-react-js";
      import { loadWhopElements } from "@whop/embedded-components-vanilla-js";

      const elements = loadWhopElements();

      export function AddPayoutMethod({ companyId }: { companyId: string }) {
        return (
          <Elements elements={elements}>
            <PayoutsSession
              token={() =>
                fetch(`/api/token?companyId=${companyId}`)
                  .then((res) => res.json())
                  .then((data) => data.token)
              }
              companyId={companyId}
              redirectUrl="https://yourapp.com/verification-complete"
            >
              <PayoutMethodElement fallback={<div>Loading...</div>} />
            </PayoutsSession>
          </Elements>
        );
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Get the default payout method">
    List the connected account's payout methods and find the one with `is_default: true`:

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import Whop from "@whop/sdk";

      const client = new Whop({
        apiKey: "Company API Key",
      });

      const payoutMethods = await client.payoutMethods.list({
        company_id: "biz_xxxxxxxxxxxxx",
      });

      const defaultMethod = payoutMethods.data.find((method) => method.is_default);
      console.log(defaultMethod.id);
      ```

      ```python Python theme={null}
      from whop_sdk import Whop

      client = Whop(
          api_key="my_api_key",
      )

      payout_methods = client.payout_methods.list(
          company_id="biz_xxxxxxxxxxxxx",
      )

      default_method = next((m for m in payout_methods.data if m.is_default), None)
      print(default_method.id)
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a payout">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      import Whop from "@whop/sdk";

      const client = new Whop({
        apiKey: "Company API Key",
      });

      const payout = await client.payouts.create({
        account_id: "biz_xxxxxxxxxxxxx",
        amount: 100.0,
        currency: "usd",
        payout_method_id: "potk_xxxxxxxxxxxxx",
      });

      console.log(payout.id);
      ```

      ```python Python theme={null}
      from whop_sdk import Whop

      client = Whop(
          api_key="my_api_key",
      )

      payout = client.payouts.create(
          account_id="biz_xxxxxxxxxxxxx",
          amount=100.0,
          currency="usd",
          payout_method_id="potk_xxxxxxxxxxxxx",
      )

      print(payout.id)
      ```
    </CodeGroup>

    In this example:

    * `account_id` is the connected account to pay out
    * `amount` is the payout amount (100.00 USD) - fees will be deducted from this amount
    * `currency` is the ISO currency code
    * `payout_method_id` is the ID of the payout method to use (from step 3)

    The request will return an error if the amount exceeds the available balance.

    ### Cover payout fees for your connected accounts

    By default, payout fees are deducted from the connected account's balance. You can choose to cover these fees from your platform balance instead by setting `platform_covers_fees` to `true`:

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const payout = await client.payouts.create({
        account_id: "biz_xxxxxxxxxxxxx",
        amount: 100.0,
        currency: "usd",
        payout_method_id: "potk_xxxxxxxxxxxxx",
        platform_covers_fees: true,
      });
      ```

      ```python Python theme={null}
      payout = client.payouts.create(
          account_id="biz_xxxxxxxxxxxxx",
          amount=100.0,
          currency="usd",
          payout_method_id="potk_xxxxxxxxxxxxx",
          platform_covers_fees=True,
      )
      ```
    </CodeGroup>

    When `platform_covers_fees` is `true`, the connected account receives the full payout amount and the fee is debited from your platform's balance instead. This requires your platform's fee coverage policy to cover the payout method, or an API key authorized to manage your connected accounts' fees.
  </Step>
</Steps>

## API Reference

<Card title="Create Payout API" icon="code" href="/api-reference/beta/payouts/create-payout">
  See the full API reference for creating payouts
</Card>

## Related resources

<CardGroup>
  <Card title="Pay connected accounts" icon="arrow-right-arrow-left" href="/developer/platforms/collect-payments-for-connected-accounts">
    Transfer funds to your connected accounts
  </Card>

  <Card title="Render payout portal" icon="money-bill-transfer" href="/developer/platforms/render-payout-portal">
    Let your users withdraw their funds
  </Card>
</CardGroup>


# Playground
Source: https://docs.whop.com/developer/platforms/playground

Interactive playground for embedded payout components

<Embed />


# Quickstart
Source: https://docs.whop.com/developer/platforms/quickstart

Embed payout components in your application in minutes

<QuickStart
  title="Embed payout components"
  description={<>
Allow your connected accounts to manage their own payouts through an embedded portal. This guide shows you how to set up the server-side token generation and client-side components.

<ExamplesLink href="https://whop.com/network/examples?filter=payouts" />

</>}
>
  ### Congratulations!

  You've successfully embedded the payout components in your application.

  ## Next steps

  <CardGroup>
    <Card title="PayoutsSession Props" icon="gear" href="/developer/platforms/render-payout-portal#payoutssession-props">
      Customize the payout portal with additional configuration options like custom styling and event callbacks.
    </Card>

    <Card title="Hosted Payout Portal" icon="arrow-up-right-from-square" href="/developer/platforms/render-payout-portal#hosted-payout-portal">
      Skip embedding entirely and redirect users to a Whop-hosted payout portal.
    </Card>

    <Card title="Manual Payouts" icon="money-bill-transfer" href="/developer/platforms/manual-payouts">
      Programmatically trigger payouts, manage KYC verification, and control payout methods via the API.
    </Card>

    <Card title="Enroll Connected Accounts" icon="user-plus" href="/developer/platforms/enroll-connected-accounts">
      Learn how to create and manage Company objects for your connected accounts.
    </Card>
  </CardGroup>
</QuickStart>


# Enable connected account payouts
Source: https://docs.whop.com/developer/platforms/render-payout-portal

Let your connected accounts manage their own payouts through an embedded or hosted portal

Allow your connected accounts to complete KYC verification, add payout methods, and withdraw their funds on their own. You can embed the payout portal directly in your app or redirect users to a Whop-hosted portal.

## Embedded payout portal

### Server side implementation

To use the embedded component, you need to generate an access token for the connected account's company. This token grants temporary access to the payout portal for that specific company.

<CodeGroup>
  ```tsx Next.JS theme={null}
  // app/api/token/route.ts
  import Whop from "@whop/sdk";
  import type { NextRequest } from "next/server";

  const whop = new Whop({
  	apiKey: process.env.WHOP_API_KEY,
  });

  export async function GET(request: NextRequest) {
  	// Authenticate your user here
  	const companyId = request.nextUrl.searchParams.get("companyId");

  	if (!companyId) {
  		return new Response(null, { status: 400 });
  	}
  	const tokenResponse = await whop.accessTokens
  		.create({
  			company_id: companyId,
  		})
  		.catch(() => {
  			return null;
  		});
  	if (!tokenResponse) {
  		return new Response(null, { status: 500 });
  	}
  	const token = tokenResponse.token;
  	return Response.json({
  		token,
  	});
  }
  ```

  ```typescript Express.js theme={null}
  import express from "express";
  import Whop from "@whop/sdk";

  const app = express();
  const client = new Whop({ apiKey: "Company API Key" });

  app.use(express.json());

  app.post("/api/access-token", async (req, res) => {
  	// Authenticate your user here
  	const { companyId } = req.body;

  	const { token } = await client.accessTokens.create({
  		company_id: companyId,
  	});

  	res.json({ token });
  });

  app.listen(3000, () => {
  	console.log("Server running on port 3000");
  });
  ```

  ```python Python theme={null}
  from whop_sdk import Whop
  from flask import Flask, request, jsonify

  app = Flask(__name__)
  client = Whop(api_key="Company API Key")

  @app.route('/api/access-token', methods=['POST'])
  def create_access_token():
      data = request.get_json()
      # Authenticate your user here
      company_id = data.get('companyId')

      access_token = client.access_tokens.create(
          company_id=company_id
      )

      return jsonify({'token': access_token.token})
  ```
</CodeGroup>

<Card title="Create Access Token API" icon="code" href="/api-reference/access-tokens/create-access-token">
  See the full API reference for generating access tokens and all available
  parameters
</Card>

## Client side setup

<CodeGroup>
  ```bash npm theme={null}
  npm install @whop/embedded-components-react-js @whop/embedded-components-vanilla-js
  ```

  ```bash pnpm theme={null}
  pnpm add @whop/embedded-components-react-js @whop/embedded-components-vanilla-js
  ```

  ```html HTML theme={null}
  <script src="https://latest.elements.whop.com/release/elements.js"></script>
  ```

  ```swift Swift theme={null}
  // Add to your Package.swift dependencies

  dependencies: [
      .package(url: "https://github.com/whopio/whopsdk-payments-swift.git", exact: "0.0.6")
  ]


  // Info.plist - Add these usage descriptions to Info.plist for KYC functionality

  <key>NSCameraUsageDescription</key>
  <string>We use your camera to let you take photos, record videos, and ID verification.</string>

  <key>NSMicrophoneUsageDescription</key>
  <string>We use your microphone so you can record and share audio, and ID verification.</string>

  <key>NSPhotoLibraryUsageDescription</key>
  <string>We use your photo library so you can select and share photos or videos from your library.</string>
  ```
</CodeGroup>

## Client side implementation

<CodeGroup>
  ```tsx React theme={null}
  import type { WhopElementsOptions } from "@whop/embedded-components-vanilla-js/types";

  import {
  	BalanceElement,
  	Elements,
  	PayoutsSession,
  	WithdrawButtonElement,
  	WithdrawalsElement,
  } from "@whop/embedded-components-react-js";
  import { loadWhopElements } from "@whop/embedded-components-vanilla-js";

  const elements = loadWhopElements();

  const appearance: WhopElementsOptions["appearance"] = {
  	classes: {
  		".Button": { height: "40px", "border-radius": "8px" },
  		".Button:disabled": { "background-color": "gray" },
  		".Container": { "border-radius": "12px" },
  	},
  };

  export function BalancePage({ companyId }: { companyId: string }) {
  	return (
  		<Elements appearance={appearance} elements={elements}>
  			<PayoutsSession
  				token={() =>
  					fetch(`/api/token?companyId=${companyId}`)
  						.then((res) => res.json())
  						.then((data) => data.token)
  				}
  				companyId={companyId}
  				redirectUrl="https://yourapp.com/verification-complete"
  			>
  				<section
  					style={{ display: "flex", flexDirection: "column", gap: "8px" }}
  				>
  					<div
  						style={{ height: "95.5px", width: "100%", position: "relative" }}
  					>
  						<BalanceElement fallback={<div>Loading...</div>} />
  					</div>
  					<div style={{ height: "40px", width: "100%", position: "relative" }}>
  						<WithdrawButtonElement fallback={<div>Loading...</div>} />
  					</div>
  					<WithdrawalsElement fallback={<div>Loading...</div>} />
  				</section>
  			</PayoutsSession>
  		</Elements>
  	);
  }
  ```

  ```swift Swift theme={null}
  import SwiftUI
  import WhopPayments

  class MyTokenProvider: WhopTokenProvider {
      /// return an access token fetched from your
      /// backend.
      ///
      /// called when `WhopPayoutsView` appears and
      /// before expiration (within 60 seconds).
      func getToken() async -> WhopTokenResponse {
          let token = await fetchAccessToken()
          return WhopTokenResponse(accessToken: token)
      }
  }

  @main
  struct MyApp: App {
      let tokenProvider = MyTokenProvider()

      var body: some Scene {
          WindowGroup {
              WhopPayoutsView(
                  tokenProvider,
                  companyId: "company_id",
                  ledgerAccountId: "ledger_account_id"
              )
          }
      }
  }
  ```
</CodeGroup>

## PayoutsSession Props

The `PayoutsSession` component requires the following props:

| Prop          | Type                            | Required | Description                                                                                                                        |
| ------------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `token`       | `string \| Promise \| Function` | Yes      | Access token for the session. Can be a string, promise, or function that returns a token.                                          |
| `companyId`   | `string`                        | Yes      | The company ID for the connected account.                                                                                          |
| `redirectUrl` | `string`                        | Yes      | Absolute URL (e.g., `https://yourapp.com/verification-complete`) to redirect the user to after identity verification is completed. |
| `currency`    | `string`                        | No       | Currency code (e.g., "USD"). Defaults to "USD".                                                                                    |

<Note>
  The `redirectUrl` must be a publicly accessible URL. Localhost URLs (e.g.,
  `http://localhost:3000`) will not work. For local development, use a tunneling
  service like [ngrok](https://ngrok.com) to expose your local server.
</Note>

## Modal methods

You can programmatically open modals using the `usePayoutsSessionRef` hook:

```tsx theme={null}
import { usePayoutsSessionRef } from "@whop/embedded-components-react-js";

const sessionRef = usePayoutsSessionRef();

<button
	onClick={() =>
		sessionRef.current?.payoutsSession?.showChangeAccountCountryModal(
			(modal) => ({
				onClose: (ev) => {
					ev.preventDefault();
					modal.close();
				},
			}),
		)
	}
>
	Change Account Country
</button>;
```

### Available modals

| Method                          | Description                                        |
| ------------------------------- | -------------------------------------------------- |
| `showChangeAccountCountryModal` | Allow users to change their payout account country |
| `showResetAccountModal`         | Allow users to reset their payout account          |

## Hosted payout portal

Instead of embedding the payout portal in your app, you can redirect users to a Whop-hosted payout portal. This is useful when you don't want to build a custom UI or need a quick integration.

Create an account link and redirect the user to the returned URL:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Whop from "@whop/sdk";

  const client = new Whop({
  	apiKey: "Company API Key",
  });

  const accountLink = await client.accountLinks.create({
  	company_id: "biz_xxxxxxxxxxxxx",
  	use_case: "payouts_portal",
  	return_url: "https://yourapp.com/payouts/complete",
  	refresh_url: "https://yourapp.com/payouts/refresh",
  });

  // Redirect the user to the hosted portal
  console.log(accountLink.url);
  ```

  ```python Python theme={null}
  from whop_sdk import Whop

  client = Whop(
      api_key="my_api_key",
  )

  account_link = client.account_links.create(
      company_id="biz_xxxxxxxxxxxxx",
      use_case="payouts_portal",
      return_url="https://yourapp.com/payouts/complete",
      refresh_url="https://yourapp.com/payouts/refresh",
  )

  # Redirect the user to the hosted portal
  print(account_link.url)
  ```
</CodeGroup>

In this example:

* `company_id` is the platform or connected account
* `use_case` specifies the portal type
* `return_url` is where the user is redirected when they want to return to your site
* `refresh_url` is where the user is redirected if the session expires

### Available use cases

| Use case             | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `account_onboarding` | KYC and identity verification                               |
| `payouts_portal`     | Withdrawals, payout methods, KYC, and identity verification |

After creating the account link, redirect the user to the `url` returned in the response. The user will complete the payout flow on the Whop-hosted portal and be redirected back to your `return_url` when finished.

## Related resources

<CardGroup>
  <Card title="Pay connected accounts" icon="arrow-right-arrow-left" href="/developer/platforms/collect-payments-for-connected-accounts">
    Transfer funds to connected accounts
  </Card>
</CardGroup>


# Business structures
Source: https://docs.whop.com/developer/verification/business-structures

business_structure values by country of incorporation.

`business_structure` is the legal entity type of a business. Set it when you create or update a verification for a business entity — either a business (KYB) verification, or an individual (KYC) verification for a creator who operates through a company.

Pick the structure that matches the business's legal form in its country of incorporation.

## By country

| Country | Supported structures                                                                                                                                                                                                                           |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AE`    | `llc`, `sole_establishment`, `free_zone_llc`, `free_zone_establishment`                                                                                                                                                                        |
| `AT`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `AU`    | `public_corporation`, `private_corporation`, `sole_proprietorship`, `private_partnership`, `trust`, `unincorporated_association`                                                                                                               |
| `BE`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `BG`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `CA`    | `private_corporation`, `public_corporation`, `private_partnership`, `sole_proprietorship`, `registered_charity`                                                                                                                                |
| `CH`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `CY`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `CZ`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `DE`    | `private_corporation`, `public_corporation`, `incorporated_partnership`, `unincorporated_partnership`, `incorporated_non_profit`, `unincorporated_non_profit`                                                                                  |
| `DK`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `EE`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `ES`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `FI`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `FR`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `GB`    | `private_corporation`, `incorporated_partnership`, `unincorporated_partnership`, `incorporated_non_profit`, `unincorporated_non_profit`                                                                                                        |
| `GI`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `GR`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `HK`    | `private_company`, `private_partnership`, `sole_proprietorship`, `incorporated_non_profit`, `unincorporated_non_profit`                                                                                                                        |
| `HR`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `HU`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `IE`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `IT`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `JP`    | `sole_proprietorship`                                                                                                                                                                                                                          |
| `LI`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `LT`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `LU`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `LV`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `MT`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `NL`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`, `sole_proprietorship`                                                                                                                   |
| `NO`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `NZ`    | `public_corporation`, `private_corporation`, `sole_proprietorship`, `private_partnership`, `trust`                                                                                                                                             |
| `PL`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `PT`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `RO`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `SE`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `SG`    | `sole_proprietorship`, `private_partnership`, `private_company`, `public_company`                                                                                                                                                              |
| `SI`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `SK`    | `incorporated_partnership`, `unincorporated_partnership`, `public_corporation`, `private_corporation`                                                                                                                                          |
| `TH`    | `private_corporation`, `incorporated_partnership`, `unincorporated_partnership`, `sole_proprietorship`                                                                                                                                         |
| `US`    | `single_member_llc`, `multi_member_llc`, `private_corporation`, `private_partnership`, `public_corporation`, `public_partnership`, `sole_proprietorship`, `unincorporated_association`, `incorporated_non_profit`, `unincorporated_non_profit` |

<Note>
  Countries not listed have no structure values. Declare the business with `business_name` alone and omit `business_structure`.
</Note>

## Values

The same data, keyed by `business_structure` value.

| Value                        | Entity type                | Countries                                                                                                                                                                                                                    |
| ---------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `free_zone_establishment`    | Free zone establishment    | `AE`                                                                                                                                                                                                                         |
| `free_zone_llc`              | Free zone LLC              | `AE`                                                                                                                                                                                                                         |
| `incorporated_non_profit`    | Incorporated non-profit    | `DE`, `GB`, `HK`, `US`                                                                                                                                                                                                       |
| `incorporated_partnership`   | Incorporated partnership   | `AT`, `BE`, `BG`, `CH`, `CY`, `CZ`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `GB`, `GI`, `GR`, `HR`, `HU`, `IE`, `IT`, `LI`, `LT`, `LU`, `LV`, `MT`, `NL`, `NO`, `PL`, `PT`, `RO`, `SE`, `SI`, `SK`, `TH`                         |
| `llc`                        | Limited liability company  | `AE`                                                                                                                                                                                                                         |
| `multi_member_llc`           | Multi-member LLC           | `US`                                                                                                                                                                                                                         |
| `private_company`            | Private company            | `HK`, `SG`                                                                                                                                                                                                                   |
| `private_corporation`        | Private corporation        | `AT`, `AU`, `BE`, `BG`, `CA`, `CH`, `CY`, `CZ`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `GB`, `GI`, `GR`, `HR`, `HU`, `IE`, `IT`, `LI`, `LT`, `LU`, `LV`, `MT`, `NL`, `NO`, `NZ`, `PL`, `PT`, `RO`, `SE`, `SI`, `SK`, `TH`, `US` |
| `private_partnership`        | Private partnership        | `AU`, `CA`, `HK`, `NZ`, `SG`, `US`                                                                                                                                                                                           |
| `public_company`             | Public company             | `SG`                                                                                                                                                                                                                         |
| `public_corporation`         | Public corporation         | `AT`, `AU`, `BE`, `BG`, `CA`, `CH`, `CY`, `CZ`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `GI`, `GR`, `HR`, `HU`, `IE`, `IT`, `LI`, `LT`, `LU`, `LV`, `MT`, `NL`, `NO`, `NZ`, `PL`, `PT`, `RO`, `SE`, `SI`, `SK`, `US`             |
| `public_partnership`         | Public partnership         | `US`                                                                                                                                                                                                                         |
| `registered_charity`         | Registered charity         | `CA`                                                                                                                                                                                                                         |
| `single_member_llc`          | Single-member LLC          | `US`                                                                                                                                                                                                                         |
| `sole_establishment`         | Sole establishment         | `AE`                                                                                                                                                                                                                         |
| `sole_proprietorship`        | Sole proprietorship        | `AU`, `CA`, `HK`, `JP`, `NL`, `NZ`, `SG`, `TH`, `US`                                                                                                                                                                         |
| `trust`                      | Trust                      | `AU`, `NZ`                                                                                                                                                                                                                   |
| `unincorporated_association` | Unincorporated association | `AU`, `US`                                                                                                                                                                                                                   |
| `unincorporated_non_profit`  | Unincorporated non-profit  | `DE`, `GB`, `HK`, `US`                                                                                                                                                                                                       |


# Identity documents
Source: https://docs.whop.com/developer/verification/identity-documents

Which identity documents the API accepts, and the exact file keys to send for each.

Verify a person entirely through the API by sending their identity document photos in the [Create Verification](/api-reference/beta/verifications/create-verification) request. No hosted session, no follow-up calls: one `POST`, then poll for the verdict.

## Which files to send

Pick the `document_type` that matches the document being photographed. It decides exactly which keys the `documents` object must contain — nothing more, nothing less.

| `document_type`    | Required `documents` keys                                   |
| ------------------ | ----------------------------------------------------------- |
| `ID_CARD`          | `id_card_front`, `id_card_back`, `selfie`                   |
| `DRIVERS`          | `drivers_front`, `drivers_back`, `selfie`                   |
| `RESIDENCE_PERMIT` | `residence_permit_front`, `residence_permit_back`, `selfie` |
| `PASSPORT`         | `passport_front`, `selfie`                                  |

Every value is the file's raw bytes, base64-encoded:

```python theme={null}
import base64

def b64(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode()
```

## File rules

* JPEG, PNG, or PDF. The type is detected from the file's actual bytes, so the extension doesn't matter.
* The `selfie` must be a JPEG or PNG photo of the person's face.
* 5MB maximum per file, measured before encoding.
* Send the complete set in one request. A missing, oversized, or unreadable file fails the whole request with an error naming the exact key — fix that file and send the same request again. Nothing partial is ever submitted.

## Full example

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/verifications?account_id=biz_XXXXXXXX" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"first_name\": \"Jane\",
    \"last_name\": \"Doe\",
    \"date_of_birth\": \"1990-01-01\",
    \"country\": \"US\",
    \"phone\": \"+15551234567\",
    \"tax_identification_number\": \"123456789\",
    \"address\": { \"line1\": \"123 Main St\", \"city\": \"Austin\", \"state\": \"TX\", \"postal_code\": \"73301\" },
    \"business_website\": \"https://example.com\",
    \"document_type\": \"DRIVERS\",
    \"documents\": {
      \"drivers_front\": \"$(base64 -i front.jpg)\",
      \"drivers_back\": \"$(base64 -i back.jpg)\",
      \"selfie\": \"$(base64 -i selfie.jpg)\"
    }
  }"
```

A `201` means every document was accepted and review has started — the response's `required_documents` lists each key as `submitted`. Poll [Retrieve Verification](/api-reference/beta/verifications/retrieve-verification) until `status` becomes `approved` or `rejected`.

<Note>
  `business_website` is optional. When omitted, the account's whop.com page is used for payout setup. If you send one, it must be an external site or social link; Whop store pages are rejected.
</Note>

## If a document is rejected

When the reviewer can't accept a photo, `status` returns to `action_required` and the rejected keys appear in `required_documents` as `pending_upload` with a `rejection_reason`. Send the same Create Verification request again with a better photo — the review resumes automatically.

## Country coverage

`ID_CARD`, `DRIVERS`, and `PASSPORT` are accepted for people in most countries. The exceptions are listed below — for a country in this table, only the listed values work; anything else comes back through the rejection flow above.

| Country | Accepted `document_type` values           |
| ------- | ----------------------------------------- |
| `AD`    | `DRIVERS`, `RESIDENCE_PERMIT`, `PASSPORT` |
| `AI`    | `DRIVERS`, `PASSPORT`                     |
| `AQ`    | `PASSPORT`                                |
| `AS`    | `DRIVERS`, `PASSPORT`                     |
| `CC`    | `ID_CARD`, `PASSPORT`                     |
| `CK`    | `DRIVERS`, `PASSPORT`                     |
| `CX`    | `DRIVERS`, `PASSPORT`                     |
| `EH`    | `PASSPORT`                                |
| `ER`    | `ID_CARD`, `PASSPORT`                     |
| `FK`    | `PASSPORT`                                |
| `FM`    | `DRIVERS`, `RESIDENCE_PERMIT`, `PASSPORT` |
| `FO`    | `DRIVERS`, `PASSPORT`                     |
| `GF`    | `ID_CARD`, `RESIDENCE_PERMIT`, `PASSPORT` |
| `GL`    | `DRIVERS`, `PASSPORT`                     |
| `HM`    | `PASSPORT`                                |
| `KY`    | `DRIVERS`, `PASSPORT`                     |
| `MS`    | `DRIVERS`, `RESIDENCE_PERMIT`, `PASSPORT` |
| `NF`    | `PASSPORT`                                |
| `PM`    | `ID_CARD`, `PASSPORT`                     |
| `SH`    | `PASSPORT`                                |
| `SJ`    | `PASSPORT`                                |
| `TF`    | `PASSPORT`                                |
| `TK`    | `DRIVERS`, `PASSPORT`                     |
| `TV`    | `DRIVERS`, `PASSPORT`                     |
| `VA`    | `PASSPORT`                                |
| `WF`    | `ID_CARD`, `PASSPORT`                     |
| `YT`    | `ID_CARD`, `PASSPORT`                     |

`RESIDENCE_PERMIT` is accepted in most countries too, but its coverage is narrower. Beyond the table above, it is **not** accepted for people in:

`AG`, `AW`, `BB`, `BF`, `BI`, `BL`, `BZ`, `CV`, `CW`, `DM`, `GG`, `GI`, `GN`, `GS`, `GU`, `GY`, `IM`, `IO`, `JE`, `KI`, `KM`, `LC`, `LR`, `MF`, `ML`, `MP`, `MQ`, `MU`, `NC`, `NR`, `NU`, `NZ`, `PF`, `PG`, `PN`, `PR`, `PS`, `PW`, `SB`, `SC`, `SM`, `SR`, `ST`, `SX`, `SY`, `SZ`, `TC`, `TL`, `TO`, `VC`, `VI`, `WS`

Identity verification is not available for people in these countries — every document type is declined:

`AF` (Afghanistan), `BY` (Belarus), `CU` (Cuba), `HT` (Haiti), `IQ` (Iraq), `IR` (Iran), `KP` (North Korea), `LB` (Lebanon), `LY` (Libya), `MM` (Myanmar), `MZ` (Mozambique), `RU` (Russia), `SD` (Sudan), `SO` (Somalia), `SS` (South Sudan)

<Note>
  This table reflects Whop's verification configuration as of July 2026. Country acceptance is applied during review, so a document type that isn't valid for the person's country fails with a `rejection_reason` rather than an upfront error.
</Note>


# Update & delete
Source: https://docs.whop.com/developer/verification/manage

Update identity fields before verification, or remove a verification entirely.

## Update a verification

Update fields on a verification that hasn't been approved yet. Use this to correct pre-filled data before the user completes KYC.

```bash cURL theme={null}
curl -X PATCH https://api.whop.com/api/v1/verifications/idpf_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Janet",
    "last_name": "Smith"
  }'
```

### Updatable fields

| Field                | Description                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `first_name`         | Legal first name                                                                                                             |
| `last_name`          | Legal last name                                                                                                              |
| `date_of_birth`      | ISO date                                                                                                                     |
| `country`            | ISO alpha-2 country code                                                                                                     |
| `personal_address`   | Residential address object                                                                                                   |
| `business_name`      | Legal business name                                                                                                          |
| `business_address`   | Registered business address                                                                                                  |
| `business_structure` | Legal entity structure — every value and its countries in [Business structures](/developer/verification/business-structures) |

<Warning>
  You can't update a verification that's already `approved`. The identity data is locked once verified. Delete it and create a new one if you need to start over.
</Warning>

## Delete a verification

Remove a verification from an account. The data stays in our system but the verification is unlinked and won't appear in the list.

```bash cURL theme={null}
curl -X DELETE https://api.whop.com/api/v1/verifications/idpf_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

```json Response theme={null}
{
  "id": "idpf_xxxxxxxxxxxxx",
  "deleted": true
}
```

After deleting, call `POST /api/v1/verifications` to start fresh with a new verification.

<Note>
  Deleting doesn't cancel an in-flight KYC session — it unlinks the verification from the account. The session expires on its own.
</Note>

## Restart a verification

If a user's KYC was declined or they need to redo it, you don't need to delete and recreate. Call create with `restart: true`:

```bash cURL theme={null}
curl -X POST https://api.whop.com/api/v1/verifications \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "biz_xxxxxxxxxxxxx",
    "kind": "individual",
    "restart": true
  }'
```

This abandons the old session and gives you a fresh `session_url`.

## Authentication

All write endpoints require a Company API key with the `identity:write` scope.

### Errors

| Status | Message                                   | When                                          |
| ------ | ----------------------------------------- | --------------------------------------------- |
| `400`  | `Cannot update an approved verification.` | Profile is already verified                   |
| `400`  | `at least one field is required`          | Empty request body                            |
| `401`  | —                                         | Missing or invalid API key                    |
| `403`  | —                                         | API key lacks `identity:write` scope          |
| `404`  | `Verification not found`                  | The `idpf_` ID doesn't exist or isn't visible |


# Verification
Source: https://docs.whop.com/developer/verification/overview

Verify your users' identities before they can receive payouts. One API call starts KYC — we handle everything else.

## How it works

<Steps>
  <Step title="Start a verification">
    Call `POST /api/v1/verifications` with the account you want to verify. You get back a `session_url`.
  </Step>

  <Step title="Send the user to complete KYC">
    Redirect your user to the `session_url`. They upload their ID, take a selfie, and verify their identity on a hosted page. You don't build any UI for this.
  </Step>

  <Step title="Listen for the result">
    Subscribe to the `identity_profile.updated` webhook — it fires on every change to the profile (approved, rejected, needs action, or a review opening or clearing). The webhook tells you *which* profile changed, not its new state, so call `GET /api/v1/verifications?account_id={biz_ tag}` to read the current status and verified identity data.
  </Step>
</Steps>

## Quick example

```bash cURL theme={null}
curl -X POST "https://api.whop.com/api/v1/verifications?account_id=biz_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "individual"}'
```

```json Response theme={null}
{
  "id": "idpf_xxxxxxxxxxxxx",
  "kind": "individual",
  "status": "pending",
  "session_url": "https://in.sumsub.com/websdk/p/sbx_xxxxxxxxxxxxx",
  "created_at": "2026-06-03T22:15:00Z",
  "updated_at": "2026-06-03T22:15:00Z"
}
```

<Note>
  You need a Company API key with the `identity:write` scope. Go to your [dashboard](https://whop.com/dashboard) → Settings → API Keys to create one.
</Note>

## Pre-fill the KYC form

Pass identity fields to skip steps for your user. These seed the verification form so they don't have to retype their name and address:

```bash cURL theme={null}
curl -X POST "https://api.whop.com/api/v1/verifications?account_id=biz_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "individual",
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1995-01-15",
    "country": "US",
    "tax_identification_number": "123-45-6789",
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105"
    }
  }'
```

<Note>
  `tax_identification_number` is the person's tax identification number — their SSN for US
  individuals — and is **required when `country` is `US`**: the payout account
  can't be created without it. Send it as-is; it is tokenized in transit and
  the raw value is never stored on Whop's systems.
</Note>

## Reuse a verification you already have

If you already verified this person with Sumsub, send their share token instead of putting them
through KYC a second time. Whop imports the identity your Sumsub account attested and rechecks it
against Whop's own requirements:

```bash cURL theme={null}
curl -X POST "https://api.whop.com/api/v1/verifications?account_id=biz_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "individual", "share_token": "_act-sbx-jwt-eyJhbGciOiJub25l"}'
```

```json Response theme={null}
{
  "id": "idpf_xxxxxxxxxxxxx",
  "kind": "individual",
  "status": "approved",
  "first_name": "Jane",
  "last_name": "Doe",
  "created_at": "2026-06-03T22:15:00Z",
  "updated_at": "2026-06-03T22:15:00Z"
}
```

<Steps>
  <Step title="Agree on Reusable KYC with Whop">
    Sumsub only releases applicant data between clients that have a Reusable KYC agreement. Whop
    gives you the client ID to share with once that is in place.
  </Step>

  <Step title="Generate a share token for the applicant">
    Call `POST https://api.sumsub.com/resources/accessTokens/shareToken` on your own Sumsub account
    with the applicant's ID and Whop's client ID as `forClientId`.
  </Step>

  <Step title="Send it to Whop">
    Pass the token as `share_token`. Each token works once.
  </Step>
</Steps>

The response tells you where it landed. `approved` means your verification covered everything Whop
needs and there is nothing left to do. `pending` with a `session_url` means it covered part of it —
send the user to that URL to finish only what is still missing. A token whose data covers none of
Whop's requirements is rejected with a `400`.

<Note>
  `share_token` cannot be combined with `documents` or `document_type` — each is a complete
  alternative to the hosted flow.
</Note>

## Two types of verification

| Type             | `kind`       | What it verifies    | When to use                              |
| ---------------- | ------------ | ------------------- | ---------------------------------------- |
| Individual (KYC) | `individual` | A person's identity | User wants to withdraw funds             |
| Business (KYB)   | `business`   | A company entity    | Company needs to verify its legal entity |

An account can have one of each — an individual KYC and a business KYB.

## What's next

<CardGroup>
  <Card title="Check status" icon="magnifying-glass" href="/developer/verification/retrieve">
    Check verification status and read verified identity data.
  </Card>

  <Card title="Handle RFIs" icon="circle-exclamation" href="/developer/verification/rfis">
    Respond when we need additional information like a bank statement.
  </Card>

  <Card title="Update & delete" icon="pen-to-square" href="/developer/verification/manage">
    Update identity fields or remove a verification.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/verifications/verification">
    Full field reference for the verification object.
  </Card>
</CardGroup>


# Check status
Source: https://docs.whop.com/developer/verification/retrieve

List verifications for an account and read verified identity data.

## List verifications for an account

Pass the account's `biz_` tag as the `account_id` query parameter to get all verifications for that account. An account has at most two — one individual (KYC) and one business (KYB).

```bash cURL theme={null}
curl "https://api.whop.com/api/v1/verifications?account_id=biz_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

```json Response theme={null}
{
  "data": [
    {
      "id": "idpf_xxxxxxxxxxxxx",
      "kind": "individual",
      "status": "approved",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1995-01-15",
      "country": "US",
      "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105"
      },
      "requested_information": [],
      "created_at": "2026-06-03T22:15:00Z",
      "updated_at": "2026-06-04T10:00:00Z"
    }
  ]
}
```

## Retrieve a single verification

Pass an `idpf_` tag in the path to read one profile directly.

```bash cURL theme={null}
curl https://api.whop.com/api/v1/verifications/idpf_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

The response is a single verification object (the same shape as an entry in the list's `data` array).

## Statuses

| Status            | What it means                      | What to do                                                                                |
| ----------------- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
| `pending`         | User hasn't completed KYC yet      | Send them to `session_url`                                                                |
| `approved`        | Identity verified                  | User can transact                                                                         |
| `rejected`        | KYC declined                       | Create a new verification with `restart: true`                                            |
| `action_required` | More information is needed         | Check the `requested_information` array — see [Handle RFIs](/developer/verification/rfis) |
| `not_started`     | Profile exists, no session started | Call create to start                                                                      |

<Note>
  `session_url` only appears when `status` is `pending` — it means the user still needs to complete KYC. Once approved or rejected, the URL is gone.
</Note>

## Response fields

Fields depend on `kind`. Individual verifications return personal fields, business verifications return company fields.

### Individual (`kind: "individual"`)

| Field           | Type     | Description                  |
| --------------- | -------- | ---------------------------- |
| `first_name`    | `string` | Verified legal first name    |
| `last_name`     | `string` | Verified legal last name     |
| `date_of_birth` | `string` | ISO date (e.g. `1995-01-15`) |
| `country`       | `string` | ISO country code             |
| `address`       | `object` | Verified residential address |

### Business (`kind: "business"`)

| Field                | Type     | Description                                                                                                                                             |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business_name`      | `string` | Verified legal entity name                                                                                                                              |
| `business_structure` | `string` | Legal entity structure, such as `private_corporation` or `sole_proprietorship` — see [Business structures](/developer/verification/business-structures) |
| `country`            | `string` | ISO country code                                                                                                                                        |
| `address`            | `object` | Registered business address                                                                                                                             |

## Authentication

Requires a Company API key with the `identity:read` scope.

### Errors

| Status | Message                  | When                                                  |
| ------ | ------------------------ | ----------------------------------------------------- |
| `400`  | `account_id is required` | No `biz_` tag provided                                |
| `401`  | —                        | Missing or invalid API key                            |
| `403`  | —                        | API key lacks `identity:read` scope                   |
| `404`  | `Account not found`      | The `biz_` tag doesn't exist or you don't have access |


# Handle RFIs
Source: https://docs.whop.com/developer/verification/rfis

Respond when Whop needs more information — a document, tax ID, or business detail.

An **RFI** (Request for Information) is raised when Whop needs something extra from a user — a document, a tax ID, a business detail. Each open RFI appears as an item in the verification's `requested_information` array, and the verification's `status` becomes `action_required` until every item is answered.

Every item is one thing to collect, answered with one write: a `requirement` naming what is needed, an input `type` telling you how to collect it, and a `label` to show your user. Keys that don't apply to an item are left out entirely. See [every requirement](#every-requirement) for the full catalog.

## How RFIs work

<Steps>
  <Step title="Information is requested">
    Whop flags that something is needed. The verification status changes to `action_required` and an `identity_profile.updated` webhook fires. (`identity_profile.needs_action` fires for this transition too, but `identity_profile.updated` is the catch-all that covers every state change — subscribe to it and re-fetch the verification to see what's outstanding.)
  </Step>

  <Step title="You read the items">
    Call `GET /api/v1/verifications?account_id={biz_ tag}`. The `requested_information` array on each verification lists what's needed and what type of answer to collect.
  </Step>

  <Step title="You collect and submit">
    Get the info from your user and send it back via `PATCH /api/v1/verifications/{id}` with a `requested_information` array. We route each answer to the right place.
  </Step>

  <Step title="Review continues">
    Answered items leave the array. Once it's empty the verification moves to `processing` while the answers are reviewed — there is nothing to submit in that state. It settles on `approved`, or on `manual_review` if a compliance review opens. If an answer is rejected the item returns to `action_required` with `errors` explaining why; resubmit it.
  </Step>
</Steps>

## Reading RFIs

```bash cURL theme={null}
curl "https://api.whop.com/api/v1/verifications?account_id=biz_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

When RFIs are outstanding, the verification looks like:

```json theme={null}
{
  "id": "idpf_xxxxxxxxxxxxx",
  "kind": "individual",
  "status": "action_required",
  "requested_information": [
    {
      "id": "inrqi_xxxxxxxxxxxxx",
      "requirement": "date_of_birth",
      "type": "date",
      "label": "Date of Birth"
    },
    {
      "id": "inrqi_yyyyyyyyyyyyy",
      "requirement": "business_structure",
      "type": "select",
      "label": "Business Structure",
      "options": ["single_member_llc", "multi_member_llc", "sole_proprietorship", "private_corporation"]
    },
    {
      "id": "inrqi_zzzzzzzzzzzzz",
      "requirement": "bank_statement",
      "type": "files",
      "label": "Bank Statement for account ending in 4242"
    }
  ]
}
```

### Item fields

| Field         | Description                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `id`          | The item identifier, prefixed `inrqi_` — include it when submitting an answer                   |
| `requirement` | What is needed, such as `ssn` or `bank_statement` — see [every requirement](#every-requirement) |
| `type`        | What to send back: `files`, `id_document`, `text`, `date`, `phone`, `select`, or `address`      |
| `label`       | What to show your user. Carries the reviewer's own note when there is one                       |
| `options`     | Allowed values for a `select` item, or the accepted ID types on an `id_document` item           |
| `optional`    | Present as `true` when the item can be skipped                                                  |
| `errors`      | Present after a rejected answer, each with a stable `code` and a human-readable `reason`        |

Only the keys that apply to an item are returned, so an item never carries an empty array or a `null` you have to check for.

Only open items are returned — answered items leave the array, so anything still present is owed. The verification stays `action_required` until the array is empty.

## Answering RFIs

Send a `PATCH` to the verification's `idpf_` tag with a `requested_information` array. Each entry needs the item `id` and exactly one answer payload matching the item's `type`:

| Item `type`                       | Answer payload                                           |
| --------------------------------- | -------------------------------------------------------- |
| `files`                           | `files` — one document, as a list of its pages           |
| `id_document`                     | `documents` — the slot keys for the ID you are uploading |
| `text`, `date`, `phone`, `select` | `value`                                                  |
| `address`                         | `address` object                                         |

Nothing else from the item is echoed back — no categories, no document types. The item `id` tells us where the answer belongs.

You can answer several items in one request:

```bash cURL theme={null}
curl -X PATCH https://api.whop.com/api/v1/verifications/idpf_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_information": [
      { "id": "inrqi_xxxxxxxxxxxxx", "value": "1990-01-15" },
      { "id": "inrqi_yyyyyyyyyyyyy", "value": "single_member_llc" }
    ]
  }'
```

### Text, date, phone, and select values

Pass the answer as `value`. Dates use `YYYY-MM-DD`, phone numbers use E.164 format (`+12125550123`), and select values must be one of the item's `options`.

### Addresses

Pass an `address` object:

```bash cURL theme={null}
curl -X PATCH https://api.whop.com/api/v1/verifications/idpf_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_information": [
      {
        "id": "inrqi_xxxxxxxxxxxxx",
        "address": {
          "line1": "123 Spring Street",
          "city": "New York",
          "state": "NY",
          "postal_code": "10012",
          "country": "US"
        }
      }
    ]
  }'
```

PO boxes are not accepted for personal or business addresses.

### Documents

[Upload the file first](/developer/guides/upload-files), then pass its ID in `files`:

```bash cURL theme={null}
curl -X PATCH https://api.whop.com/api/v1/verifications/idpf_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_information": [
      { "id": "inrqi_zzzzzzzzzzzzz", "files": ["file_xxxxxxxxxxxxx"] }
    ]
  }'
```

Each entry takes either a `file_` ID from the [upload flow](/developer/guides/upload-files) or a `direct_upload_id` from a direct upload. Documents must be JPEG, PNG, or PDF, up to 32 MB. A one-page document is a list of one — there is no separate single-file field.

The `requirement` names the document we need, and we handle the rest — you never tell us what kind of document you uploaded.

#### Documents with several pages

A document with several pages goes in the same `files` list, in page order:

```json theme={null}
{ "id": "inrqi_aaa", "requirement": "business_verification_document", "type": "files",
  "label": "Company Verification Document" }
```

```json theme={null}
{ "id": "inrqi_aaa", "files": ["file_page1xxxxxx", "file_page2xxxxxx"] }
```

#### Identity documents

An `id_document` item asks which ID it is. It carries `options` listing the ID types the review accepts, and the answer names each slot with the same keys [Create Verification](/api-reference/beta/verifications/create-verification) takes:

```json theme={null}
{
  "id": "inrqi_bbb",
  "requirement": "identity_document",
  "type": "id_document",
  "label": "Identity Document",
  "options": ["ID_CARD", "DRIVERS", "RESIDENCE_PERMIT", "PASSPORT"]
}
```

```bash cURL theme={null}
curl -X PATCH https://api.whop.com/api/v1/verifications/idpf_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_information": [
      {
        "id": "inrqi_bbb",
        "documents": {
          "drivers_front": "file_frontxxxxxxx",
          "drivers_back": "file_backxxxxxxxx"
        }
      }
    ]
  }'
```

The key names the document and the side at once, so there is no separate field for which ID it is — we read it back off the keys. Send every slot for the one you are uploading:

| ID type            | Slots                                             |
| ------------------ | ------------------------------------------------- |
| `PASSPORT`         | `passport_front`                                  |
| `ID_CARD`          | `id_card_front`, `id_card_back`                   |
| `DRIVERS`          | `drivers_front`, `drivers_back`                   |
| `RESIDENCE_PERMIT` | `residence_permit_front`, `residence_permit_back` |

Mixing slots from two documents, or leaving one out, is rejected before anything is stored. The `options` on the item say which ID types that review accepts.

If a file item has no `options`, it needs no `value`.

### Sensitive values

Tax and government ID numbers (`ssn`, `ein`, `company_tax_id`, `personal_id_number`) are submitted like any other value. They are tokenized in transit before reaching Whop's systems, and only the tokenized reference is ever stored:

```bash cURL theme={null}
curl -X PATCH https://api.whop.com/api/v1/verifications/idpf_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_information": [
      { "id": "inrqi_xxxxxxxxxxxxx", "value": "123-45-6789" }
    ]
  }'
```

If you already tokenize values yourself (Basis Theory), pass the token ID with `value_type: "vault_token"` instead.

## Rejected answers

If a submitted answer is rejected, the item returns to `requested_information` with `errors` set:

```json theme={null}
{
  "id": "inrqi_xxxxxxxxxxxxx",
  "requirement": "business_website",
  "type": "text",
  "label": "Business website or social profile",
  "errors": [
    {
      "code": "invalid_url_website_inaccessible",
      "reason": "The website provided could not be reached."
    }
  ]
}
```

Show `reason` to your user and branch on `code` if you need to. Treat unrecognized codes as a generic rejection.

Fix the underlying issue and resubmit with the same item `id`. The verification stays `action_required` until the corrected answer is accepted.

### Document rejection codes

When an uploaded document is rejected, `code` names what was wrong with it. These are the codes you can receive:

| Code                           | Meaning                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `bad_proof_of_identity`        | Not an accepted proof of identity — a government-issued photo ID is required |
| `expiration_date`              | The document has expired                                                     |
| `unsatisfactory_photos`        | Too unclear to read                                                          |
| `problematic_applicant_data`   | Submitted details don't match the document                                   |
| `screenshots`                  | A screenshot was uploaded instead of a photo of the document                 |
| `graphic_editor`               | The document appears to have been edited                                     |
| `digital_document`             | A digital copy was uploaded; a photo of the physical document is required    |
| `document_damaged`             | Damaged or partly unreadable                                                 |
| `document_page_missing`        | A page is missing                                                            |
| `document_missing`             | The document was not received                                                |
| `not_document`                 | The file isn't a document                                                    |
| `id_invalid`                   | The identity document isn't valid                                            |
| `incompatible_language`        | Unsupported language; a certified translation is required                    |
| `bad_selfie`                   | The selfie was unclear                                                       |
| `bad_face_matching`            | The selfie didn't match the photo on the document                            |
| `bad_proof_of_address`         | Not an accepted proof of address                                             |
| `wrong_address`                | The address doesn't match the document                                       |
| `incorrect_social_number`      | The tax identification number doesn't match the document                     |
| `company_incorrect_data`       | Company details don't match the registration document                        |
| `company_data_mismatch`        | Company details don't match our records                                      |
| `company_inactive_entity`      | The company isn't listed as active in the registry                           |
| `additional_document_required` | Another document is needed                                                   |
| `more_documents_required`      | More documents are needed                                                    |
| `db_data_mismatch`             | Submitted details don't match official records                               |
| `spam`                         | The submission couldn't be processed                                         |

Every code here describes something about the upload that the person can fix. A rejection we can't attribute to one of them returns no `errors` at all rather than a code you can't act on — so always handle an item that carries no `errors`, and always prefer `reason` for anything shown to a user.

## Every requirement

Each item's `requirement` is one of the values below.

### Personal details

| Requirement             | Type      | What to submit                                                                            |
| ----------------------- | --------- | ----------------------------------------------------------------------------------------- |
| `first_name`            | `text`    | Legal first name, capitalized (`Jane`)                                                    |
| `last_name`             | `text`    | Legal last name, capitalized (`Doe`)                                                      |
| `creator_legal_name`    | `text`    | Full legal name as it appears on official documents                                       |
| `date_of_birth`         | `date`    | `YYYY-MM-DD`                                                                              |
| `email`                 | `text`    | Email address                                                                             |
| `creator_email_address` | `text`    | An email address where we can reach the user                                              |
| `phone_number`          | `phone`   | E.164 format with country code (`+12125550123`)                                           |
| `personal_address`      | `address` | Current residential address — no PO boxes                                                 |
| `occupation`            | `text`    | SOC occupation code (`15-1132`), or `SELFEMP`, `STUDENT`, `RETIRED`, `UNEMPLO`, `OTHERXX` |
| `annual_salary`         | `text`    | Approximate yearly income in USD, digits only                                             |

### Tax and government ID numbers

These values are tokenized in transit — see [sensitive values](#sensitive-values).

| Requirement                  | Type     | What to submit                                                                 |
| ---------------------------- | -------- | ------------------------------------------------------------------------------ |
| `ssn`                        | `text`   | US Social Security Number, `XXX-XX-XXXX`                                       |
| `ein`                        | `text`   | US Employer Identification Number, `XX-XXXXXXX`                                |
| `company_tax_id`             | `text`   | Company tax ID in the issuing country's format                                 |
| `personal_id_number`         | `text`   | Government-issued personal ID number (passport, driver's license, national ID) |
| `personal_id_number_country` | `select` | Country that issued the ID number — pick from `options`                        |
| `country_of_issue`           | `text`   | Two-letter country code of the issuing country (`US`)                          |

### Identity documents

| Requirement         | Type          | What to submit                                                                            |
| ------------------- | ------------- | ----------------------------------------------------------------------------------------- |
| `identity_document` | `id_document` | Government-issued photo ID. Send `documents` with the slot keys for the ID being uploaded |
| `selfie`            | `files`       | Photo of the user holding their ID                                                        |

### Business details

| Requirement                     | Type      | What to submit                                                                                             |
| ------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
| `business_name`                 | `text`    | Legal name the business is registered under                                                                |
| `trade_name`                    | `text`    | Public-facing name if different from the legal name (DBA)                                                  |
| `company_title`                 | `text`    | The company's name                                                                                         |
| `business_structure`            | `select`  | Legal structure — one of `options`, e.g. `single_member_llc`, `sole_proprietorship`, `private_corporation` |
| `account_type`                  | `select`  | `individual`, `company`, or `non_profit`                                                                   |
| `business_representative_title` | `select`  | Representative's title — one of `options`, e.g. `CEO`, `Owner`, `Manager`                                  |
| `industry_type`                 | `text`    | Industry the business operates in                                                                          |
| `business_description`          | `text`    | 100–1000 characters: what is sold, what customers receive after payment, and where they access it          |
| `product_description`           | `text`    | The product or service sold                                                                                |
| `business_phone_number`         | `phone`   | E.164 format with country code                                                                             |
| `business_address`              | `address` | Registered business address — no PO boxes                                                                  |
| `business_website`              | `text`    | Business website URL                                                                                       |
| `social_media_or_website`       | `text`    | Website, or a public social profile that represents what is sold                                           |
| `store_page_url`                | `text`    | Link to the store or product page                                                                          |
| `expected_monthly_volume`       | `text`    | Expected monthly processing volume in USD, digits only                                                     |
| `account_purpose`               | `text`    | What the account is primarily used for                                                                     |

### Business documents

| Requirement                      | Type              | What to submit                                                                                     |
| -------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| `business_verification_document` | `files`           | Document confirming the company's legal identity — IRS Letter 147C, SS-4, or EIN Assistance Letter |
| `business_incorporation_papers`  | `files`           | Official incorporation documents                                                                   |
| `ownership_structure`            | `files`           | Documents showing who owns the business                                                            |
| `processing_statements`          | `files`           | Statements from a previous payment processor showing processing history — not bank statements      |
| `proof_of_fulfillment`           | `files`           | Screenshot, recording, or file showing what customers receive after purchase                       |
| `proof_of_funnel`                | `text` or `files` | Where customers come from — a social account, website, or landing page                             |

### Payout account documents

A document requested to verify a payout destination names the document itself. Upload one file — the `label` tells your user which account it's for.

| Requirement         | Type    | What to submit                                   |
| ------------------- | ------- | ------------------------------------------------ |
| `bank_statement`    | `files` | Recent bank statement for the payout account     |
| `paper_check`       | `files` | Voided paper check                               |
| `wallet_screenshot` | `files` | Screenshot of a wallet or account balance        |
| `government_id`     | `files` | Government-issued ID                             |
| `proof_of_address`  | `files` | Proof of address issued within the last 3 months |
| `utility_bill`      | `files` | Utility bill issued within the last 3 months     |
| `insurance_card`    | `files` | Insurance card issued within the last 3 months   |
| `company_documents` | `files` | Company or entity documents                      |

### Review questions

| Requirement     | Type              | What to submit                                      |
| --------------- | ----------------- | --------------------------------------------------- |
| `anything_else` | `text` or `files` | Anything else the review team should know           |
| `accept_tos`    | `text`            | Confirmation that the terms of service are accepted |
| `signature`     | `files`           | Signature image for an agreement                    |


# Enable Apple Pay
Source: https://docs.whop.com/payments/apple-pay

Enable Apple Pay for your embedded checkout by verifying your domain

Apple Pay allows customers to pay using their Apple Wallet, providing a seamless checkout experience on Safari and iOS devices. To enable Apple Pay on your embedded checkout, you need to verify ownership of your domain.

<Note>
  Domain verification is only required for [embedded
  checkout](/payments/checkout-embed). Whop-hosted checkout pages already
  support Apple Pay without any additional setup.
</Note>

## Prerequisites

Before setting up Apple Pay, ensure you have:

* A domain where you're hosting the embedded checkout
* Access to your domain's DNS settings (for Whop-hosted verification) or file hosting (for self-hosted verification)
* `@whop/checkout@0.0.43` or later if using the `hideSubmitButton` option in React

## Choose a verification method

There are two ways to verify your domain for Apple Pay:

<CardGroup>
  <Card title="Whop-hosted verification" icon="wand-magic-sparkles" href="#whop-hosted-verification">
    Recommended for most users. Whop handles the verification file hosting - you
    just need to add DNS records.
  </Card>

  <Card title="Self-hosted verification" icon="server" href="#self-hosted-verification">
    For advanced users who prefer to host the verification file themselves.
  </Card>
</CardGroup>

## Whop-hosted verification

This method lets Whop host the Apple Pay verification file on your behalf. You'll temporarily point your domain to Whop's servers to complete verification, then revert your DNS settings.

<Warning>
  This method requires temporary DNS changes that will cause your domain to be
  unavailable for a few minutes during verification. Plan accordingly.
</Warning>

<Note>
  **Before you begin:** Take a screenshot or export your current DNS records for
  the domain you're verifying. While the verification wizard will show revert
  instructions after completion, these are best-effort and may not capture all
  edge cases. Having your own backup ensures you can restore your DNS
  configuration accurately.
</Note>

### Step 0: Lower your DNS TTL (optional)

If the domain you're verifying is actively serving traffic, consider lowering the TTL (Time To Live) on the existing DNS record for that domain before starting. This ensures DNS changes propagate faster when you switch records and when you revert them. If you skip this step, downtime may last longer while DNS caches expire.

<Accordion title="How to lower your TTL">
  1. Find the existing A or CNAME record for the domain you want to verify
     (e.g., the record for `checkout.yoursite.com`) 2. Lower its TTL to 60-300
     seconds 3. Wait for the previous TTL duration to pass (e.g., if it was 1 hour,
     wait 1 hour) so all DNS caches refresh 4. Then proceed with the verification
     steps below
</Accordion>

### Step 1: Open payment domains settings

Navigate to your [checkout settings](https://whop.com/dashboard/settings/checkout/) and find the **Apple Pay for embedded checkout** section. Click **Configure** to open the domain management panel.

<Frame>
  <img alt="Payment domains settings showing the Configure button" />
</Frame>

### Step 2: Add your domain

Click the **+** button (or **Add payment domain** if no domains exist yet). From the dropdown menu, select **Whop-hosted verification**.

<Frame>
  <img alt="Add domain dropdown menu with Whop-hosted option" />
</Frame>

Enter the domain where you're hosting the embedded checkout (e.g., `checkout.yoursite.com` or `yoursite.com`). You'll need to acknowledge that your domain will experience temporary downtime during the verification process by checking the confirmation checkbox, then click **Start verification**.

<Frame>
  <img alt="Add domain dialog for Whop-hosted verification" />
</Frame>

### Step 3: Add DNS records

<Warning>
  This step will cause downtime for your domain. Your domain will point to
  Whop's servers until you revert the DNS records after verification. **If you
  haven't already, take a screenshot of your current DNS settings now** before
  making any changes.
</Warning>

After adding your domain, you'll see a list of DNS records that need to be added to your domain's DNS settings. These typically include:

* **A record** or **CNAME record** - Points your domain to Whop's verification servers
* (optional) **TXT record** - Proves domain ownership

<Tip>
  Use a low TTL (60-300 seconds) so you can revert quickly after verification.
</Tip>

<Frame>
  <img alt="DNS records to add for domain verification" />
</Frame>

If your domain already has an A or CNAME record, **edit or replace it** with the values shown—don't add a second record alongside the existing one. You can find these settings in your DNS provider's dashboard (e.g., Cloudflare, Namecheap, GoDaddy, Route 53).

<Frame>
  <img alt="DNS records configured in Cloudflare" />
</Frame>

### Step 4: Wait for DNS propagation

DNS changes can take anywhere from a few minutes to 48 hours to propagate, though most changes are visible within 5-15 minutes. The verification wizard will automatically detect when your DNS records are properly configured.

### Step 5: Complete verification

Once the DNS records are verified, Whop will:

1. Issue an SSL certificate for your domain
2. Host the Apple Pay verification file
3. Register your domain with Apple

### Step 6: Revert DNS settings

After verification is complete, revert your DNS settings to point back to your original hosting. The Apple Pay verification will remain valid. The wizard will show you the records to delete and restore.

<Warning>
  The revert instructions shown in the wizard are **best-effort** and may not be
  100% accurate in all cases. Always refer to your own DNS backup (screenshot or
  export) to ensure you restore the correct values. If you're unsure, check with
  your hosting provider for the correct DNS configuration.
</Warning>

<Frame>
  <img alt="Domain verification complete with revert instructions" />
</Frame>

## Self-hosted verification

If you prefer to host the verification file yourself, you can do so by serving the Apple Pay merchant ID domain association file at a specific path on your domain.

### Step 1: Download the verification file

Download the [Apple Pay verification file](https://whop.com/.well-known/apple-platform-integrator/apple-developer-merchantid-domain-association).

### Step 2: Host the file

Host this file at the following path on your domain:

```
https://<your-domain>/.well-known/apple-developer-merchantid-domain-association
```

The file must be:

* Served over HTTPS
* Accessible without authentication
* Served with the correct content (no modifications)

<Tabs>
  <Tab title="Next.js">
    Place the file in your `public` folder:

    ```
    public/
    └── .well-known/
        └── apple-developer-merchantid-domain-association
    ```
  </Tab>

  <Tab title="Nginx">
    Add a location block to serve the file:

    ```nginx theme={null}
    location /.well-known/apple-developer-merchantid-domain-association {
        alias /path/to/apple-developer-merchantid-domain-association;
        default_type application/octet-stream;
    }
    ```
  </Tab>

  <Tab title="Vercel">
    Create a `vercel.json` with a rewrite rule that proxies to the Whop-hosted file:

    ```json theme={null}
    {
      "rewrites": [
        {
          "source": "/.well-known/apple-developer-merchantid-domain-association",
          "destination": "https://whop.com/.well-known/apple-platform-integrator/apple-developer-merchantid-domain-association"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Cloudflare Pages">
    Place the file in your output directory:

    ```
    dist/
    └── .well-known/
        └── apple-developer-merchantid-domain-association
    ```
  </Tab>
</Tabs>

### Step 3: Verify the file is accessible

Test that the file is accessible by visiting:

```
https://<your-domain>/.well-known/apple-developer-merchantid-domain-association
```

The file should download or display its contents without any errors.

### Step 4: Open payment domains settings

Navigate to your [checkout settings](https://whop.com/dashboard/settings/checkout/) and find the **Apple Pay for embedded checkout** section. Click **Configure** to open the domain management panel.

<Frame>
  <img alt="Payment domains settings showing the Configure button" />
</Frame>

### Step 5: Register your domain

Click the **+** button (or **Add payment domain** if no domains exist yet). From the dropdown menu, select **Self-hosted verification**.

<Frame>
  <img alt="Add domain dropdown menu with self-hosted option" />
</Frame>

Enter your domain. Whop will verify that the file is accessible before registering your domain with Apple.

<Frame>
  <img alt="Add domain dialog for self-hosted verification" />
</Frame>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Apple Pay button doesn't appear">
    * Ensure your domain is fully verified in the payment domains settings -
      Check that you're using `@whop/checkout@0.0.43` or later - Apple Pay only
      appears on supported browsers (Safari) and devices (iOS, macOS) - Test on an
      actual Apple device, not in a simulator - If using **Framer**, make sure you
      are loading the checkout SDK via Custom Code in your site headers, not via
      the Embed component. Framer's Embed component uses a `srcdoc` iframe which
      Safari treats as an insecure context, blocking Apple Pay. See the [Framer
      checkout
      guide](/third-party-integrations/embedded-checkouts/framer-checkout) for the
      correct setup.
  </Accordion>

  <Accordion title="DNS verification is taking too long">
    * DNS propagation can take up to 48 hours in some cases - Use a tool like
      [dnschecker.org](https://dnschecker.org) to verify your records have
      propagated - Ensure you've added the records to the correct DNS zone - If
      using Cloudflare, make sure the DNS record is set to "DNS only" (gray
      cloud), not "Proxied" (orange cloud) during verification
  </Accordion>

  <Accordion title="SSL certificate verification failed">
    * Ensure your DNS records are pointing to the correct values - Wait a few
      minutes for the certificate to be issued - If the issue persists, try
      removing and re-adding the domain
  </Accordion>

  <Accordion title="Self-hosted file returns 404">
    * Verify the file is in the correct location:
      `/.well-known/apple-developer-merchantid-domain-association` - Check that
      your web server is configured to serve files without extensions - Ensure the
      `.well-known` directory is not blocked by your hosting configuration
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Embedded Checkout" icon="code" href="/payments/checkout-embed">
    Learn how to embed Whop checkout on your website
  </Card>

  <Card title="Checkout Links" icon="link" href="/payments/create-checkout-link">
    Create shareable checkout links for your products
  </Card>
</CardGroup>


# Ai Chat
Source: https://docs.whop.com/api-reference/ai-chats/ai-chat

An AI-powered chat conversation belonging to a user, with optional scheduled automation.

<ResponseExample>
  ```json Example theme={null}
  {
  	"blended_token_usage": "123.45",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"id": "aich_xxxxxxxxxxxxx",
  	"last_message_at": "2023-12-01T05:00:00.401Z",
  	"message_count": 42,
  	"notification_preference": "all",
  	"title": "Weekly Revenue Analysis",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"id": "user_xxxxxxxxxxxxx"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="blended_token_usage" type="string">
  The total number of tokens consumed across all messages in this conversation.

  Example: `123.45`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the ai chat was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the ai chat.

  Example: `aich_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="last_message_at" type="string<date-time> | null">
  The timestamp of the most recent message in this conversation. Null if no messages have been sent yet.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="message_count" type="integer">
  The total number of messages exchanged in this conversation.

  Example: `42`
</ResponseField>

<ResponseField name="notification_preference" type="AiChatNotificationPreferences">
  The notification preference for this AI chat. `all` delivers AI chat notifications and badges, while `none` mutes them.

  Available options: `all`, `none`
</ResponseField>

<ResponseField name="title" type="string | null">
  A short descriptive title for this AI chat conversation. Null if no title has been set.

  Example: `Weekly Revenue Analysis`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the ai chat was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object">
  The user who owns this AI chat conversation.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>


# Create ai chat
Source: https://docs.whop.com/api-reference/ai-chats/create-ai-chat

/openapi/api-v1-stable.json post /ai_chats
Create a new AI chat thread and send the first message to the AI agent.

Required permissions:
 - `ai_chat:create`



# Delete ai chat
Source: https://docs.whop.com/api-reference/ai-chats/delete-ai-chat

/openapi/api-v1-stable.json delete /ai_chats/{id}
Delete an AI chat thread so it no longer appears in the user's chat list.

Required permissions:
 - `ai_chat:delete`



# List ai chats
Source: https://docs.whop.com/api-reference/ai-chats/list-ai-chats

/openapi/api-v1-stable.json get /ai_chats
Returns a paginated list of AI chat threads for the current authenticated user.



# Retrieve ai chat
Source: https://docs.whop.com/api-reference/ai-chats/retrieve-ai-chat

/openapi/api-v1-stable.json get /ai_chats/{id}
Retrieves the details of an existing AI chat.



# Update ai chat
Source: https://docs.whop.com/api-reference/ai-chats/update-ai-chat

/openapi/api-v1-stable.json patch /ai_chats/{id}
Update an AI chat's title, notification preferences, or associated company context.

Required permissions:
 - `ai_chat:update`



# Authorized User
Source: https://docs.whop.com/api-reference/authorized-users/authorized-user

A user who has been granted administrative access to manage a company's dashboard and settings.

<ResponseExample>
  ```json Example theme={null}
  {
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"title": "Pickaxe"
  	},
  	"id": "ausr_xxxxxxxxxxxxx",
  	"role": "owner",
  	"user": {
  		"email": "john.doe@example.com",
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="company" type="object">
  The company this authorized user has access to.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the authorized user.

  Example: `ausr_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="role" type="AuthorizedUserRoles">
  The permission role assigned to this authorized user within the company.

  Available options: `owner`, `admin`, `sales_manager`, `moderator`, `advertiser`, `app_manager`, `support`, `manager`, `custom`
</ResponseField>

<ResponseField name="user" type="object">
  The user account linked to this authorized user record.

  <Expandable title="child attributes">
    <ResponseField name="email" type="string | null">
      The user's email address. Requires the member:email:read permission to access. Null if not authorized.

      Example: `john.doe@example.com`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# Create authorized user
Source: https://docs.whop.com/api-reference/authorized-users/create-authorized-user

/openapi/api-v1-stable.json post /authorized_users
Add a new authorized user to a company.

Required permissions:
 - `authorized_user:create`
 - `member:email:read`



# Delete authorized user
Source: https://docs.whop.com/api-reference/authorized-users/delete-authorized-user

/openapi/api-v1-stable.json delete /authorized_users/{id}
Remove an authorized user from a company.

Required permissions:
 - `authorized_user:delete`



# List authorized users
Source: https://docs.whop.com/api-reference/authorized-users/list-authorized-users

/openapi/api-v1-stable.json get /authorized_users
Returns a paginated list of authorized team members for a company, with optional filtering by user, role, and creation date.

Required permissions:
 - `company:authorized_user:read`
 - `member:email:read`



# Retrieve authorized user
Source: https://docs.whop.com/api-reference/authorized-users/retrieve-authorized-user

/openapi/api-v1-stable.json get /authorized_users/{id}
Retrieves the details of an existing authorized user.

Required permissions:
 - `company:authorized_user:read`
 - `member:email:read`



# Create bounty
Source: https://docs.whop.com/api-reference/bounties/create-bounty

/openapi/api-v1-stable.json post /bounties
Create a new workforce bounty by funding a dedicated bounty pool.

Required permissions:
 - `bounty:create`



# List bounties
Source: https://docs.whop.com/api-reference/bounties/list-bounties

/openapi/api-v1-stable.json get /bounties
Returns a paginated list of workforce bounties. When experienceId is provided, returns bounties scoped to that experience. When omitted, returns bounties with no experience.



# Retrieve bounty
Source: https://docs.whop.com/api-reference/bounties/retrieve-bounty

/openapi/api-v1-stable.json get /bounties/{id}
Retrieves a workforce bounty for the current authenticated user.



# Workforce Bounty
Source: https://docs.whop.com/api-reference/bounties/workforce-bounty

A privately accessible bounty.

<ResponseExample>
  ```json Example theme={null}
  {
  	"bounty_type": "classic",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"description": "<string>",
  	"id": "bnty_xxxxxxxxxxxxx",
  	"status": "published",
  	"title": "<string>",
  	"total_available": 6.9,
  	"total_paid": 6.9,
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"vote_threshold": 42
  }
  ```
</ResponseExample>

<ResponseField name="bounty_type" type="BountyTypes">
  The underlying bounty implementation type.

  Available options: `classic`, `user_funded`, `workforce`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the bounty was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies">
  The currency used for the bounty funds.

  Available options: `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`
</ResponseField>

<ResponseField name="description" type="string">
  The description of the bounty.
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the bounty.

  Example: `bnty_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="status" type="Statuses">
  The current lifecycle status of the bounty.

  Available options: `published`, `archived`, `scheduled`
</ResponseField>

<ResponseField name="title" type="string">
  The title of the bounty.
</ResponseField>

<ResponseField name="total_available" type="number">
  The total amount currently funded in the bounty pool for payout.

  Example: `6.9`
</ResponseField>

<ResponseField name="total_paid" type="number">
  The total amount paid out for this bounty.

  Example: `6.9`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the bounty was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="vote_threshold" type="integer">
  The number of watcher votes required before the submission can resolve.

  Example: `42`
</ResponseField>


# Card Transaction
Source: https://docs.whop.com/api-reference/card-transactions/card-transaction

A card transaction record.

<ResponseExample>
  ```json Example theme={null}
  {
  	"authorization_method": "ecommerce",
  	"card_id": "<string>",
  	"cashback_usd_amount": 6.9,
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "USD",
  	"declined_reason": "insufficient_funds",
  	"id": "<string>",
  	"international": true,
  	"local_amount": 6.9,
  	"memo": "Team dinner",
  	"merchant_category": "Software",
  	"merchant_category_code": "5734",
  	"merchant_icon_url": "https://logo.clearbit.com/example.com",
  	"merchant_name": "Acme Corporation",
  	"posted_at": "2023-12-01T05:00:00.401Z",
  	"status": "pending",
  	"transaction_type": "spend",
  	"usd_amount": 6.9
  }
  ```
</ResponseExample>

<ResponseField name="authorization_method" type="string | null">
  How the card was presented or authenticated for the purchase.

  Example: `ecommerce`
</ResponseField>

<ResponseField name="card_id" type="string" />

<ResponseField name="cashback_usd_amount" type="number | null">
  The cashback reward amount earned on this transaction, in USD.

  Example: `6.9`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the card transaction was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="string | null">
  The ISO 4217 currency code for the transaction amount.

  Example: `USD`
</ResponseField>

<ResponseField name="declined_reason" type="string | null">
  The issuer-provided reason the transaction was declined.

  Example: `insufficient_funds`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the card transaction.
</ResponseField>

<ResponseField name="international" type="boolean">
  Whether the transaction was made with a merchant outside the card's home
  country.
</ResponseField>

<ResponseField name="local_amount" type="number | null">
  The transaction amount in the merchant's local currency before conversion.

  Example: `6.9`
</ResponseField>

<ResponseField name="memo" type="string | null">
  A user-provided note attached to the transaction.

  Example: `Team dinner`
</ResponseField>

<ResponseField name="merchant_category" type="string | null">
  The enriched or raw category label for the merchant.

  Example: `Software`
</ResponseField>

<ResponseField name="merchant_category_code" type="string | null">
  The four-digit ISO 18245 merchant category code (MCC).

  Example: `5734`
</ResponseField>

<ResponseField name="merchant_icon_url" type="string | null">
  A URL to the enriched merchant logo image.

  Example: `https://logo.clearbit.com/example.com`
</ResponseField>

<ResponseField name="merchant_name" type="string | null">
  The enriched or raw name of the merchant where the purchase was made.

  Example: `Acme Corporation`
</ResponseField>

<ResponseField name="posted_at" type="string<date-time> | null">
  When the transaction was settled by the card network.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="status" type="CardIssuingTransactionStatus">
  The current lifecycle status of the transaction.

  Available options: `pending`, `completed`, `reversed`, `declined`
</ResponseField>

<ResponseField name="transaction_type" type="string">
  The type of transaction.

  Example: `spend`
</ResponseField>

<ResponseField name="usd_amount" type="number | null">
  The transaction amount in USD.

  Example: `6.9`
</ResponseField>


# Cardtransaction completed
Source: https://docs.whop.com/api-reference/card-transactions/cardtransaction-completed

/openapi/api-v1-stable.json webhook card_transaction.completed
Sent when a card transaction is completed

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Cardtransaction created
Source: https://docs.whop.com/api-reference/card-transactions/cardtransaction-created

/openapi/api-v1-stable.json webhook card_transaction.created
Sent when a card transaction is created

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Cardtransaction declined
Source: https://docs.whop.com/api-reference/card-transactions/cardtransaction-declined

/openapi/api-v1-stable.json webhook card_transaction.declined
Sent when a card transaction is declined

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Cardtransaction reversed
Source: https://docs.whop.com/api-reference/card-transactions/cardtransaction-reversed

/openapi/api-v1-stable.json webhook card_transaction.reversed
Sent when a card transaction is reversed

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Cardtransaction updated
Source: https://docs.whop.com/api-reference/card-transactions/cardtransaction-updated

/openapi/api-v1-stable.json webhook card_transaction.updated
Sent when a card transaction is updated

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# List card transactions
Source: https://docs.whop.com/api-reference/card-transactions/list-card-transactions

/openapi/api-v1-stable.json get /card_transactions
Returns a paginated list of card transactions for a company.

Required permissions:
 - `payout:account:read`



# Retrieve card transaction
Source: https://docs.whop.com/api-reference/card-transactions/retrieve-card-transaction

/openapi/api-v1-stable.json get /card_transactions/{id}
Retrieves a single card transaction by ID.

Required permissions:
 - `payout:account:read`



# Chat Channel
Source: https://docs.whop.com/api-reference/chat-channels/chat-channel

A real-time chat feed attached to an experience, with configurable moderation and posting permissions.

<ResponseExample>
  ```json Example theme={null}
  {
  	"ban_media": true,
  	"ban_urls": true,
  	"banned_words": ["<string>"],
  	"experience": {
  		"id": "exp_xxxxxxxxxxxxxx",
  		"name": "Trading Signals Chat"
  	},
  	"id": "<string>",
  	"user_posts_cooldown_seconds": 42,
  	"who_can_post": "everyone",
  	"who_can_react": "everyone"
  }
  ```
</ResponseExample>

<ResponseField name="ban_media" type="boolean">
  Whether media uploads such as images and videos are blocked in this chat.
</ResponseField>

<ResponseField name="ban_urls" type="boolean">
  Whether URL links are blocked from being posted in this chat.
</ResponseField>

<ResponseField name="banned_words" type="array<string>">
  A list of words that are automatically filtered from messages in this chat.
</ResponseField>

<ResponseField name="experience" type="object">
  The experience this chat feed is attached to.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the experience.

      Example: `exp_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of this experience shown to users in the product navigation. Maximum 255 characters.

      Example: `Trading Signals Chat`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the entity
</ResponseField>

<ResponseField name="user_posts_cooldown_seconds" type="integer | null">
  The minimum number of seconds a user must wait between consecutive messages. Null if no cooldown is enforced.

  Example: `42`
</ResponseField>

<ResponseField name="who_can_post" type="WhoCanPostTypes">
  The permission level controlling which users can send messages in this chat.

  Available options: `everyone`, `admins`
</ResponseField>

<ResponseField name="who_can_react" type="WhoCanReactTypes">
  The permission level controlling which users can add reactions in this chat.

  Available options: `everyone`, `no_one`
</ResponseField>


# List chat channels
Source: https://docs.whop.com/api-reference/chat-channels/list-chat-channels

/openapi/api-v1-stable.json get /chat_channels
Returns a paginated list of chat channels within a specific company, with optional filtering by product.

Required permissions:
 - `chat:read`



# Retrieve chat channel
Source: https://docs.whop.com/api-reference/chat-channels/retrieve-chat-channel

/openapi/api-v1-stable.json get /chat_channels/{id}
Retrieves the details of an existing chat channel.

Required permissions:
 - `chat:read`



# Update chat channel
Source: https://docs.whop.com/api-reference/chat-channels/update-chat-channel

/openapi/api-v1-stable.json patch /chat_channels/{id}
Update moderation settings for a chat channel, such as who can post, banned words, and media restrictions.

Required permissions:
 - `chat:moderate`



# Company
Source: https://docs.whop.com/api-reference/companies/company

A company is a seller on Whop. Companies own products, manage members, and receive payouts.

<ResponseExample>
  ```json Example theme={null}
  {
  	"affiliate_instructions": "Share your unique link on social media to earn 20% commission.",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"description": "Learn the fundamentals of data analytics with hands-on projects.",
  	"featured_affiliate_product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"name": "<string>"
  	},
  	"id": "biz_xxxxxxxxxxxxxx",
  	"logo": {
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"member_count": 42,
  	"metadata": {},
  	"owner_user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	},
  	"published_reviews_count": 42,
  	"route": "pickaxe",
  	"send_customer_emails": true,
  	"social_links": [
  		{
  			"id": "soci_xxxxxxxxxxxxx",
  			"url": "https://x.com/whop",
  			"website": "x"
  		}
  	],
  	"target_audience": "<string>",
  	"title": "Pickaxe",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"verified": true
  }
  ```
</ResponseExample>

<ResponseField name="affiliate_instructions" type="string | null">
  Guidelines and instructions provided to affiliates explaining how to promote this company's products.

  Example: `Share your unique link on social media to earn 20% commis…`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the company was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="description" type="string | null">
  A promotional pitch written by the company creator, displayed to potential customers on the store page.

  Example: `Learn the fundamentals of data analytics with hands-on pr…`
</ResponseField>

<ResponseField name="featured_affiliate_product" type="object | null">
  The product featured for affiliates to promote on this company's affiliate page. Null if none is configured.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the product shown to customers. Maximum 50 characters.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the company.

  Example: `biz_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="logo" type="object | null">
  The company's logo.

  <Expandable title="child attributes">
    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="member_count" type="integer">
  The total number of users who currently hold active memberships across all of this company's products.

  Example: `42`
</ResponseField>

<ResponseField name="metadata" type="object | null">
  A key-value JSON object of custom metadata for this company, managed by the
  platform that created the account.
</ResponseField>

<ResponseField name="owner_user" type="object">
  The user who owns and has full administrative control over this company.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="published_reviews_count" type="integer">
  The total number of published customer reviews across all products for this company.

  Example: `42`
</ResponseField>

<ResponseField name="route" type="string">
  URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.

  Example: `pickaxe`
</ResponseField>

<ResponseField name="send_customer_emails" type="boolean">
  Whether Whop sends transactional emails (receipts, updates) to customers on
  behalf of this company.
</ResponseField>

<ResponseField name="social_links" type="array<object>">
  The list of social media accounts and external links associated with this company.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the social link.

      Example: `soci_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="url" type="string">
      The URL of the social media profile or external link.

      Example: `https://x.com/whop`
    </ResponseField>

    <ResponseField name="website" type="SocialLinkWebsites">
      The website

      Available options: `x`, `instagram`, `facebook`, `tiktok`, `youtube`, `linkedin`, `twitch`, `website`, `custom`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="target_audience" type="string | null">
  The target audience for the company. Null if not set.
</ResponseField>

<ResponseField name="title" type="string">
  The display name of the company shown to customers.

  Example: `Pickaxe`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the company was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="verified" type="boolean">
  Whether this company has been verified by Whop's trust and safety team.
</ResponseField>


# Create child company API key
Source: https://docs.whop.com/api-reference/companies/create-child-company-api-key

/openapi/api-v1-stable.json post /companies/{parent_company_id}/api_keys
Create an API key for a connected account (child company) owned by a parent company.



# Create company
Source: https://docs.whop.com/api-reference/companies/create-company

/openapi/api-v1-stable.json post /companies
Create a new company. Pass parent_company_id to create a connected account under a platform, or omit it to create a company for the current user.

Required permissions:
 - `company:create`
 - `company:basic:read`



# List companies
Source: https://docs.whop.com/api-reference/companies/list-companies

/openapi/api-v1-stable.json get /companies
Returns a paginated list of companies. When parent_company_id is provided, lists connected accounts under that platform. When omitted, lists companies the current user has access to.

Required permissions:
 - `company:basic:read`



# Retrieve company
Source: https://docs.whop.com/api-reference/companies/retrieve-company

/openapi/api-v1-stable.json get /companies/{id}
Retrieves the details of an existing company.

Required permissions:
 - `company:basic:read`



# Update company
Source: https://docs.whop.com/api-reference/companies/update-company

/openapi/api-v1-stable.json patch /companies/{id}
Update a company's title, description, logo, and other settings.

Required permissions:
 - `company:update`
 - `company:basic:read`



# Create dm channel
Source: https://docs.whop.com/api-reference/dm-channels/create-dm-channel

/openapi/api-v1-stable.json post /dm_channels
Create a new DM channel between two or more users, optionally scoped to a specific company. Returns the existing channel if one already exists.



# Delete dm channel
Source: https://docs.whop.com/api-reference/dm-channels/delete-dm-channel

/openapi/api-v1-stable.json delete /dm_channels/{id}
Permanently delete a DM channel and all of its messages. Only an admin of the channel can perform this action.

Required permissions:
 - `dms:channel:manage`



# Dm Channel
Source: https://docs.whop.com/api-reference/dm-channels/dm-channel

A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.

<ResponseExample>
  ```json Example theme={null}
  {
  	"created_at": "123.45",
  	"id": "<string>",
  	"last_message_at": "2023-12-01T05:00:00.401Z",
  	"name": "Project Alpha Team"
  }
  ```
</ResponseExample>

<ResponseField name="created_at" type="string">
  The time the entity was created (in milliseconds since Unix epoch)

  Example: `123.45`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the entity
</ResponseField>

<ResponseField name="last_message_at" type="string<date-time> | null">
  The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="name" type="string | null">
  A custom display name assigned to this channel by the user. Null if no custom name has been set.

  Example: `Project Alpha Team`
</ResponseField>


# List dm channels
Source: https://docs.whop.com/api-reference/dm-channels/list-dm-channels

/openapi/api-v1-stable.json get /dm_channels
Returns a paginated list of DM channels for the currently authenticated user, sorted by most recently active.

Required permissions:
 - `dms:read`



# Retrieve dm channel
Source: https://docs.whop.com/api-reference/dm-channels/retrieve-dm-channel

/openapi/api-v1-stable.json get /dm_channels/{id}
Retrieves the details of an existing DM channel.

Required permissions:
 - `dms:read`



# Update dm channel
Source: https://docs.whop.com/api-reference/dm-channels/update-dm-channel

/openapi/api-v1-stable.json patch /dm_channels/{id}
Update the settings of an existing DM channel, such as its display name. Only an admin of the channel can perform this action.

Required permissions:
 - `dms:channel:manage`



# Create dm member
Source: https://docs.whop.com/api-reference/dm-members/create-dm-member

/openapi/api-v1-stable.json post /dm_members
Add a new user to an existing DM channel. Only an admin of the channel can add members.

Required permissions:
 - `dms:channel:manage`



# Delete dm member
Source: https://docs.whop.com/api-reference/dm-members/delete-dm-member

/openapi/api-v1-stable.json delete /dm_members/{id}
Remove a user from a DM channel. An admin can remove any member, and a member can remove themselves.

Required permissions:
 - `dms:channel:manage`



# Dm Member
Source: https://docs.whop.com/api-reference/dm-members/dm-member

A user's membership record in a messaging channel, including notification preferences and read state.

<ResponseExample>
  ```json Example theme={null}
  {
  	"channel_id": "<string>",
  	"id": "<string>",
  	"last_viewed_at": "123.45",
  	"notification_preference": "all",
  	"status": "requested",
  	"user_id": "<string>"
  }
  ```
</ResponseExample>

<ResponseField name="channel_id" type="string">
  The unique identifier of the messaging channel this membership belongs to.
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the entity
</ResponseField>

<ResponseField name="last_viewed_at" type="string | null">
  The timestamp when this member last viewed the channel, as a Unix timestamp in milliseconds. Null if the member has never viewed the channel.

  Example: `123.45`
</ResponseField>

<ResponseField name="notification_preference" type="DmsFeedMemberNotificationPreferences">
  The notification level for this channel: all, mentions, or none.

  Available options: `all`, `mentions`, `none`
</ResponseField>

<ResponseField name="status" type="DmsFeedMemberStatuses">
  The current state of this membership: requested, accepted, hidden, closed, or archived.

  Available options: `requested`, `accepted`, `hidden`, `closed`, `archived`
</ResponseField>

<ResponseField name="user_id" type="string">
  The unique identifier of the user who holds this channel membership.
</ResponseField>


# List dm members
Source: https://docs.whop.com/api-reference/dm-members/list-dm-members

/openapi/api-v1-stable.json get /dm_members
Returns a paginated list of members in a specific DM channel, sorted by the date they were added.

Required permissions:
 - `dms:read`



# Retrieve dm member
Source: https://docs.whop.com/api-reference/dm-members/retrieve-dm-member

/openapi/api-v1-stable.json get /dm_members/{id}
Retrieves the details of an existing DM member.

Required permissions:
 - `dms:read`



# Update dm member
Source: https://docs.whop.com/api-reference/dm-members/update-dm-member

/openapi/api-v1-stable.json patch /dm_members/{id}
Update a DM channel member's settings, such as their notification preferences or membership status.

Required permissions:
 - `dms:channel:manage`



# Entry approved
Source: https://docs.whop.com/api-reference/entries/entry-approved

/openapi/api-v1-stable.json webhook entry.approved
Sent when a entry is approved

Required permissions:
 - `plan:waitlist:read`
 - `member:email:read`
 - `webhook_receive:entries`



# Entry created
Source: https://docs.whop.com/api-reference/entries/entry-created

/openapi/api-v1-stable.json webhook entry.created
Sent when a entry is created

Required permissions:
 - `plan:waitlist:read`
 - `member:email:read`
 - `webhook_receive:entries`



# Entry deleted
Source: https://docs.whop.com/api-reference/entries/entry-deleted

/openapi/api-v1-stable.json webhook entry.deleted
Sent when a entry is deleted

Required permissions:
 - `plan:waitlist:read`
 - `member:email:read`
 - `webhook_receive:entries`



# Entry denied
Source: https://docs.whop.com/api-reference/entries/entry-denied

/openapi/api-v1-stable.json webhook entry.denied
Sent when a entry is denied

Required permissions:
 - `plan:waitlist:read`
 - `member:email:read`
 - `webhook_receive:entries`



# Attach experience
Source: https://docs.whop.com/api-reference/experiences/attach-experience

/openapi/api-v1-stable.json post /experiences/{id}/attach
Attach an experience to a product, making it accessible to the product's customers.

Required permissions:
 - `experience:attach`



# Create experience
Source: https://docs.whop.com/api-reference/experiences/create-experience

/openapi/api-v1-stable.json post /experiences
Required permissions:
 - `experience:create`



# Delete experience
Source: https://docs.whop.com/api-reference/experiences/delete-experience

/openapi/api-v1-stable.json delete /experiences/{id}
Required permissions:
 - `experience:delete`



# Detach experience
Source: https://docs.whop.com/api-reference/experiences/detach-experience

/openapi/api-v1-stable.json post /experiences/{id}/detach
Detach an experience from a product, removing customer access to it through that product.

Required permissions:
 - `experience:detach`



# Duplicate experience
Source: https://docs.whop.com/api-reference/experiences/duplicate-experience

/openapi/api-v1-stable.json post /experiences/{id}/duplicate
Duplicates an existing experience. The name will be copied, unless provided. The new experience will be attached to the same products as the original experience.
If duplicating a Forum or Chat experience, the new experience will have the same settings as the original experience, e.g. who can post, who can comment, etc.
No content, e.g. posts, messages, lessons from within the original experience will be copied.


Required permissions:
 - `experience:create`



# Experience
Source: https://docs.whop.com/api-reference/experiences/experience

An experience is a feature or content module within a product, such as a chat, course, or custom app.

<ResponseExample>
  ```json Example theme={null}
  {
  	"app": {
  		"icon": {
  			"url": "https://media.whop.com/abc123/optimized.jpg"
  		},
  		"id": "app_xxxxxxxxxxxxxx",
  		"name": "Courses"
  	},
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"route": "pickaxe",
  		"title": "Pickaxe"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"id": "exp_xxxxxxxxxxxxxx",
  	"image": {
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"is_public": true,
  	"name": "Trading Signals Chat",
  	"order": "123.45",
  	"products": [
  		{
  			"id": "prod_xxxxxxxxxxxxx",
  			"route": "pickaxe-analytics",
  			"title": "Pickaxe Analytics"
  		}
  	]
  }
  ```
</ResponseExample>

<ResponseField name="app" type="object">
  The app that powers this experience, defining its interface and behavior.

  <Expandable title="child attributes">
    <ResponseField name="icon" type="object | null">
      The icon image for this app, displayed on the app store, product pages, checkout, and as the default icon for experiences using this app.

      <Expandable title="child attributes">
        <ResponseField name="url" type="string | null">
          A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

          Example: `https://media.whop.com/abc123/optimized.jpg`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the app.

      Example: `app_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of this app shown on the app store and in experience navigation. Maximum 30 characters.

      Example: `Courses`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="company" type="object">
  The company that owns this experience.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="route" type="string">
      URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.

      Example: `pickaxe`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the experience was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the experience.

  Example: `exp_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="image" type="object | null">
  The custom logo image for this experience. Null if no custom logo has been uploaded.

  <Expandable title="child attributes">
    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="is_public" type="boolean">
  Whether this experience is publicly visible to all users, including those
  without a membership.
</ResponseField>

<ResponseField name="name" type="string">
  The display name of this experience shown to users in the product navigation. Maximum 255 characters.

  Example: `Trading Signals Chat`
</ResponseField>

<ResponseField name="order" type="string | null">
  The sort position of this experience within its section. Lower values appear first. Null if no position has been set.

  Example: `123.45`
</ResponseField>

<ResponseField name="products" type="array<object>">
  The list of products this experience is attached to, which determines which customers have access. Empty if the experience is only visible to authorized company team members.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="route" type="string">
      URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.

      Example: `pickaxe-analytics`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>


# List experiences
Source: https://docs.whop.com/api-reference/experiences/list-experiences

/openapi/api-v1-stable.json get /experiences
Returns a paginated list of experiences belonging to a company, with optional filtering by product and app.



# Retrieve experience
Source: https://docs.whop.com/api-reference/experiences/retrieve-experience

/openapi/api-v1-stable.json get /experiences/{id}
Retrieves the details of an existing experience.



# Update experience
Source: https://docs.whop.com/api-reference/experiences/update-experience

/openapi/api-v1-stable.json patch /experiences/{id}
Required permissions:
 - `experience:update`



# Create fee markup
Source: https://docs.whop.com/api-reference/fee-markups/create-fee-markup

/openapi/api-v1-stable.json post /fee_markups
Create or update a fee markup for a company. If a markup for the specified fee type already exists, it will be updated with the new values.

Required permissions:
 - `company:update_child_fees`



# Delete fee markup
Source: https://docs.whop.com/api-reference/fee-markups/delete-fee-markup

/openapi/api-v1-stable.json delete /fee_markups/{id}
Delete a fee markup configuration for a company. This removes the custom fee override and reverts to the parent company's default fees.

Required permissions:
 - `company:update_child_fees`



# Fee Markup
Source: https://docs.whop.com/api-reference/fee-markups/fee-markup

A fee markup configuration that defines additional charges applied to transactions for a platform's connected accounts.

<ResponseExample>
  ```json Example theme={null}
  {
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"fee_type": "crypto_withdrawal_markup",
  	"fixed_fee_usd": 6.9,
  	"id": "<string>",
  	"notes": "Approved by finance team on 2024-01-15",
  	"percentage_fee": 6.9,
  	"updated_at": "2023-12-01T05:00:00.401Z"
  }
  ```
</ResponseExample>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the fee markup was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="fee_type" type="FeeMarkupTypes">
  The category of fee this markup applies to.

  Available options: `crypto_withdrawal_markup`, `rtp_withdrawal_markup`, `next_day_bank_withdrawal_markup`, `bank_wire_withdrawal_markup`, `digital_wallet_withdrawal_markup`
</ResponseField>

<ResponseField name="fixed_fee_usd" type="number | null">
  A flat fee charged per transaction, in USD. Ranges from 0 to 50. Null if no fixed fee is configured.

  Example: `6.9`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the fee markup.
</ResponseField>

<ResponseField name="notes" type="string | null">
  Internal notes about this fee markup, visible only to administrators. Null if no notes have been added.

  Example: `Approved by finance team on 2024-01-15`
</ResponseField>

<ResponseField name="percentage_fee" type="number | null">
  A percentage-based fee charged per transaction. Ranges from 0 to 25. Null if no percentage fee is configured.

  Example: `6.9`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the fee markup was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>


# List fee markups
Source: https://docs.whop.com/api-reference/fee-markups/list-fee-markups

/openapi/api-v1-stable.json get /fee_markups
Returns a paginated list of fee markups configured for a company. If the company is a platform account, returns the platform default markups.

Required permissions:
 - `company:update_child_fees`



# Create forum post
Source: https://docs.whop.com/api-reference/forum-posts/create-forum-post

/openapi/api-v1-stable.json post /forum_posts
Create a new forum post or comment within an experience. Supports text content, attachments, polls, paywalling, and pinning. Pass experience_id 'public' with a company_id to post to a company's public forum.

Required permissions:
 - `forum:post:create`



# Forum Post
Source: https://docs.whop.com/api-reference/forum-posts/forum-post

A post or comment in a forum feed, supporting rich text, attachments, polls, and reactions.

<ResponseExample>
  ```json Example theme={null}
  {
  	"attachments": [
  		{
  			"content_type": "image/jpeg",
  			"filename": "document.pdf",
  			"id": "<string>",
  			"url": "https://media.whop.com/abc123/optimized.jpg"
  		}
  	],
  	"comment_count": 42,
  	"content": "## My Strategy\n\nHere are the key steps...",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"id": "<string>",
  	"is_edited": true,
  	"is_pinned": true,
  	"is_poster_admin": true,
  	"like_count": 42,
  	"parent_id": "<string>",
  	"title": "Weekly Market Analysis - February 2025",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	},
  	"view_count": 42
  }
  ```
</ResponseExample>

<ResponseField name="attachments" type="array<object>">
  All file attachments on this post, such as images, documents, and videos.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="comment_count" type="integer">
  The total number of direct comments on this post.

  Example: `42`
</ResponseField>

<ResponseField name="content" type="string | null">
  The body of the forum post in Markdown format. Null if the post is paywalled and the current user does not have access.

  Example: `## My Strategy Here are the key steps...`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The time this post was created, as a Unix timestamp.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string" />

<ResponseField name="is_edited" type="boolean">
  Whether this post has been edited after its initial creation.
</ResponseField>

<ResponseField name="is_pinned" type="boolean">
  Whether this post is pinned to the top of the forum feed.
</ResponseField>

<ResponseField name="is_poster_admin" type="boolean">
  Whether the author of this post is an admin of the company that owns the
  forum.
</ResponseField>

<ResponseField name="like_count" type="integer | null">
  The total number of like reactions this post has received.

  Example: `42`
</ResponseField>

<ResponseField name="parent_id" type="string | null">
  The unique identifier of the parent post. Null if this is a top-level post.
</ResponseField>

<ResponseField name="title" type="string | null">
  The headline of the forum post. Null if the post has no title.

  Example: `Weekly Market Analysis - February 2025`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The time this post was last updated, as a Unix timestamp.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object">
  The user who authored this forum post.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="view_count" type="integer | null">
  The total number of times this post has been viewed by users.

  Example: `42`
</ResponseField>


# List forum posts
Source: https://docs.whop.com/api-reference/forum-posts/list-forum-posts

/openapi/api-v1-stable.json get /forum_posts
Returns a paginated list of forum posts within a specific experience, with optional filtering by parent post or pinned status.

Required permissions:
 - `forum:read`



# Retrieve forum post
Source: https://docs.whop.com/api-reference/forum-posts/retrieve-forum-post

/openapi/api-v1-stable.json get /forum_posts/{id}
Retrieves the details of an existing forum post.

Required permissions:
 - `forum:read`



# Update forum post
Source: https://docs.whop.com/api-reference/forum-posts/update-forum-post

/openapi/api-v1-stable.json patch /forum_posts/{id}
Edit the content, attachments, pinned status, or visibility of an existing forum post or comment.



# Create lead
Source: https://docs.whop.com/api-reference/leads/create-lead

/openapi/api-v1-stable.json post /leads
Record a new lead for a company, capturing a potential customer's interest in a specific product.

Required permissions:
 - `lead:manage`
 - `member:email:read`
 - `access_pass:basic:read`
 - `member:basic:read`



# Lead
Source: https://docs.whop.com/api-reference/leads/lead

A prospective customer who has expressed interest in a company or product but has not yet purchased.

<ResponseExample>
  ```json Example theme={null}
  {
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"id": "lead_xxxxxxxxxxxxx",
  	"member": {
  		"id": "<string>"
  	},
  	"metadata": {},
  	"product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"title": "Pickaxe Analytics"
  	},
  	"referrer": "https://twitter.com/whabormarket",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"email": "john.doe@example.com",
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the lead was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the lead.

  Example: `lead_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="member" type="object | null">
  The company member record if this lead has converted into a paying customer. Null if the lead has not converted.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company member.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Custom key-value pairs attached to this lead. Null if no metadata was
  provided.
</ResponseField>

<ResponseField name="product" type="object | null">
  The product the lead expressed interest in. Null if the lead is not associated with a specific product.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="referrer" type="string | null">
  The URL of the page that referred this lead to the company. Null if no referrer was captured.

  Example: `https://twitter.com/whabormarket`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the lead was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object">
  The user account associated with this lead.

  <Expandable title="child attributes">
    <ResponseField name="email" type="string | null">
      The user's email address. Requires the member:email:read permission to access. Null if not authorized.

      Example: `john.doe@example.com`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# List leads
Source: https://docs.whop.com/api-reference/leads/list-leads

/openapi/api-v1-stable.json get /leads
Returns a paginated list of leads for a company, with optional filtering by product and creation date.

Required permissions:
 - `lead:basic:read`
 - `member:email:read`
 - `access_pass:basic:read`
 - `member:basic:read`



# Retrieve lead
Source: https://docs.whop.com/api-reference/leads/retrieve-lead

/openapi/api-v1-stable.json get /leads/{id}
Retrieves the details of an existing lead.

Required permissions:
 - `lead:basic:read`
 - `member:email:read`
 - `access_pass:basic:read`
 - `member:basic:read`



# Update lead
Source: https://docs.whop.com/api-reference/leads/update-lead

/openapi/api-v1-stable.json patch /leads/{id}
Update the metadata or referrer information on an existing lead record.

Required permissions:
 - `lead:manage`
 - `member:email:read`
 - `access_pass:basic:read`
 - `member:basic:read`



# List members
Source: https://docs.whop.com/api-reference/members/list-members

/openapi/api-v1-stable.json get /members
Returns a paginated list of members for a company, with extensive filtering by product, plan, status, access level, and more.

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `member:phone:read`



# Member
Source: https://docs.whop.com/api-reference/members/member

A member represents a user's relationship with a company on Whop, including their access level, status, and spending history.

<ResponseExample>
  ```json Example theme={null}
  {
  	"access_level": "no_access",
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"route": "<string>",
  		"title": "<string>"
  	},
  	"company_token_balance": 6.9,
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"id": "<string>",
  	"joined_at": "2023-12-01T05:00:00.401Z",
  	"most_recent_action": "canceling",
  	"most_recent_action_at": "2023-12-01T05:00:00.401Z",
  	"phone": "<string>",
  	"status": "drafted",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"usd_total_spent": 6.9,
  	"user": {
  		"email": "<string>",
  		"id": "<string>",
  		"name": "<string>",
  		"username": "<string>"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="access_level" type="AccessLevel">
  The access level of the product member. If its admin, the member is an authorized user of the company. If its customer, the member has a valid membership to any product on the company. If its no\_access, the member does not have access to the product.

  Available options: `no_access`, `admin`, `customer`
</ResponseField>

<ResponseField name="company" type="object">
  The company for the member.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="route" type="string">
      The slug/route of the company on the Whop site.
    </ResponseField>

    <ResponseField name="title" type="string">
      The written name of the company.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="company_token_balance" type="number">
  The member's token balance for this company. Computed live from the ledger, not from a cache.

  Example: `6.9`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the company member was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the company member.
</ResponseField>

<ResponseField name="joined_at" type="string<date-time>">
  When the member joined the company

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="most_recent_action" type="MemberMostRecentActions | null">
  The most recent action the member has taken.

  Available options: `canceling`, `churned`, `finished_split_pay`, `paused`, `paid_subscriber`, `paid_once`, `expiring`, `joined`, `drafted`, `left`, `trialing`, `pending_entry`, `renewing`, `past_due`
</ResponseField>

<ResponseField name="most_recent_action_at" type="string<date-time> | null">
  The time for the most recent action, if applicable.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="phone" type="string | null">
  The phone number for the member, if available.
</ResponseField>

<ResponseField name="status" type="MemberStatuses">
  The status of the member

  Available options: `drafted`, `joined`, `left`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the company member was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="usd_total_spent" type="number">
  How much money this customer has spent on the company's products and plans

  Example: `6.9`
</ResponseField>

<ResponseField name="user" type="object | null">
  The user for this member, if any.

  <Expandable title="child attributes">
    <ResponseField name="email" type="string | null">
      The digital mailing address of the user.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the company member user.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's full name.
    </ResponseField>

    <ResponseField name="username" type="string">
      The whop username.
    </ResponseField>
  </Expandable>
</ResponseField>


# Member created
Source: https://docs.whop.com/api-reference/members/member-created

/openapi/api-v1-stable.json webhook member.created
Sent when a member is created

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `member:phone:read`
 - `webhook_receive:members`



# Retrieve member
Source: https://docs.whop.com/api-reference/members/retrieve-member

/openapi/api-v1-stable.json get /members/{id}
Retrieves the details of an existing member.

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `member:phone:read`



# Add free days membership
Source: https://docs.whop.com/api-reference/memberships/add-free-days-membership

/openapi/api-v1-stable.json post /memberships/{id}/add_free_days
Add free days to extend a membership's current billing period, expiration date, or Stripe trial.

Required permissions:
 - `member:manage`
 - `member:email:read`
 - `member:basic:read`



# Cancel membership
Source: https://docs.whop.com/api-reference/memberships/cancel-membership

/openapi/api-v1-stable.json post /memberships/{id}/cancel
Cancel a membership either immediately or at the end of the current billing period. Immediate cancellation revokes access right away.

Required permissions:
 - `membership:cancel`
 - `member:email:read`
 - `member:basic:read`



# List memberships
Source: https://docs.whop.com/api-reference/memberships/list-memberships

/openapi/api-v1-stable.json get /memberships
Returns a paginated list of memberships, with optional filtering by product, plan, status, and user.

Required permissions:
 - `member:basic:read`
 - `member:email:read`



# Membership
Source: https://docs.whop.com/api-reference/memberships/membership

A membership represents an active relationship between a user and a product. It tracks the user's access, billing status, and renewal schedule.

<ResponseExample>
  ```json Example theme={null}
  {
  	"cancel_at_period_end": true,
  	"cancel_option": "too_expensive",
  	"cancelation_status": "won_back",
  	"canceled_at": "2023-12-01T05:00:00.401Z",
  	"cancellation_reason": "I found a better alternative.",
  	"checkout_configuration_id": "ch_xxxxxxxxxxxxxxx",
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"title": "Pickaxe"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"custom_field_responses": [
  		{
  			"answer": "<string>",
  			"id": "cfrp_xxxxxxxxxxxxx",
  			"question": "<string>"
  		}
  	],
  	"formatted_renewal_price": "$25.00 / month",
  	"id": "mem_xxxxxxxxxxxxxx",
  	"initial_price_paid": "$25.00",
  	"joined_at": "2023-12-01T05:00:00.401Z",
  	"license_key": "A1B2C3-D4E5F6-G7H8I9",
  	"manage_url": "https://whop.com/billing/manage/mem_abc123",
  	"member": {
  		"id": "mber_xxxxxxxxxxxxx"
  	},
  	"metadata": {},
  	"payment_collection_paused": true,
  	"plan": {
  		"id": "plan_xxxxxxxxxxxxx",
  		"metadata": {}
  	},
  	"product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"metadata": {},
  		"title": "Pickaxe Analytics"
  	},
  	"promo_code": {
  		"id": "promo_xxxxxxxxxxxx"
  	},
  	"renewal_period_end": "2023-12-01T05:00:00.401Z",
  	"renewal_period_start": "2023-12-01T05:00:00.401Z",
  	"status": "trialing",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"email": "john.doe@example.com",
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"profile_pic": "<string>",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="cancel_at_period_end" type="boolean">
  Whether this membership is set to cancel at the end of the current billing
  cycle. Only applies to memberships with a recurring plan.
</ResponseField>

<ResponseField name="cancel_option" type="CancelOptions | null">
  The category selected for why the member canceled (e.g. too\_expensive, switching, missing\_features).

  Available options: `too_expensive`, `switching`, `missing_features`, `technical_issues`, `bad_experience`, `other`, `testing`
</ResponseField>

<ResponseField name="cancelation_status" type="CancelationStatus | null">
  Whether the customer is canceling, left, or was won back. Null if the membership has no cancellation reason or its cancellation state is indeterminate.

  Available options: `won_back`, `left`, `canceling`
</ResponseField>

<ResponseField name="canceled_at" type="string<date-time> | null">
  The time the customer initiated cancellation of this membership. As a Unix timestamp. Null if the membership has not been canceled.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="cancellation_reason" type="string | null">
  Free-text explanation provided by the customer when canceling. Null if the customer did not provide a reason.

  Example: `I found a better alternative.`
</ResponseField>

<ResponseField name="checkout_configuration_id" type="string | null">
  The ID of the checkout session/configuration that produced this membership, if any. Use this to map memberships back to the checkout configuration that created them.

  Example: `ch_xxxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="company" type="object">
  The company this membership belongs to.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the membership was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies | null">
  The three-letter ISO currency code for this membership's billing. Null if the membership is free.

  Available options: `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`
</ResponseField>

<ResponseField name="custom_field_responses" type="array<object>">
  The customer's responses to custom checkout questions configured on the product at the time of purchase.

  <Expandable title="child attributes">
    <ResponseField name="answer" type="string">
      The response a user gave to the specific question or field.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the custom field response.

      Example: `cfrp_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="question" type="string">
      The question asked by the custom field
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="formatted_renewal_price" type="string | null">
  The recurring renewal price for this membership, formatted with currency symbol and billing interval. Null if the membership is not recurring.

  Example: `$25.00 / month`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the membership.

  Example: `mem_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="initial_price_paid" type="string">
  The amount the customer paid when first purchasing this membership, formatted with currency symbol.

  Example: `$25.00`
</ResponseField>

<ResponseField name="joined_at" type="string<date-time> | null">
  The time the user first joined the company associated with this membership. As a Unix timestamp. Null if the member record does not exist.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="license_key" type="string | null">
  The software license key associated with this membership. Only present if the product includes a Whop Software Licensing experience. Null otherwise.

  Example: `A1B2C3-D4E5F6-G7H8I9`
</ResponseField>

<ResponseField name="manage_url" type="string | null">
  The URL where the customer can view and manage this membership, including cancellation and plan changes. Null if no member record exists.

  Example: `https://whop.com/billing/manage/mem_abc123`
</ResponseField>

<ResponseField name="member" type="object | null">
  The member record linking the user to the company for this membership. Null if the member record has not been created yet.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the member.

      Example: `mber_xxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Custom key-value pairs for the membership (commonly used for software
  licensing, e.g., HWID). Max 50 keys, 100 chars per key, 500 chars per string
  value.
</ResponseField>

<ResponseField name="payment_collection_paused" type="boolean">
  Whether recurring payment collection for this membership is temporarily paused
  by the company.
</ResponseField>

<ResponseField name="plan" type="object">
  The plan the customer purchased to create this membership.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the plan.

      Example: `plan_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="product" type="object">
  The product this membership grants access to.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value pairs stored on the product and included in payment and
      membership webhook payloads. Max 50 keys, 100 characters per key, 500
      characters per string value.
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="promo_code" type="object | null">
  The promotional code currently applied to this membership's billing. Null if no promo code is active.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the promo code.

      Example: `promo_xxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="renewal_period_end" type="string<date-time> | null">
  The end of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="renewal_period_start" type="string<date-time> | null">
  The start of the current billing period for this recurring membership. As a Unix timestamp. Null if the membership is not recurring.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="status" type="MembershipStatus">
  The current lifecycle status of the membership (e.g., active, trialing, past\_due, canceled, expired, completed).

  Available options: `trialing`, `active`, `past_due`, `completed`, `canceled`, `expired`, `unresolved`, `drafted`, `canceling`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the membership was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object | null">
  The user who owns this membership. Null if the user account has been deleted.

  <Expandable title="child attributes">
    <ResponseField name="email" type="string | null">
      The user's email address. Requires the member:email:read permission to access. Null if not authorized.

      Example: `john.doe@example.com`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="profile_pic" type="string">
      The URL of the user's profile picture. Use profilePicture for the full
      attachment object.
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# Membership activated
Source: https://docs.whop.com/api-reference/memberships/membership-activated

/openapi/api-v1-stable.json webhook membership.activated
Sent when a membership is activated

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:memberships`



# Membership cancel at period end changed
Source: https://docs.whop.com/api-reference/memberships/membership-cancel-at-period-end-changed

/openapi/api-v1-stable.json webhook membership.cancel_at_period_end_changed
Sent when a membership is cancel at period end changed

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:memberships`



# Membership deactivated
Source: https://docs.whop.com/api-reference/memberships/membership-deactivated

/openapi/api-v1-stable.json webhook membership.deactivated
Sent when a membership is deactivated

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:memberships`



# Membership trial ending soon
Source: https://docs.whop.com/api-reference/memberships/membership-trial-ending-soon

/openapi/api-v1-stable.json webhook membership.trial_ending_soon
Sent when a membership is trial ending soon

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:memberships`



# Pause membership
Source: https://docs.whop.com/api-reference/memberships/pause-membership

/openapi/api-v1-stable.json post /memberships/{id}/pause
Pause a membership's recurring payments. The customer retains access but will not be charged until the membership is resumed.

Required permissions:
 - `member:manage`
 - `member:email:read`
 - `member:basic:read`



# Resume membership
Source: https://docs.whop.com/api-reference/memberships/resume-membership

/openapi/api-v1-stable.json post /memberships/{id}/resume
Resume a previously paused membership's recurring payments. Billing resumes on the next cycle.

Required permissions:
 - `member:manage`
 - `member:email:read`
 - `member:basic:read`



# Resync access membership
Source: https://docs.whop.com/api-reference/memberships/resync-access-membership

/openapi/api-v1-stable.json post /memberships/{id}/resync_access
Re-run access fulfillment for a membership. Recomputes the member's content access on Whop, re-validates their Discord link (re-adding them to the server and re-assigning roles if needed), and re-fulfills TradingView indicator access. Telegram access is invite-based and cannot be resynced here. The outcome is written to the membership's logs.

Required permissions:
 - `membership:resync_access`
 - `member:email:read`
 - `member:basic:read`



# Retrieve membership
Source: https://docs.whop.com/api-reference/memberships/retrieve-membership

/openapi/api-v1-stable.json get /memberships/{id}
Retrieves the details of an existing membership.

Required permissions:
 - `member:basic:read`
 - `member:email:read`



# Uncancel membership
Source: https://docs.whop.com/api-reference/memberships/uncancel-membership

/openapi/api-v1-stable.json post /memberships/{id}/uncancel
Reverse a pending cancellation for a membership that was scheduled to cancel at period end.

Required permissions:
 - `member:manage`
 - `member:email:read`
 - `member:basic:read`



# Update membership
Source: https://docs.whop.com/api-reference/memberships/update-membership

/openapi/api-v1-stable.json patch /memberships/{id}
Update a membership's metadata or other mutable properties.

Required permissions:
 - `member:manage`
 - `member:email:read`
 - `member:basic:read`



# List reviews
Source: https://docs.whop.com/api-reference/reviews/list-reviews

/openapi/api-v1-stable.json get /reviews
Returns a paginated list of customer reviews for a specific product, with optional filtering by star rating and creation date.



# Retrieve review
Source: https://docs.whop.com/api-reference/reviews/retrieve-review

/openapi/api-v1-stable.json get /reviews/{id}
Retrieves the details of an existing review.



# Review
Source: https://docs.whop.com/api-reference/reviews/review

A user-submitted review of a company, including a star rating and optional text feedback.

<ResponseExample>
  ```json Example theme={null}
  {
  	"attachments": [
  		{
  			"content_type": "image/jpeg",
  			"filename": "document.pdf",
  			"id": "<string>",
  			"url": "https://media.whop.com/abc123/optimized.jpg"
  		}
  	],
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"route": "pickaxe",
  		"title": "Pickaxe"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"description": "Great product, really helped me grow my audience.",
  	"id": "rev_xxxxxxxxxxxxxx",
  	"joined_at": "2023-12-01T05:00:00.401Z",
  	"paid_for_product": true,
  	"product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"title": "Pickaxe Analytics"
  	},
  	"published_at": "2023-12-01T05:00:00.401Z",
  	"stars": 42,
  	"status": "pending",
  	"title": "Amazing community and tools",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="attachments" type="array<object>">
  A list of files and media attached to the review.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="company" type="object">
  The company that this review was written for.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="route" type="string">
      URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.

      Example: `pickaxe`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the review was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="description" type="string | null">
  The body text of the review containing the user's detailed feedback. Returns an empty string if no description was provided.

  Example: `Great product, really helped me grow my audience.`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the review.

  Example: `rev_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="joined_at" type="string<date-time> | null">
  The timestamp of when the reviewer first joined the product. Null if unknown.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="paid_for_product" type="boolean | null">
  Whether the reviewer paid for the product. Null if the payment status is
  unknown.
</ResponseField>

<ResponseField name="product" type="object">
  The product that this review was written for.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="published_at" type="string<date-time> | null">
  The timestamp of when the review was published. Null if the review has not been published yet.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="stars" type="integer">
  The star rating given by the reviewer, from 1 to 5.

  Example: `42`
</ResponseField>

<ResponseField name="status" type="ReviewStatus">
  The current moderation status of the review.

  Available options: `pending`, `published`, `removed`
</ResponseField>

<ResponseField name="title" type="string | null">
  A short summary title for the review. Null if the reviewer did not provide one.

  Example: `Amazing community and tools`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the review was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object">
  The user account of the person who wrote this review.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# Create shipment
Source: https://docs.whop.com/api-reference/shipments/create-shipment

/openapi/api-v1-stable.json post /shipments
Create a new shipment with a tracking code for a specific payment within a company.

Required permissions:
 - `shipment:create`
 - `payment:basic:read`



# List shipments
Source: https://docs.whop.com/api-reference/shipments/list-shipments

/openapi/api-v1-stable.json get /shipments
Returns a paginated list of shipments, with optional filtering by payment, company, or user.

Required permissions:
 - `shipment:basic:read`
 - `payment:basic:read`



# Retrieve shipment
Source: https://docs.whop.com/api-reference/shipments/retrieve-shipment

/openapi/api-v1-stable.json get /shipments/{id}
Retrieves the details of an existing shipment.

Required permissions:
 - `shipment:basic:read`
 - `payment:basic:read`



# Shipment
Source: https://docs.whop.com/api-reference/shipments/shipment

A physical shipment associated with a payment, including carrier details and tracking information.

<ResponseExample>
  ```json Example theme={null}
  {
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"delivery_estimate": "2023-12-01T05:00:00.401Z",
  	"id": "ship_xxxxxxxxxxxxx",
  	"payment": {
  		"id": "pay_xxxxxxxxxxxxxx"
  	},
  	"service": "Priority",
  	"status": "unknown",
  	"substatus": "address_correction",
  	"tracking_code": "9400111899223456789012",
  	"updated_at": "2023-12-01T05:00:00.401Z"
  }
  ```
</ResponseExample>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the shipment was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="delivery_estimate" type="string<date-time> | null">
  The estimated delivery date for this shipment. Null if the carrier has not provided an estimate.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the shipment.

  Example: `ship_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="payment" type="object | null">
  The payment associated with this shipment. Null if the payment has been deleted or is inaccessible.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the payment.

      Example: `pay_xxxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="service" type="string | null">
  The shipping service level used for this shipment. Null if the carrier does not specify a service tier.

  Example: `Priority`
</ResponseField>

<ResponseField name="status" type="ShipmentStatuses">
  The current delivery status of this shipment.

  Available options: `unknown`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `available_for_pickup`, `return_to_sender`, `failure`, `cancelled`, `error`
</ResponseField>

<ResponseField name="substatus" type="ShipmentSubstatuses | null">
  A more granular status providing additional detail about the shipment's current state. Null if no substatus applies.

  Available options: `address_correction`, `arrived_at_destination`, `arrived_at_facility`, `arrived_at_pickup_location`, `awaiting_information`, `substatus_cancelled`, `damaged`, `delayed`, `delivery_exception`, `departed_facility`, `departed_origin_facility`, `expired`, `substatus_failure`, `held`, `substatus_in_transit`, `label_created`, `lost`, `missorted`, `substatus_out_for_delivery`, `received_at_destination_facility`, `received_at_origin_facility`, `refused`, `return`, `status_update`, `transferred_to_destination_carrier`, `transit_exception`, `substatus_unknown`, `weather_delay`
</ResponseField>

<ResponseField name="tracking_code" type="string">
  The carrier-assigned tracking number used to look up shipment progress.

  Example: `9400111899223456789012`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the shipment was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>


# Shipment created
Source: https://docs.whop.com/api-reference/shipments/shipment-created

/openapi/api-v1-stable.json webhook shipment.created
Sent when a shipment is created

Required permissions:
 - `shipment:basic:read`
 - `payment:basic:read`
 - `webhook_receive:shipments`



# Shipment updated
Source: https://docs.whop.com/api-reference/shipments/shipment-updated

/openapi/api-v1-stable.json webhook shipment.updated
Sent when a shipment is updated

Required permissions:
 - `shipment:basic:read`
 - `payment:basic:read`
 - `webhook_receive:shipments`



# Users
Source: https://docs.whop.com/api-reference/users/user

The Users API is documented in the Experimental API Reference.

The Users API is served by the versioned `/api/v1` API, so it is not part of the stable surface documented here.

<Card title="Users API Reference" icon="arrow-right" href="/api-reference/beta/users/user">
  Browse the Users resource schema and endpoints in the Experimental API
  Reference.
</Card>


# Checkout Configuration
Source: https://docs.whop.com/api-reference/checkout-configurations/checkout-configuration

A checkout configuration is a reusable configuration for a checkout, including the plan, affiliate, and custom metadata. Payments and memberships created from a checkout session inherit its metadata.

<ResponseExample>
  ```json Example theme={null}
  {
  	"affiliate_code": "<string>",
  	"company_id": "<string>",
  	"currency": "usd",
  	"id": "ch_xxxxxxxxxxxxxxx",
  	"metadata": {},
  	"mode": "payment",
  	"payment_method_configuration": {
  		"disabled": ["acss_debit"],
  		"enabled": ["acss_debit"],
  		"include_platform_defaults": true
  	},
  	"plan": {
  		"adaptive_pricing_enabled": true,
  		"billing_period": 42,
  		"currency": "usd",
  		"expiration_days": 42,
  		"id": "plan_xxxxxxxxxxxxx",
  		"initial_price": 6.9,
  		"plan_type": "renewal",
  		"release_method": "buy_now",
  		"renewal_price": 6.9,
  		"three_ds_level": "mandate_challenge",
  		"trial_period_days": 42,
  		"visibility": "visible"
  	},
  	"purchase_url": "<string>",
  	"redirect_url": "<string>"
  }
  ```
</ResponseExample>

<ResponseField name="affiliate_code" type="string | null">
  The affiliate code to use for the checkout configuration
</ResponseField>

<ResponseField name="company_id" type="string">
  The ID of the company to use for the checkout configuration
</ResponseField>

<ResponseField name="currency" type="Currencies | null">
  The currency to use for the configuration when in 'setup' mode. This is used to target which currency specific payment methods are available. If not provided, it will default to 'usd' when in setup mode.

  Available options: `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`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the checkout session.

  Example: `ch_xxxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="metadata" type="object | null">
  The metadata to use for the checkout configuration
</ResponseField>

<ResponseField name="mode" type="CheckoutModes">
  The mode of the checkout session.

  Available options: `payment`, `setup`
</ResponseField>

<ResponseField name="payment_method_configuration" type="object | null">
  The explicit payment method configuration for the session, if any. This currently only works in 'setup' mode. Use the plan's payment\_method\_configuration for payment method.

  <Expandable title="child attributes">
    <ResponseField name="disabled" type="array<PaymentMethodTypes>">
      An array of payment method identifiers that are explicitly disabled. Only applies if the include\_platform\_defaults is true.

      Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
    </ResponseField>

    <ResponseField name="enabled" type="array<PaymentMethodTypes>">
      An array of payment method identifiers that are explicitly enabled. This means these payment methods will be shown on checkout. Example use case is to only enable a specific payment method like cashapp, or extending the platform defaults with additional methods.

      Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
    </ResponseField>

    <ResponseField name="include_platform_defaults" type="boolean">
      Whether Whop's platform default payment method enablement settings are included in this configuration. The full list of default payment methods can be found in the documentation at docs.whop.com/payments.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="plan" type="object | null">
  The plan to use for the checkout configuration

  <Expandable title="child attributes">
    <ResponseField name="adaptive_pricing_enabled" type="boolean">
      Whether the creator has turned on adaptive pricing for this plan. Raw setting
      — does not check processor compatibility or feature flags.
    </ResponseField>

    <ResponseField name="billing_period" type="integer | null">
      Number of days between recurring charges, such as 30 for monthly or 365 for annual. `null` for one-time plans.

      Example: `42`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency.

      Available options: `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`
    </ResponseField>

    <ResponseField name="expiration_days" type="integer | null">
      Access duration in days for expiration-based plans, such as 365 for a one-year pass.

      Example: `42`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the plan.

      Example: `plan_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="initial_price" type="number">
      The initial purchase price in the plan's base\_currency (e.g., 49.99 for \$49.99). For one-time plans, this is the full price. For renewal plans, this is charged on top of the first renewal\_price.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="plan_type" type="PlanTypes">
      The billing model for this plan: 'renewal' for recurring subscriptions or 'one\_time' for single payments.

      Available options: `renewal`, `one_time`
    </ResponseField>

    <ResponseField name="release_method" type="ReleaseMethod">
      Sales method for this plan: `buy_now` for immediate purchase or `waitlist` for waitlist-based access.

      Available options: `buy_now`, `waitlist`
    </ResponseField>

    <ResponseField name="renewal_price" type="number">
      The recurring price charged every billing\_period in the plan's base\_currency (e.g., 9.99 for \$9.99/period). Zero for one-time plans.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="three_ds_level" type="PlanThreeDsLevels | null">
      The 3D Secure behavior for this plan. Null means the plan inherits the account default.

      Available options: `mandate_challenge`, `frictionless`
    </ResponseField>

    <ResponseField name="trial_period_days" type="integer | null">
      Free trial days before first renewal charge. `null` if no trial is configured or the user has already used a trial for this plan.

      Example: `42`
    </ResponseField>

    <ResponseField name="visibility" type="Visibility">
      Controls whether the plan is visible to customers. When set to 'hidden', the plan is only accessible via direct link.

      Available options: `visible`, `hidden`, `archived`, `quick_link`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="purchase_url" type="string">
  A URL you can send to customers to complete a checkout. It looks like
  `/checkout/plan_xxxx?session=\{id}`
</ResponseField>

<ResponseField name="redirect_url" type="string | null">
  The URL to redirect the user to after the checkout configuration is created
</ResponseField>


# Create checkout configuration
Source: https://docs.whop.com/api-reference/checkout-configurations/create-checkout-configuration

/openapi/api-v1-stable.json post /checkout_configurations
Creates a new checkout configuration

Required permissions:
 - `checkout_configuration:create`
 - `plan:create`
 - `access_pass:create`
 - `access_pass:update`
 - `checkout_configuration:basic:read`



# List checkout configurations
Source: https://docs.whop.com/api-reference/checkout-configurations/list-checkout-configurations

/openapi/api-v1-stable.json get /checkout_configurations
Returns a paginated list of checkout configurations for a company, with optional filtering by plan and creation date.

Required permissions:
 - `checkout_configuration:basic:read`



# Retrieve checkout configuration
Source: https://docs.whop.com/api-reference/checkout-configurations/retrieve-checkout-configuration

/openapi/api-v1-stable.json get /checkout_configurations/{id}
Retrieves the details of an existing checkout configuration.

Required permissions:
 - `checkout_configuration:basic:read`



# Dispute Alert
Source: https://docs.whop.com/api-reference/dispute-alerts/dispute-alert

A dispute alert represents an early warning notification from a payment processor about a potential dispute or chargeback.

<ResponseExample>
  ```json Example theme={null}
  {
  	"alert_type": "dispute",
  	"amount": 6.9,
  	"charge_for_alert": true,
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"dispute": {
  		"amount": 6.9,
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"currency": "usd",
  		"id": "dspt_xxxxxxxxxxxxx",
  		"reason": "Product Not Received",
  		"status": "warning_needs_response"
  	},
  	"id": "dspa_xxxxxxxxxxxxx",
  	"payment": {
  		"billing_reason": "subscription_create",
  		"card_brand": "mastercard",
  		"card_last4": "4242",
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"currency": "usd",
  		"dispute_alerted_at": "2023-12-01T05:00:00.401Z",
  		"id": "pay_xxxxxxxxxxxxxx",
  		"member": {
  			"id": "<string>",
  			"phone": "<string>"
  		},
  		"membership": {
  			"id": "mem_xxxxxxxxxxxxxx",
  			"status": "trialing"
  		},
  		"paid_at": "2023-12-01T05:00:00.401Z",
  		"payment_method_type": "acss_debit",
  		"subtotal": 6.9,
  		"total": 6.9,
  		"usd_total": 6.9,
  		"user": {
  			"email": "john.doe@example.com",
  			"id": "user_xxxxxxxxxxxxx",
  			"name": "John Doe",
  			"username": "johndoe42"
  		}
  	},
  	"transaction_date": "2023-12-01T05:00:00.401Z"
  }
  ```
</ResponseExample>

<ResponseField name="alert_type" type="DisputeAlertTypes">
  The type of the dispute alert.

  Available options: `dispute`, `dispute_rdr`, `fraud`
</ResponseField>

<ResponseField name="amount" type="number">
  The alerted amount in the specified currency.

  Example: `6.9`
</ResponseField>

<ResponseField name="charge_for_alert" type="boolean">
  Whether this alert incurs a charge.
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The time the dispute alert was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies">
  The three-letter ISO currency code for the alerted amount.

  Available options: `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`
</ResponseField>

<ResponseField name="dispute" type="object | null">
  The dispute associated with the dispute alert.

  <Expandable title="child attributes">
    <ResponseField name="amount" type="number">
      The disputed amount in the specified currency, formatted as a decimal.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time> | null">
      The datetime the dispute was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The three-letter ISO currency code for the disputed amount.

      Available options: `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`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the dispute.

      Example: `dspt_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="reason" type="string | null">
      A human-readable reason for the dispute.

      Example: `Product Not Received`
    </ResponseField>

    <ResponseField name="status" type="DisputeStatuses">
      The current status of the dispute lifecycle, such as needs\_response, under\_review, won, or lost.

      Available options: `warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`, `closed`, `other`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier of the dispute alert.

  Example: `dspa_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="payment" type="object | null">
  The payment associated with the dispute alert.

  <Expandable title="child attributes">
    <ResponseField name="billing_reason" type="BillingReasons | null">
      The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.

      Available options: `subscription_create`, `subscription_cycle`, `subscription_update`, `one_time`, `manual`, `subscription`
    </ResponseField>

    <ResponseField name="card_brand" type="CardBrands | null">
      Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.

      Available options: `mastercard`, `visa`, `amex`, `discover`, `unionpay`, `jcb`, `diners`, `link`, `troy`, `visadankort`, `visabancontact`, `china_union_pay`, `rupay`, `jcbrupay`, `elo`, `maestro`, `tarjeta_naranja`, `cirrus`, `nspk_mir`, `verve`, `ebt`, `private_label`, `local_brand`, `uatp`, `wexcard`, `uzcard`, `meeza`, `hrg_store_card`, `girocard`, `fuel_card`, `dankort`, `carnet`, `atm_card`, `china_union_payuzcard`, `codensa`, `cabal`, `hipercard`, `jcblankapay`, `cmi`, `aura`, `unknown`
    </ResponseField>

    <ResponseField name="card_last4" type="string | null">
      The last four digits of the card used to make this payment. Null if the payment was not made with a card.

      Example: `4242`
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the payment was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').

      Available options: `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`
    </ResponseField>

    <ResponseField name="dispute_alerted_at" type="string<date-time> | null">
      When an alert came in that this transaction will be disputed

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payment.

      Example: `pay_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="member" type="object | null">
      The member attached to this payment.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the company member.
        </ResponseField>

        <ResponseField name="phone" type="string | null">
          The phone number for the member, if available.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="membership" type="object | null">
      The membership attached to this payment.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the membership.

          Example: `mem_xxxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="status" type="MembershipStatus">
          The state of the membership.

          Available options: `trialing`, `active`, `past_due`, `completed`, `canceled`, `expired`, `unresolved`, `drafted`, `canceling`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="paid_at" type="string<date-time> | null">
      The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="payment_method_type" type="PaymentMethodTypes | null">
      The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.

      Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
    </ResponseField>

    <ResponseField name="subtotal" type="number | null">
      The subtotal to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="total" type="number | null">
      The total to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="usd_total" type="number | null">
      The total in USD to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="user" type="object | null">
      The user that made this payment.

      <Expandable title="child attributes">
        <ResponseField name="email" type="string | null">
          The user's email address. Requires the member:email:read permission to access. Null if not authorized.

          Example: `john.doe@example.com`
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique identifier for the user.

          Example: `user_xxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The user's display name shown on their public profile.

          Example: `John Doe`
        </ResponseField>

        <ResponseField name="username" type="string">
          The user's unique username shown on their public profile.

          Example: `johndoe42`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="transaction_date" type="string<date-time> | null">
  The date of the original transaction.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>


# Disputealert created
Source: https://docs.whop.com/api-reference/dispute-alerts/disputealert-created

/openapi/api-v1-stable.json webhook dispute_alert.created
Sent when a dispute alert is created

Required permissions:
 - `payment:dispute_alert:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `payment:dispute:read`
 - `webhook_receive:disputes`



# List dispute alerts
Source: https://docs.whop.com/api-reference/dispute-alerts/list-dispute-alerts

/openapi/api-v1-stable.json get /dispute_alerts
Returns a paginated list of dispute alerts for a company, with optional filtering by creation date.

Required permissions:
 - `payment:dispute_alert:read`
 - `payment:basic:read`
 - `payment:dispute:read`



# Retrieve dispute alert
Source: https://docs.whop.com/api-reference/dispute-alerts/retrieve-dispute-alert

/openapi/api-v1-stable.json get /dispute_alerts/{id}
Retrieves the details of an existing dispute alert.

Required permissions:
 - `payment:dispute_alert:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `payment:dispute:read`



# Dispute
Source: https://docs.whop.com/api-reference/disputes/dispute

A dispute is a chargeback or payment challenge filed against a company, including evidence and response status.

<ResponseExample>
  ```json Example theme={null}
  {
  	"access_activity_log": "192.168.1.1 - 2024-01-15 12:00:00 UTC",
  	"amount": 6.9,
  	"billing_address": "123 Main St, New York, NY 10001",
  	"cancellation_policy_attachment": {
  		"content_type": "image/jpeg",
  		"filename": "document.pdf",
  		"id": "<string>",
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"cancellation_policy_disclosure": "All sales are final. No refunds after 30 days.",
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"title": "<string>"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"customer_communication_attachment": {
  		"content_type": "image/jpeg",
  		"filename": "document.pdf",
  		"id": "<string>",
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"customer_email_address": "customer@example.com",
  	"customer_name": "Jane Doe",
  	"editable": true,
  	"id": "dspt_xxxxxxxxxxxxx",
  	"needs_response_by": "2023-12-01T05:00:00.401Z",
  	"notes": "Customer used the product for 3 months before disputing.",
  	"payment": {
  		"billing_reason": "subscription_create",
  		"card_brand": "mastercard",
  		"card_last4": "4242",
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"currency": "usd",
  		"dispute_alerted_at": "2023-12-01T05:00:00.401Z",
  		"id": "pay_xxxxxxxxxxxxxx",
  		"member": {
  			"id": "<string>",
  			"phone": "<string>"
  		},
  		"membership": {
  			"id": "mem_xxxxxxxxxxxxxx",
  			"status": "trialing"
  		},
  		"paid_at": "2023-12-01T05:00:00.401Z",
  		"payment_method_type": "acss_debit",
  		"subtotal": 6.9,
  		"total": 6.9,
  		"usd_total": 6.9,
  		"user": {
  			"email": "john.doe@example.com",
  			"id": "user_xxxxxxxxxxxxx",
  			"name": "John Doe",
  			"username": "johndoe42"
  		}
  	},
  	"plan": {
  		"id": "plan_xxxxxxxxxxxxx"
  	},
  	"product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"title": "Pickaxe Analytics"
  	},
  	"product_description": "Monthly subscription to premium analytics dashboard.",
  	"reason": "Product Not Received",
  	"reason_code": "10.4",
  	"refund_policy_attachment": {
  		"content_type": "image/jpeg",
  		"filename": "document.pdf",
  		"id": "<string>",
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"refund_policy_disclosure": "Refunds available within 14 days of purchase.",
  	"refund_refusal_explanation": "The customer exceeded the refund window by 60 days.",
  	"service_date": "2024-01-15",
  	"status": "warning_needs_response",
  	"uncategorized_attachment": {
  		"content_type": "image/jpeg",
  		"filename": "document.pdf",
  		"id": "<string>",
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"visa_rdr": true
  }
  ```
</ResponseExample>

<ResponseField name="access_activity_log" type="string | null">
  A log of IP-based access activity for the customer on Whop, submitted as evidence in the dispute.

  Example: `192.168.1.1 - 2024-01-15 12:00:00 UTC`
</ResponseField>

<ResponseField name="amount" type="number">
  The disputed amount in the specified currency, formatted as a decimal.

  Example: `6.9`
</ResponseField>

<ResponseField name="billing_address" type="string | null">
  The customer's billing address from their payment details, submitted as evidence in the dispute.

  Example: `123 Main St, New York, NY 10001`
</ResponseField>

<ResponseField name="cancellation_policy_attachment" type="object | null">
  The cancellation policy document uploaded as dispute evidence. Null if no cancellation policy has been provided.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancellation_policy_disclosure" type="string | null">
  A text disclosure describing the company's cancellation policy, submitted as dispute evidence.

  Example: `All sales are final. No refunds after 30 days.`
</ResponseField>

<ResponseField name="company" type="object | null">
  The company that the dispute was filed against.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The written name of the company.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time> | null">
  The datetime the dispute was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies">
  The three-letter ISO currency code for the disputed amount.

  Available options: `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`
</ResponseField>

<ResponseField name="customer_communication_attachment" type="object | null">
  Evidence of customer communication or product usage, uploaded as a dispute attachment. Null if not provided.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer_email_address" type="string | null">
  The customer's email address from their payment details, included in the evidence packet sent to the payment processor. Editable before submission.

  Example: `customer@example.com`
</ResponseField>

<ResponseField name="customer_name" type="string | null">
  The customer's full name from their payment details, included in the evidence packet sent to the payment processor. Editable before submission.

  Example: `Jane Doe`
</ResponseField>

<ResponseField name="editable" type="boolean | null">
  Whether the dispute evidence can still be edited and submitted.
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the dispute.

  Example: `dspt_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="needs_response_by" type="string<date-time> | null">
  The deadline by which dispute evidence must be submitted. Null if no response deadline is set.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="notes" type="string | null">
  Additional freeform notes submitted by the company as part of the dispute evidence.

  Example: `Customer used the product for 3 months before disputing.`
</ResponseField>

<ResponseField name="payment" type="object | null">
  The original payment that was disputed.

  <Expandable title="child attributes">
    <ResponseField name="billing_reason" type="BillingReasons | null">
      The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.

      Available options: `subscription_create`, `subscription_cycle`, `subscription_update`, `one_time`, `manual`, `subscription`
    </ResponseField>

    <ResponseField name="card_brand" type="CardBrands | null">
      Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.

      Available options: `mastercard`, `visa`, `amex`, `discover`, `unionpay`, `jcb`, `diners`, `link`, `troy`, `visadankort`, `visabancontact`, `china_union_pay`, `rupay`, `jcbrupay`, `elo`, `maestro`, `tarjeta_naranja`, `cirrus`, `nspk_mir`, `verve`, `ebt`, `private_label`, `local_brand`, `uatp`, `wexcard`, `uzcard`, `meeza`, `hrg_store_card`, `girocard`, `fuel_card`, `dankort`, `carnet`, `atm_card`, `china_union_payuzcard`, `codensa`, `cabal`, `hipercard`, `jcblankapay`, `cmi`, `aura`, `unknown`
    </ResponseField>

    <ResponseField name="card_last4" type="string | null">
      The last four digits of the card used to make this payment. Null if the payment was not made with a card.

      Example: `4242`
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the payment was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').

      Available options: `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`
    </ResponseField>

    <ResponseField name="dispute_alerted_at" type="string<date-time> | null">
      When an alert came in that this transaction will be disputed

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payment.

      Example: `pay_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="member" type="object | null">
      The member attached to this payment.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the company member.
        </ResponseField>

        <ResponseField name="phone" type="string | null">
          The phone number for the member, if available.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="membership" type="object | null">
      The membership attached to this payment.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the membership.

          Example: `mem_xxxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="status" type="MembershipStatus">
          The state of the membership.

          Available options: `trialing`, `active`, `past_due`, `completed`, `canceled`, `expired`, `unresolved`, `drafted`, `canceling`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="paid_at" type="string<date-time> | null">
      The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="payment_method_type" type="PaymentMethodTypes | null">
      The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.

      Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
    </ResponseField>

    <ResponseField name="subtotal" type="number | null">
      The subtotal to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="total" type="number | null">
      The total to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="usd_total" type="number | null">
      The total in USD to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="user" type="object | null">
      The user that made this payment.

      <Expandable title="child attributes">
        <ResponseField name="email" type="string | null">
          The user's email address. Requires the member:email:read permission to access. Null if not authorized.

          Example: `john.doe@example.com`
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique identifier for the user.

          Example: `user_xxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The user's display name shown on their public profile.

          Example: `John Doe`
        </ResponseField>

        <ResponseField name="username" type="string">
          The user's unique username shown on their public profile.

          Example: `johndoe42`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="plan" type="object | null">
  The plan associated with the disputed payment. Null if the dispute is not linked to a specific plan.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the plan.

      Example: `plan_xxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="product" type="object | null">
  The product associated with the disputed payment. Null if the dispute is not linked to a specific product.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="product_description" type="string | null">
  A description of the product or service provided, submitted as dispute evidence.

  Example: `Monthly subscription to premium analytics dashboard.`
</ResponseField>

<ResponseField name="reason" type="string | null">
  A human-readable reason for the dispute.

  Example: `Product Not Received`
</ResponseField>

<ResponseField name="reason_code" type="string | null">
  The card network reason code for the dispute. Null when the payment processor did not provide one.

  Example: `10.4`
</ResponseField>

<ResponseField name="refund_policy_attachment" type="object | null">
  The refund policy document uploaded as dispute evidence. Null if no refund policy has been provided.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="refund_policy_disclosure" type="string | null">
  A text disclosure describing the company's refund policy, submitted as dispute evidence.

  Example: `Refunds available within 14 days of purchase.`
</ResponseField>

<ResponseField name="refund_refusal_explanation" type="string | null">
  An explanation from the company for why a refund was refused, submitted as dispute evidence.

  Example: `The customer exceeded the refund window by 60 days.`
</ResponseField>

<ResponseField name="service_date" type="string | null">
  The date when the product or service was delivered to the customer, submitted as dispute evidence.

  Example: `2024-01-15`
</ResponseField>

<ResponseField name="status" type="DisputeStatuses">
  The current status of the dispute lifecycle, such as needs\_response, under\_review, won, or lost.

  Available options: `warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`, `closed`, `other`
</ResponseField>

<ResponseField name="uncategorized_attachment" type="object | null">
  An additional attachment that does not fit into the standard evidence categories. Null if not provided.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="visa_rdr" type="boolean">
  Whether the dispute was automatically resolved through Visa Rapid Dispute
  Resolution (RDR).
</ResponseField>


# Dispute created
Source: https://docs.whop.com/api-reference/disputes/dispute-created

/openapi/api-v1-stable.json webhook dispute.created
Sent when a dispute is created

Required permissions:
 - `payment:dispute:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `company:basic:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `webhook_receive:disputes`



# Dispute updated
Source: https://docs.whop.com/api-reference/disputes/dispute-updated

/openapi/api-v1-stable.json webhook dispute.updated
Sent when a dispute is updated

Required permissions:
 - `payment:dispute:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `company:basic:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `webhook_receive:disputes`



# List disputes
Source: https://docs.whop.com/api-reference/disputes/list-disputes

/openapi/api-v1-stable.json get /disputes
Returns a paginated list of disputes for a company, with optional filtering by creation date. A dispute represents a chargeback or inquiry filed by a customer against a payment.

Required permissions:
 - `payment:dispute:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `company:basic:read`
 - `payment:basic:read`



# Retrieve dispute
Source: https://docs.whop.com/api-reference/disputes/retrieve-dispute

/openapi/api-v1-stable.json get /disputes/{id}
Retrieves the details of an existing dispute.

Required permissions:
 - `payment:dispute:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `company:basic:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`



# Submit evidence
Source: https://docs.whop.com/api-reference/disputes/submit-evidence

/openapi/api-v1-stable.json post /disputes/{id}/submit_evidence
Submit a payment dispute to the payment processor for review. Once submitted, no further edits can be made.

Required permissions:
 - `payment:dispute`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `company:basic:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`



# Update evidence
Source: https://docs.whop.com/api-reference/disputes/update-evidence

/openapi/api-v1-stable.json post /disputes/{id}/update_evidence
Update a dispute with evidence data to attempt to win the dispute.

Required permissions:
 - `payment:dispute`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `company:basic:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`



# Forum
Source: https://docs.whop.com/api-reference/forums/forum

A discussion forum where members can create posts, comment, and react, belonging to an experience.

<ResponseExample>
  ```json Example theme={null}
  {
  	"email_notification_preference": "all_admin_posts",
  	"experience": {
  		"id": "exp_xxxxxxxxxxxxxx",
  		"name": "Trading Signals Chat"
  	},
  	"id": "<string>",
  	"who_can_comment": "everyone",
  	"who_can_post": "everyone"
  }
  ```
</ResponseExample>

<ResponseField name="email_notification_preference" type="ForumEmailNotificationPreferences">
  The email notification setting that controls which posts trigger email alerts. One of: all\_admin\_posts, only\_weekly\_summary, none.

  Available options: `all_admin_posts`, `only_weekly_summary`, `none`
</ResponseField>

<ResponseField name="experience" type="object">
  The parent experience that this forum belongs to.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the experience.

      Example: `exp_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of this experience shown to users in the product navigation. Maximum 255 characters.

      Example: `Trading Signals Chat`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the entity
</ResponseField>

<ResponseField name="who_can_comment" type="ForumWhoCanCommentTypes">
  The permission level controlling who can comment on posts. One of: everyone, admins.

  Available options: `everyone`, `admins`
</ResponseField>

<ResponseField name="who_can_post" type="ForumWhoCanPostTypes">
  The permission level controlling who can create new posts. One of: everyone, admins.

  Available options: `everyone`, `admins`
</ResponseField>


# List forums
Source: https://docs.whop.com/api-reference/forums/list-forums

/openapi/api-v1-stable.json get /forums
Returns a paginated list of forums within a specific company, with optional filtering by product.

Required permissions:
 - `forum:read`



# Retrieve forum
Source: https://docs.whop.com/api-reference/forums/retrieve-forum

/openapi/api-v1-stable.json get /forums/{id}
Retrieves the details of an existing forum.

Required permissions:
 - `forum:read`



# Update forum
Source: https://docs.whop.com/api-reference/forums/update-forum

/openapi/api-v1-stable.json patch /forums/{id}
Update moderation and notification settings for a forum, such as who can post, who can comment, and email notification preferences.

Required permissions:
 - `forum:moderate`



# Create invoice
Source: https://docs.whop.com/api-reference/invoices/create-invoice

/openapi/api-v1-stable.json post /invoices
Create an invoice for a customer. The invoice can be charged automatically using a stored payment method, or sent to the customer for manual payment.

Required permissions:
 - `invoice:create`
 - `member:email:read`



# Delete invoice
Source: https://docs.whop.com/api-reference/invoices/delete-invoice

/openapi/api-v1-stable.json delete /invoices/{id}
Delete a draft invoice.

Required permissions:
 - `invoice:update`



# Invoice
Source: https://docs.whop.com/api-reference/invoices/invoice

An invoice represents an itemized bill sent by a company to a customer for a specific product and plan, tracking the amount owed, due date, and payment status.

<ResponseExample>
  ```json Example theme={null}
  {
  	"automatically_finalizes_at": "2023-12-01T05:00:00.401Z",
  	"charge_buyer_fee": true,
  	"collection_method": "send_invoice",
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"current_plan": {
  		"currency": "usd",
  		"description": "Monthly access to all premium analytics dashboards and data exports.",
  		"formatted_price": "$10.00",
  		"id": "plan_xxxxxxxxxxxxx"
  	},
  	"customer_name": "Jane Doe",
  	"due_date": "2023-12-01T05:00:00.401Z",
  	"email_address": "customer@example.com",
  	"fetch_invoice_token": "eyJhbGciOiJIUzI1NiJ9...",
  	"id": "inv_xxxxxxxxxxxxxx",
  	"line_items": [
  		{
  			"label": "Platform subscription",
  			"position": 42,
  			"quantity": 6.9,
  			"total": 6.9,
  			"unit_price": 6.9
  		}
  	],
  	"mailing_address": {
  		"city": "<string>",
  		"country": "<string>",
  		"line1": "<string>",
  		"line2": "<string>",
  		"name": "<string>",
  		"phone": "<string>",
  		"postal_code": "<string>",
  		"state": "<string>"
  	},
  	"number": "#0001",
  	"pay_online_url": "<string>",
  	"product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"title": "Pickaxe Analytics"
  	},
  	"status": "draft",
  	"subscription_billing_anchor_at": "2023-12-01T05:00:00.401Z",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"email": "john.doe@example.com",
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="automatically_finalizes_at" type="string<date-time> | null">
  The date and time when the invoice will be automatically finalized. For charge\_automatically, triggers an automatic charge. For send\_invoice, sends the invoice email at the specified time.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="charge_buyer_fee" type="boolean">
  Whether the invoice includes a buyer processing fee on top of the plan price.
</ResponseField>

<ResponseField name="collection_method" type="InvoiceCollectionMethods">
  The method used to collect payment for this invoice, such as automatic charging or manual payment.

  Available options: `send_invoice`, `charge_automatically`
</ResponseField>

<ResponseField name="company" type="object">
  The company that issued this invoice.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the invoice was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="current_plan" type="object">
  The plan that this invoice charges for.

  <Expandable title="child attributes">
    <ResponseField name="currency" type="Currencies">
      The currency used for all prices on this plan (e.g., 'usd', 'eur'). All monetary amounts on the plan are denominated in this currency.

      Available options: `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`
    </ResponseField>

    <ResponseField name="description" type="string | null">
      A text description of the plan visible to customers. Maximum 1000 characters. Null if no description is set.

      Example: `Monthly access to all premium analytics dashboards and da…`
    </ResponseField>

    <ResponseField name="formatted_price" type="string">
      The formatted price (including currency) for the plan.

      Example: `$10.00`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the plan.

      Example: `plan_xxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer_name" type="string | null">
  The full name of the customer this invoice is addressed to. Null if no name is on file.

  Example: `Jane Doe`
</ResponseField>

<ResponseField name="due_date" type="string<date-time> | null">
  The deadline by which payment is expected. Null if the invoice is collected automatically.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="email_address" type="string | null">
  The email address of the customer this invoice is addressed to. Null if no email is on file.

  Example: `customer@example.com`
</ResponseField>

<ResponseField name="fetch_invoice_token" type="string">
  A signed token that allows fetching invoice data publicly without authentication.

  Example: `eyJhbGciOiJIUzI1NiJ9...`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the invoice.

  Example: `inv_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="line_items" type="array<object>">
  Optional line items that break down the invoice total into individual charges.

  <Expandable title="child attributes">
    <ResponseField name="label" type="string">
      The label or description for this line item.

      Example: `Platform subscription`
    </ResponseField>

    <ResponseField name="position" type="integer">
      The display order of this line item within the invoice.

      Example: `42`
    </ResponseField>

    <ResponseField name="quantity" type="number">
      The quantity of this line item.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="total" type="number">
      The computed total for this line item (quantity \* unit\_price).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="unit_price" type="number">
      The unit price for this line item.

      Example: `6.9`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="mailing_address" type="object | null">
  The billing/mailing address associated with this invoice, if one was provided at creation time.

  <Expandable title="child attributes">
    <ResponseField name="city" type="string | null">
      The city of the address.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      The country of the address.
    </ResponseField>

    <ResponseField name="line1" type="string | null">
      The line 1 of the address.
    </ResponseField>

    <ResponseField name="line2" type="string | null">
      The line 2 of the address.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The name of the customer.
    </ResponseField>

    <ResponseField name="phone" type="string | null">
      The phone number of the customer.
    </ResponseField>

    <ResponseField name="postal_code" type="string | null">
      The postal code of the address.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      The state of the address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="number" type="string">
  The sequential invoice number for display purposes.

  Example: `#0001`
</ResponseField>

<ResponseField name="pay_online_url" type="string | null">
  The checkout URL where the customer can pay this invoice online, with their
  email address pre-filled and locked.
</ResponseField>

<ResponseField name="product" type="object">
  The product that this invoice was generated for.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="InvoiceStatuses">
  The current payment status of the invoice, such as draft, open, paid, or void.

  Available options: `draft`, `open`, `paid`, `past_due`, `uncollectible`, `void`
</ResponseField>

<ResponseField name="subscription_billing_anchor_at" type="string<date-time> | null">
  The date that defines when the subscription billing cycle starts. When set on a renewal plan invoice, all future billing periods anchor to this date.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the invoice was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object | null">
  The user this invoice is addressed to. Null if the user account has been removed.

  <Expandable title="child attributes">
    <ResponseField name="email" type="string | null">
      The user's email address. Requires the member:email:read permission to access. Null if not authorized.

      Example: `john.doe@example.com`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# Invoice created
Source: https://docs.whop.com/api-reference/invoices/invoice-created

/openapi/api-v1-stable.json webhook invoice.created
Sent when a invoice is created

Required permissions:
 - `invoice:basic:read`
 - `member:email:read`
 - `webhook_receive:invoices`



# Invoice marked uncollectible
Source: https://docs.whop.com/api-reference/invoices/invoice-marked-uncollectible

/openapi/api-v1-stable.json webhook invoice.marked_uncollectible
Sent when a invoice is marked uncollectible

Required permissions:
 - `invoice:basic:read`
 - `member:email:read`
 - `webhook_receive:invoices`



# Invoice paid
Source: https://docs.whop.com/api-reference/invoices/invoice-paid

/openapi/api-v1-stable.json webhook invoice.paid
Sent when a invoice is paid

Required permissions:
 - `invoice:basic:read`
 - `member:email:read`
 - `webhook_receive:invoices`



# Invoice past due
Source: https://docs.whop.com/api-reference/invoices/invoice-past-due

/openapi/api-v1-stable.json webhook invoice.past_due
Sent when a invoice is past due

Required permissions:
 - `invoice:basic:read`
 - `member:email:read`
 - `webhook_receive:invoices`



# Invoice voided
Source: https://docs.whop.com/api-reference/invoices/invoice-voided

/openapi/api-v1-stable.json webhook invoice.voided
Sent when a invoice is voided

Required permissions:
 - `invoice:basic:read`
 - `member:email:read`
 - `webhook_receive:invoices`



# List invoices
Source: https://docs.whop.com/api-reference/invoices/list-invoices

/openapi/api-v1-stable.json get /invoices
Returns a paginated list of invoices for a company, with optional filtering by product, status, collection method, and creation date.

Required permissions:
 - `invoice:basic:read`



# Mark paid invoice
Source: https://docs.whop.com/api-reference/invoices/mark-paid-invoice

/openapi/api-v1-stable.json post /invoices/{id}/mark_paid
Mark an open invoice as paid when payment was collected outside of Whop.

Required permissions:
 - `invoice:update`



# Mark uncollectible invoice
Source: https://docs.whop.com/api-reference/invoices/mark-uncollectible-invoice

/openapi/api-v1-stable.json post /invoices/{id}/mark_uncollectible
Mark an open invoice as uncollectible when payment is not expected.

Required permissions:
 - `invoice:update`



# Resend invoice
Source: https://docs.whop.com/api-reference/invoices/resend-invoice

/openapi/api-v1-stable.json post /invoices/{id}/resend
Resend the notification email for an existing invoice to the customer.

Required permissions:
 - `invoice:update`



# Retrieve invoice
Source: https://docs.whop.com/api-reference/invoices/retrieve-invoice

/openapi/api-v1-stable.json get /invoices/{id}
Retrieves the details of an existing invoice.

Required permissions:
 - `invoice:basic:read`
 - `member:email:read`



# Update invoice
Source: https://docs.whop.com/api-reference/invoices/update-invoice

/openapi/api-v1-stable.json patch /invoices/{id}
Update a draft invoice's details.

Required permissions:
 - `invoice:update`
 - `member:email:read`



# Void invoice
Source: https://docs.whop.com/api-reference/invoices/void-invoice

/openapi/api-v1-stable.json post /invoices/{id}/void
Void an open invoice so it can no longer be paid. Voiding is permanent and cannot be undone.

Required permissions:
 - `invoice:update`



# Chat message created
Source: https://docs.whop.com/api-reference/messages/chat-message-created

/openapi/api-v1-stable.json webhook chat.message.created
Sent when a chat event is created

Required permissions:
 - `webhook_receive:chat`



# Create message
Source: https://docs.whop.com/api-reference/messages/create-message

/openapi/api-v1-stable.json post /messages
Send a new message in an experience chat, DM, or group chat channel. Supports text content, attachments, polls, and replies.

Required permissions:
 - `chat:message:create`



# Delete message
Source: https://docs.whop.com/api-reference/messages/delete-message

/openapi/api-v1-stable.json delete /messages/{id}
Permanently delete a message from an experience chat, DM, or group chat channel. Only the message author or a channel admin can delete a message.

Required permissions:
 - `chat:message:create`



# List messages
Source: https://docs.whop.com/api-reference/messages/list-messages

/openapi/api-v1-stable.json get /messages
Returns a paginated list of messages within a specific experience chat, DM, or group chat channel, sorted by creation time.

Required permissions:
 - `chat:read`



# Message
Source: https://docs.whop.com/api-reference/messages/message

A message sent within an experience chat, direct message, or group chat.

<ResponseExample>
  ```json Example theme={null}
  {
  	"content": "Hey, are you available for a **quick call**?",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"id": "<string>",
  	"is_edited": true,
  	"is_pinned": true,
  	"mentions": ["<string>"],
  	"mentions_everyone": true,
  	"message_type": "regular",
  	"poll": {
  		"options": [
  			{
  				"id": "<string>",
  				"text": "<string>"
  			}
  		]
  	},
  	"poll_votes": [
  		{
  			"count": 42,
  			"option_id": "<string>"
  		}
  	],
  	"reaction_counts": [
  		{
  			"count": 42,
  			"emoji": "<string>"
  		}
  	],
  	"replying_to_message_id": "<string>",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	},
  	"view_count": 42
  }
  ```
</ResponseExample>

<ResponseField name="content" type="string | null">
  The message content formatted as Markdown. Null if the message has no text content.

  Example: `Hey, are you available for a **quick call**?`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The timestamp when this message was originally created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string" />

<ResponseField name="is_edited" type="boolean">
  Whether the message content has been edited after it was originally sent.
</ResponseField>

<ResponseField name="is_pinned" type="boolean">
  Whether this message is pinned to the top of the channel for easy access.
</ResponseField>

<ResponseField name="mentions" type="array<string>">
  A list of user IDs that are explicitly mentioned in this message.
</ResponseField>

<ResponseField name="mentions_everyone" type="boolean">
  Whether the message includes an @everyone mention that notifies all channel
  members.
</ResponseField>

<ResponseField name="message_type" type="DmsPostTypes">
  The classification of this message: regular, system, or automated.

  Available options: `regular`, `system`, `automated`
</ResponseField>

<ResponseField name="poll" type="object | null">
  A poll attached to this message. Null if the message does not contain a poll.

  <Expandable title="child attributes">
    <ResponseField name="options" type="array<object> | null">
      The options for the poll

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the poll option.
        </ResponseField>

        <ResponseField name="text" type="string">
          The text of the poll option
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="poll_votes" type="array<object>">
  Aggregated reaction counts on this message, filtered to a specific reaction type.

  <Expandable title="child attributes">
    <ResponseField name="count" type="integer">
      The number of users who reacted

      Example: `42`
    </ResponseField>

    <ResponseField name="option_id" type="string | null">
      The reaction that was used
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reaction_counts" type="array<object>">
  Aggregated reaction counts on this message, filtered to a specific reaction type.

  <Expandable title="child attributes">
    <ResponseField name="count" type="integer">
      The number of users who reacted

      Example: `42`
    </ResponseField>

    <ResponseField name="emoji" type="string | null">
      The emoji that was used in shortcode format (:heart:)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="replying_to_message_id" type="string | null">
  The unique identifier of the message this post is replying to. Null if this is
  not a reply.
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The timestamp when this message was last modified.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object">
  The user who authored this message.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="view_count" type="integer | null">
  The number of unique views this message has received. Null if view tracking is not enabled for this channel.

  Example: `42`
</ResponseField>


# Retrieve message
Source: https://docs.whop.com/api-reference/messages/retrieve-message

/openapi/api-v1-stable.json get /messages/{id}
Retrieves the details of an existing message.

Required permissions:
 - `chat:read`



# Update message
Source: https://docs.whop.com/api-reference/messages/update-message

/openapi/api-v1-stable.json patch /messages/{id}
Edit the content, attachments, or pinned status of an existing message in an experience chat, DM, or group chat channel.



# Create notification
Source: https://docs.whop.com/api-reference/notifications/create-notification

/openapi/api-v1-stable.json post /notifications
Send a push notification to users in an experience or company team. The notification is processed asynchronously and supports targeting specific users.

Required permissions:
 - `notification:create`



# Delete payment method
Source: https://docs.whop.com/api-reference/payment-methods/delete-payment-method

/openapi/api-v1-stable.json delete /payment_methods/{id}
Delete a saved payment method. Cannot delete a payment method attached to an active subscription.

Required permissions:
 - `member:payment_methods:manage`



# List payment methods
Source: https://docs.whop.com/api-reference/payment-methods/list-payment-methods

/openapi/api-v1-stable.json get /payment_methods
Returns a paginated list of payment methods for a member or company, or for the authenticated user when neither is given, with optional filtering by creation date. A payment method is a stored representation of how a customer intends to pay, such as a card, bank account, or digital wallet.

Required permissions:
 - `member:payment_methods:read`



# Payment Method
Source: https://docs.whop.com/api-reference/payment-methods/payment-method



<ResponseExample>
  ```json Example theme={null}
  {
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"id": "payt_xxxxxxxxxxxxx",
  	"payment_method_type": "acss_debit",
  	"typename": "BasePaymentMethod"
  }
  ```
</ResponseExample>

This object is one of the following variants, distinguished by `typename`:

### Base Payment Method

<ResponseField name="created_at" type="string<date-time>">
  The time of the event in ISO 8601 UTC format with millisecond precision

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  Example: `payt_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="payment_method_type" type="PaymentMethodTypes">
  The type of payment instrument stored on file (e.g., card, us\_bank\_account, cashapp, ideal, sepa\_debit).

  Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
</ResponseField>

<ResponseField name="typename" type="string">
  The typename of this object
</ResponseField>

### Card Payment Method

<ResponseField name="card" type="object">
  The card-specific details for this payment method, including brand, last four digits, and expiration.

  <Expandable title="child attributes">
    <ResponseField name="brand" type="CardBrands | null">
      The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.

      Available options: `mastercard`, `visa`, `amex`, `discover`, `unionpay`, `jcb`, `diners`, `link`, `troy`, `visadankort`, `visabancontact`, `china_union_pay`, `rupay`, `jcbrupay`, `elo`, `maestro`, `tarjeta_naranja`, `cirrus`, `nspk_mir`, `verve`, `ebt`, `private_label`, `local_brand`, `uatp`, `wexcard`, `uzcard`, `meeza`, `hrg_store_card`, `girocard`, `fuel_card`, `dankort`, `carnet`, `atm_card`, `china_union_payuzcard`, `codensa`, `cabal`, `hipercard`, `jcblankapay`, `cmi`, `aura`, `unknown`
    </ResponseField>

    <ResponseField name="exp_month" type="integer | null">
      The two-digit expiration month of the card (1-12). Null if not available.

      Example: `42`
    </ResponseField>

    <ResponseField name="exp_year" type="integer | null">
      The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.

      Example: `42`
    </ResponseField>

    <ResponseField name="last4" type="string | null">
      The last four digits of the card number. Null if not available.

      Example: `4242`
    </ResponseField>

    <ResponseField name="three_ds_verified" type="boolean">
      Whether this card was verified with 3D Secure, either when it was saved or on a payment that used it.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The time of the event in ISO 8601 UTC format with millisecond precision

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string" />

<ResponseField name="payment_method_type" type="PaymentMethodTypes">
  The type of payment instrument stored on file (e.g., card, us\_bank\_account, cashapp, ideal, sepa\_debit).

  Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
</ResponseField>

<ResponseField name="typename" type="string">
  The typename of this object
</ResponseField>

### Us Bank Account Payment Method

<ResponseField name="created_at" type="string<date-time>">
  The time of the event in ISO 8601 UTC format with millisecond precision

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string" />

<ResponseField name="payment_method_type" type="PaymentMethodTypes">
  The type of payment instrument stored on file (e.g., card, us\_bank\_account, cashapp, ideal, sepa\_debit).

  Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
</ResponseField>

<ResponseField name="typename" type="string">
  The typename of this object
</ResponseField>

<ResponseField name="us_bank_account" type="object">
  The bank account-specific details for this payment method, including bank name and last four digits.

  <Expandable title="child attributes">
    <ResponseField name="account_type" type="string">
      The type of bank account (e.g., checking, savings).

      Example: `checking`
    </ResponseField>

    <ResponseField name="bank_name" type="string">
      The name of the financial institution holding the account.

      Example: `Chase`
    </ResponseField>

    <ResponseField name="last4" type="string">
      The last four digits of the bank account number.

      Example: `6789`
    </ResponseField>
  </Expandable>
</ResponseField>

### Cashapp Payment Method

<ResponseField name="cashapp" type="object">
  The Cash App-specific details for this payment method, including cashtag and buyer ID.

  <Expandable title="child attributes">
    <ResponseField name="buyer_id" type="string | null">
      The unique and immutable identifier assigned by Cash App to the buyer. Null if not available.

      Example: `BUYER_abc123`
    </ResponseField>

    <ResponseField name="cashtag" type="string | null">
      The public cashtag handle of the buyer on Cash App. Null if not available.

      Example: `$jacksmith`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The time of the event in ISO 8601 UTC format with millisecond precision

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string" />

<ResponseField name="payment_method_type" type="PaymentMethodTypes">
  The type of payment instrument stored on file (e.g., card, us\_bank\_account, cashapp, ideal, sepa\_debit).

  Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
</ResponseField>

<ResponseField name="typename" type="string">
  The typename of this object
</ResponseField>

### Ideal Payment Method

<ResponseField name="created_at" type="string<date-time>">
  The time of the event in ISO 8601 UTC format with millisecond precision

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string" />

<ResponseField name="ideal" type="object">
  The iDEAL-specific details for this payment method, including bank name and BIC.

  <Expandable title="child attributes">
    <ResponseField name="bank" type="string | null">
      The name of the customer's bank used for the iDEAL transaction. Null if not available.

      Example: `ing`
    </ResponseField>

    <ResponseField name="bic" type="string | null">
      The Bank Identifier Code (BIC/SWIFT) of the customer's bank. Null if not available.

      Example: `INGBNL2A`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_method_type" type="PaymentMethodTypes">
  The type of payment instrument stored on file (e.g., card, us\_bank\_account, cashapp, ideal, sepa\_debit).

  Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
</ResponseField>

<ResponseField name="typename" type="string">
  The typename of this object
</ResponseField>

### Sepa Debit Payment Method

<ResponseField name="created_at" type="string<date-time>">
  The time of the event in ISO 8601 UTC format with millisecond precision

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string" />

<ResponseField name="payment_method_type" type="PaymentMethodTypes">
  The type of payment instrument stored on file (e.g., card, us\_bank\_account, cashapp, ideal, sepa\_debit).

  Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
</ResponseField>

<ResponseField name="sepa_debit" type="object">
  The SEPA Direct Debit-specific details for this payment method, including bank code and last four IBAN digits.

  <Expandable title="child attributes">
    <ResponseField name="bank_code" type="string | null">
      The bank code of the financial institution associated with this SEPA account. Null if not available.

      Example: `37040044`
    </ResponseField>

    <ResponseField name="branch_code" type="string | null">
      The branch code of the financial institution associated with this SEPA account. Null if not available.

      Example: `0532`
    </ResponseField>

    <ResponseField name="country" type="string | null">
      The two-letter ISO country code where the bank account is located. Null if not available.

      Example: `DE`
    </ResponseField>

    <ResponseField name="last4" type="string | null">
      The last four digits of the IBAN associated with this SEPA account. Null if not available.

      Example: `3000`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="typename" type="string">
  The typename of this object
</ResponseField>

### Platform Balance Payment Method

<ResponseField name="created_at" type="string<date-time>">
  The time of the event in ISO 8601 UTC format with millisecond precision

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string" />

<ResponseField name="payment_method_type" type="PaymentMethodTypes">
  The type of payment instrument stored on file (e.g., card, us\_bank\_account, cashapp, ideal, sepa\_debit).

  Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
</ResponseField>

<ResponseField name="platform_balance" type="object">
  What is available to spend, and whether the account may spend it.

  <Expandable title="child attributes">
    <ResponseField name="balances" type="array<object>">
      Available amount per currency. Read from the balance cache, so it is indicative — the charge revalidates against settled funds and may still refuse.

      <Expandable title="child attributes">
        <ResponseField name="amount" type="number">
          The available amount in this currency.

          Example: `52.1`
        </ResponseField>

        <ResponseField name="currency" type="Currencies">
          The currency this amount is held in.

          Available options: `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`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="spendable" type="boolean">
      Whether this balance can pay right now, which here means only whether it holds funds — an account blocked from spending is not listed at all. A zero balance is still returned so a client can show it as an option the buyer could top up.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="typename" type="string">
  The typename of this object
</ResponseField>


# Retrieve payment method
Source: https://docs.whop.com/api-reference/payment-methods/retrieve-payment-method

/openapi/api-v1-stable.json get /payment_methods/{id}
Retrieves the details of an existing payment method. Addresses a member's wallet when member_id or company_id is given, otherwise your own.

Required permissions:
 - `member:payment_methods:read`



# Create payment
Source: https://docs.whop.com/api-reference/payments/create-payment

/openapi/api-v1-stable.json post /payments
Charge an existing member off-session using one of their stored payment methods. You can provide an existing plan, or create a new one in-line. This endpoint will respond with a payment object immediately, but the payment is processed asynchronously in the background. Use webhooks to be notified when the payment succeeds or fails.

Required permissions:
 - `payment:charge`
 - `plan:create`
 - `access_pass:create`
 - `access_pass:update`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`



# List fees
Source: https://docs.whop.com/api-reference/payments/list-fees

/openapi/api-v1-stable.json get /payments/{id}/fees
Returns the list of fees associated with a specific payment, including platform fees and processing fees.

Required permissions:
 - `payment:basic:read`



# List payments
Source: https://docs.whop.com/api-reference/payments/list-payments

/openapi/api-v1-stable.json get /payments
Returns a paginated list of payments for the actor in context, with optional filtering by product, plan, status, billing reason, currency, and creation date.

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`



# Payment
Source: https://docs.whop.com/api-reference/payments/payment

A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.

<ResponseExample>
  ```json Example theme={null}
  {
  	"amount_after_fees": 6.9,
  	"application_fee": {
  		"amount": 6.9,
  		"amount_captured": 6.9,
  		"amount_refunded": 6.9,
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"currency": "usd",
  		"id": "apfee_xxxxxxxxxxxx"
  	},
  	"auto_refunded": true,
  	"billing_address": {
  		"city": "<string>",
  		"country": "<string>",
  		"line1": "<string>",
  		"line2": "<string>",
  		"name": "<string>",
  		"postal_code": "<string>",
  		"state": "<string>"
  	},
  	"billing_reason": "subscription_create",
  	"card_brand": "mastercard",
  	"card_exp_month": 6,
  	"card_exp_year": 2027,
  	"card_last4": "4242",
  	"checkout_configuration_id": "ch_xxxxxxxxxxxxxxx",
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"route": "<string>",
  		"title": "<string>"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"customer_phone": "<string>",
  	"decline_code": "insufficient_funds",
  	"dispute_alerted_at": "2023-12-01T05:00:00.401Z",
  	"disputes": [
  		{
  			"amount": 6.9,
  			"currency": "usd",
  			"editable": true,
  			"id": "dspt_xxxxxxxxxxxxx",
  			"needs_response_by": "2023-12-01T05:00:00.401Z",
  			"notes": "Customer used the product for 3 months before disputing.",
  			"reason": "Product Not Received",
  			"status": "warning_needs_response"
  		}
  	],
  	"failure_message": "<string>",
  	"financing_installments_count": 42,
  	"financing_transactions": [
  		{
  			"amount": 6.9,
  			"created_at": "2023-12-01T05:00:00.401Z",
  			"id": "ptx_xxxxxxxxxxxxxx",
  			"status": "succeeded",
  			"transaction_type": "purchase"
  		}
  	],
  	"id": "pay_xxxxxxxxxxxxxx",
  	"last_payment_attempt": "2023-12-01T05:00:00.401Z",
  	"member": {
  		"id": "<string>",
  		"phone": "<string>"
  	},
  	"membership": {
  		"id": "mem_xxxxxxxxxxxxxx",
  		"phone_number": "<string>",
  		"status": "trialing"
  	},
  	"metadata": {},
  	"needs_tracking": true,
  	"next_payment_attempt": "2023-12-01T05:00:00.401Z",
  	"paid_at": "2023-12-01T05:00:00.401Z",
  	"payment_method": {
  		"card": {
  			"brand": "mastercard",
  			"exp_month": 42,
  			"exp_year": 42,
  			"last4": "4242"
  		},
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"id": "payt_xxxxxxxxxxxxx",
  		"payment_method_type": "acss_debit"
  	},
  	"payment_method_type": "acss_debit",
  	"payments_failed": 42,
  	"plan": {
  		"id": "plan_xxxxxxxxxxxxx",
  		"internal_notes": "<string>",
  		"metadata": {}
  	},
  	"product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"metadata": {},
  		"route": "pickaxe-analytics",
  		"title": "Pickaxe Analytics"
  	},
  	"promo_code": {
  		"amount_off": 6.9,
  		"base_currency": "usd",
  		"code": "<string>",
  		"id": "promo_xxxxxxxxxxxx",
  		"number_of_intervals": 42,
  		"promo_type": "percentage"
  	},
  	"refundable": true,
  	"refunded_amount": 6.9,
  	"refunded_at": "2023-12-01T05:00:00.401Z",
  	"refunds": [
  		{
  			"amount": 6.9,
  			"created_at": "2023-12-01T05:00:00.401Z",
  			"currency": "usd",
  			"id": "rf_xxxxxxxxxxxxxxx",
  			"status": "pending"
  		}
  	],
  	"resolutions": [
  		{
  			"customer_appealed": true,
  			"customer_response_actions": ["respond"],
  			"due_date": "2023-12-01T05:00:00.401Z",
  			"id": "reso_xxxxxxxxxxxxx",
  			"issue": "forgot_to_cancel",
  			"merchant_appealed": true,
  			"merchant_response_actions": ["accept"],
  			"platform_response_actions": ["request_buyer_info"],
  			"status": "merchant_response_needed"
  		}
  	],
  	"retryable": true,
  	"risk_score": 42,
  	"risk_signals": {},
  	"settlement_amount": 6.9,
  	"settlement_currency": "usd",
  	"settlement_exchange_rate": 6.9,
  	"settlement_time_at": "2023-12-01T05:00:00.401Z",
  	"shipment": {
  		"carrier": "usps",
  		"id": "ship_xxxxxxxxxxxxx",
  		"status": "unknown",
  		"tracking_number": "9400111899223456789012",
  		"tracking_url": "https://track.aftership.com/9400111899223456789012"
  	},
  	"shipping_address": {
  		"city": "<string>",
  		"country": "<string>",
  		"line1": "<string>",
  		"line2": "<string>",
  		"name": "<string>",
  		"postal_code": "<string>",
  		"state": "<string>"
  	},
  	"status": "draft",
  	"substatus": "succeeded",
  	"subtotal": 6.9,
  	"tax_amount": 6.9,
  	"tax_behavior": "exclusive",
  	"tax_refunded_amount": 6.9,
  	"three_ds_verified": true,
  	"total": 6.9,
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"usd_total": 6.9,
  	"user": {
  		"email": "john.doe@example.com",
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	},
  	"verification_checks": {
  		"address_line1": "<string>",
  		"card_holder_name": "<string>",
  		"card_security_code": "<string>",
  		"zip_code": "<string>"
  	},
  	"voidable": true
  }
  ```
</ResponseExample>

<ResponseField name="amount_after_fees" type="number">
  How much the payment is for after fees

  Example: `6.9`
</ResponseField>

<ResponseField name="application_fee" type="object | null">
  The application fee charged on this payment.

  <Expandable title="child attributes">
    <ResponseField name="amount" type="number">
      The application fee amount.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="amount_captured" type="number">
      The amount of the application fee that has been captured.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="amount_refunded" type="number">
      The amount of the application fee that has been refunded.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the application fee was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The currency of the application fee.

      Available options: `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`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the application fee.

      Example: `apfee_xxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="auto_refunded" type="boolean">
  Whether this payment was auto refunded or not
</ResponseField>

<ResponseField name="billing_address" type="object | null">
  The address of the user who made the payment.

  <Expandable title="child attributes">
    <ResponseField name="city" type="string | null">
      The city of the address.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      The country of the address.
    </ResponseField>

    <ResponseField name="line1" type="string | null">
      The line 1 of the address.
    </ResponseField>

    <ResponseField name="line2" type="string | null">
      The line 2 of the address.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The name of the customer.
    </ResponseField>

    <ResponseField name="postal_code" type="string | null">
      The postal code of the address.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      The state of the address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="billing_reason" type="BillingReasons | null">
  The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.

  Available options: `subscription_create`, `subscription_cycle`, `subscription_update`, `one_time`, `manual`, `subscription`
</ResponseField>

<ResponseField name="card_brand" type="CardBrands | null">
  Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.

  Available options: `mastercard`, `visa`, `amex`, `discover`, `unionpay`, `jcb`, `diners`, `link`, `troy`, `visadankort`, `visabancontact`, `china_union_pay`, `rupay`, `jcbrupay`, `elo`, `maestro`, `tarjeta_naranja`, `cirrus`, `nspk_mir`, `verve`, `ebt`, `private_label`, `local_brand`, `uatp`, `wexcard`, `uzcard`, `meeza`, `hrg_store_card`, `girocard`, `fuel_card`, `dankort`, `carnet`, `atm_card`, `china_union_payuzcard`, `codensa`, `cabal`, `hipercard`, `jcblankapay`, `cmi`, `aura`, `unknown`
</ResponseField>

<ResponseField name="card_exp_month" type="integer | null">
  The expiration month (1-12) of the card used for this payment. Falls back to the declined card on failed payments with no saved card. Null when the payment was not made with a card or the expiry is unavailable.

  Example: `6`
</ResponseField>

<ResponseField name="card_exp_year" type="integer | null">
  The four-digit expiration year of the card used for this payment. Falls back to the declined card on failed payments with no saved card. Null when the payment was not made with a card or the expiry is unavailable.

  Example: `2027`
</ResponseField>

<ResponseField name="card_last4" type="string | null">
  The last four digits of the card used to make this payment. Null if the payment was not made with a card.

  Example: `4242`
</ResponseField>

<ResponseField name="checkout_configuration_id" type="string | null">
  The ID of the checkout session/configuration that produced this payment, if any. Use this to map payments back to the checkout configuration that created them.

  Example: `ch_xxxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="company" type="object | null">
  The company for the payment.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="route" type="string">
      The slug/route of the company on the Whop site.
    </ResponseField>

    <ResponseField name="title" type="string">
      The written name of the company.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the payment was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies">
  The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').

  Available options: `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`
</ResponseField>

<ResponseField name="customer_phone" type="string | null">
  Phone number the customer provided at checkout, or their verified phone number
  when your checkout requires phone verification. `null` when no phone number
  was collected.
</ResponseField>

<ResponseField name="decline_code" type="PaymentDeclineCodes | null">
  The reason the payment was declined. Null if the payment did not fail.

  Available options: `insufficient_funds`, `lost_card`, `stolen_card`, `expired_card`, `suspected_fraud`, `invalid_card_number`, `invalid_cvc`, `invalid_cvc_or_expiration`, `incorrect_pin`, `authentication_required`, `card_not_supported`, `currency_not_supported`, `duplicate_transaction`, `generic_decline`, `invalid_account`, `invalid_amount`, `processing_error`, `restricted_card`, `card_velocity_exceeded`, `contact_issuer`, `bank_declined`, `regulatory_blocked`, `transaction_not_permitted`, `transaction_stopped`, `card_type_not_supported`, `issuer_not_found`, `closed_account`, `issuer_unavailable`, `invalid_zip`, `invalid_expiry_month`, `invalid_expiry_year`, `invalid_expiry`, `invalid_transaction`, `cannot_authorize`, `pin_required`, `pin_try_exceeded`, `provider_declined`, `high_risk`, `test_mode_decline`, `merchant_blacklist`, `reenter_transaction`, `invalid_pin`, `pin_required_as`, `withdrawal_count_limit_exceeded`, `invalid_country`, `issuer_error`, `invalid_card_holder_name`, `no_accounts`, `transaction_cancelled`, `three_d_secure_success`, `three_d_secure_canceled`, `three_d_secure_invalid_card_number`, `three_d_secure_generic_error`, `three_d_secure_timeout`, `three_d_secure_failed`, `three_d_secure_card_not_enrolled`, `three_d_secure_fraud`, `three_d_secure_too_many_attempts`, `three_d_secure_rejected_by_bank`, `three_d_secure_reported_lost_or_stolen`, `blocked_by_cardholder`, `test_mode_test_card`, `try_again_later`, `transaction_not_allowed`, `bank_insufficient_funds`, `bank_account_not_found`, `bank_account_closed`, `bank_account_frozen`, `bank_invalid_routing_number`, `bank_non_transaction_account`, `bank_authorization_revoked`, `bank_payment_stopped`, `bank_not_authorized`, `bank_account_holder_deceased`, `bank_duplicate`, `bank_amount_error`, `bank_regulatory_blocked`, `bank_details_invalid`, `bank_processing_error`, `bank_generic_decline`, `sepa_invalid_iban`, `sepa_no_mandate`, `sepa_mandate_data_invalid`, `sepa_disputed`, `sepa_refused_by_customer`, `sepa_generic_decline`
</ResponseField>

<ResponseField name="dispute_alerted_at" type="string<date-time> | null">
  When an alert came in that this transaction will be disputed

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="disputes" type="array<object> | null">
  The disputes attached to this payment. Null if the actor in context does not have the payment:dispute:read permission.

  <Expandable title="child attributes">
    <ResponseField name="amount" type="number">
      The disputed amount in the specified currency, formatted as a decimal.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The three-letter ISO currency code for the disputed amount.

      Available options: `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`
    </ResponseField>

    <ResponseField name="editable" type="boolean | null">
      Whether the dispute evidence can still be edited and submitted.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the dispute.

      Example: `dspt_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="needs_response_by" type="string<date-time> | null">
      The deadline by which dispute evidence must be submitted. Null if no response deadline is set.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="notes" type="string | null">
      Additional freeform notes submitted by the company as part of the dispute evidence.

      Example: `Customer used the product for 3 months before disputing.`
    </ResponseField>

    <ResponseField name="reason" type="string | null">
      A human-readable reason for the dispute.

      Example: `Product Not Received`
    </ResponseField>

    <ResponseField name="status" type="DisputeStatuses">
      The current status of the dispute lifecycle, such as needs\_response, under\_review, won, or lost.

      Available options: `warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`, `closed`, `other`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="failure_message" type="string | null">
  If the payment failed, the reason for the failure.
</ResponseField>

<ResponseField name="financing_installments_count" type="integer | null">
  The number of financing installments for the payment. Present if the payment is a financing payment (e.g. Splitit, Klarna, etc.).

  Example: `42`
</ResponseField>

<ResponseField name="financing_transactions" type="array<object>">
  The financing transactions attached to this payment. Present if the payment is a financing payment (e.g. Splitit, Klarna, etc.).

  <Expandable title="child attributes">
    <ResponseField name="amount" type="number">
      The amount of the payment transaction.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The date and time the payment transaction was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payment transaction.

      Example: `ptx_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="status" type="PaymentTransactionStatuses">
      The status of the payment transaction.

      Available options: `succeeded`, `declined`, `error`, `pending`, `created`, `expired`, `won`, `rejected`, `lost`, `prevented`, `canceled`
    </ResponseField>

    <ResponseField name="transaction_type" type="PaymentTransactionTypes">
      The type of the payment transaction.

      Available options: `purchase`, `authorize`, `capture`, `refund`, `canceled`, `verify`, `chargeback`, `pre_chargeback`, `three_d_secure`, `fraud_screening`, `authorization`, `installment`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the payment.

  Example: `pay_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="last_payment_attempt" type="string<date-time> | null">
  The time of the last payment attempt.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="member" type="object | null">
  The member attached to this payment.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company member.
    </ResponseField>

    <ResponseField name="phone" type="string | null">
      The phone number for the member, if available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="membership" type="object | null">
  The membership attached to this payment.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the membership.

      Example: `mem_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="phone_number" type="string | null">
      The phone number associated with this membership.
    </ResponseField>

    <ResponseField name="status" type="MembershipStatus">
      The state of the membership.

      Available options: `trialing`, `active`, `past_due`, `completed`, `canceled`, `expired`, `unresolved`, `drafted`, `canceling`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object | null">
  The custom metadata stored on this payment. This will be copied over to the
  checkout configuration for which this payment was made
</ResponseField>

<ResponseField name="needs_tracking" type="boolean | null">
  Whether this payment is holding funds until the order ships and has no
  tracking number yet.
</ResponseField>

<ResponseField name="next_payment_attempt" type="string<date-time> | null">
  The time of the next schedule payment retry.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="paid_at" type="string<date-time> | null">
  The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="payment_method" type="object | null">
  The tokenized payment method reference used for this payment. Null if no token was used.

  <Expandable title="child attributes">
    <ResponseField name="card" type="object | null">
      The card data associated with the payment method, if its a debit or credit card.

      <Expandable title="child attributes">
        <ResponseField name="brand" type="CardBrands | null">
          The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.

          Available options: `mastercard`, `visa`, `amex`, `discover`, `unionpay`, `jcb`, `diners`, `link`, `troy`, `visadankort`, `visabancontact`, `china_union_pay`, `rupay`, `jcbrupay`, `elo`, `maestro`, `tarjeta_naranja`, `cirrus`, `nspk_mir`, `verve`, `ebt`, `private_label`, `local_brand`, `uatp`, `wexcard`, `uzcard`, `meeza`, `hrg_store_card`, `girocard`, `fuel_card`, `dankort`, `carnet`, `atm_card`, `china_union_payuzcard`, `codensa`, `cabal`, `hipercard`, `jcblankapay`, `cmi`, `aura`, `unknown`
        </ResponseField>

        <ResponseField name="exp_month" type="integer | null">
          The two-digit expiration month of the card (1-12). Null if not available.

          Example: `42`
        </ResponseField>

        <ResponseField name="exp_year" type="integer | null">
          The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.

          Example: `42`
        </ResponseField>

        <ResponseField name="last4" type="string | null">
          The last four digits of the card number. Null if not available.

          Example: `4242`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the payment token was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payment token.

      Example: `payt_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="payment_method_type" type="PaymentMethodTypes">
      The payment method type of the payment method

      Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_method_type" type="PaymentMethodTypes | null">
  The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.

  Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
</ResponseField>

<ResponseField name="payments_failed" type="integer | null">
  The number of failed payment attempts for the payment.

  Example: `42`
</ResponseField>

<ResponseField name="plan" type="object | null">
  The plan attached to this payment.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the plan.

      Example: `plan_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="internal_notes" type="string | null">
      A personal description or notes section for the business.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="product" type="object | null">
  The product this payment was made for

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value pairs stored on the product and included in payment and
      membership webhook payloads. Max 50 keys, 100 characters per key, 500
      characters per string value.
    </ResponseField>

    <ResponseField name="route" type="string">
      URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.

      Example: `pickaxe-analytics`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="promo_code" type="object | null">
  The promo code used for this payment.

  <Expandable title="child attributes">
    <ResponseField name="amount_off" type="number">
      The discount amount. Interpretation depends on promo\_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat\_amount', this is dollars off (e.g., 10.00 means \$10.00 off).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="base_currency" type="Currencies">
      The monetary currency of the promo code.

      Available options: `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`
    </ResponseField>

    <ResponseField name="code" type="string | null">
      The specific code used to apply the promo at checkout.
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the promo code.

      Example: `promo_xxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="number_of_intervals" type="integer | null">
      The number of months the promo is applied for.

      Example: `42`
    </ResponseField>

    <ResponseField name="promo_type" type="PromoTypes">
      The type (% or flat amount) of the promo.

      Available options: `percentage`, `flat_amount`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="refundable" type="boolean">
  True only for payments that are `paid`, have not been fully refunded, and were
  processed by a payment processor that allows refunds.
</ResponseField>

<ResponseField name="refunded_amount" type="number | null">
  The payment refund amount(if applicable).

  Example: `6.9`
</ResponseField>

<ResponseField name="refunded_at" type="string<date-time> | null">
  When the payment was refunded (if applicable).

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="refunds" type="array<object>">
  The refunds issued against this payment, newest first, including failed and canceled refund attempts. Limited to the 100 most recent.

  <Expandable title="child attributes">
    <ResponseField name="amount" type="number">
      The refunded amount as a decimal in the specified currency, such as 10.43 for \$10.43 USD.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the refund was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The three-letter ISO currency code for the refunded amount.

      Available options: `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`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the refund.

      Example: `rf_xxxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="status" type="RefundStatuses">
      The current processing status of the refund, such as pending, succeeded, or failed.

      Available options: `pending`, `requires_action`, `succeeded`, `failed`, `canceled`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="resolutions" type="array<object> | null">
  The resolution center cases opened by the customer on this payment. Null if the actor in context does not have the payment:resolution\_center\_case:read permission.

  <Expandable title="child attributes">
    <ResponseField name="customer_appealed" type="boolean">
      Whether the customer has filed an appeal after the initial resolution
      decision.
    </ResponseField>

    <ResponseField name="customer_response_actions" type="array<ResolutionCenterCaseCustomerResponses>">
      The list of actions currently available to the customer.

      Available options: `respond`, `appeal`, `withdraw`
    </ResponseField>

    <ResponseField name="due_date" type="string<date-time> | null">
      The deadline by which the next response is required. Null if no deadline is currently active. As a Unix timestamp.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the resolution.

      Example: `reso_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="issue" type="ResolutionCenterCaseIssueTypes">
      The category of the dispute.

      Available options: `forgot_to_cancel`, `item_not_received`, `significantly_not_as_described`, `unauthorized_transaction`, `product_unacceptable`
    </ResponseField>

    <ResponseField name="merchant_appealed" type="boolean">
      Whether the merchant has filed an appeal after the initial resolution
      decision.
    </ResponseField>

    <ResponseField name="merchant_response_actions" type="array<ResolutionCenterCaseMerchantResponses>">
      The list of actions currently available to the merchant.

      Available options: `accept`, `deny`, `request_more_info`, `appeal`, `respond`
    </ResponseField>

    <ResponseField name="platform_response_actions" type="array<ResolutionCenterCasePlatformResponses>">
      The list of actions currently available to the Whop platform for moderating this resolution.

      Available options: `request_buyer_info`, `request_merchant_info`, `merchant_wins`, `merchant_refund`
    </ResponseField>

    <ResponseField name="status" type="ResolutionCenterCaseStatuses">
      The current status of the resolution case, indicating which party needs to respond or if the case is closed.

      Available options: `merchant_response_needed`, `customer_response_needed`, `merchant_info_needed`, `customer_info_needed`, `under_platform_review`, `customer_won`, `merchant_won`, `customer_withdrew`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="retryable" type="boolean">
  True when the payment status is `open` and its membership is in one of the
  retry-eligible states (`active`, `trialing`, `completed`, or `past_due`), or
  when it is a failed initial billing-engine payment on a `drafted` membership
  with an unlimited-stock plan; otherwise false. Used to decide if Whop can
  attempt the charge again.
</ResponseField>

<ResponseField name="risk_score" type="integer | null">
  Whop's in-house fraud risk score for this payment, from 0 (lowest risk) to 100 (highest risk). Null when the payment has not been scored or scoring has not yet completed.

  Example: `42`
</ResponseField>

<ResponseField name="risk_signals" type="object | null">
  A curated set of factors behind the risk score, grouped by category (business
  transaction history, buyer, device). Each entry has a key, human-readable
  label, category, and value. Null when there is no risk assessment for this
  payment.
</ResponseField>

<ResponseField name="settlement_amount" type="number">
  The total amount charged to the customer for this payment, including taxes and after any discounts. In the currency specified by the currency field.

  Example: `6.9`
</ResponseField>

<ResponseField name="settlement_currency" type="Currencies">
  The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').

  Available options: `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`
</ResponseField>

<ResponseField name="settlement_exchange_rate" type="number | null">
  Deprecated. Always returns null.

  Example: `6.9`
</ResponseField>

<ResponseField name="settlement_time_at" type="string<date-time> | null">
  When this payment's funds post to the company's available balance, at midnight UTC. Known at payment time and never changes. The `ledger_account.funds_available` webhook carries the same `settlement_time_at` when that batch posts — match them to know these funds are now withdrawable.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="shipment" type="object | null">
  The shipment attached to this payment.

  <Expandable title="child attributes">
    <ResponseField name="carrier" type="string | null">
      The shipping carrier detected for this shipment. Null until a tracking update identifies it.

      Example: `usps`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the shipment.

      Example: `ship_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="status" type="ShipmentStatuses">
      The current delivery status of this shipment.

      Available options: `unknown`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `available_for_pickup`, `return_to_sender`, `failure`, `cancelled`, `error`
    </ResponseField>

    <ResponseField name="tracking_number" type="string">
      The carrier-assigned tracking number used to look up shipment progress.

      Example: `9400111899223456789012`
    </ResponseField>

    <ResponseField name="tracking_url" type="string">
      A customer-facing URL to track this shipment's progress.

      Example: `https://track.aftership.com/9400111899223456789012`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shipping_address" type="object | null">
  The shipping address provided by the customer for physical goods. Null if no shipping address was collected.

  <Expandable title="child attributes">
    <ResponseField name="city" type="string | null">
      The city of the address.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      The country of the address.
    </ResponseField>

    <ResponseField name="line1" type="string | null">
      The line 1 of the address.
    </ResponseField>

    <ResponseField name="line2" type="string | null">
      The line 2 of the address.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The name of the customer.
    </ResponseField>

    <ResponseField name="postal_code" type="string | null">
      The postal code of the address.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      The state of the address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="ReceiptStatus | null">
  The current lifecycle state of this payment (e.g., 'draft', 'open', 'paid', 'void').

  Available options: `draft`, `open`, `paid`, `pending`, `uncollectible`, `unresolved`, `void`
</ResponseField>

<ResponseField name="substatus" type="FriendlyReceiptStatus">
  The friendly status of the payment.

  Available options: `succeeded`, `pending`, `failed`, `past_due`, `canceled`, `price_too_low`, `uncollectible`, `refunded`, `auto_refunded`, `partially_refunded`, `dispute_warning`, `dispute_needs_response`, `dispute_warning_needs_response`, `resolution_needs_response`, `dispute_under_review`, `dispute_warning_under_review`, `resolution_under_review`, `dispute_won`, `dispute_warning_closed`, `resolution_won`, `dispute_lost`, `dispute_closed`, `resolution_lost`, `drafted`, `incomplete`, `unresolved`, `open_dispute`, `open_resolution`
</ResponseField>

<ResponseField name="subtotal" type="number | null">
  The subtotal to show to the creator (excluding buyer fees).

  Example: `6.9`
</ResponseField>

<ResponseField name="tax_amount" type="number | null">
  The calculated amount of the sales/VAT tax (if applicable).

  Example: `6.9`
</ResponseField>

<ResponseField name="tax_behavior" type="ReceiptTaxBehaviors | null">
  The type of tax inclusivity applied to the payment, for determining whether the tax is included in the final price, or paid on top.

  Available options: `exclusive`, `inclusive`, `unspecified`, `unable_to_collect`
</ResponseField>

<ResponseField name="tax_refunded_amount" type="number | null">
  The amount of tax that has been refunded (if applicable).

  Example: `6.9`
</ResponseField>

<ResponseField name="three_ds_verified" type="boolean">
  Whether 3D Secure authentication was completed for this payment.
</ResponseField>

<ResponseField name="total" type="number | null">
  The total to show to the creator (excluding buyer fees).

  Example: `6.9`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the payment was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="usd_total" type="number | null">
  The total in USD to show to the creator (excluding buyer fees).

  Example: `6.9`
</ResponseField>

<ResponseField name="user" type="object | null">
  The user that made this payment.

  <Expandable title="child attributes">
    <ResponseField name="email" type="string | null">
      The user's email address. Requires the member:email:read permission to access. Null if not authorized.

      Example: `john.doe@example.com`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="verification_checks" type="object | null">
  The issuer's address and card security code check results for this payment. Null when the processor returned none.

  <Expandable title="child attributes">
    <ResponseField name="address_line1" type="string | null">
      Whether the billing street address the customer entered matched the address
      the issuer has on file.
    </ResponseField>

    <ResponseField name="card_holder_name" type="string | null">
      Whether the cardholder name the customer entered matched the name the issuer
      has on file.
    </ResponseField>

    <ResponseField name="card_security_code" type="string | null">
      Whether the CVV / CVC the customer entered matched the card.
    </ResponseField>

    <ResponseField name="zip_code" type="string | null">
      Whether the billing postal code the customer entered matched the postal code the issuer has on file.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="voidable" type="boolean">
  True when the payment is tied to a membership in `past_due`, the payment
  status is `open`, and the processor allows voiding payments; otherwise false.
</ResponseField>


# Payment created
Source: https://docs.whop.com/api-reference/payments/payment-created

/openapi/api-v1-stable.json webhook payment.created
Sent when a payment is created

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`
 - `webhook_receive:payments`



# Payment failed
Source: https://docs.whop.com/api-reference/payments/payment-failed

/openapi/api-v1-stable.json webhook payment.failed
Sent when a payment is failed

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`
 - `webhook_receive:payments`



# Payment pending
Source: https://docs.whop.com/api-reference/payments/payment-pending

/openapi/api-v1-stable.json webhook payment.pending
Sent when a payment is pending

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`
 - `webhook_receive:payments`



# Payment succeeded
Source: https://docs.whop.com/api-reference/payments/payment-succeeded

/openapi/api-v1-stable.json webhook payment.succeeded
Sent when a payment is succeeded

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`
 - `webhook_receive:payments`



# Refund payment
Source: https://docs.whop.com/api-reference/payments/refund-payment

/openapi/api-v1-stable.json post /payments/{id}/refund
Issue a full or partial refund for a payment. The refund is processed through the original payment processor and the membership status is updated accordingly.

Required permissions:
 - `payment:manage`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`



# Retrieve payment
Source: https://docs.whop.com/api-reference/payments/retrieve-payment

/openapi/api-v1-stable.json get /payments/{id}
Retrieves the details of an existing payment.

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`



# Retry payment
Source: https://docs.whop.com/api-reference/payments/retry-payment

/openapi/api-v1-stable.json post /payments/{id}/retry
Retry a failed or pending payment. This re-attempts the charge using the original payment method and plan details.

Required permissions:
 - `payment:manage`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`



# Void payment
Source: https://docs.whop.com/api-reference/payments/void-payment

/openapi/api-v1-stable.json post /payments/{id}/void
Void a payment that has not yet been settled. Voiding cancels the payment before it is captured by the payment processor.

Required permissions:
 - `payment:manage`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `promo_code:basic:read`
 - `shipment:basic:read`
 - `payment:dispute:read`
 - `payment:resolution_center_case:read`



# Plans
Source: https://docs.whop.com/api-reference/plans/plan

The Plans API is documented in the Experimental API Reference.

The Plans API is served by the versioned `/api/v1` API, so it is not part of the stable surface documented here.

<Card title="Plans API Reference" icon="arrow-right" href="/api-reference/beta/plans/plan">
  Browse the Plans resource schema and endpoints in the Experimental API
  Reference.
</Card>


# Create product
Source: https://docs.whop.com/api-reference/products/create-product

/openapi/api-v1-stable.json post /products
Create a new product for a company. The product serves as the top-level container for plans and experiences.

Required permissions:
 - `access_pass:create`
 - `access_pass:basic:read`



# Delete product
Source: https://docs.whop.com/api-reference/products/delete-product

/openapi/api-v1-stable.json delete /products/{id}
Permanently delete a product and remove it from the company's catalog.

Required permissions:
 - `access_pass:delete`



# List products
Source: https://docs.whop.com/api-reference/products/list-products

/openapi/api-v1-stable.json get /products
Returns a paginated list of products belonging to a company, with optional filtering by type, visibility, and creation date.

Required permissions:
 - `access_pass:basic:read`



# Product
Source: https://docs.whop.com/api-reference/products/product

A product is a digital good or service sold on Whop. Products contain plans for pricing and experiences for content delivery.

<ResponseExample>
  ```json Example theme={null}
  {
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"route": "pickaxe",
  		"title": "Pickaxe"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"custom_cta": "get_access",
  	"custom_cta_url": "https://example.com/signup",
  	"custom_statement_descriptor": "PICKAXE",
  	"description": "Track your revenue, members, and growth in real time.",
  	"external_identifier": "ext_prod_12345",
  	"gallery_images": [
  		{
  			"content_type": "image/jpeg",
  			"id": "<string>",
  			"url": "https://media.whop.com/abc123/optimized.jpg"
  		}
  	],
  	"global_affiliate_percentage": 6.9,
  	"global_affiliate_status": "enabled",
  	"headline": "Real-time data analytics for creators",
  	"id": "prod_xxxxxxxxxxxxx",
  	"member_affiliate_percentage": 6.9,
  	"member_affiliate_status": "enabled",
  	"member_count": 42,
  	"metadata": {},
  	"owner_user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	},
  	"product_tax_code": {
  		"id": "ptc_xxxxxxxxxxxxxx",
  		"name": "Digital - SaaS",
  		"product_type": "physical"
  	},
  	"published_reviews_count": 42,
  	"route": "pickaxe-analytics",
  	"title": "Pickaxe Analytics",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"verified": true,
  	"visibility": "visible"
  }
  ```
</ResponseExample>

<ResponseField name="company" type="object">
  The company this product belongs to.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="route" type="string">
      URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.

      Example: `pickaxe`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the product was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="custom_cta" type="CustomCtas">
  Call-to-action button label shown on the product purchase page.

  Available options: `get_access`, `join`, `order_now`, `shop_now`, `call_now`, `donate_now`, `contact_us`, `sign_up`, `subscribe`, `purchase`, `get_offer`, `apply_now`, `complete_order`
</ResponseField>

<ResponseField name="custom_cta_url" type="string | null">
  An optional URL that the call-to-action button links to instead of the default checkout flow. Null if no custom URL is set.

  Example: `https://example.com/signup`
</ResponseField>

<ResponseField name="custom_statement_descriptor" type="string | null">
  Custom bank statement descriptor for product purchases. Maximum 22 characters, including required `WHOP*` prefix.

  Example: `PICKAXE`
</ResponseField>

<ResponseField name="description" type="string | null">
  A brief summary of what the product offers, displayed on product pages and search results.

  Example: `Track your revenue, members, and growth in real time.`
</ResponseField>

<ResponseField name="external_identifier" type="string | null">
  External identifier for the product. Providing it on a product creation endpoint updates the existing product with this identifier instead of creating a new one.

  Example: `ext_prod_12345`
</ResponseField>

<ResponseField name="gallery_images" type="array<object>">
  The gallery images for this product, ordered by position.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="global_affiliate_percentage" type="number | null">
  Marketplace affiliate commission percentage for this product, or `null` if program is inactive.

  Example: `6.9`
</ResponseField>

<ResponseField name="global_affiliate_status" type="GlobalAffiliateStatuses">
  The enrollment status of this product in the Whop marketplace global affiliate program.

  Available options: `enabled`, `disabled`
</ResponseField>

<ResponseField name="headline" type="string | null">
  A short marketing headline displayed prominently on the product's product page.

  Example: `Real-time data analytics for creators`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the product.

  Example: `prod_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="member_affiliate_percentage" type="number | null">
  Member referral commission percentage for this product, or `null` if program is inactive.

  Example: `6.9`
</ResponseField>

<ResponseField name="member_affiliate_status" type="GlobalAffiliateStatuses">
  The enrollment status of this product in the member affiliate program.

  Available options: `enabled`, `disabled`
</ResponseField>

<ResponseField name="member_count" type="integer">
  Active memberships for this product. Returns `0` if the account has disabled public member counts.

  Example: `42`
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Custom key-value pairs stored on the product and included in payment and
  membership webhook payloads. Max 50 keys, 100 characters per key, 500
  characters per string value.
</ResponseField>

<ResponseField name="owner_user" type="object">
  The user who owns the company that sells this product.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="product_tax_code" type="object | null">
  The tax classification code applied to purchases of this product for sales tax calculation. Null if no tax code is assigned.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product tax code.

      Example: `ptc_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable name of this tax classification, such as 'Digital - SaaS'.

      Example: `Digital - SaaS`
    </ResponseField>

    <ResponseField name="product_type" type="ProductTaxCodeProductTypes">
      Broad product category this tax code covers, such as physical goods or digital services.

      Available options: `physical`, `digital`, `services`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="published_reviews_count" type="integer">
  The total number of published customer reviews for this product's company.

  Example: `42`
</ResponseField>

<ResponseField name="route" type="string">
  URL slug in the product's public link, e.g. `pickaxe-analytics` in whop.com/company/pickaxe-analytics.

  Example: `pickaxe-analytics`
</ResponseField>

<ResponseField name="title" type="string">
  The display name of the product shown to customers on the product page and in search results.

  Example: `Pickaxe Analytics`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the product was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="verified" type="boolean">
  Whether this company has been verified by Whop's trust and safety team.
</ResponseField>

<ResponseField name="visibility" type="Visibility">
  Controls whether the product is visible to customers. When set to 'hidden', the product is only accessible via direct link.

  Available options: `visible`, `hidden`, `archived`, `quick_link`
</ResponseField>


# Product created
Source: https://docs.whop.com/api-reference/products/product-created

/openapi/api-v1-stable.json webhook product.created
Sent when a product is created

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Product deleted
Source: https://docs.whop.com/api-reference/products/product-deleted

/openapi/api-v1-stable.json webhook product.deleted
Sent when a product is deleted

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Product published
Source: https://docs.whop.com/api-reference/products/product-published

/openapi/api-v1-stable.json webhook product.published
Sent when a product is published

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Product unpublished
Source: https://docs.whop.com/api-reference/products/product-unpublished

/openapi/api-v1-stable.json webhook product.unpublished
Sent when a product is unpublished

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Product updated
Source: https://docs.whop.com/api-reference/products/product-updated

/openapi/api-v1-stable.json webhook product.updated
Sent when a product is updated

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Retrieve product
Source: https://docs.whop.com/api-reference/products/retrieve-product

/openapi/api-v1-stable.json get /products/{id}
Retrieves the details of an existing product.

Required permissions:
 - `access_pass:basic:read`



# Update product
Source: https://docs.whop.com/api-reference/products/update-product

/openapi/api-v1-stable.json patch /products/{id}
Update a product's title, description, visibility, and other settings.

Required permissions:
 - `access_pass:update`
 - `access_pass:basic:read`



# Create promo code
Source: https://docs.whop.com/api-reference/promo-codes/create-promo-code

/openapi/api-v1-stable.json post /promo_codes
Create a new promo code that applies a discount at checkout. Can be scoped to specific products or plans.

Required permissions:
 - `promo_code:create`
 - `access_pass:basic:read`



# Delete promo code
Source: https://docs.whop.com/api-reference/promo-codes/delete-promo-code

/openapi/api-v1-stable.json delete /promo_codes/{id}
Archive a promo code, preventing it from being used in future checkouts. Existing memberships are not affected.

Required permissions:
 - `promo_code:delete`



# List promo codes
Source: https://docs.whop.com/api-reference/promo-codes/list-promo-codes

/openapi/api-v1-stable.json get /promo_codes
Returns a paginated list of promo codes belonging to a company, with optional filtering by product, plan, and status.

Required permissions:
 - `promo_code:basic:read`
 - `access_pass:basic:read`



# Promo Code
Source: https://docs.whop.com/api-reference/promo-codes/promo-code

A promo code applies a discount to a plan during checkout. Promo codes can be percentage-based or fixed-amount, and can have usage limits and expiration dates.

<ResponseExample>
  ```json Example theme={null}
  {
  	"amount_off": 6.9,
  	"churned_users_only": true,
  	"code": "<string>",
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"title": "<string>"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"duration": "forever",
  	"existing_memberships_only": true,
  	"expires_at": "2023-12-01T05:00:00.401Z",
  	"id": "promo_xxxxxxxxxxxx",
  	"new_users_only": true,
  	"one_per_customer": true,
  	"product": {
  		"id": "prod_xxxxxxxxxxxxx",
  		"title": "Pickaxe Analytics"
  	},
  	"promo_duration_months": 42,
  	"promo_type": "percentage",
  	"status": "active",
  	"stock": 42,
  	"unlimited_stock": true,
  	"uses": 42
  }
  ```
</ResponseExample>

<ResponseField name="amount_off" type="number">
  The discount amount. Interpretation depends on promo\_type: if 'percentage', this is the percentage (e.g., 20 means 20% off); if 'flat\_amount', this is dollars off (e.g., 10.00 means \$10.00 off).

  Example: `6.9`
</ResponseField>

<ResponseField name="churned_users_only" type="boolean">
  Restricts promo use to only users who have churned from the company before.
</ResponseField>

<ResponseField name="code" type="string | null">
  The specific code used to apply the promo at checkout.
</ResponseField>

<ResponseField name="company" type="object">
  The company for the promo code.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The written name of the company.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the promo code was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies">
  The monetary currency of the promo code.

  Available options: `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`
</ResponseField>

<ResponseField name="duration" type="PromoDurations | null">
  The duration of the promo.

  Available options: `forever`, `once`, `repeating`
</ResponseField>

<ResponseField name="existing_memberships_only" type="boolean">
  Restricts promo use to only be applied to already purchased memberships.
</ResponseField>

<ResponseField name="expires_at" type="string<date-time> | null">
  The date/time of when the promo expires.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the promo code.

  Example: `promo_xxxxxxxxxxxx`
</ResponseField>

<ResponseField name="new_users_only" type="boolean">
  Restricts promo use to only users who have never purchased from the company
  before.
</ResponseField>

<ResponseField name="one_per_customer" type="boolean">
  Restricts promo use to only be applied once per customer.
</ResponseField>

<ResponseField name="product" type="object | null">
  The product this promo code applies to

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the product.

      Example: `prod_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the product shown to customers on the product page and in search results.

      Example: `Pickaxe Analytics`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="promo_duration_months" type="integer | null">
  The number of months the promo is applied for.

  Example: `42`
</ResponseField>

<ResponseField name="promo_type" type="PromoTypes">
  The type (% or flat amount) of the promo.

  Available options: `percentage`, `flat_amount`
</ResponseField>

<ResponseField name="status" type="PromoCodeStatus">
  Indicates if the promo code is live or disabled.

  Available options: `active`, `inactive`, `archived`
</ResponseField>

<ResponseField name="stock" type="integer">
  The quantity limit on the number of uses.

  Example: `42`
</ResponseField>

<ResponseField name="unlimited_stock" type="boolean">
  Whether or not the promo code has unlimited stock.
</ResponseField>

<ResponseField name="uses" type="integer">
  The amount of times the promo codes has been used.

  Example: `42`
</ResponseField>


# Retrieve promo code
Source: https://docs.whop.com/api-reference/promo-codes/retrieve-promo-code

/openapi/api-v1-stable.json get /promo_codes/{id}
Retrieves the details of an existing promo code.

Required permissions:
 - `promo_code:basic:read`
 - `access_pass:basic:read`



# Update promo code
Source: https://docs.whop.com/api-reference/promo-codes/update-promo-code

/openapi/api-v1-stable.json patch /promo_codes/{id}
Update whether a promo code can be used at checkout.

Required permissions:
 - `promo_code:update`
 - `access_pass:basic:read`



# Chat reaction created
Source: https://docs.whop.com/api-reference/reactions/chat-reaction-created

/openapi/api-v1-stable.json webhook chat.reaction.created
Sent when a chat event is created

Required permissions:
 - `webhook_receive:chat`



# Create reaction
Source: https://docs.whop.com/api-reference/reactions/create-reaction

/openapi/api-v1-stable.json post /reactions
Add an emoji reaction or poll vote to a message or forum post. In forums, the reaction is always a like.

Required permissions:
 - `chat:read`



# Delete reaction
Source: https://docs.whop.com/api-reference/reactions/delete-reaction

/openapi/api-v1-stable.json delete /reactions/{id}
Remove an emoji reaction from a message or forum post. Only the reaction author or a channel admin can remove a reaction.

Required permissions:
 - `chat:read`



# List reactions
Source: https://docs.whop.com/api-reference/reactions/list-reactions

/openapi/api-v1-stable.json get /reactions
Returns a paginated list of emoji reactions on a specific message or forum post, sorted by most recent.

Required permissions:
 - `chat:read`



# Reaction
Source: https://docs.whop.com/api-reference/reactions/reaction

A single reaction left by a user on a feed post, such as a like or emoji.

<ResponseExample>
  ```json Example theme={null}
  {
  	"emoji": ":heart:",
  	"id": "reac_xxxxxxxxxxxxxxxxxxxxxx",
  	"resource_id": "<string>",
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="emoji" type="string | null">
  The emoji used for this reaction in shortcode format. Null if the reaction type is not emoji.

  Example: `:heart:`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the entity

  Example: `reac_xxxxxxxxxxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="resource_id" type="string">
  The unique identifier of the post this reaction was left on.
</ResponseField>

<ResponseField name="user" type="object">
  The user who left this reaction on the post.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# Retrieve reaction
Source: https://docs.whop.com/api-reference/reactions/retrieve-reaction

/openapi/api-v1-stable.json get /reactions/{id}
Retrieves the details of an existing reaction.

Required permissions:
 - `chat:read`



# List refunds
Source: https://docs.whop.com/api-reference/refunds/list-refunds

/openapi/api-v1-stable.json get /refunds
Returns a paginated list of refunds, with optional filtering by payment, company, user, and creation date.

Required permissions:
 - `payment:basic:read`



# Refund
Source: https://docs.whop.com/api-reference/refunds/refund

A refund represents a full or partial reversal of a payment, including the amount, status, and payment provider.

<ResponseExample>
  ```json Example theme={null}
  {
  	"amount": 6.9,
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"id": "rf_xxxxxxxxxxxxxxx",
  	"payment": {
  		"billing_reason": "subscription_create",
  		"card_brand": "mastercard",
  		"card_last4": "4242",
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"currency": "usd",
  		"dispute_alerted_at": "2023-12-01T05:00:00.401Z",
  		"id": "pay_xxxxxxxxxxxxxx",
  		"member": {
  			"id": "<string>",
  			"phone": "<string>"
  		},
  		"membership": {
  			"id": "mem_xxxxxxxxxxxxxx",
  			"status": "trialing"
  		},
  		"metadata": {},
  		"paid_at": "2023-12-01T05:00:00.401Z",
  		"payment_method_type": "acss_debit",
  		"plan": {
  			"id": "plan_xxxxxxxxxxxxx",
  			"metadata": {}
  		},
  		"product": {
  			"id": "prod_xxxxxxxxxxxxx",
  			"metadata": {}
  		},
  		"subtotal": 6.9,
  		"tax_amount": 6.9,
  		"tax_behavior": "exclusive",
  		"tax_refunded_amount": 6.9,
  		"total": 6.9,
  		"usd_total": 6.9,
  		"user": {
  			"email": "john.doe@example.com",
  			"id": "user_xxxxxxxxxxxxx",
  			"name": "John Doe",
  			"username": "johndoe42"
  		}
  	},
  	"provider": "stripe",
  	"provider_created_at": "2023-12-01T05:00:00.401Z",
  	"reference_status": "available",
  	"reference_type": "acquirer_reference_number",
  	"reference_value": "74850120752",
  	"status": "pending"
  }
  ```
</ResponseExample>

<ResponseField name="amount" type="number">
  The refunded amount as a decimal in the specified currency, such as 10.43 for \$10.43 USD.

  Example: `6.9`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the refund was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies">
  The three-letter ISO currency code for the refunded amount.

  Available options: `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`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the refund.

  Example: `rf_xxxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="payment" type="object | null">
  The original payment that this refund was issued against. Null if the payment is no longer available.

  <Expandable title="child attributes">
    <ResponseField name="billing_reason" type="BillingReasons | null">
      The machine-readable reason this charge was created, such as initial subscription purchase, renewal cycle, or one-time payment.

      Available options: `subscription_create`, `subscription_cycle`, `subscription_update`, `one_time`, `manual`, `subscription`
    </ResponseField>

    <ResponseField name="card_brand" type="CardBrands | null">
      Card network reported by the processor (e.g., 'visa', 'mastercard', 'amex'). Present only when the payment method type is 'card'.

      Available options: `mastercard`, `visa`, `amex`, `discover`, `unionpay`, `jcb`, `diners`, `link`, `troy`, `visadankort`, `visabancontact`, `china_union_pay`, `rupay`, `jcbrupay`, `elo`, `maestro`, `tarjeta_naranja`, `cirrus`, `nspk_mir`, `verve`, `ebt`, `private_label`, `local_brand`, `uatp`, `wexcard`, `uzcard`, `meeza`, `hrg_store_card`, `girocard`, `fuel_card`, `dankort`, `carnet`, `atm_card`, `china_union_payuzcard`, `codensa`, `cabal`, `hipercard`, `jcblankapay`, `cmi`, `aura`, `unknown`
    </ResponseField>

    <ResponseField name="card_last4" type="string | null">
      The last four digits of the card used to make this payment. Null if the payment was not made with a card.

      Example: `4242`
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the payment was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').

      Available options: `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`
    </ResponseField>

    <ResponseField name="dispute_alerted_at" type="string<date-time> | null">
      When an alert came in that this transaction will be disputed

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payment.

      Example: `pay_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="member" type="object | null">
      The member attached to this payment.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the company member.
        </ResponseField>

        <ResponseField name="phone" type="string | null">
          The phone number for the member, if available.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="membership" type="object | null">
      The membership attached to this payment.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the membership.

          Example: `mem_xxxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="status" type="MembershipStatus">
          The state of the membership.

          Available options: `trialing`, `active`, `past_due`, `completed`, `canceled`, `expired`, `unresolved`, `drafted`, `canceling`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      The custom metadata stored on this payment. This will be copied over to the
      checkout configuration for which this payment was made
    </ResponseField>

    <ResponseField name="paid_at" type="string<date-time> | null">
      The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="payment_method_type" type="PaymentMethodTypes | null">
      The type of payment instrument used for this payment (e.g., card, Cash App, iDEAL, Klarna, crypto). Null when the processor does not supply a type.

      Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
    </ResponseField>

    <ResponseField name="plan" type="object | null">
      The plan attached to this payment.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the plan.

          Example: `plan_xxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="metadata" type="object | null">
          Custom key-value pairs stored on the plan. Included in webhook payloads for payment and membership events. Max 50 keys, 100 chars per key, 500 chars per string value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="product" type="object | null">
      The product this payment was made for

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the product.

          Example: `prod_xxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="metadata" type="object | null">
          Custom key-value pairs stored on the product and included in payment and membership webhook payloads. Max 50 keys, 100 characters per key, 500 characters per string value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="subtotal" type="number | null">
      The subtotal to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="tax_amount" type="number | null">
      The calculated amount of the sales/VAT tax (if applicable).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="tax_behavior" type="ReceiptTaxBehaviors | null">
      The type of tax inclusivity applied to the payment, for determining whether the tax is included in the final price, or paid on top.

      Available options: `exclusive`, `inclusive`, `unspecified`, `unable_to_collect`
    </ResponseField>

    <ResponseField name="tax_refunded_amount" type="number | null">
      The amount of tax that has been refunded (if applicable).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="total" type="number | null">
      The total to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="usd_total" type="number | null">
      The total in USD to show to the creator (excluding buyer fees).

      Example: `6.9`
    </ResponseField>

    <ResponseField name="user" type="object | null">
      The user that made this payment.

      <Expandable title="child attributes">
        <ResponseField name="email" type="string | null">
          The user's email address. Requires the member:email:read permission to access. Null if not authorized.

          Example: `john.doe@example.com`
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique identifier for the user.

          Example: `user_xxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The user's display name shown on their public profile.

          Example: `John Doe`
        </ResponseField>

        <ResponseField name="username" type="string">
          The user's unique username shown on their public profile.

          Example: `johndoe42`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="provider" type="PaymentProviders">
  The payment provider that processed the refund.

  Available options: `stripe`, `coinbase`, `paypal`, `apple`, `sezzle`, `splitit`, `platform_balance`, `multi_psp`, `adyen`, `claritypay`, `checkout_dot_com`, `airwallex`, `coinflow`, `sequra`, `dlocal`, `masspay`, `braintree`
</ResponseField>

<ResponseField name="provider_created_at" type="string<date-time> | null">
  The timestamp when the refund was created in the payment provider's system. Null if not available from the provider.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="reference_status" type="RefundReferenceStatuses | null">
  The availability status of the refund tracking reference from the payment processor. Null if no reference was provided.

  Available options: `available`, `pending`, `unavailable`
</ResponseField>

<ResponseField name="reference_type" type="RefundReferenceTypes | null">
  The type of tracking reference provided by the payment processor, such as an acquirer reference number. Null if no reference was provided.

  Available options: `acquirer_reference_number`, `retrieval_reference_number`, `system_trace_audit_number`
</ResponseField>

<ResponseField name="reference_value" type="string | null">
  The tracking reference value from the payment processor, used to trace the refund through banking networks. Null if no reference was provided.

  Example: `74850120752`
</ResponseField>

<ResponseField name="status" type="RefundStatuses">
  The current processing status of the refund, such as pending, succeeded, or failed.

  Available options: `pending`, `requires_action`, `succeeded`, `failed`, `canceled`
</ResponseField>


# Refund created
Source: https://docs.whop.com/api-reference/refunds/refund-created

/openapi/api-v1-stable.json webhook refund.created
Sent when a refund is created

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `webhook_receive:refunds`



# Refund updated
Source: https://docs.whop.com/api-reference/refunds/refund-updated

/openapi/api-v1-stable.json webhook refund.updated
Sent when a refund is updated

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `webhook_receive:refunds`



# Retrieve refund
Source: https://docs.whop.com/api-reference/refunds/retrieve-refund

/openapi/api-v1-stable.json get /refunds/{id}
Retrieves the details of an existing refund.

Required permissions:
 - `payment:basic:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`



# List resolution center cases
Source: https://docs.whop.com/api-reference/resolution-center-cases/list-resolution-center-cases

/openapi/api-v1-stable.json get /resolution_center_cases
Returns a paginated list of resolution center cases, with optional filtering by company, status, and creation date.

Required permissions:
 - `payment:resolution_center_case:read`



# Resolution Center Case
Source: https://docs.whop.com/api-reference/resolution-center-cases/resolution-center-case

A resolution center case is a dispute or support case between a user and a company, tracking the issue, status, and outcome.

<ResponseExample>
  ```json Example theme={null}
  {
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx",
  		"title": "Pickaxe"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"customer_appealed": true,
  	"customer_response_actions": ["respond"],
  	"due_date": "2023-12-01T05:00:00.401Z",
  	"id": "reso_xxxxxxxxxxxxx",
  	"issue": "forgot_to_cancel",
  	"member": {
  		"id": "<string>"
  	},
  	"merchant_appealed": true,
  	"merchant_response_actions": ["accept"],
  	"payment": {
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"currency": "usd",
  		"id": "pay_xxxxxxxxxxxxxx",
  		"paid_at": "2023-12-01T05:00:00.401Z",
  		"subtotal": 6.9,
  		"total": 6.9
  	},
  	"platform_response_actions": ["request_buyer_info"],
  	"resolution_events": [
  		{
  			"action": "created",
  			"created_at": "2023-12-01T05:00:00.401Z",
  			"details": "I did not authorize this purchase.",
  			"id": "revt_xxxxxxxxxxxxx",
  			"reporter_type": "merchant"
  		}
  	],
  	"status": "merchant_response_needed",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="company" type="object | null">
  The company involved in this resolution case. Null if the company no longer exists.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the resolution was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="customer_appealed" type="boolean">
  Whether the customer has filed an appeal after the initial resolution
  decision.
</ResponseField>

<ResponseField name="customer_response_actions" type="array<ResolutionCenterCaseCustomerResponses>">
  The list of actions currently available to the customer.

  Available options: `respond`, `appeal`, `withdraw`
</ResponseField>

<ResponseField name="due_date" type="string<date-time> | null">
  The deadline by which the next response is required. Null if no deadline is currently active. As a Unix timestamp.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the resolution.

  Example: `reso_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="issue" type="ResolutionCenterCaseIssueTypes">
  The category of the dispute.

  Available options: `forgot_to_cancel`, `item_not_received`, `significantly_not_as_described`, `unauthorized_transaction`, `product_unacceptable`
</ResponseField>

<ResponseField name="member" type="object | null">
  The membership record associated with the disputed payment. Null if the membership no longer exists.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the extra public member.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="merchant_appealed" type="boolean">
  Whether the merchant has filed an appeal after the initial resolution
  decision.
</ResponseField>

<ResponseField name="merchant_response_actions" type="array<ResolutionCenterCaseMerchantResponses>">
  The list of actions currently available to the merchant.

  Available options: `accept`, `deny`, `request_more_info`, `appeal`, `respond`
</ResponseField>

<ResponseField name="payment" type="object">
  The payment record that is the subject of this resolution case.

  <Expandable title="child attributes">
    <ResponseField name="created_at" type="string<date-time>">
      The datetime the payment was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="currency" type="Currencies | null">
      The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').

      Available options: `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`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payment.

      Example: `pay_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="paid_at" type="string<date-time> | null">
      The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="subtotal" type="number | null">
      The payment amount before taxes and discounts are applied. In the currency specified by the currency field.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="total" type="number">
      The total amount charged to the customer for this payment, including taxes and after any discounts. In the currency specified by the currency field.

      Example: `6.9`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="platform_response_actions" type="array<ResolutionCenterCasePlatformResponses>">
  The list of actions currently available to the Whop platform for moderating this resolution.

  Available options: `request_buyer_info`, `request_merchant_info`, `merchant_wins`, `merchant_refund`
</ResponseField>

<ResponseField name="resolution_events" type="array<object>">
  The most recent 50 messages, actions, and status changes that have occurred during this resolution case.

  <Expandable title="child attributes">
    <ResponseField name="action" type="ResolutionCenterCaseActions">
      The type of action recorded in this event.

      Available options: `created`, `responded`, `accepted`, `denied`, `appealed`, `withdrew`, `requested_more_info`, `escalated`, `dispute_opened`, `dispute_customer_won`, `dispute_merchant_won`
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the resolution event was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="details" type="string | null">
      The message body or additional context provided with this resolution event. Null if no details were included.

      Example: `I did not authorize this purchase.`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the resolution event.

      Example: `revt_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="reporter_type" type="ResolutionCenterCaseReporters">
      The party who performed this action.

      Available options: `merchant`, `customer`, `platform`, `system`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="ResolutionCenterCaseStatuses">
  The current status of the resolution case, indicating which party needs to respond or if the case is closed.

  Available options: `merchant_response_needed`, `customer_response_needed`, `merchant_info_needed`, `customer_info_needed`, `under_platform_review`, `customer_won`, `merchant_won`, `customer_withdrew`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the resolution was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="user" type="object">
  The customer (buyer) who filed this resolution case.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# Resolutioncentercase created
Source: https://docs.whop.com/api-reference/resolution-center-cases/resolutioncentercase-created

/openapi/api-v1-stable.json webhook resolution_center_case.created
Sent when a resolution center case is created

Required permissions:
 - `payment:resolution_center_case:read`
 - `webhook_receive:resolutions`



# Resolutioncentercase decided
Source: https://docs.whop.com/api-reference/resolution-center-cases/resolutioncentercase-decided

/openapi/api-v1-stable.json webhook resolution_center_case.decided
Sent when a resolution center case is decided

Required permissions:
 - `payment:resolution_center_case:read`
 - `webhook_receive:resolutions`



# Resolutioncentercase updated
Source: https://docs.whop.com/api-reference/resolution-center-cases/resolutioncentercase-updated

/openapi/api-v1-stable.json webhook resolution_center_case.updated
Sent when a resolution center case is updated

Required permissions:
 - `payment:resolution_center_case:read`
 - `webhook_receive:resolutions`



# Retrieve resolution center case
Source: https://docs.whop.com/api-reference/resolution-center-cases/retrieve-resolution-center-case

/openapi/api-v1-stable.json get /resolution_center_cases/{id}
Retrieves the details of an existing resolution center case.

Required permissions:
 - `payment:resolution_center_case:read`



# Create setup intent
Source: https://docs.whop.com/api-reference/setup-intents/create-setup-intent

/openapi/api-v1-stable.json post /setup_intents
Save a buyer's payment method for later without charging it. Provide a confirmation token for a method the buyer just supplied, or an existing payment method to re-verify. The buyer may still have a step to complete — 3D Secure, a hosted enrollment, linking a bank account — so poll the setup intent's status endpoint for what to do next.

Required permissions:
 - `payment:charge`
 - `member:basic:read`
 - `member:email:read`



# List setup intents
Source: https://docs.whop.com/api-reference/setup-intents/list-setup-intents

/openapi/api-v1-stable.json get /setup_intents
Returns a paginated list of setup intents for a company, with optional filtering by creation date. A setup intent securely collects and stores a member's payment method for future use without charging them immediately.

Required permissions:
 - `payment:setup_intent:read`
 - `member:basic:read`
 - `member:email:read`



# Setup Intent
Source: https://docs.whop.com/api-reference/setup-intents/setup-intent

A setup intent allows a user to save a payment method for future use without making an immediate purchase.

<Note>
  **There is no `createSetupIntent` endpoint.** Setup intents are created indirectly by creating a [Checkout Configuration](/api-reference/checkout-configurations/create-checkout-configuration) with `mode: "setup"`. The buyer completes that checkout, and Whop creates the setup intent behind the scenes. Listen for the `setup_intent.succeeded` webhook to receive the payment method ID once it's saved.

  See [Save payment methods](/developer/guides/save-payment-methods) for the full flow.
</Note>

```typescript theme={null}
// Create a setup intent by opening a checkout in setup mode
const checkoutConfiguration = await client.checkoutConfigurations.create({
	company_id: "biz_xxxxxxxxxxxxx",
	mode: "setup",
	redirect_url: "https://yoursite.com/return",
	metadata: { customer_id: "your_internal_id" },
});

// Redirect the buyer to checkoutConfiguration.purchase_url
// or use <WhopCheckoutEmbed sessionId={checkoutConfiguration.id} />.
// Then listen for setup_intent.succeeded on your webhook handler.
```

<ResponseExample>
  ```json Example theme={null}
  {
  	"checkout_configuration": {
  		"id": "ch_xxxxxxxxxxxxxxx"
  	},
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"error_message": "Your card was declined.",
  	"id": "sint_xxxxxxxxxxxxx",
  	"member": {
  		"id": "<string>",
  		"user": {
  			"email": "<string>",
  			"id": "<string>",
  			"name": "<string>",
  			"username": "<string>"
  		}
  	},
  	"metadata": {},
  	"payment_method": {
  		"card": {
  			"brand": "mastercard",
  			"exp_month": 42,
  			"exp_year": 42,
  			"last4": "4242"
  		},
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"id": "payt_xxxxxxxxxxxxx",
  		"mailing_address": {
  			"city": "<string>",
  			"country": "<string>",
  			"line1": "<string>",
  			"line2": "<string>",
  			"name": "<string>",
  			"postal_code": "<string>",
  			"state": "<string>"
  		},
  		"payment_method_type": "acss_debit"
  	},
  	"status": "processing",
  	"three_ds_verified": true
  }
  ```
</ResponseExample>

<ResponseField name="checkout_configuration" type="object | null">
  The checkout session configuration associated with this setup intent. Null if no checkout session was used.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the checkout session.

      Example: `ch_xxxxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="company" type="object | null">
  The company that initiated this setup intent. Null if the company has been deleted.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the setup intent was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="error_message" type="string | null">
  A human-readable error message explaining why the setup intent failed. Null if no error occurred.

  Example: `Your card was declined.`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the setup intent.

  Example: `sint_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="member" type="object | null">
  The company member associated with this setup intent. Null if the user is not a member.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company member.
    </ResponseField>

    <ResponseField name="user" type="object | null">
      The user for this member, if any.

      <Expandable title="child attributes">
        <ResponseField name="email" type="string | null">
          The digital mailing address of the user.
        </ResponseField>

        <ResponseField name="id" type="string">
          The unique identifier for the company member user.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The user's full name.
        </ResponseField>

        <ResponseField name="username" type="string">
          The whop username.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Custom key-value pairs attached to this setup intent. Null if no metadata was
  provided.
</ResponseField>

<ResponseField name="payment_method" type="object | null">
  The saved payment method created by this setup intent. Null if the setup has not completed successfully.

  <Expandable title="child attributes">
    <ResponseField name="card" type="object | null">
      The card data associated with the payment method, if its a debit or credit card.

      <Expandable title="child attributes">
        <ResponseField name="brand" type="CardBrands | null">
          The card network (e.g., visa, mastercard, amex). Null if the brand could not be determined.

          Available options: `mastercard`, `visa`, `amex`, `discover`, `unionpay`, `jcb`, `diners`, `link`, `troy`, `visadankort`, `visabancontact`, `china_union_pay`, `rupay`, `jcbrupay`, `elo`, `maestro`, `tarjeta_naranja`, `cirrus`, `nspk_mir`, `verve`, `ebt`, `private_label`, `local_brand`, `uatp`, `wexcard`, `uzcard`, `meeza`, `hrg_store_card`, `girocard`, `fuel_card`, `dankort`, `carnet`, `atm_card`, `china_union_payuzcard`, `codensa`, `cabal`, `hipercard`, `jcblankapay`, `cmi`, `aura`, `unknown`
        </ResponseField>

        <ResponseField name="exp_month" type="integer | null">
          The two-digit expiration month of the card (1-12). Null if not available.

          Example: `42`
        </ResponseField>

        <ResponseField name="exp_year" type="integer | null">
          The two-digit expiration year of the card (e.g., 27 for 2027). Null if not available.

          Example: `42`
        </ResponseField>

        <ResponseField name="last4" type="string | null">
          The last four digits of the card number. Null if not available.

          Example: `4242`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the payment token was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payment token.

      Example: `payt_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="mailing_address" type="object | null">
      The mailing address associated with the payment method's user

      <Expandable title="child attributes">
        <ResponseField name="city" type="string | null">
          The city of the address.
        </ResponseField>

        <ResponseField name="country" type="string | null">
          The country of the address.
        </ResponseField>

        <ResponseField name="line1" type="string | null">
          The line 1 of the address.
        </ResponseField>

        <ResponseField name="line2" type="string | null">
          The line 2 of the address.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The name of the customer.
        </ResponseField>

        <ResponseField name="postal_code" type="string | null">
          The postal code of the address.
        </ResponseField>

        <ResponseField name="state" type="string | null">
          The state of the address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payment_method_type" type="PaymentMethodTypes">
      The payment method type of the payment method

      Available options: `acss_debit`, `affirm`, `afterpay_clearpay`, `alipay`, `alma`, `amazon_pay`, `apple`, `apple_pay`, `au_bank_transfer`, `au_becs_debit`, `bacs_debit`, `bancolombia`, `bancontact`, `bank_wire`, `billie`, `bizum`, `blik`, `boleto`, `bre_b`, `ca_bank_transfer`, `capchase_pay`, `card`, `card_installments_three`, `card_installments_six`, `card_installments_twelve`, `cashapp`, `claritypay`, `coinbase`, `crypto`, `custom`, `customer_balance`, `demo_pay`, `efecty`, `eps`, `eu_bank_transfer`, `fpx`, `gb_bank_transfer`, `giropay`, `google_pay`, `gopay`, `grabpay`, `id_bank_transfer`, `ideal`, `interac`, `kakao_pay`, `klarna`, `klarna_pay_now`, `konbini`, `kr_card`, `kr_market`, `kriya`, `kueski`, `link`, `mb_way`, `m_pesa`, `mercado_pago`, `mobilepay`, `mondu`, `multibanco`, `naver_pay`, `nequi`, `netbanking`, `ng_bank`, `ng_bank_transfer`, `ng_card`, `ng_market`, `ng_ussd`, `ng_wallet`, `nz_bank_account`, `oxxo`, `p24`, `pago_efectivo`, `pse`, `pay_by_bank`, `payco`, `paynow`, `paypal`, `paypay`, `payto`, `pix`, `platform_balance`, `promptpay`, `qris`, `rechnung`, `revolut_pay`, `samsung_pay`, `satispay`, `scalapay`, `sencillito`, `sepa_debit`, `sequra`, `servipag`, `sezzle`, `shop_pay`, `shopeepay`, `sofort`, `south_korea_market`, `spei`, `splitit`, `sunbit`, `swish`, `tamara`, `twint`, `upi`, `us_bank_account`, `us_bank_transfer`, `venmo`, `vipps`, `webpay`, `wechat_pay`, `yape`, `zip`, `coinflow`, `unknown`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="SetupIntentStatuses">
  The current status of the setup intent.

  Available options: `processing`, `succeeded`, `canceled`, `requires_action`
</ResponseField>

<ResponseField name="three_ds_verified" type="boolean">
  Whether 3D Secure authentication was completed when this payment method was
  set up.
</ResponseField>


# Create support channel
Source: https://docs.whop.com/api-reference/support-channels/create-support-channel

/openapi/api-v1-stable.json post /support_channels
Open a new support channel between a company team member and a customer. Returns the existing channel if one already exists for that user.

Required permissions:
 - `support_chat:create`



# List support channels
Source: https://docs.whop.com/api-reference/support-channels/list-support-channels

/openapi/api-v1-stable.json get /support_channels
Returns a paginated list of support channels for a specific company, with optional filtering by resolution status and custom sorting.

Required permissions:
 - `support_chat:read`



# Retrieve support channel
Source: https://docs.whop.com/api-reference/support-channels/retrieve-support-channel

/openapi/api-v1-stable.json get /support_channels/{id}
Retrieves the details of an existing support channel.

Required permissions:
 - `support_chat:read`



# Support Channel
Source: https://docs.whop.com/api-reference/support-channels/support-channel

A messaging channel that can be a one-on-one DM, group chat, company support conversation, or platform-level direct message.

<ResponseExample>
  ```json Example theme={null}
  {
  	"company_id": "<string>",
  	"custom_name": "Project Alpha Team",
  	"customer_user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	},
  	"id": "<string>",
  	"last_message_at": "2023-12-01T05:00:00.401Z",
  	"resolved_at": "2023-12-01T05:00:00.401Z"
  }
  ```
</ResponseExample>

<ResponseField name="company_id" type="string | null">
  The unique identifier of the company associated with this channel. Null if
  this is not a support or company-scoped conversation.
</ResponseField>

<ResponseField name="custom_name" type="string | null">
  A custom display name assigned to this channel by the user. Null if no custom name has been set.

  Example: `Project Alpha Team`
</ResponseField>

<ResponseField name="customer_user" type="object | null">
  The customer who initiated this support conversation. Null if this is not a support chat.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the entity
</ResponseField>

<ResponseField name="last_message_at" type="string<date-time> | null">
  The timestamp when the most recent message was sent in this channel. Null if no messages have been sent.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="resolved_at" type="string<date-time> | null">
  The timestamp when the linked support ticket was marked as resolved. Null if unresolved or not a support chat.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>


# Account
Source: https://docs.whop.com/api-reference/beta/accounts/account



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.

Accounts are classified by the `business_type`, `industry_group`, and `industry_type` fields. See the [business types and industries glossary](#business-types-and-industries-glossary) for every valid value.

## Endpoints

| Endpoint                                                                                  | Request                                                         |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [List Accounts](/api-reference/beta/accounts/list-accounts)                               | <Badge>GET</Badge> `/accounts`                                  |
| [Create Account](/api-reference/beta/accounts/create-account)                             | <Badge>POST</Badge> `/accounts`                                 |
| [Retrieve Account](/api-reference/beta/accounts/retrieve-account)                         | <Badge>GET</Badge> `/accounts/{account_id}`                     |
| [Update Account](/api-reference/beta/accounts/update-account)                             | <Badge>PATCH</Badge> `/accounts/{account_id}`                   |
| [Form Company](/api-reference/beta/accounts/form-company)                                 | <Badge>POST</Badge> `/accounts/{account_id}/form_company`       |
| [Retrieve Account Preferences](/api-reference/beta/accounts/retrieve-account-preferences) | <Badge>GET</Badge> `/accounts/{account_id}/preferences`         |
| [Update Account Preferences](/api-reference/beta/accounts/update-account-preferences)     | <Badge>PATCH</Badge> `/accounts/{account_id}/preferences`       |
| [List Account Reserves](/api-reference/beta/accounts/list-account-reserves)               | <Badge>GET</Badge> `/accounts/{account_id}/reserves`            |
| [Transfer Account Ownership](/api-reference/beta/accounts/transfer-account-ownership)     | <Badge>POST</Badge> `/accounts/{account_id}/transfer_ownership` |
| [Retrieve Requesting Account](/api-reference/beta/accounts/retrieve-requesting-account)   | <Badge>GET</Badge> `/accounts/me`                               |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Account ID, prefixed `biz_`.
    </ResponseField>

    <ResponseField name="balances" type="object[]">
      Account holdings, each with USD value. Empty when `total_usd` is `null`.

      <Accordion title="Properties">
        <ResponseField name="balance" type="string">
          Total amount held in native units, as a decimal string.
        </ResponseField>

        <ResponseField name="breakdown" type="object">
          Balance split into available, pending, and reserve amounts, as native-unit decimal strings, with the days the pending amount is expected to settle. On-chain crypto is entirely available; good\_funds and fiat cash can have pending or reserve portions.

          <Accordion title="Properties">
            <ResponseField name="available" type="string">
              Amount you can spend, send, or withdraw now, in native units, as a decimal
              string.
            </ResponseField>

            <ResponseField name="pending" type="string">
              Amount from recent payments still settling, in native units, as a decimal
              string.
            </ResponseField>

            <ResponseField name="pending_settlements" type="object[]">
              When the pending amount is expected to settle, one entry per day, earliest first. Money with no scheduled settlement day, such as a transfer in flight, is left out — so these can sum to less than `pending`, never more.

              <Accordion title="Properties">
                <ResponseField name="amount" type="string">
                  Amount expected that day, in native units, as a decimal string.
                </ResponseField>

                <ResponseField name="date" type="string">
                  The day this money is expected to finish settling, as an ISO 8601 date.
                </ResponseField>
              </Accordion>
            </ResponseField>

            <ResponseField name="reserve" type="string">
              Amount held back, in native units, as a decimal string. Retrieve the account's reserves for why it is held and when it unlocks.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="icon_url" type="string | null">
          Holding icon URL.
        </ResponseField>

        <ResponseField name="name" type="string">
          The holding's display name
        </ResponseField>

        <ResponseField name="price_usd" type="number | null">
          USD price per unit, or `null` when no exchange rate is available.
        </ResponseField>

        <ResponseField name="symbol" type="string">
          Holding display symbol, such as `USDT`, `cbBTC`, or `EUR`.
        </ResponseField>

        <ResponseField name="value_usd" type="string | null">
          Holding USD value, or `null` when no exchange rate is available.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="banner_image_url" type="string | null">
      Account banner image URL.
    </ResponseField>

    <ResponseField name="business_address" type="object | null">
      Account business address used to calculate tax, with `line1`, `line2`, `city`,
      `state`, `postal_code`, and `country`. `null` when no address is set.
    </ResponseField>

    <ResponseField name="business_type" type="string | null">
      High-level business category for the account. See the [business types and
      industries
      glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary)
      for valid values.
    </ResponseField>

    <ResponseField name="can_transfer_pending_balance_to_children" type="boolean">
      Whether pending funds may be transferred from this platform account to its
      connected accounts.
    </ResponseField>

    <ResponseField name="capabilities" type="object | null">
      Payment rails enabled for this account, each `active`, `inactive`, or `pending` (onboarding or review in progress). Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise.

      <Accordion title="Properties">
        <ResponseField name="accept_bank_payments" type="string">
          Bank payins: debits, transfers, and local bank rails

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="accept_bnpl_payments" type="string">
          Buy-now-pay-later payins; requires approval

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="accept_card_payments" type="string">
          Card payins, including Apple Pay and Google Pay

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="bank_deposit" type="string">
          Deposits by bank wire or ACH to the account's virtual bank account

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="card_deposit" type="string">
          Balance top-ups by charging a stored payment method

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="card_issuing" type="string">
          Issuing Whop cards; requires card application approval

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="crypto_deposit" type="string">
          On-chain deposits to the account's crypto wallet

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="crypto_payout" type="string">
          On-chain payouts to a crypto wallet

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="instant_payout" type="string">
          Instant payouts to an eligible payout destination

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="run_ads" type="string">
          Launching ad campaigns through Whop Ads. `inactive` while a requested ads services agreement is awaiting the account's signature.

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="standard_payout" type="string">
          Standard payouts to an external payout destination

          Available options: `active`, `inactive`, `pending`
        </ResponseField>

        <ResponseField name="transfer" type="string">
          Transfers to other accounts

          Available options: `active`, `inactive`, `pending`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="cards" type="object | null">
      Whop Cards application details for the account. Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise, or when the account has no card application.

      <Accordion title="Properties">
        <ResponseField name="kind" type="string | null">
          Whether the card application verifies a business (`business`, KYB) or a person (`individual`, consumer identity). `null` when the application is not yet linked to a verification.

          Available options: `individual`, `business`
        </ResponseField>

        <ResponseField name="status" type="string">
          Where the card application stands. `approved` means cards can be issued. `needs_verification` means the applicant has not completed identity verification yet; `needs_information` means they did, but the documents were rejected for a fixable reason and must be resubmitted. `pending` and `manual_review` are in flight. `denied`, `locked`, and `canceled` are terminal.

          Available options: `approved`, `pending`, `manual_review`, `denied`, `locked`, `canceled`, `needs_verification`, `needs_information`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="collect_vat_id" type="boolean">
      Whether checkout shows a VAT/tax ID field for buyers to optionally enter. Does
      not require a VAT ID to purchase.
    </ResponseField>

    <ResponseField name="company_formation" type="object">
      Company formation state for the account, managed through [Form Company](/api-reference/beta/accounts/form-company). A `draft` `status` until the formation checkout is paid, then filing progress with downloadable documents and signatures awaiting action. Empty when the formation state is temporarily unavailable.

      <Accordion title="Properties">
        <ResponseField name="documents" type="object[]">
          Formation documents available for download, such as the Articles of Organization and the EIN confirmation letter. Present once `status` leaves `draft`.

          <Accordion title="Properties">
            <ResponseField name="id" type="string">
              Document ID, prefixed `file_`.
            </ResponseField>

            <ResponseField name="name" type="string">
              Human-readable document name, such as `Articles of Organization`.
            </ResponseField>

            <ResponseField name="type" type="string">
              Document category: `articles_of_organization`, `operating_agreement`,
              `ein_letter`, `signed_ss4`, `signed_form8821`, or `mail` for postal
              correspondence received on the company's behalf.
            </ResponseField>

            <ResponseField name="url" type="string">
              CDN URL for downloading the document.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="ein_registered" type="boolean">
          Whether the company's EIN has been issued by the IRS. Present once `status`
          leaves `draft`.
        </ResponseField>

        <ResponseField name="legal_name" type="string | null">
          Registered company name including the entity ending, for example `Acme, LLC`.
          Present once `status` leaves `draft`.
        </ResponseField>

        <ResponseField name="signatures" type="object">
          IRS forms still awaiting a founder's signature, each with a hosted signing URL. Present once `status` leaves `draft`; empty when nothing needs signing.

          <Accordion title="Properties">
            <ResponseField name="form8821" type="object">
              Signature state for IRS Form 8821, the tax information authorization. Present only while the form still needs the founder's action.

              <Accordion title="Properties">
                <ResponseField name="expires_at" type="string">
                  When the signing URL expires, as an ISO 8601 timestamp. Present while `status`
                  is `pending`.
                </ResponseField>

                <ResponseField name="status" type="string">
                  `pending` when a signing session is ready for the founder; `unknown` when the signature state could not be determined.

                  Available options: `pending`, `unknown`
                </ResponseField>

                <ResponseField name="url" type="string">
                  Hosted signing URL where the founder completes the form. Present while `status` is `pending`.
                </ResponseField>
              </Accordion>
            </ResponseField>

            <ResponseField name="ss4" type="object">
              Signature state for IRS Form SS-4, the EIN application. Present only while the form still needs the founder's action.

              <Accordion title="Properties">
                <ResponseField name="expires_at" type="string">
                  When the signing URL expires, as an ISO 8601 timestamp. Present while `status`
                  is `pending`.
                </ResponseField>

                <ResponseField name="status" type="string">
                  `pending` when a signing session is ready for the founder; `unknown` when the signature state could not be determined.

                  Available options: `pending`, `unknown`
                </ResponseField>

                <ResponseField name="url" type="string">
                  Hosted signing URL where the founder completes the form. Present while `status` is `pending`.
                </ResponseField>
              </Accordion>
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="state_registered" type="boolean">
          Whether the state formation filing is complete. Present once `status` leaves
          `draft`.
        </ResponseField>

        <ResponseField name="status" type="string">
          Available options: `draft`, `processing`, `filed`, `rejected`, `completed`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="country" type="string | null">
      Country where the account is located.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the account was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Account promotional description.
    </ResponseField>

    <ResponseField name="email" type="string | null">
      Account owner email address.
    </ResponseField>

    <ResponseField name="home_preferences" type="string[]">
      Public account home page preferences.

      Available options: `hide_member_count`, `hide_members_card`
    </ResponseField>

    <ResponseField name="industry_group" type="string | null">
      Account industry group. See the [business types and industries
      glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary)
      for valid values.
    </ResponseField>

    <ResponseField name="industry_type" type="string | null">
      Specific industry vertical for the account. See the [business types and
      industries
      glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary)
      for valid values.
    </ResponseField>

    <ResponseField name="invoice_prefix" type="string | null">
      Prefix used for account invoices.
    </ResponseField>

    <ResponseField name="logo_url" type="string | null">
      Account logo image URL.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Arbitrary key/value metadata supplied at account creation.
    </ResponseField>

    <ResponseField name="onboarding_type" type="string | null">
      Type of onboarding the account has completed.

      Available options: `platform`, `seller`
    </ResponseField>

    <ResponseField name="opengraph_image_url" type="string | null">
      Account Open Graph image URL.
    </ResponseField>

    <ResponseField name="opengraph_image_variant" type="string | null">
      Account Open Graph image variant.

      Available options: `white`, `black`, `orange`
    </ResponseField>

    <ResponseField name="other_business_description" type="string | null">
      Business type details when business\_type is `other`.
    </ResponseField>

    <ResponseField name="other_industry_description" type="string | null">
      Industry details when industry\_type is `other`.
    </ResponseField>

    <ResponseField name="owner" type="object">
      The single user who owns the account, whose email is the `email` above. Distinct from the `owner` role on team members, which any number of them can hold.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          User ID, prefixed `user_`.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          Display name.
        </ResponseField>

        <ResponseField name="profile_picture" type="object">
          Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture.

          <Accordion title="Properties">
            <ResponseField name="url" type="string">
              Avatar image URL. Always present — a generated placeholder when the user set no picture.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="username" type="string">
          Public username.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="parent_account" type="object | null">
      Parent account for connected accounts, or `null` for standalone accounts.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Account ID, prefixed `biz_`.
        </ResponseField>

        <ResponseField name="logo_url" type="string | null">
          Account logo image URL.
        </ResponseField>

        <ResponseField name="route" type="string">
          Account public route identifier.
        </ResponseField>

        <ResponseField name="title" type="string">
          Account display name.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="payment_controls" type="object | null">
      Payment health controls currently applied to the account. Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise.

      <Accordion title="Properties">
        <ResponseField name="dispute_alert_auto_refund" type="object">
          Automatic refund settings for pre-chargeback dispute alerts.

          <Accordion title="Properties">
            <ResponseField name="locked" type="boolean">
              Whether the account owner is prevented from changing this threshold.
            </ResponseField>

            <ResponseField name="threshold_usd" type="number | null">
              Maximum dispute alert amount automatically refunded in USD. `null` when automatic refunds are disabled.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="dispute_alert_fee_usd" type="number | null">
          Fee charged for each dispute alert in USD. `null` when unavailable.
        </ResponseField>

        <ResponseField name="enforce_3ds" type="boolean">
          Whether 3-D Secure is forced on every card payment at checkout. The account
          cannot bypass it while set.
        </ResponseField>

        <ResponseField name="financing_disabled" type="boolean">
          Whether payment health controls explicitly disable financing. This is
          independent of financing approval in `capabilities.accept_bnpl_payments`.
        </ResponseField>

        <ResponseField name="high_risk_processing_fee_percentage" type="number">
          Additional processing fee percentage for high-risk processing.
        </ResponseField>

        <ResponseField name="pending_auto_topup_fee_percentage" type="number">
          Percentage fee charged when pending, not-yet-settled balance is advanced to
          fund the account's cards balance, where `2` means 2%. `0` when the account is
          exempt.
        </ResponseField>

        <ResponseField name="pending_balance_delay_days" type="integer">
          Additional days payments remain pending before becoming available.
        </ResponseField>

        <ResponseField name="reserve" type="object">
          Reserve currently applied to incoming payment volume.

          <Accordion title="Properties">
            <ResponseField name="hold_period_days" type="integer">
              Number of days reserved funds are held before release.
            </ResponseField>

            <ResponseField name="percentage" type="number | null">
              Percentage of incoming payment volume held in reserve. `null` when no reserve is applied.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="resolution_center_auto_refund" type="object">
          Automatic refund settings for resolution center cases.

          <Accordion title="Properties">
            <ResponseField name="card_threshold_usd" type="number | null">
              Maximum card-funded resolution center case amount automatically refunded in
              USD. `null` when automatic refunds are disabled for cards.
            </ResponseField>

            <ResponseField name="financing_threshold_usd" type="number | null">
              Maximum financing-funded resolution center case amount automatically refunded
              in USD. `null` when automatic refunds are disabled for financing.
            </ResponseField>

            <ResponseField name="locked" type="boolean">
              Whether the account owner is prevented from changing these thresholds.
            </ResponseField>

            <ResponseField name="paypal_threshold_usd" type="number | null">
              Maximum PayPal-funded resolution center case amount automatically refunded in USD. `null` when automatic refunds are disabled for PayPal.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="restricted_payment_methods" type="string[]">
          Card brands blocked at checkout for this account. Empty when none are blocked. The account cannot re-enable them itself.

          Available options: `card_visa`, `card_mastercard`, `card_american_express`, `card_discover_global_network`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="product_tax_code" type="object | null">
      Tax classification code applied by default to the account's products, with
      `id`, `name`, and `product_type`. `null` when no default is set.
    </ResponseField>

    <ResponseField name="recommended_actions" type="object[] | null">
      DEPRECATED: Use the `GET /accounts/\{account_id}/recommend_actions` endpoint instead.

      <Accordion title="Properties">
        <ResponseField name="action" type="string">
          The recommendation; new values may be added, so handle unknown actions gracefully

          Available options: `theme_business`, `create_product`, `create_plan`, `verify_identity`, `connect_affiliate_program`, `create_promotion`, `setup_tracking_pixel`, `migrate_from_stripe`, `accept_first_payment`, `launch_first_ad`, `launch_draft_campaign`, `increase_ad_budget`, `refresh_ad_creatives`, `fix_ad_billing`, `exclude_customers_from_ads`, `retarget_abandoned_checkouts`, `invite_team_member`, `enable_tax_collection`, `create_card`, `join_whop_university`, `apply_for_financing`
        </ResponseField>

        <ResponseField name="blocked_capabilities" type="string[]">
          Capabilities this would unlock, or empty
        </ResponseField>

        <ResponseField name="cta" type="string">
          The URL the call-to-action links to
        </ResponseField>

        <ResponseField name="cta_label" type="string">
          Button label
        </ResponseField>

        <ResponseField name="description" type="string">
          Supporting copy, or empty
        </ResponseField>

        <ResponseField name="icon_url" type="string | null">
          Illustration icon URL, or `null`
        </ResponseField>

        <ResponseField name="impact_score" type="integer | null">
          Estimated impact from 0-100, or `null` when not ranked
        </ResponseField>

        <ResponseField name="reasoning" type="string | null">
          Why this action was recommended, or `null`
        </ResponseField>

        <ResponseField name="status" type="string">
          Always optional — never blocking

          Available options: `optional`
        </ResponseField>

        <ResponseField name="title" type="string">
          Headline for the recommendation
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="require_2fa" type="boolean">
      Whether authorized users must enable two-factor authentication.
    </ResponseField>

    <ResponseField name="required_actions" type="object[] | null">
      Actions the account owner must take to unblock capabilities like payouts and card spend, ordered by display priority. Computed only on `retrieve` and `me` for callers with `company:balance:read` scope; `null` otherwise.

      <Accordion title="Properties">
        <ResponseField name="action" type="string">
          What the holder must do; new values may be added, so handle unknown actions gracefully

          Available options: `deposit_funds`, `submit_information_request`, `verify_identity`, `connect_fulfillment_tracker`, `setup_apple_pay_domains`, `configure_tax_remitter`, `add_vat_registration`
        </ResponseField>

        <ResponseField name="blocked_capabilities" type="string[]">
          Capabilities gated until this is resolved
        </ResponseField>

        <ResponseField name="cta" type="string | null">
          The URL the call-to-action links to, or null when there is no button
        </ResponseField>

        <ResponseField name="cta_label" type="string">
          Button label, or empty when there is no button
        </ResponseField>

        <ResponseField name="description" type="string">
          Supporting copy, or empty
        </ResponseField>

        <ResponseField name="icon_url" type="string | null">
          The URL of the action's illustration icon, or null if it has none
        </ResponseField>

        <ResponseField name="status" type="string">
          required (act now) or pending (under review)

          Available options: `required`, `pending`
        </ResponseField>

        <ResponseField name="title" type="string">
          Headline for the action
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="route" type="string">
      Account public route identifier.
    </ResponseField>

    <ResponseField name="send_customer_emails" type="boolean">
      Whether Whop sends transactional emails to customers on behalf of this
      account.
    </ResponseField>

    <ResponseField name="show_joined_whops" type="boolean">
      Whether the account appears in joined whops on other accounts.
    </ResponseField>

    <ResponseField name="show_reviews_dtc" type="boolean">
      Whether reviews are displayed on direct-to-consumer product pages.
    </ResponseField>

    <ResponseField name="show_user_directory" type="boolean">
      Whether the account shows users in the user directory.
    </ResponseField>

    <ResponseField name="social_links" type="object[]">
      Account social links.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          The ID of the social link
        </ResponseField>

        <ResponseField name="title" type="string | null">
          The optional display title for the social link
        </ResponseField>

        <ResponseField name="url" type="string">
          The social link URL
        </ResponseField>

        <ResponseField name="website" type="string">
          The social platform for this link

          Available options: `x`, `instagram`, `facebook`, `tiktok`, `youtube`, `linkedin`, `twitch`, `website`, `custom`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="stablecoin_rails" type="boolean">
      Whether the account settles on stablecoin rails — its balance is held on-chain
      as USDT and paid out over crypto, rather than as fiat cash.
    </ResponseField>

    <ResponseField name="status" type="string | null">
      Whether the account can operate on Whop: `active` or `suspended`. Computed on
      `list`, `retrieve`, and `me`; `null` otherwise.
    </ResponseField>

    <ResponseField name="status_reason" type="string | null">
      Why the account was suspended, in language safe to show the account owner.
      Computed only on `retrieve` and `me`; `null` otherwise, when `status` is not
      `suspended`, and when the suspension was recorded without a reason.
    </ResponseField>

    <ResponseField name="store_page_config" type="object">
      Account store page display configuration.

      <Accordion title="Properties">
        <ResponseField name="accent_color" type="string | null">
          Accent color used on the account store page.

          Available options: `ruby`, `tomato`, `red`, `crimson`, `pink`, `plum`, `purple`, `violet`, `iris`, `cyan`, `teal`, `jade`, `green`, `grass`, `brown`, `blue`, `orange`, `indigo`, `sky`, `mint`, `yellow`, `amber`, `lime`, `lemon`, `magenta`, `gold`, `bronze`, `gray`
        </ResponseField>

        <ResponseField name="layout" type="string | null">
          Layout used on the account store page.

          Available options: `featured`, `compact`
        </ResponseField>

        <ResponseField name="profile_variant" type="string | null">
          Profile presentation used on the account store page.

          Available options: `personal`, `business`
        </ResponseField>

        <ResponseField name="whop_affiliate_link" type="boolean">
          Whether the account store page shows a Whop affiliate link.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="target_audience" type="string | null">
      Target audience for this account.
    </ResponseField>

    <ResponseField name="tax_collection_enabled_states" type="string[]">
      US state codes (of the 50 states plus `DC`) where the account collects tax:
      the full set when Whop remits (`tax_remitted_by` `whop`), the configured
      subset when the account self-remits (`self`), and empty when neither. On
      update, send the complete list to replace it (only allowed when `self`).
    </ResponseField>

    <ResponseField name="tax_identifiers" type="object[]">
      Account tax/VAT registrations. Empty when none are set.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Tax identifier ID.
        </ResponseField>

        <ResponseField name="tax_id_type" type="string">
          Tax ID type.

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

        <ResponseField name="tax_id_value" type="string">
          Tax ID value.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="tax_remitted_by" type="string | null">
      Who calculates and remits tax for the account: `whop` (Whop calculates and remits), `self` (Whop calculates; the account collects and remits), or `none` (neither; the account is responsible). `null` until the account enrolls in the Whop tax service.

      Available options: `whop`, `self`, `none`
    </ResponseField>

    <ResponseField name="tax_type" type="string | null">
      How tax is applied to the account's prices: `inclusive` (tax included in the listed price) or `exclusive` (tax added on top). Defaults to `exclusive` when unset; `null` only when the account has no payment connection.

      Available options: `inclusive`, `exclusive`
    </ResponseField>

    <ResponseField name="title" type="string">
      Account display name.
    </ResponseField>

    <ResponseField name="total_earned_usd" type="number | null">
      Account lifetime sales, normalized to USD. Computed only on `retrieve` and
      `me` for callers with `stats:read` scope; `null` otherwise.
    </ResponseField>

    <ResponseField name="total_usd" type="string | null">
      Total USD value across balances with known exchange rates. Computed only on
      single-account reads (`retrieve` and `me`); `null` on list responses, writes,
      missing balance-read permission, or unavailable balance source.
    </ResponseField>

    <ResponseField name="use_logo_as_opengraph_image_fallback" type="boolean">
      Whether the account uses its logo as the fallback Open Graph image.
    </ResponseField>

    <ResponseField name="verification" type="object">
      Account identity verification status for the `individual` (KYC) and `business`
      (KYB) profiles. Each is `null` until created, otherwise a `status` of
      `not_started`, `pending`, `manual_review`, `approved`, or `rejected`.
    </ResponseField>

    <ResponseField name="volume_usd" type="number | null">
      Lifetime volume through the account — sales plus transfers received —
      normalized to USD. Computed only on `list` for callers with `stats:read` on
      the account; `null` otherwise.
    </ResponseField>

    <ResponseField name="wallet" type="object | null">
      Account primary crypto wallet, or `null` if none has been provisioned.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Wallet ID, prefixed `wallet_`.
        </ResponseField>

        <ResponseField name="address" type="string">
          The on-chain address of the wallet
        </ResponseField>

        <ResponseField name="network" type="string">
          The blockchain network the wallet lives on

          Available options: `solana`, `ethereum`, `bitcoin`
        </ResponseField>
      </Accordion>
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Account theme={null}
      {
      	"id": "biz_petalpost123",
      	"balances": [
      		{
      			"balance": "1250.5",
      			"breakdown": {
      				"available": "1200.50",
      				"pending": "50.00",
      				"reserve": "0",
      				"pending_settlements": [
      					{
      						"amount": "50.00",
      						"date": "2026-08-01"
      					}
      				]
      			},
      			"icon_url": "https://cdn.whop.com/tokens/usdt.png",
      			"name": "Tether USD",
      			"price_usd": 1,
      			"symbol": "USDT",
      			"value_usd": "1250.50"
      		},
      		{
      			"balance": "45.00",
      			"breakdown": {
      				"available": "40.00",
      				"pending": "5.00",
      				"reserve": "0",
      				"pending_settlements": [
      					{
      						"amount": "3.00",
      						"date": "2026-08-01"
      					},
      					{
      						"amount": "2.00",
      						"date": "2026-08-04"
      					}
      				]
      			},
      			"icon_url": null,
      			"name": "EUR",
      			"price_usd": 1.11,
      			"symbol": "EUR",
      			"value_usd": "50.00"
      		}
      	],
      	"banner_image_url": "https://cdn.whop.com/banner.png",
      	"business_type": "physical_products",
      	"can_transfer_pending_balance_to_children": false,
      	"country": "US",
      	"created_at": "2026-06-01T12:00:00Z",
      	"description": "Petal Post delivers fresh bouquets.",
      	"email": "hello@petalpost.example",
      	"home_preferences": ["hide_member_count"],
      	"industry_group": "retail",
      	"industry_type": "flower_delivery_gig",
      	"invoice_prefix": "PETAL",
      	"company_formation": {
      		"status": "filed",
      		"legal_name": "Petal Post, LLC",
      		"state_registered": true,
      		"ein_registered": false,
      		"signatures": {
      			"ss4": {
      				"status": "pending",
      				"url": "https://esign.doola.com/session/sess_1a2b3c",
      				"expires_at": "2026-08-01T00:00:00Z"
      			}
      		},
      		"documents": [
      			{
      				"id": "file_petalpost123",
      				"name": "Articles of Organization",
      				"type": "articles_of_organization",
      				"url": "https://img.whop.com/documents/articles-of-organization.pdf"
      			}
      		]
      	},
      	"logo_url": "https://cdn.whop.com/logo.png",
      	"metadata": {
      		"external_merchant_id": "merchant_123"
      	},
      	"onboarding_type": "seller",
      	"opengraph_image_url": "https://cdn.whop.com/og.png",
      	"opengraph_image_variant": "black",
      	"other_business_description": "Local flower delivery",
      	"other_industry_description": "Same-day floral gifts",
      	"owner": {
      		"id": "user_xxxxxxxxxxxx",
      		"username": "petalpost",
      		"name": "Ada Flores",
      		"profile_picture": {
      			"url": "https://cdn.whop.com/user.png"
      		}
      	},
      	"parent_account": {
      		"id": "biz_platform123",
      		"title": "Petal Platform",
      		"route": "petal-platform",
      		"logo_url": "https://cdn.whop.com/petal-platform-logo.png"
      	},
      	"require_2fa": true,
      	"collect_vat_id": false,
      	"capabilities": {
      		"accept_card_payments": "active",
      		"accept_bank_payments": "active",
      		"accept_bnpl_payments": "inactive",
      		"standard_payout": "inactive",
      		"instant_payout": "inactive",
      		"crypto_payout": "inactive",
      		"transfer": "inactive",
      		"bank_deposit": "active",
      		"crypto_deposit": "active",
      		"card_deposit": "active",
      		"card_issuing": "inactive",
      		"run_ads": "active"
      	},
      	"payment_controls": {
      		"dispute_alert_auto_refund": {
      			"threshold_usd": 250,
      			"locked": false
      		},
      		"resolution_center_auto_refund": {
      			"card_threshold_usd": null,
      			"financing_threshold_usd": null,
      			"paypal_threshold_usd": null,
      			"locked": false
      		},
      		"dispute_alert_fee_usd": 29,
      		"high_risk_processing_fee_percentage": 0,
      		"pending_auto_topup_fee_percentage": 2,
      		"pending_balance_delay_days": 0,
      		"financing_disabled": false,
      		"enforce_3ds": false,
      		"restricted_payment_methods": [],
      		"reserve": {
      			"percentage": null,
      			"hold_period_days": 90
      		}
      	},
      	"cards": {
      		"kind": "business",
      		"status": "approved"
      	},
      	"required_actions": [
      		{
      			"action": "verify_identity",
      			"status": "required",
      			"title": "Identity verification required",
      			"description": "Complete verification before your total earnings exceed $5k to continue accepting payments.",
      			"cta_label": "Verify now",
      			"cta": "https://whop.com/dashboard/biz_petalpost123/balance/?verify=true",
      			"icon_url": null,
      			"blocked_capabilities": [
      				"accept_card_payments",
      				"accept_bank_payments",
      				"standard_payout",
      				"instant_payout",
      				"crypto_payout",
      				"transfer",
      				"bank_deposit",
      				"card_issuing"
      			]
      		}
      	],
      	"recommended_actions": [
      		{
      			"action": "migrate_from_stripe",
      			"status": "optional",
      			"title": "Migrate your business from Stripe.",
      			"description": "",
      			"cta_label": "Get started",
      			"cta": "https://whop.com/dashboard/biz_petalpost123/settings/stripe-migrations/",
      			"icon_url": "https://whop.com/illustrations/orange/crane.svg",
      			"blocked_capabilities": [],
      			"reasoning": null,
      			"impact_score": null
      		},
      		{
      			"action": "accept_first_payment",
      			"status": "optional",
      			"title": "Accept your first payment.",
      			"description": "",
      			"cta_label": "Create payment link",
      			"cta": "https://whop.com/dashboard/biz_petalpost123/links/checkout/create/",
      			"icon_url": "https://whop.com/illustrations/orange/card.svg",
      			"blocked_capabilities": [],
      			"reasoning": null,
      			"impact_score": null
      		},
      		{
      			"action": "join_whop_university",
      			"status": "optional",
      			"title": "Grow your business faster.",
      			"description": "",
      			"cta_label": "Join Whop University",
      			"cta": "https://whop.com/whop/",
      			"icon_url": "https://whop.com/illustrations/orange/grad-cap.svg",
      			"blocked_capabilities": [],
      			"reasoning": null,
      			"impact_score": null
      		},
      		{
      			"action": "apply_for_financing",
      			"status": "optional",
      			"title": "Offer financing at checkout",
      			"description": "Let customers pay over time with buy now, pay later.",
      			"cta_label": "Apply",
      			"cta": "https://whop.com/dashboard/biz_petalpost123/settings/payments/",
      			"icon_url": "https://whop.com/illustrations/orange/piggy-bank.svg",
      			"blocked_capabilities": ["accept_bnpl_payments"],
      			"reasoning": null,
      			"impact_score": null
      		}
      	],
      	"route": "petal-post",
      	"send_customer_emails": true,
      	"show_joined_whops": false,
      	"show_reviews_dtc": true,
      	"show_user_directory": false,
      	"stablecoin_rails": false,
      	"status": "active",
      	"status_reason": null,
      	"total_earned_usd": 3450,
      	"volume_usd": 4250.5,
      	"social_links": [
      		{
      			"id": "social_petalpost123",
      			"title": "Petal Post",
      			"url": "https://petalpost.example",
      			"website": "website"
      		}
      	],
      	"store_page_config": {
      		"accent_color": "red",
      		"layout": "compact",
      		"profile_variant": "business",
      		"whop_affiliate_link": true
      	},
      	"target_audience": "Customers sending flowers locally",
      	"tax_collection_enabled_states": ["CA", "NY"],
      	"tax_remitted_by": "whop",
      	"tax_type": "exclusive",
      	"product_tax_code": {
      		"id": "ptc_CzLNn2Z058xEC1",
      		"name": "Digital Group Chat",
      		"product_type": "digital"
      	},
      	"business_address": {
      		"line1": "123 Garden Way",
      		"line2": null,
      		"city": "Austin",
      		"state": "TX",
      		"postal_code": "78701",
      		"country": "US"
      	},
      	"tax_identifiers": [
      		{
      			"id": "taxid_petalpost123",
      			"tax_id_type": "us_ein",
      			"tax_id_value": "12-3456789"
      		}
      	],
      	"title": "Petal Post",
      	"total_usd": "1300.50",
      	"use_logo_as_opengraph_image_fallback": true,
      	"verification": {
      		"business": null,
      		"individual": {
      			"status": "approved"
      		}
      	},
      	"wallet": {
      		"id": "wallet_petalpost123",
      		"address": "So11111111111111111111111111111111111111112",
      		"network": "solana"
      	}
      }
      ```
    </div>
  </Column>
</Columns>

## Business types and industries glossary

Accounts are classified by three fields: `business_type`, `industry_group`, and `industry_type`.

Dropdown structure:

```text theme={null}
business_type
    industry_group
        industry_type
```

<AccordionGroup>
  <Accordion title="coaching_and_courses">
    <AccordionGroup>
      <Accordion title="trading_and_investing">
        `forex_trading`, `stock_trading`, `options_trading`, `crypto_trading`,
        `futures_trading`, `day_trading`, `swing_trading`,
        `algorithmic_trading`, `prop_firm_trading`, `value_investing`,
        `real_estate_investing`, `alternative_investments`,
        `penny_stock_trading`, `dividend_investing`, `index_fund_investing`,
        `gold_precious_metals`, `venture_capital_education`,
        `private_equity_education`, `technical_analysis`, `forex_scalping`,
        `ict_smc_trading`, `personalized_investment_advice`
      </Accordion>

      <Accordion title="sports_betting_and_gambling">
        `sports_betting_picks`, `fantasy_sports`, `horse_racing`,
        `poker_coaching`, `esports_betting`, `sports_analytics`, `nfl_betting`,
        `nba_betting`, `mlb_betting`, `soccer_betting`, `mma_ufc_betting`
      </Accordion>

      <Accordion title="fitness_and_athletics">
        `bodybuilding_coaching`, `strength_training`, `weight_loss_coaching`,
        `athletic_performance`, `yoga_instruction`, `martial_arts_instruction`,
        `running_coaching`, `calisthenics`, `flexibility_mobility`,
        `nutrition_coaching`, `swimming_coaching`, `cycling_coaching`,
        `boxing_coaching`, `mma_coaching`, `jiu_jitsu_coaching`,
        `wrestling_coaching`, `gymnastics_coaching`, `pilates_instruction`,
        `sports_nutrition`, `body_recomposition`, `golf_coaching`,
        `tennis_coaching`, `basketball_training`, `soccer_training`,
        `racket_sports_coaching`
      </Accordion>

      <Accordion title="health_and_wellness">
        `mental_health_coaching`, `life_coaching`, `biohacking`,
        `holistic_health`, `addiction_recovery_coaching`, `breathwork`,
        `meditation_mindfulness`, `gut_health_coaching`, `longevity_coaching`,
        `womens_health_coaching`, `mens_health_coaching`, `fertility_wellness`,
        `stress_management`, `grief_coaching`, `trauma_recovery_coaching`,
        `adhd_coaching`, `biomarker_health_coaching`
      </Accordion>

      <Accordion title="business_and_entrepreneurship">
        `ecommerce_education`, `amazon_fba_coaching`, `dropshipping_coaching`,
        `print_on_demand_coaching`, `retail_arbitrage`, `wholesale_coaching`,
        `startup_coaching`, `business_strategy`, `agency_building`,
        `smma_coaching`, `consulting_business`, `saas_entrepreneurship`,
        `local_business_coaching`, `cleaning_business_coaching`,
        `trucking_business_coaching`, `vending_machine_business`,
        `atm_business_coaching`, `car_wash_business`,
        `airbnb_business_coaching`, `private_label_coaching`, `etsy_coaching`,
        `merch_business_coaching`, `licensing_business`, `business_acquisition`,
        `women_entrepreneurship`, `affiliate_marketing_education`,
        `coaching_business_coaching`
      </Accordion>

      <Accordion title="sales_and_revenue">
        `high_ticket_sales`, `b2b_sales_coaching`, `door_to_door_sales`,
        `sales_funnel_coaching`, `appointment_setting_coaching`,
        `insurance_sales_coaching`, `car_sales_coaching`,
        `retail_sales_coaching`, `solar_sales_coaching`
      </Accordion>

      <Accordion title="marketing_and_advertising">
        `facebook_ads`, `google_ads`, `tiktok_marketing`, `youtube_marketing`,
        `instagram_growth`, `seo_coaching`, `email_marketing_coaching`,
        `copywriting_coaching`, `affiliate_marketing`, `local_seo`,
        `ai_marketing`, `webinar_marketing`, `event_marketing`,
        `saas_marketing_coaching`, `digital_marketing`
      </Accordion>

      <Accordion title="creative_and_content_creation">
        `video_editing_education`, `photography_coaching`, `music_production`,
        `ui_ux_design_education`, `clipping_education`, `ugc_creation`,
        `3d_modeling_education`, `dj_education`, `youtube_automation`,
        `blog_monetization`, `wedding_photography_education`,
        `calligraphy_lettering`, `illustration_education`,
        `fashion_design_education`, `interior_design_education`,
        `influencer_education`, `ai_content_creator_education`,
        `ai_nsfw_content_generation_education`
      </Accordion>

      <Accordion title="tech_and_development">
        `web_development_education`, `ai_ml_education`,
        `data_science_education`, `cybersecurity_education`,
        `cloud_computing_education`, `blockchain_education`,
        `no_code_education`, `automation_education`,
        `game_development_education`, `prompt_engineering`,
        `python_programming`, `javascript_programming`, `react_development`,
        `database_engineering`, `aws_certification`, `data_engineering`,
        `robotics_education`, `vr_ar_development`, `linux_sysadmin`,
        `wordpress_development`, `ai_agent_building`
      </Accordion>

      <Accordion title="real_estate">
        `real_estate_wholesaling`, `house_flipping`, `property_development`,
        `rental_property`, `airbnb_str`, `commercial_real_estate`,
        `land_investing`, `section_8_housing`, `mobile_home_investing`,
        `multifamily_investing`, `self_storage_investing`,
        `property_management_education`, `vacation_rental_management`
      </Accordion>

      <Accordion title="personal_finance">
        `credit_repair_education`, `budgeting_coaching`,
        `tax_strategy_education`, `wealth_building`, `student_loan_strategy`,
        `credit_card_optimization`
      </Accordion>

      <Accordion title="career_and_professional">
        `career_coaching`, `executive_coaching`, `management_coaching`,
        `tech_career_coaching`, `medical_career_coaching`,
        `trade_skills_education`, `va_training`, `bookkeeping_education`,
        `data_career_coaching`, `cybersecurity_career`, `consulting_career`,
        `investment_banking_career`, `law_career_coaching`,
        `nursing_career_coaching`, `teaching_career_coaching`,
        `personal_branding_career`
      </Accordion>

      <Accordion title="dating_and_relationships">
        `mens_dating_coaching`, `womens_dating_coaching`,
        `relationship_coaching`, `marriage_coaching`, `communication_coaching`,
        `masculinity_coaching`, `femininity_coaching`, `breakup_recovery`
      </Accordion>

      <Accordion title="spirituality_and_mindfulness">
        `manifestation_coaching`, `astrology_coaching`, `energy_healing`,
        `spiritual_coaching`, `faith_based_coaching`, `psychic_development`,
        `numerology_coaching`, `chakra_healing`, `shamanic_healing`,
        `biblical_coaching`, `islamic_coaching`
      </Accordion>

      <Accordion title="personal_development">
        `productivity_coaching`, `public_speaking_coaching`, `mindset_coaching`,
        `stoicism_philosophy`, `mens_self_improvement`,
        `womens_self_improvement`, `leadership_development`, `anger_management`,
        `neurolinguistic_programming`, `appearance_and_grooming_coaching`
      </Accordion>

      <Accordion title="publishing_and_info_products">
        `amazon_kdp`, `self_publishing`, `audiobook_publishing`,
        `course_creation`, `digital_product_creation`, `ghostwriting_business`,
        `template_creation`, `ai_book_publishing`
      </Accordion>

      <Accordion title="academic_and_test_prep">
        `language_learning`, `tutoring`, `college_admissions_coaching`,
        `cpa_exam_prep`, `bar_exam_prep`, `real_estate_exam_prep`,
        `medical_board_prep`, `pmp_certification_prep`,
        `aws_certification_prep`, `comptia_certification`, `ap_exam_prep`,
        `graduate_school_prep`, `scholarship_coaching`, `homeschool_education`,
        `stem_education`, `financial_certification`, `coding_bootcamp_prep`
      </Accordion>

      <Accordion title="hobbies_and_lifestyle">
        `cooking_culinary`, `travel_coaching`, `parenting_coaching`,
        `pet_training`, `gardening_education`, `diy_crafts`,
        `survival_prepping`, `baking_pastry`, `wine_sommelier`, `beer_brewing`,
        `mixology_bartending`, `woodworking`, `pottery_ceramics`,
        `knitting_crocheting`, `jewelry_making`, `aquarium_fishkeeping`,
        `bird_watching`, `astronomy_education`, `magic_illusion`,
        `car_restoration`, `motorcycle_riding`, `sailing_boating`,
        `scuba_diving`, `rock_climbing`, `skiing_snowboarding`,
        `surfing_education`, `homesteading`, `tiny_house_living`, `van_life`,
        `fashion_styling`, `floral_design`, `travel_planning_service`,
        `collectibles_coaching`
      </Accordion>

      <Accordion title="video_games_and_esports">
        `esports_coaching`, `game_specific_coaching`
      </Accordion>

      <Accordion title="legal_and_compliance">`legal_education`</Accordion>

      <Accordion title="music_and_performing_arts">
        `music_theory`, `music_business`, `acting_coaching`,
        `dance_instruction`, `voice_acting`
      </Accordion>

      <Accordion title="language_and_communication">
        `english_coaching`, `spanish_coaching`, `mandarin_coaching`,
        `french_coaching`, `german_coaching`, `japanese_coaching`,
        `korean_coaching`, `arabic_coaching`, `sign_language_education`,
        `accent_reduction`, `business_english`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="services">
    <AccordionGroup>
      <Accordion title="marketing_and_advertising">
        `smma`, `performance_marketing_agency`, `seo_agency`,
        `content_marketing_agency`, `email_marketing_agency`,
        `influencer_marketing_agency`, `pr_agency`, `branding_agency`,
        `video_marketing_agency`, `amazon_marketing_agency`,
        `podcast_marketing_agency`, `tiktok_agency`, `linkedin_agency`,
        `local_marketing_agency`, `dental_marketing_agency`,
        `real_estate_marketing_agency`, `restaurant_marketing_agency`,
        `ecommerce_marketing_agency`, `b2b_marketing_agency`,
        `growth_marketing_agency`, `affiliate_management_agency`,
        `conversion_optimization_agency`, `event_marketing_agency`,
        `click_farm_service`, `data_scraping_service`, `lead_list_sales`,
        `social_media_bot_farm`
      </Accordion>

      <Accordion title="sales_and_revenue">
        `lead_generation_agency`, `cold_email_agency`, `cold_calling_agency`,
        `sales_outsourcing`, `crm_implementation`, `appointment_setting_agency`,
        `sales_training_agency`, `revenue_operations_agency`,
        `door_to_door_sales`, `inbound_teleservices`, `outbound_telemarketing`
      </Accordion>

      <Accordion title="ai_and_automation_agencies">
        `ai_chatbot_agency`, `ai_automation_agency`, `ai_consulting`,
        `workflow_automation_agency`, `data_analytics_agency`,
        `ai_voice_agent_agency`, `ai_content_agency`, `machine_learning_agency`,
        `computer_vision_agency`
      </Accordion>

      <Accordion title="creative_and_content_creation">
        `web_design_agency`, `graphic_design_agency`, `ui_ux_agency`,
        `motion_design_agency`, `product_design_agency`, `logo_design_agency`,
        `presentation_design_agency`, `3d_visualization_agency`,
        `fashion_design_agency`, `video_clipping_agency`,
        `video_production_agency`, `ugc_agency`, `content_writing_agency`,
        `translation_agency`, `social_media_management`, `ghostwriting_agency`,
        `podcast_editing_agency`, `thumbnail_design_agency`,
        `scriptwriting_agency`, `seo_content_agency`,
        `technical_writing_agency`, `photography_service`,
        `videography_service`, `music_production_service`, `voice_over_service`,
        `event_photography`, `drone_services`, `commercial_photography`,
        `portrait_photography_service`, `real_estate_photography`,
        `food_photography_service`, `live_event_production`,
        `podcast_production_service`
      </Accordion>

      <Accordion title="tech_and_development">
        `web_development_agency`, `mobile_app_agency`,
        `saas_development_agency`, `ecommerce_development`,
        `blockchain_development_agency`, `game_development_agency`,
        `devops_agency`, `ai_development_agency`, `wordpress_agency`,
        `shopify_agency`, `api_integration_agency`, `cybersecurity_agency`,
        `data_engineering_agency`, `vr_ar_development_agency`,
        `hacking_tools_malware`, `stalkerware_monitoring`
      </Accordion>

      <Accordion title="recruiting_and_staffing">
        `tech_recruiting_agency`, `executive_recruiting`, `staffing_agency`,
        `remote_staffing`, `healthcare_recruiting`, `va_placement_agency`,
        `sales_recruiting`, `creative_recruiting`, `finance_recruiting`,
        `legal_recruiting`, `construction_staffing`, `hospitality_staffing`
      </Accordion>

      <Accordion title="customer_support_agencies">
        `customer_support_outsourcing`, `live_chat_agency`,
        `technical_support_agency`, `call_center_agency`,
        `multilingual_support_agency`, `community_management_agency`
      </Accordion>

      <Accordion title="consulting">
        `management_consulting`, `financial_consulting`, `hr_consulting`,
        `operations_consulting`, `it_consulting`, `sustainability_consulting`,
        `legal_consulting`, `compliance_consulting`, `supply_chain_consulting`,
        `change_management_consulting`, `digital_transformation_consulting`,
        `healthcare_consulting`, `real_estate_consulting`,
        `franchise_consulting`, `export_trade_consulting`,
        `nonprofit_consulting`, `education_consulting`, `cannabis_consulting`,
        `restaurant_consulting`, `m_and_a_consulting`,
        `pricing_strategy_consulting`, `brand_strategy_consulting`,
        `saas_marketing_consulting`, `done_for_you_services`,
        `prop_firm_passing_service`, `trading_account_management`,
        `done_for_you_trading`
      </Accordion>

      <Accordion title="professional_services">
        `accounting_bookkeeping`, `tax_preparation`, `legal_services`,
        `notary_services`, `insurance_brokerage`, `financial_planning_service`,
        `real_estate_services`, `property_management`, `mortgage_brokerage`,
        `immigration_services`, `patent_trademark_services`,
        `business_formation_services`, `shell_company_formation`,
        `payroll_services`, `audit_services`, `forensic_accounting`,
        `actuarial_services`, `appraisal_services`, `mediation_arbitration`,
        `background_check_services`, `bail_bond_services`, `bnpl_service`,
        `check_cashing_service`, `cloud_mining_schemes`, `consumer_lending`,
        `credit_repair_service`, `crowdfunding_platform`,
        `crypto_exchange_brokerage`, `debt_collection_agency`,
        `debt_relief_settlement`, `document_falsification`, `escrow_service`,
        `essay_mill_paper_mill`, `fake_id_services`, `fake_reference_services`,
        `foreign_exchange_service`, `government_service_facilitation`,
        `immigration_services_unlicensed`, `licensed_legal_services`,
        `payment_facilitation`, `personalized_investment_advice`,
        `personalized_tax_services`, `prediction_market_exchange`,
        `private_investigation`, `repossession_services`, `stablecoin_issuance`,
        `standalone_tipping`, `token_sales_ico`, `tokenized_rwa`,
        `unlicensed_legal_services`, `yield_staking_products`
      </Accordion>

      <Accordion title="media_and_publishing_companies">
        `record_label`, `book_publishing_house`, `news_media_outlet`,
        `radio_broadcasting`, `tv_production_company`, `film_studio`,
        `magazine_publisher`, `music_licensing_agency`,
        `talent_management_agency`, `advertising_network`, `ad_tech_platform`
      </Accordion>

      <Accordion title="home_and_trade_services">
        `cleaning_service`, `landscaping_service`, `plumbing_service`,
        `electrical_service`, `hvac_service`, `roofing_service`,
        `painting_service`, `moving_service`, `handyman_service`,
        `pest_control`, `pool_service`, `solar_installation`, `home_renovation`,
        `pressure_washing`, `junk_removal`, `garage_door_service`,
        `fencing_service`, `concrete_masonry`, `tree_service`,
        `window_cleaning`, `gutter_service`, `flooring_service`,
        `cabinet_countertop`, `home_inspection`, `septic_service`,
        `waterproofing_service`, `insulation_service`, `chimney_service`,
        `locksmith_service`, `glass_window_service`, `epoxy_coating`
      </Accordion>

      <Accordion title="security_and_investigations">
        `private_security_guard_service`, `armored_car_transport`,
        `executive_protection_bodyguard`, `event_security_service`,
        `alarm_system_installation`, `cctv_installation`,
        `private_investigation_agency`, `background_check_provider`,
        `locksmith_commercial`, `bounty_hunter_bail_enforcement`
      </Accordion>

      <Accordion title="personal_services">
        `personal_styling`, `personal_chef`, `personal_assistant_service`,
        `tutoring_service`, `pet_services`, `wedding_planning`,
        `concierge_service`, `personal_training_service`, `nanny_service`,
        `elder_care_service`, `errand_service`, `life_organization`,
        `travel_planning_service`, `relocation_service`,
        `adult_dating_services`, `escort_services`,
        `hotel_accommodation_bookings`, `mail_order_spouse`,
        `psychic_fortune_telling`, `timeshare_sales`
      </Accordion>

      <Accordion title="logistics_and_transportation_services">
        `freight_brokerage`, `courier_service`, `warehousing_service`,
        `last_mile_delivery`, `auto_transport`, `international_shipping`,
        `cold_chain_logistics`, `commercial_airline_tickets`,
        `cruise_line_bookings`
      </Accordion>

      <Accordion title="industrial_and_manufacturing">
        `contract_manufacturing`, `cnc_machining_service`,
        `3d_printing_service_commercial`, `plastic_injection_molding`,
        `metal_fabrication`, `pcba_assembly`, `chemical_manufacturing`,
        `textile_manufacturing`, `food_processing_facility`,
        `packaging_manufacturing`, `industrial_automation_integrator`,
        `mining_and_extraction`, `oil_and_gas_services`,
        `renewable_energy_generation`, `waste_management_recycling`,
        `hazardous_waste_disposal`, `aerospace_defense_contracting`
      </Accordion>

      <Accordion title="health_and_wellness_services">
        `personal_training_studio`, `nutrition_consulting`,
        `mental_health_counseling`, `physical_therapy_service`,
        `occupational_therapy_service`, `speech_therapy_service`,
        `chiropractic_service`, `acupuncture_service`,
        `massage_therapy_service`, `midwifery_doula`, `lactation_consulting`,
        `dietitian_service`, `addiction_recovery_services`, `dtc_lab_testing`,
        `iv_therapy_infusion`, `medspa_aesthetic_services`,
        `prescription_delivery_services`, `registered_dietitian_services`,
        `unlicensed_therapy_counseling`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="physical_product">
    <AccordionGroup>
      <Accordion title="clothing_and_apparel">
        `streetwear`, `athleisure`, `luxury_fashion`, `kids_clothing`,
        `custom_apparel`, `workwear`, `swimwear`, `lingerie_intimates`,
        `vintage_clothing`, `plus_size_fashion`, `maternity_clothing`,
        `sleepwear_loungewear`, `denim_brand`, `outerwear_jackets`,
        `socks_hosiery`, `costumes_cosplay`, `scrubs_medical_apparel`,
        `dance_performance_wear`, `hunting_camo_apparel`,
        `casual_everyday_clothing`
      </Accordion>

      <Accordion title="supplements_and_nutrition">
        `protein_supplements`, `vitamins_minerals`, `pre_workout`, `nootropics`,
        `herbal_supplements`, `weight_management_supplements`, `gut_health`,
        `cbd_products`, `mushroom_supplements`, `collagen_supplements`,
        `testosterone_boosters`, `sleep_supplements`, `immune_support`,
        `joint_bone_health`, `greens_powder`, `creatine_supplements`,
        `electrolyte_hydration`, `prenatal_supplements`, `kids_supplements`,
        `pet_supplements`, `ayurvedic_supplements`, `keto_supplements`,
        `cannabis_thc_products`, `cbd_hemp_products_compliant`,
        `delta8_thc_products`, `dietary_supplements`,
        `drug_precursor_chemicals`, `illegal_drugs`, `kratom_kava_products`,
        `medical_treatment_claims_product`, `nutraceutical_products`,
        `otc_medication_sales`, `performance_enhancing_drugs`,
        `research_chemicals_dangerous`, `research_peptides`,
        `sexual_enhancement_products`, `tobacco_products`, `unlicensed_rx_sales`
      </Accordion>

      <Accordion title="beauty_and_personal_care">
        `skincare`, `haircare`, `cosmetics_makeup`, `mens_grooming`,
        `fragrance`, `oral_care`, `sunscreen_spf`, `hair_growth_products`,
        `body_care`, `deodorant`, `lip_care`, `acne_treatment`, `men_skincare`,
        `baby_skincare`, `tattoo_aftercare`, `intimate_care`
      </Accordion>

      <Accordion title="fitness_equipment_and_gear">
        `home_gym_equipment`, `yoga_equipment`, `combat_sports_gear`,
        `outdoor_fitness_gear`, `wearable_fitness`, `recovery_equipment`,
        `weightlifting_equipment`, `cardio_equipment`, `gymnastics_equipment`,
        `swimming_gear`, `jump_rope_equipment`, `grip_strength_tools`,
        `sauna_cold_plunge`, `posture_correctors`
      </Accordion>

      <Accordion title="accessories">
        `jewelry`, `sunglasses_eyewear`, `bags_wallets`, `hats_headwear`,
        `phone_accessories`, `travel_accessories`, `scarves_wraps`, `belts`,
        `hair_accessories`, `tech_accessories`, `keychains_charms`,
        `custom_engraved_accessories`, `cannabis_accessories_non_drug`,
        `drug_paraphernalia`, `high_value_goods_over_500`,
        `precious_metals_stones`, `replica_counterfeit_goods`
      </Accordion>

      <Accordion title="home_and_living">
        `home_decor`, `candles_scents`, `kitchenware`, `bedding_linens`,
        `smart_home`, `cleaning_products`, `outdoor_furniture`,
        `organization_storage`, `wall_art_prints`, `rugs_carpets`,
        `lighting_fixtures`, `planters_garden_decor`, `bathroom_accessories`,
        `luxury_home_goods`, `seasonal_holiday_decor`, `pet_home_products`,
        `home_fragrance_diffusers`, `hazardous_chemicals_b2c`,
        `pre_orders_delayed_delivery`
      </Accordion>

      <Accordion title="electronics_and_gadgets">
        `audio_equipment`, `camera_equipment`, `gaming_hardware`,
        `drones_robotics`, `ev_accessories`, `charging_power`,
        `smart_wearables`, `home_security_devices`, `3d_printers`,
        `projectors_displays`, `streaming_devices`, `vr_headsets`, `e_readers`,
        `portable_tech`, `hardware_wallets`, `regulated_medical_devices`,
        `signal_jamming_devices`, `spy_cameras_hidden_recording`
      </Accordion>

      <Accordion title="food_and_beverages">
        `specialty_coffee_tea`, `health_food`, `snacks_treats`,
        `sauces_condiments`, `alcohol_spirits`, `meal_kits`, `baked_goods`,
        `beverages`, `pet_food_treats`, `protein_bars_snacks`,
        `jerky_meat_snacks`, `chocolate_confections`, `honey_sweeteners`,
        `olive_oil_vinegar`, `hot_sauce`, `dried_fruit_nuts`, `baby_food`,
        `plant_based_food`, `gluten_free_food`, `keto_food_products`,
        `subscription_food_box`, `kombucha_fermented`, `alcohol_sales`
      </Accordion>

      <Accordion title="baby_and_kids">
        `baby_products`, `kids_toys`, `kids_educational`,
        `baby_clothing_accessories`, `nursery_decor`, `kids_outdoor_play`,
        `kids_books`, `baby_safety_products`, `kids_arts_crafts`
      </Accordion>

      <Accordion title="outdoor_and_sports">
        `camping_hiking`, `fishing_gear`, `hunting_gear`, `cycling_gear`,
        `water_sports_gear`, `golf_equipment`, `snow_sports_gear`,
        `climbing_gear`, `archery_equipment`, `skateboarding_gear`,
        `pickleball_equipment`, `tennis_equipment`, `equestrian_gear`,
        `tactical_gear`, `overlanding_gear`, `explosives_fireworks`,
        `firearms_sales`, `self_defense_products`, `weapon_components`
      </Accordion>

      <Accordion title="arts_and_crafts">
        `craft_kits`, `sewing_textiles`, `stationery`, `scrapbooking_supplies`,
        `beading_jewelry_supplies`, `pottery_supplies`, `printmaking_supplies`
      </Accordion>

      <Accordion title="automotive">
        `car_accessories`, `detailing_products`, `motorcycle_gear`,
        `truck_accessories`, `off_road_parts`, `car_audio_electronics`,
        `performance_parts`, `car_care_products`, `ev_charging_accessories`
      </Accordion>

      <Accordion title="pets_and_animals">
        `dog_products`, `cat_products`, `aquarium_supplies`, `bird_supplies`,
        `reptile_supplies`, `horse_supplies`, `pet_apparel`, `pet_tech`,
        `pet_grooming_products`
      </Accordion>

      <Accordion title="home_improvement_and_tools">
        `hand_tools`, `power_tools_and_accessories`, `hardware_and_fasteners`,
        `workshop_equipment_and_storage`, `safety_and_work_gear`,
        `painting_and_building_supplies`
      </Accordion>

      <Accordion title="office_and_business_supplies">
        `office_supplies`, `desk_accessories`, `printing_supplies`,
        `shipping_packaging`
      </Accordion>

      <Accordion title="sustainability_and_eco_products">
        `reusable_products`, `solar_powered_products`
      </Accordion>

      <Accordion title="religion_and_faith">
        `christian_books_bibles`, `christian_apparel`, `christian_jewelry`,
        `christian_home_decor`, `jewish_judaica`, `jewish_books_torah`,
        `jewish_apparel`, `islamic_books_quran`, `islamic_apparel`,
        `islamic_prayer_goods`, `hindu_puja_supplies`, `hindu_books_texts`,
        `buddhist_meditation_goods`, `buddhist_books_texts`,
        `sikh_religious_goods`, `other_religious_products`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="marketplace">
    <AccordionGroup>
      <Accordion title="product_marketplaces">
        `handmade_goods_marketplace`, `vintage_resale_marketplace`,
        `electronics_marketplace`, `auto_parts_marketplace`,
        `luxury_goods_marketplace`, `collectibles_marketplace`,
        `wholesale_marketplace`, `local_goods_marketplace`,
        `sneaker_marketplace`, `book_marketplace`, `furniture_marketplace`,
        `musical_instrument_marketplace`, `art_marketplace`,
        `ticket_marketplace`, `industrial_equipment_marketplace`,
        `craft_supply_marketplace`, `baby_kids_marketplace`,
        `outdoor_gear_marketplace`, `pet_marketplace`,
        `sustainable_goods_marketplace`, `3d_weapon_files`, `alcohol_sales`,
        `cannabis_thc_products`, `cbd_hemp_products_compliant`,
        `cultural_artifacts_looted`, `delta8_thc_products`,
        `dietary_supplements`, `dropshipping_operations`, `drug_paraphernalia`,
        `drug_precursor_chemicals`, `endangered_animal_products`,
        `explosives_fireworks`, `firearms_sales`, `hazardous_chemicals_b2c`,
        `high_value_goods_over_500`, `human_body_parts_tissue`, `illegal_drugs`,
        `kratom_kava_products`, `nft_marketplace`, `nutraceutical_products`,
        `otc_medication_sales`, `penny_auction`, `performance_enhancing_drugs`,
        `pre_orders_delayed_delivery`, `precious_metals_stones`,
        `primary_event_ticketing`, `regulated_medical_devices`,
        `replica_counterfeit_goods`, `research_peptides`,
        `self_defense_products`, `sexual_enhancement_products`,
        `signal_jamming_devices`, `spy_cameras_hidden_recording`,
        `tobacco_products`, `unlicensed_rx_sales`, `weapon_components`
      </Accordion>

      <Accordion title="service_marketplaces">
        `freelancer_marketplace`, `home_services_marketplace`,
        `tutoring_marketplace`, `legal_services_marketplace`,
        `healthcare_marketplace`, `wedding_services_marketplace`,
        `creative_and_content_creation_marketplace`,
        `beauty_services_marketplace`, `fitness_trainer_marketplace`,
        `pet_services_marketplace`, `childcare_marketplace`,
        `elder_care_marketplace`, `translation_marketplace`,
        `coaching_marketplace`, `therapy_marketplace`,
        `photography_marketplace`, `dj_entertainment_marketplace`,
        `auto_services_marketplace`, `commercial_airline_tickets`,
        `cruise_line_bookings`, `freelance_marketplace_operator`,
        `hotel_accommodation_bookings`, `timeshare_sales`,
        `travel_planning_service`
      </Accordion>

      <Accordion title="rental_marketplaces">
        `equipment_rental_marketplace`, `vehicle_rental_marketplace`,
        `space_rental_marketplace`, `vacation_rental_marketplace`,
        `clothing_rental_marketplace`, `camera_gear_rental`, `rv_camper_rental`,
        `boat_rental_marketplace`, `storage_rental_marketplace`,
        `office_coworking_rental`, `parking_rental_marketplace`
      </Accordion>

      <Accordion title="food_and_hospitality_marketplaces">
        `restaurant_marketplace`, `grocery_marketplace`, `catering_marketplace`,
        `homemade_food_marketplace`, `meal_prep_marketplace`,
        `bakery_marketplace`, `farm_produce_marketplace`,
        `chef_booking_marketplace`
      </Accordion>

      <Accordion title="digital_and_education_marketplaces">
        `course_marketplace`, `template_marketplace`, `stock_media_marketplace`,
        `music_beats_marketplace`, `ebook_marketplace`,
        `plugin_theme_marketplace`, `3d_model_marketplace`,
        `prompt_marketplace`, `code_snippet_marketplace`,
        `affiliate_marketing_platform`, `game_account_selling`,
        `game_cheats_hacks`, `pirated_digital_content`,
        `unauthorized_ingame_currency`, `weapon_blueprint_distribution`
      </Accordion>

      <Accordion title="b2b_and_professional_marketplaces">
        `saas_marketplace`, `agency_marketplace`, `manufacturing_marketplace`,
        `logistics_marketplace`, `commercial_real_estate_marketplace`,
        `business_for_sale_marketplace`, `bnpl_service`, `cloud_mining_schemes`,
        `crowdfunding_platform`, `crypto_exchange_brokerage`,
        `payment_facilitation`, `personalized_investment_advice`,
        `prediction_market_exchange`, `stablecoin_issuance`,
        `standalone_tipping`, `token_sales_ico`, `tokenized_rwa`,
        `yield_staking_products`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="gig_economy">
    <AccordionGroup>
      <Accordion title="delivery_and_logistics">
        `food_delivery`, `grocery_delivery`, `package_delivery`,
        `courier_service`, `moving_labor`, `alcohol_delivery`,
        `pharmacy_delivery`, `flower_delivery_gig`, `furniture_delivery_gig`,
        `catering_delivery`
      </Accordion>

      <Accordion title="transportation">
        `rideshare`, `chauffeur_service`, `bike_scooter_rental`,
        `boat_charter_gig`, `moving_truck_rental_gig`
      </Accordion>

      <Accordion title="task_and_errands">
        `assembly_installation`, `waiting_line_service`, `personal_shopping`,
        `grocery_shopping_gig`, `gift_wrapping_gig`, `notary_gig`,
        `laundry_gig`, `car_wash_gig`
      </Accordion>

      <Accordion title="home_services_gigs">
        `cleaning_gig`, `lawn_care_gig`, `handyman_gig`, `pet_care_gig`,
        `childcare_gig`, `elder_care_gig`, `painting_gig`, `snow_removal_gig`,
        `pool_cleaning_gig`, `organizing_gig`, `pressure_washing_gig`,
        `junk_removal_gig`
      </Accordion>

      <Accordion title="creative_and_content_creation">
        `freelance_design_gig`, `freelance_writing_gig`, `freelance_dev_gig`,
        `music_performance_gig`, `event_staffing_gig`, `model_talent_gig`,
        `photography_gig`, `videography_gig`, `voiceover_gig`,
        `illustration_gig`, `social_media_gig`, `dj_gig`, `face_painting_gig`,
        `clipping_gig`
      </Accordion>

      <Accordion title="professional_gigs">
        `consulting_gig`, `accounting_gig`, `legal_gig`, `healthcare_gig`,
        `teaching_gig`, `translation_gig`, `data_entry_gig`, `research_gig`,
        `virtual_assistant_gig`, `sales_gig`, `recruiting_gig`
      </Accordion>

      <Accordion title="specialized_gigs">
        `mystery_shopping`, `focus_group_gig`, `product_testing_gig`,
        `drone_pilot_gig`, `fitness_instruction_gig`, `tour_guide_gig`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="paid_group">
    <AccordionGroup>
      <Accordion title="trading_and_investing">
        `forex_signals_group`, `stock_signals_group`, `crypto_signals_group`,
        `options_alerts_group`, `futures_signals_group`,
        `trading_education_group`, `investing_community`,
        `prediction_markets_group`, `nft_alpha_group`, `penny_stock_group`,
        `dividend_investing_group`, `real_estate_investing_group`,
        `prop_firm_group`
      </Accordion>

      <Accordion title="sports_betting_and_gambling">
        `sports_picks_group`, `dfs_group`, `horse_racing_group`,
        `esports_picks_group`, `nfl_picks_group`, `nba_picks_group`,
        `soccer_picks_group`, `mlb_picks_group`, `mma_picks_group`,
        `prop_bets_group`, `fantasy_sports_free_to_play`,
        `licensed_gambling_operations`, `unlicensed_gambling`
      </Accordion>

      <Accordion title="business_and_entrepreneurship">
        `ecommerce_community`, `agency_community`, `saas_community`,
        `saas_marketing_community`, `real_estate_community`, `sales_community`,
        `affiliate_community`, `reselling_community`, `amazon_seller_community`,
        `dropshipping_community`, `freelancer_community`,
        `startup_founder_community`, `ceo_executive_community`,
        `women_business_community`, `marketing_community`,
        `ai_business_community`, `content_business_community`,
        `local_business_community`, `private_equity_community`,
        `wholesaling_community`, `coaching_business_community`,
        `make_money_online_community`
      </Accordion>

      <Accordion title="fitness_and_athletics">
        `fitness_accountability`, `nutrition_community`, `weight_loss_group`,
        `bodybuilding_community`, `running_community`, `martial_arts_community`,
        `mental_health_group`, `biohacking_community`,
        `addiction_support_group`, `yoga_community`, `crossfit_community`,
        `longevity_community`, `womens_fitness_community`,
        `postpartum_fitness_group`, `chronic_illness_support`,
        `skincare_community`
      </Accordion>

      <Accordion title="creative_and_content_creation">
        `content_creator_community`, `video_editing_community`,
        `music_producer_community`, `photography_community`,
        `writing_community`, `design_community`, `youtube_creator_community`,
        `tiktok_creator_community`, `podcast_community`, `filmmaker_community`,
        `clipping_community`, `youtube_automation_community`,
        `pirated_digital_content`
      </Accordion>

      <Accordion title="tech_and_development">
        `developer_community`, `ai_community`, `cybersecurity_community`,
        `no_code_community`, `indie_hacker_community`, `devops_community`,
        `data_science_community`, `product_community`, `open_source_community`
      </Accordion>

      <Accordion title="lifestyle_and_personal_growth">
        `dating_community`, `personal_development_community`,
        `spirituality_community`, `parenting_community`, `travel_community`,
        `networking_community`, `faith_community`, `mens_community`,
        `womens_community`, `expat_community`, `adult_community_nsfw`,
        `adult_dating_services`, `hate_violence_communities`,
        `personal_fundraising`, `political_fundraising`,
        `political_organizations`, `pornographic_content`, `registered_501c3`,
        `religious_organization`, `unregistered_charities`
      </Accordion>

      <Accordion title="video_games_and_esports">
        `gaming_community`, `game_account_selling`,
        `unauthorized_ingame_currency`
      </Accordion>

      <Accordion title="hobbies_and_lifestyle">
        `car_enthusiast_community`, `sneakerhead_community`,
        `watch_collector_community`, `wine_enthusiast_community`,
        `cigar_community`, `cooking_community`, `gardening_community`,
        `fishing_community`, `hunting_community`, `diy_maker_community`,
        `golf_community`, `collectibles_community`, `sweepstakes_raffles`,
        `event_ticket_community`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="software">
    <AccordionGroup>
      <Accordion title="trading_and_investing">
        `forex_trading_bot`, `stock_trading_platform`, `crypto_trading_bot`,
        `futures_trading_bot`, `options_flow_tool`, `portfolio_tracker`,
        `financial_modeling_software`, `accounting_software`,
        `invoicing_software`, `tax_software`, `risk_management_software`,
        `prop_trading_platform`, `backtesting_software`, `trading_indicators`,
        `market_data_feed`, `stock_research_tool`, `banking_software`,
        `lending_platform`, `insurance_software`, `bnpl_service`,
        `check_cashing_service`, `cloud_mining_schemes`, `consumer_lending`,
        `credit_repair_service`, `crypto_exchange_brokerage`,
        `crypto_trading_tools_software`, `debt_collection_agency`,
        `debt_relief_settlement`, `escrow_service`, `foreign_exchange_service`,
        `non_custodial_wallet_tools`, `payment_facilitation`,
        `prediction_market_exchange`, `stablecoin_issuance`, `token_sales_ico`,
        `tokenized_rwa`, `yield_staking_products`
      </Accordion>

      <Accordion title="ai_and_automation_software">
        `ai_outreach_tool`, `ai_chatbot_software`, `ai_writing_tool`,
        `ai_image_generator`, `ai_video_tool`, `ai_voice_tool`,
        `ai_data_analysis`, `ai_code_assistant`, `ai_meeting_assistant`,
        `workflow_automation_software`, `ai_sales_tool`, `ai_customer_support`,
        `ai_recruiting_tool`, `ai_translation_tool`, `ai_music_tool`,
        `ai_presentation_tool`, `ai_research_tool`, `ai_seo_tool`,
        `ai_social_media_tool`, `ai_phone_agent`, `ai_legal_tool`,
        `ai_healthcare_tool`, `llm_api_platform`, `ai_agent_platform`,
        `generative_ai_platform`, `celebrity_impersonation`, `deepfake_service`,
        `ai_nsfw_content_generator`
      </Accordion>

      <Accordion title="marketing_and_advertising">
        `crm_software`, `email_marketing_software`, `sms_marketing_software`,
        `seo_tool`, `landing_page_builder`, `ad_management_tool`,
        `affiliate_tracking`, `review_management`, `analytics_dashboard`,
        `lead_gen_software`, `link_in_bio_tool`, `influencer_platform`,
        `webinar_platform`, `ab_testing_tool`, `chatbot_marketing`,
        `video_sales_tool`, `proposal_software`, `competitive_intelligence`,
        `social_listening_tool`, `whatsapp_marketing_tool`,
        `click_farm_service`, `data_scraping_service`, `door_to_door_sales`,
        `inbound_teleservices`, `lead_list_sales`, `outbound_telemarketing`,
        `standalone_tipping`
      </Accordion>

      <Accordion title="e_commerce_software">
        `ecommerce_platform`, `product_research_tool`, `price_tracker`,
        `shipping_software`, `print_on_demand_software`,
        `marketplace_seller_tool`, `resale_arbitrage_tool`,
        `reseller_management_tool`, `product_review_software`,
        `returns_management`, `product_feed_management`,
        `checkout_optimization`, `wholesale_ordering`
      </Accordion>

      <Accordion title="productivity_and_business_ops">
        `project_management_software`, `team_communication`,
        `video_conferencing`, `document_collaboration`,
        `time_tracking_software`, `scheduling_software`, `hr_software`,
        `knowledge_base_software`, `form_survey_builder`, `note_taking_app`,
        `task_management`, `contract_management`, `expense_management`,
        `okr_goal_tracking`, `employee_engagement`, `onboarding_software`,
        `applicant_tracking`, `asset_management`, `facility_management`,
        `visitor_management`
      </Accordion>

      <Accordion title="tech_and_development">
        `api_management`, `hosting_platform`, `database_tool`, `devops_tool`,
        `monitoring_tool`, `testing_tool`, `code_editor`, `no_code_builder`,
        `cdn_platform`, `error_tracking`, `documentation_tool`, `webhook_tool`,
        `3d_weapon_files`, `background_check_services`,
        `document_falsification`, `fake_id_services`, `fake_reference_services`
      </Accordion>

      <Accordion title="community_and_education_software">
        `community_platform`, `event_management_software`, `webinar_software`,
        `school_management`, `newsletter_platform`, `podcast_hosting`,
        `forum_software`, `virtual_classroom`, `pirated_digital_content`,
        `primary_event_ticketing`, `ticket_marketplace`
      </Accordion>

      <Accordion title="health_and_wellness">
        `telehealth_platform`, `ehr_software`, `practice_management`,
        `mental_health_app`, `fitness_app`, `nutrition_tracking_app`,
        `wellness_app`, `patient_engagement`, `medical_billing_software`,
        `pharmacy_management`, `lab_management`, `clinical_trial_software`,
        `dental_software`, `veterinary_software`, `health_data_platform`
      </Accordion>

      <Accordion title="real_estate">
        `real_estate_crm`, `property_management_software`, `deal_analysis_tool`,
        `mls_search_tool`, `virtual_tour_software`,
        `real_estate_marketing_software`, `construction_management`,
        `home_valuation_tool`
      </Accordion>

      <Accordion title="industry_specific_software">
        `restaurant_pos`, `salon_software`, `gym_management_software`,
        `auto_shop_software`, `legal_practice_software`, `church_management`,
        `nonprofit_software`, `logistics_software`, `agriculture_software`,
        `field_service_software`, `marina_management`, `hotel_pms`,
        `childcare_management`, `cleaning_business_software`,
        `roofing_software`, `landscaping_software`, `pest_control_software`,
        `tattoo_studio_software`, `cannabis_software`, `bail_bond_services`,
        `freelance_marketplace_operator`, `private_investigation`,
        `repossession_services`
      </Accordion>

      <Accordion title="security_and_privacy_software">
        `password_manager`, `cybersecurity_software`, `identity_verification`,
        `backup_recovery`, `endpoint_protection`, `email_security`,
        `access_management`, `compliance_software`, `data_privacy_tool`,
        `hacking_tools_malware`, `stalkerware_monitoring`, `vpn_services`,
        `people_search_tool`
      </Accordion>

      <Accordion title="gaming_and_entertainment_software">
        `game_mod_tool`, `streaming_tool`, `game_server_hosting`,
        `music_software`, `video_editing_software`, `photo_editing_software`,
        `animation_software`, `audio_editing_software`,
        `screen_recording_software`, `sports_betting_tool`,
        `fantasy_sports_free_to_play`, `fantasy_sports_paid_entry`,
        `game_cheats_hacks`, `iptv_pirated_streaming`,
        `licensed_gambling_operations`, `loot_boxes_gacha`,
        `skill_contests_free_entry`, `skill_contests_paid_entry`,
        `sweepstakes_raffles`, `unlicensed_gambling`,
        `only_fans_management_software`, `pornography_platform`
      </Accordion>

      <Accordion title="communication_and_messaging_software">
        `business_phone_system`, `customer_messaging`
      </Accordion>

      <Accordion title="digital_goods_and_accounts">
        `game_account_selling`, `game_cheats_hacks`, `pirated_digital_content`,
        `unauthorized_ingame_currency`, `digital_key_reselling`,
        `streaming_account_reselling`, `subscription_account_sharing`,
        `account_generation_tool`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="telehealth">
    <AccordionGroup>
      <Accordion title="primary_and_general_care">
        `primary_care_telehealth`, `urgent_care_telehealth`,
        `pediatric_telehealth`, `geriatric_telehealth`,
        `family_medicine_telehealth`, `internal_medicine_telehealth`,
        `preventive_care_telehealth`, `licensed_online_pharmacy`,
        `telemedicine_practitioner_services`
      </Accordion>

      <Accordion title="dermatology_and_skin">
        `dermatology_telehealth`, `acne_telehealth`,
        `psoriasis_eczema_telehealth`, `skin_cancer_screening_tele`,
        `cosmetic_dermatology_tele`
      </Accordion>

      <Accordion title="mental_health_and_behavioral">
        `therapy_telehealth`, `psychiatry_telehealth`, `addiction_telehealth`,
        `couples_therapy_telehealth`, `child_psychology_telehealth`,
        `eating_disorder_telehealth`, `ptsd_trauma_telehealth`,
        `adhd_telehealth`, `anxiety_depression_telehealth`, `ocd_telehealth`,
        `grief_counseling_telehealth`, `anger_management_telehealth`,
        `family_therapy_telehealth`, `group_therapy_telehealth`,
        `licensed_psychedelic_therapy`
      </Accordion>

      <Accordion title="womens_and_mens_health">
        `womens_health_telehealth`, `mens_health_telehealth`,
        `sexual_health_telehealth`, `fertility_telehealth`,
        `hormone_therapy_telehealth`, `menopause_telehealth`,
        `prenatal_telehealth`, `postpartum_telehealth`,
        `erectile_dysfunction_tele`, `hair_loss_telehealth`,
        `birth_control_telehealth`, `sti_testing_telehealth`
      </Accordion>

      <Accordion title="dental_and_vision">
        `dental_telehealth`, `orthodontics_telehealth`, `optometry_telehealth`,
        `oral_surgery_consultation`, `vision_therapy_telehealth`
      </Accordion>

      <Accordion title="specialty_medical_care">
        `cardiology_telehealth`, `endocrinology_telehealth`,
        `neurology_telehealth`, `orthopedic_telehealth`, `allergy_telehealth`,
        `ent_telehealth`, `rheumatology_telehealth`,
        `gastroenterology_telehealth`, `infectious_disease_telehealth`,
        `pulmonology_telehealth`, `nephrology_telehealth`,
        `oncology_telehealth`, `hematology_telehealth`, `urology_telehealth`
      </Accordion>

      <Accordion title="weight_and_metabolic_health">
        `weight_management_telehealth`, `glp1_weight_loss_tele`,
        `diabetes_management_tele`, `metabolic_health_tele`,
        `bariatric_telehealth`
      </Accordion>

      <Accordion title="rehabilitation_and_therapy">
        `physical_therapy_telehealth`, `occupational_therapy_tele`,
        `speech_therapy_telehealth`, `pain_management_telehealth`,
        `cardiac_rehab_telehealth`, `pelvic_floor_telehealth`,
        `vestibular_telehealth`
      </Accordion>

      <Accordion title="sleep_and_chronic_conditions">
        `sleep_medicine_telehealth`, `chronic_disease_management`,
        `chronic_pain_telehealth`, `migraine_telehealth`,
        `asthma_copd_telehealth`
      </Accordion>

      <Accordion title="wellness_and_alternative">
        `nutrition_telehealth`, `naturopathic_telehealth`,
        `functional_medicine_telehealth`, `acupuncture_telehealth`,
        `health_coaching_telehealth`, `integrative_medicine_tele`,
        `ayurvedic_telehealth`
      </Accordion>

      <Accordion title="genetic_and_specialized">
        `genetic_counseling_telehealth`, `pharmacogenomics_tele`,
        `rare_disease_telehealth`, `second_opinion_telehealth`
      </Accordion>

      <Accordion title="veterinary">
        `vet_telehealth`, `pet_behavior_telehealth`, `exotic_pet_telehealth`,
        `equine_telehealth`, `veterinary_services`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="class_action_settlement">
    <AccordionGroup>
      <Accordion title="class_action_settlement">
        `class_action_settlement`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="events">
    <AccordionGroup>
      <Accordion title="educational_training_events">
        `mastermind_event`, `webinar_event`, `virtual_summit`, `bootcamp_event`,
        `workshop_seminar`, `hackathon`, `corporate_training_event`,
        `training_certification_event`
      </Accordion>

      <Accordion title="conference_and_expo_events">
        `convention_expo`, `conference_summit`, `industry_awards_event`,
        `product_launch_event`, `investor_demo_day`, `panel_discussion_event`,
        `pitch_competition`
      </Accordion>

      <Accordion title="social_and_networking_events">
        `meetup_event`, `dinner_event`, `alumni_event`, `community_gathering`,
        `singles_event`, `professional_happy_hour`, `women_networking_event`,
        `founders_dinner`, `industry_mixer`, `adult_community_nsfw`,
        `hate_violence_communities`, `pornographic_content`
      </Accordion>

      <Accordion title="performance_and_show_events">
        `concert_event`, `comedy_show`, `theater_performance`, `film_screening`,
        `music_festival`, `cultural_festival`, `fashion_show`, `drag_show`,
        `magic_show`, `dance_performance`, `poetry_spoken_word`,
        `art_exhibition`
      </Accordion>

      <Accordion title="social_entertainment_events">
        `party_event`, `trivia_night`, `wine_tasting_event`, `beer_festival`,
        `car_show`, `food_festival`, `fantasy_sports_free_to_play`,
        `fantasy_sports_paid_entry`, `licensed_gambling_operations`,
        `loot_boxes_gacha`, `skill_contests_free_entry`,
        `skill_contests_paid_entry`, `sweepstakes_raffles`,
        `unlicensed_gambling`
      </Accordion>

      <Accordion title="sports_and_fitness_events">
        `fitness_challenge_event`, `marathon_race`, `tournament_event`,
        `fight_event`, `yoga_retreat_event`, `outdoor_adventure_event`,
        `esports_tournament`, `obstacle_course_race`, `cycling_event`,
        `swim_meet`, `golf_tournament`, `pickleball_tournament`,
        `crossfit_competition`, `martial_arts_tournament`, `surfing_competition`
      </Accordion>

      <Accordion title="lifestyle_and_wellness_events">
        `wellness_retreat`, `spiritual_retreat`, `couples_retreat`,
        `plant_medicine_retreat`, `luxury_experience_event`, `detox_retreat`,
        `silent_retreat`, `creative_retreat`, `leadership_retreat`,
        `mens_retreat`, `womens_retreat`, `digital_detox_retreat`
      </Accordion>

      <Accordion title="charity_and_cause_events">
        `fundraiser_event`, `awareness_event`, `volunteer_event`,
        `charity_auction`, `benefit_concert`, `charity_run_walk`,
        `environmental_cleanup`, `personal_fundraising`, `registered_501c3`,
        `religious_organization`, `unregistered_charities`
      </Accordion>

      <Accordion title="family_and_community_events">
        `family_festival`, `kids_event`, `holiday_event`,
        `farmers_market_event`, `block_party`, `graduation_ceremony`,
        `memorial_event`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="newsletter">
    <AccordionGroup>
      <Accordion title="finance_and_investing">
        `stock_market_newsletter`, `crypto_newsletter`,
        `personal_finance_newsletter`, `real_estate_newsletter`,
        `fintech_newsletter`, `venture_capital_newsletter`,
        `options_trading_newsletter`, `forex_newsletter`,
        `macro_economics_newsletter`, `alternative_investing_newsletter`,
        `tax_strategy_newsletter`
      </Accordion>

      <Accordion title="business_and_entrepreneurship">
        `startup_newsletter`, `ecommerce_newsletter`, `marketing_newsletter`,
        `sales_newsletter`, `small_business_newsletter`,
        `leadership_newsletter`, `agency_newsletter`, `saas_newsletter`,
        `hr_people_newsletter`, `legal_business_newsletter`,
        `real_estate_business_newsletter`, `solopreneur_newsletter`
      </Accordion>

      <Accordion title="tech_and_ai">
        `ai_newsletter`, `tech_industry_newsletter`, `cybersecurity_newsletter`,
        `developer_newsletter`, `product_newsletter`, `devops_newsletter`,
        `open_source_newsletter`, `robotics_newsletter`,
        `climate_tech_newsletter`
      </Accordion>

      <Accordion title="health_and_wellness">
        `fitness_newsletter`, `mental_health_newsletter`,
        `longevity_newsletter`, `medical_newsletter`, `biohacking_newsletter`,
        `womens_health_newsletter`, `mens_health_newsletter`,
        `pharma_biotech_newsletter`
      </Accordion>

      <Accordion title="lifestyle_and_culture">
        `travel_newsletter`, `fashion_newsletter`, `parenting_newsletter`,
        `sports_newsletter`, `gaming_newsletter`,
        `music_entertainment_newsletter`, `book_reading_newsletter`,
        `dating_relationships_newsletter`, `home_design_newsletter`,
        `pet_newsletter`, `wine_spirits_newsletter`, `automotive_newsletter`,
        `adult_community_nsfw`, `hate_violence_communities`,
        `pornographic_content`
      </Accordion>

      <Accordion title="news_and_politics">
        `political_newsletter`, `geopolitics_newsletter`,
        `media_journalism_newsletter`, `defense_security_newsletter`,
        `legal_policy_newsletter`, `political_fundraising`,
        `political_organizations`
      </Accordion>

      <Accordion title="creative_and_education">
        `design_newsletter`, `education_newsletter`, `science_newsletter`,
        `philosophy_newsletter`, `sustainability_newsletter`,
        `architecture_newsletter`, `history_newsletter`,
        `psychology_newsletter`, `career_newsletter`
      </Accordion>

      <Accordion title="spirituality_and_personal_growth">
        `spirituality_newsletter`, `self_improvement_newsletter`,
        `productivity_newsletter`, `faith_newsletter`, `personal_fundraising`,
        `registered_501c3`, `religious_organization`, `unregistered_charities`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="brick_and_mortar">
    <AccordionGroup>
      <Accordion title="fitness_and_recreation">
        `gym_facility`, `crossfit_box`, `yoga_studio`, `pilates_studio`,
        `martial_arts_gym`, `boxing_gym`, `climbing_gym`, `dance_studio`,
        `swimming_pool`, `sports_facility`, `golf_course`, `bowling_alley`,
        `skating_rink`, `trampoline_park`, `tennis_club`, `pickleball_facility`,
        `gymnastics_center`, `spin_studio`, `barre_studio`,
        `personal_training_studio_bm`, `recovery_studio`, `indoor_soccer`,
        `batting_cage`, `shooting_range`, `archery_range`, `equestrian_center`
      </Accordion>

      <Accordion title="restaurants">
        `fine_dining`, `fast_casual_restaurant`, `steakhouse`,
        `seafood_restaurant`, `pizza_shop`, `sushi_restaurant`,
        `deli_sandwich_shop`, `bbq_restaurant`, `mexican_restaurant`,
        `italian_restaurant`, `chinese_restaurant`, `indian_restaurant`,
        `thai_restaurant`, `korean_restaurant`, `mediterranean_restaurant`,
        `vegan_vegetarian_restaurant`, `brunch_restaurant`, `ramen_noodle_shop`,
        `poke_bowl_shop`, `ethnic_restaurant`
      </Accordion>

      <Accordion title="cafes_and_quick_service">
        `coffee_shop_cafe`, `bakery`, `juice_smoothie_bar`, `ice_cream_shop`,
        `donut_shop`, `bubble_tea_shop`, `food_truck`, `fast_food`,
        `ghost_kitchen`, `food_hall_vendor`, `catering_kitchen`, `butcher_shop`,
        `cheese_shop`, `farmers_market_stall`
      </Accordion>

      <Accordion title="bars_and_breweries">
        `bar_lounge`, `brewery_taproom`, `winery_tasting`, `wine_bar`,
        `cocktail_bar`, `sports_bar`, `hookah_lounge`, `distillery`
      </Accordion>

      <Accordion title="agriculture_and_farming">
        `commercial_farming`, `livestock_ranching`,
        `hydroponic_vertical_farming`, `forestry_logging`,
        `aquaculture_fisheries`, `vineyard_winery_production`,
        `cannabis_cultivation`, `hemp_farming`, `grain_production`,
        `agricultural_cooperative`, `fertilizer_pesticide_sales`,
        `farm_equipment_sales`
      </Accordion>

      <Accordion title="retail">
        `boutique_store`, `clothing_store`, `shoe_store`, `jewelry_store`,
        `electronics_store`, `bookstore`, `pet_store`, `toy_store`,
        `sporting_goods_store`, `thrift_store`, `smoke_shop`,
        `cannabis_dispensary`, `convenience_store`, `grocery_store`,
        `liquor_store`, `florist`, `gift_shop`, `furniture_store`,
        `home_improvement_store`, `art_gallery_retail`,
        `music_instrument_store`, `outdoor_recreation_store`,
        `phone_repair_store`, `watch_store`, `bridal_shop`, `maternity_store`,
        `kids_store`, `sneaker_store`, `vintage_store`, `comic_book_store`,
        `record_store`, `craft_supply_store`, `fabric_store`,
        `health_food_store`, `vitamin_supplement_store`, `optical_store`,
        `mattress_store`, `appliance_store`, `kitchen_bath_store`,
        `tile_flooring_store`, `paint_store`, `garden_center`, `gun_store`,
        `pawn_shop`, `dollar_store`
      </Accordion>

      <Accordion title="beauty_and_wellness">
        `hair_salon`, `nail_salon`, `day_spa`, `med_spa`, `massage_studio`,
        `tattoo_parlor`, `tanning_salon`, `beauty_supply_store`,
        `lash_brow_studio`, `waxing_studio`, `sauna_bathhouse`,
        `cryotherapy_studio`, `float_sensory_studio`, `iv_therapy_lounge`,
        `teeth_whitening_studio`, `microblading_studio`, `spray_tan_studio`,
        `blowout_bar`, `mens_barbershop`, `kids_salon`
      </Accordion>

      <Accordion title="healthcare">
        `medical_office`, `dental_office`, `chiropractic_office`,
        `physical_therapy_clinic`, `optometry_office`, `dermatology_clinic`,
        `urgent_care_clinic`, `pharmacy`, `veterinary_clinic`,
        `mental_health_clinic`, `fertility_clinic`, `acupuncture_clinic`,
        `hearing_aid_center`, `orthopedic_clinic`, `pediatric_clinic`,
        `cosmetic_surgery_center`, `allergy_clinic`, `pain_management_clinic`,
        `dialysis_center`, `imaging_center`, `lab_testing_center`,
        `sleep_clinic`, `weight_loss_clinic`, `hormone_therapy_clinic`,
        `addiction_treatment_center`, `rehabilitation_center`,
        `occupational_therapy_clinic`, `speech_therapy_clinic`,
        `wound_care_center`
      </Accordion>

      <Accordion title="funeral_and_death_care">
        `funeral_home_mortuary`, `crematory_service`, `cemetery_memorial_park`,
        `casket_urn_retailer`, `pet_cremation_service`, `biohazard_cleanup`,
        `estate_liquidation`
      </Accordion>

      <Accordion title="automotive">
        `auto_repair_service`, `auto_body_shop`, `car_dealership`, `car_wash`,
        `tire_shop`, `oil_change_shop`, `auto_parts_store`, `motorcycle_shop`,
        `ev_charging_station`, `transmission_shop`, `muffler_exhaust_shop`,
        `auto_glass_shop`, `auto_upholstery_shop`, `car_audio_shop`,
        `smog_emissions_shop`, `truck_repair_shop`, `rv_repair_shop`,
        `boat_repair_shop`, `used_car_lot`, `auto_auction`
      </Accordion>

      <Accordion title="hospitality_and_lodging">
        `hotel`, `motel`, `boutique_hotel`, `bed_and_breakfast`, `hostel`,
        `resort`, `campground_rv`, `vacation_rental_property`, `extended_stay`,
        `glamping_site`, `cabin_rental`, `eco_lodge`, `retreat_center`
      </Accordion>

      <Accordion title="education_and_childcare">
        `tutoring_center`, `daycare_center`, `preschool`, `learning_center`,
        `music_school`, `art_school`, `driving_school`, `language_school`,
        `trade_school`, `coding_bootcamp_location`, `montessori_school`,
        `after_school_program`, `swim_school`, `cooking_school`,
        `test_prep_center`, `special_needs_center`, `adult_education_center`,
        `flight_school`, `cosmetology_school`
      </Accordion>

      <Accordion title="entertainment_and_leisure">
        `movie_theater`, `escape_room`, `arcade`, `mini_golf`, `laser_tag`,
        `go_kart`, `amusement_park`, `museum`, `zoo_aquarium`, `theater_venue`,
        `nightclub`, `karaoke_bar`, `comedy_club`, `live_music_venue`,
        `axe_throwing`, `virtual_reality_arcade`, `board_game_cafe`, `cat_cafe`,
        `haunted_house`, `water_park`, `indoor_playground`, `trampoline_park`,
        `concert_venue`, `drive_in_theater`, `billiards_hall`, `dart_bar`,
        `batting_cage`, `indoor_skydiving`
      </Accordion>

      <Accordion title="professional_services_storefront">
        `law_office`, `real_estate_office`, `insurance_office`,
        `accounting_office`, `bank_credit_union`, `printing_shop`,
        `shipping_center`, `dry_cleaner`, `laundromat`, `storage_facility`,
        `coworking_space`, `check_cashing`, `title_company`,
        `travel_agency_storefront`, `staffing_office`,
        `financial_advisor_office`, `immigration_office`, `bail_bonds_office`
      </Accordion>

      <Accordion title="pet_services">
        `pet_grooming`, `dog_daycare`, `pet_boarding`, `dog_training_facility`,
        `pet_spa`, `aquatic_pet_store`, `pet_bakery`, `pet_photography_studio`
      </Accordion>

      <Accordion title="home_and_trade_storefronts">
        `plumbing_showroom`, `hvac_showroom`, `solar_showroom`,
        `kitchen_design_showroom`, `bath_design_showroom`,
        `window_door_showroom`, `pool_spa_showroom`, `fireplace_showroom`,
        `countertop_showroom`
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="other">
    <AccordionGroup>
      <Accordion title="nonprofit_and_charity">
        `nonprofit_organization`, `charity_foundation`,
        `religious_organization`, `political_campaign`,
        `community_organization`, `environmental_nonprofit`,
        `education_nonprofit`, `health_nonprofit`, `animal_welfare_nonprofit`,
        `arts_culture_nonprofit`, `social_justice_nonprofit`,
        `veterans_nonprofit`, `youth_nonprofit`, `disaster_relief_nonprofit`,
        `food_bank`, `housing_nonprofit`, `personal_fundraising`,
        `registered_501c3`, `unregistered_charities`
      </Accordion>

      <Accordion title="government_and_public">
        `government_agency`, `public_utility`, `public_library`,
        `public_school`, `municipal_service`, `military_installation`,
        `embassy_consulate`, `political_fundraising`, `political_organizations`
      </Accordion>

      <Accordion title="miscellaneous">
        `niche_service`, `niche_product`, `hybrid_business`, `other_general`,
        `holding_company`, `family_office`, `cooperative`, `social_enterprise`,
        `incubator_accelerator`, `coworking_community`, `media_company`,
        `research_lab`
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>


# Create Account
Source: https://docs.whop.com/api-reference/beta/accounts/create-account

/openapi/api-v1-native.json post /accounts
Creates an account. User tokens create business accounts; Account API keys create connected accounts. Tax fields (`tax_remitted_by`, `tax_type`, `product_tax_code_id`, `business_address`, `tax_identifiers`) are configured with Update Account, not at creation.



# Form Company
Source: https://docs.whop.com/api-reference/beta/accounts/form-company

/openapi/api-v1-native.json post /accounts/{account_id}/form_company
Starts an LLC or C-Corp formation for a business account. Defaults to an LLC; set `entity_type` to `c_corp` to form a C-Corp, which additionally requires `share_structure` and officer `roles` on every founder. On submission, the application is validated and the response returns a hosted checkout URL. Once paid, the filing is submitted. Track progress through the account's [`company_formation`](/api-reference/beta/accounts/retrieve-account) field on Retrieve Account.



# List Account Reserves
Source: https://docs.whop.com/api-reference/beta/accounts/list-account-reserves

/openapi/api-v1-native.json get /accounts/{account_id}/reserves
Lists what the account's held balance is made of, one entry per currency: the total held, why each part is held, and the days it unlocks.



# List Accounts
Source: https://docs.whop.com/api-reference/beta/accounts/list-accounts

/openapi/api-v1-native.json get /accounts
Lists accounts visible to the credential. User tokens return the user's business accounts; Account API keys return the requesting account and its connected accounts. Pass `parent_account_id` to return only that parent account's connected accounts.



# Retrieve Account
Source: https://docs.whop.com/api-reference/beta/accounts/retrieve-account

/openapi/api-v1-native.json get /accounts/{account_id}
Retrieves a single account by ID or public route when it is visible to the credential, including its crypto wallet.



# Retrieve Account Preferences
Source: https://docs.whop.com/api-reference/beta/accounts/retrieve-account-preferences

/openapi/api-v1-native.json get /accounts/{account_id}/preferences
Retrieves the account's preferences: a singleton settings document keyed by preference name.



# Retrieve Requesting Account
Source: https://docs.whop.com/api-reference/beta/accounts/retrieve-requesting-account

/openapi/api-v1-native.json get /accounts/me
Retrieves the account associated with the current Account API key.



# Transfer Account Ownership
Source: https://docs.whop.com/api-reference/beta/accounts/transfer-account-ownership

/openapi/api-v1-native.json post /accounts/{account_id}/transfer_ownership
Transfers ownership of the account to another user, identified by user ID or email address. If the recipient already holds the owner role, ownership moves immediately; otherwise they get an invite and ownership moves when they accept.



# Update Account
Source: https://docs.whop.com/api-reference/beta/accounts/update-account

/openapi/api-v1-native.json patch /accounts/{account_id}
Updates an account. User tokens can update business accounts; Account API keys can update connected accounts.



# Update Account Preferences
Source: https://docs.whop.com/api-reference/beta/accounts/update-account-preferences

/openapi/api-v1-native.json patch /accounts/{account_id}/preferences
Updates the account's preferences. Each top-level key present in the body is replaced as a whole; omitted keys are left untouched. `ads_triple_whale_integration` takes the Data-In API key to connect with, or `null` to disconnect. `ads_payment_methods` always requires a `primary` entry. `backup` is optional and any pairing is allowed — two cards, `card`+`platform_balance`, or a single method — so a card-only advertiser can fund ads without a platform balance. The `primary` and `backup` must be different sources. A `platform_balance` entry may omit `id` to use the account's default Whop balance. Configuring a `card` requires a user token; account API keys can set up platform-balance billing only.



# Overview
Source: https://docs.whop.com/api-reference/beta/overview

What the API does, how requests work, and a map of every resource.

The Whop API is how you move money programmatically. Accept payments with checkout links, hold balances, send payouts, issue cards, transfer funds between accounts, and manage the products and plans you sell. All of it from your server with one API key.

## Make a request

The base URL is `https://api.whop.com/api/v1`. Authenticate every request with a Bearer API key:

```bash theme={null}
curl https://api.whop.com/api/v1/accounts/me \
  -H "Authorization: Bearer $WHOP_API_KEY"
```

```json theme={null}
{
	"id": "biz_XXXXXXXX",
	"title": "Acme Studio",
	"route": "acme-studio",
	"status": "approved"
}
```

New here? The [Quickstart](/api-reference/beta/quickstart) gets you from [creating a key](https://whop.com/dashboard/developer) to a live checkout link in about five minutes.

## How the API works

### Authentication

[Create an API key here](https://whop.com/dashboard/developer) under **Account API Keys**. Keys are scoped to an account and carry the permissions you grant them. Keep keys on your server, never in browser code, mobile apps, or public repos.

### Versioning

The API is versioned by date. Send an `Api-Version-Date` header (like `2026-07-01`) to pin the request and response shapes you built against; later changes won't break a pinned caller. When you omit the header, requests use the original `2025-01-01` shapes, and generated SDKs always send the latest version they were built against. See [Versioning](/developer/api/versioning).

### Pagination

List endpoints return a `data` array plus a `page_info` object. Pass `first` to set the page size and `after` with the previous response's `page_info.end_cursor` to fetch the next page. `page_info.has_next_page` tells you when to stop.

### Errors

Failed requests return a conventional HTTP status (`400`, `401`, `403`, `404`) and a body with a single `error` object: `type` is a machine-readable code and `message` explains what went wrong.

```json theme={null}
{
	"error": {
		"type": "invalid_parameters",
		"message": "initial_price must be greater than 0"
	}
}
```

## Resources

### Core Resources

The accounts and people everything else hangs off.

| Resource                                                        | What it's for                                                         |
| --------------------------------------------------------------- | --------------------------------------------------------------------- |
| [Accounts](/api-reference/beta/accounts/account)                | A business on Whop: profile, wallet, capabilities, settings.          |
| [Users](/api-reference/beta/users/user)                         | A person on Whop: profile and connected identities.                   |
| [Team Members](/api-reference/beta/team-members/team-member)    | An account's team members and the roles that scope their access.      |
| [Members](/api-reference/beta/members/member)                   | One buyer's relationship with an account, across all their purchases. |
| [Webhooks](/api-reference/beta/webhooks/list-webhooks)          | Event notifications pushed to your server as things happen.           |
| [Stats](/api-reference/beta/stats/stats)                        | Aggregated financial, audience, and traffic reporting.                |
| [Verifications](/api-reference/beta/verifications/verification) | Legal identity required before payouts and card issuing.              |
| [Exports](/api-reference/beta/exports/list-exports)             | Asynchronous CSV dumps of an account's dashboard data.                |

### Notifications

What users get told about, and how they tune it.

| Resource                                                              | What it's for                                                                             |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [Notifications](/api-reference/beta/notifications/list-notifications) | The user's notification feed: unread badges, mark-read, app sends, and the topic catalog. |

### Money

Balances and every way funds move in or out.

| Resource                                                                                            | What it's for                                                              |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Payments](/api-reference/beta/payments/update-payment-return-url)                                  | A charge against a buyer, and the step they still owe.                     |
| [Setup Intents](/api-reference/beta/setup-intents/update-setup-return-url)                          | Saving a buyer's payment method without charging it.                       |
| [Ledgers](/api-reference/beta/ledgers/ledger-activity)                                              | The activity feed behind an account or user's balance.                     |
| [Payouts](/api-reference/beta/payouts/payout)                                                       | Send money from a balance to a bank or wallet.                             |
| [Cards](/api-reference/beta/cards/card)                                                             | Issue cards that spend from a balance.                                     |
| [Transfers](/api-reference/beta/transfers/transfer)                                                 | Move funds between Whop accounts and users.                                |
| [Disputes](/api-reference/beta/disputes/list-disputes)                                              | Chargebacks filed against an account, with evidence and outcomes.          |
| [Deposits](/api-reference/beta/deposits/deposit)                                                    | Add funds to a balance.                                                    |
| [Swaps](/api-reference/beta/swaps/swap)                                                             | Convert a balance between currencies.                                      |
| [Resolution Center Cases](/api-reference/beta/resolution-center-cases/list-resolution-center-cases) | File or respond to a case against a payment, as the buyer or the merchant. |

### Commerce

Sell products and get paid.

| Resource                                                                                      | What it's for                                                               |
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Products](/api-reference/beta/products/product)                                              | The things you sell. Each owns plans and a store page.                      |
| [Plans](/api-reference/beta/plans/plan)                                                       | Pricing for a product: one-time, recurring, trials, stock.                  |
| [Promo Codes](/api-reference/beta/promo-codes/list-promo-codes)                               | Discounts that creators configure for checkout.                             |
| [Memberships](/api-reference/beta/memberships/membership)                                     | A customer's purchase of a plan, from checkout through cancellation.        |
| [Checkout Configurations](/api-reference/beta/checkout-configurations/checkout-configuration) | Turn a plan into a shareable, prefilled checkout link.                      |
| [Payment Method Domains](/api-reference/beta/payment-method-domains/payment-method-domain)    | Domains verified to show wallet payment methods like Apple Pay at checkout. |
| [Shipments](/api-reference/beta/shipments/list-shipments)                                     | Track the delivery of an order by its carrier tracking number.              |

### Partners

Refer users and businesses to Whop and track what you earn.

| Resource                                         | What it's for                                                               |
| ------------------------------------------------ | --------------------------------------------------------------------------- |
| [Partners](/api-reference/beta/partners/partner) | The users and businesses you referred to Whop, and what you earn from them. |

### Workforce

Post paid tasks and pay people for completed work.

| Resource                                                                             | What it's for                                              |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| [Bounties](/api-reference/beta/bounties/bounty)                                      | Paid tasks with reviewed submissions and escrowed rewards. |
| [Bounty Submissions](/api-reference/beta/bounty-submissions/list-bounty-submissions) | Work submitted to a bounty, from attempt to payout.        |

### Tracking

Who visits and what converts, captured by the pixel.

| Resource                                                                                | What it's for                                                                        |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [People](/api-reference/beta/people/person)                                             | Visitors and customers of an account, with identity, purchase, and traffic profiles. |
| [Events](/api-reference/beta/events/event)                                              | Conversion and engagement events tracked for attribution.                            |
| [Recommended Actions](/api-reference/beta/recommended-actions/list-recommended-actions) | Suggested next-step action chains for an account.                                    |

### Ads

Run and measure ad campaigns from your integration.

| Resource                                                     | What it's for                                         |
| ------------------------------------------------------------ | ----------------------------------------------------- |
| [Ads](/api-reference/beta/ads/ad)                            | The creative: copy, assets, and destination URL.      |
| [Ad Campaigns](/api-reference/beta/ad-campaigns/ad-campaign) | Platform, objective, and budget for a set of ads.     |
| [Ad Groups](/api-reference/beta/ad-groups/ad-group)          | Audience, placements, and schedule within a campaign. |
| [Audiences](/api-reference/beta/audiences/audience)          | Reusable targeting lists for ad groups.               |

### Media

Generate media assets from your integration.

| Resource                                 | What it's for                                                                       |
| ---------------------------------------- | ----------------------------------------------------------------------------------- |
| [Media](/api-reference/beta/media/media) | AI-generated assets, billed from a balance, attachable wherever files are accepted. |

### Identity

Accounts connected from other platforms.

| Resource                                                              | What it's for                                           |
| --------------------------------------------------------------------- | ------------------------------------------------------- |
| [Social Accounts](/api-reference/beta/social-accounts/social-account) | Connected Facebook and Instagram accounts that run ads. |

### Developer

Build, host, and observe apps on the Whop platform.

| Resource                                                  | What it's for                                                  |
| --------------------------------------------------------- | -------------------------------------------------------------- |
| [Apps](/api-reference/beta/apps/app)                      | Apps you build on Whop: metadata, hosted builds, runtime logs. |
| [App Builds](/api-reference/beta/app-builds/app-build)    | Versioned build artifacts deployed to an app's platforms.      |
| [API Keys](/api-reference/beta/api-keys/api-key)          | Programmatic credentials for an account or app.                |
| [Permissions](/api-reference/beta/permissions/permission) | What your credential is allowed to do on a resource.           |


# Quickstart
Source: https://docs.whop.com/api-reference/beta/quickstart

Make your first call in about a minute, then create a checkout link that takes real payments.

## Try it

<Steps>
  <Step title="Grab an API key">
    <Card title="Create an API key" icon="key" href="https://whop.com/dashboard/developer">
      Opens your dashboard. Under **Account API Keys**, click **Create** and copy the key.
    </Card>

    The Admin role is fine for poking around. Narrow it down before production.
  </Step>

  <Step title="Call the API">
    <CodeGroup>
      ```bash Request theme={null}
      curl https://api.whop.com/api/v1/accounts/me \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```

      ```json Response theme={null}
      {
      	"id": "biz_XXXXXXXX",
      	"title": "Acme Studio",
      	"route": "acme-studio",
      	"status": "approved"
      }
      ```
    </CodeGroup>

    <Check>
      That's your account. The key works.
    </Check>

    Not a terminal person? Every endpoint page has a playground: open [Retrieve Requesting Account](/api-reference/beta/accounts/retrieve-requesting-account), paste your key, hit **Send**.
  </Step>
</Steps>

## Build it

Install the SDK, check your key, then create a checkout link.

<Steps>
  <Step title="Install the SDK">
    <CodeGroup>
      ```bash TypeScript theme={null}
      pnpm add @whop/sdk
      ```

      ```bash Python theme={null}
      pip install whop-sdk
      ```

      ```bash Ruby theme={null}
      gem install whop_sdk
      ```
    </CodeGroup>

    Store your key as `WHOP_API_KEY` on your server. Don't put it in browser code, mobile apps, or public repos.

    ```bash theme={null}
    WHOP_API_KEY=whop_xxxxxxxxxxxxxxxxx
    ```
  </Step>

  <Step title="Verify your key">
    If this prints an ID starting with `biz_`, you're set.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import Whop from "@whop/sdk";

      const client = new Whop({ apiKey: process.env.WHOP_API_KEY });

      const account = await client.accounts.me();

      console.log(account.id);
      ```

      ```python Python theme={null}
      import os
      from whop_sdk import Whop

      client = Whop(api_key=os.environ["WHOP_API_KEY"])

      account = client.accounts.me()

      print(account.id)
      ```

      ```ruby Ruby theme={null}
      require "whop_sdk"

      whop = WhopSDK::Client.new(api_key: ENV.fetch("WHOP_API_KEY"))

      account = whop.accounts.me

      puts account.id
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a checkout link">
    One call creates a plan and returns a `purchase_url`, a live checkout page anyone can pay you at. Open it in your browser.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const checkout = await client.checkoutConfigurations.create({
      	plan: {
      		title: "Starter",
      		plan_type: "one_time",
      		initial_price: 10.0,
      		currency: "usd",
      	},
      });

      console.log(checkout.purchase_url);
      ```

      ```python Python theme={null}
      checkout = client.checkout_configurations.create(
          plan={
              "title": "Starter",
              "plan_type": "one_time",
              "initial_price": 10.0,
              "currency": "usd",
          },
      )

      print(checkout.purchase_url)
      ```

      ```ruby Ruby theme={null}
      checkout = whop.checkout_configurations.create(
        plan: {
          title: "Starter",
          plan_type: "one_time",
          initial_price: 10.0,
          currency: "usd",
        },
      )

      puts checkout.purchase_url
      ```
    </CodeGroup>

    The link is real: if someone checks out, they get charged and your balance goes up. Already have a plan? Pass `plan_id` instead of the inline `plan` (you can't send both). [Create Checkout Configuration](/api-reference/beta/checkout-configurations/create-a-checkout-configuration) has every option, including recurring pricing, trials, and redirect URLs.
  </Step>
</Steps>

## Pin your API version

The API is versioned by date. SDKs handle this for you. If you're calling the API directly, send the header so future changes don't break you:

```bash theme={null}
curl https://api.whop.com/api/v1/accounts/me \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-07-01"
```

See [Versioning](/developer/api/versioning) for how dated versions work.

## Next steps

<CardGroup>
  <Card title="Explore every resource" icon="map" href="/api-reference/beta/overview">
    The full map: commerce, money movement, accounts, and ads.
  </Card>

  <Card title="Send a payout" icon="money-bill-transfer" href="/api-reference/beta/payouts/payout">
    Pay out your balance to a bank or wallet.
  </Card>

  <Card title="Watch money move" icon="wave-pulse" href="/api-reference/beta/ledgers/ledger-activity">
    The ledger activity feed behind every balance change.
  </Card>

  <Card title="Handle webhooks" icon="webhook" href="/developer/guides/webhooks">
    React to payments and memberships as they happen.
  </Card>
</CardGroup>


# Team Member
Source: https://docs.whop.com/api-reference/beta/team-members/team-member



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.

## Endpoints

| Endpoint                                                                      | Request                                    |
| ----------------------------------------------------------------------------- | ------------------------------------------ |
| [List Team Members](/api-reference/beta/team-members/list-team-members)       | <Badge>GET</Badge> `/team_members`         |
| [Create Team Member](/api-reference/beta/team-members/create-team-member)     | <Badge>POST</Badge> `/team_members`        |
| [Retrieve Team Member](/api-reference/beta/team-members/retrieve-team-member) | <Badge>GET</Badge> `/team_members/{id}`    |
| [Update Team Member](/api-reference/beta/team-members/update-team-member)     | <Badge>PATCH</Badge> `/team_members/{id}`  |
| [Delete Team Member](/api-reference/beta/team-members/delete-team-member)     | <Badge>DELETE</Badge> `/team_members/{id}` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Team member ID — `ausr_` for accepted members, `ausri_` for pending invites.
    </ResponseField>

    <ResponseField name="account_id" type="string">
      The account this membership belongs to, prefixed `biz_`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the member joined or the invite was sent, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="email" type="string | null">
      The member's email address. For accepted members, `null` unless the caller
      holds the email read scope; for invites, the invited address.
    </ResponseField>

    <ResponseField name="is_agent" type="boolean">
      Whether this member is an agent (app-controlled account) rather than a human
      team member. Always `false` for invites.
    </ResponseField>

    <ResponseField name="role" type="string">
      The member's role on the account. `custom` means a bespoke dashboard-managed role; the API can read but not grant it.

      Available options: `owner`, `admin`, `sales_manager`, `moderator`, `advertiser`, `app_manager`, `support`, `manager`, `custom`
    </ResponseField>

    <ResponseField name="status" type="string">
      `joined` for accepted members, `pending` while the invite is pending.

      Available options: `joined`, `pending`
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the membership was last updated, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="user" type="object | null">
      The user behind this team membership. `null` for an invite sent to an email with no Whop account yet.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          User ID, prefixed `user_`.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          Display name.
        </ResponseField>

        <ResponseField name="profile_picture" type="object">
          Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture.

          <Accordion title="Properties">
            <ResponseField name="url" type="string">
              Avatar image URL. Always present — a generated placeholder when the user set no picture.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="username" type="string">
          Public username.
        </ResponseField>
      </Accordion>
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json TeamMember theme={null}
      {
      	"id": "ausr_xxxxxxxxxxxxx",
      	"status": "joined",
      	"role": "admin",
      	"is_agent": false,
      	"account_id": "biz_xxxxxxxxxxxxx",
      	"email": "jane@example.com",
      	"created_at": "2026-07-01T00:00:00.000Z",
      	"updated_at": "2026-07-01T00:00:00.000Z",
      	"user": {
      		"id": "user_xxxxxxxxxxxx",
      		"name": "Jane Doe",
      		"profile_picture": {
      			"url": "https://cdn.whop.com/user.png"
      		},
      		"username": "janedoe"
      	}
      }
      ```
    </div>
  </Column>
</Columns>


# Authorize an App
Source: https://docs.whop.com/api-reference/beta/users/authorize-an-app

/openapi/api-v1-native.json post /users/me/oauth_grants
Completes the OAuth authorization step for the authenticated user: records their consent for the scopes an app asked for and mints the authorization code to hand back to it. Returns the grant, plus a `redirect_url` carrying that code — the one and only time it is returned. Exchange the code at `POST /oauth/token` with the verifier for `code_challenge`. Requires a user session, because consent has to come from the account holder: an API key or an OAuth token is refused, so an app can never authorize itself. Send an `Idempotency-Key` to make a retry safe — a replay returns the original `redirect_url` and its code rather than issuing a second one.



# Check User Access
Source: https://docs.whop.com/api-reference/beta/users/check-user-access

/openapi/api-v1-native.json get /users/{id}/access/{resource_id}
Checks whether a user has access to an account, product, or experience the caller can reach.



# Create Challenge
Source: https://docs.whop.com/api-reference/beta/users/create-challenge

/openapi/api-v1-native.json post /users/me/passkeys/challenge
Mints the challenge a browser needs to run a WebAuthn ceremony against the authenticated user's own passkeys. A `registration` challenge enrolls a new passkey; a `deletion` challenge is bound to the one passkey named by `passkey_id` and proves the user still holds it. Challenges are single-use and expire 5 minutes after they are issued, so send a fresh `Idempotency-Key` per ceremony — a replayed key returns the original challenge, which may already have expired. Requires a user session.



# Delete
Source: https://docs.whop.com/api-reference/beta/users/delete

/openapi/api-v1-native.json delete /users/me/passkeys/{id}
Deletes one of the authenticated user's own passkeys. The request body carries a WebAuthn assertion from the passkey being deleted, so possession of the credential is proven before it is removed: mint a `deletion` challenge for it first, run the ceremony with that passkey, and send the result here. Deleting the user's last passkey is allowed — their other step-up factors remain. Requires a user session.



# List
Source: https://docs.whop.com/api-reference/beta/users/list

/openapi/api-v1-native.json get /users/me/passkeys
Lists the authenticated user's own passkeys, newest first. The list is always the caller's own; there is no parameter for reading another user's passkeys. Requires a user session: an API key or an OAuth token is refused, because a passkey confirms the account holder before a sensitive action and no app may enumerate one.



# List Experiences
Source: https://docs.whop.com/api-reference/beta/users/list-experiences

/openapi/api-v1-native.json get /users/me/preferences/notifications/experiences
Lists the authenticated user's per-experience notification levels. Experiences the user never set a level for are omitted — their effective level is `all`.



# List OAuth Grants
Source: https://docs.whop.com/api-reference/beta/users/list-oauth-grants

/openapi/api-v1-native.json get /users/me/oauth_grants
Lists the authenticated user's own OAuth grants — one per app they have authorized, per account they authorized it for. The list is always the caller's own; there is no parameter for reading another user's grants. Requires a user session: an API key or an OAuth token is refused, so an app can never enumerate the other apps a user has authorized.



# List Recommended Actions
Source: https://docs.whop.com/api-reference/beta/users/list-recommended-actions

/openapi/api-v1-native.json get /users/{id}/recommend_actions
Lists the recommended actions computed for the user: personal suggestions (e.g. start a business or become an affiliate) pooled with the highest-impact actions across the accounts the user owns. Business actions are tagged with their `account_id`/`account_name`; personal actions leave those `null`. Self-only: `id` must be `me` or the authenticated user's own tag/username.



# List Topics
Source: https://docs.whop.com/api-reference/beta/users/list-topics

/openapi/api-v1-native.json get /users/me/preferences/notifications/topics
Lists the authenticated user's topic-scoped notification preferences, plus user-agnostic platform defaults. Each filter matches preferences scoped to its value or not narrowed on that dimension. Per-experience levels are listed separately, by `GET /users/me/preferences/notifications/experiences`.



# List Users
Source: https://docs.whop.com/api-reference/beta/users/list-users

/openapi/api-v1-native.json get /users
Search for users by name or username, ranked by social proximity to the authenticated user. Returns the user's most recently followed users when no query is given.



# Register
Source: https://docs.whop.com/api-reference/beta/users/register

/openapi/api-v1-native.json post /users/me/passkeys
Registers a passkey for the authenticated user from the attestation a browser produced for a `registration` challenge. Mint that challenge first with `POST /users/me/passkeys/challenge`; it is single-use and expires 5 minutes after it is issued. Requires a user session.



# Retrieve
Source: https://docs.whop.com/api-reference/beta/users/retrieve

/openapi/api-v1-native.json get /users/me/preferences
Retrieves the authenticated user's settings document. Addressed only as `me` — the document always belongs to the session user.



# Retrieve Current User
Source: https://docs.whop.com/api-reference/beta/users/retrieve-current-user

/openapi/api-v1-native.json get /users/me
Retrieves the authenticated user — the self view of the user object. Same shape as `GET /users/{id}`, with the self-only fields populated: `email` (email-read scope), `staff` (Whop staff only, staff-read scope), `balance` and `earnings_usd` (balance-read scope), the opt-in `balance_history`, and every linked social account.



# Retrieve User
Source: https://docs.whop.com/api-reference/beta/users/retrieve-user

/openapi/api-v1-native.json get /users/{id}
Retrieves a user's public profile by user_ tag or username, including linked social accounts — reading your own profile returns every linked account, other profiles only what is public on Whop (the primary Discord and the X account). Self-only fields (`email`, `staff`, `balance`) are always `null` here; use `GET /users/me` to read them.



# Set
Source: https://docs.whop.com/api-reference/beta/users/set

/openapi/api-v1-native.json patch /users/me/preferences/notifications
Sets the authenticated user's notification preferences. Each preference is addressed by `scope`, not by id, so a scope read back from either list endpoint can be sent straight here.

A scope naming an experience with no topic sets that experience's level, and accepts all three levels. Any other scope sets a topic override, which is binary — `all` or `nothing` — and requires a `channel`.

`level: null` clears the preference. Preferences are stored as overrides, so clearing one means the scope inherits its default again rather than being switched off.

The batch is applied in one transaction: if any entry is rejected, none are written. Experience levels are applied before topic overrides, because setting a level replaces every topic preference for that experience — so an override sent alongside a level wins. The response reports what each scope now resolves to, in the order the entries were sent.



# Update
Source: https://docs.whop.com/api-reference/beta/users/update

/openapi/api-v1-native.json patch /users/me/preferences
Updates the authenticated user's settings document. Replaces the top-level keys it is given and leaves the rest untouched.



# Update Current User
Source: https://docs.whop.com/api-reference/beta/users/update-current-user

/openapi/api-v1-native.json patch /users/me
Updates the authenticated user's global profile, or their profile override for an account when account_id is given. Not available to API keys.



# Update User
Source: https://docs.whop.com/api-reference/beta/users/update-user

/openapi/api-v1-native.json patch /users/{id}
Updates a user. A user token updates their own global profile; an API key updates the user's account-specific profile override (account_id required).



# User
Source: https://docs.whop.com/api-reference/beta/users/user



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.

## Endpoints

| Endpoint                                                                       | Request                                                              |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| [List Users](/api-reference/beta/users/list-users)                             | <Badge>GET</Badge> `/users`                                          |
| [Retrieve User](/api-reference/beta/users/retrieve-user)                       | <Badge>GET</Badge> `/users/{id}`                                     |
| [Update User](/api-reference/beta/users/update-user)                           | <Badge>PATCH</Badge> `/users/{id}`                                   |
| [Check User Access](/api-reference/beta/users/check-user-access)               | <Badge>GET</Badge> `/users/{id}/access/{resource_id}`                |
| [List Recommended Actions](/api-reference/beta/users/list-recommended-actions) | <Badge>GET</Badge> `/users/{id}/recommend_actions`                   |
| [Retrieve Current User](/api-reference/beta/users/retrieve-current-user)       | <Badge>GET</Badge> `/users/me`                                       |
| [Update Current User](/api-reference/beta/users/update-current-user)           | <Badge>PATCH</Badge> `/users/me`                                     |
| [List OAuth Grants](/api-reference/beta/users/list-oauth-grants)               | <Badge>GET</Badge> `/users/me/oauth_grants`                          |
| [Authorize an App](/api-reference/beta/users/authorize-an-app)                 | <Badge>POST</Badge> `/users/me/oauth_grants`                         |
| [List](/api-reference/beta/users/list)                                         | <Badge>GET</Badge> `/users/me/passkeys`                              |
| [Register](/api-reference/beta/users/register)                                 | <Badge>POST</Badge> `/users/me/passkeys`                             |
| [Delete](/api-reference/beta/users/delete)                                     | <Badge>DELETE</Badge> `/users/me/passkeys/{id}`                      |
| [Create Challenge](/api-reference/beta/users/create-challenge)                 | <Badge>POST</Badge> `/users/me/passkeys/challenge`                   |
| [Retrieve](/api-reference/beta/users/retrieve)                                 | <Badge>GET</Badge> `/users/me/preferences`                           |
| [Update](/api-reference/beta/users/update)                                     | <Badge>PATCH</Badge> `/users/me/preferences`                         |
| [Set](/api-reference/beta/users/set)                                           | <Badge>PATCH</Badge> `/users/me/preferences/notifications`           |
| [List Experiences](/api-reference/beta/users/list-experiences)                 | <Badge>GET</Badge> `/users/me/preferences/notifications/experiences` |
| [List Topics](/api-reference/beta/users/list-topics)                           | <Badge>GET</Badge> `/users/me/preferences/notifications/topics`      |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      User ID, prefixed `user_`.
    </ResponseField>

    <ResponseField name="balance" type="object | null">
      The user's balance: personal cash + crypto + in-flight treasury deposits, plus account balances for accounts they own. Computed only on `GET /users/me` self-view for callers with balance-read scope; `null` otherwise.

      <Accordion title="Properties">
        <ResponseField name="businesses" type="object[]">
          Account balances for accounts the user owns, highest balance first. Excludes accounts with no balance.

          <Accordion title="Properties">
            <ResponseField name="id" type="string">
              The account ID, which looks like biz\_\*\*\*\*\*\*\*\*\*\*\*\*\*.
            </ResponseField>

            <ResponseField name="balance_usd" type="string">
              The account's total balance in USD.
            </ResponseField>

            <ResponseField name="logo_url" type="string | null">
              The account's logo URL.
            </ResponseField>

            <ResponseField name="name" type="string | null">
              The account's display name.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="businesses_total_usd" type="string">
          Combined USD balance across every account the user owns.
        </ResponseField>

        <ResponseField name="cash" type="object[]">
          Per-currency fiat cash balances.

          <Accordion title="Properties">
            <ResponseField name="balance" type="number">
              Available balance in the native currency.
            </ResponseField>

            <ResponseField name="balance_usd" type="number">
              Available balance converted to USD.
            </ResponseField>

            <ResponseField name="currency" type="string">
              Lowercase ISO currency code, such as `usd` or `eur`.
            </ResponseField>

            <ResponseField name="pending_balance_usd" type="number">
              Pending balance converted to USD.
            </ResponseField>

            <ResponseField name="reserve_balance_usd" type="number">
              Reserved balance converted to USD.
            </ResponseField>

            <ResponseField name="total_withdrawable_balance" type="number">
              Withdrawable amount in the native currency.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="cash_usd" type="string">
          Fiat cash in USD, including pending and reserve.
        </ResponseField>

        <ResponseField name="crypto" type="object[]">
          Per-token crypto holdings in the ledger's own wallet.

          <Accordion title="Properties">
            <ResponseField name="balance" type="string">
              Amount held in native token units, as a decimal string.
            </ResponseField>

            <ResponseField name="icon_url" type="string | null">
              Token icon URL.
            </ResponseField>

            <ResponseField name="name" type="string | null">
              The token's display name.
            </ResponseField>

            <ResponseField name="price_usd" type="number | null">
              USD price per token, or `null` when unknown.
            </ResponseField>

            <ResponseField name="symbol" type="string">
              Token display symbol, such as `USDT`, `XAUT`, or `cbBTC`.
            </ResponseField>

            <ResponseField name="value_usd" type="number">
              Holding USD value.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="crypto_usd" type="string">
          Crypto holdings in USD.
        </ResponseField>

        <ResponseField name="pending_usd" type="string">
          Pending funds in USD: fiat pending + in-flight treasury deposits.
        </ResponseField>

        <ResponseField name="total_usd" type="string">
          The user's personal balance in USD: cash (available + pending + reserve) +
          crypto + in-flight treasury deposits. Excludes account balances (see
          businesses\_total\_usd).
        </ResponseField>

        <ResponseField name="treasury_pending_usd" type="string">
          Balance-to-wallet USDT0 withdrawals still in flight, in USD.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="balance_history" type="object | null">
      The user's cumulative wallet balance over time (USD `\{ t, v }` points plus last/min/max), for the balance chart. Opt in with `include_balance_history=true` on `GET /users/me`; populated only for callers with balance-read scope and `null` otherwise. A user with no wallet activity returns an empty series.

      <Accordion title="Properties">
        <ResponseField name="data" type="object[]">
          Cumulative balance points over the requested window, oldest first.

          <Accordion title="Properties">
            <ResponseField name="t" type="integer">
              Point timestamp, in Unix seconds.
            </ResponseField>

            <ResponseField name="v" type="number">
              Cumulative wallet balance at this point, in USD.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="last" type="number">
          Value of the most recent point, in USD.
        </ResponseField>

        <ResponseField name="max" type="number">
          Maximum value across the window, in USD.
        </ResponseField>

        <ResponseField name="min" type="number">
          Minimum value across the window, in USD.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="banner" type="object | null">
      The user's profile banner wrapper. `null` when the user has no banner.

      <Accordion title="Properties">
        <ResponseField name="url" type="string">
          Profile banner image URL.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="bio" type="string | null">
      The user's biography
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the user was created, as an ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="earnings_usd" type="object | null">
      The user's gross USD income over time. Populated only on single-user self reads for callers with balance-read scope; `null` otherwise.

      <Accordion title="Properties">
        <ResponseField name="first_earned_at" type="string | null">
          The first time the user earned gross income, as an ISO 8601 timestamp.
        </ResponseField>

        <ResponseField name="owned_accounts" type="object">
          Gross income from accounts the user owns or is owner-authorized on.

          <Accordion title="Properties">
            <ResponseField name="last_24_hours" type="string">
              Gross income in USD over the last 24 hours.
            </ResponseField>

            <ResponseField name="last_30_days" type="string">
              Gross income in USD over the last 30 days.
            </ResponseField>

            <ResponseField name="last_7_days" type="string">
              Gross income in USD over the last 7 days.
            </ResponseField>

            <ResponseField name="lifetime" type="string">
              All-time gross income in USD.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="personal" type="object">
          Gross income from the user's personal wallet.

          <Accordion title="Properties">
            <ResponseField name="last_24_hours" type="string">
              Gross income in USD over the last 24 hours.
            </ResponseField>

            <ResponseField name="last_30_days" type="string">
              Gross income in USD over the last 30 days.
            </ResponseField>

            <ResponseField name="last_7_days" type="string">
              Gross income in USD over the last 7 days.
            </ResponseField>

            <ResponseField name="lifetime" type="string">
              All-time gross income in USD.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="total" type="object">
          Gross income from the user's personal wallet plus accounts they own or are owner-authorized on.

          <Accordion title="Properties">
            <ResponseField name="last_24_hours" type="string">
              Gross income in USD over the last 24 hours.
            </ResponseField>

            <ResponseField name="last_30_days" type="string">
              Gross income in USD over the last 30 days.
            </ResponseField>

            <ResponseField name="last_7_days" type="string">
              Gross income in USD over the last 7 days.
            </ResponseField>

            <ResponseField name="lifetime" type="string">
              All-time gross income in USD.
            </ResponseField>
          </Accordion>
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="email" type="string | null">
      The user's email address. Populated only on `GET /users/me` self-view for
      callers with email-read scope; `null` otherwise, or while the account has no
      confirmed email yet.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name
    </ResponseField>

    <ResponseField name="profile_picture" type="object">
      Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture.

      <Accordion title="Properties">
        <ResponseField name="url" type="string">
          Avatar image URL. Always present — a generated placeholder when the user set no picture.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="social_accounts" type="object[]">
      Social accounts linked to the user (Discord, X/Twitter, Telegram), oldest first. Reading your own profile returns every linked account; other profiles only include what is public on Whop (the primary Discord and the X account). Empty when none are linked.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Unique identifier for the social account.
        </ResponseField>

        <ResponseField name="error" type="string | null">
          Why this social account currently can't be used for advertising — a failed
          share or a Meta-side restriction. Null when the account is healthy.
        </ResponseField>

        <ResponseField name="external_id" type="string | null">
          The platform-specific ID for this social account.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The display name of the social account on the platform.
        </ResponseField>

        <ResponseField name="parent_social_account" type="object | null">
          The social account this one belongs to on the platform, such as the Facebook page that owns an Instagram account. Null when the social account stands on its own.

          <Accordion title="Properties">
            <ResponseField name="id" type="string">
              Social account ID, prefixed `sacc_`.
            </ResponseField>

            <ResponseField name="external_id" type="string | null">
              The platform-specific ID for the parent social account.
            </ResponseField>

            <ResponseField name="name" type="string | null">
              The display name of the parent social account on the platform.
            </ResponseField>

            <ResponseField name="platform" type="string">
              The platform the parent social account exists on.

              Available options: `x`, `instagram`, `youtube`, `tiktok`, `facebook`, `discord`, `telegram`
            </ResponseField>

            <ResponseField name="profile_picture_url" type="string | null">
              The URL where the profile picture of the parent social account can be
              accessed.
            </ResponseField>

            <ResponseField name="username" type="string | null">
              The username of the parent social account on the platform.
            </ResponseField>

            <ResponseField name="verified" type="boolean">
              Whether the parent social account is verified on the platform.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="platform" type="string">
          The platform the social account exists on.

          Available options: `x`, `instagram`, `youtube`, `tiktok`, `facebook`, `discord`, `telegram`
        </ResponseField>

        <ResponseField name="profile_picture_url" type="string | null">
          The URL where the profile picture of the social account can be accessed.
        </ResponseField>

        <ResponseField name="scopes" type="string[]">
          Capabilities Whop retains specific to this social account. For example, Whop
          may request the ability to run advertisements that use this social account's
          identity, reflected by the presence of `advertise` in this value.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          The URL where the social account can be accessed on the platform. Null while a
          Whop-owned page is still being provisioned.
        </ResponseField>

        <ResponseField name="username" type="string | null">
          The username of the social account on the platform. Null while a Whop-owned
          page is still being provisioned.
        </ResponseField>

        <ResponseField name="verified" type="boolean">
          Whether the social account is verified on the platform.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="staff" type="object | null">
      Whop staff access flags. Populated only on `GET /users/me` self-view for callers with staff-read scope; `null` there for every user who is not Whop staff, and always `null` elsewhere.

      <Accordion title="Properties">
        <ResponseField name="admin" type="boolean">
          Whether the user holds the admin staff role with a valid second factor.
        </ResponseField>

        <ResponseField name="investigation_access" type="boolean">
          Whether the user can open Whop-internal investigation tooling right now: a
          qualifying staff role plus their investigation toggle switched on.
        </ResponseField>

        <ResponseField name="manager" type="boolean">
          Whether the user holds the manager staff role with a valid second factor.
        </ResponseField>

        <ResponseField name="support" type="boolean">
          Whether the user holds the support staff role with a valid second factor.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username
    </ResponseField>

    <ResponseField name="verification" type="object">
      Identity verification status for the user's `individual` (KYC) and `business`
      (KYB) profiles. Each is `null` until created, otherwise a `status` of
      `not_started`, `pending`, `approved`, or `rejected`.
    </ResponseField>

    <ResponseField name="whop_partner_enabled_at" type="string | null">
      When the user became an enrolled Whop Partner, as an ISO 8601 timestamp.
      `null` if never enrolled.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json User theme={null}
      {
      	"id": "user_alex123",
      	"balance": {
      		"businesses": [
      			{
      				"id": "biz_acme123",
      				"name": "Acme Inc",
      				"logo_url": "https://cdn.whop.com/logos/acme.png",
      				"balance_usd": "14325.00"
      			}
      		],
      		"businesses_total_usd": "14325.00",
      		"cash": [
      			{
      				"currency": "usd",
      				"balance": 250,
      				"balance_usd": 250,
      				"pending_balance_usd": 0,
      				"reserve_balance_usd": 0,
      				"total_withdrawable_balance": 250
      			}
      		],
      		"cash_usd": "250.00",
      		"crypto": [
      			{
      				"symbol": "USDT",
      				"name": "Tether USD",
      				"balance": "500.00",
      				"value_usd": 500,
      				"price_usd": 1,
      				"icon_url": "https://cdn.whop.com/tokens/usdt.png"
      			}
      		],
      		"crypto_usd": "500.00",
      		"pending_usd": "0.00",
      		"total_usd": "750.00",
      		"treasury_pending_usd": "0.00"
      	},
      	"balance_history": {
      		"data": [
      			{
      				"t": 1735689600,
      				"v": 500
      			},
      			{
      				"t": 1735776000,
      				"v": 750
      			}
      		],
      		"last": 750,
      		"min": 500,
      		"max": 750
      	},
      	"bio": "Building communities on Whop.",
      	"banner": {
      		"url": "https://cdn.whop.com/banner.png"
      	},
      	"social_accounts": [
      		{
      			"id": "discord_123456789012345678",
      			"platform": "discord",
      			"username": "alex",
      			"name": "alex",
      			"url": null,
      			"profile_picture_url": "https://cdn.discordapp.com/avatars/123456789012345678/abcdef.png",
      			"verified": false,
      			"external_id": "123456789012345678",
      			"scopes": [],
      			"error": null,
      			"parent_social_account": null
      		},
      		{
      			"id": "telegram_987654321",
      			"platform": "telegram",
      			"username": "alex_tg",
      			"name": "alex_tg",
      			"url": null,
      			"profile_picture_url": null,
      			"verified": false,
      			"external_id": "987654321",
      			"scopes": [],
      			"error": null,
      			"parent_social_account": null
      		},
      		{
      			"id": "x_111222333",
      			"platform": "x",
      			"username": "alex",
      			"name": "alex",
      			"url": null,
      			"profile_picture_url": "https://pbs.twimg.com/profile_images/alex.jpg",
      			"verified": true,
      			"external_id": "111222333",
      			"scopes": [],
      			"error": null,
      			"parent_social_account": null
      		}
      	],
      	"created_at": "2026-06-01T12:00:00Z",
      	"earnings_usd": {
      		"total": {
      			"lifetime": "15075.00",
      			"last_30_days": "3425.00",
      			"last_7_days": "890.00",
      			"last_24_hours": "120.00"
      		},
      		"personal": {
      			"lifetime": "750.00",
      			"last_30_days": "250.00",
      			"last_7_days": "100.00",
      			"last_24_hours": "25.00"
      		},
      		"owned_accounts": {
      			"lifetime": "14325.00",
      			"last_30_days": "3175.00",
      			"last_7_days": "790.00",
      			"last_24_hours": "95.00"
      		},
      		"first_earned_at": "2026-06-02T15:30:00Z"
      	},
      	"name": "Alex Rivera",
      	"profile_picture": {
      		"url": "https://cdn.whop.com/avatar.png"
      	},
      	"username": "alex",
      	"verification": {
      		"business": null,
      		"individual": {
      			"status": "approved"
      		}
      	},
      	"whop_partner_enabled_at": "2026-06-10T09:00:00Z",
      	"email": "jack@whop.com",
      	"staff": null
      }
      ```
    </div>
  </Column>
</Columns>


# Course Chapter
Source: https://docs.whop.com/api-reference/course-chapters/course-chapter

A grouping of related lessons within a course, used to organize content into sections.

<ResponseExample>
  ```json Example theme={null}
  {
  	"id": "chap_xxxxxxxxxxxxx",
  	"lessons": [
  		{
  			"id": "lesn_xxxxxxxxxxxxx",
  			"order": 42,
  			"title": "Understanding Candlestick Patterns"
  		}
  	],
  	"order": 42,
  	"title": "Getting Started"
  }
  ```
</ResponseExample>

<ResponseField name="id" type="string">
  The unique identifier for the chapter.

  Example: `chap_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="lessons" type="array<object>">
  An ordered list of lessons in this chapter, sorted by display position. Hidden lessons are excluded for non-admin users.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the lesson.

      Example: `lesn_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="order" type="integer">
      The sort position of this lesson within its parent chapter, starting from zero.

      Example: `42`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the lesson shown to students. Maximum 120 characters.

      Example: `Understanding Candlestick Patterns`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="order" type="integer">
  The sort position of this chapter within its parent course, starting from zero.

  Example: `42`
</ResponseField>

<ResponseField name="title" type="string">
  The display name of the chapter shown to students. Maximum 150 characters.

  Example: `Getting Started`
</ResponseField>


# Create course chapter
Source: https://docs.whop.com/api-reference/course-chapters/create-course-chapter

/openapi/api-v1-stable.json post /course_chapters
Create a new chapter within a course to organize lessons into sections.

Required permissions:
 - `courses:update`



# Delete course chapter
Source: https://docs.whop.com/api-reference/course-chapters/delete-course-chapter

/openapi/api-v1-stable.json delete /course_chapters/{id}
Permanently delete a chapter and all of its lessons from a course.

Required permissions:
 - `courses:update`



# List course chapters
Source: https://docs.whop.com/api-reference/course-chapters/list-course-chapters

/openapi/api-v1-stable.json get /course_chapters
Returns a paginated list of chapters within a course, ordered by position.

Required permissions:
 - `courses:read`



# Retrieve course chapter
Source: https://docs.whop.com/api-reference/course-chapters/retrieve-course-chapter

/openapi/api-v1-stable.json get /course_chapters/{id}
Retrieves the details of an existing course chapter.

Required permissions:
 - `courses:read`



# Update course chapter
Source: https://docs.whop.com/api-reference/course-chapters/update-course-chapter

/openapi/api-v1-stable.json patch /course_chapters/{id}
Update a chapter's title within a course.

Required permissions:
 - `courses:update`



# Course Lesson Interaction
Source: https://docs.whop.com/api-reference/course-lesson-interactions/course-lesson-interaction

A record of a user's progress on a specific lesson, tracking whether they have completed it.

<ResponseExample>
  ```json Example theme={null}
  {
  	"completed": true,
  	"course": {
  		"experience": {
  			"id": "exp_xxxxxxxxxxxxxx"
  		},
  		"id": "cors_xxxxxxxxxxxxx",
  		"title": "Introduction to Technical Analysis"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"id": "crsli_xxxxxxxxxxxx",
  	"lesson": {
  		"chapter": {
  			"id": "chap_xxxxxxxxxxxxx"
  		},
  		"id": "lesn_xxxxxxxxxxxxx",
  		"title": "Understanding Candlestick Patterns"
  	},
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="completed" type="boolean">
  Whether the user has finished this lesson.
</ResponseField>

<ResponseField name="course" type="object">
  The course that contains the tracked lesson.

  <Expandable title="child attributes">
    <ResponseField name="experience" type="object">
      The parent experience that this course belongs to.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the experience.

          Example: `exp_xxxxxxxxxxxxxx`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the course.

      Example: `cors_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string | null">
      The display name of the course shown to students. Null if no title has been set.

      Example: `Introduction to Technical Analysis`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the lesson interaction was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the lesson interaction.

  Example: `crsli_xxxxxxxxxxxx`
</ResponseField>

<ResponseField name="lesson" type="object">
  The lesson that this progress record belongs to.

  <Expandable title="child attributes">
    <ResponseField name="chapter" type="object">
      The parent chapter that contains this lesson.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the chapter.

          Example: `chap_xxxxxxxxxxxxx`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the lesson.

      Example: `lesn_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the lesson shown to students. Maximum 120 characters.

      Example: `Understanding Candlestick Patterns`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="user" type="object">
  The user whose progress is being tracked.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# Courselessoninteraction completed
Source: https://docs.whop.com/api-reference/course-lesson-interactions/courselessoninteraction-completed

/openapi/api-v1-stable.json webhook course_lesson_interaction.completed
Sent when a course lesson interaction is completed

Required permissions:
 - `courses:read`
 - `course_analytics:read`
 - `webhook_receive:courses`



# List course lesson interactions
Source: https://docs.whop.com/api-reference/course-lesson-interactions/list-course-lesson-interactions

/openapi/api-v1-stable.json get /course_lesson_interactions
Returns a paginated list of lesson interactions, filtered by lesson, course, user, or completion status.

Required permissions:
 - `courses:read`
 - `course_analytics:read`



# Retrieve course lesson interaction
Source: https://docs.whop.com/api-reference/course-lesson-interactions/retrieve-course-lesson-interaction

/openapi/api-v1-stable.json get /course_lesson_interactions/{id}
Retrieves the details of an existing course lesson interaction.

Required permissions:
 - `courses:read`
 - `course_analytics:read`



# Course Lesson
Source: https://docs.whop.com/api-reference/course-lessons/course-lesson

An individual learning unit within a chapter, which can contain text, video, PDF, or assessment content.

<ResponseExample>
  ```json Example theme={null}
  {
  	"assessment_questions": [
  		{
  			"correct_answer": "<string>",
  			"created_at": "2023-12-01T05:00:00.401Z",
  			"id": "crsaq_xxxxxxxxxxxx",
  			"image": {
  				"content_type": "image/jpeg",
  				"filename": "document.pdf",
  				"id": "<string>",
  				"url": "https://media.whop.com/abc123/optimized.jpg"
  			},
  			"options": [
  				{
  					"id": "crsaqo_xxxxxxxxxxx",
  					"is_correct": true,
  					"option_text": "<string>",
  					"order": 42
  				}
  			],
  			"order": 42,
  			"question_text": "<string>",
  			"question_type": "short_answer"
  		}
  	],
  	"attachments": [
  		{
  			"content_type": "image/jpeg",
  			"filename": "document.pdf",
  			"id": "<string>",
  			"url": "https://media.whop.com/abc123/optimized.jpg"
  		}
  	],
  	"content": "In this lesson, we will cover the basics of technical analysis...",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"days_from_course_start_until_unlock": 42,
  	"embed_id": "dQw4w9WgXcQ",
  	"embed_type": "youtube",
  	"id": "lesn_xxxxxxxxxxxxx",
  	"lesson_type": "text",
  	"main_pdf": {
  		"content_type": "image/jpeg",
  		"filename": "document.pdf",
  		"id": "<string>",
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"order": 42,
  	"thumbnail": {
  		"url": "https://media.whop.com/abc123/optimized.jpg"
  	},
  	"title": "Understanding Candlestick Patterns",
  	"video_asset": {
  		"asset_id": "<string>",
  		"audio_only": true,
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"duration_seconds": 42,
  		"finished_uploading_at": "2023-12-01T05:00:00.401Z",
  		"id": "mux_xxxxxxxxxxxxxx",
  		"playback_id": "<string>",
  		"signed_playback_id": "<string>",
  		"signed_storyboard_playback_token": "<string>",
  		"signed_thumbnail_playback_token": "<string>",
  		"signed_video_playback_token": "<string>",
  		"status": "uploading",
  		"updated_at": "2023-12-01T05:00:00.401Z"
  	},
  	"visibility": "visible"
  }
  ```
</ResponseExample>

<ResponseField name="assessment_questions" type="array<object>">
  The list of questions for quiz or knowledge check lessons. Empty for non-assessment lesson types.

  <Expandable title="child attributes">
    <ResponseField name="correct_answer" type="string | null">
      The correct answer for the question. Used for short answer questions. Only
      visible to admins (users with courses:update permission)
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the assessment question was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the assessment question.

      Example: `crsaq_xxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="image" type="object | null">
      Optional image attachment for the question

      <Expandable title="child attributes">
        <ResponseField name="content_type" type="string | null">
          Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

          Example: `image/jpeg`
        </ResponseField>

        <ResponseField name="filename" type="string | null">
          The original filename of the uploaded attachment, including its file extension.

          Example: `document.pdf`
        </ResponseField>

        <ResponseField name="id" type="string" />

        <ResponseField name="url" type="string | null">
          A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

          Example: `https://media.whop.com/abc123/optimized.jpg`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="options" type="array<object>">
      The answer options for multiple choice/select questions

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the assessment question option.

          Example: `crsaqo_xxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="is_correct" type="boolean | null">
          Whether this option is a correct answer. Only visible to admins (users with
          courses:update permission)
        </ResponseField>

        <ResponseField name="option_text" type="string">
          The text of the answer option
        </ResponseField>

        <ResponseField name="order" type="integer">
          The order of this option within the question

          Example: `42`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="order" type="integer">
      The order of the question within its lesson

      Example: `42`
    </ResponseField>

    <ResponseField name="question_text" type="string">
      The text of the question
    </ResponseField>

    <ResponseField name="question_type" type="CoursesAssessmentQuestionTypes">
      The type of the question

      Available options: `short_answer`, `true_false`, `multiple_choice`, `multiple_select`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="attachments" type="array<object>">
  All supplementary files attached to this lesson returned as a flat array rather than a paginated connection.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="content" type="string | null">
  The Markdown content body of the lesson. Null if the lesson has no text content.

  Example: `In this lesson, we will cover the basics of technical ana…`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the lesson was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="days_from_course_start_until_unlock" type="integer | null">
  The number of days after a student starts the course before this lesson becomes accessible. Null if the lesson is available immediately.

  Example: `42`
</ResponseField>

<ResponseField name="embed_id" type="string | null">
  The external video identifier for embedded video lessons, such as a YouTube video ID or Loom share ID. Null if the lesson has no embed.

  Example: `dQw4w9WgXcQ`
</ResponseField>

<ResponseField name="embed_type" type="EmbedTypes | null">
  The platform type for the embedded video. One of: youtube, loom. Null if the lesson has no embed.

  Available options: `youtube`, `loom`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the lesson.

  Example: `lesn_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="lesson_type" type="LessonTypes">
  The content format of this lesson. One of: text, video, pdf, multi, quiz, knowledge\_check.

  Available options: `text`, `video`, `pdf`, `multi`, `quiz`, `knowledge_check`
</ResponseField>

<ResponseField name="main_pdf" type="object | null">
  The primary PDF document for PDF-type lessons. Null if this lesson is not a PDF lesson or no PDF has been uploaded.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="order" type="integer">
  The sort position of this lesson within its parent chapter, starting from zero.

  Example: `42`
</ResponseField>

<ResponseField name="thumbnail" type="object | null">
  The thumbnail image displayed on lesson cards and previews. Null if no thumbnail has been uploaded.

  <Expandable title="child attributes">
    <ResponseField name="url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="title" type="string">
  The display name of the lesson shown to students. Maximum 120 characters.

  Example: `Understanding Candlestick Patterns`
</ResponseField>

<ResponseField name="video_asset" type="object | null">
  The Mux video asset for video-type lessons, used for streaming playback. Null if this lesson has no hosted video.

  <Expandable title="child attributes">
    <ResponseField name="asset_id" type="string | null">
      The Mux-provided ID of the asset
    </ResponseField>

    <ResponseField name="audio_only" type="boolean">
      Whether this asset contains only audio
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      The datetime the mux asset was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="duration_seconds" type="integer | null">
      The duration of the video in seconds

      Example: `42`
    </ResponseField>

    <ResponseField name="finished_uploading_at" type="string<date-time> | null">
      The time at which the video finished uploading

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the mux asset.

      Example: `mux_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="playback_id" type="string | null">
      The public playback ID of the Mux asset
    </ResponseField>

    <ResponseField name="signed_playback_id" type="string | null">
      The signed playback ID of the Mux asset
    </ResponseField>

    <ResponseField name="signed_storyboard_playback_token" type="string | null">
      The signed storyboard playback token of the Mux asset
    </ResponseField>

    <ResponseField name="signed_thumbnail_playback_token" type="string | null">
      The signed thumbnail playback token of the Mux asset
    </ResponseField>

    <ResponseField name="signed_video_playback_token" type="string | null">
      The signed video playback token of the Mux asset
    </ResponseField>

    <ResponseField name="status" type="MuxAssetStatuses">
      The status of the Mux asset

      Available options: `uploading`, `created`, `ready`
    </ResponseField>

    <ResponseField name="updated_at" type="string<date-time>">
      The datetime the mux asset was last updated.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="visibility" type="LessonVisibilities">
  The visibility setting that controls whether this lesson appears to students. One of: visible, hidden.

  Available options: `visible`, `hidden`
</ResponseField>


# Create course lesson
Source: https://docs.whop.com/api-reference/course-lessons/create-course-lesson

/openapi/api-v1-stable.json post /course_lessons
Create a new lesson within a course chapter. Lessons can contain video, text, or assessment content.

Required permissions:
 - `courses:update`



# Delete course lesson
Source: https://docs.whop.com/api-reference/course-lessons/delete-course-lesson

/openapi/api-v1-stable.json delete /course_lessons/{id}
Permanently delete a lesson and remove it from its chapter.

Required permissions:
 - `courses:update`



# List course lessons
Source: https://docs.whop.com/api-reference/course-lessons/list-course-lessons

/openapi/api-v1-stable.json get /course_lessons
Returns a paginated list of lessons within a course or chapter, ordered by position.

Required permissions:
 - `courses:read`



# Mark as completed course lesson
Source: https://docs.whop.com/api-reference/course-lessons/mark-as-completed-course-lesson

/openapi/api-v1-stable.json post /course_lessons/{lesson_id}/mark_as_completed
Mark a lesson as completed for the current user after they finish the content.



# Retrieve course lesson
Source: https://docs.whop.com/api-reference/course-lessons/retrieve-course-lesson

/openapi/api-v1-stable.json get /course_lessons/{id}
Retrieves the details of an existing course lesson.

Required permissions:
 - `courses:read`



# Start course lesson
Source: https://docs.whop.com/api-reference/course-lessons/start-course-lesson

/openapi/api-v1-stable.json post /course_lessons/{lesson_id}/start
Record that the current user has started viewing a lesson, creating progress tracking records.



# Submit assessment course lesson
Source: https://docs.whop.com/api-reference/course-lessons/submit-assessment-course-lesson

/openapi/api-v1-stable.json post /course_lessons/{lesson_id}/submit_assessment
Submit answers for a quiz or knowledge check lesson and receive a graded result.



# Update course lesson
Source: https://docs.whop.com/api-reference/course-lessons/update-course-lesson

/openapi/api-v1-stable.json patch /course_lessons/{id}
Update a lesson's content, type, visibility, assessment questions, or media attachments.

Required permissions:
 - `courses:update`



# Course Student
Source: https://docs.whop.com/api-reference/course-students/course-student

An enrollment record for a student in a course, including progress and completion metrics.

<ResponseExample>
  ```json Example theme={null}
  {
  	"completed_lessons_count": 42,
  	"completion_rate": 6.9,
  	"course": {
  		"experience": {
  			"id": "exp_xxxxxxxxxxxxxx"
  		},
  		"id": "cors_xxxxxxxxxxxxx",
  		"title": "Introduction to Technical Analysis"
  	},
  	"first_interaction_at": "2023-12-01T05:00:00.401Z",
  	"id": "<string>",
  	"last_interaction_at": "2023-12-01T05:00:00.401Z",
  	"total_lessons_count": 42,
  	"user": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"username": "johndoe42"
  	}
  }
  ```
</ResponseExample>

<ResponseField name="completed_lessons_count" type="integer">
  The total number of lessons this student has marked as completed in the course.

  Example: `42`
</ResponseField>

<ResponseField name="completion_rate" type="number">
  The percentage of available lessons the student has completed, as a value from 0 to 100 rounded to two decimal places.

  Example: `6.9`
</ResponseField>

<ResponseField name="course" type="object">
  The course this student is enrolled in.

  <Expandable title="child attributes">
    <ResponseField name="experience" type="object">
      The parent experience that this course belongs to.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the experience.

          Example: `exp_xxxxxxxxxxxxxx`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the course.

      Example: `cors_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string | null">
      The display name of the course shown to students. Null if no title has been set.

      Example: `Introduction to Technical Analysis`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="first_interaction_at" type="string<date-time>">
  The timestamp when the student first interacted with this course, as a Unix timestamp.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the course student type.
</ResponseField>

<ResponseField name="last_interaction_at" type="string<date-time>">
  The timestamp when the student most recently interacted with this course, as a Unix timestamp.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="total_lessons_count" type="integer">
  The total number of visible lessons available to this student in the course.

  Example: `42`
</ResponseField>

<ResponseField name="user" type="object">
  The user profile of the enrolled student.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>
</ResponseField>


# List course students
Source: https://docs.whop.com/api-reference/course-students/list-course-students

/openapi/api-v1-stable.json get /course_students
Returns a paginated list of students enrolled in a course, with optional name filtering.

Required permissions:
 - `courses:read`
 - `course_analytics:read`



# Retrieve course student
Source: https://docs.whop.com/api-reference/course-students/retrieve-course-student

/openapi/api-v1-stable.json get /course_students/{id}
Retrieves the details of an existing course student.

Required permissions:
 - `courses:read`
 - `course_analytics:read`



# Course
Source: https://docs.whop.com/api-reference/courses/course

A structured learning module containing chapters and lessons, belonging to an experience.

<ResponseExample>
  ```json Example theme={null}
  {
  	"certificate_after_completion_enabled": true,
  	"chapters": [
  		{
  			"id": "chap_xxxxxxxxxxxxx",
  			"lessons": [
  				{
  					"id": "lesn_xxxxxxxxxxxxx",
  					"lesson_type": "text",
  					"order": 42,
  					"thumbnail": {
  						"url": "https://media.whop.com/abc123/optimized.jpg"
  					},
  					"title": "Understanding Candlestick Patterns",
  					"video_asset": {
  						"duration_seconds": 42,
  						"signed_playback_id": "<string>",
  						"signed_thumbnail_playback_token": "<string>"
  					}
  				}
  			],
  			"order": 42,
  			"title": "Getting Started"
  		}
  	],
  	"cover_image": "https://assets.whop.com/images/course-cover.jpg",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"description": "Learn advanced trading strategies from industry experts.",
  	"id": "cors_xxxxxxxxxxxxx",
  	"language": "en",
  	"order": "123.45",
  	"require_completing_lessons_in_order": true,
  	"tagline": "Master the fundamentals in 30 days",
  	"thumbnail": {
  		"content_type": "image/jpeg",
  		"filename": "document.pdf",
  		"id": "<string>",
  		"optimized_url": "https://media.whop.com/abc123/optimized.jpg",
  		"source_url": "https://media.whop.com/abc123/original.jpg"
  	},
  	"title": "Introduction to Technical Analysis",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"visibility": "visible"
  }
  ```
</ResponseExample>

<ResponseField name="certificate_after_completion_enabled" type="boolean | null">
  Whether students receive a PDF certificate after completing all lessons in
  this course. Null if the setting has not been configured.
</ResponseField>

<ResponseField name="chapters" type="array<object>">
  An ordered list of all chapters in this course, sorted by their display position.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the chapter.

      Example: `chap_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="lessons" type="array<object>">
      An ordered list of lessons in this chapter, sorted by display position. Hidden lessons are excluded for non-admin users.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The unique identifier for the lesson.

          Example: `lesn_xxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="lesson_type" type="LessonTypes">
          The content format of this lesson. One of: text, video, pdf, multi, quiz, knowledge\_check.

          Available options: `text`, `video`, `pdf`, `multi`, `quiz`, `knowledge_check`
        </ResponseField>

        <ResponseField name="order" type="integer">
          The sort position of this lesson within its parent chapter, starting from zero.

          Example: `42`
        </ResponseField>

        <ResponseField name="thumbnail" type="object | null">
          The thumbnail image displayed on lesson cards and previews. Null if no thumbnail has been uploaded.

          <Expandable title="child attributes">
            <ResponseField name="url" type="string | null">
              A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

              Example: `https://media.whop.com/abc123/optimized.jpg`
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="title" type="string">
          The display name of the lesson shown to students. Maximum 120 characters.

          Example: `Understanding Candlestick Patterns`
        </ResponseField>

        <ResponseField name="video_asset" type="object | null">
          The Mux video asset for video-type lessons, used for streaming playback. Null if this lesson has no hosted video.

          <Expandable title="child attributes">
            <ResponseField name="duration_seconds" type="integer | null">
              The duration of the video in seconds

              Example: `42`
            </ResponseField>

            <ResponseField name="signed_playback_id" type="string | null">
              The signed playback ID of the Mux asset
            </ResponseField>

            <ResponseField name="signed_thumbnail_playback_token" type="string | null">
              The signed thumbnail playback token of the Mux asset
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="order" type="integer">
      The sort position of this chapter within its parent course, starting from zero.

      Example: `42`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the chapter shown to students. Maximum 150 characters.

      Example: `Getting Started`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cover_image" type="string | null">
  The URL of the course cover image shown on preview cards. Null if no cover image has been uploaded.

  Example: `https://assets.whop.com/images/course-cover.jpg`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the course was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="description" type="string | null">
  A brief summary of the course content and objectives. Null if no description has been set.

  Example: `Learn advanced trading strategies from industry experts.`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the course.

  Example: `cors_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="language" type="Languages">
  The spoken language of the video content, used to generate accurate closed captions. One of: en, es, it, pt, de, fr, pl, ru, nl, ca, tr, sv, uk, no, fi, sk, el, cs, hr, da, ro, bg.

  Available options: `en`, `es`, `it`, `pt`, `de`, `fr`, `pl`, `ru`, `nl`, `ca`, `tr`, `sv`, `uk`, `no`, `fi`, `sk`, `el`, `cs`, `hr`, `da`, `ro`, `bg`
</ResponseField>

<ResponseField name="order" type="string">
  The sort position of this course within its parent experience, as a decimal for flexible ordering.

  Example: `123.45`
</ResponseField>

<ResponseField name="require_completing_lessons_in_order" type="boolean">
  Whether students must complete each lesson sequentially before advancing to
  the next one.
</ResponseField>

<ResponseField name="tagline" type="string | null">
  A short marketing tagline displayed beneath the course title. Null if no tagline has been set.

  Example: `Master the fundamentals in 30 days`
</ResponseField>

<ResponseField name="thumbnail" type="object | null">
  The thumbnail image displayed on course cards and previews. Null if no thumbnail has been uploaded.

  <Expandable title="child attributes">
    <ResponseField name="content_type" type="string | null">
      Uploaded file MIME type, such as image/jpeg, video/mp4, or audio/mpeg.

      Example: `image/jpeg`
    </ResponseField>

    <ResponseField name="filename" type="string | null">
      The original filename of the uploaded attachment, including its file extension.

      Example: `document.pdf`
    </ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="optimized_url" type="string | null">
      A pre-optimized URL for rendering this attachment on the client. This should be used for displaying attachments in apps.

      Example: `https://media.whop.com/abc123/optimized.jpg`
    </ResponseField>

    <ResponseField name="source_url" type="string | null">
      The original source URL of the attachment, such as a direct link to S3. This should never be displayed on the client and should always be passed through an Imgproxy transformer.

      Example: `https://media.whop.com/abc123/original.jpg`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="title" type="string | null">
  The display name of the course shown to students. Null if no title has been set.

  Example: `Introduction to Technical Analysis`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  The datetime the course was last updated.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="visibility" type="CourseVisibilities">
  The visibility setting that controls whether this course appears to students. One of: visible, hidden.

  Available options: `visible`, `hidden`
</ResponseField>


# Create course
Source: https://docs.whop.com/api-reference/courses/create-course

/openapi/api-v1-stable.json post /courses
Create a new course within an experience, with optional chapters, lessons, and a certificate.

Required permissions:
 - `courses:update`



# Delete course
Source: https://docs.whop.com/api-reference/courses/delete-course

/openapi/api-v1-stable.json delete /courses/{id}
Permanently delete a course and all of its chapters, lessons, and student progress.

Required permissions:
 - `courses:update`



# List courses
Source: https://docs.whop.com/api-reference/courses/list-courses

/openapi/api-v1-stable.json get /courses
Returns a paginated list of courses, filtered by either an experience or a company.

Required permissions:
 - `courses:read`



# Retrieve course
Source: https://docs.whop.com/api-reference/courses/retrieve-course

/openapi/api-v1-stable.json get /courses/{id}
Retrieves the details of an existing course.

Required permissions:
 - `courses:read`



# Update course
Source: https://docs.whop.com/api-reference/courses/update-course

/openapi/api-v1-stable.json patch /courses/{id}
Update a course's title, description, visibility, thumbnail, or chapter ordering.

Required permissions:
 - `courses:update`



# Identity Profile
Source: https://docs.whop.com/api-reference/identity-profiles/identity-profile

A consolidated identity or business profile synced from verification provider data.

<ResponseExample>
  ```json Example theme={null}
  {
  	"business_address": {
  		"city": "<string>",
  		"country": "<string>",
  		"line1": "<string>",
  		"line2": "<string>",
  		"postal_code": "<string>",
  		"state": "<string>"
  	},
  	"business_name": "<string>",
  	"business_structure": "<string>",
  	"country": "<string>",
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"date_of_birth": "<string>",
  	"email": "<string>",
  	"first_name": "<string>",
  	"id": "idpf_xxxxxxxxxxxxx",
  	"last_name": "<string>",
  	"linked_companies": [
  		{
  			"id": "biz_xxxxxxxxxxxxxx",
  			"title": "Pickaxe"
  		}
  	],
  	"payout_status": "connected",
  	"payouts_enabled": true,
  	"personal_address": {
  		"city": "<string>",
  		"country": "<string>",
  		"line1": "<string>",
  		"line2": "<string>",
  		"postal_code": "<string>",
  		"state": "<string>"
  	},
  	"phone": "<string>",
  	"profile_type": "<string>",
  	"status": "not_started",
  	"updated_at": "2023-12-01T05:00:00.401Z",
  	"verifications": [
  		{
  			"created_at": "2023-12-01T05:00:00.401Z",
  			"id": "verf_xxxxxxxxxxxxx",
  			"last_error_code": "abandoned",
  			"last_error_reason": "Document image was too blurry to read.",
  			"session_url": "https://verify.stripe.com/session/abc123",
  			"status": "requires_input"
  		}
  	]
  }
  ```
</ResponseExample>

<ResponseField name="business_address" type="object | null">
  Registered business address reported by the identity provider. Present on `business` profiles.

  <Expandable title="child attributes">
    <ResponseField name="city" type="string | null">
      The city of the address.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      The country of the address.
    </ResponseField>

    <ResponseField name="line1" type="string | null">
      The line 1 of the address.
    </ResponseField>

    <ResponseField name="line2" type="string | null">
      The line 2 of the address.
    </ResponseField>

    <ResponseField name="postal_code" type="string | null">
      The postal code of the address.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      The state of the address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="business_name" type="string | null">
  Business entity name. Present on `business` profiles.
</ResponseField>

<ResponseField name="business_structure" type="string | null">
  Reported legal structure of a business profile (e.g. `corp`, `llc`).
  Provider-specific values; present on `business` profiles.
</ResponseField>

<ResponseField name="country" type="string | null">
  ISO 3166-1 alpha-2 country code reported by the identity provider, such as
  `US` or `GB`. For individuals this is the country of citizenship or residence;
  for businesses, the country of incorporation.
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  When the identity profile was first created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="date_of_birth" type="string | null">
  ISO date (`YYYY-MM-DD`) reported by the identity provider. Present on
  `individual` profiles.
</ResponseField>

<ResponseField name="email" type="string | null">
  Email address reported by the identity provider. Typically present on
  `individual` profiles.
</ResponseField>

<ResponseField name="first_name" type="string | null">
  Individual's first name.
</ResponseField>

<ResponseField name="id" type="string">
  The tag of the identity profile (idpf\_xxx).

  Example: `idpf_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="last_name" type="string | null">
  Individual's last name.
</ResponseField>

<ResponseField name="linked_companies" type="array<object>">
  The companies this identity profile is currently linked to. Only populated for direct Whop user sessions; always empty when authenticated via API key, app, or OAuth scope (a single identity can be linked to companies the calling platform is not entitled to see).

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payout_status" type="PayoutAccountCalculatedStatuses">
  Progress of payout-account setup for this profile, independent of holds. `connected` means onboarding is complete; a `connected` status paired with `payouts_enabled: false` indicates an active account restriction rather than incomplete setup.

  Available options: `connected`, `disabled`, `action_required`, `pending_verification`, `verification_failed`, `manual_review`, `denied`, `not_started`, `blocked_by_parent`
</ResponseField>

<ResponseField name="payouts_enabled" type="boolean">
  Whether this profile can receive payouts right now. True only when payout
  onboarding is complete and no payout holds are active on the linked account.
  Treat this as the single source of truth for payout readiness.
</ResponseField>

<ResponseField name="personal_address" type="object | null">
  Residential address reported by the identity provider. Present on `individual` profiles.

  <Expandable title="child attributes">
    <ResponseField name="city" type="string | null">
      The city of the address.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      The country of the address.
    </ResponseField>

    <ResponseField name="line1" type="string | null">
      The line 1 of the address.
    </ResponseField>

    <ResponseField name="line2" type="string | null">
      The line 2 of the address.
    </ResponseField>

    <ResponseField name="postal_code" type="string | null">
      The postal code of the address.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      The state of the address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="phone" type="string | null">
  Phone number reported by the identity provider. Typically present on
  `individual` profiles.
</ResponseField>

<ResponseField name="profile_type" type="string">
  Whether this is an 'individual' or 'business' profile.
</ResponseField>

<ResponseField name="status" type="IdentityProfileStatuses">
  Derived verification status across all linked verifications. Returns `action_required` whenever the profile has an open request for information (whether a verification, payout, or audit RFI) — i.e. the merchant must submit something before it is in good standing.

  Available options: `not_started`, `pending`, `manual_review`, `approved`, `rejected`, `action_required`
</ResponseField>

<ResponseField name="updated_at" type="string<date-time>">
  When the identity profile was last synced from a verification.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="verifications" type="array<object>">
  All verification attempts attached to this identity profile, ordered most-recent first.

  <Expandable title="child attributes">
    <ResponseField name="created_at" type="string<date-time>">
      When the verification record was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="id" type="string">
      The numeric id of the verification record.

      Example: `verf_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="last_error_code" type="VerificationErrorCodes | null">
      The most recent error code returned during verification. Null if no error has occurred.

      Available options: `abandoned`, `consent_declined`, `country_not_supported`, `device_not_supported`, `document_expired`, `document_type_not_supported`, `document_unverified_other`, `email_unverified_other`, `email_verification_declined`, `id_number_insufficient_document_data`, `id_number_mismatch`, `id_number_unverified_other`, `phone_unverified_other`, `phone_verification_declined`, `selfie_document_missing_photo`, `selfie_face_mismatch`, `selfie_manipulated`, `selfie_unverified_other`, `under_supported_age`
    </ResponseField>

    <ResponseField name="last_error_reason" type="string | null">
      A human-readable explanation of the most recent verification error. Null if no error has occurred.

      Example: `Document image was too blurry to read.`
    </ResponseField>

    <ResponseField name="session_url" type="string | null">
      A URL the user can visit to complete the verification process. Null if the session does not require user interaction.

      Example: `https://verify.stripe.com/session/abc123`
    </ResponseField>

    <ResponseField name="status" type="VerificationStatuses">
      The current status of this verification session.

      Available options: `requires_input`, `processing`, `verified`, `canceled`, `created`, `started`, `submitted`, `approved`, `declined`, `resubmission_requested`, `expired`, `abandoned`, `review`, `action_required`, `manual_review`
    </ResponseField>
  </Expandable>
</ResponseField>


# Identityprofile updated
Source: https://docs.whop.com/api-reference/identity-profiles/identityprofile-updated

/openapi/api-v1-stable.json webhook identity_profile.updated
Sent whenever an identity profile changes state — a verification is approved, needs action, or is rejected, or a Whop review opens or clears. Every other identity_profile event is also delivered as an identity_profile.updated, so you can subscribe to this single event and re-fetch the verification to read its current status.

Required permissions:
 - `identity:read`
 - `webhook_receive:identity_profiles`



# List identity profile verifications
Source: https://docs.whop.com/api-reference/identity-profiles/list-identity-profile-verifications

/openapi/api-v1-stable.json get /identity_profiles/{id}/verifications
Returns a list of verifications attached to an identity profile, ordered by most recent first.

Required permissions:
 - `identity:read`



# List identity profiles
Source: https://docs.whop.com/api-reference/identity-profiles/list-identity-profiles

/openapi/api-v1-stable.json get /identity_profiles
Returns a paginated list of identity profiles. When company_id is provided, lists IPs currently linked to that company's ledger. When omitted, lists IPs linked to any ledger the actor can read (including child companies under a parent).

Required permissions:
 - `identity:read`



# Retrieve identity profile
Source: https://docs.whop.com/api-reference/identity-profiles/retrieve-identity-profile

/openapi/api-v1-stable.json get /identity_profiles/{id}
Retrieves the details of an existing identity profile.

Required permissions:
 - `identity:read`



# Unlink an identity profile
Source: https://docs.whop.com/api-reference/identity-profiles/unlink-an-identity-profile

/openapi/api-v1-stable.json delete /identity_profiles/{id}
Unlinks an IdentityProfile from a LedgerAccount (flips the matching link to is_current=false).



# Ledger Account
Source: https://docs.whop.com/api-reference/ledger-accounts/ledger-account

A ledger account represents a financial account on Whop that can hold many balances.

<ResponseExample>
  ```json Example theme={null}
  {
  	"balances": [
  		{
  			"balance": 6.9,
  			"currency": "usd",
  			"pending_balance": 6.9,
  			"reserve_balance": 6.9
  		}
  	],
  	"id": "ldgr_xxxxxxxxxxxxx",
  	"ledger_type": "primary",
  	"owner": {
  		"id": "user_xxxxxxxxxxxxx",
  		"name": "John Doe",
  		"typename": "User",
  		"username": "johndoe42"
  	},
  	"payments_approval_status": "pending",
  	"payout_account_details": {
  		"address": {
  			"city": "<string>",
  			"country": "<string>",
  			"line1": "<string>",
  			"line2": "<string>",
  			"postal_code": "<string>",
  			"state": "<string>"
  		},
  		"business_name": "<string>",
  		"business_representative": {
  			"date_of_birth": "<string>",
  			"first_name": "<string>",
  			"last_name": "<string>",
  			"middle_name": "<string>"
  		},
  		"email": "<string>",
  		"id": "poact_xxxxxxxxxxxx",
  		"latest_verification": {
  			"id": "verf_xxxxxxxxxxxxx",
  			"last_error_code": "abandoned",
  			"last_error_reason": "Document image was too blurry to read.",
  			"status": "requires_input"
  		},
  		"phone": "<string>",
  		"status": "connected"
  	},
  	"settlement_time_at": "2023-12-01T05:00:00.401Z",
  	"transfer_fee": 6.9,
  	"treasury_balance": {
  		"balance": 6.9,
  		"balance_usd": 6.9,
  		"currency": "usd",
  		"pending_balance": 6.9,
  		"reserve_balance": 6.9,
  		"total_withdrawable_balance": 6.9
  	}
  }
  ```
</ResponseExample>

<ResponseField name="balances" type="array<object>">
  The balances associated with the account.

  <Expandable title="child attributes">
    <ResponseField name="balance" type="number">
      The amount of the balance.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The currency of the balance.

      Available options: `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`
    </ResponseField>

    <ResponseField name="pending_balance" type="number">
      The amount of the balance that is pending.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="reserve_balance" type="number">
      The amount of the balance that is reserved.

      Example: `6.9`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the ledger account.

  Example: `ldgr_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="ledger_type" type="LedgerTypes">
  The type of ledger account.

  Available options: `primary`, `pool`
</ResponseField>

<ResponseField name="owner" type="User or Company | null">
  The owner of the ledger account.

  <Expandable title="User">
    <ResponseField name="id" type="string">
      The unique identifier for the user.

      Example: `user_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The user's display name shown on their public profile.

      Example: `John Doe`
    </ResponseField>

    <ResponseField name="typename" type="string">
      The typename of this object
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's unique username shown on their public profile.

      Example: `johndoe42`
    </ResponseField>
  </Expandable>

  <Expandable title="Company">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="route" type="string">
      URL slug for the account's store page, e.g. `pickaxe` in whop.com/pickaxe.

      Example: `pickaxe`
    </ResponseField>

    <ResponseField name="title" type="string">
      The display name of the company shown to customers.

      Example: `Pickaxe`
    </ResponseField>

    <ResponseField name="typename" type="string">
      The typename of this object
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payments_approval_status" type="PaymentsApprovalStatuses | null">
  The status of payments approval for the ledger account.

  Available options: `pending`, `approved`, `monitoring`, `rejected`
</ResponseField>

<ResponseField name="payout_account_details" type="object | null">
  The payout account associated with the LedgerAccount, if any.

  <Expandable title="child attributes">
    <ResponseField name="address" type="object | null">
      The physical address associated with this payout account

      <Expandable title="child attributes">
        <ResponseField name="city" type="string | null">
          The city of the address.
        </ResponseField>

        <ResponseField name="country" type="string | null">
          The country of the address.
        </ResponseField>

        <ResponseField name="line1" type="string | null">
          The line 1 of the address.
        </ResponseField>

        <ResponseField name="line2" type="string | null">
          The line 2 of the address.
        </ResponseField>

        <ResponseField name="postal_code" type="string | null">
          The postal code of the address.
        </ResponseField>

        <ResponseField name="state" type="string | null">
          The state of the address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="business_name" type="string | null">
      The company's legal name
    </ResponseField>

    <ResponseField name="business_representative" type="object | null">
      The business representative for this payout account

      <Expandable title="child attributes">
        <ResponseField name="date_of_birth" type="string | null">
          The date of birth of the business representative in ISO 8601 format
          (YYYY-MM-DD).
        </ResponseField>

        <ResponseField name="first_name" type="string | null">
          The first name of the business representative.
        </ResponseField>

        <ResponseField name="last_name" type="string | null">
          The last name of the business representative.
        </ResponseField>

        <ResponseField name="middle_name" type="string | null">
          The middle name of the business representative.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="email" type="string | null">
      The email address of the representative
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payout account.

      Example: `poact_xxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="latest_verification" type="object | null">
      The latest verification for the connected account.

      <Expandable title="child attributes">
        <ResponseField name="id" type="string">
          The numeric id of the verification record.

          Example: `verf_xxxxxxxxxxxxx`
        </ResponseField>

        <ResponseField name="last_error_code" type="VerificationErrorCodes | null">
          The most recent error code returned during verification. Null if no error has occurred.

          Available options: `abandoned`, `consent_declined`, `country_not_supported`, `device_not_supported`, `document_expired`, `document_type_not_supported`, `document_unverified_other`, `email_unverified_other`, `email_verification_declined`, `id_number_insufficient_document_data`, `id_number_mismatch`, `id_number_unverified_other`, `phone_unverified_other`, `phone_verification_declined`, `selfie_document_missing_photo`, `selfie_face_mismatch`, `selfie_manipulated`, `selfie_unverified_other`, `under_supported_age`
        </ResponseField>

        <ResponseField name="last_error_reason" type="string | null">
          A human-readable explanation of the most recent verification error. Null if no error has occurred.

          Example: `Document image was too blurry to read.`
        </ResponseField>

        <ResponseField name="status" type="VerificationStatuses">
          The current status of this verification session.

          Available options: `requires_input`, `processing`, `verified`, `canceled`, `created`, `started`, `submitted`, `approved`, `declined`, `resubmission_requested`, `expired`, `abandoned`, `review`, `action_required`, `manual_review`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="phone" type="string | null">
      The business representative's phone
    </ResponseField>

    <ResponseField name="status" type="PayoutAccountCalculatedStatuses | null">
      The granular calculated status of the payout account reflecting its current KYC and withdrawal readiness state.

      Available options: `connected`, `disabled`, `action_required`, `pending_verification`, `verification_failed`, `manual_review`, `denied`, `not_started`, `blocked_by_parent`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="settlement_time_at" type="string<date-time> | null">
  The settlement batch most recently posted to this account's available balance, at midnight UTC. Every payment settling in that batch carries the same `settlement_time_at`.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="transfer_fee" type="number | null">
  The fee for transfers, if applicable.

  Example: `6.9`
</ResponseField>

<ResponseField name="treasury_balance" type="object | null">
  The balance cache associated with the account by currency.

  <Expandable title="child attributes">
    <ResponseField name="balance" type="number">
      The amount of the balance.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="balance_usd" type="number">
      The balance converted to USD.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="currency" type="Currencies">
      The currency of the balance.

      Available options: `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`
    </ResponseField>

    <ResponseField name="pending_balance" type="number">
      The amount of the balance that is pending.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="reserve_balance" type="number">
      The amount of the balance that is reserved.

      Example: `6.9`
    </ResponseField>

    <ResponseField name="total_withdrawable_balance" type="number">
      The amount of the balance that is withdrawable.

      Example: `6.9`
    </ResponseField>
  </Expandable>
</ResponseField>


# Ledgeraccount funds available
Source: https://docs.whop.com/api-reference/ledger-accounts/ledgeraccount-funds-available

/openapi/api-v1-stable.json webhook ledger_account.funds_available
Sent when a ledger account is funds available

Required permissions:
 - `company:balance:read`
 - `payout:account:read`
 - `webhook_receive:ledger_accounts`



# Retrieve ledger account
Source: https://docs.whop.com/api-reference/ledger-accounts/retrieve-ledger-account

/openapi/api-v1-stable.json get /ledger_accounts/{id}
Retrieves the details of an existing ledger account.

Required permissions:
 - `company:balance:read`
 - `payout:account:read`



# Payout Account
Source: https://docs.whop.com/api-reference/payout-accounts/payout-account

An object representing an account used for payouts.

<ResponseExample>
  ```json Example theme={null}
  {
  	"address": {
  		"city": "<string>",
  		"country": "<string>",
  		"line1": "<string>",
  		"line2": "<string>",
  		"postal_code": "<string>",
  		"state": "<string>"
  	},
  	"business_name": "<string>",
  	"business_representative": {
  		"date_of_birth": "<string>",
  		"first_name": "<string>",
  		"last_name": "<string>",
  		"middle_name": "<string>"
  	},
  	"email": "<string>",
  	"id": "poact_xxxxxxxxxxxx",
  	"latest_verification": {
  		"id": "verf_xxxxxxxxxxxxx",
  		"last_error_code": "abandoned",
  		"last_error_reason": "Document image was too blurry to read.",
  		"status": "requires_input"
  	},
  	"phone": "<string>",
  	"status": "connected"
  }
  ```
</ResponseExample>

<ResponseField name="address" type="object | null">
  The physical address associated with this payout account

  <Expandable title="child attributes">
    <ResponseField name="city" type="string | null">
      The city of the address.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      The country of the address.
    </ResponseField>

    <ResponseField name="line1" type="string | null">
      The line 1 of the address.
    </ResponseField>

    <ResponseField name="line2" type="string | null">
      The line 2 of the address.
    </ResponseField>

    <ResponseField name="postal_code" type="string | null">
      The postal code of the address.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      The state of the address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="business_name" type="string | null">
  The company's legal name
</ResponseField>

<ResponseField name="business_representative" type="object | null">
  The business representative for this payout account

  <Expandable title="child attributes">
    <ResponseField name="date_of_birth" type="string | null">
      The date of birth of the business representative in ISO 8601 format
      (YYYY-MM-DD).
    </ResponseField>

    <ResponseField name="first_name" type="string | null">
      The first name of the business representative.
    </ResponseField>

    <ResponseField name="last_name" type="string | null">
      The last name of the business representative.
    </ResponseField>

    <ResponseField name="middle_name" type="string | null">
      The middle name of the business representative.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="email" type="string | null">
  The email address of the representative
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the payout account.

  Example: `poact_xxxxxxxxxxxx`
</ResponseField>

<ResponseField name="latest_verification" type="object | null">
  The latest verification for the connected account.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The numeric id of the verification record.

      Example: `verf_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="last_error_code" type="VerificationErrorCodes | null">
      The most recent error code returned during verification. Null if no error has occurred.

      Available options: `abandoned`, `consent_declined`, `country_not_supported`, `device_not_supported`, `document_expired`, `document_type_not_supported`, `document_unverified_other`, `email_unverified_other`, `email_verification_declined`, `id_number_insufficient_document_data`, `id_number_mismatch`, `id_number_unverified_other`, `phone_unverified_other`, `phone_verification_declined`, `selfie_document_missing_photo`, `selfie_face_mismatch`, `selfie_manipulated`, `selfie_unverified_other`, `under_supported_age`
    </ResponseField>

    <ResponseField name="last_error_reason" type="string | null">
      A human-readable explanation of the most recent verification error. Null if no error has occurred.

      Example: `Document image was too blurry to read.`
    </ResponseField>

    <ResponseField name="status" type="VerificationStatuses">
      The current status of this verification session.

      Available options: `requires_input`, `processing`, `verified`, `canceled`, `created`, `started`, `submitted`, `approved`, `declined`, `resubmission_requested`, `expired`, `abandoned`, `review`, `action_required`, `manual_review`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="phone" type="string | null">
  The business representative's phone
</ResponseField>

<ResponseField name="status" type="PayoutAccountCalculatedStatuses | null">
  The granular calculated status of the payout account reflecting its current KYC and withdrawal readiness state.

  Available options: `connected`, `disabled`, `action_required`, `pending_verification`, `verification_failed`, `manual_review`, `denied`, `not_started`, `blocked_by_parent`
</ResponseField>


# Payoutaccount status updated
Source: https://docs.whop.com/api-reference/payout-accounts/payoutaccount-status-updated

/openapi/api-v1-stable.json webhook payout_account.status_updated
Sent when a payout account is status updated

Required permissions:
 - `payout:account:read`
 - `webhook_receive:payout_accounts`



# Retrieve payout account
Source: https://docs.whop.com/api-reference/payout-accounts/retrieve-payout-account

/openapi/api-v1-stable.json get /payout_accounts/{id}
Retrieves the details of an existing payout account.

Required permissions:
 - `payout:account:read`



# List payout methods
Source: https://docs.whop.com/api-reference/payout-methods/list-payout-methods

/openapi/api-v1-stable.json get /payout_methods
Returns a list of active payout methods configured for a company, ordered by most recently created.

Required permissions:
 - `payout:destination:read`



# Payout Method
Source: https://docs.whop.com/api-reference/payout-methods/payout-method

A configured payout destination where a user receives earned funds, such as a bank account or digital wallet.

<ResponseExample>
  ```json Example theme={null}
  {
  	"account_reference": "****1234",
  	"company": {
  		"id": "biz_xxxxxxxxxxxxxx"
  	},
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "USD",
  	"destination": {
  		"category": "crypto",
  		"country_code": "<string>",
  		"name": "<string>"
  	},
  	"id": "potk_xxxxxxxxxxxxx",
  	"institution_name": "Chase Bank",
  	"is_default": true,
  	"nickname": "My Business Account"
  }
  ```
</ResponseExample>

<ResponseField name="account_reference" type="string | null">
  A masked identifier for the payout destination, such as the last four digits of a bank account or an email address. Null if no reference is available.

  Example: `****1234`
</ResponseField>

<ResponseField name="company" type="object | null">
  The company associated with this payout destination. Null if not linked to a specific company.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The unique identifier for the company.

      Example: `biz_xxxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the payout token was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="string">
  The three-letter ISO currency code that payouts are delivered in for this destination.

  Example: `USD`
</ResponseField>

<ResponseField name="destination" type="object | null">
  The payout destination configuration linked to this token. Null if not yet configured.

  <Expandable title="child attributes">
    <ResponseField name="category" type="PayoutDestinationCategory">
      The category of the payout destination

      Available options: `crypto`, `rtp`, `next_day_bank`, `bank_wire`, `digital_wallet`, `unknown`
    </ResponseField>

    <ResponseField name="country_code" type="string">
      The country code of the payout destination
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the payer associated with the payout destination
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the payout token.

  Example: `potk_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="institution_name" type="string | null">
  The name of the bank or financial institution receiving payouts. Null if not applicable or not provided.

  Example: `Chase Bank`
</ResponseField>

<ResponseField name="is_default" type="boolean">
  Whether this is the default payout destination for the associated payout
  account.
</ResponseField>

<ResponseField name="nickname" type="string | null">
  A user-defined label to help identify this payout destination. Not sent to the provider. Null if no nickname has been set.

  Example: `My Business Account`
</ResponseField>


# Payoutmethod created
Source: https://docs.whop.com/api-reference/payout-methods/payoutmethod-created

/openapi/api-v1-stable.json webhook payout_method.created
Sent when a payout method is created

Required permissions:
 - `payout:destination:read`
 - `webhook_receive:payout_methods`



# Retrieve payout method
Source: https://docs.whop.com/api-reference/payout-methods/retrieve-payout-method

/openapi/api-v1-stable.json get /payout_methods/{id}
Retrieves the details of an existing payout method.

Required permissions:
 - `payout:destination:read`



# Retrieve setup intent
Source: https://docs.whop.com/api-reference/setup-intents/retrieve-setup-intent

/openapi/api-v1-stable.json get /setup_intents/{id}
Retrieves the details of an existing setup intent.

Required permissions:
 - `payment:setup_intent:read`
 - `member:basic:read`
 - `member:email:read`



# Setupintent canceled
Source: https://docs.whop.com/api-reference/setup-intents/setupintent-canceled

/openapi/api-v1-stable.json webhook setup_intent.canceled
Sent when a setup intent is canceled

Required permissions:
 - `payment:setup_intent:read`
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:setup_intents`



# Setupintent requires action
Source: https://docs.whop.com/api-reference/setup-intents/setupintent-requires-action

/openapi/api-v1-stable.json webhook setup_intent.requires_action
Sent when a setup intent is requires action

Required permissions:
 - `payment:setup_intent:read`
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:setup_intents`



# Setupintent succeeded
Source: https://docs.whop.com/api-reference/setup-intents/setupintent-succeeded

/openapi/api-v1-stable.json webhook setup_intent.succeeded
Sent when a setup intent is succeeded

Required permissions:
 - `payment:setup_intent:read`
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:setup_intents`



# Describe stats
Source: https://docs.whop.com/api-reference/stats/describe-stats

/openapi/api-v1-stable.json get /stats/describe
Describe available stats schema. Without resource returns root nodes and metrics. With resource returns node columns, associations, and available metrics.

Required permissions:
 - `stats:read`



# Metric stats
Source: https://docs.whop.com/api-reference/stats/metric-stats

/openapi/api-v1-stable.json get /stats/metric
Query an aggregated metric. Returns data grouped by period with optional breakdowns.

Required permissions:
 - `stats:read`



# Raw stats
Source: https://docs.whop.com/api-reference/stats/raw-stats

/openapi/api-v1-stable.json get /stats/raw
Query raw data from a resource. Returns paginated rows with all columns.

Required permissions:
 - `stats:read`



# Create topup
Source: https://docs.whop.com/api-reference/topups/create-topup

/openapi/api-v1-stable.json post /topups
Add funds to a company's platform balance by charging a stored payment method. Top-ups have no fees or taxes and do not count as revenue.

Required permissions:
 - `payment:charge`



# Topup
Source: https://docs.whop.com/api-reference/topups/topup

A payment represents a completed or attempted charge. Payments track the amount, status, currency, and payment method used.

<ResponseExample>
  ```json Example theme={null}
  {
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"failure_message": "<string>",
  	"id": "pay_xxxxxxxxxxxxxx",
  	"paid_at": "2023-12-01T05:00:00.401Z",
  	"status": "draft",
  	"total": 6.9
  }
  ```
</ResponseExample>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the payment was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies | null">
  The three-letter ISO currency code for this payment (e.g., 'usd', 'eur').

  Available options: `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`
</ResponseField>

<ResponseField name="failure_message" type="string | null">
  If the payment failed, the reason for the failure.
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the payment.

  Example: `pay_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="paid_at" type="string<date-time> | null">
  The time at which this payment was successfully collected. Null if the payment has not yet succeeded. As a Unix timestamp.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="status" type="ReceiptStatus | null">
  The current lifecycle state of this payment (e.g., 'draft', 'open', 'paid', 'void').

  Available options: `draft`, `open`, `paid`, `pending`, `uncollectible`, `unresolved`, `void`
</ResponseField>

<ResponseField name="total" type="number | null">
  The total to show to the creator (excluding buyer fees).

  Example: `6.9`
</ResponseField>


# Transfers
Source: https://docs.whop.com/api-reference/transfers/transfer

The Transfers API is documented in the Experimental API Reference.

The Transfers API is served by the versioned `/api/v1` API, so it is not part of the stable surface documented here.

<Card title="Transfers API Reference" icon="arrow-right" href="/api-reference/beta/transfers/transfer">
  Browse the Transfers resource schema and endpoints in the Experimental API
  Reference.
</Card>


# List verifications
Source: https://docs.whop.com/api-reference/verifications/list-verifications

/openapi/api-v1-stable.json get /verifications
Returns a list of identity verifications for a payout account, ordered by most recent first.

Required permissions:
 - `payout:account:read`



# Retrieve verification
Source: https://docs.whop.com/api-reference/verifications/retrieve-verification

/openapi/api-v1-stable.json get /verifications/{id}
Retrieves the details of an existing verification.

Required permissions:
 - `payout:account:read`



# Verification
Source: https://docs.whop.com/api-reference/verifications/verification

An identity verification session used to confirm a person or entity's identity for payout account eligibility.

A Verification walks you through identity verification (KYC for individuals, KYB for businesses) for an account that needs to receive payouts. For example, you can create a Verification to onboard a user before their first withdrawal, pre-filling their name and address so they complete the hosted KYC form in seconds without you building any verification UI. Later, you can use the same Verification to read back their verified identity data and respond to any [RFIs](/developer/verification/rfis) that downstream payout providers surface.

Create a Verification when an account needs to be verified before transacting — typically before their first [withdrawal](/api-reference/withdrawals/withdrawal). Before creating, make sure you have a [Company](/api-reference/companies/company) with a ledger account (created automatically when you create a company). Don't create multiple Verifications of the same `kind` on the same account — each account supports at most one active individual (KYC) and one business (KYB) profile. The Verification transitions through multiple statuses as the user completes the process: `pending` while they're going through KYC, `approved` once identity is confirmed, `rejected` if the provider declines, and `action_required` when a payout provider needs additional information like a bank statement or tax ID.

Successful Verifications result in a fully verified identity with confirmed name, date of birth, country, and address — unlocking the account for [payouts](/api-reference/payout-accounts/payout-account). If you create a Verification with pre-fill fields (`first_name`, `address`, etc.), it automatically seeds both the verification and the hosted KYC form so the user doesn't re-enter information you already have. We recommend subscribing to the `identity_profile.updated` [webhook](/api-reference/webhooks/webhook) rather than polling — it fires on every state change (approved, rejected, needs action, or a review opening or clearing), and its body identifies which profile changed rather than embedding the state, so re-fetch with `GET /verifications` to read the current status. By using Verifications, you can onboard users for payouts through a single API integration, even as the underlying KYC providers and compliance requirements change over time.

## Endpoints

| Method   | Path                                   | Description                                                                           |
| -------- | -------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET`    | `/verifications?account_id={biz_ tag}` | [List verifications](/developer/verification/retrieve) for an account                 |
| `GET`    | `/verifications/{verification_id}`     | [Retrieve a single verification](/developer/verification/retrieve) by its `idpf_` tag |
| `POST`   | `/verifications`                       | [Create a verification](/developer/verification/overview) and start a KYC/KYB session |
| `PATCH`  | `/verifications/{verification_id}`     | [Update identity fields or respond to RFIs](/developer/verification/manage)           |
| `DELETE` | `/verifications/{verification_id}`     | [Soft-delete](/developer/verification/manage) and unlink from the account             |

## Statuses

| Status            | Description                                             | Next step                                                      |
| ----------------- | ------------------------------------------------------- | -------------------------------------------------------------- |
| `not_started`     | Verification exists but no KYC session has been started | Call `POST /verifications` to start                            |
| `pending`         | User needs to complete KYC at the `session_url`         | Redirect the user to `session_url`                             |
| `approved`        | KYC passed — the account can transact                   | No action needed                                               |
| `rejected`        | KYC was declined by the provider                        | Call `POST /verifications` with `restart: true`                |
| `action_required` | A payout provider needs additional information          | Check `rfis` array and [respond](/developer/verification/rfis) |

<ResponseExample>
  ```json Example theme={null}
  {
  	"id": "verf_xxxxxxxxxxxxx",
  	"last_error_code": "abandoned",
  	"last_error_reason": "Document image was too blurry to read.",
  	"status": "requires_input"
  }
  ```
</ResponseExample>

<ResponseField name="id" type="string">
  The numeric id of the verification record.

  Example: `verf_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="last_error_code" type="VerificationErrorCodes | null">
  The most recent error code returned during verification. Null if no error has occurred.

  Available options: `abandoned`, `consent_declined`, `country_not_supported`, `device_not_supported`, `document_expired`, `document_type_not_supported`, `document_unverified_other`, `email_unverified_other`, `email_verification_declined`, `id_number_insufficient_document_data`, `id_number_mismatch`, `id_number_unverified_other`, `phone_unverified_other`, `phone_verification_declined`, `selfie_document_missing_photo`, `selfie_face_mismatch`, `selfie_manipulated`, `selfie_unverified_other`, `under_supported_age`
</ResponseField>

<ResponseField name="last_error_reason" type="string | null">
  A human-readable explanation of the most recent verification error. Null if no error has occurred.

  Example: `Document image was too blurry to read.`
</ResponseField>

<ResponseField name="status" type="VerificationStatuses">
  The current status of this verification session.

  Available options: `requires_input`, `processing`, `verified`, `canceled`, `created`, `started`, `submitted`, `approved`, `declined`, `resubmission_requested`, `expired`, `abandoned`, `review`, `action_required`, `manual_review`
</ResponseField>


# Verification succeeded
Source: https://docs.whop.com/api-reference/verifications/verification-succeeded

/openapi/api-v1-stable.json webhook verification.succeeded
Sent when a verification is succeeded

Required permissions:
 - `payout:account:read`
 - `webhook_receive:verifications`



# Create withdrawal
Source: https://docs.whop.com/api-reference/withdrawals/create-withdrawal

/openapi/api-v1-stable.json post /withdrawals
Creates a withdrawal request for a ledger account

Required permissions:
 - `payout:withdraw_funds`
 - `payout:destination:read`



# Generate PDF
Source: https://docs.whop.com/api-reference/withdrawals/generate-pdf

/openapi/api-v1-stable.json post /withdrawals/{id}/generate_pdf
Generates a withdrawal PDF invoice and returns a temporary download URL.

Required permissions:
 - `payout:withdrawal:read`



# List withdrawals
Source: https://docs.whop.com/api-reference/withdrawals/list-withdrawals

/openapi/api-v1-stable.json get /withdrawals
Returns a paginated list of withdrawals for a company, with optional sorting and date filtering.

Required permissions:
 - `payout:withdrawal:read`



# Retrieve withdrawal
Source: https://docs.whop.com/api-reference/withdrawals/retrieve-withdrawal

/openapi/api-v1-stable.json get /withdrawals/{id}
Retrieves the details of an existing withdrawal.

Required permissions:
 - `payout:withdrawal:read`
 - `payout:destination:read`



# Withdrawal
Source: https://docs.whop.com/api-reference/withdrawals/withdrawal

A withdrawal represents a request to transfer funds from a ledger account to an external payout method.

<ResponseExample>
  ```json Example theme={null}
  {
  	"amount": 6.9,
  	"created_at": "2023-12-01T05:00:00.401Z",
  	"currency": "usd",
  	"error_code": "account_closed",
  	"error_message": "Destination bank account is invalid.",
  	"estimated_availability": "2023-12-01T05:00:00.401Z",
  	"fee_amount": 6.9,
  	"fee_type": "exclusive",
  	"id": "wdrl_xxxxxxxxxxxxx",
  	"ledger_account": {
  		"company_id": "<string>",
  		"id": "ldgr_xxxxxxxxxxxxx"
  	},
  	"markup_fee": 6.9,
  	"payout_request_id": "cofr_xxxxxxxxxxxxxx",
  	"payout_token": {
  		"created_at": "2023-12-01T05:00:00.401Z",
  		"destination_currency_code": "USD",
  		"id": "potk_xxxxxxxxxxxxx",
  		"nickname": "My Business Account",
  		"payer_name": "Acme Corp LLC"
  	},
  	"speed": "standard",
  	"status": "requested",
  	"trace_code": "021000021234567"
  }
  ```
</ResponseExample>

<ResponseField name="amount" type="number">
  The withdrawal amount as a decimal number in the specified currency (e.g., 100.00 for \$100.00 USD).

  Example: `6.9`
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  The datetime the withdrawal was created.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="currency" type="Currencies">
  The three-letter ISO currency code for this withdrawal (e.g., 'usd', 'eur').

  Available options: `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`
</ResponseField>

<ResponseField name="error_code" type="PayoutErrorCodes | null">
  A machine-readable error code describing why the payout failed. Null if no error occurred.

  Available options: `account_closed`, `account_does_not_exist`, `account_information_invalid`, `account_number_invalid_region`, `account_frozen`, `account_lookup_failed`, `account_not_found`, `amount_out_of_bounds`, `attributes_not_validated`, `b2b_payments_prohibited`, `bank_statement_required`, `compliance_review`, `currency_not_supported`, `deposit_canceled`, `deposit_failed`, `deposit_rejected`, `destination_unavailable`, `exceeded_account_limit`, `expired_quote`, `generic_payout_error`, `junk_failure_reason`, `technical_problem`, `provider_temporarily_unavailable`, `provider_validation_failed`, `identification_number_invalid`, `invalid_account_number`, `invalid_bank_code`, `invalid_beneficiary`, `invalid_mailing_address`, `invalid_branch_number`, `invalid_branch_code`, `invalid_phone_number`, `invalid_routing_number`, `invalid_swift_code`, `invalid_company_details`, `manual_cancelation`, `misc_error`, `missing_city_and_country`, `missing_phone_number`, `missing_remittance_info`, `payee_name_invalid`, `beneficiary_name_mismatch`, `receiving_account_locked`, `rejected_by_compliance`, `rtp_not_supported`, `non_transaction_account`, `source_token_insufficient_funds`, `ssn_invalid`, `wallet_screenshot_required`, `unsupported_region`, `payout_provider_timeout`
</ResponseField>

<ResponseField name="error_message" type="string | null">
  A human-readable message describing why the payout failed. Null if no error occurred.

  Example: `Destination bank account is invalid.`
</ResponseField>

<ResponseField name="estimated_availability" type="string<date-time> | null">
  The estimated time at which the funds become available in the destination account. Null if no estimate is available. As a Unix timestamp.

  Example: `2023-12-01T05:00:00.401Z`
</ResponseField>

<ResponseField name="fee_amount" type="number">
  The fee charged for processing this withdrawal, in the same currency as the withdrawal amount.

  Example: `6.9`
</ResponseField>

<ResponseField name="fee_type" type="WithdrawalFeeTypes | null">
  How the fee was applied to the withdrawal. 'exclusive' means the fee was added on top (user receives the full requested amount). 'inclusive' means the fee was deducted from the withdrawal (user receives less than requested). Null if no fee was charged.

  Available options: `exclusive`, `inclusive`
</ResponseField>

<ResponseField name="id" type="string">
  The unique identifier for the withdrawal.

  Example: `wdrl_xxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="ledger_account" type="object">
  The ledger account from which the withdrawal funds are sourced.

  <Expandable title="child attributes">
    <ResponseField name="company_id" type="string | null" />

    <ResponseField name="id" type="string">
      The unique identifier for the ledger account.

      Example: `ldgr_xxxxxxxxxxxxx`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="markup_fee" type="number">
  An additional markup fee charged for the withdrawal, in the same currency as the withdrawal amount. Only applies to platform accounts using Whop Rails.

  Example: `6.9`
</ResponseField>

<ResponseField name="payout_request_id" type="string | null">
  The id of the payout request (returned by POST /payouts) that this withdrawal settles. Null unless the withdrawal originated from a stablecoin payout.

  Example: `cofr_xxxxxxxxxxxxxx`
</ResponseField>

<ResponseField name="payout_token" type="object | null">
  The saved payout destination used for this withdrawal (e.g., a bank account or PayPal address). Null if no payout token was used.

  <Expandable title="child attributes">
    <ResponseField name="created_at" type="string<date-time>">
      The datetime the payout token was created.

      Example: `2023-12-01T05:00:00.401Z`
    </ResponseField>

    <ResponseField name="destination_currency_code" type="string">
      The three-letter ISO currency code that payouts are delivered in for this destination.

      Example: `USD`
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier for the payout token.

      Example: `potk_xxxxxxxxxxxxx`
    </ResponseField>

    <ResponseField name="nickname" type="string | null">
      A user-defined label to help identify this payout destination. Not sent to the provider. Null if no nickname has been set.

      Example: `My Business Account`
    </ResponseField>

    <ResponseField name="payer_name" type="string | null">
      The legal name of the account holder receiving payouts. Null if not provided.

      Example: `Acme Corp LLC`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="speed" type="WithdrawalSpeeds">
  The processing speed selected for this withdrawal ('standard' or 'instant').

  Available options: `standard`, `instant`
</ResponseField>

<ResponseField name="status" type="WithdrawalStatus">
  The computed lifecycle status of the withdrawal, accounting for the state of associated payouts (e.g., 'requested', 'in\_transit', 'completed', 'failed').

  Available options: `requested`, `awaiting_payment`, `in_transit`, `completed`, `failed`, `canceled`, `denied`
</ResponseField>

<ResponseField name="trace_code" type="string | null">
  The ACH trace number for tracking the payout through the banking network. Null if not available or not an ACH transaction.

  Example: `021000021234567`
</ResponseField>


# Withdrawal created
Source: https://docs.whop.com/api-reference/withdrawals/withdrawal-created

/openapi/api-v1-stable.json webhook withdrawal.created
Sent when a withdrawal is created

Required permissions:
 - `payout:withdrawal:read`
 - `payout:destination:read`
 - `webhook_receive:withdrawals`



# Withdrawal updated
Source: https://docs.whop.com/api-reference/withdrawals/withdrawal-updated

/openapi/api-v1-stable.json webhook withdrawal.updated
Sent when a withdrawal is updated

Required permissions:
 - `payout:withdrawal:read`
 - `payout:destination:read`
 - `webhook_receive:withdrawals`



# Idempotent requests
Source: https://docs.whop.com/developer/api/idempotency

Retry POST requests safely by attaching an Idempotency-Key header, so a request is never executed twice.

Every authenticated `POST` on the Experimental API accepts an `Idempotency-Key` header. When a request with a key succeeds, its response is stored for 24 hours; retrying with the same key replays the stored response instead of executing the request again. This makes it safe to retry a request that timed out or errored on your side without risking a duplicate charge, transfer, or resource.

Any unique string up to 255 bytes works as a key — a UUID is a good default. Generate a fresh key for every distinct operation, and reuse that exact key only to retry that operation.

```bash theme={null}
curl -X POST https://api.whop.com/api/v1/transfers \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Idempotency-Key: d9105228-4a08-46b1-8b91-42fed586d383" \
  -H "Content-Type: application/json" \
  -d '{"amount": "10.00", "currency": "usd", "destination_id": "user_XXXXXXXX"}'
```

| Your retry                                         | You get                                                  |
| -------------------------------------------------- | -------------------------------------------------------- |
| Same key, same request                             | The original response, replayed — not a second execution |
| Same key, different request                        | A `400` error                                            |
| Same key, while the first request is still running | A `409` error — retry after the first request finishes   |
| Same key, more than 24 hours later                 | A fresh execution, as if the key were new                |

Replayed responses are byte-for-byte identical to the original — including the status code — and carry an `Idempotent-Replayed: true` header so you can tell a replay apart from a fresh execution.

<Note>
  **Error responses are replayed too.** If the original request failed with a `4xx`, retrying with the same key returns that same error. That failure was the real outcome of the request — send a new key with the corrected request instead.
</Note>

A few details worth knowing:

* "Same request" means the method, path, query string, body, and `Api-Version-Date` all match the original exactly. Any difference is treated as a key reuse and rejected with a `400`.
* Keys are scoped to the authenticated caller. Two different API keys or users can use the same key value without colliding.
* The header is ignored on unauthenticated requests and on non-`POST` methods — `GET`, `PATCH`, and `DELETE` requests are naturally safe to retry.
* If a request fails in a way where the outcome is unknown (for example, a server crash mid-request), retries return a `409` until the key expires — the API never risks executing a request twice.


# API versions
Source: https://docs.whop.com/developer/api/versioning

Pin your requests to a dated API version so changes to the API never break your integration.

The Experimental API is versioned with dates. Pin a version when you want a stable API contract; official SDKs send the version they were generated against automatically.

```bash theme={null}
curl https://api.whop.com/api/v1/plans \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-07-23"
```

| You send                       | You get                                   |
| ------------------------------ | ----------------------------------------- |
| `Api-Version-Date: 2026-07-23` | The API as it worked on that date         |
| No header, API key has a pin   | The API version stored on the API key     |
| No header or stored pin        | The original `2025-01-01` behavior        |
| An unknown date                | A `400` error with the supported versions |

<Note>
  **If you don't pass an `Api-Version-Date` or have a stored API-key pin, the stable API model is used.** Requests with neither are served by the pre-versioning behavior, so existing integrations keep working unchanged. Pin a dated version to opt into the latest API.
</Note>

## API key version pins

API keys carry their own API version pin. Requests authenticated with an API key use that pin when they omit `Api-Version-Date`. Existing keys without a stored pin use `2025-01-01`; newly created keys use the latest released version.

An explicit `Api-Version-Date` header always takes precedence over the API key's pin, so you can test an upgrade before changing the saved version.

New endpoints and new optional fields are added to every version automatically. Breaking changes create a new dated version and are listed below.

## Changelog

<Update label="2026-08-05-1" description="Fiat currency conversion on swaps">
  Fiat-pair swaps (`POST /swaps` with two fiat currencies) now support free-form currency conversion, and `amount` matches crypto swap semantics.

  * `amount` is the amount of `from_token` to convert at the mid-market rate — no negative balance required.
  * Sizing a partial repayment of a negative `to_token` balance moved to the new `to_amount` field (denominated in `to_token`, capped at the debt). `amount` and `to_amount` are mutually exclusive.
  * Omitting both still repays the full negative `to_token` balance.
  * Callers pinned to earlier versions keep the previous behavior: their fiat `amount` is treated as the `to_token` repayment amount.
</Update>

<Update label="2026-08-05" description="Flat verification requirements">
  A verification's `requested_information` is now a flat list: one requirement per entry, one write per answer.

  * Each entry names what is needed in `requirement` — a document such as `bank_statement`, or a field key such as `ssn` — with a `label` to show the user.
  * Answer `file` entries with `file` (a direct upload ID); `text`, `date`, `phone`, and `select` entries with `value`; `address` entries with `address`. Nothing from the response is echoed back.
  * An entry marked `multiple` takes several files in one answer, in slot order — front first for a two-sided document.
  * An entry listing `options` also takes a `value`: on a `select` those are the allowed answers, and on an identity document they are the ID types accepted.
  * Keys that don't apply are omitted, and rejected submissions carry structured `errors` with a stable `code` and a `reason`.
  * The nested `requested_files`/`category` form shape is gone from this version. Callers pinned to earlier versions keep it, and their answers are translated automatically.
</Update>

<Update label="2026-08-03" description="Native promo code endpoints">
  Promo codes are now a complete top-level REST resource and remain dual-served with the legacy proxy.

  * `GET /promo_codes` lists an account's promo codes and uses `account_id` instead of `company_id`.
  * `POST /promo_codes` creates promo codes; `GET` and `DELETE /promo_codes/{id}` retrieve and archive them.
  * `POST /promo_codes/{id}/activate` and `POST /promo_codes/{id}/deactivate` replace the legacy `PATCH` status write.
  * List responses use cursor pagination and support status, product, plan, timestamp, and sorting filters.
  * Callers pinned to earlier versions keep the legacy proxy contract unchanged.
</Update>

<Update label="2026-07-31" description="Richer parent accounts">
  Account responses now expose a richer parent account relationship for connected accounts.

  * `parent_account` replaces `parent_account_id`.
  * The parent account includes its `id`, `title`, `route`, and `logo_url`.
</Update>

<Update label="2026-07-29-1" description="Supported payout methods">
  Supported payout methods now have their own paginated endpoint.

  * `GET /payouts/supported_methods` lists the payout methods an account or user is eligible to add.
  * Supported methods use `object: "supported_payout_method"` and their `podst_` IDs are passed as `supported_payout_method_id`.
  * Saved payout methods expose `supported_payout_method`; payouts expose `payout_method.supported_payout_method`.
  * Use `country` to list supported methods for a country other than the payout account's country.
  * `GET /payouts/methods` no longer accepts `include_available` or returns `available_destinations`.
  * Callers pinned to earlier versions keep `destination_id`, `payout_destination`, and `payout_token`.
</Update>

<Update label="2026-07-29" description="Native card transactions, payout method arrival estimates">
  Card transactions now use native REST endpoints and remain dual-served with the legacy proxy.

  * `GET /card_transactions` lists an account's card transactions, and `GET /card_transactions/{id}` retrieves one by its `citx_` id. The list also takes a `transaction_ids` filter to fetch specific transactions in one request.
  * Card transactions are account-scoped: the owner is selected with `account_id`, defaulting to the account the credential belongs to.
  * Filters on `transaction_ids`, `card_id`, `cardholder_id`, `status`, `created_after`, and `created_before`. Timestamp filters are ISO 8601.
  * `cardholder_id` is new on the response: the user the card is assigned to.

  Payout methods now carry amount-independent fee and delivery terms, and the quote no longer duplicates arrival estimates.

  * Each payout method returns `fee_structure` (percentage, fixed amount, currency) and `estimated_arrival` (per-speed timestamps) without requiring an `amount`.
  * The quote's `standard` and `instant` objects no longer include `estimated_arrival`; read it from the method's top-level `estimated_arrival` field.
</Update>

<Update label="2026-07-27" description="Native resolution center endpoints">
  Resolution center cases now use native REST endpoints and remain dual-served with the legacy proxy.

  * `status`, `escalated`, `outcome`, `refund`, `reason`, and `available_actions` expose case state and permitted actions.
  * Events are available from paginated `GET /resolution_center_cases/{id}/events`; summaries are available from `GET /resolution_center_cases/summary`.
  * Writes use `message` and `attachments`; `due_date` is renamed `response_due_at`. Listing no longer requires `account_id`.
</Update>

<Update label="2026-07-26" description="Native shipments endpoints">
  Shipments now use native REST endpoints and remain dual-served with the legacy proxy.

  * `GET /shipments` lists shipments; `GET /shipments/{id}` retrieves by shipment id or payment id.
  * `POST /shipments` creates a shipment, and `PATCH /shipments/{id}` updates its tracking number.
  * Responses use `account_id` and `tracking_number`, alongside `carrier`, `tracking_url`, `order_id`, and `payment_id`.
  * Callers pinned before this date keep the legacy proxy contract unchanged.
</Update>

<Update label="2026-07-25" description="Native disputes endpoints">
  Disputes now use native REST endpoints and remain dual-served with the legacy proxy.

  * `PATCH /disputes/{id}` edits evidence, and `POST /disputes/{id}/submit` submits it. Evidence is nested under `evidence`.
  * `GET /disputes/summary` provides totals grouped by `status` and `currency`; list and retrieve return the same fields.
  * Responses use `account_id`, `product_id`, and `plan_id`, plus `buyer` alongside `payment`. Listing no longer requires `account_id`.
  * `status` and `reason` are normalized enums, and `needs_response_by`, `rdr`, and `editable` are replaced by their new fields.
  * Callers pinned before this date keep the legacy proxy contract unchanged.
</Update>

<Update label="2026-07-23" description="Members and memberships">
  Members and memberships now use native resources with an account-oriented membership model and redesigned lifecycle actions.

  * Membership responses return `plan_id` and `product_id` instead of nested `plan` and `product` objects.
  * Listing memberships returns everything the caller can read — their own plus their managed accounts' — and `account_id`/`user_id` narrow that list instead of switching modes or erroring.
  * Set `cancel_at_period_end` to schedule cancellation; the `cancel` action ends access immediately.
  * The `extend` action replaces `add_free_days`.
</Update>

<Update label="2026-07-22" description="REST response and timestamp consistency">
  The Experimental API now uses consistent delete responses, timestamp inputs, and Account naming.

  * Delete endpoints for products, plans, checkout configurations, ads, ad groups, ad campaigns, social accounts, and bounty submissions return `{ id, deleted: true }` instead of a bare boolean.
  * Timestamp filters on products, plans, checkout configurations, transfers, and financial reports accept ISO 8601 only instead of also accepting epoch seconds.
  * Product responses return `account` instead of `company`.
</Update>

<Update label="2026-07-20" description="Partner business payout percentages">
  Partner businesses now expose separate payout rates for every income source.

  * `payout_percentage` is replaced by `payout_percentages`.
  * The nested object includes `sales`, `ad_spend`, `transfer`, and `card_interchange` rates.
</Update>

<Update label="2026-07-18" description="Products and checkout configurations">
  Products and checkout configurations now use the Account model consistently.

  * Product request parameters use `account_id` instead of `company_id`.
  * Checkout configuration requests use `account_id` at the top level and inside inline `plan` objects.
  * Checkout configuration responses return `account_id` instead of `company_id`.
</Update>

<Update label="2026-07-08-1" description="Checkout configuration timestamps">
  Checkout configuration timestamps now use the same format as the rest of the API.

  * `created_at` and `updated_at` are ISO 8601 strings instead of Unix epoch integers.
</Update>

<Update label="2026-07-08" description="User balances">
  User balances now provide a complete, structured balance summary.

  * The flat `total_usd` and `balances` fields are replaced by a nested `balance` object.
  * The summary separates cash, crypto, in-flight treasury deposits, and balances for accounts the user owns.
</Update>

<Update label="2026-07-01" description="Business referral earnings resources">
  Business referral earnings now identify the polymorphic resource that generated the earning.

  * `receipt` is replaced by `resource`.
  * `access_pass` is replaced by `product`.
  * Receipt-backed earnings return `resource.object: "receipt"` with receipt payment details.
  * The `resource` field can support additional earning resources in future versions without reusing receipt-specific fields.
</Update>

<Update label="2026-06-20" description="Business referrals resource">
  Business referral volume and earnings are now reported as reconciling groups.

  * `processing_volume`, `total_earnings`, `pending_payout`, and `completed_payout` are replaced by nested `volume_usd` and `earnings_usd` objects.
  * Earnings rename `base_amount`/`amount` to `transaction_amount_usd`/`commission_amount_usd` and express `payout_percentage` as a fraction.
</Update>

<Update label="2026-06-09" description="Plans resource">
  Plans now use the Account model consistently.

  * Request parameters and request bodies use `account_id` instead of `company_id`.
  * Plan responses return `account` instead of `company`.
</Update>

<Update label="2026-06-08" description="Users resource">
  User access requests now use the Account model consistently.

  * Request parameters and request bodies use `account_id` instead of `company_id`.
  * Response shapes are unchanged.
</Update>

<Update label="2025-01-01" description="Original version">
  The original Experimental API behavior before dated versioning existed.

  Requests without `Api-Version-Date` use this version so existing integrations keep working.
</Update>


# Cards
Source: https://docs.whop.com/api-reference/beta/cards/card



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.

## Endpoints

| Endpoint                                                                         | Request                                      |
| -------------------------------------------------------------------------------- | -------------------------------------------- |
| [List Card Transactions](/api-reference/beta/cards/list-card-transactions)       | <Badge>GET</Badge> `/card_transactions`      |
| [Retrieve Card Transaction](/api-reference/beta/cards/retrieve-card-transaction) | <Badge>GET</Badge> `/card_transactions/{id}` |
| [List Cards](/api-reference/beta/cards/list-cards)                               | <Badge>GET</Badge> `/cards`                  |
| [Create Card](/api-reference/beta/cards/create-card)                             | <Badge>POST</Badge> `/cards`                 |
| [Retrieve Card](/api-reference/beta/cards/retrieve-card)                         | <Badge>GET</Badge> `/cards/{card_id}`        |
| [Update Card](/api-reference/beta/cards/update-card)                             | <Badge>PATCH</Badge> `/cards/{card_id}`      |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Card ID, prefixed `icrd_`.
    </ResponseField>

    <ResponseField name="billing" type="object | null">
      The billing address.

      <Accordion title="Properties">
        <ResponseField name="city" type="string | null">
          Billing city.
        </ResponseField>

        <ResponseField name="country_code" type="string | null">
          Billing country code.
        </ResponseField>

        <ResponseField name="line1" type="string | null">
          Street address line 1.
        </ResponseField>

        <ResponseField name="line2" type="string | null">
          Street address line 2.
        </ResponseField>

        <ResponseField name="postal_code" type="string | null">
          Billing postal code.
        </ResponseField>

        <ResponseField name="region" type="string | null">
          Billing region or state.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="canceled_at" type="string | null">
      When the card was canceled.
    </ResponseField>

    <ResponseField name="created_at" type="string | null">
      When the card was created.
    </ResponseField>

    <ResponseField name="expiration_month" type="string | null">
      Card expiration month.
    </ResponseField>

    <ResponseField name="expiration_year" type="string | null">
      Card expiration year.
    </ResponseField>

    <ResponseField name="last4" type="string | null">
      Last four digits of the card number. `null` for pending invitation cards.
    </ResponseField>

    <ResponseField name="limit" type="object | null">
      The spending limit configuration.

      <Accordion title="Properties">
        <ResponseField name="amount" type="number">
          The limit amount in dollars.
        </ResponseField>

        <ResponseField name="frequency" type="string">
          The window the limit amount applies to. `per_transaction` caps each individual authorization and is what a limit set with `transaction_limit` reports.

          Available options: `daily`, `weekly`, `monthly`, `one_time`, `per_transaction`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="name" type="string | null">
      Card display name.
    </ResponseField>

    <ResponseField name="object" type="string" />

    <ResponseField name="secrets" type="object | null">
      Sensitive card details. Present only on `GET /cards/:card_id` for active cards; `null` when the card is inactive or details cannot be retrieved.

      <Accordion title="Properties">
        <ResponseField name="card_number" type="string">
          Full card number.
        </ResponseField>

        <ResponseField name="cvc" type="string">
          Card verification code.
        </ResponseField>

        <ResponseField name="name_on_card" type="string | null">
          Cardholder name printed on the card.
        </ResponseField>

        <ResponseField name="pin" type="string | null">
          The card PIN. Only returned when the request is authenticated as the user the card is assigned to; `null` for all other callers, including account API keys.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="spent_last_month" type="integer | null">
      Total spend in the last 30 days, in cents.
    </ResponseField>

    <ResponseField name="status" type="string | null">
      The card status. `denied` means the issuer declined the cardholder, so the card will never be issued.

      Available options: `active`, `frozen`, `canceled`, `invited`, `denied`
    </ResponseField>

    <ResponseField name="type" type="string | null">
      The card type.

      Available options: `virtual`, `physical`
    </ResponseField>

    <ResponseField name="user_id" type="string | null">
      Cardholder user ID, prefixed `user_`, when assigned.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Card theme={null}
      {
      	"id": "icrd_xxxxxxxxxxxxx",
      	"billing": {
      		"city": "New York",
      		"country_code": "US",
      		"line1": "123 Spring Street",
      		"line2": "Suite 4",
      		"postal_code": "10012",
      		"region": "NY"
      	},
      	"canceled_at": null,
      	"created_at": "2026-06-01T12:00:00Z",
      	"expiration_month": "12",
      	"expiration_year": "2029",
      	"last4": "4242",
      	"limit": {
      		"amount": 500,
      		"frequency": "daily"
      	},
      	"name": "Operations Card",
      	"object": "card",
      	"secrets": {
      		"card_number": "4242424242424242",
      		"cvc": "123",
      		"name_on_card": "Pickaxe Operations",
      		"pin": "1234"
      	},
      	"spent_last_month": 12500,
      	"status": "active",
      	"type": "virtual",
      	"user_id": "user_xxxxxxxxxxxxx"
      }
      ```
    </div>
  </Column>
</Columns>


# Card application approved
Source: https://docs.whop.com/api-reference/beta/cards/card-application-approved

/openapi/api-v1-native.json webhook card_application.approved
Sent when a card application is approved

Required permissions:
 - `webhook_receive:card_applications`



# Card application created
Source: https://docs.whop.com/api-reference/beta/cards/card-application-created

/openapi/api-v1-native.json webhook card_application.created
Sent when a card application is created

Required permissions:
 - `webhook_receive:card_applications`



# Card application denied
Source: https://docs.whop.com/api-reference/beta/cards/card-application-denied

/openapi/api-v1-native.json webhook card_application.denied
Sent when a card application is denied

Required permissions:
 - `webhook_receive:card_applications`



# Card application updated
Source: https://docs.whop.com/api-reference/beta/cards/card-application-updated

/openapi/api-v1-native.json webhook card_application.updated
Sent when a card application is updated

Required permissions:
 - `webhook_receive:card_applications`



# Card canceled
Source: https://docs.whop.com/api-reference/beta/cards/card-canceled

/openapi/api-v1-native.json webhook card.canceled
Sent when a card is canceled

Required permissions:
 - `webhook_receive:cards`



# Card created
Source: https://docs.whop.com/api-reference/beta/cards/card-created

/openapi/api-v1-native.json webhook card.created
Sent when a card is created

Required permissions:
 - `webhook_receive:cards`



# Card frozen
Source: https://docs.whop.com/api-reference/beta/cards/card-frozen

/openapi/api-v1-native.json webhook card.frozen
Sent when a card is frozen

Required permissions:
 - `webhook_receive:cards`



# Card updated
Source: https://docs.whop.com/api-reference/beta/cards/card-updated

/openapi/api-v1-native.json webhook card.updated
Sent when a card is updated

Required permissions:
 - `webhook_receive:cards`



# Cardtransaction completed
Source: https://docs.whop.com/api-reference/beta/cards/cardtransaction-completed

/openapi/api-v1-native.json webhook card_transaction.completed
Sent when a card transaction is completed

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Cardtransaction created
Source: https://docs.whop.com/api-reference/beta/cards/cardtransaction-created

/openapi/api-v1-native.json webhook card_transaction.created
Sent when a card transaction is created

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Cardtransaction declined
Source: https://docs.whop.com/api-reference/beta/cards/cardtransaction-declined

/openapi/api-v1-native.json webhook card_transaction.declined
Sent when a card transaction is declined

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Cardtransaction reversed
Source: https://docs.whop.com/api-reference/beta/cards/cardtransaction-reversed

/openapi/api-v1-native.json webhook card_transaction.reversed
Sent when a card transaction is reversed

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Cardtransaction updated
Source: https://docs.whop.com/api-reference/beta/cards/cardtransaction-updated

/openapi/api-v1-native.json webhook card_transaction.updated
Sent when a card transaction is updated

Required permissions:
 - `payout:account:read`
 - `webhook_receive:card_transactions`



# Create Card
Source: https://docs.whop.com/api-reference/beta/cards/create-card

/openapi/api-v1-native.json post /cards
Issue a virtual card, or apply for card issuing.



# List Card Transactions
Source: https://docs.whop.com/api-reference/beta/cards/list-card-transactions

/openapi/api-v1-native.json get /card_transactions
Lists an account's card transactions, newest first. Defaults to the account the credential belongs to. Covers every card the owner has ever had, including canceled cards and spend that predates a re-application, and team members only see transactions on the cards assigned to them. Pass `transaction_ids` to fetch specific transactions instead of paging for them.



# List Cards
Source: https://docs.whop.com/api-reference/beta/cards/list-cards

/openapi/api-v1-native.json get /cards
Lists the Whop cards of an account or user, including ones still being set up. Team members only see the cards assigned to them.



# Retrieve Card
Source: https://docs.whop.com/api-reference/beta/cards/retrieve-card

/openapi/api-v1-native.json get /cards/{card_id}
Retrieve a single card.



# Retrieve Card Transaction
Source: https://docs.whop.com/api-reference/beta/cards/retrieve-card-transaction

/openapi/api-v1-native.json get /card_transactions/{id}
Fetches a single card transaction by its `citx_` identifier. The owner defaults to the account the credential belongs to.



# Update Card
Source: https://docs.whop.com/api-reference/beta/cards/update-card

/openapi/api-v1-native.json patch /cards/{card_id}
Update, freeze, or cancel a card. Updating the card's name, billing address, or limits requires both `payout:account:update` and `company:balance:read`; a card's assigned holder may update their own card's pin and frozen state with any user token.



# Create Deposit
Source: https://docs.whop.com/api-reference/beta/deposits/create-deposit

/openapi/api-v1-native.json post /deposits
Retrieve the deposit methods for an account, including crypto and bank transfer.



# Deposits
Source: https://docs.whop.com/api-reference/beta/deposits/deposit



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.

## Endpoints

| Endpoint                                                      | Request                         |
| ------------------------------------------------------------- | ------------------------------- |
| [Create Deposit](/api-reference/beta/deposits/create-deposit) | <Badge>POST</Badge> `/deposits` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="account_id" type="string | null">
      Account ID of the destination owner. Null for raw wallet address destinations.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Requested deposit amount.
    </ResponseField>

    <ResponseField name="hosted_url" type="string | null">
      URL of the hosted deposit page. Only present for business destinations.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Metadata from the request.
    </ResponseField>

    <ResponseField name="methods" type="object">
      Available deposit methods for destination.

      <Accordion title="Properties">
        <ResponseField name="bank" type="object | null">
          Bank deposit details. Only present when bank deposits are active for the destination account.

          <Accordion title="Properties">
            <ResponseField name="currencies" type="object[]">
              Bank transfer currencies available for this deposit.

              <Accordion title="Properties">
                <ResponseField name="account_number" type="string | null">
                  Bank account number for deposits in this currency.
                </ResponseField>

                <ResponseField name="currency" type="string">
                  Currency supported by these bank instructions.
                </ResponseField>

                <ResponseField name="deposit_bank_address" type="string | null">
                  Receiving bank address.
                </ResponseField>

                <ResponseField name="deposit_bank_name" type="string | null">
                  Receiving bank name.
                </ResponseField>

                <ResponseField name="deposit_beneficiary_name" type="string | null">
                  Beneficiary name to use for transfer.
                </ResponseField>

                <ResponseField name="deposit_reference" type="string | null">
                  Reference to include with bank transfer.
                </ResponseField>

                <ResponseField name="rails" type="string[]">
                  Active deposit rails for this currency.

                  Available options: `ach`, `wire`, `sepa`, `fps`, `chaps`
                </ResponseField>

                <ResponseField name="routing_number" type="string | null">
                  Bank routing number for deposits in this currency.
                </ResponseField>

                <ResponseField name="swift_bic" type="string | null">
                  SWIFT/BIC code for international wires, when available.
                </ResponseField>
              </Accordion>
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="crypto" type="object[]">
          Crypto networks available for this deposit, each with its on-chain deposit address and the tokens accepted on that network.

          <Accordion title="Properties">
            <ResponseField name="deposit_address" type="string | null">
              Address to send funds to on this network. Null when the provider has not
              issued one yet.
            </ResponseField>

            <ResponseField name="icon_url" type="string | null">
              Network icon URL.
            </ResponseField>

            <ResponseField name="name" type="string">
              Network display name.

              Available options: `Ethereum`, `Solana`, `Base`, `BNB Smart Chain`, `Hyperliquid`, `Hypercore`, `MegaETH`, `Polygon`, `Plasma`, `Arbitrum`
            </ResponseField>

            <ResponseField name="supported_currencies" type="object[]">
              Tokens accepted for deposit on this network.

              <Accordion title="Properties">
                <ResponseField name="icon_url" type="string | null">
                  Token icon URL. Null when no icon is available.
                </ResponseField>

                <ResponseField name="name" type="string">
                  Token symbol.

                  Available options: `ARB`, `BNB`, `ETH`, `EURC`, `HYPE`, `PYUSD`, `SOL`, `USD1`, `USDC`, `USDC.e`, `USDG`, `USDT`, `USDT0`, `USDe`, `USDm`, `XO`, `XPL`, `pUSD`, `wETH`
                </ResponseField>
              </Accordion>
            </ResponseField>
          </Accordion>
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="object" type="string" />
  </Column>

  <Column>
    <div>
      ```json Deposit theme={null}
      {
      	"account_id": "biz_xxxxxxxxxxxxxx",
      	"amount": "250.00",
      	"hosted_url": "https://whop.com/deposit/example/?amount=250.00",
      	"metadata": {},
      	"methods": {
      		"bank": {
      			"currencies": [
      				{
      					"account_number": "123456789012",
      					"currency": "usd",
      					"deposit_bank_address": "885 Example Road, Teaneck, NJ 07666",
      					"deposit_bank_name": "Example Bank",
      					"deposit_beneficiary_name": "Example Business Inc.",
      					"deposit_reference": "WHOPDEP123",
      					"rails": ["ach", "wire"],
      					"routing_number": "021000021",
      					"swift_bic": "EXAMUS33XXX"
      				}
      			]
      		},
      		"crypto": [
      			{
      				"deposit_address": "0x1234abcd5678ef901234abcd5678ef901234abcd",
      				"icon_url": "https://whop.com/images/networks/ethereum.png",
      				"name": "Ethereum",
      				"supported_currencies": [
      					{
      						"icon_url": "https://whop.com/images/tokens/usdc.png",
      						"name": "USDC"
      					}
      				]
      			}
      		]
      	},
      	"object": "deposit"
      }
      ```
    </div>
  </Column>
</Columns>


# Deposit succeeded
Source: https://docs.whop.com/api-reference/beta/deposits/deposit-succeeded

/openapi/api-v1-native.json webhook deposit.succeeded
Sent when a deposit is succeeded

Required permissions:
 - `webhook_receive:deposits`



# Dispute created
Source: https://docs.whop.com/api-reference/beta/disputes/dispute-created

/openapi/api-v1-native.json webhook dispute.created
Sent when a dispute is created

Required permissions:
 - `payment:dispute:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `company:basic:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `webhook_receive:disputes`



# Dispute updated
Source: https://docs.whop.com/api-reference/beta/disputes/dispute-updated

/openapi/api-v1-native.json webhook dispute.updated
Sent when a dispute is updated

Required permissions:
 - `payment:dispute:read`
 - `plan:basic:read`
 - `access_pass:basic:read`
 - `company:basic:read`
 - `payment:basic:read`
 - `member:email:read`
 - `member:basic:read`
 - `member:phone:read`
 - `webhook_receive:disputes`



# List Disputes
Source: https://docs.whop.com/api-reference/beta/disputes/list-disputes

/openapi/api-v1-native.json get /disputes
Lists the disputes across the accounts you can read.



# Retrieve Dispute
Source: https://docs.whop.com/api-reference/beta/disputes/retrieve-dispute

/openapi/api-v1-native.json get /disputes/{id}
Retrieves a single dispute.



# Retrieve Dispute Summary
Source: https://docs.whop.com/api-reference/beta/disputes/retrieve-dispute-summary

/openapi/api-v1-native.json get /disputes/summary
Totals up the same disputes the list returns, so you can build status tabs and totals without paging through them.



# Submit Dispute
Source: https://docs.whop.com/api-reference/beta/disputes/submit-dispute

/openapi/api-v1-native.json post /disputes/{id}/submit
Sends a dispute's evidence to the payment processor. This is final — it cannot be edited or sent again.



# Update Dispute
Source: https://docs.whop.com/api-reference/beta/disputes/update-dispute

/openapi/api-v1-native.json patch /disputes/{id}
Edits a dispute's evidence, while it is still editable. Sending it is a separate call.



# Create Export
Source: https://docs.whop.com/api-reference/beta/exports/create-export

/openapi/api-v1-native.json post /exports
Starts an asynchronous CSV export of a resource for an account. Returns the export in `pending`; poll `GET /exports/{id}` until `download_url` is set.



# Export completed
Source: https://docs.whop.com/api-reference/beta/exports/export-completed

/openapi/api-v1-native.json webhook export.completed
Sent when a export is completed

Required permissions:
 - `webhook_receive:exports`



# Export failed
Source: https://docs.whop.com/api-reference/beta/exports/export-failed

/openapi/api-v1-native.json webhook export.failed
Sent when a export is failed

Required permissions:
 - `webhook_receive:exports`



# List Exports
Source: https://docs.whop.com/api-reference/beta/exports/list-exports

/openapi/api-v1-native.json get /exports
Lists the exports requested for an account, newest first. Only exports of resources the credential is allowed to export are returned.



# Retrieve Export
Source: https://docs.whop.com/api-reference/beta/exports/retrieve-export

/openapi/api-v1-native.json get /exports/{id}
Fetches an export's status and, once complete, its download link.



# Get Financial Report
Source: https://docs.whop.com/api-reference/beta/ledgers/get-financial-report

/openapi/api-v1-native.json get /financial_reports
Returns a financial report — balance activity, income statement, or balance summary — for an account over a date range.



# Ledger Activity
Source: https://docs.whop.com/api-reference/beta/ledgers/ledger-activity



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.

## Endpoints

| Endpoint                                                                       | Request                                  |
| ------------------------------------------------------------------------------ | ---------------------------------------- |
| [Get Financial Report](/api-reference/beta/ledgers/get-financial-report)       | <Badge>GET</Badge> `/financial_reports`  |
| [List Financial Activity](/api-reference/beta/ledgers/list-financial-activity) | <Badge>GET</Badge> `/financial-activity` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Ledger activity ID.
    </ResponseField>

    <ResponseField name="account" type="account or user">
      The viewer account that owns this row's ledger. Present only when the response
      aggregates owned accounts (include\_owned\_accounts=true); omitted otherwise.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Signed amount in the currency's smallest precision units.
    </ResponseField>

    <ResponseField name="available_at" type="string | null">
      ISO 8601 timestamp these funds became (or are scheduled to become)
      withdrawable: the posted time for already-settled funds, or 00:00:00 UTC on
      the scheduled release date for pending funds. Present only on inflows entering
      the balance (payments, top-ups, incoming transfers/affiliate); null on
      withdrawals, refunds, disputes and on-chain rows. The available\_after/before
      filters window on its UTC settlement date.
    </ResponseField>

    <ResponseField name="created_at" type="string | null">
      When the activity record was created.
    </ResponseField>

    <ResponseField name="currency" type="object">
      Currency for this ledger activity.

      <Accordion title="Properties">
        <ResponseField name="code" type="string">
          Currency code.
        </ResponseField>

        <ResponseField name="precision" type="string">
          Precision factor for the currency, for example `100000000` for USD.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="ledger_account_id" type="string | null">
      The ledger account (a ldgr\_ identifier) this row belongs to. Present only when
      the response aggregates owned accounts (include\_owned\_accounts=true); omitted
      otherwise. Pair it with `account` to scope drawers and dashboard links to the
      owning business.
    </ResponseField>

    <ResponseField name="line_type" type="string">
      The ledger line category this activity was posted under.

      Available options: `ad_budget_release`, `ad_campaign_budget`, `ad_publisher_payout`, `ad_publisher_payout_received`, `ad_spend_charge`, `affiliate_fee`, `airdrop`, `airdrop_link_created`, `airdrop_link_redeemed`, `airdrop_link_returned`, `airdrop_reversal`, `application_fee`, `application_fee_payout`, `bank_transfer`, `billing_percentage_fee`, `buyer_fee`, `card_spend_authorization`, `card_spend_authorization_void`, `card_spend_refund`, `company_referral`, `cross_border_percentage_fee`, `currency_conversion_incoming`, `currency_conversion_outgoing`, `dispute_alert_fee`, `dispute_hold_adjustment`, `fraud_prevention_fee`, `fx_percentage_fee`, `high_risk_merchant_fee`, `installment_default`, `internal_balance_transfer_incoming`, `internal_balance_transfer_outgoing`, `legacy_crypto_payment`, `legacy_payment`, `legacy_payment_refund`, `license_sale`, `license_sale_commission`, `license_sale_revenue`, `misc_purchase`, `misc_refund`, `misc_reversal`, `onchain_deposit`, `onchain_swap_target`, `onchain_wallet_transfer_incoming`, `onchain_wallet_transfer_outgoing`, `orchestration_percentage_fee`, `passthrough_gmv`, `payment_dispute`, `payment_dispute_adjustment`, `payment_dispute_fee`, `payment_dispute_reversal`, `payment_gross`, `payment_gross_reversal`, `payment_processing_fixed_fee`, `payment_processing_percentage_fee`, `payment_referral`, `payment_referral_reversal`, `payment_refund`, `payment_refund_reversal`, `payment_revshare`, `payment_revshare_payout`, `payment_revshare_refund`, `payment_revshare_reversal`, `payout_fee`, `platform_affiliate_payment`, `platform_affiliate_payment_reversal`, `platform_balance_payment`, `platform_balance_payment_refund`, `platform_balance_transfer_incoming`, `platform_balance_transfer_outgoing`, `platform_covered_dispute`, `promo_reversal`, `referral_bonus`, `resolution_center_refund`, `revshare_percentage_fee`, `sales_tax_fee`, `sales_tax_remittance`, `sales_tax_remittance_reversal`, `software_rental_revshare`, `software_rental_transaction`, `stripe_domestic_processing_fee`, `stripe_international_processing_fee`, `three_ds_fixed_fee`, `topup`, `topup_fee`, `topup_reversal`, `treasury_payin`, `whop_processing_fee`, `withdrawal`, `withdrawal_clawback`, `withdrawal_clawback_reversal`, `withdrawal_reclassification`, `withdrawal_reversal`
    </ResponseField>

    <ResponseField name="object" type="string" />

    <ResponseField name="posted_at" type="string">
      When the activity posted to the ledger.
    </ResponseField>

    <ResponseField name="resource" type="account or user or bounty or ledger_account or payment_method or payout_method or card_transaction | null">
      Resource associated with this ledger activity.
    </ResponseField>

    <ResponseField name="source" type="object | null">
      Source of this ledger activity.

      <Accordion title="Properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="amount_float" type="number | null">
          Withdrawal amount as a decimal number in the destination currency (withdrawal
          sources only; requires payout:withdrawal:read).
        </ResponseField>

        <ResponseField name="chain" type="string | null">
          Chain the deposit landed on, for example plasma (onchain\_transaction sources
          only).
        </ResponseField>

        <ResponseField name="claim_url" type="string | null">
          Public claim URL for the airdrop link (airdrop\_link sources only).
        </ResponseField>

        <ResponseField name="created_at" type="string | null">
          Withdrawal creation time as an ISO 8601 timestamp (withdrawal sources only;
          requires payout:withdrawal:read).
        </ResponseField>

        <ResponseField name="estimated_arrival" type="string | null">
          Estimated arrival as an ISO 8601 timestamp (withdrawal sources only; requires
          payout:withdrawal:read).
        </ResponseField>

        <ResponseField name="from_amount" type="string | null">
          Amount converted out of from\_currency as a decimal string (swap sources only).
        </ResponseField>

        <ResponseField name="from_currency" type="string | null">
          Lowercase currency code converted from (swap sources only).
        </ResponseField>

        <ResponseField name="object" type="string" />

        <ResponseField name="payer_name" type="string | null">
          Name of the entity processing the payout (withdrawal sources only; requires
          payout:withdrawal:read).
        </ResponseField>

        <ResponseField name="payout_destination" type="object | null">
          Payout destination display info (withdrawal sources only).

          <Accordion title="Properties">
            <ResponseField name="icon_url" type="string | null" />

            <ResponseField name="payer_name" type="string | null" />
          </Accordion>
        </ResponseField>

        <ResponseField name="payout_token_nickname" type="string | null">
          Saved payout destination nickname (withdrawal sources only).
        </ResponseField>

        <ResponseField name="reason" type="string | null">
          Why the activity happened. On transfer sources this is the transfer reason,
          for example pool\_top\_up or bounty\_return. On withdrawal sources it explains
          why the withdrawal was canceled, denied, or failed (requires
          payout:withdrawal:read); null while the withdrawal is progressing normally.
        </ResponseField>

        <ResponseField name="sender_address" type="string | null">
          Sender wallet address or onramp provider identifier (onchain\_transaction
          sources only).
        </ResponseField>

        <ResponseField name="status" type="string | null">
          Lifecycle status. On withdrawal sources this is the withdrawal status
          (requires payout:withdrawal:read); on airdrop\_link sources it is the
          claim-link status (ungated); on payment and top-up sources it is the friendly
          payment status such as succeeded/pending/failed (ungated).
        </ResponseField>

        <ResponseField name="to_amount" type="string | null">
          Amount received in to\_currency as a decimal string (swap sources only).
        </ResponseField>

        <ResponseField name="to_currency" type="string | null">
          Lowercase currency code converted to (swap sources only).
        </ResponseField>

        <ResponseField name="tx_hash" type="string | null">
          On-chain transaction hash (onchain\_transaction and swap sources only).
        </ResponseField>
      </Accordion>
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json LedgerActivity theme={null}
      {
      	"id": "line_cGF5bWVudF9ncm9zczpsaTpwZXRhbHBvc3Q6YWM6bGVkZ2VyOmxlOjE6djppazpyZWNlaXB0",
      	"object": "ledger_activity",
      	"line_type": "payment_gross",
      	"amount": "4800000000",
      	"currency": {
      		"code": "usd",
      		"precision": "100000000"
      	},
      	"posted_at": "2026-06-14T18:49:49Z",
      	"available_at": "2026-06-17T00:00:00Z",
      	"created_at": "2026-06-14T18:49:49Z",
      	"resource": {
      		"id": "user_4Hk2mZ9qLpXa",
      		"object": "user",
      		"name": "Jordan Avery",
      		"username": "jordanavery",
      		"profile_picture_url": "https://cdn.whop.com/users/jordan-avery.png"
      	},
      	"source": {
      		"id": "pay_8QcR2mZ9qLpXa",
      		"object": "payment"
      	},
      	"account": {
      		"id": "biz_9dCwK2mZ9qLpXa",
      		"object": "account",
      		"title": "Acme Studios",
      		"route": "acme-studios",
      		"logo_url": "https://cdn.whop.com/companies/acme-studios.png"
      	},
      	"ledger_account_id": "ldgr_7bQx2mZ9qLpXa"
      }
      ```
    </div>
  </Column>
</Columns>

## Glossary of line types

Every activity row carries a `line_type` that names the financial event it represents. Pass one or more `line_types` to [List Financial Activity](/api-reference/beta/ledgers/list-financial-activity) to filter the feed to specific events — either as repeated `line_types[]` parameters or as a single comma-separated value (`line_types=payment_gross,payment_refund`). Unknown line types return a `400`.

Throughout this glossary, "LPM" means a local payment method (a non-card method such as a bank debit or wallet).

### Categories

In place of listing individual line types, you can pass a category shorthand. A category expands to every line type it contains.

| Category | Expands to                                                                      |
| -------- | ------------------------------------------------------------------------------- |
| `fees`   | All processing-fee line types — every entry in the [Fees](#fees) section below. |

### Payments

| Line type                  | Description                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `payment_gross`            | A card or LPM sale settling into the wallet — the gross amount before fees.                                        |
| `topup`                    | Funds the account added to its own wallet balance, rather than a product sale.                                     |
| `platform_balance_payment` | A purchase paid for with existing wallet balance instead of an external card or LPM.                               |
| `passthrough_gmv`          | Recorded GMV for a purchase made through an external processor (Stripe Standard, PayPal, Coinbase Commerce, etc.). |
| `installment_default`      | A charge to the wallet covering a buyer's defaulted Buy Now, Pay Later installment.                                |

### Refunds

| Line type                         | Description                                                                          |
| --------------------------------- | ------------------------------------------------------------------------------------ |
| `payment_refund`                  | A refund of a card or LPM payment, deducted from the wallet.                         |
| `payment_refund_reversal`         | Reverses a `payment_refund`, returning the funds to the wallet.                      |
| `platform_balance_payment_refund` | A refund of a wallet-balance purchase, returned to the original purchaser's balance. |

### Disputes

| Line type                    | Description                                                                                                                |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `payment_dispute`            | A chargeback on a card or LPM payment, debited from the wallet.                                                            |
| `payment_dispute_adjustment` | A credit or debit that adjusts a chargeback when the disputed amount differs from the original payment (partial disputes). |
| `payment_dispute_reversal`   | Reverses a `payment_dispute` when the dispute is won.                                                                      |
| `platform_covered_dispute`   | The portion of a chargeback Whop's marketplace covers when the sale carried a buyer fee; can be a credit or a debit.       |
| `dispute_hold_adjustment`    | Moves funds into or out of a dispute hold — debited when a hold is placed, credited when it is released.                   |

### Reserves

| Line type             | Description                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `psp_reserve_hold`    | A payment processor withholds part of a settlement in reserve, making those funds unavailable until released. |
| `psp_reserve_release` | A payment processor returns previously withheld reserve funds to the available settlement balance.            |

### Withdrawals

| Line type                      | Description                                                                                                                        |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `withdrawal`                   | A payout of wallet funds to an external bank account.                                                                              |
| `withdrawal_reversal`          | Reverses a withdrawal that was canceled or rejected, returning the funds to the wallet.                                            |
| `withdrawal_clawback`          | A credit to the wallet that recovers funds from the linked bank account to cover a negative balance.                               |
| `withdrawal_clawback_reversal` | Reverses a `withdrawal_clawback` when the clawback later fails or is returned by the bank.                                         |
| `withdrawal_reclassification`  | Returns a withdrawal's net amount to the wallet's available balance when that payout is reclassified as an internal Whop transfer. |

### Transfers

| Line type                            | Description                                                                                                        |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `platform_balance_transfer_outgoing` | A transfer of wallet funds out to another account on the platform.                                                 |
| `platform_balance_transfer_incoming` | A transfer of funds into the wallet from another account on the platform.                                          |
| `internal_balance_transfer_outgoing` | A transfer out to another wallet owned by the same entity, such as primary to pool; not counted as revenue.        |
| `internal_balance_transfer_incoming` | A transfer in from another wallet owned by the same entity, such as pool funded by parent; not counted as revenue. |

### Currency conversion

| Line type                      | Description                                                                          |
| ------------------------------ | ------------------------------------------------------------------------------------ |
| `currency_conversion_outgoing` | The source-currency debit when wallet balance is converted between currencies.       |
| `currency_conversion_incoming` | The destination-currency credit when wallet balance is converted between currencies. |

### Affiliates & revenue share

| Line type                             | Description                                                                                                             |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `payment_referral`                    | An affiliate referral bonus the merchant chose to share from a card or LPM payment, credited to the affiliate's wallet. |
| `payment_referral_reversal`           | Reverses a previously paid referral bonus, debited from the affiliate's wallet.                                         |
| `payment_revshare`                    | A revenue-share amount debited from the seller's wallet on a payment.                                                   |
| `payment_revshare_payout`             | A revenue-share amount credited to an affiliate's wallet on a payment.                                                  |
| `payment_revshare_reversal`           | Reverses a previously paid revenue share, debited from the affiliate's wallet.                                          |
| `payment_revshare_refund`             | Returns a revenue-share amount to the seller's wallet when the payment is refunded or disputed.                         |
| `application_fee_payout`              | A platform fee from a connected-account payment, settled into the parent account.                                       |
| `platform_affiliate_payment`          | A referral bonus for referring an account or buyer to Whop: a share of the processing revenue that account generated.   |
| `platform_affiliate_payment_reversal` | Reverses a `platform_affiliate_payment` that Whop determined was invalid or needed correction.                          |
| `ad_publisher_payout_received`        | A credit to a publisher's wallet for ad revenue earned.                                                                 |
| `ad_publisher_payout`                 | A payout of ad revenue, debited from the Whop Ads wallet.                                                               |
| `company_referral`                    | Legacy: a referral bonus for referring an account to Whop, sharing the processing revenue that account generated.       |

### Airdrops

| Line type                  | Description                                                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `airdrop`                  | A credit of funds into the wallet at Whop's expense, typically promotional or to make good on an issue.           |
| `airdrop_reversal`         | Reverses an `airdrop` found to be invalid or in need of correction.                                               |
| `airdrop_link_created`     | Debits the wallet to fund a newly created airdrop link.                                                           |
| `airdrop_link_returned`    | Returns an airdrop link's funds to the sender's available balance when the link is canceled.                      |
| `airdrop_link_redeemed`    | Credits a claimed airdrop link's funds into the recipient's available balance.                                    |
| `resolution_center_refund` | A refund to a buyer that Whop covers out of pocket after resolving a Resolution Center case in the buyer's favor. |

### Advertising

| Line type            | Description                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `ad_campaign_budget` | Earmarks funds for an ad campaign when the campaign is funded.                            |
| `ad_spend_charge`    | A charge against earmarked campaign funds for ad spend, billed at the marked-up rate.     |
| `ad_budget_release`  | Releases unspent campaign budget, typically the first step of a refund or balance return. |

### Crypto & cards

<Note>
  `onchain_deposit` is opt-in: it is excluded from the default feed and only
  returned when you request it explicitly in `line_types`.
</Note>

| Line type                          | Description                                                                                                                                                  |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `onchain_deposit`                  | An inbound on-chain crypto transfer credited to a Whop-managed wallet (including onramps such as MoonPay). Opt-in — only returned when explicitly requested. |
| `onchain_wallet_transfer_outgoing` | An outbound on-chain transfer from a Whop-managed crypto wallet to another Whop-managed wallet.                                                              |
| `onchain_wallet_transfer_incoming` | An inbound on-chain transfer to a Whop-managed crypto wallet from another Whop-managed wallet.                                                               |
| `onchain_swap_target`              | The received side of an on-chain token swap — the output token credited to the wallet.                                                                       |
| `treasury_payin`                   | A credit to the cash wallet from a treasury pay-in, such as a crypto off-ramp moving stablecoin balance back into cash.                                      |
| `card_spend_authorization`         | A card authorization hold, debited from the card balance when a spend is authorized.                                                                         |
| `card_spend_authorization_void`    | Returns a card authorization to the card balance when it is voided, expired, or declined after auth.                                                         |
| `card_spend_refund`                | A merchant refund credited back to the card balance.                                                                                                         |

### Legacy & miscellaneous

| Line type                     | Description                                                                                                                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legacy_crypto_payment`       | A historical Coinbase Commerce payment Whop processed and paid out to the merchant's wallet.                                                                                                      |
| `legacy_payment`              | A historical express-account payment credited directly to the user's wallet.                                                                                                                      |
| `legacy_payment_refund`       | Reverses a `legacy_payment`, debiting the merchant's wallet.                                                                                                                                      |
| `license_sale`                | The merchant payout for a multi-party software license sale — the sale amount net of fees. Commission and revenue shares post separately as `license_sale_commission` and `license_sale_revenue`. |
| `license_sale_commission`     | The commission portion of a software license sale, credited to the commission wallet.                                                                                                             |
| `license_sale_revenue`        | The revenue-share portion of a software license sale, credited to the revenue wallet.                                                                                                             |
| `software_rental_revshare`    | A revenue-share payout for a software rental, crediting the merchant net of fees.                                                                                                                 |
| `software_rental_transaction` | The final settlement of a software rental, crediting the merchant net of fees.                                                                                                                    |
| `misc_purchase`               | A purchase made directly from Whop, such as legacy software rentals or proxies.                                                                                                                   |
| `misc_refund`                 | A refund of a `misc_purchase`.                                                                                                                                                                    |
| `referral_bonus`              | A bonus for referring a new user to sign up for whop.com.                                                                                                                                         |
| `promo_reversal`              | A one-time reversal of promotional, non-withdrawable `referral_bonus` balance.                                                                                                                    |
| `misc_reversal`               | Legacy — a miscellaneous debit for charges negotiated outside the normal transaction lifecycle.                                                                                                   |

### Fees

| Line type                             | Description                                                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `payment_processing_fixed_fee`        | A fixed fee (≈\$0.30) for processing a card or LPM payment.                                            |
| `payment_processing_percentage_fee`   | A percentage fee, such as 2.7%, for processing a card or LPM payment.                                  |
| `billing_percentage_fee`              | A fee on recurring billing transactions covering subscription management and retries.                  |
| `cross_border_percentage_fee`         | A fee on cross-border transactions, charged when the buyer is outside the processing region.           |
| `fx_percentage_fee`                   | A fee for converting a payment processed in a foreign currency at settlement.                          |
| `orchestration_percentage_fee`        | A fee for routing a payment across multiple PSPs (smart routing and failover).                         |
| `revshare_percentage_fee`             | A fee for using revenue-share payouts on a payment.                                                    |
| `three_ds_fixed_fee`                  | A fixed fee for 3DS authentication, charged only when 3DS is required.                                 |
| `whop_processing_fee`                 | A platform fee for using whop.com, not tied directly to processing cost.                               |
| `fraud_prevention_fee`                | A fee for fraud prevention on card or LPM payments.                                                    |
| `buyer_fee`                           | A buyer fee booked as platform income, posted only when buyer fees are configured as platform revenue. |
| `sales_tax_fee`                       | A fee for Whop collecting and remitting sales tax on a payment.                                        |
| `sales_tax_remittance`                | Sales tax collected on a transaction that Whop remits to the tax authority.                            |
| `sales_tax_remittance_reversal`       | Reverses a `sales_tax_remittance` when a payment is refunded or disputed.                              |
| `affiliate_fee`                       | The portion of a card or LPM payment earmarked to pay an affiliate referral bonus.                     |
| `application_fee`                     | The platform fee from a connected-account payment paid to the parent account.                          |
| `payout_fee`                          | A fee covering the cost of paying out to a bank account.                                               |
| `payment_dispute_fee`                 | A fee (≈\$15) for receiving a chargeback on a card or LPM payment.                                     |
| `dispute_alert_fee`                   | A fee for receiving an early dispute alert on a card or LPM payment.                                   |
| `stripe_domestic_processing_fee`      | Legacy — a fee for processing a card or LPM payment through Stripe domestically.                       |
| `stripe_international_processing_fee` | Legacy — a fee for processing a card or LPM payment through Stripe internationally.                    |


# List Financial Activity
Source: https://docs.whop.com/api-reference/beta/ledgers/list-financial-activity

/openapi/api-v1-native.json get /financial-activity
Returns an account's or user's activity feed: every movement of money in or out.



# List Member Logs
Source: https://docs.whop.com/api-reference/beta/members/list-member-logs

/openapi/api-v1-native.json get /members/{id}/logs
Lists activity for a member and all of their non-drafted memberships, most recent first.



# List Members
Source: https://docs.whop.com/api-reference/beta/members/list-members

/openapi/api-v1-native.json get /members
Lists the members of an account. A member is one buyer's relationship with the account, regardless of how many memberships they hold.



# Member
Source: https://docs.whop.com/api-reference/beta/members/member



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.

## Endpoints

| Endpoint                                                         | Request                                 |
| ---------------------------------------------------------------- | --------------------------------------- |
| [List Members](/api-reference/beta/members/list-members)         | <Badge>GET</Badge> `/members`           |
| [Retrieve Member](/api-reference/beta/members/retrieve-member)   | <Badge>GET</Badge> `/members/{id}`      |
| [List Member Logs](/api-reference/beta/members/list-member-logs) | <Badge>GET</Badge> `/members/{id}/logs` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Member ID, prefixed `mber_`.
    </ResponseField>

    <ResponseField name="access_level" type="string">
      What the member can reach on the account: `customer` for paying members, `admin` for team members, `no_access` once every grant has lapsed.

      Available options: `no_access`, `admin`, `customer`
    </ResponseField>

    <ResponseField name="account_id" type="string">
      The account this member belongs to, prefixed `biz_`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the member record was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="joined_at" type="string">
      When the member first joined the account, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="last_accessed_at" type="string | null">
      When the member last opened the account's content, as an ISO 8601 timestamp.
      `null` if they never have.
    </ResponseField>

    <ResponseField name="status" type="string">
      `joined` while the member is part of the account, `left` after they leave.

      Available options: `joined`, `left`
    </ResponseField>

    <ResponseField name="user" type="object | null">
      The user behind this member. `null` when the buyer is another business rather than a person.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          User ID, prefixed `user_`.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          Display name.
        </ResponseField>

        <ResponseField name="profile_picture" type="object">
          Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture.

          <Accordion title="Properties">
            <ResponseField name="url" type="string">
              Avatar image URL. Always present — a generated placeholder when the user set no picture.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="username" type="string">
          Public username.
        </ResponseField>
      </Accordion>
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Member theme={null}
      {
      	"id": "mber_xxxxxxxxxxxxx",
      	"account_id": "biz_xxxxxxxxxxxxxx",
      	"access_level": "customer",
      	"status": "joined",
      	"joined_at": "2026-07-01T00:00:00.000Z",
      	"last_accessed_at": "2026-07-20T15:30:00.000Z",
      	"created_at": "2026-07-01T00:00:00.000Z",
      	"user": {
      		"id": "user_xxxxxxxxxxxxx",
      		"username": "janedoe",
      		"name": "Jane Doe",
      		"profile_picture": {
      			"url": "https://cdn.whop.com/user.png"
      		}
      	}
      }
      ```
    </div>
  </Column>
</Columns>


# Member created
Source: https://docs.whop.com/api-reference/beta/members/member-created

/openapi/api-v1-native.json webhook member.created
Sent when a member is created

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `member:phone:read`
 - `webhook_receive:members`



# Retrieve Member
Source: https://docs.whop.com/api-reference/beta/members/retrieve-member

/openapi/api-v1-native.json get /members/{id}
Retrieves a member by ID. Accessible to the account and to the member's own user.



# List Notification Badges
Source: https://docs.whop.com/api-reference/beta/notifications/list-notification-badges

/openapi/api-v1-native.json get /notifications/badges
Lists the authenticated user's per-experience unread badge state. Requires a user credential. Returns one row per experience the user belongs to (or per requested experience).



# List Notification Topics
Source: https://docs.whop.com/api-reference/beta/notifications/list-notification-topics

/openapi/api-v1-native.json get /notifications/topics
Lists the platform's visible notification topics — the categories users can set notification preferences on. App-created topics are internal and not returned.



# List Notifications
Source: https://docs.whop.com/api-reference/beta/notifications/list-notifications

/openapi/api-v1-native.json get /notifications
Lists the authenticated user's notifications, newest first. Requires a user credential — an account API key has no notification feed. Without filters the feed spans every experience the user belongs to plus the teams they are a member of.



# Mark Notifications Read
Source: https://docs.whop.com/api-reference/beta/notifications/mark-notifications-read

/openapi/api-v1-native.json post /notifications/mark_read
Marks the authenticated user's notifications as read: one experience's (`experience_id`) or everything (`all: true`) — exactly one of the two. Requires a user credential. Responds with the refreshed badge rows for the affected scope.



# Retrieve Notification
Source: https://docs.whop.com/api-reference/beta/notifications/retrieve-notification

/openapi/api-v1-native.json get /notifications/{notification_id}
Retrieves a single notification by id — either an `id` returned by List Notifications, or the ephemeral id delivered with a push/websocket event. Requires a user credential.



# Send Notification
Source: https://docs.whop.com/api-reference/beta/notifications/send-notification

/openapi/api-v1-native.json post /notifications
Queues a notification to every user of an experience or to an account's team, processed asynchronously. Every send is attributed to an app: use an app API key, or a credential acting on behalf of an app. Narrow the audience with `user_ids` to send a mention.



# Retrieve payment status
Source: https://docs.whop.com/api-reference/beta/payments/retrieve-payment-status

/openapi/api-v1-native.json get /payments/{payment_id}/status
Retrieves how far a payment has got and what the buyer must do next, if anything. A payment is collected in the background, so poll this rather than reading the create response. Accepts either a secret key or the payment's own `client_secret`, so the surface collecting the payment can poll it directly.



# Update payment return URL
Source: https://docs.whop.com/api-reference/beta/payments/update-payment-return-url

/openapi/api-v1-native.json patch /payments/{payment_id}/return_url
Changes where the buyer lands after completing an off-site step, up until they return. Accepts either a secret key or the payment's own `client_secret`, so the surface that knows the final destination can set it.



# Create Payout
Source: https://docs.whop.com/api-reference/beta/payouts/create-payout

/openapi/api-v1-native.json post /payouts
Sends money from an account's or user's balance to one of its saved payout methods.



# Create Saved Payout Method
Source: https://docs.whop.com/api-reference/beta/payouts/create-saved-payout-method

/openapi/api-v1-native.json post /payouts/methods
Saves a new place an account or user can withdraw to. Sensitive details are vaulted in transit and never stored raw.



# Delete Saved Payout Method
Source: https://docs.whop.com/api-reference/beta/payouts/delete-saved-payout-method

/openapi/api-v1-native.json delete /payouts/methods/{payout_method_id}
Deletes a saved payout method so it can no longer receive payouts.



# List Payouts
Source: https://docs.whop.com/api-reference/beta/payouts/list-payouts

/openapi/api-v1-native.json get /payouts
Lists an account's or user's payouts, newest first.



# List Saved Payout Methods
Source: https://docs.whop.com/api-reference/beta/payouts/list-saved-payout-methods

/openapi/api-v1-native.json get /payouts/methods
Lists the bank accounts, wallets, and crypto addresses an account or user can withdraw to, newest first.



# List Supported Payout Methods
Source: https://docs.whop.com/api-reference/beta/payouts/list-supported-payout-methods

/openapi/api-v1-native.json get /payouts/supported_methods
Lists the payout methods an account or user is eligible to add.



# Payouts
Source: https://docs.whop.com/api-reference/beta/payouts/payout



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 payouts from accounts, list payout history for accounts or users, monitor payout statuses, and show expected arrival details for funds leaving Whop.

## Endpoints

| Endpoint                                                                                   | Request                                                     |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| [List Payouts](/api-reference/beta/payouts/list-payouts)                                   | <Badge>GET</Badge> `/payouts`                               |
| [Create Payout](/api-reference/beta/payouts/create-payout)                                 | <Badge>POST</Badge> `/payouts`                              |
| [Retrieve Payout](/api-reference/beta/payouts/retrieve-payout)                             | <Badge>GET</Badge> `/payouts/{payout_id}`                   |
| [List Saved Payout Methods](/api-reference/beta/payouts/list-saved-payout-methods)         | <Badge>GET</Badge> `/payouts/methods`                       |
| [Create Saved Payout Method](/api-reference/beta/payouts/create-saved-payout-method)       | <Badge>POST</Badge> `/payouts/methods`                      |
| [Rename Saved Payout Method](/api-reference/beta/payouts/rename-saved-payout-method)       | <Badge>PATCH</Badge> `/payouts/methods/{payout_method_id}`  |
| [Delete Saved Payout Method](/api-reference/beta/payouts/delete-saved-payout-method)       | <Badge>DELETE</Badge> `/payouts/methods/{payout_method_id}` |
| [List Supported Payout Methods](/api-reference/beta/payouts/list-supported-payout-methods) | <Badge>GET</Badge> `/payouts/supported_methods`             |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Payout ID.
    </ResponseField>

    <ResponseField name="amount" type="number">
      The payout amount in whole currency units.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the payout was created.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Payout currency.
    </ResponseField>

    <ResponseField name="estimated_arrival" type="string | null">
      Estimated time the funds become available in the destination account.
    </ResponseField>

    <ResponseField name="fee_amount" type="number">
      The fee charged for the payout, in the payout currency.
    </ResponseField>

    <ResponseField name="object" type="string" />

    <ResponseField name="payer_name" type="string | null">
      Name of the entity processing the payout.
    </ResponseField>

    <ResponseField name="payout_method" type="object | null">
      The saved payout method used. Requires payout:destination:read; null without it.

      <Accordion title="Properties">
        <ResponseField name="nickname" type="string | null">
          Saved payout method nickname.
        </ResponseField>

        <ResponseField name="supported_payout_method" type="object | null">
          Supported payout method display details.

          <Accordion title="Properties">
            <ResponseField name="icon_url" type="string | null">
              Supported payout method icon URL.
            </ResponseField>

            <ResponseField name="payer_name" type="string | null">
              Supported payout method display name.
            </ResponseField>
          </Accordion>
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="payout_request_id" type="string | null">
      The ID returned by POST /payouts when this payout was requested. Match it to
      the settled payout in GET /payouts. Null for payouts not created by POST
      /payouts.
    </ResponseField>

    <ResponseField name="speed" type="string">
      Payout delivery speed.

      Available options: `standard`, `instant`
    </ResponseField>

    <ResponseField name="status" type="string">
      Current payout status.

      Available options: `requested`, `awaiting_payment`, `in_transit`, `completed`, `failed`, `canceled`, `denied`
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Payout theme={null}
      {
      	"id": "po_xxxxxxxxxxxxx",
      	"amount": 125.5,
      	"created_at": "2026-06-01T12:00:00Z",
      	"currency": "usd",
      	"estimated_arrival": "2026-06-03T12:00:00Z",
      	"fee_amount": 1.25,
      	"object": "payout",
      	"payer_name": "Whop Payments",
      	"payout_request_id": "cofr_xxxxxxxxxxxxx",
      	"payout_method": {
      		"nickname": "Operating account",
      		"supported_payout_method": {
      			"icon_url": "https://cdn.whop.com/bank.png",
      			"payer_name": "Whop Payments"
      		}
      	},
      	"speed": "standard",
      	"status": "completed"
      }
      ```
    </div>
  </Column>
</Columns>


# Payoutmethod created
Source: https://docs.whop.com/api-reference/beta/payouts/payoutmethod-created

/openapi/api-v1-native.json webhook payout_method.created
Sent when a payout method is created

Required permissions:
 - `payout:destination:read`
 - `webhook_receive:payout_methods`



# Rename Saved Payout Method
Source: https://docs.whop.com/api-reference/beta/payouts/rename-saved-payout-method

/openapi/api-v1-native.json patch /payouts/methods/{payout_method_id}
Changes the label used to identify a saved payout method.



# Retrieve Payout
Source: https://docs.whop.com/api-reference/beta/payouts/retrieve-payout

/openapi/api-v1-native.json get /payouts/{payout_id}
Fetches a single payout. Accepts a `wdrl_` payout id from GET /payouts, or the `cofr_` payout request id returned by POST /payouts on stablecoin accounts — poll it to watch a requested payout settle.



# Withdrawal created
Source: https://docs.whop.com/api-reference/beta/payouts/withdrawal-created

/openapi/api-v1-native.json webhook withdrawal.created
Sent when a withdrawal is created

Required permissions:
 - `payout:withdrawal:read`
 - `payout:destination:read`
 - `webhook_receive:withdrawals`



# Withdrawal updated
Source: https://docs.whop.com/api-reference/beta/payouts/withdrawal-updated

/openapi/api-v1-native.json webhook withdrawal.updated
Sent when a withdrawal is updated

Required permissions:
 - `payout:withdrawal:read`
 - `payout:destination:read`
 - `webhook_receive:withdrawals`



# List Resolution Center Cases
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/list-resolution-center-cases

/openapi/api-v1-native.json get /resolution_center_cases
Lists resolution center cases. Without `account_id` you get every case you can read — the ones you opened as a buyer and every account you are a team member of; the filters narrow that list.



# Retrieve setup status
Source: https://docs.whop.com/api-reference/beta/setup-intents/retrieve-setup-status

/openapi/api-v1-native.json get /setup_intents/{setup_intent_id}/status
Retrieves how far a setup has got and what the buyer must do next, if anything. Collection runs in the background, so poll this rather than reading the create response. Accepts either a secret key or the setup's own `client_secret`, so the surface collecting the payment method can poll it directly.



# Update setup return URL
Source: https://docs.whop.com/api-reference/beta/setup-intents/update-setup-return-url

/openapi/api-v1-native.json patch /setup_intents/{setup_intent_id}/return_url
Changes where the buyer lands after completing an off-site step, up until they return. Accepts either a secret key or the setup's own `client_secret`, so the surface that knows the final destination can set it.



# List Metrics
Source: https://docs.whop.com/api-reference/beta/stats/list-metrics

/openapi/api-v1-native.json get /stats
Lists every metric you can query, with its unit and the properties you can filter or break it down by.



# Retrieve Metric
Source: https://docs.whop.com/api-reference/beta/stats/retrieve-metric

/openapi/api-v1-native.json get /stats/{metric}
Retrieves a metric as a time series of points for an account over a time range. The `market_prices` metric is public and requires no authentication.



# Stats
Source: https://docs.whop.com/api-reference/beta/stats/stats



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.

## Endpoints

| Endpoint                                                     | Request                              |
| ------------------------------------------------------------ | ------------------------------------ |
| [List Metrics](/api-reference/beta/stats/list-metrics)       | <Badge>GET</Badge> `/stats`          |
| [Retrieve Metric](/api-reference/beta/stats/retrieve-metric) | <Badge>GET</Badge> `/stats/{metric}` |

## Metrics glossary

Every metric has a `key` that you pass as the `{metric}` path segment to [Retrieve Metric](/api-reference/beta/stats/retrieve-metric). [List Metrics](/api-reference/beta/stats/list-metrics) returns the same catalog at runtime, with each metric's `unit` and the `properties` you can filter or break down by. An unknown key returns a `404`.

### Units

| Unit       | How to read the value                                                                                    |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `count`    | An integer count.                                                                                        |
| `currency` | A decimal amount in the display currency (see [`convert_to`](#query-parameters)), for example `4899.50`. |
| `percent`  | A number where `1.6` means 1.6%, already scaled to percentage points rather than a `0`–`1` fraction.     |

### Filtering and breaking down

Each property works two ways unless noted otherwise:

* **Filter** — pass `property=value` to narrow the series to a single value, for example `?payment_method=card`.
* **Break down** — pass `breakdown_by=property` to split each point into one entry per value. For example, `?breakdown_by=currency` returns an entry for `usd`, an entry for `eur`, and so on. One `breakdown_by` at a time.

Passing a property a metric does not list returns a `400`.

| Property             | Values                                                                                                                                                                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currency`           | An ISO 4217 code such as `usd` or `eur`, or an asset symbol such as `btc` or `xaut` for `market_prices`. Transaction metrics report the original currency, not converted.                                                               |
| `hostname`           | A website hostname the traffic was recorded on, for example `shop.example.com` (traffic metrics only).                                                                                                                                  |
| `page`               | A hostname plus normalized path, for example `shop.example.com/pricing` (traffic metrics only).                                                                                                                                         |
| `source`             | Where a visit came from: `whop_ads` for Whop ad clicks, `direct` for unattributed visits, or the visit's `utm_source` value (traffic metrics only).                                                                                     |
| `device_type`        | `desktop`, `mobile`, `tablet`, or `unknown` (traffic metrics only).                                                                                                                                                                     |
| `country_code`       | An uppercase ISO 3166-1 alpha-2 code, for example `US`, or empty when unknown (traffic metrics only).                                                                                                                                   |
| `payment_method`     | `card` or `crypto`.                                                                                                                                                                                                                     |
| `card_network`       | A card brand, for example `visa` or `mastercard`. A refinement of `payment_method=card` — only valid alongside it.                                                                                                                      |
| `dispute_reason`     | A provider-normalized dispute reason such as `product_not_received`, `product_unacceptable`, `fraudulent`, or `credit_not_processed`. Use it on `snapshot_disputes`; clients can group remaining reason slugs into “Other” for display. |
| `product`            | A product ID to scope the metric to a single product.                                                                                                                                                                                   |
| `fee_type`           | A fee line type, for example `payment_processing_percentage_fee` (see the [Ledger Activity fees glossary](/api-reference/beta/ledgers/ledger-activity#fees)).                                                                           |
| `status`             | A membership status for New users, or an affiliate payment status for Partner metrics.                                                                                                                                                  |
| `access_level`       | A member's access level, for example `customer` (New users only).                                                                                                                                                                       |
| `most_recent_action` | A member's most recent lifecycle action (New users only).                                                                                                                                                                               |
| `account_id`         | A referred business ID (Partner metrics only).                                                                                                                                                                                          |
| `tier`               | `first` or `second` (Partner metrics only).                                                                                                                                                                                             |
| `referred_user_id`   | A referred user ID. Filter-only; it cannot be used with `breakdown_by` (Partner metrics only).                                                                                                                                          |
| `merchant`           | A slugified merchant name, for example `starbucks`, or `other` when unknown (card metrics only). On `card_spend` it names the transaction's merchant; on cashback metrics it names the cashback offer's merchant bucket.                |
| `event_name`         | A tracked event name, for example `pixel.page` or `pixel.custom` (`events` only).                                                                                                                                                       |
| `event_type`         | A canonical group of events: `page_view` (pixel page views plus whop.com store views), `checkout_start` (hosted and embedded checkout views), or `other` (`events` only).                                                               |
| `custom_name`        | The merchant-defined name of a custom event (`events` only). A refinement of `event_name=pixel.custom` — only valid alongside it, since no other event carries a custom name.                                                           |

### Query parameters

These apply to every metric on [Retrieve Metric](/api-reference/beta/stats/retrieve-metric), independent of its properties:

| Parameter         | Description                                                                                                                                                                                                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`, `to`      | Required. The date range (`YYYY-MM-DD`) to plot.                                                                                                                                                                                                                                                         |
| `interval`        | Point width: `hour`, `day`, `week`, or `month`. Defaults to `day`. Traffic metrics also accept `minute` for ranges up to one hour. `market_prices` accepts `five_minutes`, `thirty_minutes`, `hour`, or `day`.                                                                                           |
| `convert_to`      | Display currency for money metrics — every amount is converted into this ISO currency at each period's rate. Defaults to `usd`. Ignored when you filter or break down by `currency` (those report the original, unconverted currency). `market_prices` currently supports `usd` only.                    |
| `time_zone`       | IANA time zone to bucket the series in, for example `America/New_York`. Defaults to `UTC`.                                                                                                                                                                                                               |
| `breakdown_by`    | Split each point out by one of the metric's properties.                                                                                                                                                                                                                                                  |
| `snapshot_window` | Snapshot metrics only. Ordinary snapshots accept `30d` as their trailing activity window. Cohorted dispute metrics accept `7d` or `28d` as the sales-transaction pooling window; the attribution window is fixed in the metric name. Check the metric catalog's `windows` array for the accepted values. |

### Revenue

| Metric                             | Unit       | Filters & breakdowns                    | Description                                                                  |
| ---------------------------------- | ---------- | --------------------------------------- | ---------------------------------------------------------------------------- |
| `net_revenue`                      | `currency` | —                                       | Earnings kept after refunds, disputes, and all fees.                         |
| `gross_revenue`                    | `currency` | `payment_method`, `product`, `currency` | Gross earnings from sales and platform income, before refunds or fees.       |
| `net_volume`                       | `currency` | —                                       | Gross earnings minus Whop fees, before refunds and other deductions.         |
| `gross_transaction_value`          | `currency` | `currency`                              | Total value of completed sales (GMV), before refunds or fees.                |
| `marketplace_revenue`              | `currency` | `payment_method`, `product`, `currency` | Revenue from marketplace sales, excluding direct-to-consumer.                |
| `churned_revenue`                  | `currency` | —                                       | Recurring revenue lost from memberships whose MRR decreased over the period. |
| `total_refunded`                   | `currency` | `payment_method`, `product`, `currency` | Total amount refunded to buyers.                                             |
| `monthly_recurring_revenue`        | `currency` | `currency`                              | Monthly recurring revenue from active subscriptions.                         |
| `annual_recurring_revenue`         | `currency` | `currency`                              | Annualized recurring revenue: MRR times twelve.                              |
| `average_revenue_per_user`         | `currency` | `payment_method`, `product`, `currency` | Average revenue earned per paying user.                                      |
| `average_revenue_per_subscription` | `currency` | `payment_method`, `product`, `currency` | Average revenue earned per active subscription.                              |

### Payments

| Metric                | Unit    | Filters & breakdowns                    | Description                   |
| --------------------- | ------- | --------------------------------------- | ----------------------------- |
| `successful_payments` | `count` | `payment_method`, `product`, `currency` | Successful payments received. |

### Fees

Every fee metric accepts a `currency` filter.

| Metric                    | Unit       | Filters & breakdowns   | Description                                                   |
| ------------------------- | ---------- | ---------------------- | ------------------------------------------------------------- |
| `fees`                    | `currency` | `currency`, `fee_type` | All fees charged. Break down by `fee_type` to itemize them.   |
| `payment_processing_fees` | `currency` | `currency`             | Card, network, currency-conversion, billing, and payout fees. |
| `whop_processing_fees`    | `currency` | `currency`             | Whop's processing fee on transactions.                        |
| `affiliate_fees`          | `currency` | `currency`             | Fees paid to affiliates on referred sales.                    |
| `marketplace_fees`        | `currency` | `currency`             | Affiliate fees on marketplace sales.                          |
| `dispute_fees`            | `currency` | `currency`             | Fees charged for disputes and dispute alerts.                 |
| `sales_tax_withheld`      | `currency` | `currency`             | Sales tax withheld and remitted.                              |

### Disputes & refunds

| Metric           | Unit      | Filters & breakdowns | Description                                                      |
| ---------------- | --------- | -------------------- | ---------------------------------------------------------------- |
| `disputes`       | `count`   | —                    | Disputes opened against the account.                             |
| `dispute_alerts` | `count`   | —                    | Early-warning dispute alerts received on the account's payments. |
| `dispute_rate`   | `percent` | `payment_method`     | Share of paid receipts with a dispute.                           |
| `refund_rate`    | `percent` | `payment_method`     | Share of paid receipts refunded.                                 |

### Authorizations

| Metric      | Unit      | Filters & breakdowns | Description                                              |
| ----------- | --------- | -------------------- | -------------------------------------------------------- |
| `auth_rate` | `percent` | —                    | Share of decided card authorizations that were approved. |

### Members & users

| Metric                  | Unit      | Filters & breakdowns                                      | Description                             |
| ----------------------- | --------- | --------------------------------------------------------- | --------------------------------------- |
| `new_users`             | `count`   | `status`, `access_level`, `most_recent_action`, `product` | Users who joined.                       |
| `users_growth`          | `count`   | —                                                         | Active members over time.               |
| `paid_active_members`   | `count`   | —                                                         | Active paying members.                  |
| `churn_rate`            | `percent` | —                                                         | Share of paying members who canceled.   |
| `trial_conversion_rate` | `percent` | —                                                         | Share of trials that converted to paid. |

### Partners

| Metric             | Unit       | Filters & breakdowns                                              | Description                                                              |
| ------------------ | ---------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `partner_earnings` | `currency` | `status`, `account_id`, `tier`; `referred_user_id` is filter-only | Commissions earned from referred businesses across both partner tiers.   |
| `partner_volume`   | `currency` | `status`, `account_id`, `tier`; `referred_user_id` is filter-only | Sales volume generated by referred businesses across both partner tiers. |

### Cards

Card metrics report spend and cashback on the account's issued Whop cards. They are USD-only and UTC-only: `convert_to` and `time_zone` are not accepted. Accounts without issued cards return an empty series.

| Metric                     | Unit       | Filters & breakdowns | Description                                                                                  |
| -------------------------- | ---------- | -------------------- | -------------------------------------------------------------------------------------------- |
| `card_spend`               | `currency` | `merchant`           | Total spend on issued cards each period. Break down by `merchant` to split by merchant.      |
| `cashback`                 | `currency` | `merchant`           | Cashback earned on eligible card spend. Break down by `merchant` to split by cashback offer. |
| `cashback_qualified_spend` | `currency` | `merchant`           | Card spend that earned cashback. Break down by `merchant` to split by cashback offer.        |

### Market data

`market_prices` is publicly available without authentication, `account_id`, or `user_id`. It returns historical prices for Bitcoin (`btc`) and Gold (`xaut`) in USD, supports ranges up to one year, and returns at most 2,000 points.

| Metric          | Unit       | Filters & breakdowns | Description                                       |
| --------------- | ---------- | -------------------- | ------------------------------------------------- |
| `market_prices` | `currency` | `currency`           | Market price of Bitcoin or Gold in USD over time. |

### Advertising & traffic

Traffic metrics cover pixel events on the merchant's own websites plus whop.com store views, support `interval=minute` for ranges up to one hour, and cap their range at 30 days. High-cardinality breakdowns (such as `page`) return at most the top 500 entries per point.

| Metric        | Unit       | Filters & breakdowns                                                                                   | Description                                                                                                                                                                            |
| ------------- | ---------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ad_spend`    | `currency` | —                                                                                                      | Total advertising spend across the account's ad campaigns.                                                                                                                             |
| `page_visits` | `count`    | —                                                                                                      | Store page views for the account.                                                                                                                                                      |
| `events`      | `count`    | `event_name`, `custom_name`, `event_type`, `hostname`, `page`, `source`, `device_type`, `country_code` | Tracked events across the account's traffic, excluding crawlers. Filter by `event_type=page_view` or `event_type=checkout_start` for canonical counts, `event_name` for one raw event. |
| `people`      | `count`    | `hostname`, `page`, `source`, `device_type`, `country_code`                                            | Unique people across the account's traffic, deduplicated by resolved identity.                                                                                                         |

### Snapshot metrics

<Note>
  Snapshot metrics are captured once per day and preserve what was known at that
  time. They are day-only and UTC-only: `interval` must be `day` and `time_zone`
  is not accepted. You still pass `from` and `to` to choose the range of daily
  points. Use each metric's `windows` catalog field to determine which
  `snapshot_window` values it accepts.
</Note>

| Metric                                    | Unit      | `snapshot_window` | Filters & breakdowns                               | Description                                                                                                           |
| ----------------------------------------- | --------- | ----------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `snapshot_receipts`                       | `count`   | `30d`             | `card_network`, `payment_method`                   | Paid receipts in the trailing 30 days.                                                                                |
| `snapshot_refunds`                        | `count`   | `30d`             | —                                                  | Refunds issued in the trailing 30 days.                                                                               |
| `snapshot_refund_rate`                    | `percent` | `30d`             | —                                                  | Share of trailing-30-day paid receipts refunded.                                                                      |
| `snapshot_disputes`                       | `count`   | `30d`             | `card_network`, `payment_method`, `dispute_reason` | Non-RDR disputes filed in the trailing 30 days. Break down by normalized reason to build a dispute-composition chart. |
| `snapshot_dispute_rate`                   | `percent` | `30d`             | `card_network`, `payment_method`                   | Disputes filed in the trailing 30 days divided by paid receipts in that window.                                       |
| `snapshot_cohorted_dispute_rate_7d_attr`  | `percent` | `7d`, `28d`       | `card_network`, `payment_method`                   | Share of the latest mature sales cohort disputed within 7 days of purchase.                                           |
| `snapshot_cohorted_dispute_rate_14d_attr` | `percent` | `7d`, `28d`       | `card_network`, `payment_method`                   | Share of the latest mature sales cohort disputed within 14 days.                                                      |
| `snapshot_cohorted_dispute_rate_28d_attr` | `percent` | `7d`, `28d`       | `card_network`, `payment_method`                   | Share of the latest mature sales cohort disputed within 28 days.                                                      |
| `snapshot_resolution_center_cases`        | `count`   | `30d`             | —                                                  | Resolution center cases opened in the trailing 30 days.                                                               |
| `snapshot_resolution_center_case_rate`    | `percent` | `30d`             | —                                                  | Trailing-30-day resolution center cases divided by paid receipts.                                                     |
| `snapshot_approved_authorizations`        | `count`   | `30d`             | —                                                  | Card authorizations approved in the trailing 30 days.                                                                 |
| `snapshot_decided_authorizations`         | `count`   | `30d`             | —                                                  | Card authorizations approved or declined in the trailing 30 days.                                                     |
| `snapshot_auth_rate`                      | `percent` | `30d`             | —                                                  | Trailing-30-day approved authorizations divided by decided authorizations.                                            |

### Cohorted dispute snapshots

Cohorted metrics attribute each dispute to the date of its original paid receipt. The attribution window in the metric name answers “how long after purchase can a dispute count?” The `snapshot_window` answers a separate question: “how many consecutive days of sales are pooled into this point?” Use `7d` for a more reactive series or `28d` for a smoother denominator.

Each captured point uses the latest sales cohort whose complete attribution window has elapsed. For a snapshot captured on date `D`, its cohort ends on `D - attribution days - 1 day`; the extra day ensures the final attribution day is complete. To reproduce a cohort-end-date chart, plot each point on that inferred cohort end date. Comparing 7d, 14d, and 28d attribution values at the same raw API timestamp compares different mature cohorts; align them by cohort end date before expecting `7d ≤ 14d ≤ 28d`.


# Create Swap
Source: https://docs.whop.com/api-reference/beta/swaps/create-swap

/openapi/api-v1-native.json post /swaps
Swaps one token for another from the account's wallet, or converts between fiat currencies in the account's ledger at the mid-market rate. Crypto swaps finish in the background — check the swap for its status.



# Create Swap Quote
Source: https://docs.whop.com/api-reference/beta/swaps/create-swap-quote

/openapi/api-v1-native.json post /swaps/quote
Previews the price of a swap. Fiat pairs quote the in-ledger mid-market conversion — the same rate creating the swap fills at. No funds move and nothing is saved.



# List Swaps
Source: https://docs.whop.com/api-reference/beta/swaps/list-swaps

/openapi/api-v1-native.json get /swaps
Retrieve the account's completed or pending swaps — currently just the latest one.



# Retrieve Swap
Source: https://docs.whop.com/api-reference/beta/swaps/retrieve-swap

/openapi/api-v1-native.json get /swaps/{id}
Retrieves a single swap and its status.



# Swaps
Source: https://docs.whop.com/api-reference/beta/swaps/swap



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.

## Endpoints

| Endpoint                                                         | Request                            |
| ---------------------------------------------------------------- | ---------------------------------- |
| [List Swaps](/api-reference/beta/swaps/list-swaps)               | <Badge>GET</Badge> `/swaps`        |
| [Create Swap](/api-reference/beta/swaps/create-swap)             | <Badge>POST</Badge> `/swaps`       |
| [Retrieve Swap](/api-reference/beta/swaps/retrieve-swap)         | <Badge>GET</Badge> `/swaps/{id}`   |
| [Create Swap Quote](/api-reference/beta/swaps/create-swap-quote) | <Badge>POST</Badge> `/swaps/quote` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Swap ID.
    </ResponseField>

    <ResponseField name="account_id" type="string">
      Account ID that owns the wallet used for the swap.
    </ResponseField>

    <ResponseField name="error" type="string | null">
      Latest error returned for a failed swap.
    </ResponseField>

    <ResponseField name="object" type="string" />

    <ResponseField name="status" type="string">
      Current swap status. `complete` and `failed` are terminal.

      Available options: `queued`, `working`, `complete`, `failed`
    </ResponseField>

    <ResponseField name="tx_hashes" type="string[]">
      On-chain transaction hashes produced by the swap.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Swap theme={null}
      {
      	"id": "swap_xxxxxxxxxxxx",
      	"account_id": "biz_xxxxxxxxxxxxxx",
      	"error": null,
      	"object": "swap",
      	"status": "complete",
      	"tx_hashes": ["0x1234567890abcdef"]
      }
      ```
    </div>
  </Column>
</Columns>


# Swap completed
Source: https://docs.whop.com/api-reference/beta/swaps/swap-completed

/openapi/api-v1-native.json webhook swap.completed
Sent when a swap is completed

Required permissions:
 - `webhook_receive:swaps`



# Create Team Member
Source: https://docs.whop.com/api-reference/beta/team-members/create-team-member

/openapi/api-v1-native.json post /team_members
Adds a member to an account's team with a system role. Identify them by exactly one of `user_id` or `email`. If the person has not yet accepted — or the email does not belong to a Whop account yet — an invitation is sent instead and the response is `202` with `{ "object": "team_member_invite", "invitation_sent": true }`. If they already have a pending invite, the request fails with a `400`. Custom roles cannot be granted via the API.



# Delete Team Member
Source: https://docs.whop.com/api-reference/beta/team-members/delete-team-member

/openapi/api-v1-native.json delete /team_members/{id}
Removes a team member from the account, or revokes a pending invite when given an `ausri_` ID. A user session may delete its own membership to leave the team without the delete scope. The account owner cannot be removed.



# List Team Members
Source: https://docs.whop.com/api-reference/beta/team-members/list-team-members

/openapi/api-v1-native.json get /team_members
Lists an account's team members, including pending invites (`status: "pending"`, `ausri_` ids; `user` is `null` for invites sent to an email with no Whop account yet). For accepted members, `email` requires the `company:authorized_user:email:read` scope and is `null` otherwise.



# Retrieve Team Member
Source: https://docs.whop.com/api-reference/beta/team-members/retrieve-team-member

/openapi/api-v1-native.json get /team_members/{id}
Retrieves a team member by ID. `email` requires the `company:authorized_user:email:read` scope and is `null` otherwise.



# Update Team Member
Source: https://docs.whop.com/api-reference/beta/team-members/update-team-member

/openapi/api-v1-native.json patch /team_members/{id}
Changes a team member's system role. Requires a user session — account API keys cannot change member roles. The account owner's role cannot be changed, and you cannot change your own role.



# Create Transfer
Source: https://docs.whop.com/api-reference/beta/transfers/create-transfer

/openapi/api-v1-native.json post /transfers
Moves money between accounts, or into a claim link anyone with the URL can redeem.



# List Transfer Recipients
Source: https://docs.whop.com/api-reference/beta/transfers/list-transfer-recipients

/openapi/api-v1-native.json get /transfers/recipients
Lists the people and accounts you can send money to.



# List Transfers
Source: https://docs.whop.com/api-reference/beta/transfers/list-transfers

/openapi/api-v1-native.json get /transfers
Lists an account's transfers.



# Retrieve Transfer
Source: https://docs.whop.com/api-reference/beta/transfers/retrieve-transfer

/openapi/api-v1-native.json get /transfers/{id}
Retrieves a single transfer.



# Transfers
Source: https://docs.whop.com/api-reference/beta/transfers/transfer



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.

## Endpoints

| Endpoint                                                                           | Request                                    |
| ---------------------------------------------------------------------------------- | ------------------------------------------ |
| [List Transfers](/api-reference/beta/transfers/list-transfers)                     | <Badge>GET</Badge> `/transfers`            |
| [Create Transfer](/api-reference/beta/transfers/create-transfer)                   | <Badge>POST</Badge> `/transfers`           |
| [Retrieve Transfer](/api-reference/beta/transfers/retrieve-transfer)               | <Badge>GET</Badge> `/transfers/{id}`       |
| [List Transfer Recipients](/api-reference/beta/transfers/list-transfer-recipients) | <Badge>GET</Badge> `/transfers/recipients` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Transfer ID.
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transfer amount.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the transfer was created.
    </ResponseField>

    <ResponseField name="created_by_user" type="object | null">
      The user who initiated the transfer, such as the team member who sent a manual payout. Null if the creator is unavailable.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          User ID.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          User display name.
        </ResponseField>

        <ResponseField name="username" type="string">
          User's username.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="currency" type="string">
      Transfer currency.
    </ResponseField>

    <ResponseField name="destination" type="object">
      Account or user receiving funds.
    </ResponseField>

    <ResponseField name="destination_ledger_account_id" type="string">
      Destination ledger account ID.
    </ResponseField>

    <ResponseField name="fee_amount" type="number | null">
      Fee charged for the transfer.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom metadata attached to the transfer.
    </ResponseField>

    <ResponseField name="notes" type="string | null">
      Transfer note.
    </ResponseField>

    <ResponseField name="object" type="string">
      The object type. Discriminates the create response from a send or a claim
      link.
    </ResponseField>

    <ResponseField name="origin" type="object">
      Account or user sending funds.
    </ResponseField>

    <ResponseField name="origin_ledger_account_id" type="string">
      Source ledger account ID.
    </ResponseField>

    <ResponseField name="status" type="string">
      Transfer status. `processing` means the on-chain leg is still executing — poll the transfer until it resolves to `succeeded` or `failed`.

      Available options: `processing`, `succeeded`, `failed`
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Transfer theme={null}
      {
      	"id": "tr_xxxxxxxxxxxxx",
      	"amount": 50,
      	"created_at": "2026-06-01T12:00:00Z",
      	"created_by_user": {
      		"id": "user_xxxxxxxxxxxxx",
      		"name": "Jordan Lee",
      		"username": "jordan"
      	},
      	"currency": "usd",
      	"destination": {
      		"id": "user_xxxxxxxxxxxxx",
      		"name": "Alex Rivera",
      		"typename": "User",
      		"username": "alex"
      	},
      	"destination_ledger_account_id": "la_destxxxxxxxx",
      	"fee_amount": null,
      	"metadata": {
      		"external_transfer_id": "transfer_123"
      	},
      	"notes": "Creator bonus",
      	"object": "transfer",
      	"origin": {
      		"id": "biz_xxxxxxxxxxxxxx",
      		"route": "pickaxe",
      		"title": "Pickaxe",
      		"typename": "Company"
      	},
      	"origin_ledger_account_id": "la_originxxxxxx",
      	"status": "succeeded"
      }
      ```
    </div>
  </Column>
</Columns>


# Transfer completed
Source: https://docs.whop.com/api-reference/beta/transfers/transfer-completed

/openapi/api-v1-native.json webhook transfer.completed
Sent when a transfer is completed

Required permissions:
 - `webhook_receive:transfers`



# Transfer created
Source: https://docs.whop.com/api-reference/beta/transfers/transfer-created

/openapi/api-v1-native.json webhook transfer.created
Sent when a transfer is created

Required permissions:
 - `webhook_receive:transfers`



# Create Verification
Source: https://docs.whop.com/api-reference/beta/verifications/create-verification

/openapi/api-v1-native.json post /verifications
Starts a hosted verification session for an account or user, or returns the active session when one already exists. Any fields you include in the request body are used to prefill the session. Send `documents` (with `document_type`) to instead verify the person from identity documents included in this request — no hosted session involved. Send `share_token` to reuse a verification another Sumsub account has already completed for this person, instead of verifying them again. If the account already has an `approved` verification the request is rejected; unlink it first to start a new one.



# Identityprofile updated
Source: https://docs.whop.com/api-reference/beta/verifications/identityprofile-updated

/openapi/api-v1-native.json webhook identity_profile.updated
Sent whenever an identity profile changes state — a verification is approved, needs action, or is rejected, or a Whop review opens or clears. Every other identity_profile event is also delivered as an identity_profile.updated, so you can subscribe to this single event and re-fetch the verification to read its current status.

Required permissions:
 - `identity:read`
 - `webhook_receive:identity_profiles`



# List Verifications
Source: https://docs.whop.com/api-reference/beta/verifications/list-verifications

/openapi/api-v1-native.json get /verifications
Returns verifications for an account, including their status and any required actions.



# Retrieve Verification
Source: https://docs.whop.com/api-reference/beta/verifications/retrieve-verification

/openapi/api-v1-native.json get /verifications/{verification_id}
Returns verifications for an account, including their status and any required actions.



# Update Verification
Source: https://docs.whop.com/api-reference/beta/verifications/update-verification

/openapi/api-v1-native.json patch /verifications/{verification_id}
Updates editable profile details or submits answers for items returned in `requested_information`. Once a verification is `approved` its profile details are locked and can no longer be edited.



# Verification
Source: https://docs.whop.com/api-reference/beta/verifications/verification



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).

## Endpoints

| Endpoint                                                                         | Request                                                 |
| -------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [List Verifications](/api-reference/beta/verifications/list-verifications)       | <Badge>GET</Badge> `/verifications`                     |
| [Create Verification](/api-reference/beta/verifications/create-verification)     | <Badge>POST</Badge> `/verifications`                    |
| [Retrieve Verification](/api-reference/beta/verifications/retrieve-verification) | <Badge>GET</Badge> `/verifications/{verification_id}`   |
| [Update Verification](/api-reference/beta/verifications/update-verification)     | <Badge>PATCH</Badge> `/verifications/{verification_id}` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Verification profile ID, prefixed `idpf_`.
    </ResponseField>

    <ResponseField name="address" type="object | null">
      Address on the verification profile. `null` when no address is set.

      <Accordion title="Properties">
        <ResponseField name="city" type="string | null" />

        <ResponseField name="country" type="string | null">
          Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.
        </ResponseField>

        <ResponseField name="line1" type="string">
          First line of the street address.
        </ResponseField>

        <ResponseField name="line2" type="string | null">
          Second line of the street address.
        </ResponseField>

        <ResponseField name="postal_code" type="string | null">
          Postal or ZIP code.
        </ResponseField>

        <ResponseField name="state" type="string | null">
          State, province, or region code, for example `CA`.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="business_name" type="string | null">
      Legal business name.
    </ResponseField>

    <ResponseField name="business_structure" type="string | null">
      Legal entity structure of the business, such as `private_corporation` or
      `sole_proprietorship`. Supported values vary by country of incorporation — see
      [Business structures](/developer/verification/business-structures).
    </ResponseField>

    <ResponseField name="country" type="string | null">
      Two-letter ISO 3166-1 country code, for example `US`, `DE`, or `GB`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the verification profile was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="date_of_birth" type="string | null">
      Formatted as `YYYY-MM-DD`.
    </ResponseField>

    <ResponseField name="first_name" type="string | null" />

    <ResponseField name="kind" type="string">
      Available options: `individual`, `business`
    </ResponseField>

    <ResponseField name="last_name" type="string | null" />

    <ResponseField name="requested_information" type="object[]">
      What Whop still needs before review can continue — one requirement per entry. Answer with Update Verification; nothing from the response is echoed back. Keys that don't apply are omitted.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Requested information item ID, prefixed `inrqi_`.
        </ResponseField>

        <ResponseField name="errors" type="object[]">
          Present after a rejected submission.

          <Accordion title="Properties">
            <ResponseField name="code" type="string">
              Stable error code.
            </ResponseField>

            <ResponseField name="reason" type="string">
              Why it was rejected.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="label" type="string">
          Instruction to show the user. Carries the reviewer's note verbatim when there
          is one.
        </ResponseField>

        <ResponseField name="optional" type="boolean">
          `true` when the item can be skipped.
        </ResponseField>

        <ResponseField name="options" type="string[]">
          The values `value` may take on a `select` item. On an `id_document` item these
          are the ID types accepted, and the chosen one decides which `documents` slots
          to send. Absent when the item has no choice to make.
        </ResponseField>

        <ResponseField name="requirement" type="string">
          What is needed: a document name such as `bank_statement`, or a field key such
          as `ssn` or `identity_document`. Handle unrecognized values by `type`.
        </ResponseField>

        <ResponseField name="type" type="string">
          What to send as the answer, so you never have to infer it: `files` (a document, as a list of its pages), `id_document` (send `documents` with the slot keys for the ID you are uploading), `text`, `date`, `phone` or `select` (send `value`), or `address` (send `address`).
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="required_documents" type="object[]">
      Documents for a document-upload verification and their progress. Present only on verifications created by sending `documents`. `pending_upload` documents were not accepted yet — send the full set again with another Create Verification call.

      <Accordion title="Properties">
        <ResponseField name="document" type="string">
          Document slot key, such as `id_card_front`, `id_card_back`, or `selfie`.
        </ResponseField>

        <ResponseField name="rejection_reason" type="string | null">
          Why the previous submission was rejected, when the provider requested new
          documents or declined the verification.
        </ResponseField>

        <ResponseField name="status" type="string">
          `pending_upload` until the document has been relayed for review; `submitted` afterwards.

          Available options: `pending_upload`, `submitted`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="session_url" type="string | null">
      Hosted verification session URL for the user to complete identity checks.
      Expires 7 days after creation.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current verification state. `not_started` before any session exists; `pending` while a session needs the user's input; `processing` while the provider's automated checks run on a fresh submission; `action_required` when `requested_information` needs answers; `manual_review` while information already sent is under review — an audit answer, or a document the payout provider holds — nothing to submit, usually done within 3 business days; `approved` on success; `rejected` on failure. Call Create Verification again to start a new session.

      Available options: `not_started`, `pending`, `processing`, `manual_review`, `approved`, `rejected`, `action_required`
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the verification profile was last updated, as an ISO 8601 timestamp.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Verification theme={null}
      {
      	"id": "idpf_xxxxxxxxxxxx",
      	"address": {
      		"city": "New York",
      		"country": "US",
      		"line1": "123 Spring Street",
      		"line2": "Apt 4B",
      		"postal_code": "10012",
      		"state": "NY"
      	},
      	"business_name": null,
      	"business_structure": null,
      	"country": "US",
      	"created_at": "2026-06-01T12:00:00Z",
      	"date_of_birth": "1990-01-01",
      	"first_name": "Alex",
      	"kind": "individual",
      	"last_name": "Rivera",
      	"requested_information": [
      		{
      			"id": "inrqi_xxxxxxxxxxx",
      			"label": "Identity document",
      			"options": ["PASSPORT", "ID_CARD", "DRIVERS", "RESIDENCE_PERMIT"],
      			"requirement": "identity_document",
      			"type": "id_document"
      		},
      		{
      			"id": "inrqi_yyyyyyyyyyy",
      			"label": "Bank Statement or a check for account ending in 4242",
      			"requirement": "bank_statement",
      			"type": "files"
      		}
      	],
      	"required_documents": [
      		{
      			"document": "id_card_front",
      			"rejection_reason": null,
      			"status": "submitted"
      		},
      		{
      			"document": "id_card_back",
      			"rejection_reason": null,
      			"status": "submitted"
      		},
      		{
      			"document": "selfie",
      			"rejection_reason": null,
      			"status": "submitted"
      		}
      	],
      	"session_url": "https://verify.whop.com/session/idpf_xxxxxxxxxxxx",
      	"status": "action_required",
      	"updated_at": "2026-06-02T12:00:00Z"
      }
      ```
    </div>
  </Column>
</Columns>


# Create Webhook
Source: https://docs.whop.com/api-reference/beta/webhooks/create-webhook

/openapi/api-v1-native.json post /webhooks
Creates a webhook endpoint that receives event notifications via HTTP POST.



# Delete Webhook
Source: https://docs.whop.com/api-reference/beta/webhooks/delete-webhook

/openapi/api-v1-native.json delete /webhooks/{id}
Permanently deletes a webhook endpoint. Returns `true` on success, matching the legacy proxy response.



# List Deliveries
Source: https://docs.whop.com/api-reference/beta/webhooks/list-deliveries

/openapi/api-v1-native.json get /webhooks/{id}/deliveries
Returns a paginated list of delivery attempts for a webhook, ordered by most recent first. Includes the request payload, response body, response code, and timing for each attempt.



# List Webhooks
Source: https://docs.whop.com/api-reference/beta/webhooks/list-webhooks

/openapi/api-v1-native.json get /webhooks
Returns a paginated list of webhook endpoints configured for an account, ordered by most recently created.



# Retrieve Webhook
Source: https://docs.whop.com/api-reference/beta/webhooks/retrieve-webhook

/openapi/api-v1-native.json get /webhooks/{id}
Retrieves the details of an existing webhook.



# Send Test Event
Source: https://docs.whop.com/api-reference/beta/webhooks/send-test-event

/openapi/api-v1-native.json post /webhooks/{id}/test
Sends a sample payload for the given event to the webhook's URL and returns the delivery result.



# Update Webhook
Source: https://docs.whop.com/api-reference/beta/webhooks/update-webhook

/openapi/api-v1-native.json patch /webhooks/{id}
Updates a webhook endpoint's URL, subscribed events, API version, pinned payload version, or enabled state.



# Bounty
Source: https://docs.whop.com/api-reference/beta/bounties/bounty



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.

## Endpoints

| Endpoint                                                                        | Request                                                |
| ------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [List Bounties](/api-reference/beta/bounties/list-bounties)                     | <Badge>GET</Badge> `/bounties`                         |
| [Create Bounty](/api-reference/beta/bounties/create-bounty)                     | <Badge>POST</Badge> `/bounties`                        |
| [Retrieve Bounty](/api-reference/beta/bounties/retrieve-bounty)                 | <Badge>GET</Badge> `/bounties/{id}`                    |
| [Update Bounty](/api-reference/beta/bounties/update-bounty)                     | <Badge>PATCH</Badge> `/bounties/{id}`                  |
| [Cancel](/api-reference/beta/bounties/cancel)                                   | <Badge>POST</Badge> `/bounties/{id}/cancel`            |
| [List Public Submissions](/api-reference/beta/bounties/list-public-submissions) | <Badge>GET</Badge> `/bounties/{bounty_id}/submissions` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Bounty ID, prefixed `bnty_`.
    </ResponseField>

    <ResponseField name="accepted_deliverable_types" type="string[]">
      The deliverable shapes this bounty accepts. Every bounty accepts any combination of `content_url` (posted links) and `media` (uploaded files), except `data_capture` bounties, whose proof is clips recorded in the Whop app that accumulate on the attempt.

      Available options: `content_url`, `media`, `data_capture`
    </ResponseField>

    <ResponseField name="accepted_submissions_count" type="integer">
      Submissions accepted so far.
    </ResponseField>

    <ResponseField name="accepted_submissions_limit" type="integer">
      Number of submissions that can be accepted (winner slots).
    </ResponseField>

    <ResponseField name="affiliate_share_amount" type="number">
      What a referrer earns per accepted submission when the worker arrived through
      their affiliate link, in whole currency units, at the standard platform fee
      rate. Taken out of the worker's post-fee reward rather than added on top. `0`
      when the bounty pays no affiliate share, including bounties tied to no
      account, which cannot record a referral.
    </ResponseField>

    <ResponseField name="allowed_country_codes" type="string[]">
      Countries whose residents can work the bounty, as ISO 3166 alpha-2 codes.
      Empty means worldwide.
    </ResponseField>

    <ResponseField name="budget_amount" type="number">
      Total gross budget committed to the bounty: `gross_reward_amount` times
      `accepted_submissions_limit`.
    </ResponseField>

    <ResponseField name="business_goal_type" type="string | null">
      What the poster wants the work to achieve, declared once at create. `null` for bounties created before the taxonomy rolled out.

      Available options: `clipping`, `post_engagement`, `owned_account_growth`, `ugc_content`, `local_activation`, `data_capture`, `other`
    </ResponseField>

    <ResponseField name="cancel_requested_at" type="string | null">
      When cancellation was requested, as an ISO 8601 timestamp. On a `closed`
      bounty this means the cancel is pending: submissions are stopped and the
      bounty cancels once in-flight submissions resolve. On a `canceled` bounty it
      records when the cancellation was requested. `null` when no cancellation was
      ever requested.
    </ResponseField>

    <ResponseField name="capture_spec" type="object | null">
      The technical contract footage must be recorded against. Present only on `data_capture` bounties; `null` for every other goal type.

      <Accordion title="Properties">
        <ResponseField name="filename_pattern" type="string">
          The naming convention for uploaded files, built from the required metadata
          fields.
        </ResponseField>

        <ResponseField name="imu" type="object">
          Inertial measurement unit (IMU) recording requirements.

          <Accordion title="Properties">
            <ResponseField name="device_motion_units" type="string">
              Units for the device-motion channels, as a compact key=unit string.
            </ResponseField>

            <ResponseField name="magnetometer_units" type="string">
              Units for the magnetometer channel.
            </ResponseField>

            <ResponseField name="min_rate_hz" type="number">
              Minimum sustained IMU sample rate in hertz for a clip to pass validation.
            </ResponseField>

            <ResponseField name="target_rate_hz" type="integer">
              Target IMU sample rate in hertz.
            </ResponseField>

            <ResponseField name="warmup_min_rate_hz" type="number">
              Minimum IMU sample rate in hertz tolerated during the warmup window.
            </ResponseField>

            <ResponseField name="warmup_ns" type="integer">
              Startup window, in nanoseconds, during which the relaxed warmup rate applies.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="manifest_schema_version" type="integer">
          Schema version the client must stamp on the capture manifest it uploads.
        </ResponseField>

        <ResponseField name="min_clip_duration_seconds" type="integer">
          Minimum length of a single clip, in seconds.
        </ResponseField>

        <ResponseField name="min_total_verified_duration_seconds" type="integer">
          Total verified footage a submission must accumulate across all its clips
          before it can be submitted, in seconds. Always a whole number of hours.
        </ResponseField>

        <ResponseField name="required_metadata_fields" type="string[]">
          Metadata fields a submission must provide, matching the `metadata` object on
          the submissions API.
        </ResponseField>

        <ResponseField name="single_continuous_take" type="boolean">
          Whether each clip must be one uninterrupted recording rather than stitched
          segments.
        </ResponseField>

        <ResponseField name="video" type="object">
          Video recording requirements.

          <Accordion title="Properties">
            <ResponseField name="bitrate_ceiling_mbps" type="integer">
              Maximum acceptable average bitrate, in megabits per second.
            </ResponseField>

            <ResponseField name="bitrate_floor_mbps" type="integer">
              Minimum acceptable average bitrate, in megabits per second.
            </ResponseField>

            <ResponseField name="bitrate_target_mbps" type="integer">
              Recommended average bitrate to encode at, in megabits per second.
            </ResponseField>

            <ResponseField name="camera_lens" type="string">
              Which physical lens to record with.
            </ResponseField>

            <ResponseField name="codecs" type="string[]">
              Accepted video codecs, in preference order.
            </ResponseField>

            <ResponseField name="embed_camera_metadata" type="boolean">
              Whether the client must also write the camera make and model into the video
              container's metadata. When `false`, the capture manifest and export CSV are
              the metadata carrier.
            </ResponseField>

            <ResponseField name="fps" type="integer">
              Target capture frame rate.
            </ResponseField>

            <ResponseField name="frame_gap_tolerance_ms" type="integer">
              Longest stall between consecutive frames a clip may contain before the client
              rejects it, in milliseconds. Every frame is timestamped in the frame log, so a
              stall stays alignable downstream — this bounds how broken a capture may be,
              not how evenly it must be paced.
            </ResponseField>

            <ResponseField name="height" type="integer">
              Required frame height in pixels — recorded footage must match exactly.
            </ResponseField>

            <ResponseField name="min_fov_degrees" type="integer">
              Minimum acceptable horizontal field of view, in degrees.
            </ResponseField>

            <ResponseField name="orientation" type="string">
              Device orientation to record in.
            </ResponseField>

            <ResponseField name="preferred_fov_degrees" type="integer">
              Preferred horizontal field of view, in degrees.
            </ResponseField>

            <ResponseField name="stabilization_mode" type="string">
              How the client must configure video stabilization: `off` disables EIS so raw motion is preserved for pose extraction, `on` requires it, `any` leaves the device default.

              Available options: `off`, `on`, `any`
            </ResponseField>

            <ResponseField name="stabilization_required" type="boolean">
              Whether hardware/software stabilization must be enabled. True exactly when
              stabilization\_mode is `on`.
            </ResponseField>

            <ResponseField name="width" type="integer">
              Required frame width in pixels — recorded footage must match exactly.
            </ResponseField>
          </Accordion>
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the bounty was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency for all amounts on the bounty, as a lowercase ISO 4217 code.

      Available options: `usd`, `sgd`, `inr`, `aud`, `brl`, `cad`, `dkk`, `eur`, `nok`, `gbp`, `sek`, `chf`, `hkd`, `huf`, `jpy`, `mxn`, `myr`, `pln`, `czk`, `nzd`, `aed`, `cop`, `ron`, `thb`, `bgn`, `idr`, `dop`, `php`, `try`, `krw`, `twd`, `vnd`, `pkr`, `clp`, `uyu`, `ars`, `zar`, `dzd`, `tnd`, `mad`, `kes`, `kwd`, `jod`, `all`, `xcd`, `amd`, `bsd`, `bhd`, `bob`, `bam`, `khr`, `crc`, `xof`, `egp`, `etb`, `gmd`, `ghs`, `gtq`, `gyd`, `ils`, `jmd`, `mop`, `mga`, `mur`, `mdl`, `mnt`, `nad`, `ngn`, `mkd`, `omr`, `pyg`, `pen`, `qar`, `rwf`, `sar`, `rsd`, `lkr`, `tzs`, `ttd`, `uzs`, `rub`, `cny`, `kzt`, `awg`
    </ResponseField>

    <ResponseField name="description" type="string">
      Full task instructions shown to workers.
    </ResponseField>

    <ResponseField name="experience_id" type="string | null">
      Experience the bounty is hosted in, prefixed `exp_`. `null` for platform-wide
      bounties; may belong to a different account than the funder.
    </ResponseField>

    <ResponseField name="funding_account" type="object | null">
      Account whose balance funds the bounty pool, or `null` when a user funds it personally. May differ from the account hosting `experience_id`.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Account ID, prefixed `biz_`.
        </ResponseField>

        <ResponseField name="title" type="string">
          Account display name.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="gross_paid_out_amount" type="number">
      Gross amount paid out from the bounty pool across accepted submissions —
      worker payouts, platform fees, and affiliate shares together. Tips and
      reviewer rewards are excluded.
    </ResponseField>

    <ResponseField name="gross_reward_amount" type="number">
      Gross bounty-pool amount allocated per accepted submission, in whole currency
      units.
    </ResponseField>

    <ResponseField name="net_reward_amount" type="number">
      What a worker is quoted per accepted submission after the platform fee, in
      whole currency units. The exact post-fee figure, at the standard platform fee
      rate — a worker who locked a different rate, or who arrived through an
      affiliate link, is paid a different amount.
    </ResponseField>

    <ResponseField name="poster" type="object">
      User who posted the bounty — the account owner when created with an account API key.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          User ID, prefixed `user_`.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          Display name.
        </ResponseField>

        <ResponseField name="profile_picture" type="object">
          Avatar wrapper; its `url` is always present, using a generated placeholder when the user set no picture.

          <Accordion title="Properties">
            <ResponseField name="url" type="string">
              Avatar image URL. Always present — a generated placeholder when the user set no picture.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="username" type="string">
          Public username.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="scheduled_frequency" type="string | null">
      How often the schedule creates a new bounty. Each occurrence is a separate bounty; the original is not republished.

      Available options: `once`, `hourly`, `daily`, `weekly`, `monthly`
    </ResponseField>

    <ResponseField name="scheduled_publish_at" type="string | null">
      When a scheduled bounty will publish, as an ISO 8601 timestamp. `null` once
      published, for bounties that were never scheduled, and for terminally failed
      drafts parked for manual rescheduling.
    </ResponseField>

    <ResponseField name="spots_remaining" type="integer">
      Unfilled winner capacity: `accepted_submissions_limit` minus
      `accepted_submissions_count`, clamped to zero. Not a signal that the bounty
      currently accepts new claims.
    </ResponseField>

    <ResponseField name="status" type="string">
      Lifecycle state. `scheduled` bounties are unpublished drafts, visible to their poster and the account's authorized managers; `open` bounties accept new submissions; `closed` bounties are live but no longer accept new submissions; `completed` bounties paid out every winner slot; `canceled` bounties ended before filling their slots.

      Available options: `scheduled`, `open`, `closed`, `completed`, `canceled`
    </ResponseField>

    <ResponseField name="submissions_closed_at" type="string | null">
      When new submissions stopped being accepted, as an ISO 8601 timestamp. Set
      when a cancellation is requested on a bounty with work in flight, so in-flight
      submissions can resolve before the bounty cancels. `null` when submissions
      were never stopped — including completed bounties that simply filled every
      winner slot.
    </ResponseField>

    <ResponseField name="title" type="string">
      Short name of the task shown to workers.
    </ResponseField>

    <ResponseField name="unresolved_submissions_count" type="integer">
      Submissions still awaiting an outcome: in progress or pending review.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the bounty was last updated, as an ISO 8601 timestamp.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Bounty theme={null}
      {
      	"id": "bnty_xxxxxxxxxxxxx",
      	"title": "Clip our Tuesday livestream",
      	"description": "Record a 30-60 second clip of the stream's best moment and post it with the campaign hashtag.",
      	"status": "open",
      	"currency": "usd",
      	"gross_reward_amount": 25,
      	"net_reward_amount": 17.5,
      	"affiliate_share_amount": 3.5,
      	"budget_amount": 125,
      	"gross_paid_out_amount": 50,
      	"accepted_submissions_limit": 5,
      	"accepted_submissions_count": 2,
      	"unresolved_submissions_count": 1,
      	"spots_remaining": 3,
      	"business_goal_type": "clipping",
      	"accepted_deliverable_types": ["content_url", "media"],
      	"capture_spec": null,
      	"allowed_country_codes": ["US", "MX"],
      	"submissions_closed_at": null,
      	"cancel_requested_at": null,
      	"scheduled_publish_at": null,
      	"scheduled_frequency": null,
      	"experience_id": "exp_xxxxxxxxxxxxx",
      	"poster": {
      		"id": "user_xxxxxxxxxxxx",
      		"username": "acme_studio",
      		"name": "Creator Name",
      		"profile_picture": {
      			"url": "https://img.whop.com/creator.png"
      		}
      	},
      	"funding_account": {
      		"id": "biz_xxxxxxxxxxxxx",
      		"title": "Acme Studio"
      	},
      	"created_at": "2026-07-01T00:00:00.000Z",
      	"updated_at": "2026-07-08T00:00:00.000Z"
      }
      ```
    </div>
  </Column>
</Columns>


# Cancel
Source: https://docs.whop.com/api-reference/beta/bounties/cancel

/openapi/api-v1-native.json post /bounties/{id}/cancel
Cancels a bounty. With no in-flight work, it cancels immediately and refunds the funder. Otherwise it stops new submissions and cancels once the in-flight work resolves and pays out. Repeating the request is a no-op. A bounty that already paid out every slot returns `400`.



# Create Bounty
Source: https://docs.whop.com/api-reference/beta/bounties/create-bounty

/openapi/api-v1-native.json post /bounties
Creates a bounty and escrows its reward pool. Publishes immediately, or as a scheduled draft when you set `publish_at`.



# List Bounties
Source: https://docs.whop.com/api-reference/beta/bounties/list-bounties

/openapi/api-v1-native.json get /bounties
Lists bounties visible to the credential — for an account API key, the account's bounties including scheduled drafts; for a user token, the bounties the user can see and work.



# List Public Submissions
Source: https://docs.whop.com/api-reference/beta/bounties/list-public-submissions

/openapi/api-v1-native.json get /bounties/{bounty_id}/submissions
Lists a bounty's publicly visible work — submitted, approved, and denied submissions in the reduced public shape. Authentication is optional; a bounty that is not publicly visible returns `404`.



# Retrieve Bounty
Source: https://docs.whop.com/api-reference/beta/bounties/retrieve-bounty

/openapi/api-v1-native.json get /bounties/{id}
Retrieves a bounty by ID. Bounties outside the caller's scope return `404`.



# Update Bounty
Source: https://docs.whop.com/api-reference/beta/bounties/update-bounty

/openapi/api-v1-native.json patch /bounties/{id}
Updates a bounty. A published bounty accepts title, description, and country targeting while it is still open with nothing under review. A scheduled (not-yet-published) draft additionally accepts the reward, winner slots, and schedule.



# Cancel Bounty Submission
Source: https://docs.whop.com/api-reference/beta/bounty-submissions/cancel-bounty-submission

/openapi/api-v1-native.json delete /bounty_submissions/{bounty_submission_id}
Cancels the caller's own active attempt on a bounty and discards any accumulated capture clips. Only the worker who started the attempt can cancel it — account API keys cannot.



# Create Bounty Submission
Source: https://docs.whop.com/api-reference/beta/bounty-submissions/create-bounty-submission

/openapi/api-v1-native.json post /bounty_submissions
Creates a submission on a workforce bounty. Include a `deliverable` payload — any combination of links and uploaded files, with at least one of the two — and the submission goes straight to review; create is the only step. For `data_capture` bounties, omit the deliverable: this starts a claimed attempt whose proof accumulates server-side, and the separate submit endpoint sends it to review once complete. Requires a user credential — account API keys cannot author submissions.



# List Bounty Submissions
Source: https://docs.whop.com/api-reference/beta/bounty-submissions/list-bounty-submissions

/openapi/api-v1-native.json get /bounty_submissions
Lists bounty submissions visible to the credential — for a user token, the submissions they authored plus those on bounties they posted; for an account API key, the submissions on the account's bounties. For the anonymous view of one bounty's reviewed work, use the submissions list under the bounty instead.



# Retrieve Bounty Submission
Source: https://docs.whop.com/api-reference/beta/bounty-submissions/retrieve-bounty-submission

/openapi/api-v1-native.json get /bounty_submissions/{bounty_submission_id}
Retrieves one bounty submission the credential can see — one the caller authored, or one on a bounty they posted or their account owns.



# Submit Bounty Submission
Source: https://docs.whop.com/api-reference/beta/bounty-submissions/submit-bounty-submission

/openapi/api-v1-native.json post /bounty_submissions/{bounty_submission_id}/submit
Submits a claimed attempt for review. A livestream attempt needs an ended proof stream and can attach an optional `deliverable` — links, files, and a caption in any combination; if the attempt already went to review when its stream ended, the payload attaches to it once, until reviewers start voting. A data capture attempt instead needs enough validated clip time and takes no payload. Only the worker who started the attempt can submit it — account API keys cannot.



# Checkout Configuration
Source: https://docs.whop.com/api-reference/beta/checkout-configurations/checkout-configuration



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.

## Endpoints

| Endpoint                                                                                                           | Request                                               |
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| [List checkout configurations](/api-reference/beta/checkout-configurations/list-checkout-configurations)           | <Badge>GET</Badge> `/checkout_configurations`         |
| [Create a checkout configuration](/api-reference/beta/checkout-configurations/create-a-checkout-configuration)     | <Badge>POST</Badge> `/checkout_configurations`        |
| [Retrieve a checkout configuration](/api-reference/beta/checkout-configurations/retrieve-a-checkout-configuration) | <Badge>GET</Badge> `/checkout_configurations/{id}`    |
| [Delete a checkout configuration](/api-reference/beta/checkout-configurations/delete-a-checkout-configuration)     | <Badge>DELETE</Badge> `/checkout_configurations/{id}` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Checkout configuration ID, prefixed `ch_`.
    </ResponseField>

    <ResponseField name="account_id" type="string">
      Account ID, prefixed `biz_`.
    </ResponseField>

    <ResponseField name="affiliate_code" type="string | null">
      Affiliate code applied at checkout, or `null` when none is set.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the checkout configuration was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="currency" type="string | null">
      Currency used for setup-mode payment method availability; defaults to `usd`
      when omitted.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value metadata copied to payments and memberships. `null` without
      the `checkout_configuration:basic:read` scope.
    </ResponseField>

    <ResponseField name="mode" type="string">
      Controls whether checkout charges the buyer immediately or saves payment details for later.

      Available options: `payment`, `setup`
    </ResponseField>

    <ResponseField name="payment_method_configuration" type="object | null">
      Payment method overrides for this checkout. `null` when it uses the plan or platform defaults.

      <Accordion title="Properties">
        <ResponseField name="disabled" type="string[]">
          Payment methods explicitly disabled for checkout.
        </ResponseField>

        <ResponseField name="enabled" type="string[]">
          Payment methods explicitly enabled for checkout.
        </ResponseField>

        <ResponseField name="include_platform_defaults" type="boolean">
          Whether platform default payment methods are included.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="plan" type="object | null">
      Plan used for payment checkout. `null` in setup mode.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Plan ID, prefixed `plan_`.
        </ResponseField>

        <ResponseField name="adaptive_pricing_enabled" type="boolean">
          Whether this plan accepts local currency payments via adaptive pricing.
        </ResponseField>

        <ResponseField name="billing_period" type="integer | null">
          Recurring billing interval in days, such as 30 for monthly or 365 for annual.
          `null` for one-time plans.
        </ResponseField>

        <ResponseField name="currency" type="string">
          Three-letter ISO currency code for the plan's prices.
        </ResponseField>

        <ResponseField name="expiration_days" type="integer | null">
          Access duration in days for expiration-based plans.
        </ResponseField>

        <ResponseField name="initial_price" type="number">
          Initial purchase price in the plan currency.
        </ResponseField>

        <ResponseField name="plan_type" type="string">
          Billing model for the plan.

          Available options: `renewal`, `one_time`
        </ResponseField>

        <ResponseField name="release_method" type="string">
          Sales method for the plan.

          Available options: `buy_now`, `waitlist`
        </ResponseField>

        <ResponseField name="renewal_price" type="number">
          Recurring price charged each billing period.
        </ResponseField>

        <ResponseField name="three_ds_level" type="string | null">
          3D Secure behavior for this plan, or `null` to use the account default.

          Available options: `mandate_challenge`, `frictionless`
        </ResponseField>

        <ResponseField name="trial_period_days" type="integer | null">
          Free trial days before the first renewal charge.
        </ResponseField>

        <ResponseField name="visibility" type="string">
          Whether the plan is visible to customers or hidden from public view.

          Available options: `visible`, `hidden`, `archived`, `quick_link`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="purchase_url" type="string | null">
      Checkout URL you can send to customers.
    </ResponseField>

    <ResponseField name="redirect_url" type="string | null">
      URL customers are sent to after checkout, or `null` when no redirect is
      configured.
    </ResponseField>

    <ResponseField name="three_ds_level" type="string | null">
      3D Secure behavior for this checkout, or `null` to use the account default.

      Available options: `mandate_challenge`, `frictionless`
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the checkout configuration was last updated, as an ISO 8601 timestamp.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json CheckoutConfiguration theme={null}
      {
      	"id": "ch_xxxxxxxxxxxxxx",
      	"account_id": "biz_xxxxxxxxxxxxxx",
      	"affiliate_code": "pickaxe-partner",
      	"created_at": "2026-07-01T12:00:00Z",
      	"currency": "usd",
      	"metadata": {
      		"campaign": "summer-launch"
      	},
      	"mode": "payment",
      	"payment_method_configuration": {
      		"enabled": ["card", "apple_pay"],
      		"disabled": ["crypto"],
      		"include_platform_defaults": true
      	},
      	"plan": {
      		"id": "plan_xxxxxxxxxxxxx",
      		"visibility": "visible",
      		"plan_type": "renewal",
      		"release_method": "buy_now",
      		"currency": "usd",
      		"billing_period": 30,
      		"expiration_days": null,
      		"initial_price": 29,
      		"renewal_price": 29,
      		"trial_period_days": 7,
      		"three_ds_level": "frictionless",
      		"adaptive_pricing_enabled": true
      	},
      	"purchase_url": "https://whop.com/checkout/plan_xxxxxxxxxxxxx/?session=ch_xxxxxxxxxxxxxx",
      	"redirect_url": "https://pickaxe.example/welcome",
      	"three_ds_level": "frictionless",
      	"updated_at": "2026-07-02T12:00:00Z"
      }
      ```
    </div>
  </Column>
</Columns>


# Create a checkout configuration
Source: https://docs.whop.com/api-reference/beta/checkout-configurations/create-a-checkout-configuration

/openapi/api-v1-native.json post /checkout_configurations
Creates a reusable checkout configuration for an existing or inline plan.



# Delete a checkout configuration
Source: https://docs.whop.com/api-reference/beta/checkout-configurations/delete-a-checkout-configuration

/openapi/api-v1-native.json delete /checkout_configurations/{id}
Deletes a checkout configuration so its checkout URL can no longer be used.



# List checkout configurations
Source: https://docs.whop.com/api-reference/beta/checkout-configurations/list-checkout-configurations

/openapi/api-v1-native.json get /checkout_configurations
Lists checkout configurations for an account.



# Retrieve a checkout configuration
Source: https://docs.whop.com/api-reference/beta/checkout-configurations/retrieve-a-checkout-configuration

/openapi/api-v1-native.json get /checkout_configurations/{id}
Retrieves a checkout configuration by ID. This endpoint is public so a checkout page can load from the configuration URL.



# Create Event
Source: https://docs.whop.com/api-reference/beta/events/create-event

/openapi/api-v1-native.json post /events
Tracks a conversion or engagement event for an account.



# Events
Source: https://docs.whop.com/api-reference/beta/events/event



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.

## Endpoints

| Endpoint                                                                      | Request                                      |
| ----------------------------------------------------------------------------- | -------------------------------------------- |
| [List Events](/api-reference/beta/events/list-events)                         | <Badge>GET</Badge> `/events`                 |
| [Create Event](/api-reference/beta/events/create-event)                       | <Badge>POST</Badge> `/events`                |
| [Retrieve the pulse feed](/api-reference/beta/events/retrieve-the-pulse-feed) | <Badge>GET</Badge> `/events/pulse`           |
| [Validate Pixel](/api-reference/beta/events/validate-pixel)                   | <Badge>POST</Badge> `/events/validate_pixel` |


# List Events
Source: https://docs.whop.com/api-reference/beta/events/list-events

/openapi/api-v1-native.json get /events
Lists identity-linked events, most recent first by default. Pass identifier for one person's journey, or omit it to list events for an account within an explicit time range. Pass direction=asc to read a journey forwards from where it starts. Events are shaped like the POST /events intake: attribution in context, identity in user.



# Retrieve the pulse feed
Source: https://docs.whop.com/api-reference/beta/events/retrieve-the-pulse-feed

/openapi/api-v1-native.json get /events/pulse
Returns a fully anonymized feed of recent platform-wide money movement, most recent first: purchases, affiliate commissions, card and ad spend, app revenue, off-platform sales, wallet deposits, card loads, claimed drops, transfers between accounts, and referral bonuses. Items carry only a `type`, the underlying event name, a USD amount, a coarse location under `user`, and a timestamp coarsened to the start of the minute; missing fields are omitted, not nulled. The payload is identical for every caller; no auth is required.



# Validate Pixel
Source: https://docs.whop.com/api-reference/beta/events/validate-pixel

/openapi/api-v1-native.json post /events/validate_pixel
Checks whether the Whop pixel is installed for an account. Recent pixel events count as proof on their own, so an account that has sent data lately comes back installed without a `url`. Pass a `url` and events from that page settle it; conversion events are also read across the hostname because they commonly fire on a later confirmation page. If the requested page hasn't sent any events lately, it is fetched and read for the pixel and conversion events wired on it. `installed` is only true when the pixel was actually seen — in the account's events or in the page.



# Cancel Membership
Source: https://docs.whop.com/api-reference/beta/memberships/cancel-membership

/openapi/api-v1-native.json post /memberships/{id}/cancel
Cancels a membership immediately, revoking access right away. To cancel at the end of the billing period instead, update the membership with `cancel_at_period_end: true`.



# Extend Membership
Source: https://docs.whop.com/api-reference/beta/memberships/extend-membership

/openapi/api-v1-native.json post /memberships/{id}/extend
Adds free days to a membership, extending its current billing period, expiration date, or trial depending on the plan type.



# Invite to a Membership
Source: https://docs.whop.com/api-reference/beta/memberships/invite-to-a-membership

/openapi/api-v1-native.json post /memberships/invite
Sends an email inviting one recipient to join the account through a free plan. Identify the recipient by exactly one of `user_id` or `email`. The invitation is bound to that recipient; after signing in, accepting it immediately grants the membership without checkout. This Experimental endpoint is available only to accounts enabled for membership invitations.



# List Memberships
Source: https://docs.whop.com/api-reference/beta/memberships/list-memberships

/openapi/api-v1-native.json get /memberships
Lists every membership the caller can read: an account API key its account's; a user credential their own plus those of every account they manage. `account_id` and `user_id` only narrow that list — values outside the caller's reach return fewer results, not an error.



# Membership
Source: https://docs.whop.com/api-reference/beta/memberships/membership



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, and update metadata.

## Endpoints

| Endpoint                                                                         | Request                                        |
| -------------------------------------------------------------------------------- | ---------------------------------------------- |
| [List Memberships](/api-reference/beta/memberships/list-memberships)             | <Badge>GET</Badge> `/memberships`              |
| [Retrieve Membership](/api-reference/beta/memberships/retrieve-membership)       | <Badge>GET</Badge> `/memberships/{id}`         |
| [Update Membership](/api-reference/beta/memberships/update-membership)           | <Badge>PATCH</Badge> `/memberships/{id}`       |
| [Cancel Membership](/api-reference/beta/memberships/cancel-membership)           | <Badge>POST</Badge> `/memberships/{id}/cancel` |
| [Extend Membership](/api-reference/beta/memberships/extend-membership)           | <Badge>POST</Badge> `/memberships/{id}/extend` |
| [Pause Membership](/api-reference/beta/memberships/pause-membership)             | <Badge>POST</Badge> `/memberships/{id}/pause`  |
| [Resume Membership](/api-reference/beta/memberships/resume-membership)           | <Badge>POST</Badge> `/memberships/{id}/resume` |
| [Invite to a Membership](/api-reference/beta/memberships/invite-to-a-membership) | <Badge>POST</Badge> `/memberships/invite`      |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Membership ID, prefixed `mem_`.
    </ResponseField>

    <ResponseField name="account" type="object">
      The account (seller) this membership belongs to.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Account ID, prefixed `biz_`.
        </ResponseField>

        <ResponseField name="logo_url" type="string | null">
          Account logo image URL.
        </ResponseField>

        <ResponseField name="route" type="string">
          Account public route identifier — the `whop.com/\{route}` storefront path.
        </ResponseField>

        <ResponseField name="title" type="string">
          Account display name.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="cancel_at_period_end" type="boolean">
      Whether the membership is set to cancel when the current billing period ends.
      Only meaningful for recurring plans.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the membership was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="current_period_end" type="string | null">
      When the current billing period renews, or when a non-renewing membership
      expires, as an ISO 8601 timestamp. `null` for one-time purchases with no
      expiration.
    </ResponseField>

    <ResponseField name="license_key" type="string | null">
      The software license key for this membership. Only present when the product
      includes a software licensing experience.
    </ResponseField>

    <ResponseField name="member" type="object | null">
      The caller's member row on the account. Present only when the membership belongs to the caller; `null` on seller-side reads.

      <Accordion title="Properties">
        <ResponseField name="access_level" type="string">
          What the member can reach on the account: `customer` for paying members, `admin` for team members, `no_access` once every grant has lapsed.

          Available options: `no_access`, `admin`, `customer`
        </ResponseField>

        <ResponseField name="last_accessed_at" type="string | null">
          When the member last opened the account's content, as an ISO 8601 timestamp.
          `null` if they never have.
        </ResponseField>

        <ResponseField name="position" type="number | null">
          The member's sort position in the buyer's own account list. `null` until they arrange it.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Custom key-value pairs stored on the membership, commonly used for software
      licensing.
    </ResponseField>

    <ResponseField name="plan_id" type="string">
      The plan the buyer purchased, prefixed `plan_`.
    </ResponseField>

    <ResponseField name="product_id" type="string">
      The product this membership grants access to, prefixed `prod_`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Billing state of the membership. `active`/`trialing` memberships grant access; `past_due` is the grace period after a failed payment; `completed` one-time purchases keep access; `canceled`/`expired` do not.

      Available options: `trialing`, `active`, `past_due`, `completed`, `canceled`, `expired`, `unresolved`
    </ResponseField>

    <ResponseField name="user_id" type="string | null">
      The buyer, prefixed `user_`. `null` when the buyer is another business or the
      membership is unclaimed.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Membership theme={null}
      {
      	"id": "mem_xxxxxxxxxxxxxx",
      	"status": "active",
      	"user_id": "user_xxxxxxxxxxxxx",
      	"product_id": "prod_xxxxxxxxxxxxx",
      	"plan_id": "plan_xxxxxxxxxxxxx",
      	"license_key": "A1B2C3-D4E5F6-G7H8I9",
      	"cancel_at_period_end": false,
      	"current_period_end": "2026-08-01T00:00:00.000Z",
      	"metadata": {
      		"external_customer_id": "cus_123"
      	},
      	"created_at": "2026-07-01T00:00:00.000Z",
      	"member": {
      		"access_level": "customer",
      		"last_accessed_at": "2026-07-20T15:30:00.000Z",
      		"position": 1
      	},
      	"account": {
      		"id": "biz_xxxxxxxxxxxxxx",
      		"title": "Pickaxe",
      		"route": "pickaxe",
      		"logo_url": "https://cdn.whop.com/account.png"
      	}
      }
      ```
    </div>
  </Column>
</Columns>


# Membership activated
Source: https://docs.whop.com/api-reference/beta/memberships/membership-activated

/openapi/api-v1-native.json webhook membership.activated
Sent when a membership is activated

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:memberships`



# Membership cancel at period end changed
Source: https://docs.whop.com/api-reference/beta/memberships/membership-cancel-at-period-end-changed

/openapi/api-v1-native.json webhook membership.cancel_at_period_end_changed
Sent when a membership is cancel at period end changed

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:memberships`



# Membership deactivated
Source: https://docs.whop.com/api-reference/beta/memberships/membership-deactivated

/openapi/api-v1-native.json webhook membership.deactivated
Sent when a membership is deactivated

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:memberships`



# Membership trial ending soon
Source: https://docs.whop.com/api-reference/beta/memberships/membership-trial-ending-soon

/openapi/api-v1-native.json webhook membership.trial_ending_soon
Sent when a membership is trial ending soon

Required permissions:
 - `member:basic:read`
 - `member:email:read`
 - `webhook_receive:memberships`



# Pause Membership
Source: https://docs.whop.com/api-reference/beta/memberships/pause-membership

/openapi/api-v1-native.json post /memberships/{id}/pause
Pauses a membership's recurring payment collection. The customer keeps access but is not charged until the membership is resumed.



# Resume Membership
Source: https://docs.whop.com/api-reference/beta/memberships/resume-membership

/openapi/api-v1-native.json post /memberships/{id}/resume
Resumes a previously paused membership's recurring payment collection. Billing resumes on the next cycle.



# Retrieve Membership
Source: https://docs.whop.com/api-reference/beta/memberships/retrieve-membership

/openapi/api-v1-native.json get /memberships/{id}
Retrieves a membership by ID or license key. Accessible to the account and to the membership's own user.



# Update Membership
Source: https://docs.whop.com/api-reference/beta/memberships/update-membership

/openapi/api-v1-native.json patch /memberships/{id}
Updates a membership: merge metadata key-value pairs, or toggle `cancel_at_period_end` — `true` schedules the cancellation for the end of the current billing period, `false` reverses a pending one.



# Enroll as a Whop partner
Source: https://docs.whop.com/api-reference/beta/partners/enroll-as-a-whop-partner

/openapi/api-v1-native.json post /partners
Enrolls the calling user in the Whop partner program, making their partner businesses eligible for earnings. Idempotent — enrolling again keeps the original enrollment time.



# List referred business earnings
Source: https://docs.whop.com/api-reference/beta/partners/list-referred-business-earnings

/openapi/api-v1-native.json get /partners/businesses/{id}/earnings
Lists the earnings Whop pays out for one referred business's activity, most recent first.



# List referred businesses
Source: https://docs.whop.com/api-reference/beta/partners/list-referred-businesses

/openapi/api-v1-native.json get /partners/businesses
Lists the businesses the authenticated user referred onto Whop, most recent first.



# List the users the caller referred
Source: https://docs.whop.com/api-reference/beta/partners/list-the-users-the-caller-referred

/openapi/api-v1-native.json get /partners/referred_users
Lists the users the caller referred onto Whop (newest first), each with the second-tier earnings the caller has made from that user's businesses.



# Partners
Source: https://docs.whop.com/api-reference/beta/partners/partner



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.

## Endpoints

| Endpoint                                                                                              | Request                                                 |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [Enroll as a Whop partner](/api-reference/beta/partners/enroll-as-a-whop-partner)                     | <Badge>POST</Badge> `/partners`                         |
| [List referred businesses](/api-reference/beta/partners/list-referred-businesses)                     | <Badge>GET</Badge> `/partners/businesses`               |
| [Retrieve a referred business](/api-reference/beta/partners/retrieve-a-referred-business)             | <Badge>GET</Badge> `/partners/businesses/{id}`          |
| [List referred business earnings](/api-reference/beta/partners/list-referred-business-earnings)       | <Badge>GET</Badge> `/partners/businesses/{id}/earnings` |
| [Retrieve the leaderboard](/api-reference/beta/partners/retrieve-the-leaderboard)                     | <Badge>GET</Badge> `/partners/leaderboard`              |
| [List the users the caller referred](/api-reference/beta/partners/list-the-users-the-caller-referred) | <Badge>GET</Badge> `/partners/referred_users`           |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Partner business ID.
    </ResponseField>

    <ResponseField name="account" type="object | null">
      Referred account.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Referred account ID.
        </ResponseField>

        <ResponseField name="capabilities" type="object | null">
          <Accordion title="Properties">
            <ResponseField name="accept_bank_payments" type="string">
              Bank payins: debits, transfers, and local bank rails

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="accept_bnpl_payments" type="string">
              Buy-now-pay-later payins; requires approval

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="accept_card_payments" type="string">
              Card payins, including Apple Pay and Google Pay

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="bank_deposit" type="string">
              Deposits by bank wire or ACH to the account's virtual bank account

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="card_deposit" type="string">
              Balance top-ups by charging a stored payment method

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="card_issuing" type="string">
              Issuing Whop cards; requires card application approval

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="crypto_deposit" type="string">
              On-chain deposits to the account's crypto wallet

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="crypto_payout" type="string">
              On-chain payouts to a crypto wallet

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="instant_payout" type="string">
              Instant payouts to an eligible payout destination

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="run_ads" type="string">
              Launching ad campaigns through Whop Ads. `inactive` while a requested ads services agreement is awaiting the account's signature.

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="standard_payout" type="string">
              Standard payouts to an external payout destination

              Available options: `active`, `inactive`, `pending`
            </ResponseField>

            <ResponseField name="transfer" type="string">
              Transfers to other accounts

              Available options: `active`, `inactive`, `pending`
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="logo_url" type="string | null">
          Referred account logo URL.
        </ResponseField>

        <ResponseField name="recommended_actions" type="object[] | null">
          Optional actions that unlock capabilities or grow the referred account.

          <Accordion title="Properties">
            <ResponseField name="action" type="string">
              The recommendation; new values may be added, so handle unknown actions gracefully

              Available options: `theme_business`, `create_product`, `create_plan`, `verify_identity`, `connect_affiliate_program`, `create_promotion`, `setup_tracking_pixel`, `migrate_from_stripe`, `accept_first_payment`, `launch_first_ad`, `launch_draft_campaign`, `increase_ad_budget`, `refresh_ad_creatives`, `fix_ad_billing`, `exclude_customers_from_ads`, `retarget_abandoned_checkouts`, `invite_team_member`, `enable_tax_collection`, `create_card`, `join_whop_university`, `apply_for_financing`
            </ResponseField>

            <ResponseField name="blocked_capabilities" type="string[]">
              Capabilities this would unlock, or empty
            </ResponseField>

            <ResponseField name="cta" type="string">
              The URL the call-to-action links to
            </ResponseField>

            <ResponseField name="cta_label" type="string">
              Button label
            </ResponseField>

            <ResponseField name="description" type="string">
              Supporting copy, or empty
            </ResponseField>

            <ResponseField name="icon_url" type="string | null">
              Illustration icon URL, or `null`
            </ResponseField>

            <ResponseField name="impact_score" type="integer | null">
              Estimated impact from 0-100, or `null` when not ranked
            </ResponseField>

            <ResponseField name="reasoning" type="string | null">
              Why this action was recommended, or `null`
            </ResponseField>

            <ResponseField name="status" type="string">
              Always optional — never blocking

              Available options: `optional`
            </ResponseField>

            <ResponseField name="title" type="string">
              Headline for the recommendation
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="required_actions" type="object[] | null">
          Actions the referred account owner must take to unblock capabilities.

          <Accordion title="Properties">
            <ResponseField name="action" type="string">
              What the holder must do; new values may be added, so handle unknown actions gracefully

              Available options: `deposit_funds`, `submit_information_request`, `verify_identity`, `connect_fulfillment_tracker`, `setup_apple_pay_domains`, `configure_tax_remitter`, `add_vat_registration`
            </ResponseField>

            <ResponseField name="blocked_capabilities" type="string[]">
              Capabilities gated until this is resolved
            </ResponseField>

            <ResponseField name="cta" type="string | null">
              The URL the call-to-action links to, or null when there is no button
            </ResponseField>

            <ResponseField name="cta_label" type="string">
              Button label, or empty when there is no button
            </ResponseField>

            <ResponseField name="description" type="string">
              Supporting copy, or empty
            </ResponseField>

            <ResponseField name="icon_url" type="string | null">
              The URL of the action's illustration icon, or null if it has none
            </ResponseField>

            <ResponseField name="status" type="string">
              required (act now) or pending (under review)

              Available options: `required`, `pending`
            </ResponseField>

            <ResponseField name="title" type="string">
              Headline for the action
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="route" type="string">
          Referred account route.
        </ResponseField>

        <ResponseField name="title" type="string">
          Referred account display name.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the partner business was created.
    </ResponseField>

    <ResponseField name="earnings_usd" type="object">
      <Accordion title="Properties">
        <ResponseField name="completed" type="string">
          Commission already paid out, in USD.
        </ResponseField>

        <ResponseField name="pending" type="string">
          Commission scheduled but not yet paid, in USD.
        </ResponseField>

        <ResponseField name="total" type="string">
          Pending + completed commission, in USD.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="first_tier_partner" type="object | null">
      The partner who referred the business owner onto Whop (first tier). Null if there is no active first-tier partner.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          User ID, prefixed `user_`.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The user's display name.
        </ResponseField>

        <ResponseField name="profile_picture" type="object">
          The user's profile picture.

          <Accordion title="Properties">
            <ResponseField name="url" type="string">
              The user's profile picture URL.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="username" type="string">
          The user's unique username.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="my_partner_tier" type="string">
      Which tier the caller earns on for this business: `first` (they referred the owner) or `second` (they referred the first-tier partner).

      Available options: `first`, `second`
    </ResponseField>

    <ResponseField name="object" type="string" />

    <ResponseField name="owner" type="object | null">
      The owner of the referred business.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          User ID, prefixed `user_`.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The user's display name.
        </ResponseField>

        <ResponseField name="profile_picture" type="object">
          The user's profile picture.

          <Accordion title="Properties">
            <ResponseField name="url" type="string">
              The user's profile picture URL.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="username" type="string">
          The user's unique username.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="payout_percentages" type="object">
      The referrer's commission rate for each income source, expressed as a fraction (0.3 = 30%).

      <Accordion title="Properties">
        <ResponseField name="ad_spend" type="number | null">
          Share of the referred business's Whop Ads spend.
        </ResponseField>

        <ResponseField name="card_interchange" type="number | null">
          Share of Whop's profit from card interchange.
        </ResponseField>

        <ResponseField name="sales" type="number">
          Share of Whop's profit from product sales.
        </ResponseField>

        <ResponseField name="transfer" type="number | null">
          Share of Whop's profit from platform balance transfers.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="referral_expires_at" type="string | null">
      When the referral expires.
    </ResponseField>

    <ResponseField name="referral_started_at" type="string | null">
      When the referral became active.
    </ResponseField>

    <ResponseField name="second_tier_partner" type="object | null">
      The second-tier partner who earns on this business (referred the first-tier partner). Null if there is no active second-tier partner.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          User ID, prefixed `user_`.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The user's display name.
        </ResponseField>

        <ResponseField name="profile_picture" type="object">
          The user's profile picture.

          <Accordion title="Properties">
            <ResponseField name="url" type="string">
              The user's profile picture URL.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="username" type="string">
          The user's unique username.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="status" type="string">
      Current referral status.

      Available options: `active`, `removed`
    </ResponseField>

    <ResponseField name="volume_usd" type="object">
      <Accordion title="Properties">
        <ResponseField name="attributed" type="string">
          Credited GMV (awaiting\_settlement + settled); excludes canceled and reversed,
          in USD.
        </ResponseField>

        <ResponseField name="awaiting_settlement" type="string">
          GMV awaiting settlement (commission not yet computed), in USD.
        </ResponseField>

        <ResponseField name="settled" type="string">
          GMV of pending + completed payments, in USD.
        </ResponseField>
      </Accordion>
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json PartnerBusiness theme={null}
      {
      	"id": "bref_xxxxxxxxxxxx",
      	"account": {
      		"id": "biz_xxxxxxxxxxxxxx",
      		"capabilities": {
      			"accept_bank_payments": "active",
      			"accept_bnpl_payments": "inactive",
      			"accept_card_payments": "active",
      			"bank_deposit": "inactive",
      			"card_deposit": "active",
      			"card_issuing": "inactive",
      			"crypto_deposit": "active",
      			"crypto_payout": "inactive",
      			"instant_payout": "inactive",
      			"run_ads": "active",
      			"standard_payout": "inactive",
      			"transfer": "inactive"
      		},
      		"logo_url": "https://cdn.whop.com/logo.png",
      		"recommended_actions": [
      			{
      				"action": "accept_first_payment",
      				"blocked_capabilities": [],
      				"cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/links/checkout/create/",
      				"cta_label": "Create payment link",
      				"description": "",
      				"icon_url": "https://whop.com/illustrations/orange/card.svg",
      				"impact_score": null,
      				"reasoning": null,
      				"status": "optional",
      				"title": "Accept your first payment."
      			}
      		],
      		"required_actions": [
      			{
      				"action": "verify_identity",
      				"blocked_capabilities": [
      					"standard_payout",
      					"instant_payout",
      					"crypto_payout",
      					"transfer"
      				],
      				"cta": "https://whop.com/dashboard/biz_xxxxxxxxxxxxxx/balance/?verify=true",
      				"cta_label": "Verify now",
      				"description": "Complete verification to continue accepting payments.",
      				"icon_url": null,
      				"status": "required",
      				"title": "Identity verification required"
      			}
      		],
      		"route": "pickaxe",
      		"title": "Pickaxe"
      	},
      	"created_at": "2026-06-01T12:00:00Z",
      	"earnings_usd": {
      		"completed": "120.50",
      		"pending": "45.25",
      		"total": "165.75"
      	},
      	"first_tier_partner": {
      		"id": "user_yyyyyyyyyyyy",
      		"name": "Alex Partner",
      		"profile_picture": {
      			"url": "https://cdn.whop.com/user.png"
      		},
      		"username": "alexpartner"
      	},
      	"my_partner_tier": "first",
      	"object": "partner_business",
      	"owner": {
      		"id": "user_xxxxxxxxxxxx",
      		"name": "Jane Doe",
      		"profile_picture": {
      			"url": "https://cdn.whop.com/user.png"
      		},
      		"username": "jane"
      	},
      	"payout_percentages": {
      		"sales": 0.3,
      		"ad_spend": 0.015,
      		"transfer": 0.3,
      		"card_interchange": 0.3
      	},
      	"referral_expires_at": "2027-06-01T12:00:00Z",
      	"referral_started_at": "2026-06-01T12:00:00Z",
      	"second_tier_partner": {
      		"id": "user_zzzzzzzzzzzz",
      		"name": "Sam Referrer",
      		"profile_picture": {
      			"url": "https://cdn.whop.com/user.png"
      		},
      		"username": "samreferrer"
      	},
      	"status": "active",
      	"volume_usd": {
      		"attributed": "11050.00",
      		"awaiting_settlement": "250.00",
      		"settled": "10800.00"
      	}
      }
      ```
    </div>
  </Column>
</Columns>


# Retrieve a referred business
Source: https://docs.whop.com/api-reference/beta/partners/retrieve-a-referred-business

/openapi/api-v1-native.json get /partners/businesses/{id}
Retrieves a single referred business and its referral terms.



# Retrieve the leaderboard
Source: https://docs.whop.com/api-reference/beta/partners/retrieve-the-leaderboard

/openapi/api-v1-native.json get /partners/leaderboard
Ranks referrers by partner business earnings — all-time by default, or over the current day, month, year, or trailing 30 days. Authentication is optional: authenticated callers also get their own standing, anonymous callers get the rankings alone.



# Create Payment Method Domain
Source: https://docs.whop.com/api-reference/beta/payment-method-domains/create-payment-method-domain

/openapi/api-v1-native.json post /payment_method_domains
Registers a hostname with the wallet provider and attempts verification inline. Returns `verified` when the provider fetched the domain-association file (for Apple Pay, `/.well-known/apple-developer-merchantid-domain-association`), or `pending` when it could not — host the file, then retry with the verify endpoint.



# Delete Payment Method Domain
Source: https://docs.whop.com/api-reference/beta/payment-method-domains/delete-payment-method-domain

/openapi/api-v1-native.json delete /payment_method_domains/{id}
Unregisters a payment method domain so its wallet payment methods stop rendering there.



# List Payment Method Domains
Source: https://docs.whop.com/api-reference/beta/payment-method-domains/list-payment-method-domains

/openapi/api-v1-native.json get /payment_method_domains
Lists payment method domains. Without `account_id`, returns the caller's own domains and those of every connected account.



# Payment Method Domain
Source: https://docs.whop.com/api-reference/beta/payment-method-domains/payment-method-domain



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.

## Endpoints

| Endpoint                                                                                                    | Request                                                   |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [List Payment Method Domains](/api-reference/beta/payment-method-domains/list-payment-method-domains)       | <Badge>GET</Badge> `/payment_method_domains`              |
| [Create Payment Method Domain](/api-reference/beta/payment-method-domains/create-payment-method-domain)     | <Badge>POST</Badge> `/payment_method_domains`             |
| [Retrieve Payment Method Domain](/api-reference/beta/payment-method-domains/retrieve-payment-method-domain) | <Badge>GET</Badge> `/payment_method_domains/{id}`         |
| [Delete Payment Method Domain](/api-reference/beta/payment-method-domains/delete-payment-method-domain)     | <Badge>DELETE</Badge> `/payment_method_domains/{id}`      |
| [Verify Payment Method Domain](/api-reference/beta/payment-method-domains/verify-payment-method-domain)     | <Badge>POST</Badge> `/payment_method_domains/{id}/verify` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Payment method domain ID, prefixed `pmd_`.
    </ResponseField>

    <ResponseField name="account_id" type="string | null">
      ID of the account the domain is registered for, prefixed `biz_`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the domain was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="hostname" type="string">
      Hostname the checkout is served from (e.g. `checkout.example.com`).
    </ResponseField>

    <ResponseField name="provider" type="string">
      Wallet provider the domain is registered with.

      Available options: `apple`
    </ResponseField>

    <ResponseField name="status" type="string">
      Verification status. `pending` means the provider could not fetch the domain-association file yet; only `verified` domains show wallet payment methods at checkout.

      Available options: `pending`, `verified`
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the domain was last updated, as an ISO 8601 timestamp.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json PaymentMethodDomain theme={null}
      {
      	"id": "pmd_xxxxxxxxxxxxxx",
      	"account_id": "biz_xxxxxxxxxxxxxx",
      	"hostname": "checkout.example.com",
      	"provider": "apple",
      	"status": "verified",
      	"created_at": "2026-08-01T12:00:00Z",
      	"updated_at": "2026-08-01T12:05:00Z"
      }
      ```
    </div>
  </Column>
</Columns>


# Retrieve Payment Method Domain
Source: https://docs.whop.com/api-reference/beta/payment-method-domains/retrieve-payment-method-domain

/openapi/api-v1-native.json get /payment_method_domains/{id}
Retrieves a payment method domain to check its verification status.



# Verify Payment Method Domain
Source: https://docs.whop.com/api-reference/beta/payment-method-domains/verify-payment-method-domain

/openapi/api-v1-native.json post /payment_method_domains/{id}/verify
Re-attempts provider verification of a pending domain once the association file is hosted. Fails with a `bad_request` explaining what to fix; verifying an already `verified` domain is a no-op.



# List People
Source: https://docs.whop.com/api-reference/beta/people/list-people

/openapi/api-v1-native.json get /people
Lists the people (visitors and customers) of an account: the identity-linked person profiles aggregated from every pixel, payment, and platform event — identities, purchases and LTV, geo/device profile, traffic sources, and first/last marketing touches.



# People
Source: https://docs.whop.com/api-reference/beta/people/person



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.

## Endpoints

| Endpoint                                                      | Request                                  |
| ------------------------------------------------------------- | ---------------------------------------- |
| [List People](/api-reference/beta/people/list-people)         | <Badge>GET</Badge> `/people`             |
| [Retrieve Person](/api-reference/beta/people/retrieve-person) | <Badge>GET</Badge> `/people/{person_id}` |


# Retrieve Person
Source: https://docs.whop.com/api-reference/beta/people/retrieve-person

/openapi/api-v1-native.json get /people/{person_id}
Retrieves one person for an account. The identifier can be a person ID (prefixed `prsn_`), a user ID (prefixed `user_`), an email address, or a phone number — merged people resolve to the surviving profile.



# Calculate Tax
Source: https://docs.whop.com/api-reference/beta/plans/calculate-tax

openapi/api-v1-native.json POST /plans/{id}/calculate_tax
Previews tax for a plan before checkout, based on the buyer's location.

Use it in a checkout preview to show the buyer their subtotal, tax, and total. The request is read-only — it doesn't create a checkout, reserve inventory, or charge the buyer.


# Create Plan
Source: https://docs.whop.com/api-reference/beta/plans/create-plan

/openapi/api-v1-native.json post /plans
Create a new pricing plan for a product. The plan defines the billing interval, price, and availability for customers.



# Delete Plan
Source: https://docs.whop.com/api-reference/beta/plans/delete-plan

/openapi/api-v1-native.json delete /plans/{id}
Permanently delete a plan from a product. Existing memberships on this plan will not be affected.



# List Plans
Source: https://docs.whop.com/api-reference/beta/plans/list-plans

/openapi/api-v1-native.json get /plans
Returns a paginated list of plans belonging to an account, with optional filtering by visibility, type, release method, and product.



# Plan
Source: https://docs.whop.com/api-reference/beta/plans/plan



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.

## Endpoints

| Endpoint                                                 | Request                                         |
| -------------------------------------------------------- | ----------------------------------------------- |
| [List Plans](/api-reference/beta/plans/list-plans)       | <Badge>GET</Badge> `/plans`                     |
| [Create Plan](/api-reference/beta/plans/create-plan)     | <Badge>POST</Badge> `/plans`                    |
| [Retrieve Plan](/api-reference/beta/plans/retrieve-plan) | <Badge>GET</Badge> `/plans/{id}`                |
| [Update Plan](/api-reference/beta/plans/update-plan)     | <Badge>PATCH</Badge> `/plans/{id}`              |
| [Delete Plan](/api-reference/beta/plans/delete-plan)     | <Badge>DELETE</Badge> `/plans/{id}`             |
| [Calculate Tax](/api-reference/beta/plans/calculate-tax) | <Badge>POST</Badge> `/plans/{id}/calculate_tax` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Plan ID, prefixed `plan_`.
    </ResponseField>

    <ResponseField name="account" type="object | null">
      Account that sells this plan; `null` for standalone invoice plans.
    </ResponseField>

    <ResponseField name="adaptive_pricing_enabled" type="boolean">
      Whether adaptive pricing is enabled for this plan. Raw setting — does not
      check processor compatibility or feature flags.
    </ResponseField>

    <ResponseField name="billing_period" type="number | null">
      Number of days between recurring charges, such as 30 for monthly or 365 for
      annual. `null` for one-time plans.
    </ResponseField>

    <ResponseField name="cancel_discount_intervals" type="number | null">
      Billing intervals the cancellation discount applies to (`0` forever, `1` first
      payment, or a month count). `null` when none is offered or the actor lacks the
      `plan:basic:read` scope.
    </ResponseField>

    <ResponseField name="cancel_discount_percentage" type="number | null">
      Cancellation discount as a whole-number percentage. `null` when none is
      offered or the actor lacks the `plan:basic:read` scope.
    </ResponseField>

    <ResponseField name="checkout_styling" type="object | null">
      Plan-level checkout styling (`background_color`, `button_color`,
      `font_family`, `border_style`); `null` inherits the account default.
    </ResponseField>

    <ResponseField name="collect_tax" type="boolean">
      Whether tax is collected on purchases of this plan, based on the account's tax
      configuration.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the plan was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Three-letter ISO currency code for this plan's prices.

      Available options: `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`
    </ResponseField>

    <ResponseField name="custom_fields" type="object[]">
      Custom input fields collected on the checkout form.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Custom field ID, prefixed `field_`.
        </ResponseField>

        <ResponseField name="field_type" type="string">
          Custom field input type.

          Available options: `text`
        </ResponseField>

        <ResponseField name="name" type="string">
          Field label shown to customer at checkout.
        </ResponseField>

        <ResponseField name="order" type="number">
          Field position on checkout form.
        </ResponseField>

        <ResponseField name="placeholder" type="string | null">
          Placeholder text shown in the empty field. `null` if none is set.
        </ResponseField>

        <ResponseField name="required" type="boolean">
          Whether the customer must complete this field to check out.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="deletable" type="boolean | null">
      Whether the plan can be deleted (it has no memberships or waitlist entries).
      `null` unless the actor has the `plan:basic:read` scope on the plan's account.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Customer-visible plan description. Maximum 1000 characters. `null` if no
      description is set.
    </ResponseField>

    <ResponseField name="expiration_days" type="number | null">
      Access duration in days for expiration-based plans, such as 365 for a one-year
      pass. `null` for plans without an expiration.
    </ResponseField>

    <ResponseField name="formatted_price" type="string">
      Human-readable price for display (currency + interval), e.g. "\$10 / month".
    </ResponseField>

    <ResponseField name="image" type="object | null">
      Pricing-tier image (`url`, `blurhash`) shown on the product page; `null` when
      no image is set.
    </ResponseField>

    <ResponseField name="initial_price" type="number">
      Initial purchase price in plan currency.
    </ResponseField>

    <ResponseField name="internal_notes" type="string | null">
      Private notes not shown to customers. `null` unless the actor has the
      `plan:basic:read` scope on the plan's account.
    </ResponseField>

    <ResponseField name="invoice" type="object | null">
      Invoice this plan was generated for; `null` unless created for an invoice.
    </ResponseField>

    <ResponseField name="member_count" type="number | null">
      Active memberships through this plan. `null` unless the actor has the
      `plan:basic:read` scope on the plan's account.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value pairs stored on the plan. Included in webhook payloads for
      payment and membership events. Maximum 50 keys, 100 characters per key, 500
      characters per value.
    </ResponseField>

    <ResponseField name="offer_cancel_discount" type="boolean | null">
      Whether a cancellation discount is offered. `null` unless the actor has the
      `plan:basic:read` scope on the plan's account.
    </ResponseField>

    <ResponseField name="payment_method_configuration" type="object | null">
      Payment method configuration (`enabled`, `disabled`,
      `include_platform_defaults`); `null` when plan uses default settings.
    </ResponseField>

    <ResponseField name="plan_type" type="string">
      Billing model for this plan.

      Available options: `renewal`, `one_time`
    </ResponseField>

    <ResponseField name="product" type="object | null">
      Product this plan belongs to; `null` for standalone plans.
    </ResponseField>

    <ResponseField name="purchase_url" type="string">
      URL where customers can purchase this plan directly.
    </ResponseField>

    <ResponseField name="release_method" type="string">
      Sales method for this plan.

      Available options: `buy_now`, `waitlist`
    </ResponseField>

    <ResponseField name="renewal_price" type="number">
      Recurring price charged every billing period.
    </ResponseField>

    <ResponseField name="split_pay_required_payments" type="number | null">
      Installment payments required before the subscription pauses. Must be greater
      than 1. `null` if split pay is not configured.
    </ResponseField>

    <ResponseField name="stock" type="number | null">
      Units available for purchase. `null` unless the actor has the
      `plan:basic:read` scope on the plan's account.
    </ResponseField>

    <ResponseField name="strike_through_initial_price" type="number | null">
      Original initial price shown with a strikethrough, in the plan's currency.
      `null` when no strikethrough is set.
    </ResponseField>

    <ResponseField name="strike_through_renewal_price" type="number | null">
      Original renewal price shown with a strikethrough, in the plan's currency.
      `null` when no strikethrough is set.
    </ResponseField>

    <ResponseField name="tax_type" type="string">
      How tax is handled for this plan, including whether tax is included in the price, added at checkout, or not configured.

      Available options: `inclusive`, `exclusive`, `unspecified`
    </ResponseField>

    <ResponseField name="three_ds_level" type="string | null">
      3D Secure behavior for this plan; `null` inherits the account default.

      Available options: `mandate_challenge`, `frictionless`
    </ResponseField>

    <ResponseField name="title" type="string | null">
      Plan display name shown to customers. Maximum 30 characters. `null` if no
      title has been set.
    </ResponseField>

    <ResponseField name="trial_period_days" type="number | null">
      Free trial days before the first renewal charge. `null` if no trial is
      configured or the user has already used a trial for this plan.
    </ResponseField>

    <ResponseField name="unlimited_stock" type="boolean">
      Whether the plan has unlimited stock. When `true`, the `stock` field is
      ignored; waitlist plans always report `true`.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the plan was last updated, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="visibility" type="string">
      Controls where this plan can be seen. When `hidden`, the plan is reachable only by its direct link.

      Available options: `visible`, `hidden`, `archived`, `quick_link`
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Plan theme={null}
      {
      	"id": "plan_xxxxxxxxxxxxx",
      	"account": {
      		"id": "biz_xxxxxxxxxxxxxx",
      		"title": "Pickaxe"
      	},
      	"adaptive_pricing_enabled": true,
      	"billing_period": 30,
      	"cancel_discount_intervals": null,
      	"cancel_discount_percentage": null,
      	"checkout_styling": null,
      	"collect_tax": true,
      	"created_at": "2023-12-01T05:00:00.401Z",
      	"currency": "usd",
      	"custom_fields": [
      		{
      			"id": "cusf_xxxxxxxxxxxx",
      			"field_type": "text",
      			"name": "Discord username",
      			"order": 0,
      			"placeholder": "e.g. pickaxe_user",
      			"required": true
      		}
      	],
      	"deletable": false,
      	"description": "Monthly access to Pickaxe Analytics.",
      	"expiration_days": null,
      	"formatted_price": "$29.00 / month",
      	"image": null,
      	"initial_price": 29,
      	"internal_notes": "Standard monthly plan",
      	"invoice": null,
      	"member_count": 42,
      	"metadata": {
      		"external_plan_id": "monthly"
      	},
      	"offer_cancel_discount": false,
      	"payment_method_configuration": {
      		"enabled": ["card"],
      		"disabled": [],
      		"include_platform_defaults": true
      	},
      	"plan_type": "renewal",
      	"product": {
      		"id": "prod_xxxxxxxxxxxxx",
      		"title": "Pickaxe Analytics"
      	},
      	"purchase_url": "https://whop.com/pickaxe-analytics/checkout/plan_xxxxxxxxxxxxx",
      	"release_method": "buy_now",
      	"renewal_price": 29,
      	"split_pay_required_payments": null,
      	"stock": null,
      	"strike_through_initial_price": null,
      	"strike_through_renewal_price": null,
      	"tax_type": "exclusive",
      	"three_ds_level": "frictionless",
      	"title": "Monthly",
      	"trial_period_days": 7,
      	"unlimited_stock": true,
      	"updated_at": "2023-12-01T05:00:00.401Z",
      	"visibility": "visible"
      }
      ```
    </div>
  </Column>
</Columns>


# Plan created
Source: https://docs.whop.com/api-reference/beta/plans/plan-created

/openapi/api-v1-native.json webhook plan.created
Sent when a plan is created

Required permissions:
 - `webhook_receive:plans`



# Plan deleted
Source: https://docs.whop.com/api-reference/beta/plans/plan-deleted

/openapi/api-v1-native.json webhook plan.deleted
Sent when a plan is deleted

Required permissions:
 - `webhook_receive:plans`



# Plan updated
Source: https://docs.whop.com/api-reference/beta/plans/plan-updated

/openapi/api-v1-native.json webhook plan.updated
Sent when a plan is updated

Required permissions:
 - `webhook_receive:plans`



# Retrieve Plan
Source: https://docs.whop.com/api-reference/beta/plans/retrieve-plan

/openapi/api-v1-native.json get /plans/{id}
Retrieves the details of an existing plan.



# Update Plan
Source: https://docs.whop.com/api-reference/beta/plans/update-plan

/openapi/api-v1-native.json patch /plans/{id}
Update a plan's pricing, billing interval, visibility, stock, and other settings.



# Create Product
Source: https://docs.whop.com/api-reference/beta/products/create-product

/openapi/api-v1-native.json post /products
Creates a new product for an account.



# Delete Product
Source: https://docs.whop.com/api-reference/beta/products/delete-product

/openapi/api-v1-native.json delete /products/{id}
Deletes a product. Only products with no memberships, entries, reviews, or invoices can be deleted.



# List Products
Source: https://docs.whop.com/api-reference/beta/products/list-products

/openapi/api-v1-native.json get /products
Returns a paginated list of products belonging to an account.



# Product
Source: https://docs.whop.com/api-reference/beta/products/product



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 create products, list products visible to your credentials, retrieve product details, update product metadata or merchandising fields, and delete products that should no longer be sold.

## Endpoints

| Endpoint                                                            | Request                                        |
| ------------------------------------------------------------------- | ---------------------------------------------- |
| [List Products](/api-reference/beta/products/list-products)         | <Badge>GET</Badge> `/products`                 |
| [Create Product](/api-reference/beta/products/create-product)       | <Badge>POST</Badge> `/products`                |
| [Retrieve Product](/api-reference/beta/products/retrieve-product)   | <Badge>GET</Badge> `/products/{id}`            |
| [Update Product](/api-reference/beta/products/update-product)       | <Badge>PATCH</Badge> `/products/{id}`          |
| [Delete Product](/api-reference/beta/products/delete-product)       | <Badge>DELETE</Badge> `/products/{id}`         |
| [Publish Product](/api-reference/beta/products/publish-product)     | <Badge>POST</Badge> `/products/{id}/publish`   |
| [Unpublish Product](/api-reference/beta/products/unpublish-product) | <Badge>POST</Badge> `/products/{id}/unpublish` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Product ID, prefixed `prod_`.
    </ResponseField>

    <ResponseField name="account" type="object | null">
      Account that sells this product.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the product was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="custom_cta" type="string | null">
      Call-to-action button label shown on the product purchase page.

      Available options: `get_access`, `join`, `order_now`, `shop_now`, `call_now`, `donate_now`, `contact_us`, `sign_up`, `subscribe`, `purchase`, `get_offer`, `apply_now`, `complete_order`
    </ResponseField>

    <ResponseField name="custom_cta_url" type="string | null">
      URL the call-to-action button links to instead of checkout.
    </ResponseField>

    <ResponseField name="custom_statement_descriptor" type="string | null">
      Custom text label on customer's bank statement.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Written description displayed on product page.
    </ResponseField>

    <ResponseField name="external_identifier" type="string | null">
      External identifier stored on the product for your own reference.
    </ResponseField>

    <ResponseField name="gallery_images" type="object[]">
      Gallery images for this product, ordered by position.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Gallery image ID.
        </ResponseField>

        <ResponseField name="content_type" type="string | null">
          Uploaded file MIME type, such as image/jpeg.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          Pre-optimized URL for rendering this image on the client.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="global_affiliate_percentage" type="number | null">
      Commission rate affiliates earn through the global affiliate program.
    </ResponseField>

    <ResponseField name="global_affiliate_status" type="string | null">
      Enrollment status in the global affiliate program.

      Available options: `enabled`, `disabled`
    </ResponseField>

    <ResponseField name="headline" type="string | null">
      Short marketing headline displayed on product page.
    </ResponseField>

    <ResponseField name="marketplace_status" type="string">
      Listing state on the whop.com marketplace. `pending_review` means submitted and awaiting review; `live_marketplace` means approved and discoverable.

      Available options: `not_available`, `pending_review`, `live_marketplace`
    </ResponseField>

    <ResponseField name="member_affiliate_percentage" type="number | null">
      Commission rate members earn through the member affiliate program.
    </ResponseField>

    <ResponseField name="member_affiliate_status" type="string | null">
      Enrollment status in the member affiliate program.

      Available options: `enabled`, `disabled`
    </ResponseField>

    <ResponseField name="member_count" type="number">
      Active memberships for this product; 0 if public member counts are disabled.
    </ResponseField>

    <ResponseField name="metadata" type="object | null">
      Custom key-value pairs stored on the product.
    </ResponseField>

    <ResponseField name="owner_user" type="object | null">
      User who owns the account selling this product.
    </ResponseField>

    <ResponseField name="product_tax_code" type="object | null">
      Tax classification code for this product, or `null` if no tax code is set.
    </ResponseField>

    <ResponseField name="published_reviews_count" type="number">
      Published customer reviews for this product.
    </ResponseField>

    <ResponseField name="route" type="string">
      URL slug for the product's public link.
    </ResponseField>

    <ResponseField name="title" type="string">
      Product display name shown to customers.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the product was last updated, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="verified" type="boolean">
      Whether the product has been verified by Whop.
    </ResponseField>

    <ResponseField name="visibility" type="string | null">
      Whether the product is publicly visible, hidden, or archived.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Product theme={null}
      {
      	"id": "prod_xxxxxxxxxxxxx",
      	"account": {
      		"id": "biz_xxxxxxxxxxxxxx",
      		"route": "pickaxe",
      		"title": "Pickaxe"
      	},
      	"created_at": "2023-12-01T05:00:00.401Z",
      	"custom_cta": "get_access",
      	"custom_cta_url": "https://example.com/signup",
      	"custom_statement_descriptor": "PICKAXE",
      	"description": "Track your revenue, members, and growth in real time.",
      	"external_identifier": "ext_prod_12345",
      	"gallery_images": [
      		{
      			"id": "file_xxxxxxxxxxxxx",
      			"content_type": "image/jpeg",
      			"url": "https://media.whop.com/abc123/optimized.jpg"
      		}
      	],
      	"global_affiliate_percentage": 6.9,
      	"global_affiliate_status": "enabled",
      	"headline": "Real-time data analytics for creators",
      	"marketplace_status": "live_marketplace",
      	"member_affiliate_percentage": 6.9,
      	"member_affiliate_status": "enabled",
      	"member_count": 42,
      	"metadata": {
      		"external_product_id": "prod_123"
      	},
      	"owner_user": {
      		"id": "user_xxxxxxxxxxxxx",
      		"name": "John Doe",
      		"username": "johndoe42"
      	},
      	"product_tax_code": {
      		"id": "ptc_xxxxxxxxxxxxxx",
      		"name": "Digital - SaaS",
      		"product_type": "digital"
      	},
      	"published_reviews_count": 12,
      	"route": "pickaxe-analytics",
      	"title": "Pickaxe Analytics",
      	"updated_at": "2023-12-01T05:00:00.401Z",
      	"verified": true,
      	"visibility": "visible"
      }
      ```
    </div>
  </Column>
</Columns>


# Product created
Source: https://docs.whop.com/api-reference/beta/products/product-created

/openapi/api-v1-native.json webhook product.created
Sent when a product is created

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Product deleted
Source: https://docs.whop.com/api-reference/beta/products/product-deleted

/openapi/api-v1-native.json webhook product.deleted
Sent when a product is deleted

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Product published
Source: https://docs.whop.com/api-reference/beta/products/product-published

/openapi/api-v1-native.json webhook product.published
Sent when a product is published

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Product unpublished
Source: https://docs.whop.com/api-reference/beta/products/product-unpublished

/openapi/api-v1-native.json webhook product.unpublished
Sent when a product is unpublished

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Product updated
Source: https://docs.whop.com/api-reference/beta/products/product-updated

/openapi/api-v1-native.json webhook product.updated
Sent when a product is updated

Required permissions:
 - `access_pass:basic:read`
 - `webhook_receive:products`



# Publish Product
Source: https://docs.whop.com/api-reference/beta/products/publish-product

/openapi/api-v1-native.json post /products/{id}/publish
Submits a product to the whop.com marketplace for review. The product moves to `pending_review`; a Whop reviewer approves it before it goes live.



# Retrieve Product
Source: https://docs.whop.com/api-reference/beta/products/retrieve-product

/openapi/api-v1-native.json get /products/{id}
Retrieves the details of an existing product. This endpoint is publicly accessible.



# Unpublish Product
Source: https://docs.whop.com/api-reference/beta/products/unpublish-product

/openapi/api-v1-native.json post /products/{id}/unpublish
Removes a product from the whop.com marketplace. The product moves to `not_available`.



# Update Product
Source: https://docs.whop.com/api-reference/beta/products/update-product

/openapi/api-v1-native.json patch /products/{id}
Updates an existing product.



# Activate Promo Code
Source: https://docs.whop.com/api-reference/beta/promo-codes/activate-promo-code

/openapi/api-v1-native.json post /promo_codes/{id}/activate
Turns an inactive promo code back on so it can be redeemed at checkout.



# Create Promo Code
Source: https://docs.whop.com/api-reference/beta/promo-codes/create-promo-code

/openapi/api-v1-native.json post /promo_codes
Creates a promo code for an account. First-party sessions may attach an affiliate.



# Deactivate Promo Code
Source: https://docs.whop.com/api-reference/beta/promo-codes/deactivate-promo-code

/openapi/api-v1-native.json post /promo_codes/{id}/deactivate
Turns off an active promo code so it can no longer be redeemed at checkout.



# Delete Promo Code
Source: https://docs.whop.com/api-reference/beta/promo-codes/delete-promo-code

/openapi/api-v1-native.json delete /promo_codes/{id}
Archives a promo code so it cannot be used in future checkouts.



# List Promo Codes
Source: https://docs.whop.com/api-reference/beta/promo-codes/list-promo-codes

/openapi/api-v1-native.json get /promo_codes
Lists promo codes for an account with cursor pagination, filters, and sorting.



# Retrieve Promo Code
Source: https://docs.whop.com/api-reference/beta/promo-codes/retrieve-promo-code

/openapi/api-v1-native.json get /promo_codes/{id}
Retrieves a promo code by ID.



# List Recommended Actions
Source: https://docs.whop.com/api-reference/beta/recommended-actions/list-recommended-actions

/openapi/api-v1-native.json get /recommended_actions
Lists the recommended action chains for an account — short sequences of actions (create a product, price it, publish it) the account should run next, gated on what it already has.



# Accept a Case
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/accept-a-case

/openapi/api-v1-native.json post /resolution_center_cases/{id}/accept
Accepts the case in the customer's favor, as the merchant: refunds the payment in full and closes the case.



# Appeal a Case
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/appeal-a-case

/openapi/api-v1-native.json post /resolution_center_cases/{id}/appeal
Appeals a decision, as the customer, on a case that closed in the merchant's favor. Escalates the case to Whop for platform review. A case can be appealed once.



# Deny a Case
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/deny-a-case

/openapi/api-v1-native.json post /resolution_center_cases/{id}/deny
Denies the case, as the merchant: rejects the claim and closes the case with no refund.



# List Resolution Center Case Events
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/list-resolution-center-case-events

/openapi/api-v1-native.json get /resolution_center_cases/{id}/events
Lists the case timeline, newest first. Events the viewer is not allowed to see are omitted — a customer reads the customer-visible timeline, the merchant reads the full one.



# Open a Case as the Customer
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/open-a-case-as-the-customer

/openapi/api-v1-native.json post /resolution_center_cases
Opens a case, as the customer, against one of your own payments. Provide the payment (`receipt_id`), the `reason`, and a `message`.



# Reply to a Case
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/reply-to-a-case

/openapi/api-v1-native.json post /resolution_center_cases/{id}/reply
Replies to an open request for information on the case. As the merchant this answers Whop's request (valid while the case awaits your information); as the customer it provides the information requested from you. The actor is resolved from the credential.



# Request Information from the Customer
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/request-information-from-the-customer

/openapi/api-v1-native.json post /resolution_center_cases/{id}/request_info
Asks the customer for more information, as the merchant. Allowed up to 3 times per case before you must accept or deny it.



# Resolutioncentercase created
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/resolutioncentercase-created

/openapi/api-v1-native.json webhook resolution_center_case.created
Sent when a resolution center case is created

Required permissions:
 - `payment:resolution_center_case:read`
 - `webhook_receive:resolutions`



# Resolutioncentercase decided
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/resolutioncentercase-decided

/openapi/api-v1-native.json webhook resolution_center_case.decided
Sent when a resolution center case is decided

Required permissions:
 - `payment:resolution_center_case:read`
 - `webhook_receive:resolutions`



# Resolutioncentercase updated
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/resolutioncentercase-updated

/openapi/api-v1-native.json webhook resolution_center_case.updated
Sent when a resolution center case is updated

Required permissions:
 - `payment:resolution_center_case:read`
 - `webhook_receive:resolutions`



# Retrieve Resolution Center Case
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/retrieve-resolution-center-case

/openapi/api-v1-native.json get /resolution_center_cases/{id}
Retrieves a single resolution center case with its full event timeline.



# Retrieve Resolution Center Case Summary
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/retrieve-resolution-center-case-summary

/openapi/api-v1-native.json get /resolution_center_cases/summary
Aggregates the same cases `GET /resolution_center_cases` lists, using the same filters. Use it to build status tabs and issue filters without paging the whole list.



# Withdraw a Case
Source: https://docs.whop.com/api-reference/beta/resolution-center-cases/withdraw-a-case

/openapi/api-v1-native.json post /resolution_center_cases/{id}/withdraw
Withdraws (cancels) a case you opened, as the customer. Only possible while the case is still open.



# Create Shipment
Source: https://docs.whop.com/api-reference/beta/shipments/create-shipment

/openapi/api-v1-native.json post /shipments
Attaches a carrier tracking number to a payment and begins tracking it.



# List Shipments
Source: https://docs.whop.com/api-reference/beta/shipments/list-shipments

/openapi/api-v1-native.json get /shipments
Returns a paginated list of shipments for an account.



# Retrieve Shipment
Source: https://docs.whop.com/api-reference/beta/shipments/retrieve-shipment

/openapi/api-v1-native.json get /shipments/{id}
Retrieves a shipment by its id, or by the payment id it fulfills.



# Shipment created
Source: https://docs.whop.com/api-reference/beta/shipments/shipment-created

/openapi/api-v1-native.json webhook shipment.created
Sent when a shipment is created

Required permissions:
 - `shipment:basic:read`
 - `payment:basic:read`
 - `webhook_receive:shipments`



# Shipment updated
Source: https://docs.whop.com/api-reference/beta/shipments/shipment-updated

/openapi/api-v1-native.json webhook shipment.updated
Sent when a shipment is updated

Required permissions:
 - `shipment:basic:read`
 - `payment:basic:read`
 - `webhook_receive:shipments`



# Update Shipment
Source: https://docs.whop.com/api-reference/beta/shipments/update-shipment

/openapi/api-v1-native.json patch /shipments/{id}
Updates a shipment's tracking number and re-tracks it with the carrier.



# Ad Campaign
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/ad-campaign



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.

## Endpoints

| Endpoint                                                                                                  | Request                                                |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [List Ad Campaigns](/api-reference/beta/ad-campaigns/list-ad-campaigns)                                   | <Badge>GET</Badge> `/ad_campaigns`                     |
| [Create an Ad Campaign](/api-reference/beta/ad-campaigns/create-an-ad-campaign)                           | <Badge>POST</Badge> `/ad_campaigns`                    |
| [Retrieve an Ad Campaign](/api-reference/beta/ad-campaigns/retrieve-an-ad-campaign)                       | <Badge>GET</Badge> `/ad_campaigns/{id}`                |
| [Update an Ad Campaign](/api-reference/beta/ad-campaigns/update-an-ad-campaign)                           | <Badge>PATCH</Badge> `/ad_campaigns/{id}`              |
| [Delete an Ad Campaign](/api-reference/beta/ad-campaigns/delete-an-ad-campaign)                           | <Badge>DELETE</Badge> `/ad_campaigns/{id}`             |
| [Duplicate an Ad Campaign](/api-reference/beta/ad-campaigns/duplicate-an-ad-campaign)                     | <Badge>POST</Badge> `/ad_campaigns/{id}/duplicate`     |
| [Pause an Ad Campaign](/api-reference/beta/ad-campaigns/pause-an-ad-campaign)                             | <Badge>POST</Badge> `/ad_campaigns/{id}/pause`         |
| [Retry a Failed Ad Campaign Payment](/api-reference/beta/ad-campaigns/retry-a-failed-ad-campaign-payment) | <Badge>POST</Badge> `/ad_campaigns/{id}/retry_payment` |
| [Unpause an Ad Campaign](/api-reference/beta/ad-campaigns/unpause-an-ad-campaign)                         | <Badge>POST</Badge> `/ad_campaigns/{id}/unpause`       |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Unique identifier for the ad campaign, prefixed `adcamp_`.
    </ResponseField>

    <ResponseField name="added_to_cart_value" type="number">
      USD value attributed to add-to-cart events. Sums the value sent with each
      event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="added_to_carts" type="number">
      Whop pixel-attributed add-to-cart events, last-click.
    </ResponseField>

    <ResponseField name="bid_type" type="string | null">
      How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, and `maximum_target` never bids above a cap.

      Available options: `minimum_cost`, `average_target`, `maximum_target`
    </ResponseField>

    <ResponseField name="budget_amount" type="number | null">
      The campaign's budget, in the ad account's currency. `null` when each ad group
      sets its own budget instead.
    </ResponseField>

    <ResponseField name="budget_optimization" type="string | null">
      Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`).

      Available options: `ad_campaign`, `ad_group`
    </ResponseField>

    <ResponseField name="budget_type" type="string | null">
      Whether `budget_amount` is spent per day (`daily`) or over the campaign's full run (`lifetime`).

      Available options: `daily`, `lifetime`
    </ResponseField>

    <ResponseField name="click_through_rate" type="number">
      Clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="clicks" type="number">
      The number of clicks.
    </ResponseField>

    <ResponseField name="completed_registration_value" type="number">
      USD value attributed to complete-registration events. Sums the value sent with
      each event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="completed_registrations" type="number">
      Whop pixel-attributed complete-registration events, last-click.
    </ResponseField>

    <ResponseField name="contact_value" type="number">
      USD value attributed to contact events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="contacts" type="number">
      Whop pixel-attributed contact events, last-click.
    </ResponseField>

    <ResponseField name="cost_per_added_to_cart" type="number | null">
      Spend divided by attributed add-to-cart events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_click" type="number">
      Spend divided by clicks; 0 when there are no clicks.
    </ResponseField>

    <ResponseField name="cost_per_completed_registration" type="number | null">
      Spend divided by attributed complete-registration events; null when they are
      not the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_contact" type="number | null">
      Spend divided by attributed contact events; null when contacts are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_lead" type="number | null">
      Spend divided by attributed leads; null when leads are not a goal and none are
      attributed.
    </ResponseField>

    <ResponseField name="cost_per_mille" type="number">
      Spend per 1,000 impressions; 0 when there are no impressions.
    </ResponseField>

    <ResponseField name="cost_per_purchase" type="number | null">
      Spend divided by attributed purchases; null when purchases are not a goal and
      none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_result" type="number | null">
      Spend divided by Whop pixel-attributed results; null when nothing
      Whop-attributable is being optimized for.
    </ResponseField>

    <ResponseField name="cost_per_schedule" type="number | null">
      Spend divided by attributed schedule events; null when schedules are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_submitted_application" type="number | null">
      Spend divided by attributed submit-application events; null when they are not
      the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_unique_click" type="number | null">
      Spend divided by unique clicks; null when there are no unique clicks.
    </ResponseField>

    <ResponseField name="cost_per_viewed_content" type="number | null">
      Spend divided by attributed view-content events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the campaign was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="custom_conversions" type="number">
      Whop pixel-attributed custom (merchant-defined) conversion events, last-click,
      across all custom event names.
    </ResponseField>

    <ResponseField name="custom_event_counts" type="object">
      Whop pixel-attributed custom conversions, keyed by your event name with its
      last-click count as the value. Empty when no named custom events are
      attributed. Custom events fired without a name are counted in
      custom\_conversions but omitted here, so these values sum to at most
      custom\_conversions.
    </ResponseField>

    <ResponseField name="custom_event_values" type="object">
      Conversion value attributed to each custom event, keyed by event name like
      custom\_event\_counts. Sums the value passed to whop.track, normalized to USD;
      events fired without a value contribute 0.
    </ResponseField>

    <ResponseField name="delivery_status" type="string">
      Whether the campaign's ads are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.

      Available options: `payment_failed`, `all_ads_rejected`, `draft`, `no_ad_groups`, `no_ads`, `paused`, `processing`, `issues`, `scheduled`, `completed`, `ad_groups_off`, `active`
    </ResponseField>

    <ResponseField name="frequency" type="number | null">
      Platform-reported impressions divided by reach.
    </ResponseField>

    <ResponseField name="impressions" type="number">
      The number of impressions.
    </ResponseField>

    <ResponseField name="issues" type="object[]">
      Open issues affecting the campaign and its descendant ad groups and ads.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Unique identifier for the issue.
        </ResponseField>

        <ResponseField name="message" type="string">
          A description of what the issue is and how it can be resolved.
        </ResponseField>

        <ResponseField name="resource_id" type="string | null">
          The ID of the campaign, ad group, or ad the issue is attached to.
        </ResponseField>

        <ResponseField name="resource_type" type="string">
          The type of resource the issue is attached to.

          Available options: `ad_campaign`, `ad_group`, `ad`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="lead_value" type="number">
      USD value attributed to lead events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="leads" type="number">
      Whop pixel-attributed leads, last-click.
    </ResponseField>

    <ResponseField name="objective" type="string | null">
      The goal the campaign optimizes toward.

      Available options: `awareness`, `traffic`, `engagement`, `leads`, `sales`
    </ResponseField>

    <ResponseField name="optimization_goal" type="string | null">
      The event the campaign optimizes for when a single goal is set campaign-wide.
      `null` when each ad group sets its own optimization\_goal.
    </ResponseField>

    <ResponseField name="platform" type="string">
      The ad network the campaign runs on.

      Available options: `meta`, `tiktok`
    </ResponseField>

    <ResponseField name="purchase_value" type="number">
      USD value of pixel-attributed purchases.
    </ResponseField>

    <ResponseField name="purchases" type="number">
      Whop pixel-attributed purchases, last-click.
    </ResponseField>

    <ResponseField name="reach" type="number">
      The number of unique people who saw this.
    </ResponseField>

    <ResponseField name="result_event" type="string | null">
      The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.

      Available options: `purchase`, `lead`, `schedule`, `submit_application`, `contact`, `complete_registration`, `view_content`, `add_to_cart`, `custom`
    </ResponseField>

    <ResponseField name="result_event_name" type="string | null">
      The merchant-defined event name when result\_event is custom; null for the
      standard events.
    </ResponseField>

    <ResponseField name="results" type="number | null">
      The Whop pixel-attributed count behind result\_event. When a campaign's ad
      groups optimize different goals there is no single result\_event (it is null),
      and this is instead the sum of each ad group's own attributed results. Null
      when nothing Whop-attributable is being optimized for.
    </ResponseField>

    <ResponseField name="return_on_ad_spend" type="number">
      Purchase value divided by spend, both in USD (a currency-neutral ratio); 0
      when there is no spend.
    </ResponseField>

    <ResponseField name="schedule_value" type="number">
      USD value attributed to schedule events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="schedules" type="number">
      Whop pixel-attributed schedule events, last-click.
    </ResponseField>

    <ResponseField name="special_ad_categories" type="string[]">
      Regulated categories the campaign is declared under. Ads in these categories are subject to extra targeting restrictions. Empty when none apply.

      Available options: `housing`, `employment`, `financial_products`, `politics`
    </ResponseField>

    <ResponseField name="spend" type="number">
      The amount charged, in spend\_currency.
    </ResponseField>

    <ResponseField name="spend_currency" type="string | null">
      The ISO 4217 currency code of all monetary metrics.
    </ResponseField>

    <ResponseField name="status" type="string">
      The lifecycle status of the ad campaign.

      Available options: `active`, `paused`, `inactive`, `stale`, `pending_refund`, `payment_failed`, `draft`, `in_review`, `flagged`, `importing`, `imported`, `duplicating`
    </ResponseField>

    <ResponseField name="submitted_application_value" type="number">
      USD value attributed to submit-application events. Sums the value sent with
      each event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="submitted_applications" type="number">
      Whop pixel-attributed submit-application events, last-click.
    </ResponseField>

    <ResponseField name="title" type="string">
      Display name of the ad campaign.
    </ResponseField>

    <ResponseField name="unique_click_through_rate" type="number | null">
      Unique clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="unique_clicks" type="number">
      People who clicked, reported by the Whop pixel, counted once per person.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the campaign was last updated, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="viewed_content_value" type="number">
      USD value attributed to view-content events. Sums the value sent with each
      event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="viewed_contents" type="number">
      Whop pixel-attributed view-content events, last-click.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json AdCampaign theme={null}
      {
      	"id": "adcamp_xxxxxxxxxx",
      	"added_to_cart_value": 2100,
      	"added_to_carts": 42,
      	"bid_type": "minimum_cost",
      	"budget_amount": 250,
      	"budget_optimization": "ad_campaign",
      	"budget_type": "daily",
      	"click_through_rate": 0.032,
      	"clicks": 1200,
      	"completed_registration_value": 0,
      	"completed_registrations": 28,
      	"contact_value": 0,
      	"contacts": 18,
      	"cost_per_added_to_cart": 17.86,
      	"cost_per_click": 0.63,
      	"cost_per_completed_registration": 26.79,
      	"cost_per_contact": 41.67,
      	"cost_per_lead": 30,
      	"cost_per_mille": 20,
      	"cost_per_purchase": 50,
      	"cost_per_result": 50,
      	"cost_per_schedule": null,
      	"cost_per_submitted_application": null,
      	"cost_per_unique_click": 0.74,
      	"cost_per_viewed_content": 1.25,
      	"created_at": "2026-06-01T12:00:00Z",
      	"custom_conversions": 10,
      	"custom_event_counts": {
      		"QualifiedCall": 7,
      		"BookedDemo": 3
      	},
      	"custom_event_values": {
      		"QualifiedCall": 3500,
      		"BookedDemo": 0
      	},
      	"delivery_status": "issues",
      	"frequency": 2.1,
      	"impressions": 37500,
      	"issues": [
      		{
      			"id": "adiss_xxxxxxxxxxx",
      			"message": "The ad's creative violates the ad network's policies. Edit the creative and resubmit for review.",
      			"resource_id": "adcamp_xxxxxxxxxx",
      			"resource_type": "ad_campaign"
      		}
      	],
      	"lead_value": 1250,
      	"leads": 25,
      	"objective": "sales",
      	"optimization_goal": "purchase",
      	"platform": "meta",
      	"purchase_value": 12600,
      	"purchases": 15,
      	"reach": 17800,
      	"result_event": "purchase",
      	"result_event_name": null,
      	"results": 15,
      	"return_on_ad_spend": 16.8,
      	"schedule_value": 0,
      	"schedules": 0,
      	"special_ad_categories": [],
      	"spend": 750,
      	"spend_currency": "usd",
      	"status": "active",
      	"submitted_application_value": 0,
      	"submitted_applications": 0,
      	"title": "Pickaxe Pro launch",
      	"unique_click_through_rate": 0.027,
      	"unique_clicks": 1010,
      	"updated_at": "2026-06-02T12:00:00Z",
      	"viewed_content_value": 0,
      	"viewed_contents": 600
      }
      ```
    </div>
  </Column>
</Columns>


# Create an Ad Campaign
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/create-an-ad-campaign

/openapi/api-v1-native.json post /ad_campaigns
Creates an ad campaign for an account.



# Delete an Ad Campaign
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/delete-an-ad-campaign

/openapi/api-v1-native.json delete /ad_campaigns/{id}
Deletes an ad campaign and archives it on the ad platform (cascades to ad groups and ads).



# Duplicate an Ad Campaign
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/duplicate-an-ad-campaign

/openapi/api-v1-native.json post /ad_campaigns/{id}/duplicate
Creates copies of the campaign in `duplicating` status and returns them; each copy transitions to `draft` once duplication completes. Poll each returned campaign until it leaves `duplicating` — a copy that could not be completed is deleted and returns 404.



# List Ad Campaigns
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/list-ad-campaigns

/openapi/api-v1-native.json get /ad_campaigns
Lists the ad campaigns for an account, with stats over the requested window.



# Pause an Ad Campaign
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/pause-an-ad-campaign

/openapi/api-v1-native.json post /ad_campaigns/{id}/pause
Pauses an active ad campaign.



# Retrieve an Ad Campaign
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/retrieve-an-ad-campaign

/openapi/api-v1-native.json get /ad_campaigns/{id}
Retrieves a single ad campaign with stats over the requested window.



# Retry a Failed Ad Campaign Payment
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/retry-a-failed-ad-campaign-payment

/openapi/api-v1-native.json post /ad_campaigns/{id}/retry_payment
Retries billing for an ad campaign whose payment previously failed.



# Unpause an Ad Campaign
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/unpause-an-ad-campaign

/openapi/api-v1-native.json post /ad_campaigns/{id}/unpause
Resumes a paused ad campaign.



# Update an Ad Campaign
Source: https://docs.whop.com/api-reference/beta/ad-campaigns/update-an-ad-campaign

/openapi/api-v1-native.json patch /ad_campaigns/{id}
Updates an ad campaign's editable fields (title, budget, schedule, bid strategy, special ad categories, and, before launch, budget optimization), and launches a draft campaign by setting status to active. Objective, budget type and desired cost per result are fixed at creation and cannot be changed.



# Ad Group
Source: https://docs.whop.com/api-reference/beta/ad-groups/ad-group



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.

## Endpoints

| Endpoint                                                                           | Request                                           |
| ---------------------------------------------------------------------------------- | ------------------------------------------------- |
| [List Ad Groups](/api-reference/beta/ad-groups/list-ad-groups)                     | <Badge>GET</Badge> `/ad_groups`                   |
| [Create an Ad Group](/api-reference/beta/ad-groups/create-an-ad-group)             | <Badge>POST</Badge> `/ad_groups`                  |
| [Retrieve an Ad Group](/api-reference/beta/ad-groups/retrieve-an-ad-group)         | <Badge>GET</Badge> `/ad_groups/{id}`              |
| [Update an Ad Group](/api-reference/beta/ad-groups/update-an-ad-group)             | <Badge>PATCH</Badge> `/ad_groups/{id}`            |
| [Delete an Ad Group](/api-reference/beta/ad-groups/delete-an-ad-group)             | <Badge>DELETE</Badge> `/ad_groups/{id}`           |
| [Duplicate an Ad Group](/api-reference/beta/ad-groups/duplicate-an-ad-group)       | <Badge>POST</Badge> `/ad_groups/{id}/duplicate`   |
| [Pause an Ad Group](/api-reference/beta/ad-groups/pause-an-ad-group)               | <Badge>POST</Badge> `/ad_groups/{id}/pause`       |
| [Unpause an Ad Group](/api-reference/beta/ad-groups/unpause-an-ad-group)           | <Badge>POST</Badge> `/ad_groups/{id}/unpause`     |
| [Estimate Ad Group Reach](/api-reference/beta/ad-groups/estimate-ad-group-reach)   | <Badge>POST</Badge> `/ad_groups/estimate_reach`   |
| [Search Targeting Options](/api-reference/beta/ad-groups/search-targeting-options) | <Badge>GET</Badge> `/ad_groups/targeting_options` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Unique identifier for the ad group, prefixed `adgrp_`.
    </ResponseField>

    <ResponseField name="ad_campaign" type="object">
      The ad campaign this ad group belongs to.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          The referenced entity's id.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="added_to_cart_value" type="number">
      USD value attributed to add-to-cart events. Sums the value sent with each
      event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="added_to_carts" type="number">
      Whop pixel-attributed add-to-cart events, last-click.
    </ResponseField>

    <ResponseField name="audiences" type="object">
      Saved audiences this ad group delivers to or excludes.

      <Accordion title="Properties">
        <ResponseField name="exclude" type="string[]">
          IDs of saved audiences excluded from delivery, prefixed `adaud_`.
        </ResponseField>

        <ResponseField name="include" type="string[]">
          IDs of saved audiences the ad group delivers to, prefixed `adaud_`.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="bid_type" type="string | null">
      How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`.

      Available options: `minimum_cost`, `average_target`, `maximum_target`
    </ResponseField>

    <ResponseField name="budget_amount" type="number | null">
      This ad group's budget, in the ad account's currency. `null` when the budget
      is set on the campaign instead.
    </ResponseField>

    <ResponseField name="budget_type" type="string | null">
      Whether `budget_amount` is spent per day (`daily`) or over the ad group's full run (`lifetime`).

      Available options: `daily`, `lifetime`
    </ResponseField>

    <ResponseField name="click_through_rate" type="number">
      Clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="clicks" type="number">
      The number of clicks.
    </ResponseField>

    <ResponseField name="completed_registration_value" type="number">
      USD value attributed to complete-registration events. Sums the value sent with
      each event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="completed_registrations" type="number">
      Whop pixel-attributed complete-registration events, last-click.
    </ResponseField>

    <ResponseField name="contact_value" type="number">
      USD value attributed to contact events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="contacts" type="number">
      Whop pixel-attributed contact events, last-click.
    </ResponseField>

    <ResponseField name="conversion_event" type="string | null">
      The pixel event optimized for. A standard event, or any custom pixel event
      name.
    </ResponseField>

    <ResponseField name="conversion_location" type="string | null">
      Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission.

      Available options: `website`, `profile`, `instagram_and_facebook`, `instagram_profile`, `messaging`, `on_ad`, `instant_forms`, `instant_forms_and_messenger`, `website_and_instant_forms`
    </ResponseField>

    <ResponseField name="cost_per_added_to_cart" type="number | null">
      Spend divided by attributed add-to-cart events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_click" type="number">
      Spend divided by clicks; 0 when there are no clicks.
    </ResponseField>

    <ResponseField name="cost_per_completed_registration" type="number | null">
      Spend divided by attributed complete-registration events; null when they are
      not the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_contact" type="number | null">
      Spend divided by attributed contact events; null when contacts are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_lead" type="number | null">
      Spend divided by attributed leads; null when leads are not a goal and none are
      attributed.
    </ResponseField>

    <ResponseField name="cost_per_mille" type="number">
      Spend per 1,000 impressions; 0 when there are no impressions.
    </ResponseField>

    <ResponseField name="cost_per_purchase" type="number | null">
      Spend divided by attributed purchases; null when purchases are not a goal and
      none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_result" type="number | null">
      Spend divided by Whop pixel-attributed results; null when nothing
      Whop-attributable is being optimized for.
    </ResponseField>

    <ResponseField name="cost_per_schedule" type="number | null">
      Spend divided by attributed schedule events; null when schedules are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_submitted_application" type="number | null">
      Spend divided by attributed submit-application events; null when they are not
      the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_unique_click" type="number | null">
      Spend divided by unique clicks; null when there are no unique clicks.
    </ResponseField>

    <ResponseField name="cost_per_viewed_content" type="number | null">
      Spend divided by attributed view-content events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the ad group was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="custom_conversions" type="number">
      Whop pixel-attributed custom (merchant-defined) conversion events, last-click,
      across all custom event names.
    </ResponseField>

    <ResponseField name="custom_event_counts" type="object">
      Whop pixel-attributed custom conversions, keyed by your event name with its
      last-click count as the value. Empty when no named custom events are
      attributed. Custom events fired without a name are counted in
      custom\_conversions but omitted here, so these values sum to at most
      custom\_conversions.
    </ResponseField>

    <ResponseField name="custom_event_values" type="object">
      Conversion value attributed to each custom event, keyed by event name like
      custom\_event\_counts. Sums the value passed to whop.track, normalized to USD;
      events fired without a value contribute 0.
    </ResponseField>

    <ResponseField name="delivery_status" type="string">
      Whether ads in this ad group are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.

      Available options: `all_ads_rejected`, `rejected`, `draft`, `no_ads`, `campaign_paused`, `paused`, `processing`, `issues`, `scheduled`, `completed`, `ads_off`, `learning_limited`, `learning`, `active`
    </ResponseField>

    <ResponseField name="demographics" type="object">
      Age, gender, and automatic-audience targeting.

      <Accordion title="Properties">
        <ResponseField name="automatic" type="boolean">
          Whether automatic audience targeting is on (Advantage+ on Meta). When `true`,
          the platform can deliver beyond the ages, genders, and detailed targeting you
          set, treating them as suggestions.
        </ResponseField>

        <ResponseField name="gender" type="string">
          Gender targeted.

          Available options: `all`, `male`, `female`
        </ResponseField>

        <ResponseField name="maximum_age" type="number | null">
          Oldest age targeted. `null` when no maximum is set.
        </ResponseField>

        <ResponseField name="minimum_age" type="number | null">
          Youngest age targeted. `null` when no minimum is set.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="desired_cost_per_result" type="number | null">
      Cost per result to aim for (`average_target`) or never exceed
      (`maximum_target`). `null` for `minimum_cost` bidding.
    </ResponseField>

    <ResponseField name="detailed_targeting" type="object">
      Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Can't be combined with automatic audience targeting, and unavailable to campaigns with special\_ad\_categories.

      <Accordion title="Properties">
        <ResponseField name="behaviors" type="object[]">
          Behavior categories targeted, such as frequent travelers.

          <Accordion title="Properties">
            <ResponseField name="id" type="string">
              The ad platform's ID for the category in its targeting taxonomy.
            </ResponseField>

            <ResponseField name="name" type="string">
              Category name, such as `Movies`.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="demographics" type="object[]">
          Demographic categories targeted, such as life events or industries.

          <Accordion title="Properties">
            <ResponseField name="id" type="string">
              The ad platform's ID for the category in its targeting taxonomy.
            </ResponseField>

            <ResponseField name="name" type="string">
              Category name, such as `Recently moved`.
            </ResponseField>

            <ResponseField name="type" type="string">
              Kind of demographic the category belongs to.

              Available options: `life_events`, `industries`, `income`, `family_statuses`
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="interests" type="object[]">
          Interest categories targeted, such as an interest in movies.

          <Accordion title="Properties">
            <ResponseField name="id" type="string">
              The ad platform's ID for the category in its targeting taxonomy.
            </ResponseField>

            <ResponseField name="name" type="string">
              Category name, such as `Movies`.
            </ResponseField>
          </Accordion>
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="devices" type="object">
      Device platforms and operating systems targeted.

      <Accordion title="Properties">
        <ResponseField name="operating_systems" type="object[]">
          Operating systems targeted. Empty targets all operating systems.

          <Accordion title="Properties">
            <ResponseField name="minimum_version" type="string">
              Lowest OS version targeted, such as `18.0`. Absent when any version qualifies.
            </ResponseField>

            <ResponseField name="os" type="string">
              Operating system targeted.

              Available options: `ios`, `android`
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="platforms" type="string[]">
          Device types targeted. Empty targets all devices.

          Available options: `mobile`, `desktop`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="dynamic_creative" type="boolean">
      Whether the ad platform automatically mixes and matches this ad group's
      creatives and copy to find the best-performing combinations.
    </ResponseField>

    <ResponseField name="ends_at" type="string | null">
      When the ad group stops delivering, as an ISO 8601 timestamp. `null` when it
      runs until paused.
    </ResponseField>

    <ResponseField name="frequency" type="number | null">
      Platform-reported impressions divided by reach.
    </ResponseField>

    <ResponseField name="frequency_cap" type="object | null">
      Cap on how often one person sees ads from this ad group. Only available on campaigns with the `awareness` objective; `null` when uncapped.

      <Accordion title="Properties">
        <ResponseField name="maximum_impressions" type="number">
          Most times one person can be shown ads from this ad group within the window.
        </ResponseField>

        <ResponseField name="per_days" type="number | null">
          Length of the rolling window, in days.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="impressions" type="number">
      The number of impressions.
    </ResponseField>

    <ResponseField name="issues" type="object[]">
      Open issues affecting this ad group and its ads. Empty when there are none.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Unique identifier for the issue.
        </ResponseField>

        <ResponseField name="message" type="string">
          A description of what the issue is and how it can be resolved.
        </ResponseField>

        <ResponseField name="resource_id" type="string | null">
          The ID of the campaign, ad group, or ad the issue is attached to.
        </ResponseField>

        <ResponseField name="resource_type" type="string">
          The type of resource the issue is attached to.

          Available options: `ad_campaign`, `ad_group`, `ad`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="languages" type="string[]">
      Languages targeted, as ISO 639 codes such as `en` or `es`. A region-specific
      locale with no ISO code appears as its numeric platform locale key. Empty
      targets all languages.
    </ResponseField>

    <ResponseField name="lead_value" type="number">
      USD value attributed to lead events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="leads" type="number">
      Whop pixel-attributed leads, last-click.
    </ResponseField>

    <ResponseField name="message_apps" type="string[]">
      Apps the conversation opens in when `conversion_location` is `messaging`. Empty for other conversion locations.

      Available options: `messenger`, `instagram`, `whatsapp`
    </ResponseField>

    <ResponseField name="minimum_daily_spend" type="number | null">
      Minimum the ad group tries to spend each day. `null` when no floor is set.
    </ResponseField>

    <ResponseField name="optimization_goal" type="string | null">
      The result the ad group's delivery is optimized to get the most of.

      Available options: `conversions`, `link_clicks`, `landing_page_views`, `reach`, `impressions`, `engagement`, `conversations`, `video_views`, `two_second_views`, `page_likes`, `social_profile`, `ad_recall_lift`, `event_responses`, `reminders_set`, `lead_generation`, `quality_lead`, `value`, `profile_and_page_engagement`
    </ResponseField>

    <ResponseField name="placements" type="object[]">
      Where ads can appear, per platform. Empty when placements are chosen automatically.

      <Accordion title="Properties">
        <ResponseField name="platform" type="string">
          Publisher platform where the ad is eligible to appear.

          Available options: `facebook`, `instagram`, `messenger`, `audience_network`, `threads`, `whatsapp`
        </ResponseField>

        <ResponseField name="positions" type="string[]">
          Positions targeted within the platform, such as `feed` or `story`. Empty targets all of the platform's positions.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="purchase_value" type="number">
      USD value of pixel-attributed purchases.
    </ResponseField>

    <ResponseField name="purchases" type="number">
      Whop pixel-attributed purchases, last-click.
    </ResponseField>

    <ResponseField name="reach" type="number">
      The number of unique people who saw this.
    </ResponseField>

    <ResponseField name="regions" type="object">
      Locations targeted and excluded.

      <Accordion title="Properties">
        <ResponseField name="exclude" type="object">
          Locations excluded from targeting. Country groups can't be excluded.

          <Accordion title="Properties">
            <ResponseField name="cities" type="object[]">
              Cities, keyed by the ad platform's location taxonomy.

              <Accordion title="Properties">
                <ResponseField name="key" type="string">
                  The ad platform's key for the city in its location taxonomy.
                </ResponseField>

                <ResponseField name="name" type="string">
                  City name, such as `Austin`. Absent when the platform doesn't return one.
                </ResponseField>
              </Accordion>
            </ResponseField>

            <ResponseField name="countries" type="string[]">
              Countries, as ISO 3166-1 alpha-2 codes such as `US`.
            </ResponseField>

            <ResponseField name="country_groups" type="string[]">
              Multi-country groups such as `worldwide` or `europe`.
            </ResponseField>

            <ResponseField name="custom_locations" type="object[]">
              Circular areas, each a coordinate plus a radius.

              <Accordion title="Properties">
                <ResponseField name="distance_unit" type="string">
                  Unit for `radius`.

                  Available options: `mile`, `kilometer`
                </ResponseField>

                <ResponseField name="latitude" type="number">
                  Latitude of the center point.
                </ResponseField>

                <ResponseField name="longitude" type="number">
                  Longitude of the center point.
                </ResponseField>

                <ResponseField name="name" type="string">
                  Label for the location, such as a city or address. Absent when the location
                  has no label.
                </ResponseField>

                <ResponseField name="radius" type="number">
                  Radius around the center point, in `distance_unit`.
                </ResponseField>
              </Accordion>
            </ResponseField>

            <ResponseField name="regions" type="string[]">
              US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`,
              `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through
              `countries`.
            </ResponseField>

            <ResponseField name="zips" type="string[]">
              ZIP and postal codes.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="include" type="object">
          Locations the ad group targets.

          <Accordion title="Properties">
            <ResponseField name="cities" type="object[]">
              Cities, keyed by the ad platform's location taxonomy.

              <Accordion title="Properties">
                <ResponseField name="key" type="string">
                  The ad platform's key for the city in its location taxonomy.
                </ResponseField>

                <ResponseField name="name" type="string">
                  City name, such as `Austin`. Absent when the platform doesn't return one.
                </ResponseField>
              </Accordion>
            </ResponseField>

            <ResponseField name="countries" type="string[]">
              Countries, as ISO 3166-1 alpha-2 codes such as `US`.
            </ResponseField>

            <ResponseField name="country_groups" type="string[]">
              Multi-country groups such as `worldwide` or `europe`.
            </ResponseField>

            <ResponseField name="custom_locations" type="object[]">
              Circular areas, each a coordinate plus a radius.

              <Accordion title="Properties">
                <ResponseField name="distance_unit" type="string">
                  Unit for `radius`.

                  Available options: `mile`, `kilometer`
                </ResponseField>

                <ResponseField name="latitude" type="number">
                  Latitude of the center point.
                </ResponseField>

                <ResponseField name="longitude" type="number">
                  Longitude of the center point.
                </ResponseField>

                <ResponseField name="name" type="string">
                  Label for the location, such as a city or address. Absent when the location
                  has no label.
                </ResponseField>

                <ResponseField name="radius" type="number">
                  Radius around the center point, in `distance_unit`.
                </ResponseField>
              </Accordion>
            </ResponseField>

            <ResponseField name="regions" type="string[]">
              US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`,
              `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through
              `countries`.
            </ResponseField>

            <ResponseField name="zips" type="string[]">
              ZIP and postal codes.
            </ResponseField>
          </Accordion>
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="result_event" type="string | null">
      The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.

      Available options: `purchase`, `lead`, `schedule`, `submit_application`, `contact`, `complete_registration`, `view_content`, `add_to_cart`, `custom`
    </ResponseField>

    <ResponseField name="result_event_name" type="string | null">
      The merchant-defined event name when result\_event is custom; null for the
      standard events.
    </ResponseField>

    <ResponseField name="results" type="number | null">
      The Whop pixel-attributed count behind result\_event. When a campaign's ad
      groups optimize different goals there is no single result\_event (it is null),
      and this is instead the sum of each ad group's own attributed results. Null
      when nothing Whop-attributable is being optimized for.
    </ResponseField>

    <ResponseField name="return_on_ad_spend" type="number">
      Purchase value divided by spend, both in USD (a currency-neutral ratio); 0
      when there is no spend.
    </ResponseField>

    <ResponseField name="schedule_value" type="number">
      USD value attributed to schedule events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="schedules" type="number">
      Whop pixel-attributed schedule events, last-click.
    </ResponseField>

    <ResponseField name="spend" type="number">
      The amount charged, in spend\_currency.
    </ResponseField>

    <ResponseField name="spend_currency" type="string | null">
      The ISO 4217 currency code of all monetary metrics.
    </ResponseField>

    <ResponseField name="starts_at" type="string | null">
      When the ad group starts delivering, as an ISO 8601 timestamp. `null` when it
      starts as soon as it's active.
    </ResponseField>

    <ResponseField name="status" type="string">
      Whether the ad group is enabled. `active` and `paused` are set by you; `rejected` means it failed ad review; `duplicating` is a copy still being filled in.

      Available options: `active`, `paused`, `rejected`, `duplicating`
    </ResponseField>

    <ResponseField name="submitted_application_value" type="number">
      USD value attributed to submit-application events. Sums the value sent with
      each event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="submitted_applications" type="number">
      Whop pixel-attributed submit-application events, last-click.
    </ResponseField>

    <ResponseField name="title" type="string | null">
      Display name of the ad group.
    </ResponseField>

    <ResponseField name="unique_click_through_rate" type="number | null">
      Unique clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="unique_clicks" type="number">
      People who clicked, reported by the Whop pixel, counted once per person.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the ad group was last updated, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="viewed_content_value" type="number">
      USD value attributed to view-content events. Sums the value sent with each
      event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="viewed_contents" type="number">
      Whop pixel-attributed view-content events, last-click.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json AdGroup theme={null}
      {
      	"id": "adgrp_xxxxxxxxxxx",
      	"ad_campaign": {
      		"id": "adcamp_xxxxxxxxxx"
      	},
      	"added_to_cart_value": 1050,
      	"added_to_carts": 24,
      	"audiences": {
      		"exclude": [],
      		"include": ["adaud_xxxxxxxxxxx"]
      	},
      	"bid_type": "minimum_cost",
      	"budget_amount": 100,
      	"budget_type": "daily",
      	"click_through_rate": 0.036,
      	"clicks": 720,
      	"completed_registration_value": 0,
      	"completed_registrations": 16,
      	"contact_value": 0,
      	"contacts": 10,
      	"conversion_event": "purchase",
      	"conversion_location": "website",
      	"cost_per_added_to_cart": 8.33,
      	"cost_per_click": 0.28,
      	"cost_per_completed_registration": 12.5,
      	"cost_per_contact": 20,
      	"cost_per_lead": 13.33,
      	"cost_per_mille": 10,
      	"cost_per_purchase": 25,
      	"cost_per_result": 25,
      	"cost_per_schedule": null,
      	"cost_per_submitted_application": null,
      	"cost_per_unique_click": 0.33,
      	"cost_per_viewed_content": 0.67,
      	"created_at": "2026-06-01T12:00:00Z",
      	"custom_conversions": 5,
      	"custom_event_counts": {
      		"QualifiedCall": 4,
      		"BookedDemo": 1
      	},
      	"custom_event_values": {
      		"QualifiedCall": 2000,
      		"BookedDemo": 0
      	},
      	"delivery_status": "issues",
      	"demographics": {
      		"automatic": false,
      		"minimum_age": 21,
      		"maximum_age": 45,
      		"gender": "all"
      	},
      	"desired_cost_per_result": 30,
      	"detailed_targeting": {
      		"interests": [
      			{
      				"id": "6003139266461",
      				"name": "Movies"
      			}
      		],
      		"behaviors": [
      			{
      				"id": "6002714895372",
      				"name": "Frequent travelers"
      			}
      		],
      		"demographics": [
      			{
      				"id": "6015559470583",
      				"name": "Recently moved",
      				"type": "life_events"
      			}
      		]
      	},
      	"devices": {
      		"platforms": ["mobile", "desktop"],
      		"operating_systems": [
      			{
      				"os": "ios",
      				"minimum_version": "18.0"
      			}
      		]
      	},
      	"dynamic_creative": false,
      	"ends_at": "2026-07-01T12:00:00Z",
      	"frequency": 1.6,
      	"frequency_cap": null,
      	"impressions": 20000,
      	"issues": [
      		{
      			"id": "adiss_xxxxxxxxxxx",
      			"message": "The audience is too narrow to deliver. Broaden the targeting to reach more people.",
      			"resource_id": "adgrp_xxxxxxxxxxx",
      			"resource_type": "ad_group"
      		}
      	],
      	"languages": ["en"],
      	"lead_value": 750,
      	"leads": 15,
      	"message_apps": [],
      	"minimum_daily_spend": 25,
      	"optimization_goal": "conversions",
      	"placements": [
      		{
      			"platform": "instagram",
      			"positions": ["stream", "story"]
      		}
      	],
      	"purchase_value": 5200,
      	"purchases": 8,
      	"reach": 12500,
      	"regions": {
      		"include": {
      			"countries": ["US"],
      			"country_groups": [],
      			"regions": ["US-CA"],
      			"cities": [
      				{
      					"key": "2418779",
      					"name": "Miami"
      				}
      			],
      			"zips": [],
      			"custom_locations": [
      				{
      					"latitude": 30.2672,
      					"longitude": -97.7431,
      					"radius": 10,
      					"distance_unit": "mile",
      					"name": "Austin, TX"
      				}
      			]
      		},
      		"exclude": {
      			"countries": [],
      			"country_groups": [],
      			"regions": [],
      			"cities": [
      				{
      					"key": "2421215",
      					"name": "Anchorage"
      				}
      			],
      			"zips": [],
      			"custom_locations": [
      				{
      					"latitude": 40.758,
      					"longitude": -73.9855,
      					"radius": 2,
      					"distance_unit": "mile",
      					"name": "Times Square"
      				}
      			]
      		}
      	},
      	"result_event": "purchase",
      	"result_event_name": null,
      	"results": 8,
      	"return_on_ad_spend": 26,
      	"schedule_value": 0,
      	"schedules": 0,
      	"spend": 200,
      	"spend_currency": "usd",
      	"starts_at": "2026-06-01T12:00:00Z",
      	"status": "active",
      	"submitted_application_value": 0,
      	"submitted_applications": 0,
      	"title": "US founders",
      	"unique_click_through_rate": 0.03,
      	"unique_clicks": 600,
      	"updated_at": "2026-06-02T12:00:00Z",
      	"viewed_content_value": 0,
      	"viewed_contents": 300
      }
      ```
    </div>
  </Column>
</Columns>


# Create an Ad Group
Source: https://docs.whop.com/api-reference/beta/ad-groups/create-an-ad-group

/openapi/api-v1-native.json post /ad_groups
Creates an ad group (ad set) in a campaign.



# Delete an Ad Group
Source: https://docs.whop.com/api-reference/beta/ad-groups/delete-an-ad-group

/openapi/api-v1-native.json delete /ad_groups/{id}
Deletes an ad group.



# Duplicate an Ad Group
Source: https://docs.whop.com/api-reference/beta/ad-groups/duplicate-an-ad-group

/openapi/api-v1-native.json post /ad_groups/{id}/duplicate
Creates copies of the ad group in `duplicating` status and returns them — into its own campaign, or into target_ad_campaign_id (which must belong to the same account and be compatible with the ad group's targeting and goals); each copy transitions to its final status (matching the source's active/paused state) once duplication completes. Poll each returned ad group until it leaves `duplicating` — a copy that could not be completed is deleted and returns 404.



# Estimate Ad Group Reach
Source: https://docs.whop.com/api-reference/beta/ad-groups/estimate-ad-group-reach

/openapi/api-v1-native.json post /ad_groups/estimate_reach
Estimates how many people a draft targeting spec can reach, before an ad group is created. The body takes the same targeting fields as creating an ad group — `regions`, `demographics`, `detailed_targeting`, `audiences`, `languages`, and `devices` — and nothing is persisted.



# List Ad Groups
Source: https://docs.whop.com/api-reference/beta/ad-groups/list-ad-groups

/openapi/api-v1-native.json get /ad_groups
Lists ad groups for the account, newest first.



# Pause an Ad Group
Source: https://docs.whop.com/api-reference/beta/ad-groups/pause-an-ad-group

/openapi/api-v1-native.json post /ad_groups/{id}/pause
Pauses delivery of an ad group.



# Retrieve an Ad Group
Source: https://docs.whop.com/api-reference/beta/ad-groups/retrieve-an-ad-group

/openapi/api-v1-native.json get /ad_groups/{id}
Retrieves a single ad group.



# Search Targeting Options
Source: https://docs.whop.com/api-reference/beta/ad-groups/search-targeting-options

/openapi/api-v1-native.json get /ad_groups/targeting_options
Searches the ad platform's targeting taxonomy for options to target an ad group with. Each result comes back in the exact shape the ad-group body accepts for its `type`, so it can be used in `detailed_targeting`, `regions`, or `languages` as-is. A blank `query` browses the small fixed lists (behaviors, demographic categories, languages); interests and locations need a search term.



# Unpause an Ad Group
Source: https://docs.whop.com/api-reference/beta/ad-groups/unpause-an-ad-group

/openapi/api-v1-native.json post /ad_groups/{id}/unpause
Resumes delivery of a paused ad group.



# Update an Ad Group
Source: https://docs.whop.com/api-reference/beta/ad-groups/update-an-ad-group

/openapi/api-v1-native.json patch /ad_groups/{id}
Updates an ad group's editable fields. Only the keys you send are changed.



# Ad
Source: https://docs.whop.com/api-reference/beta/ads/ad



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.

## Endpoints

| Endpoint                                                   | Request                                   |
| ---------------------------------------------------------- | ----------------------------------------- |
| [List Ads](/api-reference/beta/ads/list-ads)               | <Badge>GET</Badge> `/ads`                 |
| [Create an Ad](/api-reference/beta/ads/create-an-ad)       | <Badge>POST</Badge> `/ads`                |
| [Retrieve an Ad](/api-reference/beta/ads/retrieve-an-ad)   | <Badge>GET</Badge> `/ads/{id}`            |
| [Update an Ad](/api-reference/beta/ads/update-an-ad)       | <Badge>PATCH</Badge> `/ads/{id}`          |
| [Delete an Ad](/api-reference/beta/ads/delete-an-ad)       | <Badge>DELETE</Badge> `/ads/{id}`         |
| [Duplicate an Ad](/api-reference/beta/ads/duplicate-an-ad) | <Badge>POST</Badge> `/ads/{id}/duplicate` |
| [Pause an Ad](/api-reference/beta/ads/pause-an-ad)         | <Badge>POST</Badge> `/ads/{id}/pause`     |
| [Unpause an Ad](/api-reference/beta/ads/unpause-an-ad)     | <Badge>POST</Badge> `/ads/{id}/unpause`   |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Unique identifier for the ad, prefixed `ad_`.
    </ResponseField>

    <ResponseField name="ad_campaign" type="object">
      The ad campaign this ad belongs to.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          The referenced entity's id.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="ad_group" type="object">
      The ad group this ad belongs to.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          The referenced entity's id.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="added_to_cart_value" type="number">
      USD value attributed to add-to-cart events. Sums the value sent with each
      event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="added_to_carts" type="number">
      Whop pixel-attributed add-to-cart events, last-click.
    </ResponseField>

    <ResponseField name="call_to_action" type="string | null">
      The call-to-action button shown on the ad.

      Available options: `learn_more`, `shop_now`, `sign_up`, `subscribe`, `get_started`, `book_now`, `apply_now`, `contact_us`, `download`, `order_now`, `buy_now`, `get_quote`, `message_page`, `whatsapp_message`, `instagram_message`, `call_now`, `get_directions`, `send_updates`, `get_offer`, `watch_more`, `listen_now`, `play_game`, `open_link`, `no_button`, `get_offer_view`, `get_event_tickets`, `see_menu`, `request_time`, `event_rsvp`, `see_details`, `view_instagram_profile`
    </ResponseField>

    <ResponseField name="click_through_rate" type="number">
      Clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="clicks" type="number">
      The number of clicks.
    </ResponseField>

    <ResponseField name="completed_registration_value" type="number">
      USD value attributed to complete-registration events. Sums the value sent with
      each event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="completed_registrations" type="number">
      Whop pixel-attributed complete-registration events, last-click.
    </ResponseField>

    <ResponseField name="contact_value" type="number">
      USD value attributed to contact events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="contacts" type="number">
      Whop pixel-attributed contact events, last-click.
    </ResponseField>

    <ResponseField name="cost_per_added_to_cart" type="number | null">
      Spend divided by attributed add-to-cart events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_click" type="number">
      Spend divided by clicks; 0 when there are no clicks.
    </ResponseField>

    <ResponseField name="cost_per_completed_registration" type="number | null">
      Spend divided by attributed complete-registration events; null when they are
      not the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_contact" type="number | null">
      Spend divided by attributed contact events; null when contacts are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_lead" type="number | null">
      Spend divided by attributed leads; null when leads are not a goal and none are
      attributed.
    </ResponseField>

    <ResponseField name="cost_per_mille" type="number">
      Spend per 1,000 impressions; 0 when there are no impressions.
    </ResponseField>

    <ResponseField name="cost_per_purchase" type="number | null">
      Spend divided by attributed purchases; null when purchases are not a goal and
      none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_result" type="number | null">
      Spend divided by Whop pixel-attributed results; null when nothing
      Whop-attributable is being optimized for.
    </ResponseField>

    <ResponseField name="cost_per_schedule" type="number | null">
      Spend divided by attributed schedule events; null when schedules are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_submitted_application" type="number | null">
      Spend divided by attributed submit-application events; null when they are not
      the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_unique_click" type="number | null">
      Spend divided by unique clicks; null when there are no unique clicks.
    </ResponseField>

    <ResponseField name="cost_per_viewed_content" type="number | null">
      Spend divided by attributed view-content events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the ad was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="creatives" type="object[]">
      The creative assets used by this ad. The original asset has a null format; square, vertical, and horizontal entries are placement-specific variants. A carousel ad returns one format-null entry per attachment, in order.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          The creative attachment's file id.
        </ResponseField>

        <ResponseField name="crop" type="object | null">
          The saved crop window for this creative, in source image pixels. Null for the original asset or a format that has not been cropped.

          <Accordion title="Properties">
            <ResponseField name="height" type="number">
              Height of the crop window in source pixels.
            </ResponseField>

            <ResponseField name="width" type="number">
              Width of the crop window in source pixels.
            </ResponseField>

            <ResponseField name="x" type="number">
              Left edge of the crop window in source pixels.
            </ResponseField>

            <ResponseField name="y" type="number">
              Top edge of the crop window in source pixels.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="format" type="string | null">
          The placement variant this asset covers, or null for the original asset.

          Available options: `square`, `vertical`, `horizontal`
        </ResponseField>

        <ResponseField name="media_type" type="string | null">
          The kind of asset, image or video.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          CDN url of the asset.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="custom_conversions" type="number">
      Whop pixel-attributed custom (merchant-defined) conversion events, last-click,
      across all custom event names.
    </ResponseField>

    <ResponseField name="custom_event_counts" type="object">
      Whop pixel-attributed custom conversions, keyed by your event name with its
      last-click count as the value. Empty when no named custom events are
      attributed. Custom events fired without a name are counted in
      custom\_conversions but omitted here, so these values sum to at most
      custom\_conversions.
    </ResponseField>

    <ResponseField name="custom_event_values" type="object">
      Conversion value attributed to each custom event, keyed by event name like
      custom\_event\_counts. Sums the value passed to whop.track, normalized to USD;
      events fired without a value contribute 0.
    </ResponseField>

    <ResponseField name="delivery_status" type="string">
      Whether the ad is delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.

      Available options: `rejected`, `in_review`, `draft`, `campaign_paused`, `ad_group_paused`, `paused`, `processing`, `issues`, `learning_limited`, `learning`, `active`
    </ResponseField>

    <ResponseField name="descriptions" type="string[]">
      The description variants shown on the ad.
    </ResponseField>

    <ResponseField name="frequency" type="number | null">
      Platform-reported impressions divided by reach.
    </ResponseField>

    <ResponseField name="headlines" type="string[]">
      The headline variants shown on the ad.
    </ResponseField>

    <ResponseField name="impressions" type="number">
      The number of impressions.
    </ResponseField>

    <ResponseField name="issues" type="object[]">
      Open issues affecting this ad. Empty when there are none.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Unique identifier for the issue.
        </ResponseField>

        <ResponseField name="message" type="string">
          A description of what the issue is and how it can be resolved.
        </ResponseField>

        <ResponseField name="resource_id" type="string | null">
          The ID of the campaign, ad group, or ad the issue is attached to.
        </ResponseField>

        <ResponseField name="resource_type" type="string">
          The type of resource the issue is attached to.

          Available options: `ad_campaign`, `ad_group`, `ad`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="lead_form" type="object | null">
      The instant lead form shown when someone taps this ad. `null` when the ad group's conversion\_location is not an instant-form destination.

      <Accordion title="Properties">
        <ResponseField name="completion" type="object | null">
          Screen shown after the form is submitted. `null` when the form uses the default.

          <Accordion title="Properties">
            <ResponseField name="button_text" type="string | null">
              Text of the follow-up button.
            </ResponseField>

            <ResponseField name="description" type="string | null">
              Body text under the headline.
            </ResponseField>

            <ResponseField name="headline" type="string | null">
              Headline of the completion screen.
            </ResponseField>

            <ResponseField name="url" type="string | null">
              Website the follow-up button opens. `null` when the screen has no button.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="disclaimer" type="object | null">
          Custom consent disclaimer shown before submission. `null` when the form has none.

          <Accordion title="Properties">
            <ResponseField name="body" type="string | null">
              Disclaimer text.
            </ResponseField>

            <ResponseField name="checkboxes" type="object[]">
              Consent checkboxes the person can tick. Empty when the disclaimer is text-only.

              <Accordion title="Properties">
                <ResponseField name="checked_by_default" type="boolean | null">
                  Whether the checkbox starts ticked.
                </ResponseField>

                <ResponseField name="key" type="string | null">
                  Stable identifier consent responses are stored under.
                </ResponseField>

                <ResponseField name="required" type="boolean | null">
                  Whether the checkbox must be ticked to submit the form.
                </ResponseField>

                <ResponseField name="text" type="string">
                  Consent text next to the checkbox.
                </ResponseField>
              </Accordion>
            </ResponseField>

            <ResponseField name="title" type="string | null">
              Disclaimer title.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="form_type" type="string">
          `more_volume` is quickest to submit; `higher_intent` adds a confirmation step before submission.

          Available options: `more_volume`, `higher_intent`
        </ResponseField>

        <ResponseField name="intro" type="object | null">
          Intro screen shown before the questions. `null` when the form has none.

          <Accordion title="Properties">
            <ResponseField name="description" type="string | null">
              Body text under the headline.
            </ResponseField>

            <ResponseField name="headline" type="string | null">
              Headline of the intro screen.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="name" type="string | null">
          Internal name of the form.
        </ResponseField>

        <ResponseField name="phone_verification" type="boolean">
          Whether the phone number must be verified by SMS before submitting.
        </ResponseField>

        <ResponseField name="privacy_policy" type="object | null">
          Your privacy policy, linked from the form. `null` when unset.

          <Accordion title="Properties">
            <ResponseField name="link_text" type="string | null">
              Link text shown for the policy. `null` uses the platform default.
            </ResponseField>

            <ResponseField name="url" type="string">
              URL of your privacy policy.
            </ResponseField>
          </Accordion>
        </ResponseField>

        <ResponseField name="questions" type="object[]">
          Questions on the form, in order.

          <Accordion title="Properties">
            <ResponseField name="format" type="string">
              Answer format for `custom` questions: `short_answer`, `multiple_choice`, or
              `appointment`. Absent otherwise.
            </ResponseField>

            <ResponseField name="label" type="string">
              Question text for `custom` questions. Absent for standard prefill questions.
            </ResponseField>

            <ResponseField name="options" type="object[]">
              Choices for `multiple_choice` questions. Absent for other formats.

              <Accordion title="Properties">
                <ResponseField name="key" type="string | null">
                  Stable identifier the choice's answers are stored under. Absent for simple
                  choices.
                </ResponseField>

                <ResponseField name="logic" type="object">
                  Where the form goes when this choice is selected. Absent when the form just continues to the next question.

                  <Accordion title="Properties">
                    <ResponseField name="action" type="string">
                      What happens when the choice is selected.

                      Available options: `go_to_question`, `submit_form`, `close_form`
                    </ResponseField>

                    <ResponseField name="target_end_page_index" type="number">
                      Zero-based index of the ending screen to jump to.
                    </ResponseField>

                    <ResponseField name="target_question_index" type="number">
                      Zero-based index of the question to jump to, for `go_to_question`.
                    </ResponseField>
                  </Accordion>
                </ResponseField>

                <ResponseField name="value" type="string">
                  Choice text shown to the person.
                </ResponseField>
              </Accordion>
            </ResponseField>

            <ResponseField name="type" type="string">
              Question type: a standard prefill type such as `email`, `phone`, or `full_name`, or `custom` for your own question.
            </ResponseField>
          </Accordion>
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="lead_form_id" type="string | null">
      The ad platform's ID for the instant form the ad uses. Set when the ad
      references an existing form via `lead_form_id`, or once a form built from
      `lead_form` has been created on the platform.
    </ResponseField>

    <ResponseField name="lead_value" type="number">
      USD value attributed to lead events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="leads" type="number">
      Whop pixel-attributed leads, last-click.
    </ResponseField>

    <ResponseField name="messaging_config" type="object | null">
      Welcome message for click-to-message ads, shown when the conversation opens. `null` when the ad has none.

      <Accordion title="Properties">
        <ResponseField name="keyword" type="string | null">
          Suggested reply the person can tap to start the conversation.
        </ResponseField>

        <ResponseField name="message" type="string | null">
          Greeting shown when the conversation opens.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="multi_advertiser_ads" type="boolean">
      Whether the ad can appear alongside other advertisers' ads in the same unit.
      Defaults to true.
    </ResponseField>

    <ResponseField name="post_id" type="string | null">
      The existing post this ad promotes — a Facebook post or Instagram media ID.
      `null` when the ad uses uploaded creatives.
    </ResponseField>

    <ResponseField name="post_source" type="string | null">
      Identifies the network that owns `post_id`; `null` when the ad uses uploaded creatives.

      Available options: `facebook`, `instagram`
    </ResponseField>

    <ResponseField name="post_thumbnail_url" type="string | null">
      Preview image of the existing post this ad promotes. `null` for ads that use
      uploaded creatives, or until the post's media has been fetched from the
      network.
    </ResponseField>

    <ResponseField name="primary_texts" type="string[]">
      The primary text variants shown in the ad body.
    </ResponseField>

    <ResponseField name="purchase_value" type="number">
      USD value of pixel-attributed purchases.
    </ResponseField>

    <ResponseField name="purchases" type="number">
      Whop pixel-attributed purchases, last-click.
    </ResponseField>

    <ResponseField name="reach" type="number">
      The number of unique people who saw this.
    </ResponseField>

    <ResponseField name="result_event" type="string | null">
      The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event.

      Available options: `purchase`, `lead`, `schedule`, `submit_application`, `contact`, `complete_registration`, `view_content`, `add_to_cart`, `custom`
    </ResponseField>

    <ResponseField name="result_event_name" type="string | null">
      The merchant-defined event name when result\_event is custom; null for the
      standard events.
    </ResponseField>

    <ResponseField name="results" type="number | null">
      The Whop pixel-attributed count behind result\_event. When a campaign's ad
      groups optimize different goals there is no single result\_event (it is null),
      and this is instead the sum of each ad group's own attributed results. Null
      when nothing Whop-attributable is being optimized for.
    </ResponseField>

    <ResponseField name="return_on_ad_spend" type="number">
      Purchase value divided by spend, both in USD (a currency-neutral ratio); 0
      when there is no spend.
    </ResponseField>

    <ResponseField name="schedule_value" type="number">
      USD value attributed to schedule events. Sums the value sent with each event,
      normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="schedules" type="number">
      Whop pixel-attributed schedule events, last-click.
    </ResponseField>

    <ResponseField name="social_accounts" type="object[]">
      The social accounts the ad runs under — its Facebook page and Instagram profile — each referenced by ID, prefixed `sacc_`.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          The referenced entity's id.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="spend" type="number">
      The amount charged, in spend\_currency.
    </ResponseField>

    <ResponseField name="spend_currency" type="string | null">
      The ISO 4217 currency code of all monetary metrics.
    </ResponseField>

    <ResponseField name="status" type="string">
      Whether the ad is enabled. `active` and `paused` are set by you; `in_review` and `rejected` come from ad review.

      Available options: `active`, `paused`, `in_review`, `rejected`
    </ResponseField>

    <ResponseField name="submitted_application_value" type="number">
      USD value attributed to submit-application events. Sums the value sent with
      each event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="submitted_applications" type="number">
      Whop pixel-attributed submit-application events, last-click.
    </ResponseField>

    <ResponseField name="title" type="string | null">
      Display title of the ad.
    </ResponseField>

    <ResponseField name="unique_click_through_rate" type="number | null">
      Unique clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="unique_clicks" type="number">
      People who clicked, reported by the Whop pixel, counted once per person.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the ad was last updated, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="url" type="string | null">
      The URL the ad links to.
    </ResponseField>

    <ResponseField name="url_parameters" type="object">
      Query parameters appended to the URL, keyed by parameter name.
    </ResponseField>

    <ResponseField name="viewed_content_value" type="number">
      USD value attributed to view-content events. Sums the value sent with each
      event, normalized to USD; events without a value contribute 0.
    </ResponseField>

    <ResponseField name="viewed_contents" type="number">
      Whop pixel-attributed view-content events, last-click.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Ad theme={null}
      {
      	"id": "ad_xxxxxxxxxxxxx",
      	"ad_campaign": {
      		"id": "adcamp_xxxxxxxxxx"
      	},
      	"ad_group": {
      		"id": "adgrp_xxxxxxxxxxx"
      	},
      	"added_to_cart_value": 540,
      	"added_to_carts": 18,
      	"call_to_action": "shop_now",
      	"click_through_rate": 0.034,
      	"clicks": 420,
      	"completed_registration_value": 0,
      	"completed_registrations": 12,
      	"contact_value": 0,
      	"contacts": 8,
      	"cost_per_added_to_cart": 7.22,
      	"cost_per_click": 0.31,
      	"cost_per_completed_registration": 10.83,
      	"cost_per_contact": 16.25,
      	"cost_per_lead": 9.29,
      	"cost_per_mille": 14.5,
      	"cost_per_purchase": 21.67,
      	"cost_per_result": 21.67,
      	"cost_per_schedule": null,
      	"cost_per_submitted_application": null,
      	"cost_per_unique_click": 0.37,
      	"cost_per_viewed_content": 0.54,
      	"created_at": "2026-06-01T12:00:00Z",
      	"creatives": [
      		{
      			"id": "file_xxxxxxxxxxxx",
      			"crop": {
      				"height": 1080,
      				"width": 1080,
      				"x": 120,
      				"y": 0
      			},
      			"format": "square",
      			"media_type": "image",
      			"url": "https://img.whop.com/file_xxxxxxxxxxxx.jpg"
      		}
      	],
      	"custom_conversions": 4,
      	"custom_event_counts": {
      		"QualifiedCall": 3,
      		"BookedDemo": 1
      	},
      	"custom_event_values": {
      		"QualifiedCall": 1500,
      		"BookedDemo": 0
      	},
      	"delivery_status": "issues",
      	"descriptions": ["Limited spots available this week."],
      	"frequency": 1.8,
      	"headlines": ["Join Pickaxe Pro"],
      	"impressions": 9000,
      	"issues": [
      		{
      			"id": "adiss_xxxxxxxxxxx",
      			"message": "The ad's creative violates the ad network's policies. Edit the creative and resubmit for review.",
      			"resource_id": "ad_xxxxxxxxxxxxx",
      			"resource_type": "ad"
      		}
      	],
      	"lead_form": null,
      	"lead_form_id": null,
      	"lead_value": 700,
      	"leads": 14,
      	"messaging_config": null,
      	"multi_advertiser_ads": true,
      	"post_id": null,
      	"post_source": null,
      	"post_thumbnail_url": null,
      	"primary_texts": ["Build sharper trading habits with daily lessons."],
      	"purchase_value": 1820,
      	"purchases": 6,
      	"reach": 5000,
      	"result_event": "purchase",
      	"result_event_name": null,
      	"results": 6,
      	"return_on_ad_spend": 14,
      	"schedule_value": 0,
      	"schedules": 0,
      	"social_accounts": [
      		{
      			"id": "sacc_xxxxxxxxxxxx"
      		}
      	],
      	"spend": 130,
      	"spend_currency": "usd",
      	"status": "active",
      	"submitted_application_value": 0,
      	"submitted_applications": 0,
      	"title": "Pickaxe Pro launch ad",
      	"unique_click_through_rate": 0.028,
      	"unique_clicks": 350,
      	"updated_at": "2026-06-02T12:00:00Z",
      	"url": "https://whop.com/pickaxe",
      	"url_parameters": {
      		"utm_campaign": "pickaxe-launch"
      	},
      	"viewed_content_value": 0,
      	"viewed_contents": 240
      }
      ```
    </div>
  </Column>
</Columns>


# Create an Ad
Source: https://docs.whop.com/api-reference/beta/ads/create-an-ad

/openapi/api-v1-native.json post /ads
Creates an ad in an ad group.



# Delete an Ad
Source: https://docs.whop.com/api-reference/beta/ads/delete-an-ad

/openapi/api-v1-native.json delete /ads/{id}
Deletes an ad.



# Duplicate an Ad
Source: https://docs.whop.com/api-reference/beta/ads/duplicate-an-ad

/openapi/api-v1-native.json post /ads/{id}/duplicate
Copies the ad into its own ad group, or into target_ad_group_id (which must belong to the same account and be compatible with the ad). Copies keep the source ad's active/paused state.



# List Ads
Source: https://docs.whop.com/api-reference/beta/ads/list-ads

/openapi/api-v1-native.json get /ads
Lists the ads for an account, with stats over the requested window.



# Overview
Source: https://docs.whop.com/api-reference/beta/ads/overview



Whop Ads runs paid ads on networks like Meta directly from your Whop account. You fund campaigns from your balance; Whop handles the ad account, review, launch, and billing.

Two API calls take you from nothing to a live ad: generate a creative, then create the campaign, ad group, and ad in one request.

## Resources

| Resource                                                    | What it is                                              |
| ----------------------------------------------------------- | ------------------------------------------------------- |
| [Ad Campaign](/api-reference/beta/ad-campaigns/ad-campaign) | Top-level container: objective and (optionally) budget. |
| [Ad Group](/api-reference/beta/ad-groups/ad-group)          | Targeting, placements, and budget for a set of ads.     |
| [Ad](/api-reference/beta/ads/ad)                            | The creative unit — copy, assets, destination URL.      |
| [Audience](/api-reference/beta/audiences/audience)          | A custom audience to target or exclude in ad groups.    |

## One-time setup

* **Scopes**: `media:generate`, `media:read`, `ad_campaign:create`, `ad_campaign:update`, `ad_campaign:basic:read`, `social_account:read`.
* **Facebook page**: [`GET /social_accounts`](/api-reference/beta/social-accounts/list-social-accounts) must have a `"platform": "facebook"` entry. If not, link your Meta Business account with [`POST /social_accounts/connect`](/api-reference/beta/social-accounts/connect-a-social-account) `{"platform": "meta_business", "scopes": ["advertise"], "redirect_url": "..."}` → send the user to the returned `authorize_url` — or, if you don't have a page at all, have Whop create one with [`POST /social_accounts`](/api-reference/beta/social-accounts/create-a-social-account) `{"platform": "facebook"}`.
* **Ads payment method**: connected in the dashboard (balance or card). Only launching needs it — drafts work without.

<Steps>
  <Step title="Generate a creative">
    ```bash theme={null}
    curl -X POST "https://api.whop.com/api/v1/media/generate" \
      -H "Authorization: Bearer $WHOP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"type": "image", "prompt": "A running club jogging across a bridge at sunrise, warm light, joyful energy"}'
    ```

    Billed from your balance (`amount_charged`; not enough balance → `402` with a `deposit_url`). Poll [`GET /media/{id}`](/api-reference/beta/media/retrieve-media-asset) until `status` is `ready`, then use `file.id`:

    ```json theme={null}
    {
    	"id": "media_Hx7qg4tZc97o",
    	"status": "ready",
    	"file": { "id": "file_Zsv4DYkrbWE7h" }
    }
    ```

    `failed` refunds the charge — tweak the prompt and retry. Video: `"type": "video"` plus optional `duration_seconds` (5/10/15), `resolution` (`480p`–`4k`), and up to 4 `reference_media` file IDs (first one seeds the opening frame).
  </Step>

  <Step title="Create and launch the ad — one request">
    [`POST /ads`](/api-reference/beta/ads/create-an-ad) with an inline `ad_group` and `ad_campaign` creates the whole tree in one transaction and launches it:

    ```bash theme={null}
    curl -X POST "https://api.whop.com/api/v1/ads" \
      -H "Authorization: Bearer $WHOP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Run club launch ad",
        "primary_texts": ["Join 10,000 runners chasing their next PR together."],
        "headlines": ["Find your stride"],
        "call_to_action": "sign_up",
        "url": "https://whop.com/your-store-page",
        "creatives": [{"id": "file_Zsv4DYkrbWE7h"}],
        "social_accounts": [{"id": "sacc_XXXXXXXX"}],
        "ad_group": {
          "title": "US broad",
          "conversion_location": "website",
          "budget_amount": 25,
          "budget_type": "daily",
          "regions": {"include": {"countries": ["US"]}},
          "ad_campaign": {"title": "Run club growth", "platform": "meta", "objective": "sales"}
        }
      }'
    ```

    Not ready to spend? Add `"status": "draft"` to `ad_campaign`, then launch later with [`PATCH /ad_campaigns/{id}`](/api-reference/beta/ad-campaigns/update-an-ad-campaign) `{"status": "active"}`.

    | Field       | Rule                                                                                                                                         |
    | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
    | `creatives` | One entry with no `format` is required (the base asset). `square` / `vertical` / `horizontal` are optional crops on top.                     |
    | `url`       | Required for website ads. Your whop.com store page works as-is; an external page needs your [Whop pixel](/developer/guides/pixel) installed. |
    | Budget      | One level owns it: `budget_amount` on the ad group (default), or on the campaign with `budget_optimization: "ad_campaign"` — never both.     |
    | Targeting   | Omit `demographics` / `placements` / `devices` for automatic optimization. `regions` uses ISO 3166 (`"US"`, `"US-CA"`).                      |
    | `lead_form` | Only with an instant-form `conversion_location`.                                                                                             |

    To reuse existing containers, pass `ad_group_id` instead of `ad_group`, or `ad_campaign_id` instead of `ad_campaign`.
  </Step>

  <Step title="Monitor">
    Poll [`GET /ads/{id}`](/api-reference/beta/ads/retrieve-an-ad): `delivery_status` is the live state (a brief `in_review` for content moderation is normal), and `issues[]` carries a human-readable `message` for anything Meta rejected asynchronously.

    Control delivery with [`pause`](/api-reference/beta/ads/pause-an-ad) / [`unpause`](/api-reference/beta/ads/unpause-an-ad) on ads, ad groups, or campaigns. Edit copy or creatives with [`PATCH /ads/{id}`](/api-reference/beta/ads/update-an-ad) — sending `creatives` replaces the whole set, so include the base entry.
  </Step>
</Steps>

## Errors

Every gate is a `400` whose message says what to fix:

| Error contains                                   | Fix                                                                                                                           |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `The Whop pixel was not detected on <url>`       | Use your own whop.com store page, or [install the pixel](/developer/guides/pixel) on the landing page.                        |
| `A Facebook page is required`                    | Connect one via `POST /social_accounts` (human OAuth step), pass it in `social_accounts`.                                     |
| `Connect an ads payment method before launching` | Create with `ad_campaign.status: "draft"`, have the user connect a payment method in the dashboard, then `PATCH` to `active`. |
| `Include a base creative`                        | Add a `creatives` entry with no `format`.                                                                                     |
| `A destination URL is required`                  | Pass `url`.                                                                                                                   |
| `budget_amount is required` / `can't be set`     | Move the budget to the right level (see field rules above).                                                                   |
| `402` + `deposit_url` (media)                    | Send the user to `deposit_url` to top up, then retry.                                                                         |


# Pause an Ad
Source: https://docs.whop.com/api-reference/beta/ads/pause-an-ad

/openapi/api-v1-native.json post /ads/{id}/pause
Pauses an active ad.



# Retrieve an Ad
Source: https://docs.whop.com/api-reference/beta/ads/retrieve-an-ad

/openapi/api-v1-native.json get /ads/{id}
Retrieves a single ad with stats over the requested window.



# Unpause an Ad
Source: https://docs.whop.com/api-reference/beta/ads/unpause-an-ad

/openapi/api-v1-native.json post /ads/{id}/unpause
Resumes a paused ad.



# Update an Ad
Source: https://docs.whop.com/api-reference/beta/ads/update-an-ad

/openapi/api-v1-native.json patch /ads/{id}
Updates an ad's editable fields.



# API Key
Source: https://docs.whop.com/api-reference/beta/api-keys/api-key



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.

## Version pinning

Each API key stores an `api_version_date`. Requests authenticated with the key use that version when they omit the `Api-Version-Date` header. An explicit header takes precedence. New keys default to the latest released version, while legacy keys without a stored pin use `2025-01-01`.

## Endpoints

| Endpoint                                                                                | Request                                     |
| --------------------------------------------------------------------------------------- | ------------------------------------------- |
| [List API Keys](/api-reference/beta/api-keys/list-api-keys)                             | <Badge>GET</Badge> `/api_keys`              |
| [Create API Key](/api-reference/beta/api-keys/create-api-key)                           | <Badge>POST</Badge> `/api_keys`             |
| [Retrieve API Key](/api-reference/beta/api-keys/retrieve-api-key)                       | <Badge>GET</Badge> `/api_keys/{id}`         |
| [Update API Key](/api-reference/beta/api-keys/update-api-key)                           | <Badge>PATCH</Badge> `/api_keys/{id}`       |
| [Delete API Key](/api-reference/beta/api-keys/delete-api-key)                           | <Badge>DELETE</Badge> `/api_keys/{id}`      |
| [Rotate API Key](/api-reference/beta/api-keys/rotate-api-key)                           | <Badge>POST</Badge> `/api_keys/{id}/rotate` |
| [List the Permission Catalog](/api-reference/beta/api-keys/list-the-permission-catalog) | <Badge>GET</Badge> `/api_keys/permissions`  |


# Create API Key
Source: https://docs.whop.com/api-reference/beta/api-keys/create-api-key

/openapi/api-v1-native.json post /api_keys
Creates an API key for an account or app. The response is the only place the full `secret_key` is returned — store it immediately. Requires a user session; API keys cannot manage API keys.



# Delete API Key
Source: https://docs.whop.com/api-reference/beta/api-keys/delete-api-key

/openapi/api-v1-native.json delete /api_keys/{id}
Permanently revokes an API key; requests using its secret stop authenticating immediately. Default and agent-backend keys cannot be deleted.



# List API Keys
Source: https://docs.whop.com/api-reference/beta/api-keys/list-api-keys

/openapi/api-v1-native.json get /api_keys
Lists the API keys of an account or app, newest first. Responses never include the full secret — only its obfuscated form.



# List the Permission Catalog
Source: https://docs.whop.com/api-reference/beta/api-keys/list-the-permission-catalog

/openapi/api-v1-native.json get /api_keys/permissions
Lists the catalog of permission actions that can be granted to users, apps, and API keys — the source for the dashboard's permission pickers. Small and returned in full on one page.



# Retrieve API Key
Source: https://docs.whop.com/api-reference/beta/api-keys/retrieve-api-key

/openapi/api-v1-native.json get /api_keys/{id}
Retrieves an API key with its effective permission grants. The full secret is never returned — rotate the key if it was lost.



# Rotate API Key
Source: https://docs.whop.com/api-reference/beta/api-keys/rotate-api-key

/openapi/api-v1-native.json post /api_keys/{id}/rotate
Rotates the API key's secret, invalidating the previous secret immediately. The response is the only place the new `secret_key` is returned.



# Update API Key
Source: https://docs.whop.com/api-reference/beta/api-keys/update-api-key

/openapi/api-v1-native.json patch /api_keys/{id}
Updates an API key's name, permissions, API version, expiration, or IP allowlist. Fields that are omitted keep their current value; default keys cannot be modified.



# App Build
Source: https://docs.whop.com/api-reference/beta/app-builds/app-build



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.

## Endpoints

| Endpoint                                                                | Request                                        |
| ----------------------------------------------------------------------- | ---------------------------------------------- |
| [List App Builds](/api-reference/beta/app-builds/list-app-builds)       | <Badge>GET</Badge> `/app_builds`               |
| [Create App Build](/api-reference/beta/app-builds/create-app-build)     | <Badge>POST</Badge> `/app_builds`              |
| [Retrieve App Build](/api-reference/beta/app-builds/retrieve-app-build) | <Badge>GET</Badge> `/app_builds/{id}`          |
| [Promote App Build](/api-reference/beta/app-builds/promote-app-build)   | <Badge>POST</Badge> `/app_builds/{id}/promote` |


# Create App Build
Source: https://docs.whop.com/api-reference/beta/app-builds/create-app-build

/openapi/api-v1-native.json post /app_builds
Uploads a new build artifact for an app. Upload the file first (POST /files or a direct upload), then reference it here; iOS and Android take a .zip bundle, web takes a JavaScript file or a .zip archive of the hosted site.



# List App Builds
Source: https://docs.whop.com/api-reference/beta/app-builds/list-app-builds

/openapi/api-v1-native.json get /app_builds
Returns a paginated list of build artifacts for an app, newest first, with optional platform, status, and creation-date filters.



# Promote App Build
Source: https://docs.whop.com/api-reference/beta/app-builds/promote-app-build

/openapi/api-v1-native.json post /app_builds/{id}/promote
Promotes a draft or approved app build to production so it becomes the active version served to users. Draft builds enter review first.



# Retrieve App Build
Source: https://docs.whop.com/api-reference/beta/app-builds/retrieve-app-build

/openapi/api-v1-native.json get /app_builds/{id}
Retrieves the details of an existing app build.



# App
Source: https://docs.whop.com/api-reference/beta/apps/app



An App is software you build on Whop. It can be a hosted web app served at `<route>.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 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.

## Endpoints

| Endpoint                                                                  | Request                                       |
| ------------------------------------------------------------------------- | --------------------------------------------- |
| [List Apps](/api-reference/beta/apps/list-apps)                           | <Badge>GET</Badge> `/apps`                    |
| [Create App](/api-reference/beta/apps/create-app)                         | <Badge>POST</Badge> `/apps`                   |
| [Retrieve App](/api-reference/beta/apps/retrieve-app)                     | <Badge>GET</Badge> `/apps/{id}`               |
| [Update App](/api-reference/beta/apps/update-app)                         | <Badge>PATCH</Badge> `/apps/{id}`             |
| [Delete App](/api-reference/beta/apps/delete-app)                         | <Badge>DELETE</Badge> `/apps/{id}`            |
| [List App Logs](/api-reference/beta/apps/list-app-logs)                   | <Badge>GET</Badge> `/apps/{id}/logs`          |
| [Update App Permissions](/api-reference/beta/apps/update-app-permissions) | <Badge>PATCH</Badge> `/apps/{id}/permissions` |


# Create App
Source: https://docs.whop.com/api-reference/beta/apps/create-app

/openapi/api-v1-native.json post /apps
Registers a new app on the Whop developer platform. Apps provide custom experiences that can be added to products.



# Delete App
Source: https://docs.whop.com/api-reference/beta/apps/delete-app

/openapi/api-v1-native.json delete /apps/{id}
Deletes an app. The app stops resolving within seconds — a website's site stops serving, and any claimed subdomain is reserved for a month before it can be claimed again.



# List App Logs
Source: https://docs.whop.com/api-reference/beta/apps/list-app-logs

/openapi/api-v1-native.json get /apps/{id}/logs
Lists a hosted app's server runtime logs, most recent first: console output, uncaught exceptions, and failed-request summaries captured on whop.app hosting. Logs are retained for 7 days.



# List Apps
Source: https://docs.whop.com/api-reference/beta/apps/list-apps

/openapi/api-v1-native.json get /apps
Lists apps on the Whop platform: the app store's live apps, or — with `account_id` and developer access to that account — every app the account owns.



# Retrieve App
Source: https://docs.whop.com/api-reference/beta/apps/retrieve-app

/openapi/api-v1-native.json get /apps/{id}
Retrieves an app by ID, claimed route, or proxy domain id. Credential fields (api_key, default_api_key, secrets) render `null` unless the caller has the corresponding developer permission on the owning account.



# Update App
Source: https://docs.whop.com/api-reference/beta/apps/update-app

/openapi/api-v1-native.json patch /apps/{id}
Updates the settings, metadata, or status of an app. Fields that are omitted keep their current value.



# Update App Permissions
Source: https://docs.whop.com/api-reference/beta/apps/update-app-permissions

/openapi/api-v1-native.json patch /apps/{id}/permissions
Replaces the set of permissions the app requests from users when they install it. Requires a user session: the `developer:update_app_authorization` scope cannot be delegated to API keys.



# Add People
Source: https://docs.whop.com/api-reference/beta/audiences/add-people

/openapi/api-v1-native.json post /audiences/{audience_id}/add_people
Adds users from a new CSV file to an existing uploaded custom audience. The file uses the audience's saved column mapping, processing happens in the background, and existing audience members remain unchanged.



# Audience
Source: https://docs.whop.com/api-reference/beta/audiences/audience



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`.

## Endpoints

| Endpoint                                                         | Request                                                   |
| ---------------------------------------------------------------- | --------------------------------------------------------- |
| [List Audiences](/api-reference/beta/audiences/list-audiences)   | <Badge>GET</Badge> `/audiences`                           |
| [Create Audience](/api-reference/beta/audiences/create-audience) | <Badge>POST</Badge> `/audiences`                          |
| [Update Audience](/api-reference/beta/audiences/update-audience) | <Badge>PATCH</Badge> `/audiences/{audience_id}`           |
| [Delete Audience](/api-reference/beta/audiences/delete-audience) | <Badge>DELETE</Badge> `/audiences/{audience_id}`          |
| [Add People](/api-reference/beta/audiences/add-people)           | <Badge>POST</Badge> `/audiences/{audience_id}/add_people` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Audience ID, prefixed `adaud_`.
    </ResponseField>

    <ResponseField name="audience_type" type="string">
      `custom` = a customer list (uploaded, or built from saved People filters); `lookalike` = Meta lookalike built from a custom audience.

      Available options: `custom`, `lookalike`
    </ResponseField>

    <ResponseField name="auto_refresh" type="boolean">
      Whether membership keeps updating. `true` rebuilds it from the saved filters
      twice a day, so people join and leave as they start and stop matching. `false`
      keeps whoever matched when it was built and never rebuilds. Always `false` for
      uploaded lists and lookalikes.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the audience was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="error_message" type="string | null">
      Processing error message. `null` unless processing is partial or failed.
    </ResponseField>

    <ResponseField name="filters" type="object | null">
      For audiences built from People filters: the filters that define membership, keyed exactly as `GET /people` accepts them — for example `\{"os": "iOS", "country": "US"}`. `null` for uploaded lists and lookalikes.
    </ResponseField>

    <ResponseField name="last_refreshed_at" type="string | null">
      When the audience membership was last rebuilt, as an ISO 8601 timestamp.
      `null` until the first build completes.
    </ResponseField>

    <ResponseField name="lookalike_ratio" type="number | null">
      For lookalikes: the upper bound of the similarity band as a fraction (0.02 =
      top 2%). `null` for custom audiences.
    </ResponseField>

    <ResponseField name="lookalike_starting_ratio" type="number | null">
      For lookalikes: the lower bound of the similarity band as a fraction. `null`
      for custom audiences and first-tier lookalikes.
    </ResponseField>

    <ResponseField name="match_rates" type="object[]">
      Estimated match rates by ad platform. Empty when the audience was not sent to a supported platform.

      <Accordion title="Properties">
        <ResponseField name="lower_bound" type="number | null">
          Lower bound of the estimated match rate percentage. `null` until available.
        </ResponseField>

        <ResponseField name="platform" type="string">
          The ad platform that provided the match-rate estimate.

          Available options: `meta`
        </ResponseField>

        <ResponseField name="status" type="string | null">
          Availability of the estimated match rate.

          Available options: `calculating`, `available`, `unavailable`
        </ResponseField>

        <ResponseField name="upper_bound" type="number | null">
          Upper bound of the estimated match rate percentage. `null` until available.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="matched_rows" type="number">
      Members successfully uploaded to connected ad accounts. Always 0 for
      lookalikes.
    </ResponseField>

    <ResponseField name="name" type="string">
      Audience display name.
    </ResponseField>

    <ResponseField name="platform_audience_ids" type="string[]">
      External audience IDs created on connected ad platforms, such as Meta.
    </ResponseField>

    <ResponseField name="processed_rows" type="number">
      Members processed from the source so far. Always 0 for lookalikes.
    </ResponseField>

    <ResponseField name="progress_percent" type="number">
      Processing progress from 0 to 100.
    </ResponseField>

    <ResponseField name="source_audience_id" type="string | null">
      For lookalikes: the audience this lookalike was built from. `null` for custom
      audiences.
    </ResponseField>

    <ResponseField name="source_type" type="string">
      Where members come from. `csv_upload` = an uploaded customer list; `people_filter` = built from saved People filters. See `auto_refresh` for whether a `people_filter` audience keeps updating.

      Available options: `csv_upload`, `people_filter`
    </ResponseField>

    <ResponseField name="status" type="string">
      Current state of the audience import. `syncing` means Whop is sending matched rows to connected ad accounts. When status is `partial` or `failed`, `error_message` explains what went wrong.

      Available options: `pending`, `processing`, `syncing`, `ready`, `partial`, `failed`
    </ResponseField>

    <ResponseField name="total_rows" type="number">
      Total members detected in the source — CSV rows for uploaded lists, matching
      people for automatic audiences. Always 0 for lookalikes.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the audience was last updated, as an ISO 8601 timestamp.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json Audience theme={null}
      {
      	"id": "adaud_PastPurchasers123",
      	"name": "Past purchasers",
      	"status": "ready",
      	"audience_type": "custom",
      	"source_type": "people_filter",
      	"source_audience_id": null,
      	"lookalike_ratio": null,
      	"lookalike_starting_ratio": null,
      	"total_rows": 2500,
      	"processed_rows": 2500,
      	"matched_rows": 1830,
      	"progress_percent": 100,
      	"error_message": null,
      	"platform_audience_ids": ["120246230799130686"],
      	"filters": {
      		"has_purchased": true,
      		"country": "US"
      	},
      	"auto_refresh": true,
      	"last_refreshed_at": "2025-12-01T01:00:00Z",
      	"match_rates": [
      		{
      			"platform": "meta",
      			"status": "available",
      			"lower_bound": 68.2,
      			"upper_bound": 74.5
      		}
      	],
      	"created_at": "2025-12-01T00:00:00Z",
      	"updated_at": "2025-12-01T01:00:00Z"
      }
      ```
    </div>
  </Column>
</Columns>


# Create
Source: https://docs.whop.com/api-reference/beta/audiences/create-audience

openapi/api-v1-native.json POST /audiences
Creates an audience. Default (`audience_type` omitted or `custom`): creates one audience from an uploaded customer identity CSV file (`name`, `column_mapping`, and `file_id` required) and starts processing it; responds with the audience object. With `filters`: creates an audience from saved People filters (`name` required) — membership is built from the account's People data, and `auto_refresh` decides whether it keeps tracking the filters or keeps whoever matched at creation. With `audience_type: lookalike`: creates a ladder of Meta lookalike audiences from an existing ready custom audience (`source_audience_id`, `count`, and `percentage` required) — `count` equal similarity bands slicing the top `percentage`% (3 audiences at 6% = 0–2%, 2–4%, 4–6%), each returned as its own audience in a `{ data: [...] }` envelope.

Upload the customer CSV with [`POST /files`](/api-reference/beta/files/create-file), then pass the returned `file_...` ID as `file_id`.

`column_mapping` tells Whop which CSV header contains each identity field. Headers can be custom, but rows missing both email and phone are skipped. After creating the audience, poll [List Audiences](/api-reference/beta/audiences/list-audiences) until `status` is `ready`, `partial`, or `failed`.

Map `ltv` to a column of per-customer lifetime values to build a value-based audience. Lookalikes created from it favor people similar to your highest-value customers.

<RequestExample>
  ```csv CSV file theme={null}
  Email,Phone,First Name,Last Name,Country,LTV
  jenny.nuo@example.com,+14155550123,Jenny,Nuo,US,249.50
  ```

  ```json Request body theme={null}
  {
  	"account_id": "biz_xxxxxxxxxxxxxx",
  	"name": "Past purchasers",
  	"column_mapping": {
  		"email": "Email",
  		"phone": "Phone",
  		"first_name": "First Name",
  		"last_name": "Last Name",
  		"country": "Country",
  		"ltv": "LTV"
  	},
  	"file_id": "file_xxxxxxxxxxxxx"
  }
  ```
</RequestExample>


# Delete Audience
Source: https://docs.whop.com/api-reference/beta/audiences/delete-audience

/openapi/api-v1-native.json delete /audiences/{audience_id}
Deletes an audience so it is no longer available for targeting.



# List Audiences
Source: https://docs.whop.com/api-reference/beta/audiences/list-audiences

/openapi/api-v1-native.json get /audiences
Lists uploaded customer-list audiences for an account. Pass `audience_id` to return a specific audience.



# Update Audience
Source: https://docs.whop.com/api-reference/beta/audiences/update-audience

/openapi/api-v1-native.json patch /audiences/{audience_id}
Renames an audience. For an audience built from People filters that keeps itself up to date, pass `filters` to replace them, which rebuilds membership immediately. Whether an audience auto refreshes is set when it is created.



# Generate Media Asset
Source: https://docs.whop.com/api-reference/beta/media/generate-media-asset

/openapi/api-v1-native.json post /media/generate
Starts an AI media generation job billed from the account's balance. Generation is asynchronous — poll `GET /media/{id}` until the asset is `ready`, then use `file.id` anywhere attachments are accepted.



# Media
Source: https://docs.whop.com/api-reference/beta/media/media



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.

## Endpoints

| Endpoint                                                               | Request                               |
| ---------------------------------------------------------------------- | ------------------------------------- |
| [Retrieve Media Asset](/api-reference/beta/media/retrieve-media-asset) | <Badge>GET</Badge> `/media/{id}`      |
| [Generate Media Asset](/api-reference/beta/media/generate-media-asset) | <Badge>POST</Badge> `/media/generate` |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Media asset ID, prefixed `media_`.
    </ResponseField>

    <ResponseField name="amount_charged" type="number | null">
      USD amount charged to the account's balance for this generation. `null` if the
      generation wasn't billed.
    </ResponseField>

    <ResponseField name="completed_at" type="string | null">
      ISO 8601 timestamp when the asset reached a terminal state. `null` while
      `processing`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when the generation was requested.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency of `amount_charged`. Always `usd`.
    </ResponseField>

    <ResponseField name="error_message" type="string | null">
      Why generation failed. `null` unless status is `failed`.
    </ResponseField>

    <ResponseField name="file" type="object | null">
      The produced file, usable anywhere attachments are accepted. `null` until the asset is `ready`.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          File ID, prefixed `file_`.
        </ResponseField>

        <ResponseField name="url" type="string">
          CDN URL for downloading the file.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="generation" type="object">
      The inputs the asset was generated from.

      <Accordion title="Properties">
        <ResponseField name="duration_seconds" type="number | null">
          Requested video length in seconds. `null` for images.
        </ResponseField>

        <ResponseField name="prompt" type="string">
          What the asset was generated from.
        </ResponseField>

        <ResponseField name="reference_media" type="string[]">
          Reference image file IDs (`file_` prefixed) supplied at generation time.
        </ResponseField>

        <ResponseField name="resolution" type="string | null">
          Requested video resolution. `null` for images. `1080p` is not supported by Seedance 2.0 Fast or Mini; `4k` is only supported by Seedance 2.0.

          Available options: `480p`, `720p`, `1080p`, `4k`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="media_type" type="string">
      The kind of media this asset holds.

      Available options: `video`, `image`
    </ResponseField>

    <ResponseField name="source" type="string">
      How the asset was created. Always `generated`.

      Available options: `generated`
    </ResponseField>

    <ResponseField name="status" type="string">
      Lifecycle state: `processing` while generation runs, `ready` when the file is available, `failed` when generation failed and the charge was refunded.

      Available options: `processing`, `ready`, `failed`
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json MediaAsset theme={null}
      {
      	"id": "media_xxxxxxxxxxx",
      	"amount_charged": 0.25,
      	"completed_at": "2026-06-01T12:01:30Z",
      	"created_at": "2026-06-01T12:00:00Z",
      	"currency": "usd",
      	"error_message": null,
      	"file": {
      		"id": "file_xxxxxxxxxxxx",
      		"url": "https://img.whop.com/file_xxxxxxxxxxxx.png"
      	},
      	"generation": {
      		"duration_seconds": null,
      		"prompt": "A clean product mockup on a white background",
      		"reference_media": [],
      		"resolution": null
      	},
      	"media_type": "image",
      	"source": "generated",
      	"status": "ready"
      }
      ```
    </div>
  </Column>
</Columns>


# Retrieve Media Asset
Source: https://docs.whop.com/api-reference/beta/media/retrieve-media-asset

/openapi/api-v1-native.json get /media/{id}
Retrieves a media asset by ID. Poll this while the asset is `processing`.



# Check Permissions
Source: https://docs.whop.com/api-reference/beta/permissions/check-permissions

/openapi/api-v1-native.json get /permissions
Lists permission actions and whether the calling credential is granted each one for a resource. Answers for whichever identity authenticated the request — a user session, an OAuth token, or an account or app API key — so it never describes who else can reach the resource.



# Permission
Source: https://docs.whop.com/api-reference/beta/permissions/permission



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.

## Endpoints

| Endpoint                                                               | Request                           |
| ---------------------------------------------------------------------- | --------------------------------- |
| [Check Permissions](/api-reference/beta/permissions/check-permissions) | <Badge>GET</Badge> `/permissions` |


# Run Recommended Action
Source: https://docs.whop.com/api-reference/beta/recommended-actions/run-recommended-action

/openapi/api-v1-native.json post /recommended_actions/{chain_id}
Records that the caller ran a recommended action chain. Nothing is executed server-side yet — the client follows the chain's step CTAs itself; this writes the `recommended_action_chain.executed` analytics event.



# Connect a Social Account
Source: https://docs.whop.com/api-reference/beta/social-accounts/connect-a-social-account

/openapi/api-v1-native.json post /social_accounts/connect
Starts an OAuth connection flow and returns an authorize_url where the user can connect a social account.



# Create a Social Account
Source: https://docs.whop.com/api-reference/beta/social-accounts/create-a-social-account

/openapi/api-v1-native.json post /social_accounts
Creates or returns a Whop-managed Facebook page for an account.



# Delete a Social Account
Source: https://docs.whop.com/api-reference/beta/social-accounts/delete-a-social-account

/openapi/api-v1-native.json delete /social_accounts/{id}
Disconnects a social account from an account or user without deleting the underlying platform account.



# List Social Account Lead Forms
Source: https://docs.whop.com/api-reference/beta/social-accounts/list-social-account-lead-forms

/openapi/api-v1-native.json get /social_accounts/{id}/lead_forms
Lists the active lead (instant) forms that already exist on a connected Facebook page, so an ad can reuse one as its `lead_gen_form_id` instead of authoring a new form. Every active form comes back in a single response — the list is not paginated.



# List Social Account Posts
Source: https://docs.whop.com/api-reference/beta/social-accounts/list-social-account-posts

/openapi/api-v1-native.json get /social_accounts/{id}/posts
Lists the existing posts of a connected Facebook page, Instagram account, or TikTok account.



# List Social Accounts
Source: https://docs.whop.com/api-reference/beta/social-accounts/list-social-accounts

/openapi/api-v1-native.json get /social_accounts
Lists the social accounts linked to an account or user.



# Social Account
Source: https://docs.whop.com/api-reference/beta/social-accounts/social-account



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.

## Endpoints

| Endpoint                                                                                             | Request                                               |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [List Social Accounts](/api-reference/beta/social-accounts/list-social-accounts)                     | <Badge>GET</Badge> `/social_accounts`                 |
| [Create a Social Account](/api-reference/beta/social-accounts/create-a-social-account)               | <Badge>POST</Badge> `/social_accounts`                |
| [Delete a Social Account](/api-reference/beta/social-accounts/delete-a-social-account)               | <Badge>DELETE</Badge> `/social_accounts/{id}`         |
| [List Social Account Lead Forms](/api-reference/beta/social-accounts/list-social-account-lead-forms) | <Badge>GET</Badge> `/social_accounts/{id}/lead_forms` |
| [List Social Account Posts](/api-reference/beta/social-accounts/list-social-account-posts)           | <Badge>GET</Badge> `/social_accounts/{id}/posts`      |
| [Connect a Social Account](/api-reference/beta/social-accounts/connect-a-social-account)             | <Badge>POST</Badge> `/social_accounts/connect`        |

## Attributes

<Columns>
  <Column>
    <ResponseField name="id" type="string">
      Unique identifier for the social account.
    </ResponseField>

    <ResponseField name="error" type="string | null">
      Why this social account currently can't be used for advertising — a failed
      share or a Meta-side restriction. Null when the account is healthy.
    </ResponseField>

    <ResponseField name="external_id" type="string | null">
      The platform-specific ID for this social account.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The display name of the social account on the platform.
    </ResponseField>

    <ResponseField name="parent_social_account" type="object | null">
      The social account this one belongs to on the platform, such as the Facebook page that owns an Instagram account. Null when the social account stands on its own.

      <Accordion title="Properties">
        <ResponseField name="id" type="string">
          Social account ID, prefixed `sacc_`.
        </ResponseField>

        <ResponseField name="external_id" type="string | null">
          The platform-specific ID for the parent social account.
        </ResponseField>

        <ResponseField name="name" type="string | null">
          The display name of the parent social account on the platform.
        </ResponseField>

        <ResponseField name="platform" type="string">
          The platform the parent social account exists on.

          Available options: `x`, `instagram`, `youtube`, `tiktok`, `facebook`, `discord`, `telegram`
        </ResponseField>

        <ResponseField name="profile_picture_url" type="string | null">
          The URL where the profile picture of the parent social account can be
          accessed.
        </ResponseField>

        <ResponseField name="username" type="string | null">
          The username of the parent social account on the platform.
        </ResponseField>

        <ResponseField name="verified" type="boolean">
          Whether the parent social account is verified on the platform.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="platform" type="string">
      The platform the social account exists on.

      Available options: `x`, `instagram`, `youtube`, `tiktok`, `facebook`, `discord`, `telegram`
    </ResponseField>

    <ResponseField name="profile_picture_url" type="string | null">
      The URL where the profile picture of the social account can be accessed.
    </ResponseField>

    <ResponseField name="scopes" type="string[]">
      Capabilities Whop retains specific to this social account. For example, Whop
      may request the ability to run advertisements that use this social account's
      identity, reflected by the presence of `advertise` in this value.
    </ResponseField>

    <ResponseField name="url" type="string | null">
      The URL where the social account can be accessed on the platform. Null while a
      Whop-owned page is still being provisioned.
    </ResponseField>

    <ResponseField name="username" type="string | null">
      The username of the social account on the platform. Null while a Whop-owned
      page is still being provisioned.
    </ResponseField>

    <ResponseField name="verified" type="boolean">
      Whether the social account is verified on the platform.
    </ResponseField>
  </Column>

  <Column>
    <div>
      ```json SocialAccount theme={null}
      {
      	"id": "sacc_xxxxxxxxxxxx",
      	"external_id": "17841400000000000",
      	"name": "Pickaxe Pro",
      	"parent_social_account": {
      		"id": "sacc_yyyyyyyyyyyy",
      		"platform": "facebook",
      		"username": "pickaxepro",
      		"name": "Pickaxe Pro",
      		"profile_picture_url": "https://img.whop.com/sacc_yyyyyyyyyyyy.png",
      		"verified": true,
      		"external_id": "112233445566778"
      	},
      	"platform": "instagram",
      	"profile_picture_url": "https://img.whop.com/sacc_xxxxxxxxxxxx.png",
      	"scopes": ["advertise"],
      	"error": null,
      	"url": "https://instagram.com/pickaxepro",
      	"username": "pickaxepro",
      	"verified": true
      }
      ```
    </div>
  </Column>
</Columns>


# Getting started
Source: https://docs.whop.com/elements/upcoming/getting-started

Install Whop Elements and mount your first element in React, vanilla JavaScript, or Swift.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

<Tabs>
  <Tab title="Web">
    Whop Elements are hosted, themeable UI components you embed in your own site. Each element renders in an isolated frame served from Whop's CDN. You install a thin, fully typed package and the element code stays up to date on its own.

    ## Install

    <CodeGroup>
      ```bash React theme={null}
      npm install @whop/elements-react @whop/elements
      ```

      ```bash Vanilla JS theme={null}
      npm install @whop/elements
      ```
    </CodeGroup>

    ## Mount your first element

    <CodeGroup>
      ```tsx React theme={null}
      import { WhopElements, Payments, PaymentElement, AddressElement, CardElement, EmailElement } from "@whop/elements-react";
      import { loadWhop } from "@whop/elements";

      function Example() {
        return (
          <WhopElements elements={loadWhop()}>
            <Payments /* options */>
              <PaymentElement />
              <AddressElement />
              <CardElement />
              <EmailElement />
            </Payments>
          </WhopElements>
        );
      }
      ```

      ```html Vanilla JS theme={null}
      <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
      <script type="module">
        const payments = window.WhopElements().payments.create({ /* options */ });
        payments.create('payment').mount('#payments-payment');
        payments.create('address').mount('#payments-address');
        payments.create('card').mount('#payments-card');
        payments.create('email').mount('#payments-email');
      </script>
      ```
    </CodeGroup>

    Prefer npm over the script tag? `loadWhop()` injects the same hosted script and resolves the global constructor:

    ```ts theme={null}
    import { loadWhop } from "@whop/elements";

    const whop = (await loadWhop())({ locale: "en" });
    const payments = whop.payments.create({ /* options */ });
    ```

    ## Global configuration

    Everything you pass at construction applies to every element group created from that instance (a handle's own options can override per group):

    <ResponseField name="appearance" type="Appearance">
      Visual customization for every element — `theme` (light/dark + palettes), `variables` (CSS custom properties), and `classes` (per-part style declarations). The color scheme is applied before an element's first paint, so dark pages never flash light. See [Appearance](/elements/upcoming/appearance).
    </ResponseField>

    <ResponseField name="locale" type="&#x22;en&#x22; | &#x22;es&#x22; | &#x22;zh&#x22; | &#x22;nl&#x22; | &#x22;pt&#x22; | &#x22;de&#x22; | &#x22;it&#x22; | &#x22;fr&#x22; | &#x22;ja&#x22; | &#x22;pl&#x22; | &#x22;tr&#x22;">
      Locale for element UI text — one of the app's built locales; any other value falls back to the default locale. Defaults to `"en"`.
    </ResponseField>

    <ResponseField name="environment" type="&#x22;production&#x22; | &#x22;sandbox&#x22;">
      Which Whop API environment the elements talk to — `"sandbox"` targets the sandbox API (test data; no real money moves). Choosing an environment is the only way to change where the elements send what a buyer types, and both environments are Whop's own. The sandbox environment is not yet generally available. Defaults to `"production"`.
    </ResponseField>

    ```ts theme={null}
    const whop = WhopElements({
      locale: 'es',
      appearance: { theme: { appearance: 'dark', accentColor: 'blue' } }
    });
    ```

    In React, the same object rides `<WhopElements appearance={…} locale={…}>`.

    ## Next

    * [Appearance](/elements/upcoming/appearance): theming, CSS variables, and per-part restyling
    * [Payments](/elements/upcoming/payments/overview): Drives a payment collection surface against the Whop Payments API. Charge config is a plan id OR the inline currency/amount — a plan resolves client-side to the same shape, one path either way. Mount ONE of its faces — the payment element (the full method list), the fused card element, or the exploded card-fields unit — then `payments.createConfirmationToken({ billingDetails })` is the ONE confirm verb for all of them: it tokenizes the selection and mints a confirmation token your server confirms with a secret key; the payment's client\_secret then drives any pending step via `handleNextAction`.
    * [Checkout](/elements/upcoming/checkout/overview): Drives a full hosted checkout for one plan — price summary, promo codes, the currency the buyer pays in, and the whole payment collection surface (the payments elements, composed inside) — against the Whop checkout sessions API. Mount it with a `plan` and the element creates the checkout session itself; the session credential never leaves the element. Or resume a session you already hold by passing its `session` secret. The buyer pays inside the element; you get `onCompleted` with the payment id. A payment needing an off-site step (3DS, a bank page) is driven automatically — on whop.com the buyer is brought back into the restored checkout, and when you embed the element they return to the `returnUrl` you set. EVERY option here is CREATE-TIME: a checkout session is minted at mount from these values, so changing one later (`update()`, or new React props) refuses loudly instead of silently charging the booted order — mount a fresh checkout to change what is being bought.
    * [Ads](/elements/upcoming/ads/overview): An advertising account. Scope it to a company with `accountId` — the ad account underneath is assigned server-side and never surfaces here — then mount `reporting` for what the account spent and what came back, or `campaign-creator` to build a campaign.
    * [Wallet](/elements/upcoming/wallet/overview): Drives an account's money surfaces. `deposit` returns live funding rails; `send` moves money to a recipient or creates a public claim link; `withdraw` collects a payout request; `balances` holds two faces — the holdings list, and the balance block drawing value over a window; `cards` lists issued cards; and `activity` lists ledger movements. Every surface but `deposit` can use the viewer's session when no token is provided.
    * [Websites](/elements/upcoming/websites/overview): An account's websites: every site built on whop.app plus every domain the Whop Pixel reports, with traffic per domain. Mount `websites` and it lists them with visitors, page views, trend, and most-viewed pages. Reading stats is privileged, so it needs an `accessToken` — except inside Whop's own app, where the viewer's session carries the read.
  </Tab>

  <Tab title="Swift">
    Whop Elements are themeable UI components you can import in your iOS app. They ship as a single Swift SPM package. Each one is a plain SwiftUI view that fetches its own data and manages its own state, so a balance screen is a couple of views in a `VStack` instead of a networking layer and a view model. Add the package, tell the SDK how to fetch an access token, and put the elements in your view hierarchy.

    ## Install

    Add the package to your `Package.swift` (or **File → Add Package Dependencies** in Xcode):

    ```swift theme={null}
    dependencies: [
        .package(url: "https://github.com/whopio/whopsdk-elements-swift.git", from: "0.1.12")
    ]
    ```

    ## Requirements

    |           |                       |
    | --------- | --------------------- |
    | Platform  | iOS 18.0+             |
    | Toolchain | Swift 6.0             |
    | Install   | Swift Package Manager |

    ## Before you start

    You need two things:

    1. **The account the elements read.** A company's `biz_…` tag.
    2. **A backend endpoint that mints an access token** for it. Never ship a Whop API key in the app; the key mints tokens, so anyone who extracts it can read the account. Mint server-side and return only the short-lived token.

    Your backend calls [Create Access Token](https://docs.whop.com/api-reference/access-tokens/create-access-token) with the account and the scope the elements need:

    ```http theme={null}
    POST /api/v1/access_tokens
    { "company_id": "biz_xxxxxxxx", "scoped_actions": ["company:balance:read"] }
    ```

    ## Mount your first element

    A complete app. `configure` runs once at launch, and the elements render a spinner until it lands, so nothing races it:

    ```swift theme={null}
    import SwiftUI
    import WhopElements

    /// The SDK calls this again before the token expires, so fetch rather than cache.
    final class WalletTokenProvider: WhopTokenProvider {
        func getToken() async -> WhopTokenResponse {
            WhopTokenResponse(accessToken: await myBackend.whopAccessToken())
        }
    }

    @main
    struct MyApp: App {
        var body: some Scene {
            WindowGroup {
                WalletScreen()
                    .task { await WhopSDK.configure(tokenProvider: WalletTokenProvider()) }
            }
        }
    }

    struct WalletScreen: View {
        var body: some View {
            ScrollView {
                VStack(spacing: 24) {
                    BalanceElement(accountId: "biz_xxxxxxxx")
                    ListElement(accountId: "biz_xxxxxxxx")
                }
                .padding()
            }
        }
    }
    ```

    ## Authentication

    `getToken()` is your only integration point, and the SDK calls it **again before the token expires**, so return a fresh token each time rather than caching one:

    ```swift theme={null}
    final class WalletTokenProvider: WhopTokenProvider {
        func getToken() async -> WhopTokenResponse {
            // your backend, not the Whop API directly
            WhopTokenResponse(accessToken: await myBackend.whopAccessToken())
        }
    }
    ```

    Configure once, anywhere above the elements. `WhopSDK` is process-wide, so a second call is only needed when the account changes:

    ```swift theme={null}
    await WhopSDK.configure(tokenProvider: WalletTokenProvider())
    ```

    Chat and DMs authenticate the **viewer** instead of an account, through OAuth: `WhopSDK.configureWithOAuth(appId:)`.

    ## Theming

    `.whopTheme(_:)` propagates through the SwiftUI environment, so one call themes every element beneath it. Six roles, each a `WhopTint`:

    ```swift theme={null}
    ListElement(accountId: "biz_xxxxxxxx")
        .whopTheme(WhopTheme(accent: .blue, danger: .red, success: .green))
    ```

    Defaults are `accent: .blue`, `neutral: .gray`, `danger: .red`, `info: .sky`, `success: .green`, `warning: .amber`. `WhopTheme.default` is all six. Views follow the system light/dark appearance on their own.

    ## What the elements handle, and what you own

    Each view fetches its own data and renders its own loading, empty and error states, including a retry. You own **navigation**: the selection callbacks hand you a value and never push a screen.

    ```swift theme={null}
    ListElement(accountId: account) { balance in
        path.append(Route.asset(balance.symbol))   // your router, your screen
    }
    ```

    ## Troubleshooting

    | What you see                 | Why                                                                                                                                                                                                                       |
    | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `Authentication failed`      | The token is missing, expired, or is an **API key** rather than an access token. `getToken()` must return a token minted by [Create Access Token](https://docs.whop.com/api-reference/access-tokens/create-access-token). |
    | A view stays empty           | The token is valid but not scoped for that read. Balances need `company:balance:read`.                                                                                                                                    |
    | `Couldn't load this account` | The `accountId` is not one this token can read.                                                                                                                                                                           |
    | A chart with no line         | Balance history is not available for personal (`user_…`) accounts yet, company accounts only.                                                                                                                             |

    ## Available on iOS

    The wallet views, each with a live simulator on its page:

    * [`BalanceElement`](/elements/upcoming/wallet/balances-balance#swift): the total balance, its trend, and the range picker
    * [`ListElement`](/elements/upcoming/wallet/balances-list#swift): the holdings list
    * [`ActivityElement`](/elements/upcoming/wallet/activity#swift): the ledger activity feed

    `WhopChatView` and `WhopDMsListView` ship in the same package for viewer-authenticated chat. See the [README](https://github.com/whopio/whopsdk-elements-swift).
  </Tab>
</Tabs>


# Embed checkout
Source: https://docs.whop.com/payments/checkout-embed

Learn how to embed Whop's checkout flow on your website

Embedded checkout allows you to embed Whop's checkout flow on your own website. This allows you to offer your customers a seamless checkout experience without leaving your website.

<Card title="Try the checkout playground" icon="sliders" href="https://whop.com/checkout-playground">
  Customize colors, radius, and fields in real time, then copy the generated embed code.
</Card>

<iframe title="YouTube video player" />

## React setup

### Step 1: Install the package

```bash theme={null}
npm install @whop/checkout
```

### Step 2: Add the checkout element

```tsx theme={null}
import { WhopCheckoutEmbed } from "@whop/checkout/react";

export default function Home() {
	return (
		<WhopCheckoutEmbed
			planId="plan_XXXXXXXXX"
			returnUrl="https://yoursite.com/checkout/complete"
		/>
	);
}
```

This component will mount an iframe with the Whop checkout embed.

The `returnUrl` is required to handle redirects from external payment providers. When redirected, check the `status` query parameter:

* **success**: The payment succeeded. Use the receipt information to render a success page.
* **error**: The payment failed or was canceled. Remount the checkout so your customer can try again.

<Tip>
  Keep that Plan ID handy. You'll need to paste it into your website code, so
  save it somewhere you can find it.
</Tip>

### Step 3: **(optional)** Configure - Programmatic controls

To get access to the controls of the checkout embed, you can use the `ref` prop.

```tsx theme={null}
const ref = useCheckoutEmbedControls();

return <WhopCheckoutEmbed ref={ref} planId="plan_XXXXXXXXX" />;
```

#### **`submit`**

To submit checkout programmatically, you can use the `submit` method on the checkout element.

```tsx theme={null}
ref.current?.submit();
```

#### **`getEmail`**

To get the email of the user who is checking out, you can use the `getEmail` method on the checkout element.

```tsx theme={null}
const email = await ref.current?.getEmail();
console.log(email);
```

#### **`setEmail`**

To set the email of the user who is checking out, you can use the `setEmail` method on the checkout element.

```tsx theme={null}
try {
	await ref.current?.setEmail("example@domain.com");
} catch (error) {
	console.error(error);
}
```

#### **`getAddress`**

To get the address of the user who is checking out, you can use the `getAddress` method on the checkout element.

```tsx theme={null}
const address = await ref.current?.getAddress();
console.log(address);
```

#### **`setAddress`**

To set the address of the user who is checking out, you can use the `setAddress` method on the checkout element.

<Note>
  This method will only work if the address form is hidden. You can hide the
  address form by setting the `hideAddressForm` prop to `true`.
</Note>

```tsx theme={null}
try {
	await ref.current?.setAddress({
		name: "John Doe",
		country: "US",
		line1: "123 Main St",
		city: "Any Town",
		state: "CA",
		postalCode: "12345",
	});
} catch (error) {
	console.error(error);
}
```

### Step 4: **(optional)** Configure - Available properties

#### **`planId`**

**Required** - The plan id you want to checkout.

#### **`theme`**

**Optional** - The theme you want to use for the checkout.

Possible values are `light`, `dark` or `system`.

#### **`themeOptions`**

**Optional** - Fine-grained theme options for the checkout embed.

**`themeOptions.backgroundColor`** - A hex color to match the embed background to your site. The embed automatically picks light or dark text and tints its panels and inputs to fit the color, overriding `theme`.

```tsx theme={null}
<WhopCheckoutEmbed
	themeOptions={{ backgroundColor: "#09090b" }}
	planId="plan_XXXXXXXXX"
/>
```

**`themeOptions.accentColor`** - The accent color used for the submit button, focus rings, and links. Accepts any hex color — the embed derives the full accent palette from it, including a legible button text color. Named palette values like `green` or `blue` are also supported (the full list is under `data-whop-checkout-theme-accent-color`).

```tsx theme={null}
<WhopCheckoutEmbed
	themeOptions={{ accentColor: "#7c3aed" }}
	planId="plan_XXXXXXXXX"
/>
```

**`themeOptions.highContrast`** - Set to `true` to render the submit button with higher contrast against the checkout background.

```tsx theme={null}
<WhopCheckoutEmbed
	themeOptions={{ highContrast: true }}
	planId="plan_XXXXXXXXX"
/>
```

**`themeOptions.borderRadius`** - The corner radius for the embed, in pixels. Inputs and containers use the value as-is; buttons scale proportionally (1.5×). Pass `0` for square corners.

```tsx theme={null}
<WhopCheckoutEmbed
	themeOptions={{ borderRadius: 8 }}
	planId="plan_XXXXXXXXX"
/>
```

#### **`sessionId`**

**Optional** - The session id to use for the checkout.

This can be used to attach metadata to a checkout by first creating a session through the API and then passing the session id to the checkout element.

#### **`returnUrl`**

**Optional** - The URL to redirect the user to after checkout completes.

```tsx theme={null}
<WhopCheckoutEmbed
	returnUrl="https://yoursite.com/checkout/complete"
	planId="plan_XXXXXXXXX"
/>
```

#### **`affiliateCode`**

**Optional** - The affiliate code to use for the checkout.

```tsx theme={null}
<WhopCheckoutEmbed affiliateCode="tristan" planId="plan_XXXXXXXXX" />
```

#### **`hidePrice`**

**Optional** - Turn on to hide the price in the embedded checkout form.

Defaults to `false`

#### **`hideTermsAndConditions`**

**Optional** - Set to `true` to hide the terms and conditions in the embedded checkout form.

Defaults to `false`

#### **`skipRedirect`**

**Optional** - Set to `true` to skip the final redirect and keep the top frame loaded.

Defaults to `false`

#### **`adaptivePricing`**

**Optional** - Set to `true` to enable adaptive pricing on the embedded checkout. When enabled and supported for the plan, prices are presented in the buyer's local currency.

Defaults to `false` — embedded checkouts must opt in explicitly. Buyers will be charged in the plan's base currency unless this is set.

See [Listening for currency changes](#listening-for-currency-changes) to react to currency events from the embed or switch currencies programmatically.

```tsx theme={null}
<WhopCheckoutEmbed adaptivePricing planId="plan_XXXXXXXXX" />
```

#### **`collectPhoneNumbers`**

**Optional** - Set to `true` to require a phone number, `"optional"` to show a phone number field that buyers may leave blank, or `false` to disable collection. When omitted, the plan's feature setting is used.

```tsx theme={null}
<WhopCheckoutEmbed collectPhoneNumbers="optional" planId="plan_XXXXXXXXX" />
```

#### **`collectShipping`**

**Optional** - Set to `true` to collect a shipping address during checkout, even when the plan does not require one. Works in both the regular embedded checkout and the [one click checkout button](/payments/one-click-checkout-button) (Apple Pay; Google Pay shipping support is pending). To hide the shipping address instead, use `shipping.address.hidden`.

```tsx theme={null}
<WhopCheckoutEmbed collectShipping planId="plan_XXXXXXXXX" />
```

#### **`locale`**

**Optional** - The language the checkout renders in, as a locale code (e.g. `"es"`, `"fr"`, `"pt"`). When omitted, the checkout falls back to the buyer's browser language preference.

```tsx theme={null}
<WhopCheckoutEmbed locale="es" planId="plan_XXXXXXXXX" />
```

#### **`onComplete`**

**Optional** - A callback function that will be called when the checkout is complete.

<Note>This option will set `skipRedirect` to `true`</Note>

```tsx theme={null}
<WhopCheckoutEmbed
	onComplete={(planId, receiptId) => {
		console.log(planId, receiptId);
	}}
	planId="plan_XXXXXXXXX"
/>
```

The third argument carries everything the completed checkout resolved to. In
[setup mode](/developer/guides/save-payment-methods) it includes
`payment_method_id` — the saved payment method, ready to charge later without
waiting for the `setup_intent.succeeded` webhook.

```tsx theme={null}
<WhopCheckoutEmbed
	onComplete={(sessionId, setupIntentId, result) => {
		console.log(result.payment_method_id); // payt_XXXXXXXXX
	}}
	sessionId="ch_XXXXXXXXX"
/>
```

#### **`utm`**

**Optional** - The UTM parameters to add to the checkout URL.

**Note** - The keys must start with `utm_`

```tsx theme={null}
<WhopCheckoutEmbed
	planId="plan_XXXXXXXXX"
	utm={{ utm_campaign: "ad_XXXXXXX" }}
/>
```

#### **`fallback`**

**Optional** - The fallback content to show while the checkout is loading.

```tsx theme={null}
<WhopCheckoutEmbed fallback={<>loading...</>} planId="plan_XXXXXXXXX" />
```

#### **`prefill`**

**Optional** - The prefill options to apply to the checkout embed.

Used to prefill the email or address in the embedded checkout form.
This setting can be helpful when integrating the embed into a funnel that collects the email prior to payment already.

```tsx theme={null}
<WhopCheckoutEmbed
  prefill={{ email: "example@domain.com" }}
  planId="plan_XXXXXXXXX"
/>
<WhopCheckoutEmbed
  prefill={{ address: {
    name: "John Doe",
    country: "US",
    line1: "123 Main St",
    city: "Any Town",
    state: "CA",
    postalCode: "12345",
  } }}
  planId="plan_XXXXXXXXX"
/>
```

#### **`hideEmail`**

**Optional** - Set to `true` to hide the email input in the embedded checkout form. Make sure to display the users email in the parent page when setting this attribute.

Defaults to `false`

<Note>
  Use this in conjunction with the `prefill` attribute or the `setEmail` method
  to control the email input.
</Note>

```tsx theme={null}
<WhopCheckoutEmbed hideEmail planId="plan_XXXXXXXXX" />
```

#### **`disableEmail`**

**Optional** - Set to `true` to disable the email input in the embedded checkout form.

Defaults to `false`

<Note>
  Use this in conjunction with the `prefill` attribute or the `setEmail` method
  to control the email input.
</Note>

```tsx theme={null}
<WhopCheckoutEmbed disableEmail planId="plan_XXXXXXXXX" />
```

#### **`hideAddressForm`**

**Optional** - Set to `true` to hide the address form in the embedded checkout form.

Defaults to `false`

<Note>
  Use this in conjunction with the `setAddress` method to control the address
  input.
</Note>

```tsx theme={null}
<WhopCheckoutEmbed hideAddressForm planId="plan_XXXXXXXXX" />
```

#### **`setupFutureUsage`**

**Optional** - The setup future usage to use for the checkout. When using the `chargeUser` API you need to set this to `off_session`. This will filter out payment methods that are not supported with that API.

```tsx theme={null}
<WhopCheckoutEmbed setupFutureUsage="off_session" planId="plan_XXXXXXXXX" />
```

#### **`onStateChange`**

**Optional** - A callback function that will be called when the checkout state changes.

This can be used when programmatically submitting the checkout embed.

Possible values are `loading`, `ready`, `disabled`.

```tsx theme={null}
<WhopCheckoutEmbed
	onStateChange={(state) => {
		console.log(state);
	}}
	planId="plan_XXXXXXXXX"
/>
```

#### **`environment`**

**Optional** - The environment to use for the checkout.

Possible values are `production` or `sandbox`.

Defaults to `production`

<Note>
  When using `sandbox`, make sure to use a sandbox plan ID. Sandbox plans can be
  created in the [sandbox dashboard](https://sandbox.whop.com/dashboard).
</Note>

```tsx theme={null}
<WhopCheckoutEmbed environment="sandbox" planId="plan_XXXXXXXXX" />
```

#### **`onAddressValidationError`**

**Optional** - A callback function that will be called when the address validation error occurs.

<Note>
  This method will only work if the address form is hidden. You can hide the
  address form by setting the `hideAddressForm` prop to `true`.
</Note>

```tsx theme={null}
<WhopCheckoutEmbed
	hideAddressForm
	onAddressValidationError={(error) => {
		console.log(error);
	}}
	planId="plan_XXXXXXXXX"
/>
```

#### **`onPaymentError`**

**Optional** - A callback function that will be called when checkout payment processing fails.

The callback receives an error object with a human readable `message` and an optional machine readable `code`. It fires for declines on submit as well as failures detected while the payment is processing, for example after 3D Secure or a redirect to an external payment provider.

```tsx theme={null}
<WhopCheckoutEmbed
	onPaymentError={(error) => {
		console.log(error.message, error.code);
	}}
	planId="plan_XXXXXXXXX"
/>
```

#### **`onPromoCodeChanged`**

**Optional** - A callback function that will be called when the promo code changes.

The callback receives the full promo code object when a code is applied, or `null` when the code is removed.

```tsx theme={null}
<WhopCheckoutEmbed
	onPromoCodeChanged={(promoCode) => {
		if (promoCode) {
			console.log(
				"Promo applied:",
				promoCode.code,
				promoCode.type,
				promoCode.amount,
			);
		} else {
			console.log("Promo removed");
		}
	}}
	planId="plan_XXXXXXXXX"
/>
```

#### **`styles`**

**Optional** - Customize the padding of the checkout embed container.

The `styles` prop accepts a `container` object with the following properties:

| Property        | Description                          | Default |
| --------------- | ------------------------------------ | ------- |
| `paddingTop`    | Top padding in pixels                | `32`    |
| `paddingBottom` | Bottom padding in pixels             | `32`    |
| `paddingLeft`   | Left padding in pixels               | `32`    |
| `paddingRight`  | Right padding in pixels              | `32`    |
| `paddingY`      | Shorthand for top and bottom padding | `32`    |
| `paddingX`      | Shorthand for left and right padding | `32`    |

Individual properties take precedence over their shorthand equivalents.

```tsx theme={null}
<WhopCheckoutEmbed
	planId="plan_XXXXXXXXX"
	styles={{ container: { paddingX: 0 } }}
/>
```

```tsx theme={null}
<WhopCheckoutEmbed
	planId="plan_XXXXXXXXX"
	styles={{
		container: {
			paddingLeft: 16,
			paddingRight: 16,
			paddingTop: 0,
			paddingBottom: 0,
		},
	}}
/>
```

### Full example

```tsx theme={null}
import { WhopCheckoutEmbed } from "@whop/checkout/react";

export default function Home() {
	return (
		<WhopCheckoutEmbed
			fallback={<>loading...</>}
			planId="plan_XXXXXXXXX"
			sessionId="ch_XXXXXXXXX"
			returnUrl="https://yoursite.com/checkout/complete"
			theme="light"
			hidePrice={false}
		/>
	);
}
```

## Other websites

### Step 1: Add the script tag

To embed checkout, you need to add the following script tag into the `<head>` of your page:

```md theme={null}
<script
  async
  defer
  src="https://js.whop.com/static/checkout/loader.js"
></script>
```

### Step 2: Add the checkout element

To create a checkout element, you need to include the following attributes on an element in your page:

```md theme={null}
<div
  data-whop-checkout-plan-id="plan_XXXXXXXXX"
  data-whop-checkout-return-url="https://yoursite.com/checkout/complete"
></div>
```

This will mount an iframe inside of the element with the plan id you provided.

The `data-whop-checkout-return-url` is required to handle redirects from external payment providers. When redirected, check the `status` query parameter:

* **success**: The payment succeeded. Use the receipt information to render a success page.
* **error**: The payment failed or was canceled. Remount the checkout so your customer can try again.

### Step 3: **(optional)** Configure - Programmatic controls

First, attach an `id` to the checkout container:

```md theme={null}
<div id="whop-embedded-checkout" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`submit`**

To submit checkout programmatically, you can use the `submit` method on the checkout element.

```js theme={null}
wco.submit("whop-embedded-checkout");
```

#### **`getEmail`**

To get the email of the user who is checking out, you can use the `getEmail` method on the checkout element.

```js theme={null}
const email = await wco.getEmail("whop-embedded-checkout");
console.log(email);
```

#### **`setEmail`**

To set the email of the user who is checking out, you can use the `setEmail` method on the checkout element.

```js theme={null}
wco.setEmail("whop-embedded-checkout", "example@domain.com");
```

#### **`getAddress`**

To get the address of the user who is checking out, you can use the `getAddress` method on the checkout element.

```js theme={null}
const address = await wco.getAddress("whop-embedded-checkout");
console.log(address);
```

#### **`setAddress`**

To set the address of the user who is checking out, you can use the `setAddress` method on the checkout element.

<Note>
  This method will only work if the address form is hidden. You can hide the
  address form by setting the `data-whop-checkout-hide-address` prop to `true`.
</Note>

```js theme={null}
try {
	await wco.setAddress("whop-embedded-checkout", {
		name: "John Doe",
		country: "US",
		line1: "123 Main St",
		city: "Any Town",
		state: "CA",
		postalCode: "12345",
	});
} catch (error) {
	console.error(error);
}
```

### Step 4: **(optional)** Configure - Available attributes

#### **`data-whop-checkout-plan-id`**

**Required** - The plan id you want to checkout.

> To get your plan id, you need to first create a plan in the **Manage Pricing** section on your whop page.

#### **`data-whop-checkout-theme`**

**Optional** - The theme you want to use for the checkout.

Possible values are `light`, `dark` or `system`.

```md theme={null}
<div data-whop-checkout-theme="light" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-theme-accent-color`**

**Optional** - The accent color to apply to the checkout embed.

Accepts any hex color like `#7c3aed` — the embed derives the full accent palette from it, including a legible button text color. The following named palettes are also supported:

* `tomato`
* `red`
* `ruby`
* `crimson`
* `pink`
* `plum`
* `purple`
* `violet`
* `iris`
* `cyan`
* `teal`
* `jade`
* `green`
* `grass`
* `brown`
* `blue`
* `orange`
* `indigo`
* `sky`
* `mint`
* `yellow`
* `amber`
* `lime`
* `lemon`
* `magenta`
* `gold`
* `bronze`
* `gray`

```md theme={null}
<div data-whop-checkout-theme-accent-color="green" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-theme-background-color`**

**Optional** - The background color to apply to the checkout embed.

Accepts a hex color like `#09090b`. The embed automatically picks light or dark text and tints its panels and inputs to fit the color, overriding `data-whop-checkout-theme`.

```md theme={null}
<div data-whop-checkout-theme-background-color="#09090b" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-theme-border-radius`**

**Optional** - The corner radius to apply to the checkout embed, in pixels.

Inputs and containers use the value as-is; buttons scale proportionally (1.5×). Pass `0` for square corners.

```md theme={null}
<div data-whop-checkout-theme-border-radius="8" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-session`**

**Optional** - The session id to use for the checkout.

This can be used to attach metadata to a checkout by first creating a session through the API and then passing the session id to the checkout element.

```md theme={null}
<div data-whop-checkout-session="ch_XXXXXXXXX" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-return-url`**

**Optional** - The URL to redirect the user to after checkout completes.

```md theme={null}
<div data-whop-checkout-return-url="https://yoursite.com/checkout/complete" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-affiliate-code`**

**Optional** - The affiliate code to use for the checkout.

```md theme={null}
<div data-whop-checkout-affiliate-code="tristan" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-hide-price`**

**Optional** - Set to `true` to hide the price in the embedded checkout form.

Defaults to `false`

```md theme={null}
<div data-whop-checkout-hide-price="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-hide-submit-button`**

**Optional** - Set to `true` to hide the submit button in the embedded checkout form.

Defaults to `false`

<Note>
  When using this Option, you will need to [programmatically submit](#submit)
  the checkout form.
</Note>

```md theme={null}
<div data-whop-checkout-hide-submit-button="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-hide-tos`**

**Optional** - Set to `true` to hide the terms and conditions in the embedded checkout form.

Defaults to `false`

```md theme={null}
<div data-whop-checkout-hide-tos="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-skip-redirect`**

**Optional** - Set to `true` to skip the final redirect and keep the top frame loaded.

Defaults to `false`

```md theme={null}
<div data-whop-checkout-skip-redirect="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-adaptive-pricing`**

**Optional** - Set to `true` to enable adaptive pricing on the embedded checkout. When enabled and supported for the plan, prices are presented in the buyer's local currency.

Defaults to `false` — embedded checkouts must opt in explicitly. Buyers will be charged in the plan's base currency unless this is set.

See [Listening for currency changes](#listening-for-currency-changes) to react to currency events from the embed or switch currencies programmatically.

```md theme={null}
<div data-whop-checkout-adaptive-pricing="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-collect-phone-numbers`**

**Optional** - Set to `true` to require a phone number, `optional` to show a phone number field that buyers may leave blank, or `false` to disable collection. When omitted, the plan's feature setting is used.

```md theme={null}
<div data-whop-checkout-collect-phone-numbers="optional" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-collect-shipping`**

**Optional** - Set to `true` to collect a shipping address during checkout, even when the plan does not require one. To hide the shipping address instead, use `shipping.address.hidden`.

```md theme={null}
<div data-whop-checkout-collect-shipping="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-locale`**

**Optional** - The language the checkout renders in, as a locale code (e.g. `"es"`, `"fr"`, `"pt"`). When omitted, the checkout falls back to the buyer's browser language preference.

```md theme={null}
<div data-whop-checkout-locale="es" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-on-complete`**

**Optional** - The callback to call when the checkout succeeds

<Note>This option will set `data-whop-checkout-skip-redirect` to `true`</Note>

```html theme={null}
<script>
	window.onCheckoutComplete = (planId, receiptId) => {
		console.log(planId, receiptId);
	};
</script>

<div
	data-whop-checkout-on-complete="onCheckoutComplete"
	data-whop-checkout-plan-id="plan_XXXXXXXXX"
></div>
```

#### **`data-whop-checkout-on-state-change`**

**Optional** - The callback to call when state of the checkout changes

This can be used when programmatically submitting the checkout embed.

Possible values are `loading`, `ready`, `disabled`.

```html theme={null}
<script>
	window.onCheckoutStateChange = (state) => {
		console.log(state);
	};
</script>

<div
	data-whop-checkout-on-state-change="onCheckoutStateChange"
	data-whop-checkout-plan-id="plan_XXXXXXXXX"
></div>
```

#### **`data-whop-checkout-skip-utm`**

By default any utm params from the main page will be forwarded to the checkout embed.

**Optional** - Set to `true` to prevent the automatic forwarding of utm parameters

Defaults to `false`

#### **`data-whop-checkout-prefill-*`**

Used to prefill the email or address in the embedded checkout form. This setting can be helpful when integrating the embed into a funnel that collects the email prior to payment already.

```md theme={null}
<div data-whop-checkout-prefill-email="example@domain.com" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>

<div 
	data-whop-checkout-prefill-name="John Doe"
	data-whop-checkout-prefill-address-country="US"
	data-whop-checkout-prefill-address-line1="123 Main St"
	data-whop-checkout-prefill-address-line2=""
	data-whop-checkout-prefill-address-city="Any Town"
	data-whop-checkout-prefill-address-state="CA"
	data-whop-checkout-prefill-address-postal-code="12345"
	data-whop-checkout-plan-id="plan_XXXXXXXXX"
></div>

<div data-whop-checkout-prefill-address-name="John Doe" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-hide-email`**

**Optional** - Set to `true` to hide the email input in the embedded checkout form. Make sure to display the users email in the parent page when setting this attribute.

Defaults to `false`

<Note>
  Use this in conjunction with the `data-whop-checkout-prefill-email` attribute
  or the `setEmail` method to control the email input.
</Note>

```md theme={null}
<div data-whop-checkout-hide-email="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-disable-email`**

**Optional** - Set to `true` to disable the email input in the embedded checkout form.

Defaults to `false`

<Note>
  Use this in conjunction with the `data-whop-checkout-prefill-email` attribute
  or the `setEmail` method to control the email input.
</Note>

```md theme={null}
<div data-whop-checkout-disable-email="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-hide-address`**

**Optional** - Set to `true` to hide the address form in the embedded checkout form.

Defaults to `false`

<Note>
  This method will only work if the address form is hidden. You can hide the
  address form by setting the `data-whop-checkout-hide-address` prop to `true`.
</Note>

```md theme={null}
<div data-whop-checkout-hide-address="true" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-setup-future-usage`**

**Optional** - The setup future usage to use for the checkout. When using the `chargeUser` API you need to set this to `off_session`. This will filter out payment methods that are not supported with that API.

```md theme={null}
<div data-whop-checkout-setup-future-usage="off_session" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-environment`**

**Optional** - The environment to use for the checkout.

Possible values are `production` or `sandbox`.

Defaults to `production`

<Note>
  When using `sandbox`, make sure to use a sandbox plan ID. Sandbox plans can be
  created in the [sandbox dashboard](https://sandbox.whop.com/dashboard).
</Note>

```md theme={null}
<div data-whop-checkout-environment="sandbox" data-whop-checkout-plan-id="plan_XXXXXXXXX"></div>
```

#### **`data-whop-checkout-on-address-validation-error`**

**Optional** - The callback to call when the address validation error occurs.

<Note>
  This method will only work if the address form is hidden. You can hide the
  address form by setting the `data-whop-checkout-hide-address` prop to `true`.
</Note>

```html theme={null}
<script>
	window.onAddressValidationError = (error) => {
		console.log(error);
	};
</script>

<div
	data-whop-checkout-on-address-validation-error="onAddressValidationError"
	data-whop-checkout-plan-id="plan_XXXXXXXXX"
></div>
```

#### **`data-whop-checkout-on-payment-error`**

**Optional** - The callback to call when checkout payment processing fails.

The callback receives an error object with a human readable `message` and an optional machine readable `code`. It fires for declines on submit as well as failures detected while the payment is processing, for example after 3D Secure or a redirect to an external payment provider.

```html theme={null}
<script>
	window.onPaymentError = (error) => {
		console.log(error.message, error.code);
	};
</script>

<div
	data-whop-checkout-on-payment-error="onPaymentError"
	data-whop-checkout-plan-id="plan_XXXXXXXXX"
></div>
```

#### **`data-whop-checkout-on-promo-code-changed`**

**Optional** - The callback to call when the promo code changes.

The callback receives the full promo code object when a code is applied, or `null` when the code is removed.

```html theme={null}
<script>
	window.onPromoCodeChanged = (promoCode) => {
		if (promoCode) {
			console.log(
				"Promo applied:",
				promoCode.code,
				promoCode.type,
				promoCode.amount,
			);
		} else {
			console.log("Promo removed");
		}
	};
</script>

<div
	data-whop-checkout-on-promo-code-changed="onPromoCodeChanged"
	data-whop-checkout-plan-id="plan_XXXXXXXXX"
></div>
```

#### **`data-whop-checkout-style-*`**

**Optional** - Customize the padding of the checkout embed container.

The attribute pattern is `data-whop-checkout-style-container-{property}` where `{property}` is a kebab-case padding property.

| Attribute                                           | Description                          | Default |
| --------------------------------------------------- | ------------------------------------ | ------- |
| `data-whop-checkout-style-container-padding-top`    | Top padding in pixels                | `32`    |
| `data-whop-checkout-style-container-padding-bottom` | Bottom padding in pixels             | `32`    |
| `data-whop-checkout-style-container-padding-left`   | Left padding in pixels               | `32`    |
| `data-whop-checkout-style-container-padding-right`  | Right padding in pixels              | `32`    |
| `data-whop-checkout-style-container-padding-y`      | Shorthand for top and bottom padding | `32`    |
| `data-whop-checkout-style-container-padding-x`      | Shorthand for left and right padding | `32`    |

Individual properties take precedence over their shorthand equivalents.

```md theme={null}
<div
  data-whop-checkout-plan-id="plan_XXXXXXXXX"
  data-whop-checkout-style-container-padding-x="0"
></div>
```

```md theme={null}
<div
  data-whop-checkout-plan-id="plan_XXXXXXXXX"
  data-whop-checkout-style-container-padding-left="16"
  data-whop-checkout-style-container-padding-right="16"
  data-whop-checkout-style-container-padding-top="0"
  data-whop-checkout-style-container-padding-bottom="0"
></div>
```

### Full example

```md theme={null}
<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width">
		<script
			async
			defer
  			src="https://js.whop.com/static/checkout/loader.js"
		></script>
		<title>Whop embedded checkout example</title>
		<style>
			div {
				box-sizing: border-box;
			}
			body {
				margin: 0
			}
		</style>
	</head>
	<body>
		<div
			data-whop-checkout-plan-id="plan_XXXXXXXXX"
			data-whop-checkout-session="ch_XXXXXXXXX"
			data-whop-checkout-return-url="https://yoursite.com/checkout/complete"
			data-whop-checkout-theme="light"
			data-whop-checkout-hide-price="false"
			style="height: fit-content; overflow: hidden; max-width: 50%;"
		></div>
	</body>
</html>
```

## Listening for currency changes

When [`adaptivePricing`](#adaptivepricing) is enabled, the embedded checkout exposes the available and active currencies through callbacks, a programmatic getter, and a setter for switching currencies.

The currency snapshot has the following shape:

| Field               | Type             | Description                                                                                                                    |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `base_currency`     | `string`         | The plan's base currency (ISO 4217).                                                                                           |
| `optional_currency` | `string \| null` | The buyer's local currency when different from `base_currency` and supported. `null` when only the base currency is available. |
| `current_currency`  | `string`         | The currency currently displayed.                                                                                              |
| `exchange_rate`     | `number \| null` | Rate from `base_currency` to `current_currency`. `null` when no conversion is active.                                          |

### React

Use the `onCurrenciesAvailable` and `onCurrencyChanged` props to react to currency events, or read the latest snapshot from the embed's ref via `getAvailableCurrencies()`. Send the buyer to a different supported currency with `setDisplayCurrency()`.

```tsx theme={null}
import { useRef } from "react";
import { WhopCheckoutEmbed, type WhopCheckoutEmbedControls } from "@whop/react/checkout";

function Checkout() {
	const ref = useRef<WhopCheckoutEmbedControls>(null);

	return (
		<>
			<WhopCheckoutEmbed
				ref={ref}
				adaptivePricing
				planId="plan_XXXXXXXXX"
				onCurrenciesAvailable={(snapshot) => console.log(snapshot)}
				onCurrencyChanged={({ currency, exchange_rate }) =>
					console.log(currency, exchange_rate)
				}
			/>
			<button
				onClick={async () => {
					const snapshot = ref.current?.getAvailableCurrencies();
					if (snapshot?.optional_currency) {
						await ref.current?.setDisplayCurrency(snapshot.optional_currency);
					}
				}}
			>
				Use local currency
			</button>
		</>
	);
}
```

### HTML / vanilla JS

Set callbacks via data attributes pointing to functions on `window`. Use `wco.getAvailableCurrencies(identifier)` to read the latest snapshot and `wco.setDisplayCurrency(identifier, currency)` to switch.

```html theme={null}
<script>
	window.onCurrenciesAvailable = (snapshot) => console.log(snapshot);
	window.onCurrencyChanged = ({ currency, exchange_rate }) =>
		console.log(currency, exchange_rate);
</script>

<div
	id="whop-embedded-checkout"
	data-whop-checkout-plan-id="plan_XXXXXXXXX"
	data-whop-checkout-adaptive-pricing="true"
	data-whop-checkout-on-currencies-available="onCurrenciesAvailable"
	data-whop-checkout-on-currency-changed="onCurrencyChanged"
></div>

<script>
	document.querySelector("#switch").addEventListener("click", async () => {
		const snapshot = wco.getAvailableCurrencies("whop-embedded-checkout");
		if (snapshot?.optional_currency) {
			await wco.setDisplayCurrency(
				"whop-embedded-checkout",
				snapshot.optional_currency,
			);
		}
	});
</script>
```

<Note>
  `setDisplayCurrency` only accepts currencies present in the most recent
  `onCurrenciesAvailable` snapshot — any other currency is rejected with
  `WhopCheckoutSetDisplayCurrencyError`.
</Note>

## Apple Pay

Apple Pay allows customers to pay using their Apple Wallet, providing a seamless checkout experience on Safari and iOS devices. To enable Apple Pay on your embedded checkout, you need to verify ownership of your domain.

<Card title="Set up Apple Pay" icon="apple" href="/payments/apple-pay">
  Learn how to verify your domain and enable Apple Pay for embedded checkout
</Card>

<Note>
  When using the `hideSubmitButton` option in React, `@whop/checkout@0.0.43` or
  later is required for Apple Pay to appear in the embed.
</Note>

## Platform-specific guides

<CardGroup>
  <Card title="Framer" icon="browser" href="/third-party-integrations/embedded-checkouts/framer-checkout">
    Embed checkout on Framer with Apple Pay support
  </Card>

  <Card title="ClickFunnels" icon="browser" href="/third-party-integrations/embedded-checkouts/clickfunnels-checkout">
    Embed checkout on ClickFunnels pages
  </Card>

  <Card title="GoHighLevel" icon="browser" href="/third-party-integrations/embedded-checkouts/gohighlevel-checkout">
    Embed checkout on GoHighLevel funnels
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Why is my checkout not loading?">
    Make sure you've correctly replaced `plan_XXXXXXXXX` or `PLAN_ID_HERE` in the code snippets with your actual Plan ID from the Whop dashboard. Also verify that the script tag is properly loaded in the `<head>` section if using HTML/JS.
  </Accordion>

  <Accordion title="Where do I find my Plan ID?">
    Go to your **Dashboard** > **Checkout links** > Click the **three dots (⋮)** on your pricing option > Hover over **Details** > Click the ID (starts with `plan_`) to copy it.
  </Accordion>

  <Accordion title="Can I embed multiple checkouts on the same page?">
    Yes, you can add multiple checkout embeds with different Plan IDs. Each embed operates independently.
  </Accordion>

  <Accordion title="How do I change the checkout theme?">
    For React: add `theme="dark"` or `theme="light"` as a property. For HTML: add `data-whop-checkout-theme="dark"` to your div element.
  </Accordion>

  <Accordion title="Can I hide the price in the embedded checkout?">
    Yes, add `hidePrice={true}` in React or `data-whop-checkout-hide-price="true"` in HTML to hide the price display.
  </Accordion>

  <Accordion title="What happens after a customer completes checkout?">
    By default, customers are redirected to your whop. You can customize this by setting a custom redirect URL or skipping the redirect entirely.
  </Accordion>

  <Accordion title="How do I prevent the redirect after checkout?">
    Use `skipRedirect={true}` in React or `data-whop-checkout-skip-redirect="true"` in HTML to keep users on the same page.
  </Accordion>

  <Accordion title="Is the embedded checkout mobile-responsive?">
    Yes, the checkout automatically adapts to different screen sizes and devices.
  </Accordion>

  <Accordion title="Can I customize the checkout's appearance with CSS?">
    You can style the wrapper using the `.whop-checkout-wrapper iframe` CSS class, but the checkout content itself cannot be modified for security reasons.
  </Accordion>

  <Accordion title="Can I pre-fill customer information?">
    Yes, use `prefill={{ email: "customer@example.com" }}` in React or `data-whop-checkout-prefill-email="customer@example.com"` in HTML.
  </Accordion>
</AccordionGroup>


# One click checkout button
Source: https://docs.whop.com/payments/one-click-checkout-button

Drop a single Apple Pay, Google Pay, or Whop Pay button on your site that opens Whop checkout in a dialog

## Try it (its real) 👇

<div>
  <div />

  <OneClickCheckoutDemo />
</div>

## React setup

### Step 1: Install the package

```bash theme={null}
npm install @whop/checkout
```

### Step 2: Add the button

```tsx theme={null}
import { WhopExpressCheckoutButton } from "@whop/checkout/react";

export default function PricingCard() {
	return (
		<WhopExpressCheckoutButton
			planId="plan_XXXXXXXXX"
			returnUrl="https://yoursite.com/checkout/complete"
		/>
	);
}
```

The `returnUrl` is **required** on the one click checkout button (unlike the regular embedded checkout, where it's optional). Payments started here may complete inside the Whop Pay dialog via a redirect-based payment method (3DS, Sezzle, etc.) and the user needs somewhere to land that closes the loop on your page.

When the customer is redirected back, check the `status` query parameter:

* **success**: The payment succeeded.
* **error**: The payment failed or was canceled.

On success, the redirect also includes:

* **`payment_id`** — the id of the [payment](/api-reference/payments/payment). Use it to look up the payment on your backend or render a confirmation.
* **`setup_intent_id`** — set instead of `payment_id` when checkout didn't charge anything (e.g. saving a card for future use).
* **`state_id`** — the checkout session id.

### Step 3: **(optional)** Configure - Available properties

#### **`planId`**

**Required (or `checkoutConfigurationId`)** - The plan id you want to checkout. Provide either this or `checkoutConfigurationId`, not both.

#### **`checkoutConfigurationId`**

**Required (or `planId`)** - An API-created checkout configuration id. Use this to mount the button against a pre-configured checkout (e.g. with attached metadata, a pre-applied promo, or a multi-line cart) instead of creating a new session at mount time. Provide either this or `planId`, not both.

#### **`returnUrl`**

**Required** - The URL to return to after payment authorization flows.

#### **`methods`**

**Optional** - Which methods the button is allowed to render, in priority order. Defaults to `["apple-pay", "google-pay", "whop-pay"]`.

* `apple-pay` — the native Apple Pay button (Safari and other Apple Pay-capable browsers).
* `google-pay` — the native Google Pay button (Chrome, Android, and other Google Pay-capable browsers).
* `whop-pay` — a Whop Pay button that opens checkout in a dialog.

```tsx theme={null}
<WhopExpressCheckoutButton
	methods={["apple-pay"]}
	planId="plan_XXXXXXXXX"
	returnUrl="https://yoursite.com/checkout/complete"
/>
```

Wallet requests are strict: a `methods={["google-pay"]}` button only ever renders Google Pay — it never falls back to Apple Pay (and vice versa). If none of the allowed methods can render in the current browser, nothing renders and the `onExpressMethodResolved` callback fires with `{ rendered: "none" }`.

#### **`theme`**

**Optional** - The theme for the button and the dialog. Possible values are `light`, `dark`, or `system`.

#### **`themeOptions`**

**Optional** - Theme tuning for the Whop Pay dialog.

```tsx theme={null}
<WhopExpressCheckoutButton
	planId="plan_XXXXXXXXX"
	returnUrl="https://yoursite.com/checkout/complete"
	theme="dark"
	themeOptions={{ accentColor: "violet", highContrast: true }}
/>
```

#### **`prefill`**

**Optional** - Prefill the email or address inside the Whop Pay dialog. Same shape as the regular embedded checkout — see [prefill options](/payments/checkout-embed#prefill).

```tsx theme={null}
<WhopExpressCheckoutButton
	planId="plan_XXXXXXXXX"
	returnUrl="https://yoursite.com/checkout/complete"
	prefill={{ email: "example@domain.com" }}
/>
```

#### **`affiliateCode`**

**Optional** - Attribute the sale to an affiliate.

#### **`promoCode`**

**Optional** - Apply a promo code on the session.

#### **`adaptivePricing`**

**Optional** - Set to `true` to present prices in the buyer's local currency where supported. Defaults to `false`.

#### **`skipRedirect`**

**Optional** - Set to `true` to skip the final redirect and keep your page loaded. Automatically `true` when `onComplete` is provided.

#### **`onComplete`**

**Optional** - Fires when the checkout completes successfully.

<Note>Setting this implies `skipRedirect = true`.</Note>

```tsx theme={null}
<WhopExpressCheckoutButton
	planId="plan_XXXXXXXXX"
	returnUrl="https://yoursite.com/checkout/complete"
	onComplete={(planId, receiptId) => {
		console.log("paid", planId, receiptId);
	}}
/>
```

#### **`onPaymentError`**

**Optional** - Fires when checkout payment processing fails, with a human readable `message` and an optional machine readable `code`.

```tsx theme={null}
<WhopExpressCheckoutButton
	planId="plan_XXXXXXXXX"
	returnUrl="https://yoursite.com/checkout/complete"
	onPaymentError={(error) => {
		console.log(error.message, error.code);
	}}
/>
```

#### **`onExpressMethodResolved`**

**Optional** - Fires once the button decides which method it will render.

```tsx theme={null}
<WhopExpressCheckoutButton
	planId="plan_XXXXXXXXX"
	returnUrl="https://yoursite.com/checkout/complete"
	onExpressMethodResolved={({ rendered }) => {
		// rendered: "apple-pay" | "google-pay" | "whop-pay" | "none"
		if (rendered === "none") hidePricingCard();
	}}
/>
```

`rendered: "none"` means the button won't show anything — typically because the only requested method is `apple-pay` and the browser can't render it. Use this to hide the surrounding slot so you don't leave an empty space on the page.

## What renders

The button picks one method per browser, in this order:

| Browser                                          | Renders                  | Notes                                     |
| ------------------------------------------------ | ------------------------ | ----------------------------------------- |
| Safari (macOS/iOS) with an Apple Pay card set up | Native Apple Pay button  | Submits inline; no dialog                 |
| Chrome / Android with Google Pay                 | Native Google Pay button | Submits inline; no dialog                 |
| Anything else                                    | Whop Pay button          | Opens checkout in a dialog over your page |

If you only request `apple-pay` and the browser can't render it, the button signals back to your page (via the `express-method-resolved` event) so you can hide the slot.

## Other websites

### Step 1: Add the script tag

```html theme={null}
<script
	async
	defer
	src="https://js.whop.com/static/checkout/loader.js"
></script>
```

### Step 2: Add the button

The one click checkout button is a custom element. Once the script loads it registers `<whop-express-checkout-button>`:

```html theme={null}
<whop-express-checkout-button
	plan-id="plan_XXXXXXXXX"
	return-url="https://yoursite.com/checkout/complete"
></whop-express-checkout-button>
```

### Step 3: **(optional)** Configure - Available attributes

| Attribute                              | Required                             | Description                                                                                 |
| -------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
| `plan-id`                              | yes (or `checkout-configuration-id`) | The plan to check out.                                                                      |
| `checkout-configuration-id`            | yes (or `plan-id`)                   | An API-created checkout configuration to resume instead of creating a new session at mount. |
| `return-url`                           | yes                                  | Where to return after redirect-based authorization.                                         |
| `methods`                              | no                                   | Comma-separated list — `apple-pay`, `google-pay`, `whop-pay`. Defaults to all.              |
| `theme`                                | no                                   | `light`, `dark`, or `system`.                                                               |
| `theme-accent-color`                   | no                                   | Frosted UI accent color name (e.g. `violet`).                                               |
| `theme-high-contrast`                  | no                                   | `"true"` or `"false"`.                                                                      |
| `prefill-email`                        | no                                   | Prefill the buyer's email.                                                                  |
| `prefill-name`                         | no                                   | Prefill the buyer's name.                                                                   |
| `prefill-address-line1`                | no                                   | Prefill billing address line 1.                                                             |
| `prefill-address-line2`                | no                                   | Prefill billing address line 2.                                                             |
| `prefill-address-city`                 | no                                   | Prefill billing city.                                                                       |
| `prefill-address-state`                | no                                   | Prefill billing state.                                                                      |
| `prefill-address-country`              | no                                   | Prefill billing country code.                                                               |
| `prefill-address-postal-code`          | no                                   | Prefill billing postal code.                                                                |
| `prefill-shipping-name`                | no                                   | Prefill shipping name.                                                                      |
| `prefill-shipping-address-line1`       | no                                   | Prefill shipping address line 1.                                                            |
| `prefill-shipping-address-line2`       | no                                   | Prefill shipping address line 2.                                                            |
| `prefill-shipping-address-city`        | no                                   | Prefill shipping city.                                                                      |
| `prefill-shipping-address-state`       | no                                   | Prefill shipping state.                                                                     |
| `prefill-shipping-address-country`     | no                                   | Prefill shipping country code.                                                              |
| `prefill-shipping-address-postal-code` | no                                   | Prefill shipping postal code.                                                               |
| `affiliate-code`                       | no                                   | Affiliate attribution.                                                                      |
| `promo-code`                           | no                                   | Apply a promo code on the session.                                                          |
| `state-id`                             | no                                   | Resume a previously-created session.                                                        |
| `adaptive-pricing`                     | no                                   | `"true"` to present buyer-local currency.                                                   |
| `skip-redirect`                        | no                                   | `"true"` to keep your page loaded after payment.                                            |
| `setup-future-usage`                   | no                                   | Set to `off_session` to save the payment method for future charges.                         |
| `environment`                          | no                                   | Override the API environment (rarely needed).                                               |
| `wuid`                                 | no                                   | Stable per-buyer identifier for analytics.                                                  |

### Step 4: Listening for events

The custom element dispatches DOM events you can listen for:

```html theme={null}
<whop-express-checkout-button
	id="my-button"
	plan-id="plan_XXXXXXXXX"
	return-url="https://yoursite.com/checkout/complete"
></whop-express-checkout-button>

<script>
	const button = document.getElementById("my-button");

	button.addEventListener("express-method-resolved", (event) => {
		// event.detail.rendered: "apple-pay" | "google-pay" | "whop-pay" | "none"
		if (event.detail.rendered === "none") button.style.display = "none";
	});

	button.addEventListener("complete", (event) => {
		// event.detail: { planId, receiptOrSetupIntentId }
		console.log("paid", event.detail);
	});

	button.addEventListener("payment-error", (event) => {
		// event.detail: { message, code? }
		console.log("payment failed", event.detail);
	});

	button.addEventListener("overlay-open", () => {
		// the Whop Pay dialog opened
	});

	button.addEventListener("overlay-close", () => {
		// the Whop Pay dialog closed (cancelled or completed)
	});
</script>
```

| Event                     | Fires when                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `ready`                   | The button has mounted and measured itself.                                                                                          |
| `express-method-resolved` | The button decided which method it will render. `event.detail.rendered` is `"apple-pay"`, `"google-pay"`, `"whop-pay"`, or `"none"`. |
| `overlay-open`            | The Whop Pay dialog opened.                                                                                                          |
| `overlay-close`           | The Whop Pay dialog closed (for any reason).                                                                                         |
| `complete`                | Payment completed successfully. `event.detail` has `planId` and `receiptOrSetupIntentId`.                                            |
| `payment-error`           | Payment processing failed. `event.detail` has a human readable `message` and an optional machine readable `code`.                    |


# AddPayoutMethodElement
Source: https://docs.whop.com/sdk/elements/add-payout-method-element

A UI element that allows users to add a new payout method (bank account, PayPal, etc.) to their account.

## Overview

A UI element that allows users to add a new payout method (bank account, PayPal, etc.) to their account.

This element handles the complete flow for adding payout methods, including:

* Selecting the payout method type
* Entering account details
* Validating the information
* Saving the payout method

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("add-payout-method-element", {
  onComplete: () => {
    console.log("Payout method added!");
  },
});

// Mount it to a container
element.mount("#payout-method-container");
```

### Using as a modal

```typescript theme={null}
// Show the element in a modal overlay
const modal = session.showAddPayoutMethodModal({
  onComplete: (ev) => {
    ev.preventDefault(); // Prevent auto-close
    showSuccessMessage();
    setTimeout(() => modal.close(), 2000);
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("add-payout-method-element", {});

element.on("ready", () => {
  console.log("Element loaded");
});

element.on("complete", (ev) => {
  console.log("Success!");
});

element.on("close", (ev) => {
  // Prevent unmount and show confirmation dialog
  ev.preventDefault();
  if (confirm("Are you sure you want to cancel?")) {
    element.unmount();
  }
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("add-payout-method-element", {
  onReady: (element) => {
    console.log("Element is ready");
  },
  onComplete: (ev) => {
    console.log("Payout method added successfully!");
    // Optionally prevent auto-unmount to show a success message
    // ev.preventDefault();
  },
  onClose: (ev) => {
    console.log("User closed the form");
  },
});
```

## Events

Events emitted by the AddPayoutMethodElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `AddPayoutMethodElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`AddPayoutMethodElementOptions`](#addpayoutmethodelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`AddPayoutMethodElementSnapshot`](#addpayoutmethodelementsnapshot)) => void

### `close`

Emitted when the user closes the payout method form without completing it.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `complete`

Emitted when the user successfully adds a new payout method.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`AddPayoutMethodElement`>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                          | Description                                      |
| --------- | ----------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`AddPayoutMethodElementOptions`](#addpayoutmethodelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`AddPayoutMethodElementSnapshot`](#addpayoutmethodelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### AddPayoutMethodElementOptions

Configuration options for the AddPayoutMethodElement.

| Property     | Type                                                               | Required | Default | Description                                                                                                                                                                   |
| ------------ | ------------------------------------------------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady`    | `((element: AddPayoutMethodElement) => void) \| undefined`         | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                      |
| `onClose`    | `((ev: CustomEvent) => void) \| undefined`                         | No       | -       | Callback fired when the user closes the form without adding a payout method. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted. |
| `onComplete` | `((ev: CustomEvent<AddPayoutMethodElement>) => void) \| undefined` | No       | -       | Callback fired when the user successfully adds a new payout method. By default, the element will unmount after completion. Call 'ev.preventDefault()' to keep it mounted.     |

### AddPayoutMethodElementSnapshot

Represents the current state of the AddPayoutMethodElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# AutomaticWithdrawElement
Source: https://docs.whop.com/sdk/elements/automatic-withdraw-element

A UI element that allows users to configure automatic withdrawals for their account.

## Overview

A UI element that allows users to configure automatic withdrawals for their account.

This element handles the complete flow for setting up automatic withdrawals, including:

* Configuring withdrawal frequency and thresholds
* Selecting the destination payout method
* Enabling or disabling automatic withdrawals

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("automatic-withdraw-element", {
  onComplete: () => {
    console.log("Automatic withdraw settings saved!");
  },
});

// Mount it to a container
element.mount("#automatic-withdraw-container");
```

### Using as a modal

```typescript theme={null}
// Show the element in a modal overlay
const modal = session.showAutomaticWithdrawModal({
  onComplete: (ev) => {
    ev.preventDefault(); // Prevent auto-close
    showSuccessMessage();
    setTimeout(() => modal.close(), 2000);
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("automatic-withdraw-element", {});

element.on("ready", () => {
  console.log("Element loaded");
});

element.on("complete", (ev) => {
  console.log("Settings saved!");
});

element.on("close", (ev) => {
  // Prevent unmount and show confirmation dialog
  ev.preventDefault();
  if (confirm("Are you sure you want to cancel?")) {
    element.unmount();
  }
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("automatic-withdraw-element", {
  onReady: (element) => {
    console.log("Element is ready");
  },
  onComplete: (ev) => {
    console.log("Automatic withdraw settings saved!");
    // Optionally prevent auto-unmount to show a success message
    // ev.preventDefault();
  },
  onClose: (ev) => {
    console.log("User closed the form");
  },
});
```

## Events

Events emitted by the AutomaticWithdrawElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `AutomaticWithdrawElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`AutomaticWithdrawElementOptions`](#automaticwithdrawelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`AutomaticWithdrawElementSnapshot`](#automaticwithdrawelementsnapshot)) => void

### `close`

Emitted when the user closes the automatic withdraw configuration without saving.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `complete`

Emitted when the user successfully saves their automatic withdraw settings.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`AutomaticWithdrawElement`>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                              | Description                                      |
| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`AutomaticWithdrawElementOptions`](#automaticwithdrawelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`AutomaticWithdrawElementSnapshot`](#automaticwithdrawelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### AutomaticWithdrawElementOptions

Configuration options for the AutomaticWithdrawElement.

| Property     | Type                                                                 | Required | Default | Description                                                                                                                                                                              |
| ------------ | -------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady`    | `((element: AutomaticWithdrawElement) => void) \| undefined`         | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                                 |
| `onClose`    | `((ev: CustomEvent) => void) \| undefined`                           | No       | -       | Callback fired when the user closes the form without saving changes. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted.                    |
| `onComplete` | `((ev: CustomEvent<AutomaticWithdrawElement>) => void) \| undefined` | No       | -       | Callback fired when the user successfully saves their automatic withdraw settings. By default, the element will unmount after completion. Call 'ev.preventDefault()' to keep it mounted. |

### AutomaticWithdrawElementSnapshot

Represents the current state of the AutomaticWithdrawElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# AvailableCashBreakdownElement
Source: https://docs.whop.com/sdk/elements/available-cash-breakdown-element

A UI element that shows a detailed breakdown of the available (withdrawable) cash balance.

## Overview

A UI element that shows a detailed breakdown of the available (withdrawable) cash balance.

This element provides a detailed view of available funds, including:

* Itemized breakdown of available cash by source
* Total withdrawable amount
* Close action to dismiss the breakdown

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("available-cash-breakdown-element", {
  onClose: (ev) => {
    console.log("Breakdown closed");
  },
});

// Mount it to a container
element.mount("#breakdown-container");
```

### Using as a modal

```typescript theme={null}
// Show the breakdown in a modal overlay
const modal = session.showAvailableCashBreakdownModal({
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("available-cash-breakdown-element", {});

element.on("ready", () => {
  console.log("Breakdown loaded");
});

element.on("close", (ev) => {
  console.log("User closed the breakdown");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("available-cash-breakdown-element", {
  onReady: (element) => {
    console.log("Breakdown is ready");
  },
  onClose: (ev) => {
    console.log("User closed the breakdown");
  },
});
```

## Events

Events emitted by the AvailableCashBreakdownElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `AvailableCashBreakdownElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`AvailableCashBreakdownElementOptions`](#availablecashbreakdownelementoptions)) => void

### `close`

Emitted when the user closes the breakdown view.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`AvailableCashBreakdownElementSnapshot`](#availablecashbreakdownelementsnapshot)) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                                        | Description                                      |
| --------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`AvailableCashBreakdownElementOptions`](#availablecashbreakdownelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`AvailableCashBreakdownElementSnapshot`](#availablecashbreakdownelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### AvailableCashBreakdownElementOptions

Configuration options for the AvailableCashBreakdownElement.

| Property  | Type                                                              | Required | Default | Description                                                                                                                                              |
| --------- | ----------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady` | `((element: AvailableCashBreakdownElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                 |
| `onClose` | `((ev: CustomEvent) => void) \| undefined`                        | No       | -       | Callback fired when the user closes the breakdown view. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted. |

### AvailableCashBreakdownElementSnapshot

Represents the current state of the AvailableCashBreakdownElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# BalanceElement
Source: https://docs.whop.com/sdk/elements/balance-element

A UI element that displays the user's current balance including available, pending, and reserve amounts with an optional withdraw button.

## Overview

A UI element that displays the user's current balance including available, pending, and reserve amounts with an optional withdraw button.

This element provides a complete balance overview, including:

* Displaying available, pending, and reserve balance amounts
* Optional withdraw button to initiate withdrawals
* Clickable balance rows that open detailed breakdown modals
* Treasury balance display when enabled

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("balance-element", {
  showWithdrawButton: true,
  onWithdraw: (ev) => {
    console.log("User initiated withdrawal");
  },
});

// Mount it to a container
element.mount("#balance-container");
```

### Listening to events

```typescript theme={null}
const element = session.createElement("balance-element", {
  showWithdrawButton: true,
});

element.on("ready", () => {
  console.log("Balance loaded");
});

element.on("withdraw", (ev) => {
  // Prevent the default withdraw modal from opening
  ev.preventDefault();
  // Handle withdrawal with your own UI
  openCustomWithdrawFlow();
});

element.on("verify", (ev) => {
  console.log("Account verification required");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("balance-element", {
  showWithdrawButton: true,
  onReady: (element) => {
    console.log("Balance element is ready");
  },
  onWithdraw: (ev) => {
    console.log("User clicked withdraw");
  },
  onVerify: (ev) => {
    console.log("User needs to verify their account");
  },
});
```

## Events

Events emitted by the BalanceElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `BalanceElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`BalanceElementOptions`](#balanceelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`BalanceElementSnapshot`](#balanceelementsnapshot)) => void

### `withdraw`

Emitted when the user clicks the withdraw button.
Call `ev.preventDefault()` to prevent the element from automatically opening the withdraw modal.

**Callback signature:** (ev: `CustomEvent`\<`BalanceElement`>) => void

### `verify`

Emitted when the user needs to verify their account before withdrawing.

**Callback signature:** (ev: `CustomEvent`\<`BalanceElement`>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                          | Description                                      |
| --------- | ------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`BalanceElementOptions`](#balanceelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`BalanceElementSnapshot`](#balanceelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### BalanceElementOptions

Configuration options for the BalanceElement.

| Property             | Type                                                       | Required | Default | Description                                                                                                                                                                  |
| -------------------- | ---------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `showWithdrawButton` | `boolean \| undefined`                                     | No       | -       | Whether to show the withdraw button within the balance element. When enabled, the user can initiate a withdrawal directly from the balance view.                             |
| `onReady`            | `((element: BalanceElement) => void) \| undefined`         | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                     |
| `onWithdraw`         | `((ev: CustomEvent<BalanceElement>) => void) \| undefined` | No       | -       | Callback fired when the user clicks the withdraw button. By default, the element will open the withdraw modal. Call 'ev.preventDefault()' to handle the withdrawal yourself. |
| `onVerify`           | `((ev: CustomEvent<BalanceElement>) => void) \| undefined` | No       | -       | Callback fired when the user needs to verify their account before withdrawing.                                                                                               |

### BalanceElementSnapshot

Represents the current state of the BalanceElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# BalancesElement
Source: https://docs.whop.com/sdk/elements/balances-element

A UI element that displays a multi-currency balance overview with expandable currency rows showing available, pending, and reserve breakdowns per currency.

## Overview

A UI element that displays a multi-currency balance overview with expandable currency rows showing available, pending, and reserve breakdowns per currency.

This element provides a comprehensive multi-currency balance view, including:

* Aggregated total balance across all currencies
* Expandable rows for each currency with available, pending, and reserve breakdowns
* Primary currency pinned at the top of the list
* Treasury (crypto portfolio) section when enabled

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("balances-element", {
  primaryCurrency: "usd",
  onReady: (element) => {
    console.log("Balances loaded");
  },
});

// Mount it to a container
element.mount("#balances-container");
```

### Listening to events

```typescript theme={null}
const element = session.createElement("balances-element", {});

element.on("ready", () => {
  console.log("Element loaded");
});

element.on("snapshot", (snapshot) => {
  console.log("Currencies:", snapshot.currencies);
  console.log("Treasury enabled:", snapshot.treasuryEnabled);
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("balances-element", {
  primaryCurrency: "usd",
  onReady: (element) => {
    console.log("Balances element is ready");
  },
});
```

## Events

Events emitted by the BalancesElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `BalancesElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`BalancesElementOptions`](#balanceselementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`BalancesElementSnapshot`](#balanceselementsnapshot)) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                            | Description                                      |
| --------- | --------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`BalancesElementOptions`](#balanceselementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`BalancesElementSnapshot`](#balanceselementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### BalancesElementOptions

Configuration options for the BalancesElement.

| Property          | Type                                                | Required | Default | Description                                                                                                                              |
| ----------------- | --------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `primaryCurrency` | `string \| undefined`                               | No       | -       | The ISO currency code to display as the primary (top-level) currency. Other currencies with balances will appear below it.               |
| `onReady`         | `((element: BalancesElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event. |

### BalancesElementSnapshot

Represents the current state of the BalancesElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property          | Type                              | Required | Default | Description                                                                                                                                                                                                          |
| ----------------- | --------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`           | `"error" \| "ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive - '"error"' - The element encountered an error during initialization |
| `currencies`      | `string[]`                        | Yes      | -       | The list of ISO currency codes that have balances.                                                                                                                                                                   |
| `treasuryEnabled` | `boolean`                         | Yes      | -       | Whether the treasury (crypto portfolio) feature is enabled for this account.                                                                                                                                         |


# ChangeAccountCountryElement
Source: https://docs.whop.com/sdk/elements/change-account-country-element

A UI element that allows users to change the country associated with their payout account.

## Overview

A UI element that allows users to change the country associated with their payout account.

This element handles the complete flow for updating account country, including:

* Displaying available countries
* Validating the country selection
* Updating the account settings

Changing the account country may affect available payout methods and tax requirements.

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("change-account-country-element", {
  onCountryChanged: (ev) => {
    console.log("Country changed to:", ev.detail.country);
  },
});

// Mount it to a container
element.mount("#country-change-container");
```

### Using as a modal

```typescript theme={null}
// Show the element in a modal overlay
const modal = session.showChangeAccountCountryModal({
  onCountryChanged: (ev) => {
    console.log("New country:", ev.detail.country);
    // Element auto-unmounts by default
  },
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("change-account-country-element", {});

element.on("ready", () => {
  console.log("Element loaded");
});

element.on("countryChanged", (ev) => {
  console.log("Country changed to:", ev.detail.country);
  // Optionally prevent auto-unmount
  // ev.preventDefault();
});

element.on("close", (ev) => {
  console.log("User cancelled the change");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("change-account-country-element", {
  onReady: (element) => {
    console.log("Element is ready");
  },
  onCountryChanged: (ev) => {
    console.log("Country changed to:", ev.detail.country);
  },
  onClose: (ev) => {
    console.log("User cancelled");
  },
});
```

## Events

Events emitted by the ChangeAccountCountryElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `ChangeAccountCountryElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`ChangeAccountCountryElementOptions`](#changeaccountcountryelementoptions)) => void

### `close`

Emitted when the user closes the country selection without making a change.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`ChangeAccountCountryElementSnapshot`](#changeaccountcountryelementsnapshot)) => void

### `countryChanged`

Emitted when the user successfully changes their account country.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<\{ country: `string`; }>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                                    | Description                                      |
| --------- | --------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`ChangeAccountCountryElementOptions`](#changeaccountcountryelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`ChangeAccountCountryElementSnapshot`](#changeaccountcountryelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### ChangeAccountCountryElementOptions

Configuration options for the ChangeAccountCountryElement.

| Property           | Type                                                             | Required | Default | Description                                                                                                                                                                      |
| ------------------ | ---------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady`          | `((element: ChangeAccountCountryElement) => void) \| undefined`  | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                         |
| `onClose`          | `((ev: CustomEvent) => void) \| undefined`                       | No       | -       | Callback fired when the user closes the element without changing their country. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted. |
| `onCountryChanged` | `((ev: CustomEvent<{ country: string; }>) => void) \| undefined` | No       | -       | Callback fired when the user successfully changes their account country. By default, the element will unmount after the change. Call 'ev.preventDefault()' to keep it mounted.   |

### ChangeAccountCountryElementSnapshot

Represents the current state of the ChangeAccountCountryElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# ChatElement
Source: https://docs.whop.com/sdk/elements/chat-element

A UI element that displays a chat interface.

## Overview

A UI element that displays a chat interface.

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("chat-element", {
  channelId: "feed_XXXXXXXXXXXXXX",
  onReady: () => {
    console.log("Chat element is ready");
  },
});

// Mount it to a container
element.mount("#chat-container");
```

### Listening to events

```typescript theme={null}
const element = session.createElement("chat-element", {
  channelId: "feed_XXXXXXXXXXXXXX",
});

element.on("ready", () => {
  console.log("Chat element is ready");
});

element.on("profileClick", (ev) => {
  console.log("Profile clicked:", ev.detail.id);
});

element.on("linkClick", (ev) => {
  console.log("Link clicked:", ev.detail.url);
});

element.on("messageSent", (ev) => {
  console.log("Message sent:", ev.detail.id, ev.detail.content, ev.detail.channelId);
});

element.on("messageDeleted", (ev) => {
  console.log("Message deleted:", ev.detail.id);
});

element.on("experienceClick", (ev) => {
  console.log("Experience clicked:", ev.detail.id);
});

element.mount("#chat-container");
```

```typescript theme={null}
const element = session.createElement("chat-element", {
  channelId: "feed_XXXXXXXXXXXXXX",
  onReady: (element) => {
    console.log("Chat element is ready");
  },
});
```

## Events

Events emitted by the ChatElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `ChatElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`ChatElementOptions`](#chatelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`ChatElementSnapshot`](#chatelementsnapshot)) => void

### `profileClick`

Emitted when the user clicks on a profile.

**Callback signature:** (ev: `CustomEvent`\<\{ id: `string`; }>) => void

### `linkClick`

Emitted when the user clicks on a link.

**Callback signature:** (ev: `CustomEvent`\<\{ url: `string`; }>) => void

### `messageSent`

Emitted when the user sends a message.

**Callback signature:** (ev: `CustomEvent`\<\{ id: `string`; content: `string`; channelId: `string`; }>) => void

### `messageDeleted`

Emitted when the user deletes a message.

**Callback signature:** (ev: `CustomEvent`\<\{ id: `string`; }>) => void

### `experienceClick`

Emitted when the user clicks on an experience mention.

**Callback signature:** (ev: `CustomEvent`\<\{ id: `string`; }>) => void

### `attachmentClick`

Emitted when the user clicks on an attachment.

**Callback signature:** (ev: `CustomEvent`\<\{ messageId: `string`; attachments: `AttachmentClickEventAttachment`\[]; }>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                    | Description                                      |
| --------- | ------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`ChatElementOptions`](#chatelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`ChatElementSnapshot`](#chatelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### ChatElementOptions

Configuration options for the ChatElement.

| Property            | Type                                                                                                                  | Required | Default    | Description                                                                                                                              |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `channelId`         | `string`                                                                                                              | Yes      | -          | The ID of the channel, DM, or support chat to connect to.                                                                                |
| `deeplinkToPostId`  | `string \| undefined`                                                                                                 | No       | -          | The ID of the message to deep link to.                                                                                                   |
| `disableNavigation` | `boolean \| undefined`                                                                                                | No       | false      | Disables link navigation. Listen to the 'linkClick' event to handle navigation yourself.                                                 |
| `emptyState`        | `EmptyStateOptions \| undefined`                                                                                      | No       | -          | Custom empty state displayed when there are no messages.                                                                                 |
| `style`             | `"imessage" \| "discord" \| undefined`                                                                                | No       | 'imessage' | The style of the chat.                                                                                                                   |
| `features`          | `{ banUser?: boolean; muteUser?: boolean; previewAttachments?: boolean; mentionExperiences?: boolean; } \| undefined` | No       | -          | Configure which features are available in chat.                                                                                          |
| `onReady`           | `((element: ChatElement) => void) \| undefined`                                                                       | No       | -          | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event. |
| `onEvent`           | `((event: ChatElementEvent) => void) \| undefined`                                                                    | No       | -          | Callback fired when a chat element event is emitted.                                                                                     |

### ChatElementSnapshot

Represents the current state of the ChatElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# Create a chat session
Source: https://docs.whop.com/sdk/elements/chat-session

Manages authentication and creates chat elements.

## Overview

Manages authentication and creates chat elements.

## Examples

### Basic usage

```typescript theme={null}
const session = whopElements.createChatSession({
  token: async () => {
    const response = await fetch("/api/token");
    const data = await response.json();
    return data.token;
  },
});

session.on("ready", () => {
  console.log("Session is ready");
});
```

### Creating elements

```typescript theme={null}
const chatElement = session.createElement("chat-element", {
  channelId: "feed_XXXXXXXXXXXXXX",
});
chatElement.mount("#chat-container");
```

## Options

| Property | Type                | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                             |
| -------- | ------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`  | `Token \| GetToken` | Yes      | -       | The token to use for the session. If a function is provided, it will be called and awaited to get the token. When a function is provided, the token will be refreshed automatically before it expires.  if a string is provided, it will be used as the token and not refreshed automatically. However you can update the token at runtime by calling 'updateOptions' with a new token. |

## Events

Events emitted by the ChatSession.

Listen to these events using the `on()` method.

### `optionsUpdated`

Emitted when the session options are updated via `updateOptions()`.

**Callback signature:** (options: `ExpandedChatSessionOptions`) => void

### `tokenRefreshed`

Emitted when the authentication token is refreshed.

**Callback signature:** (token: `string`) => void

### `tokenRefreshError`

Emitted when token refresh fails.

**Callback signature:** (error: `unknown`) => void

### `error`

Emitted when an error occurs during session operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the session is ready and authenticated.

**Callback signature:** (`void`) => void

## Methods

### `createElement(type, options)`

Create a new element instance.

| Parameter | Type                        | Description                             |
| --------- | --------------------------- | --------------------------------------- |
| `type`    | T \| \{ type: T; }          | The element type (e.g., "chat-element") |
| `options` | ChatSessionElements\[T]\[0] | Element-specific configuration options  |

**Returns:** `ChatSessionElements[T][1]`

```typescript theme={null}
const element = session.createElement("chat-element", {
  channelId: "feed_XXXXXXXXXXXXXX",
  onReady: () => console.log("Element ready"),
});
element.mount("#chat-container");
```

### `updateOptions(options)`

Update the session options after initialization.

Changes will be propagated to all active elements.

| Parameter | Type                         | Description                                      |
| --------- | ---------------------------- | ------------------------------------------------ |
| `options` | Partial\<ChatSessionOptions> | Partial options object with the values to update |

### `destroy()`

Destroy the session and clean up all mounted elements.

Call this when you no longer need the session to free up resources.

### Modal Methods

#### `showSearchModal(options, force)`

Show the search element in a modal overlay.

By default, the modal auto-closes on completion (`onResultClick`) or dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                    | Description                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `options` | [`SearchElementOptions`](/sdk/elements/search-element#searchelementoptions) \| ((modal: ModalContainer) => [`SearchElementOptions`](/sdk/elements/search-element#searchelementoptions)) | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                      | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`


# DmsListElement
Source: https://docs.whop.com/sdk/elements/dms-list-element

A UI element that displays a dms list.

## Overview

A UI element that displays a dms list.

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("dms-list-element", {
  onReady: (element) => {
    console.log("Dms list element is ready");
  },
});

// Mount it to a container
element.mount("#dms-list-container");
```

### Listening to events

```typescript theme={null}
const element = session.createElement("dms-list-element", {});

element.on("ready", () => {
  console.log("Dms list element is ready");
});

element.on("channelSelected", (ev) => {
  console.log("Channel selected:", ev.detail.id);
});

element.mount("#dms-list-container");
```

```typescript theme={null}
const element = session.createElement("dms-list-element", {
  onReady: (element) => {
    console.log("Dms list element is ready");
  },
});
```

## Events

Events emitted by the DmListElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `DmsListElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`DmsListElementOptions`](#dmslistelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`DmsListElementSnapshot`](#dmslistelementsnapshot)) => void

### `channelSelected`

Emitted when the user clicks a channel.

**Callback signature:** (ev: `CustomEvent`\<\{ id: `string`; }>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                          | Description                                      |
| --------- | ------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`DmsListElementOptions`](#dmslistelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`DmsListElementSnapshot`](#dmslistelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### DmsListElementOptions

Configuration options for the DmsListElement.

| Property          | Type                                                  | Required | Default | Description                                                                                                                              |
| ----------------- | ----------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `companyId`       | `string \| undefined`                                 | No       | -       | The company ID to filter the channels by.                                                                                                |
| `selectedChannel` | `string \| undefined`                                 | No       | -       | The ID of the currently selected channel.                                                                                                |
| `emptyState`      | `EmptyStateOptions \| undefined`                      | No       | -       | Custom empty state displayed when there are no channels.                                                                                 |
| `onReady`         | `((element: DmsListElement) => void) \| undefined`    | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event. |
| `onEvent`         | `((event: DmsListElementEvent) => void) \| undefined` | No       | -       | Callback fired when a dms list element event is emitted.                                                                                 |

### DmsListElementSnapshot

Represents the current state of the DmsListElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# GenerateWithdrawalReceiptElement
Source: https://docs.whop.com/sdk/elements/generate-withdrawal-receipt-element

A UI element that allows users to generate and request a receipt for a specific withdrawal.

## Overview

A UI element that allows users to generate and request a receipt for a specific withdrawal.

This element handles the receipt generation flow, including:

* Displaying withdrawal details
* Allowing the user to request a receipt
* Sending the receipt to the user's email

## Usage

### Basic usage

```typescript theme={null}
// Create the element with a specific withdrawal ID
const element = session.createElement("generate-withdrawal-receipt-element", {
  withdrawalId: "withdrawal_abc123",
  onReceiptRequested: () => {
    console.log("Receipt sent to email!");
  },
});

// Mount it to a container
element.mount("#receipt-container");
```

### Using as a modal

```typescript theme={null}
// Show the element in a modal overlay
const modal = session.showGenerateWithdrawalReceiptModal({
  withdrawalId: "withdrawal_abc123",
  onReceiptRequested: (ev) => {
    console.log("Receipt requested!");
    // Element auto-unmounts by default
  },
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("generate-withdrawal-receipt-element", {
  withdrawalId: "withdrawal_abc123",
});

element.on("ready", () => {
  console.log("Element loaded");
});

element.on("receiptRequested", (ev) => {
  console.log("Receipt requested!");
  ev.preventDefault(); // Keep element mounted
  showSuccessMessage();
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("generate-withdrawal-receipt-element", {
  withdrawalId: "withdrawal_abc123",
  onReady: (element) => {
    console.log("Receipt generator is ready");
  },
  onReceiptRequested: (ev) => {
    console.log("Receipt requested!");
  },
});
```

## Events

Events emitted by the GenerateWithdrawalReceiptElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `GenerateWithdrawalReceiptElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`GenerateWithdrawalReceiptElementOptions`](#generatewithdrawalreceiptelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`GenerateWithdrawalReceiptElementSnapshot`](#generatewithdrawalreceiptelementsnapshot)) => void

### `close`

Emitted when the user closes the receipt generator without requesting a receipt.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `receiptRequested`

Emitted when the user successfully requests a receipt for the withdrawal.
The receipt will be sent to the user's email address.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                                              | Description                                      |
| --------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`GenerateWithdrawalReceiptElementOptions`](#generatewithdrawalreceiptelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`GenerateWithdrawalReceiptElementSnapshot`](#generatewithdrawalreceiptelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### GenerateWithdrawalReceiptElementOptions

Configuration options for the GenerateWithdrawalReceiptElement.

| Property             | Type                                                                 | Required | Default | Description                                                                                                                                                                                                                |
| -------------------- | -------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `withdrawalId`       | `string`                                                             | Yes      | -       | The ID of the withdrawal to generate a receipt for. This is required to identify which withdrawal the receipt should be generated for.                                                                                     |
| `onReady`            | `((element: GenerateWithdrawalReceiptElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                                                                   |
| `onClose`            | `((ev: CustomEvent) => void) \| undefined`                           | No       | -       | Callback fired when the user closes the element without requesting a receipt. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted.                                             |
| `onReceiptRequested` | `((ev: CustomEvent) => void) \| undefined`                           | No       | -       | Callback fired when the user successfully requests a receipt. The receipt will be sent to the user's email address. By default, the element will unmount after the request. Call 'ev.preventDefault()' to keep it mounted. |

### GenerateWithdrawalReceiptElementSnapshot

Represents the current state of the GenerateWithdrawalReceiptElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# Create a payouts session
Source: https://docs.whop.com/sdk/elements/payouts-session

Manages authentication and creates payout elements.

## Overview

Manages authentication and creates payout elements.

The PayoutsSession handles token management, element creation, and provides
convenience methods for showing elements in modals.

## Examples

### Basic usage

```typescript theme={null}
const session = whopElements.createPayoutsSession({
  token: async () => {
    const response = await fetch("/api/token");
    const data = await response.json();
    return data.token;
  },
  companyId: "your-company-id",
  redirectUrl: "https://yourapp.com/callback",
});

session.on("ready", () => {
  console.log("Session is ready");
});
```

### Creating elements

```typescript theme={null}
const balanceElement = session.createElement("balance-element", {});
balanceElement.mount("#balance-container");

const withdrawButton = session.createElement("withdraw-button-element", {
  onWithdraw: () => console.log("Withdrawal initiated"),
});
withdrawButton.mount("#withdraw-button");
```

### Using modal methods

```typescript theme={null}
// No args — the modal auto-closes on completion or dismiss
session.showWithdrawModal();

// Custom callback — runs your handler, then auto-closes
session.showWithdrawModal({
  onWithdraw: () => console.log("Withdrawal submitted"),
});

// preventDefault() opts out of auto-close
session.showWithdrawModal({
  onWithdraw: (ev) => {
    ev.preventDefault(); // modal stays open
    showConfirmation();
  },
});
```

## Options

| Property      | Type                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                             |
| ------------- | --------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`       | `Token \| GetToken`   | Yes      | -       | The token to use for the session. If a function is provided, it will be called and awaited to get the token. When a function is provided, the token will be refreshed automatically before it expires.  if a string is provided, it will be used as the token and not refreshed automatically. However you can update the token at runtime by calling 'updateOptions' with a new token. |
| `currency`    | `string \| undefined` | No       | "USD"   | The currency to use in the Elements                                                                                                                                                                                                                                                                                                                                                     |
| `companyId`   | `string`              | Yes      | -       | The company ID to use in the Elements                                                                                                                                                                                                                                                                                                                                                   |
| `redirectUrl` | `string`              | Yes      | -       | URL to redirect to after identity verification is completed. This must be an absolute URL (e.g., "[https://yourapp.com/callback](https://yourapp.com/callback)"). Localhost URLs will not work - use ngrok for local development.                                                                                                                                                       |

## Events

Events emitted by the PayoutsSession.

Listen to these events using the `on()` method.

### `optionsUpdated`

Emitted when the session options are updated via `updateOptions()`.

**Callback signature:** (options: `ExpandedPayoutsSessionOptions`) => void

### `tokenRefreshed`

Emitted when the authentication token is refreshed.

**Callback signature:** (token: `string`) => void

### `tokenRefreshError`

Emitted when token refresh fails.

**Callback signature:** (error: `unknown`) => void

### `error`

Emitted when an error occurs during session operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the session is ready and authenticated.

**Callback signature:** (`void`) => void

## Methods

### `createElement(type, options)`

Create a new element instance.

| Parameter | Type                           | Description                                                           |
| --------- | ------------------------------ | --------------------------------------------------------------------- |
| `type`    | T \| \{ type: T; }             | The element type (e.g., "balance-element", "withdraw-button-element") |
| `options` | PayoutsSessionElements\[T]\[0] | Element-specific configuration options                                |

**Returns:** `PayoutsSessionElements[T][1]`

```typescript theme={null}
const element = session.createElement("balance-element", {
  onReady: () => console.log("Element ready"),
});
element.mount("#container");
```

### `updateOptions(options)`

Update the session options after initialization.

Changes will be propagated to all active elements.

| Parameter | Type                            | Description                                      |
| --------- | ------------------------------- | ------------------------------------------------ |
| `options` | Partial\<PayoutsSessionOptions> | Partial options object with the values to update |

### `destroy()`

Destroy the session and clean up all mounted elements.

Call this when you no longer need the session to free up resources.

### Modal Methods

#### `showWithdrawModal(options, force)`

Show the withdraw element in a modal overlay.

By default, the modal auto-closes on completion (`onWithdraw`) or dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                             | Description                                                     |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `options` | [`WithdrawElementOptions`](/sdk/elements/withdraw-element#withdrawelementoptions) \| ((modal: ModalContainer) => [`WithdrawElementOptions`](/sdk/elements/withdraw-element#withdrawelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                               | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showAddPayoutMethodModal(options, force)`

Show the add payout method element in a modal overlay.

By default, the modal auto-closes on completion (`onComplete`) or dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                           | Description                                                     |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `options` | [`AddPayoutMethodElementOptions`](/sdk/elements/add-payout-method-element#addpayoutmethodelementoptions) \| ((modal: ModalContainer) => [`AddPayoutMethodElementOptions`](/sdk/elements/add-payout-method-element#addpayoutmethodelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                                                                             | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showAutomaticWithdrawModal(options, force)`

Show the automatic withdraw settings element in a modal overlay.

By default, the modal auto-closes on completion (`onComplete`) or dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                                     | Description                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `options` | [`AutomaticWithdrawElementOptions`](/sdk/elements/automatic-withdraw-element#automaticwithdrawelementoptions) \| ((modal: ModalContainer) => [`AutomaticWithdrawElementOptions`](/sdk/elements/automatic-withdraw-element#automaticwithdrawelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                                                                                       | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showVerifyModal(options, force)`

Show the identity verification element in a modal overlay.

By default, the modal auto-closes on completion (`onVerificationSubmitted`) or dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                 | Description                                                     |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `options` | [`VerifyElementOptions`](/sdk/elements/verify-element#verifyelementoptions) \| ((modal: ModalContainer) => [`VerifyElementOptions`](/sdk/elements/verify-element#verifyelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                   | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showWithdrawalBreakdownModal(options, force)`

Show the withdrawal breakdown element in a modal overlay.

By default, the modal auto-closes on dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                                    | Description                                                                                   |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `options` | [`WithdrawalBreakdownElementOptions`](/sdk/elements/withdrawal-breakdown-element#withdrawalbreakdownelementoptions) \| ((modal: ModalContainer) => [`WithdrawalBreakdownElementOptions`](/sdk/elements/withdrawal-breakdown-element#withdrawalbreakdownelementoptions)) | Element options or a callback that receives the modal container. Must include 'withdrawalId'. |
| `force`   | Force \| undefined                                                                                                                                                                                                                                                      | -                                                                                             |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showChangeAccountCountryModal(options, force)`

Show the change account country element in a modal overlay.

By default, the modal auto-closes on completion (`onCountryChanged`) or dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                                                         | Description                                                     |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `options` | [`ChangeAccountCountryElementOptions`](/sdk/elements/change-account-country-element#changeaccountcountryelementoptions) \| ((modal: ModalContainer) => [`ChangeAccountCountryElementOptions`](/sdk/elements/change-account-country-element#changeaccountcountryelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                                                                                                           | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showResetAccountModal(options, force)`

Show the reset account element in a modal overlay.

By default, the modal auto-closes on completion (`onReset`) or dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                       | Description                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `options` | [`ResetAccountElementOptions`](/sdk/elements/reset-account-element#resetaccountelementoptions) \| ((modal: ModalContainer) => [`ResetAccountElementOptions`](/sdk/elements/reset-account-element#resetaccountelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                                                         | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showAvailableCashBreakdownModal(options, force)`

Show the available cash breakdown element in a modal overlay.

By default, the modal auto-closes on dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                                                                     | Description                                                     |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `options` | [`AvailableCashBreakdownElementOptions`](/sdk/elements/available-cash-breakdown-element#availablecashbreakdownelementoptions) \| ((modal: ModalContainer) => [`AvailableCashBreakdownElementOptions`](/sdk/elements/available-cash-breakdown-element#availablecashbreakdownelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                                                                                                                       | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showGenerateWithdrawalReceiptModal(options, force)`

Show the generate withdrawal receipt element in a modal overlay.

By default, the modal auto-closes on completion (`onReceiptRequested`) or dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                                                                          | Description                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `options` | [`GenerateWithdrawalReceiptElementOptions`](/sdk/elements/generate-withdrawal-receipt-element#generatewithdrawalreceiptelementoptions) \| ((modal: ModalContainer) => [`GenerateWithdrawalReceiptElementOptions`](/sdk/elements/generate-withdrawal-receipt-element#generatewithdrawalreceiptelementoptions)) | Element options or a callback that receives the modal container. Must include 'withdrawalId'. |
| `force`   | Force \| undefined                                                                                                                                                                                                                                                                                            | -                                                                                             |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showPendingBreakdownModal(options, force)`

Show the pending breakdown element in a modal overlay.

By default, the modal auto-closes on dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                               | Description                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `options` | [`PendingBreakdownElementOptions`](/sdk/elements/pending-breakdown-element#pendingbreakdownelementoptions) \| ((modal: ModalContainer) => [`PendingBreakdownElementOptions`](/sdk/elements/pending-breakdown-element#pendingbreakdownelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                                                                                 | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showReserveBreakdownModal(options, force)`

Show the reserve breakdown element in a modal overlay.

By default, the modal auto-closes on dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                               | Description                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `options` | [`ReserveBreakdownElementOptions`](/sdk/elements/reserve-breakdown-element#reservebreakdownelementoptions) \| ((modal: ModalContainer) => [`ReserveBreakdownElementOptions`](/sdk/elements/reserve-breakdown-element#reservebreakdownelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                                                                                 | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`

#### `showTreasuryBreakdownModal(options, force)`

Show the treasury breakdown element in a modal overlay.

By default, the modal auto-closes on dismiss (`onClose`).
Call `ev.preventDefault()` in a callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                                                                                     | Description                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `options` | [`TreasuryBreakdownElementOptions`](/sdk/elements/treasury-breakdown-element#treasurybreakdownelementoptions) \| ((modal: ModalContainer) => [`TreasuryBreakdownElementOptions`](/sdk/elements/treasury-breakdown-element#treasurybreakdownelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                                                                                       | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`


# PendingBreakdownElement
Source: https://docs.whop.com/sdk/elements/pending-breakdown-element

A UI element that displays a breakdown of pending balance amounts that are being processed.

## Overview

A UI element that displays a breakdown of pending balance amounts that are being processed.

This element provides a detailed view of pending funds, including:

* Itemized list of pending transactions and their expected settlement
* Total pending amount
* Close action to dismiss the breakdown

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("pending-breakdown-element", {
  onClose: (ev) => {
    console.log("Breakdown closed");
  },
});

// Mount it to a container
element.mount("#breakdown-container");
```

### Using as a modal

```typescript theme={null}
// Show the breakdown in a modal overlay
const modal = session.showPendingBreakdownModal({
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("pending-breakdown-element", {});

element.on("ready", () => {
  console.log("Breakdown loaded");
});

element.on("close", (ev) => {
  console.log("User closed the breakdown");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("pending-breakdown-element", {
  onReady: (element) => {
    console.log("Breakdown is ready");
  },
  onClose: (ev) => {
    console.log("User closed the breakdown");
  },
});
```

## Events

Events emitted by the PendingBreakdownElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `PendingBreakdownElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`PendingBreakdownElementOptions`](#pendingbreakdownelementoptions)) => void

### `close`

Emitted when the user closes the breakdown view.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`PendingBreakdownElementSnapshot`](#pendingbreakdownelementsnapshot)) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                            | Description                                      |
| --------- | ------------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`PendingBreakdownElementOptions`](#pendingbreakdownelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`PendingBreakdownElementSnapshot`](#pendingbreakdownelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### PendingBreakdownElementOptions

Configuration options for the PendingBreakdownElement.

| Property  | Type                                                        | Required | Default | Description                                                                                                                                              |
| --------- | ----------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady` | `((element: PendingBreakdownElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                 |
| `onClose` | `((ev: CustomEvent) => void) \| undefined`                  | No       | -       | Callback fired when the user closes the breakdown view. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted. |

### PendingBreakdownElementSnapshot

Represents the current state of the PendingBreakdownElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# ReserveBreakdownElement
Source: https://docs.whop.com/sdk/elements/reserve-breakdown-element

A UI element that shows a breakdown of reserve balance amounts explaining held funds and their expected availability.

## Overview

A UI element that shows a breakdown of reserve balance amounts explaining held funds and their expected availability.

This element provides a detailed view of reserved funds, including:

* Itemized list of reserve holds and their reasons
* Expected release dates for held funds
* Total reserve amount
* Close action to dismiss the breakdown

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("reserve-breakdown-element", {
  onClose: (ev) => {
    console.log("Breakdown closed");
  },
});

// Mount it to a container
element.mount("#breakdown-container");
```

### Using as a modal

```typescript theme={null}
// Show the breakdown in a modal overlay
const modal = session.showReserveBreakdownModal({
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("reserve-breakdown-element", {});

element.on("ready", () => {
  console.log("Breakdown loaded");
});

element.on("close", (ev) => {
  console.log("User closed the breakdown");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("reserve-breakdown-element", {
  onReady: (element) => {
    console.log("Breakdown is ready");
  },
  onClose: (ev) => {
    console.log("User closed the breakdown");
  },
});
```

## Events

Events emitted by the ReserveBreakdownElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `ReserveBreakdownElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`ReserveBreakdownElementOptions`](#reservebreakdownelementoptions)) => void

### `close`

Emitted when the user closes the breakdown view.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`ReserveBreakdownElementSnapshot`](#reservebreakdownelementsnapshot)) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                            | Description                                      |
| --------- | ------------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`ReserveBreakdownElementOptions`](#reservebreakdownelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`ReserveBreakdownElementSnapshot`](#reservebreakdownelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### ReserveBreakdownElementOptions

Configuration options for the ReserveBreakdownElement.

| Property  | Type                                                        | Required | Default | Description                                                                                                                                              |
| --------- | ----------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady` | `((element: ReserveBreakdownElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                 |
| `onClose` | `((ev: CustomEvent) => void) \| undefined`                  | No       | -       | Callback fired when the user closes the breakdown view. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted. |

### ReserveBreakdownElementSnapshot

Represents the current state of the ReserveBreakdownElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# ResetAccountElement
Source: https://docs.whop.com/sdk/elements/reset-account-element

A UI element that allows users to reset their payout account.

## Overview

A UI element that allows users to reset their payout account.

This element handles the account reset flow, including:

* Displaying reset confirmation
* Warning about consequences of resetting
* Processing the reset request

Resetting an account will clear all payout methods and may require re-verification.
This action cannot be undone.

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("reset-account-element", {
  onReset: () => {
    console.log("Account reset successfully!");
  },
});

// Mount it to a container
element.mount("#reset-account-container");
```

### Using as a modal

```typescript theme={null}
// Show the element in a modal overlay
const modal = session.showResetAccountModal({
  onReset: (ev) => {
    console.log("Account reset!");
    // Element auto-unmounts by default
  },
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("reset-account-element", {});

element.on("ready", () => {
  console.log("Element loaded");
});

element.on("reset", (ev) => {
  console.log("Account reset confirmed!");
});

element.on("close", (ev) => {
  console.log("User cancelled the reset");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("reset-account-element", {
  onReady: (element) => {
    console.log("Element is ready");
  },
  onReset: (ev) => {
    console.log("Account has been reset!");
  },
  onClose: (ev) => {
    console.log("User cancelled the reset");
  },
});
```

## Events

Events emitted by the ResetAccountElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `ResetAccountElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`ResetAccountElementOptions`](#resetaccountelementoptions)) => void

### `close`

Emitted when the user closes the reset confirmation without resetting.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`ResetAccountElementSnapshot`](#resetaccountelementsnapshot)) => void

### `reset`

Emitted when the user confirms and successfully resets their payout account.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                    | Description                                      |
| --------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`ResetAccountElementOptions`](#resetaccountelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`ResetAccountElementSnapshot`](#resetaccountelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### ResetAccountElementOptions

Configuration options for the ResetAccountElement.

| Property  | Type                                                    | Required | Default | Description                                                                                                                                                                              |
| --------- | ------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady` | `((element: ResetAccountElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                                 |
| `onClose` | `((ev: CustomEvent) => void) \| undefined`              | No       | -       | Callback fired when the user closes the element without resetting their account. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted.        |
| `onReset` | `((ev: CustomEvent) => void) \| undefined`              | No       | -       | Callback fired when the user confirms and successfully resets their payout account. By default, the element will unmount after the reset. Call 'ev.preventDefault()' to keep it mounted. |

### ResetAccountElementSnapshot

Represents the current state of the ResetAccountElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# SearchElement
Source: https://docs.whop.com/sdk/elements/search-element

A UI element that allows users to search for messages in a channel, DM, or support chat.

## Overview

A UI element that allows users to search for messages in a channel, DM, or support chat.

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("search-element", {
  onClose: (ev) => {
    console.log("Search element closed");
  },
});

// Mount it to a container
element.mount("#search-container");
```

### Using as a modal

```typescript theme={null}
// Show the element in a modal overlay
const modal = session.showSearchModal({
  channelId: "feed_XXXXXXXXXXXXXX",
  onResultClick: (ev) => {
    console.log("Result clicked!", ev.detail.messageId);
    // Element auto-unmounts by default
  },
});
```

```typescript theme={null}
const element = session.createElement("search-element", {
  channelId: "feed_XXXXXXXXXXXXXX",
  onReady: (element) => {
    console.log("Search element is ready");
  },
});
```

## Events

Events emitted by the SearchElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `SearchElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`SearchElementOptions`](#searchelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`SearchElementSnapshot`](#searchelementsnapshot)) => void

### `close`

Emitted when the user closes the search element.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `resultClick`

Callback fired when the user clicks on a search result.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<\{ messageId: `string`; channelId: `string`; }>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                        | Description                                      |
| --------- | ----------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`SearchElementOptions`](#searchelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`SearchElementSnapshot`](#searchelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### SearchElementOptions

Configuration options for the SearchElement.

| Property        | Type                                                                                  | Required | Default | Description                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `companyId`     | `string \| undefined`                                                                 | No       | -       | The ID of the company to search messages in.                                                                                                                             |
| `channelId`     | `string \| undefined`                                                                 | No       | -       | The ID of the channel, DM, or support chat to search messages in.                                                                                                        |
| `onReady`       | `((element: SearchElement) => void) \| undefined`                                     | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                 |
| `onClose`       | `((ev: CustomEvent) => void) \| undefined`                                            | No       | -       | Callback fired when the user closes the element. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted.                        |
| `onResultClick` | `((ev: CustomEvent<{ messageId: string; channelId: string; }>) => void) \| undefined` | No       | -       | Callback fired when the user clicks on a search result. By default, the element will unmount after the result is clicked. Call 'ev.preventDefault()' to keep it mounted. |

### SearchElementSnapshot

Represents the current state of the SearchElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# StatusBannerElement
Source: https://docs.whop.com/sdk/elements/status-banner-element

A UI element that displays a status banner indicating the user's account verification and compliance status.

## Overview

A UI element that displays a status banner indicating the user's account verification and compliance status.

This element automatically shows relevant banners based on the account status:

* KYC (Know Your Customer) verification status
* Compliance requirements
* Information requests
* Review status

The banner includes actionable buttons that open verification flows when clicked.

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("status-banner-element", {
  onReady: () => {
    console.log("Status banner loaded");
  },
});

// Mount it to a container
element.mount("#status-banner-container");
```

### Custom verify click handling

```typescript theme={null}
const element = session.createElement("status-banner-element", {
  onVerifyClick: (ev) => {
    // Prevent default verify modal
    ev.preventDefault();
    // Show your own verification UI
    showCustomVerificationFlow();
  },
});

element.mount("#status-banner-container");
```

### Listening to banner changes

```typescript theme={null}
const element = session.createElement("status-banner-element", {});

element.on("bannerChange", (ev, bannerType) => {
  if (bannerType === "kyc-success") {
    showSuccessNotification("Verification complete!");
  } else if (bannerType === null) {
    console.log("No issues - account in good standing");
  }
});

element.on("snapshot", (snapshot) => {
  console.log("Current banner type:", snapshot.bannerType);
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("status-banner-element", {
  onReady: (element) => {
    console.log("Status banner is ready");
  },
  onVerifyClick: (ev) => {
    // Custom verification flow
    ev.preventDefault();
    openCustomVerificationModal();
  },
  onBannerChange: (ev, bannerType) => {
    console.log("Banner changed to:", bannerType);
  },
});
```

## Events

Events emitted by the StatusBannerElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `StatusBannerElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`StatusBannerElementOptions`](#statusbannerelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`StatusBannerElementSnapshot`](#statusbannerelementsnapshot)) => void

### `verifyClick`

Emitted when the user clicks the verify button on the banner.
By default, opens the verification modal. Call `ev.preventDefault()` to handle this yourself.

**Callback signature:** (ev: `CustomEvent`\<`StatusBannerElement`>) => void

### `bannerChange`

Emitted when the banner type changes (e.g., after verification status updates).

**Callback signature:** (ev: `CustomEvent`\<`StatusBannerElement`>, bannerType: `StatusBannerType`) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                    | Description                                      |
| --------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`StatusBannerElementOptions`](#statusbannerelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`StatusBannerElementSnapshot`](#statusbannerelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### StatusBannerElementOptions

Configuration options for the StatusBannerElement.

| Property         | Type                                                                                          | Required | Default | Description                                                                                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `onReady`        | `((element: StatusBannerElement) => void) \| undefined`                                       | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                           |
| `onVerifyClick`  | `((ev: CustomEvent<StatusBannerElement>) => void) \| undefined`                               | No       | -       | Callback fired when the user clicks the verify button on the banner. By default, opens the verification modal. Call 'ev.preventDefault()' to handle this yourself. |
| `onBannerChange` | `((ev: CustomEvent<StatusBannerElement>, bannerType: StatusBannerType) => void) \| undefined` | No       | -       | Callback fired when the banner type changes (e.g., after verification status updates).                                                                             |

### StatusBannerElementSnapshot

Represents the current state of the StatusBannerElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property     | Type                   | Required | Default | Description                                                                                                                                                                          |
| ------------ | ---------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `state`      | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive                                      |
| `bannerType` | `StatusBannerType`     | Yes      | -       | The type of banner currently being displayed. This indicates the user's current verification/compliance status. Will be 'null' if no banner is needed (account is in good standing). |


# Styling reference
Source: https://docs.whop.com/sdk/elements/styling-reference

Stable CSS class names applied to Whop embeddable components

## Overview

The class names below are the **stable styling contract** for Whop embeddable
components. Each name is guaranteed to be applied to a specific element rendered
inside the iframe, so you can target it from `appearance.classes`.

`appearance.classes` accepts any CSS selector string as a key — the value is
emitted verbatim into a stylesheet inside the iframe. That means you can combine
the class names below with any standard CSS selector syntax (`:hover`,
`:focus-visible`, descendant selectors, attribute selectors, etc.). Selectors
that don't match any of the names below will still be emitted, but they're not
part of the stable contract and may stop matching as components evolve.

See [`Appearance`](/sdk/elements/types#appearance) for full configuration.

## Shared

Building blocks reused across multiple elements.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			Chevron: {
				color: "var(--gray-11)",
			},
		},
	},
});
```

| Class           | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| `Chevron`       | A shared expand/collapse chevron icon used in breakdown and balance rows. |
| `ConvertButton` | The button to initiate a crypto asset conversion.                         |
| `Icon`          | A step completion icon in the verification navigation.                    |
| `Separator`     | A horizontal divider between address suggestions.                         |

## Address Form

Address form root used by payout-method flows.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			AddressFormRoot: {
				display: "flex",
				flexDirection: "column",
				gap: "12px",
			},
		},
	},
});
```

| Class             | Description                             |
| ----------------- | --------------------------------------- |
| `AddressFormRoot` | The root container of the address form. |

## Auto Withdraw

Automatic withdrawal configuration element.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			AutoWithdrawConfigBody: {
				padding: "16px",
			},
			AutoWithdrawInfoRow: {
				fontSize: "14px",
			},
		},
	},
});
```

| Class                        | Description                                                                                                                         |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `AutoWithdrawConfigBody`     | The main content wrapper of the automatic withdrawal configuration form.                                                            |
| `AutoWithdrawInfoRow`        | An info row displaying a label-value pair in the automatic withdrawal configuration (e.g. Fees, Exchange rate, Estimated delivery). |
| `AutoWithdrawReserveSection` | The section containing the minimum reserve amount input in the automatic withdrawal configuration.                                  |

## Available Cash

Available cash breakdown element.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			AvailableCashBreakdownContainer: {
				padding: "16px",
			},
			AvailableCashSummaryRow: {
				fontWeight: "600",
			},
		},
	},
});
```

| Class                             | Description                                                               |
| --------------------------------- | ------------------------------------------------------------------------- |
| `AvailableCashBreakdownContainer` | The container wrapping available cash breakdown rows.                     |
| `AvailableCashCurrencyRow`        | A currency row in the available cash breakdown.                           |
| `AvailableCashCurrencyRowLeft`    | The left content area of a currency row in the available cash breakdown.  |
| `AvailableCashCurrencyRowRight`   | The right content area of a currency row in the available cash breakdown. |
| `AvailableCashInfoContent`        | The expanded content of the info section in the available cash breakdown. |
| `AvailableCashInfoSection`        | The collapsible information section in the available cash breakdown.      |
| `AvailableCashInfoToggle`         | The toggle button for the info section in the available cash breakdown.   |
| `AvailableCashSummaryRow`         | The summary total row in the available cash breakdown.                    |

## Balance

Single-currency balance element.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			BalanceRoot: {
				padding: "16px",
			},
			BalanceAmount: {
				fontSize: "32px",
				fontWeight: "600",
			},
		},
	},
});
```

| Class                | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| `BalanceActions`     | The container for action buttons like withdraw and deposit.         |
| `BalanceAmount`      | The total balance amount display.                                   |
| `BalanceBar`         | The horizontal bar showing the proportion of each balance category. |
| `BalanceBarEmpty`    | The empty state placeholder for the balance bar.                    |
| `BalanceBarSegment`  | A single segment within the balance bar.                            |
| `BalanceHeader`      | The header area containing the title and action buttons.            |
| `BalanceLegend`      | The legend showing the breakdown of balance categories.             |
| `BalanceLegendDot`   | The colored dot indicator in a legend row.                          |
| `BalanceLegendLabel` | The label area of a legend row, including the color dot.            |
| `BalanceLegendRow`   | A single row in the balance legend.                                 |
| `BalanceRoot`        | The root container of the balance element.                          |
| `BalanceTitleGroup`  | The group containing the balance label and amount.                  |

## Balances

Multi-currency balances element.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			BalancesRoot: {
				padding: "16px",
			},
			BalancesSectionTitle: {
				fontSize: "14px",
				fontWeight: "600",
			},
		},
	},
});
```

| Class                     | Description                                                           |
| ------------------------- | --------------------------------------------------------------------- |
| `BalancesBreakdownLabel`  | The label of a breakdown detail row.                                  |
| `BalancesBreakdownRow`    | An expanded breakdown detail row within a currency.                   |
| `BalancesBuyAssetRow`     | A treasury asset row (Bitcoin, Gold, etc.).                           |
| `BalancesCardsBanner`     | A promotional banner for setting up business cards.                   |
| `BalancesCardsRow`        | The cards spending power row.                                         |
| `BalancesCashRow`         | A currency row in the cash section.                                   |
| `BalancesCurrencyFlag`    | The country flag icon displayed next to a currency.                   |
| `BalancesEmptyState`      | The empty state shown when no balances exist.                         |
| `BalancesExpandablePanel` | An expandable panel for showing breakdown details in balance rows.    |
| `BalancesRoot`            | The root container of the balances element.                           |
| `BalancesRowBalance`      | The balance amount column in a balances row.                          |
| `BalancesRowChevron`      | The expand/collapse chevron column in a balances row.                 |
| `BalancesRowName`         | The name column in a balances row.                                    |
| `BalancesRowYield`        | The yield/APY column in a balances row.                               |
| `BalancesSection`         | A section card grouping related balance rows (Cash, Treasury, Cards). |
| `BalancesSectionBody`     | The body content area of a balances section.                          |
| `BalancesSectionTitle`    | The title header of a balances section.                               |
| `BalancesTreasuryRow`     | The treasury balance row.                                             |

## Breakdown

Generic breakdown layout primitives shared across breakdown elements.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			BreakdownItem: {
				padding: "12px 0",
			},
			BreakdownDivider: {
				borderColor: "var(--gray-5)",
			},
		},
	},
});
```

| Class                   | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| `BreakdownDivider`      | A horizontal divider line within the withdrawal breakdown detail view. |
| `BreakdownItem`         | A single line item within a breakdown list.                            |
| `PendingBreakdownRoot`  | The root container of the pending balance breakdown.                   |
| `TreasuryBreakdownRoot` | The root container of the treasury breakdown.                          |

## Dialog

Modal dialog primitives shared across elements.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			DialogContent: {
				borderRadius: "12px",
			},
			DialogTitle: {
				fontSize: "18px",
				fontWeight: "600",
			},
		},
	},
});
```

| Class               | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `DialogBody`        | The main content area of a dialog.                                            |
| `DialogClose`       | A wrapper that closes the dialog when clicked.                                |
| `DialogCloseButton` | The icon button used to dismiss a dialog.                                     |
| `DialogContent`     | The content panel of a dialog.                                                |
| `DialogFooter`      | The footer area of a dialog, typically containing action buttons.             |
| `DialogHeader`      | The header area of a dialog, typically containing the title and close button. |
| `DialogRoot`        | The root container of a dialog overlay.                                       |
| `DialogTitle`       | The title text of a dialog.                                                   |

## Field

Form field primitives (label, error, description).

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			FieldLabel: {
				fontSize: "14px",
				fontWeight: "500",
			},
			FieldError: {
				color: "var(--red-11)",
			},
		},
	},
});
```

| Class              | Description                                                                            |
| ------------------ | -------------------------------------------------------------------------------------- |
| `FieldDescription` | Helper text displayed below a form field.                                              |
| `FieldError`       | The validation error message displayed below a form field.                             |
| `FieldLabel`       | The label text associated with a form field.                                           |
| `FieldRoot`        | The root container of a form field, wrapping the label, input, description, and error. |

## Fieldset

Fieldset primitives for grouped fields.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			FieldsetLegend: {
				fontSize: "14px",
				fontWeight: "600",
			},
			FieldsetGroup: {
				display: "flex",
				flexDirection: "column",
				gap: "12px",
			},
		},
	},
});
```

| Class            | Description                                               |
| ---------------- | --------------------------------------------------------- |
| `FieldsetGroup`  | A group of fields within a fieldset.                      |
| `FieldsetLegend` | The legend (title) of a fieldset group.                   |
| `FieldsetRoot`   | The root container grouping related form fields together. |

## Input

Text input primitives.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			InputRoot: {
				borderRadius: "8px",
				border: "1px solid var(--gray-7)",
			},
			Input: {
				padding: "8px 12px",
			},
		},
	},
});
```

| Class       | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| `Input`     | The text input element.                                                         |
| `InputRoot` | The outer container wrapping the input element and its slots.                   |
| `InputSlot` | A slot within the input root for icons or other adornments alongside the input. |

## Payout Details

Payout method details card.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			PayoutDetailsCard: {
				padding: "16px",
				borderRadius: "12px",
			},
			PayoutDetailsRow: {
				fontSize: "14px",
			},
		},
	},
});
```

| Class                  | Description                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `PayoutDetailsCard`    | The bordered card containing payout detail sections in the edit payout details modal.                   |
| `PayoutDetailsContent` | The content wrapper of the edit payout details modal.                                                   |
| `PayoutDetailsRow`     | A single section row within the payout details card (e.g. Bank details, Mailing address, Phone number). |

## Payout Method

Payout method form.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			PayoutMethodForm: {
				display: "flex",
				flexDirection: "column",
				gap: "16px",
			},
		},
	},
});
```

| Class              | Description                              |
| ------------------ | ---------------------------------------- |
| `PayoutMethodForm` | The form for adding a new payout method. |

## Pending

Pending breakdown element.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			PendingCurrencySection: {
				padding: "12px 0",
			},
			PendingSummaryRow: {
				fontWeight: "600",
			},
		},
	},
});
```

| Class                     | Description                                                             |
| ------------------------- | ----------------------------------------------------------------------- |
| `PendingCurrencyRow`      | A currency row in the pending breakdown.                                |
| `PendingCurrencyRowLeft`  | The left content area of a currency row in the pending breakdown.       |
| `PendingCurrencyRowRight` | The right content area of a currency row in the pending breakdown.      |
| `PendingCurrencySection`  | A currency section group in the pending breakdown.                      |
| `PendingIndentedRow`      | An indented sub-row within the pending breakdown.                       |
| `PendingIndentedRowRight` | The right content area of an indented sub-row in the pending breakdown. |
| `PendingInfoContent`      | The expanded content of the info section in the pending breakdown.      |
| `PendingInfoSection`      | The collapsible information section in the pending breakdown.           |
| `PendingInfoToggle`       | The toggle button for the info section in the pending breakdown.        |
| `PendingSummaryRow`       | The summary total row in the pending breakdown.                         |

## Phone

Phone input primitive.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			PhoneInput: {
				borderRadius: "8px",
			},
		},
	},
});
```

| Class        | Description                                        |
| ------------ | -------------------------------------------------- |
| `PhoneInput` | A phone number input with a country code selector. |

## Receipt

Generated withdrawal receipt header.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			ReceiptHeader: {
				padding: "16px",
				borderBottom: "1px solid var(--gray-5)",
			},
		},
	},
});
```

| Class           | Description                                  |
| --------------- | -------------------------------------------- |
| `ReceiptHeader` | The header of the withdrawal receipt dialog. |

## Reserve

Reserve breakdown element.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			ReserveCurrencyRow: {
				padding: "8px 0",
			},
		},
	},
});
```

| Class                | Description                              |
| -------------------- | ---------------------------------------- |
| `ReserveCurrencyRow` | A currency row in the reserve breakdown. |

## Select

Select / dropdown primitives.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			SelectTrigger: {
				borderRadius: "8px",
				padding: "8px 12px",
			},
			SelectPopup: {
				borderRadius: "8px",
			},
		},
	},
});
```

| Class                 | Description                                                               |
| --------------------- | ------------------------------------------------------------------------- |
| `SelectArrow`         | The arrow pointer on the custom select popup.                             |
| `SelectBackdrop`      | The overlay backdrop behind an open custom select dropdown.               |
| `SelectChevron`       | The dropdown chevron icon inside a custom select trigger.                 |
| `SelectGroup`         | A group of related items within a custom select.                          |
| `SelectGroupLabel`    | The label for a group of items within a custom select.                    |
| `SelectIcon`          | The dropdown indicator icon in a custom select trigger.                   |
| `SelectItem`          | An individual option within a custom select dropdown.                     |
| `SelectItemIndicator` | The checkmark or indicator shown on the selected item.                    |
| `SelectItemText`      | The text label of a custom select item.                                   |
| `SelectList`          | The scrollable list container inside a custom select popup.               |
| `SelectOption`        | An option within a native select element.                                 |
| `SelectPopup`         | The floating dropdown panel of a custom select.                           |
| `SelectPortal`        | The portal container for a custom select dropdown.                        |
| `SelectPositioner`    | The positioning wrapper for the custom select popup.                      |
| `SelectRoot`          | The root container of a native select element.                            |
| `SelectScrollDown`    | The scroll-down indicator shown when the custom select list overflows.    |
| `SelectScrollUp`      | The scroll-up indicator shown when the custom select list overflows.      |
| `SelectSeparator`     | A visual divider between groups of items in a custom select.              |
| `SelectTrigger`       | The button that opens a custom select dropdown.                           |
| `SelectValue`         | The display text showing the currently selected value in a custom select. |

## Status Banner

Account status banner element.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			StatusBannerRoot: {
				padding: "16px",
				borderRadius: "8px",
			},
			StatusBannerCallout: {
				fontWeight: "600",
			},
		},
	},
});
```

| Class                        | Description                                                  |
| ---------------------------- | ------------------------------------------------------------ |
| `StatusBannerAction`         | The action button within a status banner callout.            |
| `StatusBannerApproved`       | The approval confirmation banner.                            |
| `StatusBannerApprovedAction` | The action button in the approval banner.                    |
| `StatusBannerApprovedIcon`   | The icon in the approval banner.                             |
| `StatusBannerApprovedText`   | The text content in the approval banner.                     |
| `StatusBannerAwaitingReview` | The awaiting review status banner.                           |
| `StatusBannerBadgeGroup`     | A group of status badges within a banner.                    |
| `StatusBannerCallout`        | A callout banner displaying account status information.      |
| `StatusBannerDismiss`        | The dismiss button to close a status banner.                 |
| `StatusBannerHourglassIcon`  | The hourglass icon in the awaiting review banner.            |
| `StatusBannerInfoContent`    | The content area of the information required banner.         |
| `StatusBannerInfoRequired`   | The information required status banner.                      |
| `StatusBannerPendingContent` | The content area of a pending status banner.                 |
| `StatusBannerRoot`           | The root container of the status banner element.             |
| `StatusBannerWarningIcon`    | The warning icon in a status banner.                         |
| `StatusBannerWarningImage`   | The warning illustration in the information required banner. |

## Treasury

Treasury breakdown element.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			TreasuryAssetRow: {
				padding: "12px 0",
			},
			TreasurySummaryRow: {
				fontWeight: "600",
			},
		},
	},
});
```

| Class                  | Description                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| `TreasuryAssetIconSvg` | The icon for a treasury asset.                                      |
| `TreasuryAssetRow`     | An asset row in the treasury breakdown.                             |
| `TreasuryAssetRowLeft` | The left content area of a treasury asset row.                      |
| `TreasuryIndentedRow`  | An indented sub-row within the treasury breakdown.                  |
| `TreasuryInfoContent`  | The expanded content of the info section in the treasury breakdown. |
| `TreasuryInfoSection`  | The collapsible information section in the treasury breakdown.      |
| `TreasuryInfoToggle`   | The toggle button for the info section in the treasury breakdown.   |
| `TreasurySummaryRow`   | The summary total row in the treasury breakdown.                    |

## Verify

Account verification flow.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			VerifyLayout: {
				display: "grid",
				gap: "16px",
			},
			VerifyHeader: {
				fontSize: "20px",
				fontWeight: "600",
			},
		},
	},
});
```

| Class            | Description                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `VerifyAside`    | The sidebar navigation area of the verification flow.                                         |
| `VerifyContent`  | The content column wrapper of the verification flow, containing step views and the footer.    |
| `VerifyFooter`   | The footer area with navigation buttons in the verification flow.                             |
| `VerifyHeader`   | The header area of the verification flow.                                                     |
| `VerifyInfoForm` | The additional information form within the verification flow.                                 |
| `VerifyLayout`   | The main flex layout container holding the sidebar and content area of the verification flow. |
| `VerifyNav`      | The step navigation list in the verification sidebar.                                         |
| `VerifyNavItem`  | A single step item in the verification navigation.                                            |

## Withdraw

Withdraw flow element and currency picker.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			WithdrawFormRoot: {
				padding: "16px",
			},
			WithdrawHeader: {
				fontSize: "18px",
				fontWeight: "600",
			},
		},
	},
});
```

| Class                      | Description                                                                                                      |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `WithdrawCreateTokenPanel` | The panel containing the create payout token form within the withdrawal view.                                    |
| `WithdrawCurrencyInfo`     | The currency detail text in a withdrawal currency row.                                                           |
| `WithdrawCurrencyList`     | The currency picker list in the withdrawal flow.                                                                 |
| `WithdrawCurrencyRow`      | A single currency option in the withdrawal currency picker.                                                      |
| `WithdrawCurrencyRowLeft`  | The left content area of a withdrawal currency row.                                                              |
| `WithdrawFormPanel`        | The main form panel within the withdrawal request view.                                                          |
| `WithdrawFormRoot`         | The root container of the withdrawal request form.                                                               |
| `WithdrawHeader`           | The header of the withdrawal dialog.                                                                             |
| `WithdrawInfoRow`          | An info row displaying a label-value pair in the withdrawal form (e.g. Fees, Exchange rate, Estimated delivery). |
| `WithdrawSpeedFooter`      | The footer area of the withdrawal speed selector.                                                                |
| `WithdrawSpeedFooterText`  | The footer description text of the withdrawal speed selector.                                                    |
| `WithdrawSpeedHeader`      | The header of a withdrawal speed option.                                                                         |
| `WithdrawSpeedPrimary`     | The primary label of a withdrawal speed option.                                                                  |
| `WithdrawSpeedRoot`        | The root container of the withdrawal speed selector.                                                             |
| `WithdrawSpeedSecondary`   | The secondary description of a withdrawal speed option.                                                          |
| `WithdrawSpeedText`        | The text container within a withdrawal speed option.                                                             |

## Withdrawals

Withdrawals history table.

```typescript theme={null}
new WhopElements({
	appearance: {
		classes: {
			WithdrawalsRow: {
				borderBottom: "1px solid var(--gray-5)",
			},
			"WithdrawalsRow:hover": {
				backgroundColor: "var(--gray-2)",
			},
		},
	},
});
```

| Class                        | Description                                                               |
| ---------------------------- | ------------------------------------------------------------------------- |
| `WithdrawalsAmountCell`      | The amount column cell in the withdrawals table.                          |
| `WithdrawalsArrivalCell`     | The estimated arrival column cell in the withdrawals table.               |
| `WithdrawalsBody`            | The body section of the withdrawals table.                                |
| `WithdrawalsCell`            | A data cell in the withdrawals table.                                     |
| `WithdrawalsDateCell`        | The date column cell in the withdrawals table.                            |
| `WithdrawalsDestinationCell` | The destination column cell in the withdrawals table.                     |
| `WithdrawalsFooter`          | The footer area of the withdrawals table, containing pagination controls. |
| `WithdrawalsHeaderCell`      | A column header cell in the withdrawals table.                            |
| `WithdrawalsReceiptCell`     | The receipt column cell in the withdrawals table.                         |
| `WithdrawalsRow`             | A row in the withdrawals table representing a single withdrawal.          |
| `WithdrawalsStatusCell`      | The status column cell in the withdrawals table.                          |


# TreasuryBreakdownElement
Source: https://docs.whop.com/sdk/elements/treasury-breakdown-element

A UI element that displays a breakdown of treasury funds including crypto portfolio holdings.

## Overview

A UI element that displays a breakdown of treasury funds including crypto portfolio holdings.

This element provides a detailed view of treasury funds, including:

* Crypto portfolio holdings and their current values
* Total treasury balance
* Close action to dismiss the breakdown

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("treasury-breakdown-element", {
  onClose: (ev) => {
    console.log("Breakdown closed");
  },
});

// Mount it to a container
element.mount("#breakdown-container");
```

### Using as a modal

```typescript theme={null}
// Show the breakdown in a modal overlay
const modal = session.showTreasuryBreakdownModal({
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("treasury-breakdown-element", {});

element.on("ready", () => {
  console.log("Breakdown loaded");
});

element.on("close", (ev) => {
  console.log("User closed the breakdown");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("treasury-breakdown-element", {
  onReady: (element) => {
    console.log("Breakdown is ready");
  },
  onClose: (ev) => {
    console.log("User closed the breakdown");
  },
});
```

## Events

Events emitted by the TreasuryBreakdownElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `TreasuryBreakdownElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`TreasuryBreakdownElementOptions`](#treasurybreakdownelementoptions)) => void

### `close`

Emitted when the user closes the breakdown view.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`TreasuryBreakdownElementSnapshot`](#treasurybreakdownelementsnapshot)) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                              | Description                                      |
| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`TreasuryBreakdownElementOptions`](#treasurybreakdownelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`TreasuryBreakdownElementSnapshot`](#treasurybreakdownelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### TreasuryBreakdownElementOptions

Configuration options for the TreasuryBreakdownElement.

| Property  | Type                                                         | Required | Default | Description                                                                                                                                              |
| --------- | ------------------------------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady` | `((element: TreasuryBreakdownElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                 |
| `onClose` | `((ev: CustomEvent) => void) \| undefined`                   | No       | -       | Callback fired when the user closes the breakdown view. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted. |

### TreasuryBreakdownElementSnapshot

Represents the current state of the TreasuryBreakdownElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# Types
Source: https://docs.whop.com/sdk/elements/types

Shared type definitions for Whop embedded components

## Overview

This page documents the shared types used across Whop embedded components.

## EmbeddableElement

| Property  | Type                                             | Required | Default | Description |
| --------- | ------------------------------------------------ | -------- | ------- | ----------- |
| `mount`   | `(element: HTMLElement \| '#${string}') => void` | Yes      | -       | -           |
| `unmount` | `() => void`                                     | Yes      | -       | -           |

## CSSValue

A CSS property value.

```typescript theme={null}

type CSSValue = string

```

## CSSProps

A record of CSS properties and their values.

```typescript theme={null}

type CSSProps = { [x: string]: string; }

```

## Classes

A record of CSS class names to their style definitions.

```typescript theme={null}

type Classes = { [x: string]: CSSProps; }

```

See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names applied to embedded components.

## Variables

CSS custom properties (variables) that can be used to customize element styles.
Keys must start with `--` prefix.

```typescript theme={null}

type Variables = { [x: `--${string}`]: string; }

```

## AccentColor

Available accent colors for theming elements.

These colors are used for primary UI elements like buttons, links, and highlights.

```typescript theme={null}

type AccentColor = "ruby" | "blue" | "red" | "yellow" | "green" | "gray" | "tomato" | "crimson" | "pink" | "plum" | "purple" | "violet" | "iris" | "cyan" | "teal" | "jade" | "grass" | "brown" | "orange" | "indigo" | "sky" | "mint" | "amber" | "lime" | "lemon" | "magenta" | "gold" | "bronze"

```

## Theme

Theme configuration for customizing the visual appearance of elements.

```typescript theme={null}
const theme: Theme = {
  appearance: "dark",
  accentColor: "blue",
  grayColor: "slate",
};
```

| Property       | Type                                                                                 | Required | Default | Description                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `appearance`   | `"light" \| "dark" \| undefined`                                                     | No       | -       | The color scheme to use. - '"light"' - Light mode with dark text on light backgrounds - '"dark"' - Dark mode with light text on dark backgrounds |
| `accentColor`  | [`AccentColor`](#accentcolor) \| undefined                                           | No       | -       | The primary accent color used for interactive elements.                                                                                          |
| `grayColor`    | `"gray" \| "mauve" \| "slate" \| "sage" \| "olive" \| "sand" \| "auto" \| undefined` | No       | -       | The gray color palette to use for neutral elements. Use '"auto"' to automatically match the accent color.                                        |
| `dangerColor`  | `"ruby" \| "red" \| "tomato" \| undefined`                                           | No       | -       | The color used for error states and destructive actions.                                                                                         |
| `warningColor` | `"yellow" \| "amber" \| undefined`                                                   | No       | -       | The color used for warning states.                                                                                                               |
| `successColor` | `"green" \| "teal" \| "jade" \| "grass" \| undefined`                                | No       | -       | The color used for success states.                                                                                                               |
| `infoColor`    | `"blue" \| "sky" \| undefined`                                                       | No       | -       | The color used for informational states.                                                                                                         |

## Appearance

Configuration for customizing the visual appearance of Whop elements.

Use this to match the embedded components to your application's design.

```typescript theme={null}
const appearance: Appearance = {
  theme: {
    appearance: "dark",
    accentColor: "blue",
  },
};

const whopElements = new WhopElements({ appearance });
```

| Property    | Type                                           | Required | Default | Description                                       |
| ----------- | ---------------------------------------------- | -------- | ------- | ------------------------------------------------- |
| `variables` | [`Variables`](#variables) \| null \| undefined | No       | -       | CSS custom properties to override default styles. |
| `classes`   | [`Classes`](#classes) \| null \| undefined     | No       | -       | Custom CSS classes to apply to elements.          |
| `theme`     | [`Theme`](#theme) \| null \| undefined         | No       | -       | Theme settings for colors and appearance mode.    |

## WhopElementsEnvironment

The environment to use for API calls.

* `"production"` - Use the live production API
* `"sandbox"` - Use the sandbox API for testing

```typescript theme={null}

type WhopElementsEnvironment = "production" | "sandbox"

```

## WhopElementsOptions

Configuration options for initializing WhopElements.

```typescript theme={null}
const whopElements = new WhopElements({
  appearance: {
    theme: { appearance: "light" },
  },
  locale: "en",
  environment: "production",
});
```

| Property      | Type                                                                                                | Required | Default      | Description                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `appearance`  | [`Appearance`](#appearance) \| undefined                                                            | No       | -            | Customize the appearance of the Whop embedded Elements. Includes theme settings like light/dark mode and accent colors. |
| `locale`      | `"en" \| "es" \| "zh" \| "nl" \| "pt" \| "de" \| "it" \| "fr" \| "ja" \| "pl" \| "tr" \| undefined` | No       | "en"         | The locale to use for all Elements. Controls the language and formatting of text, dates, and numbers.                   |
| `environment` | [`WhopElementsEnvironment`](#whopelementsenvironment) \| undefined                                  | No       | "production" | The environment to use for API calls. Use '"sandbox"' for testing without affecting production data.                    |


# VerifyElement
Source: https://docs.whop.com/sdk/elements/verify-element

A UI element that guides users through identity verification (KYC) and compliance requirements.

## Overview

A UI element that guides users through identity verification (KYC) and compliance requirements.

This element handles the complete verification flow, including:

* Collecting personal information
* Document upload and verification
* Identity verification checks
* Compliance questionnaires

The verification process is required before users can withdraw funds.

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("verify-element", {
  onVerificationSubmitted: () => {
    console.log("Verification submitted!");
  },
});

// Mount it to a container
element.mount("#verify-container");
```

### Using as a modal

```typescript theme={null}
// Show the element in a modal overlay
const modal = session.showVerifyModal({
  onVerificationSubmitted: (ev) => {
    console.log("Verification complete!");
    // Element auto-unmounts by default
  },
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Inline with controls

```typescript theme={null}
// Embed the element with its own navigation controls
const element = session.createElement("verify-element", {
  includeControls: true,
  onVerificationSubmitted: (ev) => {
    ev.preventDefault(); // Keep mounted
    showSuccessMessage();
  },
});

element.mount("#verification-section");
```

### Listening to events

```typescript theme={null}
const element = session.createElement("verify-element", {});

element.on("ready", () => {
  console.log("Verification form loaded");
});

element.on("verificationSubmitted", (ev) => {
  console.log("Verification submitted!");
});

element.on("close", (ev) => {
  console.log("User closed the form");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("verify-element", {
  includeControls: true,
  onReady: (element) => {
    console.log("Verification form is ready");
  },
  onVerificationSubmitted: (ev) => {
    console.log("Verification submitted!");
  },
  onClose: (ev) => {
    console.log("User closed the form");
  },
});
```

## Events

Events emitted by the VerifyElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `VerifyElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`VerifyElementOptions`](#verifyelementoptions)) => void

### `close`

Emitted when the user closes the verification form without completing it.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`VerifyElementSnapshot`](#verifyelementsnapshot)) => void

### `verificationSubmitted`

Emitted when the user successfully submits their verification information.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`VerifyElement`>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                        | Description                                      |
| --------- | ----------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`VerifyElementOptions`](#verifyelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`VerifyElementSnapshot`](#verifyelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### VerifyElementOptions

Configuration options for the VerifyElement.

| Property                  | Type                                                      | Required | Default | Description                                                                                                                                                                                   |
| ------------------------- | --------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `includeControls`         | `boolean \| undefined`                                    | No       | false   | Whether to include navigation controls (back/close buttons) in the element. Set to 'true' when embedding the element inline, or 'false' when using in a modal that provides its own controls. |
| `onReady`                 | `((element: VerifyElement) => void) \| undefined`         | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                                      |
| `onVerificationSubmitted` | `((ev: CustomEvent<VerifyElement>) => void) \| undefined` | No       | -       | Callback fired when the user successfully submits their verification information. By default, the element will unmount after submission. Call 'ev.preventDefault()' to keep it mounted.       |
| `onClose`                 | `((ev: CustomEvent) => void) \| undefined`                | No       | -       | Callback fired when the user closes the verification form without completing it. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted.             |

### VerifyElementSnapshot

Represents the current state of the VerifyElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# Create a wallet session
Source: https://docs.whop.com/sdk/elements/wallet-session

Manages authentication and creates wallet elements.

## Overview

Manages authentication and creates wallet elements.

The WalletSession handles token management, element creation, and provides
convenience methods for showing wallet elements in modals.

For v1, mint the token via the existing `whop.accessTokens.create({ company_id })` flow —
the same backend mutation that powers `PayoutsSession`. No new mutation is required.

## Examples

### Basic usage

```typescript theme={null}
const session = whopElements.createWalletSession({
  companyId: "biz_xxx",
  token: async () => {
    const response = await fetch("/api/wallet-token");
    const data = await response.json();
    return data.token;
  },
});

session.on("ready", () => {
  console.log("Wallet session is ready");
});
```

## Options

| Property    | Type                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------- | --------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`     | `Token \| GetToken`   | Yes      | -       | The token to use for the session. If a function is provided, it will be called and awaited to get the token. When a function is provided, the token will be refreshed automatically before it expires.  if a string is provided, it will be used as the token and not refreshed automatically. However you can update the token at runtime by calling 'updateOptions' with a new token.  For v1, mint this token from your backend with the existing 'whop.accessTokens.create()' call — the same approach used by 'PayoutsSession'. A dedicated 'wallet:\*' scope set is on the roadmap. |
| `companyId` | `string`              | Yes      | -       | The company ID that owns the wallet.  Accepts a 'biz\_\*' ID. The wallet's underlying ledger account is resolved server-side from this value. (A polymorphic 'ledger\_account\_id' parameter is on the roadmap once 'wallet:session:create' ships.)                                                                                                                                                                                                                                                                                                                                       |
| `currency`  | `string \| undefined` | No       | "USD"   | The currency to format display amounts in.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Events

Events emitted by the WalletSession.

Listen to these events using the `on()` method.

### `optionsUpdated`

Emitted when the session options are updated via `updateOptions()`.

**Callback signature:** (options: `ExpandedWalletSessionOptions`) => void

### `tokenRefreshed`

Emitted when the authentication token is refreshed.

**Callback signature:** (token: `string`) => void

### `tokenRefreshError`

Emitted when token refresh fails.

**Callback signature:** (error: `unknown`) => void

### `error`

Emitted when an error occurs during session operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the session is ready and authenticated.

**Callback signature:** (`void`) => void

## Methods

### `createElement(type, options)`

Create a new element instance.

| Parameter | Type                          | Description                                |
| --------- | ----------------------------- | ------------------------------------------ |
| `type`    | T \| \{ type: T; }            | The element type (e.g., "deposit-element") |
| `options` | WalletSessionElements\[T]\[0] | Element-specific configuration options     |

**Returns:** `WalletSessionElements[T][1]`

```typescript theme={null}
const element = session.createElement("deposit-element", {
  onDeposit: () => console.log("Deposit flow finished"),
});
element.mount("#container");
```

### `updateOptions(options)`

Update the session options after initialization.

Changes will be propagated to all active elements.

| Parameter | Type                           | Description                                      |
| --------- | ------------------------------ | ------------------------------------------------ |
| `options` | Partial\<WalletSessionOptions> | Partial options object with the values to update |

### `destroy()`

Destroy the session and clean up all mounted elements.

Call this when you no longer need the session to free up resources.

### Modal Methods

#### `showDepositModal(options, force)`

Show the deposit element in a modal overlay.

By default, the modal auto-closes on dismiss (`onClose`). `onDeposit` fires
when the user continues past amount entry and keeps the modal open so the
transfer instructions stay visible.
Call `ev.preventDefault()` in the close callback to prevent auto-close.

| Parameter | Type                                                                                                                                                                                                       | Description                                                     |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `options` | [`DepositElementOptions`](/sdk/elements/deposit-element#depositelementoptions) \| ((modal: ModalContainer) => [`DepositElementOptions`](/sdk/elements/deposit-element#depositelementoptions)) \| undefined | Element options or a callback that receives the modal container |
| `force`   | Force \| undefined                                                                                                                                                                                         | -                                                               |

**Returns:** `Force extends true ? ModalContainer : ModalContainer | undefined`


# Getting Started
Source: https://docs.whop.com/sdk/elements/whop-elements

The main entry point for Whop embedded components.

## Overview

The main entry point for Whop embedded components.

WhopElements is the root object that manages configuration and creates sessions
for different element types. Initialize it once and use it to create sessions
for payouts, payments, and other embedded experiences.

## Installation

<CodeGroup>
  ```bash React theme={null}
  npm install @whop/embedded-components-vanilla-js @whop/embedded-components-react-js
  ```

  ```bash Vanilla JS theme={null}
  npm install @whop/embedded-components-vanilla-js
  ```
</CodeGroup>

## Examples

### Basic initialization

```typescript theme={null}
import WhopElements from "@whop/embeddable-components";

const whopElements = new WhopElements({
  appearance: {
    theme: { appearance: "light" },
  },
  locale: "en",
});
```

### Creating a payouts session

```typescript theme={null}
const session = whopElements.createPayoutsSession({
  token: async () => {
    // Fetch token from your backend
    const response = await fetch("/api/payouts-token");
    const data = await response.json();
    return data.token;
  },
  companyId: "your-company-id",
  redirectUrl: "https://yourapp.com/callback",
});

// Create and mount an element
const element = session.createElement("balance-element", {});
element.mount("#balance-container");
```

### Updating options after initialization

```typescript theme={null}
// Switch to dark mode
whopElements.updateOptions({
  appearance: {
    theme: { appearance: "dark" },
  },
});
```

### Listening to option changes

```typescript theme={null}
whopElements.on("optionsUpdated", (options) => {
  console.log("Options changed:", options);
});
```

## Options

| Property      | Type                                                                                                | Required | Default      | Description                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `appearance`  | [`Appearance`](/sdk/elements/types#appearance) \| undefined                                         | No       | -            | Customize the appearance of the Whop embedded Elements. Includes theme settings like light/dark mode and accent colors. |
| `locale`      | `"en" \| "es" \| "zh" \| "nl" \| "pt" \| "de" \| "it" \| "fr" \| "ja" \| "pl" \| "tr" \| undefined` | No       | "en"         | The locale to use for all Elements. Controls the language and formatting of text, dates, and numbers.                   |
| `environment` | [`WhopElementsEnvironment`](/sdk/elements/types#whopelementsenvironment) \| undefined               | No       | "production" | The environment to use for API calls. Use '"sandbox"' for testing without affecting production data.                    |

## Events

Events emitted by WhopElements.

Listen to these events using the `on()` method.

### `optionsUpdated`

Emitted when the WhopElements options are updated via `updateOptions()`.

**Callback signature:** (options: [`WhopElementsOptions`](/sdk/elements/types#whopelementsoptions)) => void

## Methods

### `createPayoutsSession(options)`

Create a new payouts session for managing payout elements.

The session handles authentication and provides methods to create
payout-related elements like balance displays, withdrawal forms, and more.

| Parameter | Type                    | Description                                   |
| --------- | ----------------------- | --------------------------------------------- |
| `options` | `PayoutsSessionOptions` | Configuration options for the payouts session |

**Returns:** [`PayoutsSession`](/sdk/elements/payouts-session)

### `createChatSession(options)`

Create a new chat session for managing chat elements.

| Parameter | Type                 | Description                                |
| --------- | -------------------- | ------------------------------------------ |
| `options` | `ChatSessionOptions` | Configuration options for the chat session |

**Returns:** [`ChatSession`](/sdk/elements/chat-session)

### `createWalletSession(options)`

Create a new wallet session for managing wallet elements.

The session handles authentication and provides methods to create
wallet-related elements like balance displays, send/receive flows, and conversions.

| Parameter | Type                   | Description                                  |
| --------- | ---------------------- | -------------------------------------------- |
| `options` | `WalletSessionOptions` | Configuration options for the wallet session |

**Returns:** [`WalletSession`](/sdk/elements/wallet-session)

### `updateOptions(options)`

Update the WhopElements configuration after initialization.

Changes will be propagated to all active sessions and elements.
Only the provided options will be updated; others remain unchanged.

| Parameter | Type                                                                       | Description                                      |
| --------- | -------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | Partial\<[`WhopElementsOptions`](/sdk/elements/types#whopelementsoptions)> | Partial options object with the values to update |

## Related Types

* [WhopElementsOptions](/sdk/elements/types#whopelementsoptions)
* [WhopElementsEnvironment](/sdk/elements/types#whopelementsenvironment)
* [Appearance](/sdk/elements/types#appearance)
* [Theme](/sdk/elements/types#theme)
* [AccentColor](/sdk/elements/types#accentcolor)


# WithdrawButtonElement
Source: https://docs.whop.com/sdk/elements/withdraw-button-element

A UI element that renders a button for initiating withdrawals.

## Overview

A UI element that renders a button for initiating withdrawals.

This element provides a convenient one-click withdrawal experience:

* Shows current available balance
* Automatically handles verification if required
* Opens withdrawal modal when clicked
* Supports customizable styling

The button intelligently routes users to verification or withdrawal based on their account status.

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("withdraw-button-element", {
  onWithdrawalRequested: () => {
    console.log("Withdrawal initiated!");
  },
});

// Mount it to a container
element.mount("#withdraw-button-container");
```

### Customized button

```typescript theme={null}
const element = session.createElement("withdraw-button-element", {
  size: "4",
  variant: "solid",
  highContrast: true,
  onWithdrawalRequested: (ev) => {
    console.log("Withdrawal requested!");
  },
});

element.mount("#withdraw-button-container");
```

### Handling verification

```typescript theme={null}
const element = session.createElement("withdraw-button-element", {
  onVerificationSubmitted: (ev) => {
    console.log("User completed verification!");
  },
  onWithdrawalRequested: (ev) => {
    console.log("Withdrawal requested!");
  },
});

// Custom verify handling
element.on("verify", (ev) => {
  ev.preventDefault(); // Handle verification yourself
  showCustomVerificationFlow();
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("withdraw-button-element", {
  size: "3",
  variant: "solid",
  onReady: (element) => {
    console.log("Button is ready");
  },
  onWithdrawalRequested: (ev) => {
    console.log("Withdrawal requested!");
  },
});
```

## Events

Events emitted by the WithdrawButtonElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `WithdrawButtonElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`WithdrawButtonElementOptions`](#withdrawbuttonelementoptions)) => void

### `verify`

Emitted when the user clicks the button and needs to verify their identity first.
By default, opens the verification modal. Call `ev.preventDefault()` to handle this yourself.

**Callback signature:** (ev: `CustomEvent`\<`WithdrawButtonElement`>) => void

### `withdraw`

Emitted when the user clicks the button to initiate a withdrawal.
By default, opens the withdrawal modal. Call `ev.preventDefault()` to handle this yourself.

**Callback signature:** (ev: `CustomEvent`\<`WithdrawButtonElement`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`WithdrawButtonElementSnapshot`](#withdrawbuttonelementsnapshot)) => void

### `verificationSubmitted`

Emitted when the user successfully submits verification through the modal opened by this button.

**Callback signature:** (ev: `CustomEvent`\<`WithdrawButtonElement`>) => void

### `withdrawalRequested`

Emitted when the user successfully requests a withdrawal through the modal opened by this button.

**Callback signature:** (ev: `CustomEvent`\<`WithdrawButtonElement`>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                        | Description                                      |
| --------- | --------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`WithdrawButtonElementOptions`](#withdrawbuttonelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`WithdrawButtonElementSnapshot`](#withdrawbuttonelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### WithdrawButtonElementOptions

Configuration options for the WithdrawButtonElement.

| Property                  | Type                                                                  | Required | Default | Description                                                                                                                                                                                                                                                                                         |
| ------------------------- | --------------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hidePendingBalance`      | `boolean \| undefined`                                                | No       | false   | Whether to hide the pending balance from the button display.                                                                                                                                                                                                                                        |
| `onReady`                 | `((element: WithdrawButtonElement) => void) \| undefined`             | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                                                                                                                                            |
| `onVerificationSubmitted` | `((ev: CustomEvent<WithdrawButtonElement>) => void) \| undefined`     | No       | -       | Callback fired when the user successfully submits verification through this button's flow.                                                                                                                                                                                                          |
| `onWithdrawalRequested`   | `((ev: CustomEvent<WithdrawButtonElement>) => void) \| undefined`     | No       | -       | Callback fired when the user successfully requests a withdrawal through this button's flow.                                                                                                                                                                                                         |
| `size`                    | `"1" \| "2" \| "3" \| "4" \| undefined`                               | No       | -       | The size of the button. - '"1"' - Extra small - '"2"' - Small - '"3"' - Medium (default) - '"4"' - Large                                                                                                                                                                                            |
| `variant`                 | `"solid" \| "soft" \| "surface" \| "ghost" \| "classic" \| undefined` | No       | -       | The visual variant of the button. - '"solid"' - Filled background - '"soft"' - Subtle background - '"surface"' - Surface-level emphasis - '"ghost"' - No background - '"classic"' - Traditional button style                                                                                        |
| `color`                   | `AccentColor \| undefined`                                            | No       | -       | The accent color for the button.                                                                                                                                                                                                                                                                    |
| `highContrast`            | `boolean \| undefined`                                                | No       | false   | Whether to use high contrast mode for better accessibility.                                                                                                                                                                                                                                         |
| `showIcon`                | `boolean \| undefined`                                                | No       | false   | Whether to show an icon in the button.                                                                                                                                                                                                                                                              |
| `showCurrencySelector`    | `boolean \| undefined`                                                | No       | -       | When true, the withdrawal modal opened by this button shows a currency picker first. This allows the user to choose which currency to withdraw from when they have balances in multiple currencies. The session's default currency will be omitted so the picker can display all available options. |

### WithdrawButtonElementSnapshot

Represents the current state of the WithdrawButtonElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# WithdrawElement
Source: https://docs.whop.com/sdk/elements/withdraw-element

A UI element that provides a complete withdrawal form for users to request fund transfers.

## Overview

A UI element that provides a complete withdrawal form for users to request fund transfers.

This element handles the full withdrawal flow, including:

* Displaying available balance
* Selecting withdrawal amount
* Choosing payout method
* Confirming and submitting the withdrawal request

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("withdraw-element", {
  onWithdraw: () => {
    console.log("Withdrawal submitted!");
  },
});

// Mount it to a container
element.mount("#withdraw-container");
```

### Using as a modal

```typescript theme={null}
// Show the withdrawal form in a modal overlay
const modal = session.showWithdrawModal({
  onWithdraw: (ev) => {
    console.log("Withdrawal submitted!");
    // Element auto-unmounts by default
  },
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("withdraw-element", {});

element.on("ready", () => {
  console.log("Form loaded");
});

element.on("withdraw", (ev) => {
  console.log("Withdrawal submitted!");
  ev.preventDefault(); // Keep mounted
  showSuccessMessage();
});

element.on("close", (ev) => {
  console.log("User cancelled");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("withdraw-element", {
  onReady: (element) => {
    console.log("Withdrawal form is ready");
  },
  onWithdraw: (ev) => {
    console.log("Withdrawal requested!");
  },
  onClose: (ev) => {
    console.log("User cancelled");
  },
});
```

## Events

Events emitted by the WithdrawElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `WithdrawElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`WithdrawElementOptions`](#withdrawelementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`WithdrawElementSnapshot`](#withdrawelementsnapshot)) => void

### `close`

Emitted when the user closes the withdrawal form without completing it.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `withdraw`

Emitted when the user successfully submits a withdrawal request.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                            | Description                                      |
| --------- | --------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`WithdrawElementOptions`](#withdrawelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`WithdrawElementSnapshot`](#withdrawelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### WithdrawElementOptions

Configuration options for the WithdrawElement.

| Property               | Type                                                | Required | Default | Description                                                                                                                                                                                                                                                                   |
| ---------------------- | --------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady`              | `((element: WithdrawElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                                                                                                                                      |
| `onWithdraw`           | `((ev: CustomEvent) => void) \| undefined`          | No       | -       | Callback fired when the user successfully submits a withdrawal request. By default, the element will unmount after the request. Call 'ev.preventDefault()' to keep it mounted.                                                                                                |
| `onClose`              | `((ev: CustomEvent) => void) \| undefined`          | No       | -       | Callback fired when the user closes the withdrawal form without completing it. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted.                                                                                               |
| `showCurrencySelector` | `boolean \| undefined`                              | No       | -       | When true, shows a currency picker before the withdrawal form. This allows the user to choose which currency to withdraw from when they have balances in multiple currencies. The session's default currency will be omitted so the picker can display all available options. |

### WithdrawElementSnapshot

Represents the current state of the WithdrawElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# WithdrawalBreakdownElement
Source: https://docs.whop.com/sdk/elements/withdrawal-breakdown-element

A UI element that displays a detailed breakdown of a specific withdrawal.

## Overview

A UI element that displays a detailed breakdown of a specific withdrawal.

This element shows comprehensive information about a withdrawal, including:

* Withdrawal amount
* Fees and deductions
* Destination payout method
* Status and timeline
* Transaction details

## Usage

### Basic usage

```typescript theme={null}
// Create the element with a specific withdrawal ID
const element = session.createElement("withdrawal-breakdown-element", {
  withdrawalId: "withdrawal_abc123",
  onClose: () => {
    console.log("Breakdown closed");
  },
});

// Mount it to a container
element.mount("#withdrawal-breakdown-container");
```

### Using as a modal

```typescript theme={null}
// Show the breakdown in a modal overlay
const modal = session.showWithdrawalBreakdownModal({
  withdrawalId: "withdrawal_abc123",
  onClose: (ev) => {
    ev.preventDefault();
    modal.close();
  },
});
```

### Listening to events

```typescript theme={null}
const element = session.createElement("withdrawal-breakdown-element", {
  withdrawalId: "withdrawal_abc123",
});

element.on("ready", () => {
  console.log("Breakdown loaded");
});

element.on("close", (ev) => {
  console.log("User closed the breakdown");
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("withdrawal-breakdown-element", {
  withdrawalId: "withdrawal_abc123",
  onReady: (element) => {
    console.log("Breakdown is ready");
  },
  onClose: (ev) => {
    console.log("User closed the breakdown");
  },
});
```

## Events

Events emitted by the WithdrawalBreakdownElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `WithdrawalBreakdownElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`WithdrawalBreakdownElementOptions`](#withdrawalbreakdownelementoptions)) => void

### `close`

Emitted when the user closes the breakdown view.
Call `ev.preventDefault()` to prevent the element from automatically unmounting.

**Callback signature:** (ev: `CustomEvent`\<`any`>) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`WithdrawalBreakdownElementSnapshot`](#withdrawalbreakdownelementsnapshot)) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                                  | Description                                      |
| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`WithdrawalBreakdownElementOptions`](#withdrawalbreakdownelementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`WithdrawalBreakdownElementSnapshot`](#withdrawalbreakdownelementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### WithdrawalBreakdownElementOptions

Configuration options for the WithdrawalBreakdownElement.

| Property       | Type                                                           | Required | Default | Description                                                                                                                                              |
| -------------- | -------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `withdrawalId` | `string`                                                       | Yes      | -       | The ID of the withdrawal to show the breakdown for. This is required to identify which withdrawal's details to display.                                  |
| `onReady`      | `((element: WithdrawalBreakdownElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event.                 |
| `onClose`      | `((ev: CustomEvent) => void) \| undefined`                     | No       | -       | Callback fired when the user closes the breakdown view. By default, the element will unmount when closed. Call 'ev.preventDefault()' to keep it mounted. |

### WithdrawalBreakdownElementSnapshot

Represents the current state of the WithdrawalBreakdownElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# WithdrawalsElement
Source: https://docs.whop.com/sdk/elements/withdrawals-element

A UI element that displays a list of the user's past withdrawals.

## Overview

A UI element that displays a list of the user's past withdrawals.

This element provides a comprehensive view of withdrawal history, including:

* List of all withdrawals with status, amount, and date
* Ability to view detailed breakdown for each withdrawal
* Option to generate receipts for completed withdrawals
* Pagination for large withdrawal histories

## Usage

### Basic usage

```typescript theme={null}
// Create the element
const element = session.createElement("withdrawals-element", {
  onReady: () => {
    console.log("Withdrawals list loaded");
  },
});

// Mount it to a container
element.mount("#withdrawals-container");
```

### Custom breakdown handling

```typescript theme={null}
const element = session.createElement("withdrawals-element", {});

element.on("showWithdrawalBreakdown", (ev) => {
  // Prevent default modal
  ev.preventDefault();
  // Show your own breakdown UI
  showCustomBreakdown(ev.detail.withdrawalId);
});

element.on("showGenerateWithdrawalReceipt", (ev) => {
  // Prevent default modal
  ev.preventDefault();
  // Handle receipt generation yourself
  generateReceipt(ev.detail.withdrawalId);
});

element.mount("#withdrawals-container");
```

### Listening to events

```typescript theme={null}
const element = session.createElement("withdrawals-element", {});

element.on("ready", () => {
  console.log("Withdrawals list loaded");
});

element.on("showWithdrawalBreakdown", (ev) => {
  console.log("User viewing withdrawal:", ev.detail.withdrawalId);
  // Let default modal open
});

element.mount("#container");
```

```typescript theme={null}
const element = session.createElement("withdrawals-element", {
  onReady: (element) => {
    console.log("Withdrawals list is ready");
  },
});
```

## Events

Events emitted by the WithdrawalsElement.

Listen to these events using the `on()` method or by passing callback functions in the options.

### `error`

Emitted when an error occurs during element initialization or operation.

**Callback signature:** (error: `unknown`) => void

### `ready`

Emitted when the element has finished loading and is ready for user interaction.

**Callback signature:** (element: `WithdrawalsElement`) => void

### `optionsUpdated`

Emitted when the element's options are updated via `updateOptions()`.

**Callback signature:** (options: [`WithdrawalsElementOptions`](#withdrawalselementoptions)) => void

### `snapshot`

Emitted when the element's internal state changes.

**Callback signature:** (snapshot: [`WithdrawalsElementSnapshot`](#withdrawalselementsnapshot)) => void

### `showWithdrawalBreakdown`

Emitted when the user clicks to view a withdrawal breakdown.
By default, opens the WithdrawalBreakdown modal. Call `ev.preventDefault()` to handle this yourself.

**Callback signature:** (ev: `CustomEvent`\<\{ withdrawalId: `string`; }>) => void

### `showGenerateWithdrawalReceipt`

Emitted when the user clicks to generate a receipt for a withdrawal.
By default, opens the GenerateWithdrawalReceipt modal. Call `ev.preventDefault()` to handle this yourself.

**Callback signature:** (ev: `CustomEvent`\<\{ withdrawalId: `string`; }>) => void

## Methods

### `mount(container)`

Mount the element to a DOM container.

The container must be an empty element. The element will be appended as a child.
If the element is already mounted, this method will log a warning and return.

| Parameter   | Type                              | Description                                               |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| `container` | `HTMLElement` \| `#$\{`string`\}` | The container element or a CSS selector starting with '#' |

```typescript theme={null}
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);
```

### `unmount()`

Remove the element from the DOM and clean up all event listeners.

After unmounting, the element instance should not be reused.
Create a new element instance if you need to mount again.

```typescript theme={null}
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});
```

### `updateOptions(options)`

Update the element's configuration options after creation.

Only the provided options will be updated; other options remain unchanged.
The element will re-render with the new options.

| Parameter | Type                                                                  | Description                                      |
| --------- | --------------------------------------------------------------------- | ------------------------------------------------ |
| `options` | `Partial`\<[`WithdrawalsElementOptions`](#withdrawalselementoptions)> | Partial options object with the values to update |

```typescript theme={null}
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});
```

### `getSnapshot()`

Get the current state snapshot of the element.

The snapshot contains the element's current internal state, such as
loading status, form values, or other element-specific data.

**Returns:** [`WithdrawalsElementSnapshot`](#withdrawalselementsnapshot)

```typescript theme={null}
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});
```

## Styling

Customize this element with `appearance.classes`. See the [styling reference](/sdk/elements/styling-reference) for the full list of stable class names and example snippets.

## Types

### WithdrawalsElementOptions

Configuration options for the WithdrawalsElement.

| Property  | Type                                                   | Required | Default | Description                                                                                                                              |
| --------- | ------------------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady` | `((element: WithdrawalsElement) => void) \| undefined` | No       | -       | Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the 'ready' event. |

### WithdrawalsElementSnapshot

Represents the current state of the WithdrawalsElement.

Use `element.getSnapshot()` to get the current state, or listen to the `snapshot` event for changes.

| Property | Type                   | Required | Default | Description                                                                                                                                     |
| -------- | ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`  | `"ready" \| "loading"` | Yes      | -       | The current loading state of the element. - '"loading"' - The element is initializing - '"ready"' - The element is fully loaded and interactive |


# BillingSetupElement
Source: https://docs.whop.com/elements/upcoming/ads/billing-setup

Which payment methods ad spend bills against: a primary that is charged first, and an optional backup for when it fails. Both are chosen from the methods already saved on the account, and picking one saves it immediately — there is no separate submit. Adding a card opens a card form over your page and returns to the slot that asked for it. The account's own balance appears alongside its cards wherever the account has one.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Ads`](/elements/upcoming/ads/overview) group. Render `<BillingSetupElement />` inside it (React), or call `ads.create('billing-setup', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Ads, BillingSetupElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Ads /* options */>
            <BillingSetupElement />
          </Ads>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const ads = window.WhopElements().ads.create({ /* options */ });
      ads.create('billing-setup').mount('#ads-billing-setup');
    </script>
    ```
  </CodeGroup>
</div>

## Props

*This element takes no consumer props.*

### Direct mode only

*These props exist only on the in-process (direct-mode) component. The hosted embed never carries them, and the element renders without them.*

<ResponseField name="manageUrl" type="direct mode only">
  Adds a link out to the full payment-method manager. Direct mode only: the destination is a Whop-owned page, so it is never offered to an embedded consumer.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<BillingSetupElementProps>) => void`

## Styling

This element exposes no targetable class names. Use `appearance` (theme, accent color, variables) to restyle it.


# CampaignCreatorElement
Source: https://docs.whop.com/elements/upcoming/ads/campaign-creator

The advertising campaign builder: objective and budget, ad groups with their targeting and schedule, and the ads themselves with their creative — the whole flow through to launch. Opens empty to build a new campaign, or on an existing one when you pass `campaignId`.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Ads`](/elements/upcoming/ads/overview) group and opens as a modal overlay: `ads.createOverlay('campaign-creator', { … })`. Consumer props and `on<Event>` callbacks both go in the create options.

<Note>This element is **modal-only**. Open it with `createOverlay`; it has no inline mount.</Note>

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Ads, CampaignCreatorElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Ads /* options */>
            <CampaignCreatorElement onExited={(payload) => console.log("exited", payload)} onLaunched={(payload) => console.log("launched", payload)} />
          </Ads>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const ads = window.WhopElements().ads.create({ /* options */ });
      ads.createOverlay('campaign-creator', {
        onExited: (payload) => console.log("exited", payload),
        onLaunched: (payload) => console.log("launched", payload)
      }).open();
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="campaignId" type="string">
  The campaign (`adcamp_…`) to open. Empty builds a new one. A draft opens where it was left off; a launched campaign opens in edit mode. Defaults to `""`.
</ResponseField>

<ResponseField name="adGroupId" type="string">
  The ad group (`adgrp_…`) to open in focus, within `campaignId`. Ignored when the campaign has no such group, and when `campaignId` is empty. Defaults to `""`.
</ResponseField>

<ResponseField name="adId" type="string">
  The ad (`ad_…`) to open in focus, within `adGroupId`. Ignored when that group has no such ad, and when `adGroupId` is empty. Defaults to `""`.
</ResponseField>

<ResponseField name="initialStep" type="&#x22;ads&#x22; | &#x22;ad-groups&#x22; | &#x22;campaign-settings&#x22;">
  Which step to open on: `campaign-settings`, `ad-groups`, or `ads`. The dashboard deep-links this off its own URL; pass it to drop a merchant straight onto the part they came to change. Read once at mount — moving it later will not walk them between steps. Defaults to `"campaign-settings"`.
</ResponseField>

### Direct mode only

*These props exist only on the in-process (direct-mode) component. The hosted embed never carries them, and the element renders without them.*

<ResponseField name="renderBillingSetup" type="direct mode only">
  Direct mode only. Renders the billing checklist a first launch must clear.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onExited`

The merchant backed out of the builder without launching. Nothing has been discarded — a draft campaign, if one was started, is already saved. An overlay has already closed itself by the time this fires; react to it if your page needs to.

**Signature:** `((payload: Record<string, never>) => void)`

### `onLaunched`

A campaign went live. `firstLaunch` marks the account’s first ever launched campaign, which is what the dashboard uses to show its welcome state. An overlay has already closed itself; this is where you route onward.

**Signature:** `((payload: { campaignId: string; firstLaunch: boolean; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<CampaignCreatorElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                     | Targets                                          |
| ------------------------- | ------------------------------------------------ |
| `.whop-PixelSetupSurface` | The pixel setup wizard root — one step at a time |

```ts theme={null}
const ads = whop.ads.create({
  appearance: {
    classes: {
      'whop-PixelSetupSurface': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
ads.update({
  appearance: {
    classes: { 'whop-PixelSetupSurface': { fontWeight: '700' } }
  }
});
```

In React, pass the same object as the `appearance` prop on `<Ads>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# Ads
Source: https://docs.whop.com/elements/upcoming/ads/overview

An advertising account. Scope it to a company with `accountId` — the ad account underneath is assigned server-side and never surfaces here — then mount `reporting` for what the account spent and what came back, or `campaign-creator` to build a campaign.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

## Playground

Assemble the elements with sample data. Drive the controls, add and arrange elements, and watch events fire live:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Ads } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Ads /* options */>
            {/* mount elements here */}
          </Ads>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const ads = window.WhopElements().ads.create({ /* options */ });
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `whop.ads.create({ … })`, or as props on `<Ads>` in React.

<ResponseField name="accountId" type="string">
  The company (`biz_…`) whose advertising this reads. Required. This is the Whop account, not an ad account. Defaults to `""`.
</ResponseField>

<ResponseField name="accessToken" type="string">
  A scoped token every surface under this handle reads and writes with. Mint it on your server with `POST /v1/access_tokens` and set a fresh one with `update({ accessToken })` before it expires. Each element documents the scopes it needs, so a page mounting one surface can mint for that surface alone; mounting all of them needs `ad_campaign:read`/`:create`, `ad_group:read`, `ad:read`, `stats:read` and the `:update`/`:delete` scopes the table's row actions use. Omitted, the calls carry the viewer's own session, which only answers same-origin.
</ResponseField>

<ResponseField name="appearance" type="Appearance">
  Visual customization for this group's elements. Overrides the global `WhopElements({ appearance })`; change it live with `update({ appearance })`.
</ResponseField>

<ResponseField name="locale" type="WhopElementsLocale">
  Locale for this group's element UI text. One of the app's built locales, overriding the global config; any other value falls back to the default locale.
</ResponseField>

## Events

Pass a callback in the create options / React props.

### `onBillingChanged`

The account's ad-spend payment methods changed and the change is saved. Slot values are the method ids themselves — `payt_…` for a card, `ldgr_…` for a balance; an empty `backup` means none is set.

**Signature:** `((payload: { primary: string; backup: string; }) => void)`

### `onLoadingChange`

Fired when the grouped loading state changes. `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the Ads handle, which is the return of `whop.ads.create({ … })` (vanilla) or `useAds()` (React).

### `update`

Update the handle live: any of its options (`appearance` and `locale` included), propagated to every mounted element. React consumers never call it; updating the namespace component's props does the same.

**Signature:** `(options: Partial<AdsOptions>) => void`

## Returned objects

Live objects returned by the methods above. Hold the reference and call it on your page; these are capabilities, not serializable data.

## `AdsEditTarget`

What a builder href asks to edit, once it has been read back out of the route.

### `campaignId`

**Signature:** `string`

### `adGroupId`

**Signature:** `string | undefined`

### `adId`

**Signature:** `string | undefined`

## `CustomMetricDefinition`

A computed column as anyone outside this module needs it. `id` is deliberately absent — it is a within-render column key (`customMetricColumnVisibility`), never persisted and never meaningful to a caller, so it is minted on the way in rather than carried around.

### `name`

**Signature:** `string`

### `formula`

**Signature:** `string`

### `format`

**Signature:** `"number" | "currency" | "percent"`

### `enabled`

**Signature:** `boolean`

## Elements

The elements this group mounts. Each has its own page:

<CardGroup>
  <Card title="Reporting" href="/elements/upcoming/ads/reporting">
    An advertising account's reporting: what it spent and what came back, over a window, at whatever level you narrow to. Mount `chart`, `table`, or both — they read the same window, the same credit rule and the same selection, so two surfaces side by side can never disagree about what they are showing. *(sub-controller, 3 elements)*
  </Card>

  <Card title="BillingSetupElement" href="/elements/upcoming/ads/billing-setup">
    Which payment methods ad spend bills against: a primary that is charged first, and an optional backup for when it fails. Both are chosen from the methods already saved on the account, and picking one saves it immediately — there is no separate submit. Adding a card opens a card form over your page and returns to the slot that asked for it. The account's own balance appears alongside its cards wherever the account has one.
  </Card>

  <Card title="CampaignCreatorElement" href="/elements/upcoming/ads/campaign-creator">
    The advertising campaign builder: objective and budget, ad groups with their targeting and schedule, and the ads themselves with their creative — the whole flow through to launch. Opens empty to build a new campaign, or on an existing one when you pass `campaignId`.
  </Card>
</CardGroup>

## Flow surfaces

These internal elements open automatically during flows (for example a confirmation or verification step). They are not part of the consumer API, so you never mount, configure, or subscribe to them directly.

* **AddCardElement** (`add-card`): Saves a card for ad spend without charging it, in a dialog over the page. Collects the card and the billing details a card confirm requires, vaults it, and reports it back to the slot that asked. Opened by the billing slots — not mounted directly.


# Reporting
Source: https://docs.whop.com/elements/upcoming/ads/reporting

An advertising account's reporting: what it spent and what came back, over a window, at whatever level you narrow to. Mount `chart`, `table`, or both — they read the same window, the same credit rule and the same selection, so two surfaces side by side can never disagree about what they are showing.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

A **sub-controller** in the [`Ads`](/elements/upcoming/ads/overview) group. In vanilla, mint it with `ads.create('reporting', { … })`. In React, render `<Reporting>` inside `<Ads>`: mounting mints it, unmounting destroys it. Either way you mount its elements off the handle you get back. Calling `destroy()` tears it down, and a later `create('reporting')` starts fresh.

## Preview

A live, interactive demo of this sub-controller's default arrangement with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Ads, Reporting, ChartElement, TableElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Ads /* options */>
            <Reporting>
              <ChartElement />
              <TableElement />
            </Reporting>
          </Ads>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const ads = window.WhopElements().ads.create({ /* options */ });
      const reporting = ads.create('reporting', { /* options */ });
      reporting.create('chart').mount('#ads-reporting-chart');
      reporting.create('table').mount('#ads-reporting-table');
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `ads.create('reporting', { … })`, or as props on `<Reporting>` in React. Parent-injected props never appear here.

<ResponseField name="period" type="&#x22;today&#x22; | &#x22;yesterday&#x22; | &#x22;last_7_days&#x22; | &#x22;last_14_days&#x22; | &#x22;last_30_days&#x22; | &#x22;last_90_days&#x22; | &#x22;all_time&#x22; | &#x22;custom&#x22;">
  The window every surface reports on: `today`, `yesterday`, `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days`, `all_time`, or `custom` (pair it with `customRange`). The chart carries the picker, and it moves this — so a host can drive the window and read it back off `periodChanged`. Defaults to `"last_14_days"`.
</ResponseField>

<ResponseField name="customRange" type="{ from: string; to: string; } | null">
  The explicit window, as ISO 8601 instants, used when `period` is `custom`. Ignored otherwise. Defaults to `null`.
</ResponseField>

<ResponseField name="timezone" type="&#x22;account&#x22; | &#x22;local&#x22;">
  Which of two zones every figure is reported in: `account`, the account's own `preferences.ads_scheduling_timezone`, or `local`, whichever zone the viewer's browser is in. A CHOICE and not a zone, because those two are the only ones the chart's picker offers — a free IANA zone would report figures in one zone while the picker labelled them as another, and the first touch of the picker would lose it. To report in some third zone, change the account's. `account` falls back to the viewer's own when the account has set none. Defaults to `"account"`.
</ResponseField>

<ResponseField name="currency" type="string">
  The ISO currency every amount is converted to and labelled in — `usd`, `eur`. Unset, it defaults to the account's `preferences.ads_reporting_currency`. Defaults to `""`.
</ResponseField>

<ResponseField name="attributionModel" type="&#x22;last_touch&#x22; | &#x22;first_touch&#x22;">
  Which touch in a buyer’s journey gets the credit: `last_touch`, the default, or `first_touch`. Under both, a Whop touch anywhere in the journey wins the Whop bucket — the model only picks the endpoints. The table carries the picker and moves this, so a host can drive it and read it back off `attributionModelChanged`. Defaults to `"last_touch"`.
</ResponseField>

<ResponseField name="campaignIds" type="string[]">
  Narrow reporting to these ad campaigns (`adcamp_…`). Empty reports on the whole account. Overridden by `adGroupIds` or `adIds` when either is set. **Pass one id for an exact figure:** the reporting API scopes by a single source path, so where more than one is given the chart reports on the first alone. Defaults to `[]`.
</ResponseField>

<ResponseField name="adGroupIds" type="string[]">
  Narrow reporting to these ad groups (`adgrp_…`). Takes precedence over `campaignIds`. Same single-id caveat. Defaults to `[]`.
</ResponseField>

<ResponseField name="adIds" type="string[]">
  Narrow reporting to these ads (`ad_…`). The narrowest filter — takes precedence over both others. Same single-id caveat. Defaults to `[]`.
</ResponseField>

<ResponseField name="tab" type="&#x22;ads&#x22; | &#x22;all&#x22; | &#x22;campaigns&#x22; | &#x22;ad-groups&#x22;">
  Which table the `table` element opens on: `campaigns`, `ad-groups`, `ads`, or `all` for the traffic-source view. `all` always reports account-wide — the source series exists only at that level — so a filter set alongside it narrows the table but not the chart. Defaults to `"campaigns"`.
</ResponseField>

<ResponseField name="sources" type="string[] | null">
  Which traffic the chart reports on, as source paths — `whop:*` for advertising bought through Whop, `ext:*` and `ext:<platform>:*` for ads run elsewhere, `referrer:*` for organic, `direct`, `other`. `null`, the default, reports on Whop advertising alone; `[]` reports on every source; a non-empty array reports on those. A DIFFERENT axis to `campaignIds` and friends, which narrow within Whop advertising — spend-derived ratios stay Whop-attributed whatever this is set to, because spend only ever bought Whop ads. The `table` element’s All tab moves it. Defaults to `null`.
</ResponseField>

## Events

Pass a callback in the create options / React props.

### `onEditRequested`

The viewer asked to edit something — a row menu, a draft row, or Edit ad in the details overlay. `campaignId` is always there; `adGroupId` and `adId` narrow it to what they clicked. Only raised when `useCampaignCreator` is off; on, the builder opens over the page instead and this stays quiet.

**Signature:** `((payload: AdsEditTarget) => void)`

### `onLoadingChange`

Fired when the grouped loading state changes. `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the minted sub handle, which is the return of `ads.create('reporting', { … })`.

### `update`

Live-update the sub-controller's consumer props and `on<Event>` callbacks.

**Signature:** `(options: Partial<ReportingSubOptions>) => void`

### `destroy`

Tear the sub-controller down: its mounted elements are destroyed, its runtime state is discarded, and its exclusive slot is freed, and a later `create("reporting")` boots fresh.

**Signature:** `() => void`

## Elements

The elements this sub-controller mounts. Each has its own page:

<CardGroup>
  <Card title="ChartElement" href="/elements/upcoming/ads/reporting-chart">
    An advertising account’s performance charted over a window you choose, with a picker for which metric to plot — spend, impressions, clicks, or any conversion the account records. Read-only, and the chart only: headline figures belong to whatever surface composes this.
  </Card>

  <Card title="TableElement" href="/elements/upcoming/ads/reporting-table">
    An advertising account's campaigns, ad groups and ads in one table, with the tabs that move between them: pick rows to narrow the level below, search, sort, break the numbers down, choose your columns, and pause, resume, duplicate or delete straight from a row. The window it reports on and the rows it is filtered to live on the handle, so a chart mounted beside it reports on exactly the same thing.
  </Card>
</CardGroup>

## Flow surfaces

These internal elements open automatically during flows (for example a confirmation or verification step). They are not part of the consumer API, so you never mount, configure, or subscribe to them directly.

* **AdDetailsElement** (`adDetails`): A single ad in detail: its creative, its copy, the accounts it runs under and where it sends people. Opened from a row in the `table` element — it is not mounted directly, and appears over the page rather than inside either frame.


# ChartElement
Source: https://docs.whop.com/elements/upcoming/ads/reporting-chart

An advertising account’s performance charted over a window you choose, with a picker for which metric to plot — spend, impressions, clicks, or any conversion the account records. Read-only, and the chart only: headline figures belong to whatever surface composes this.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Reporting`](/elements/upcoming/ads/reporting) sub-controller in the [`Ads`](/elements/upcoming/ads/overview) group. Render `<ChartElement />` inside `<Reporting>` (React), or mint the sub and mount off it (vanilla): `ads.create('reporting', { … }).create('chart', { … })`. Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Ads, Reporting, ChartElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Ads /* options */>
            <Reporting>
              <ChartElement onMetricChanged={(payload) => console.log("metricChanged", payload)} onTimezoneChanged={(payload) => console.log("timezoneChanged", payload)} onPeriodChanged={(payload) => console.log("periodChanged", payload)} />
            </Reporting>
          </Ads>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const ads = window.WhopElements().ads.create({ /* options */ });
      const reporting = ads.create('reporting', { /* options */ });
      reporting.create('chart', {
        onMetricChanged: (payload) => console.log("metricChanged", payload),
        onTimezoneChanged: (payload) => console.log("timezoneChanged", payload),
        onPeriodChanged: (payload) => console.log("periodChanged", payload)
      }).mount('#ads-reporting-chart');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="metric" type="&#x22;funnel&#x22; | &#x22;spend&#x22; | &#x22;impressions&#x22; | &#x22;clicks&#x22; | &#x22;cost_per_1k_impressions&#x22; | &#x22;cost_per_click&#x22; | &#x22;conversions&#x22; | &#x22;conversion_value&#x22; | &#x22;cost_per_conversion&#x22;">
  What the chart plots — `spend`, `impressions`, `clicks`, or a conversion. The picker moves it; set it to open on something else. For `conversions`, `conversion_value` and `cost_per_conversion`, name the conversion in `metricEvent`. Defaults to `"spend"`.
</ResponseField>

<ResponseField name="metricEvent" type="string">
  The conversion `metric` refers to when it is a per-conversion one — `payment.completed`, `pixel.lead`, or a custom event the account names itself. Ignored by every other metric. Defaults to `""`.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onMetricChanged`

The viewer picked a different result to plot. `metric` is what is being plotted; `event` names the conversion it refers to, and is present only for `conversions`, `conversion_value` and `cost_per_conversion` — the account decides what those are called, so it is a string rather than a member. Mirror it into your own URL and hand it back as `metric`/`metricEvent` if you want the choice to survive a reload; the element holds it for the life of the mount either way.

**Signature:** `((payload: { metric: "funnel" | "spend" | "impressions" | "clicks" | "cost_per_1k_impressions" | "cost_per_click" | "conversions" | "conversion_value" | "cost_per_conversion"; event?: string | undefined; }) => void)`

### `onTimezoneChanged`

The viewer switched which zone the figures are reported in: the choice they made AND the IANA zone it resolves to. The choice is the half that survives a reload — persist it and pass it back as `timezone`, which is what the Whop dashboard does with its own copy; the element holds it for the life of the mount either way. `resolved` comes along so a host can label its own figures without repeating the account-preference lookup, and is the viewer's own zone whenever the account has set none.

**Signature:** `((payload: { timezone: "account" | "local"; resolved: string; }) => void)`

### `onPeriodChanged`

The viewer moved the reporting window: the period they picked AND the window it resolves to, as ISO 8601 instants. The dates come resolved because a period name alone would leave you redoing the day-boundary and account-timezone arithmetic to act on it; the period comes too because only it survives a reload as a ROLLING window — stored dates would pin it. Every surface under the same handle has already followed the move.

**Signature:** `((payload: { period: "today" | "yesterday" | "last_7_days" | "last_14_days" | "last_30_days" | "last_90_days" | "all_time" | "custom"; from: string; to: string; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<ChartElementProps>) => void`

## Styling

This element exposes no targetable class names. Use `appearance` (theme, accent color, variables) to restyle it.


# TableElement
Source: https://docs.whop.com/elements/upcoming/ads/reporting-table

An advertising account's campaigns, ad groups and ads in one table, with the tabs that move between them: pick rows to narrow the level below, search, sort, break the numbers down, choose your columns, and pause, resume, duplicate or delete straight from a row. The window it reports on and the rows it is filtered to live on the handle, so a chart mounted beside it reports on exactly the same thing.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Reporting`](/elements/upcoming/ads/reporting) sub-controller in the [`Ads`](/elements/upcoming/ads/overview) group. Render `<TableElement />` inside `<Reporting>` (React), or mint the sub and mount off it (vanilla): `ads.create('reporting', { … }).create('table', { … })`. Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Ads, Reporting, TableElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Ads /* options */>
            <Reporting>
              <TableElement onTabChanged={(payload) => console.log("tabChanged", payload)} onFilterChanged={(payload) => console.log("filterChanged", payload)} onColumnsChanged={(payload) => console.log("columnsChanged", payload)} onCustomMetricsChanged={(payload) => console.log("customMetricsChanged", payload)} onViewChanged={(payload) => console.log("viewChanged", payload)} onSourcesChanged={(payload) => console.log("sourcesChanged", payload)} onAttributionModelChanged={(payload) => console.log("attributionModelChanged", payload)} />
            </Reporting>
          </Ads>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const ads = window.WhopElements().ads.create({ /* options */ });
      const reporting = ads.create('reporting', { /* options */ });
      reporting.create('table', {
        onTabChanged: (payload) => console.log("tabChanged", payload),
        onFilterChanged: (payload) => console.log("filterChanged", payload),
        onColumnsChanged: (payload) => console.log("columnsChanged", payload),
        onCustomMetricsChanged: (payload) => console.log("customMetricsChanged", payload),
        onViewChanged: (payload) => console.log("viewChanged", payload),
        onSourcesChanged: (payload) => console.log("sourcesChanged", payload),
        onAttributionModelChanged: (payload) => console.log("attributionModelChanged", payload)
      }).mount('#ads-reporting-table');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="useCampaignCreator" type="boolean">
  What happens when a viewer asks to edit — from a row menu, a draft row, or Edit ad in the details overlay. On by default: the campaign builder opens over the page, on the campaign and step they asked for, so editing works with nothing wired up. Turn it off to handle campaign editing yourself — nothing opens, and the request comes back on `editRequested`. Defaults to `true`.
</ResponseField>

<ResponseField name="breakdown" type="&#x22;age&#x22; | &#x22;gender&#x22; | &#x22;age_gender&#x22; | &#x22;placement&#x22; | &#x22;publisher_platform&#x22; | &#x22;device_platform&#x22; | &#x22;impression_device&#x22; | &#x22;country&#x22; | &#x22;region&#x22; | &#x22;hour&#x22; | null">
  How rows are broken down — by country, platform, placement — or `null` for whole rows. Defaults to `null`.
</ResponseField>

<ResponseField name="columns" type="string[] | null">
  The columns on show, by name — standard ones like `impressions` and `roas`, and any pixel events the viewer added. Unset, the table opens on its own defaults. Comes back whole on `columnsChanged`; store the list and pass it here to have the layout stick. Defaults to `null`.
</ResponseField>

<ResponseField name="customMetrics" type="CustomMetricDefinition[]">
  Columns computed from the figures already in the table — a formula over them, named and formatted by you. The table can edit them, and every change comes back on `customMetricsChanged` as the whole new list; persist it and pass it here to have it stick. Defaults to `[]`.
</ResponseField>

<ResponseField name="sourcesDrill" type="string | null">
  What the All tab is drilled into, as a source path: `null` for the roots, `ext:*` for a platform list, `ext:<platform>:*` for that platform’s campaigns. Comes back on `viewChanged`. Defaults to `null`.
</ResponseField>

<ResponseField name="query" type="string">
  What the Ads tab’s search box is filtered to. Defaults to `""`.
</ResponseField>

<ResponseField name="showPausedCampaigns" type="boolean">
  Whether paused campaigns are listed. Defaults to `true`.
</ResponseField>

### Direct mode only

*These props exist only on the in-process (direct-mode) component. The hosted embed never carries them, and the element renders without them.*

<ResponseField name="inheritLayout" type="direct mode only">
  Direct mode only. Leave the viewer’s columns and computed metrics to the app around the table — its own store, its own defaults — instead of taking them from `columns` and `customMetrics`. An embed cannot set this and should not want to: localStorage inside a frame belongs to the bundle’s origin, so a layout chosen there is invisible to everything else you run.
</ResponseField>

<ResponseField name="navigation" type="direct mode only">
  Direct mode only. Hand the table your router and its links become real navigations — a `Link` for the row menus, a `navigate` that honours cmd-click. Left unset, and in every embed, links raise `editRequested` instead: an element frame has no router, and a plain `<a>` would move the frame rather than the page around it.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onTabChanged`

The open tab changed. Mirror it into your own URL if you want it to survive a reload.

**Signature:** `((payload: { tab: "ads" | "all" | "campaigns" | "ad-groups"; }) => void)`

### `onFilterChanged`

The viewer narrowed the view — by ticking rows, or by clicking through a campaign to its ad groups. Every surface under the same handle has already followed it.

**Signature:** `((payload: { campaignIds: string[]; adGroupIds: string[]; adIds: string[]; }) => void)`

### `onColumnsChanged`

The viewer showed or hid a column. Carries every column now on show, standard and pixel-event alike — store the list and pass it straight back as `columns`, or the layout resets on the next mount.

**Signature:** `((payload: { columns: string[]; }) => void)`

### `onCustomMetricsChanged`

The viewer added, edited or removed a computed column. Carries the WHOLE list either way — store it as given and pass it back as `customMetrics`, or they are gone on the next mount.

**Signature:** `((payload: { customMetrics: CustomMetricDefinition[]; }) => void)`

### `onViewChanged`

The viewer moved one of the table’s own controls — the All tab’s drill, the breakdown, the search box, the paused toggle. Carries all four whichever moved; store them and pass them back as props, or they reset on the next mount.

**Signature:** `((payload: { sourcesDrill: string | null; breakdown: "age" | "gender" | "age_gender" | "placement" | "publisher_platform" | "device_platform" | "impression_device" | "country" | "region" | "hour" | null; query: string; showPausedCampaigns: boolean; }) => void)`

### `onSourcesChanged`

What the All tab is now looking at, as source paths ready to hand to a chart: `null` off the All tab (Whop advertising alone), `[]` for every source, otherwise the ticked rows or the drilled-into group. Every surface under the same handle has already followed it.

**Signature:** `((payload: { sources: string[] | null; }) => void)`

### `onAttributionModelChanged`

The viewer changed which touch gets the credit, from the picker on the All tab. Every surface under the same handle has already re-credited; persist it and pass it back as `attributionModel`, or it reverts to last touch on the next mount.

**Signature:** `((payload: { attributionModel: "last_touch" | "first_touch"; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<TableElementProps>) => void`

## Styling

This element exposes no targetable class names. Use `appearance` (theme, accent color, variables) to restyle it.


# Appearance
Source: https://docs.whop.com/elements/upcoming/appearance

Theme, CSS variables, and per-part styling for every element.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

One `appearance` object styles every element. Pass it globally at construction, per group at `create()` (or as React props), and change it live at any point with `update({ appearance })`. Mounted elements restyle in place.

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    theme: { appearance: 'dark', accentColor: 'blue' },
    variables: { '--radius': '8px' },
    classes: { /* per-part declarations, see below */ }
  }
});
```

## Theme

The high-level design tokens. Every field is optional and fully typed. The values below are enumerated from the source types:

<ResponseField name="appearance" type="&#x22;light&#x22; | &#x22;dark&#x22;">
  The color scheme to use. - `"light"` - Light mode with dark text on light backgrounds - `"dark"` - Dark mode with light text on dark backgrounds
</ResponseField>

<ResponseField name="accentColor" type="AccentColor">
  The primary accent color used for interactive elements. One of `ruby`, `blue`, `red`, `yellow`, `green`, `gray`, `tomato`, `crimson`, `pink`, `plum`, `purple`, `violet`, `iris`, `cyan`, `teal`, `jade`, `grass`, `brown`, `orange`, `indigo`, `sky`, `mint`, `amber`, `lime`, `lemon`, `magenta`, `gold`, `bronze`.
</ResponseField>

<ResponseField name="grayColor" type="&#x22;gray&#x22; | &#x22;mauve&#x22; | &#x22;slate&#x22; | &#x22;sage&#x22; | &#x22;olive&#x22; | &#x22;sand&#x22; | &#x22;auto&#x22;">
  The gray color palette to use for neutral elements. Use `"auto"` to automatically match the accent color.
</ResponseField>

<ResponseField name="dangerColor" type="&#x22;ruby&#x22; | &#x22;red&#x22; | &#x22;tomato&#x22;">
  The color used for error states and destructive actions.
</ResponseField>

<ResponseField name="warningColor" type="&#x22;yellow&#x22; | &#x22;amber&#x22;">
  The color used for warning states.
</ResponseField>

<ResponseField name="successColor" type="&#x22;green&#x22; | &#x22;teal&#x22; | &#x22;jade&#x22; | &#x22;grass&#x22;">
  The color used for success states.
</ResponseField>

<ResponseField name="infoColor" type="&#x22;sky&#x22; | &#x22;blue&#x22;">
  The color used for informational states.
</ResponseField>

## Variables

CSS custom properties (variables) that can be used to customize element styles. Keys must start with `--` prefix.

```ts theme={null}
appearance: { variables: { "--radius": "8px" } }
```

## Classes

Style declarations per targetable `whop-*` class name — each entry restyles one documented part of an element (see the element's Styling section for its class list). The declarations are sanitized and injected INSIDE the element's frame; page stylesheets cannot reach it.

A style declaration object — CSS properties to values, React-`CSSProperties`-style. Property names may be camelCase (`fontWeight`) or kebab-case (`font-weight`); both are normalized and checked against the safe-property allowlist before being applied.

```ts theme={null}
appearance: {
  classes: {
    "whop-SomePart": { borderRadius: "8px", fontWeight: "600" },
  },
}
```

Find each element's part list in the **Styling** section of its page.


# CheckoutElement
Source: https://docs.whop.com/elements/upcoming/checkout/checkout

The full checkout surface — order summary with the live quote, promo code entry, the currency the buyer pays in, everything this checkout has to collect from the buyer, the composed payment methods surface, and the pay flow. What it collects is whatever the seller set up (email, their own questions, a phone number, an explicit agreement to their terms), rendered together on one screen in the order they chose — so a seller who starts asking for something new needs no change here. Renders the whole purchase; the checkout controller owns the session and the credential. After a payment that needs an off-site step, this same surface renders the outcome the server reports when the buyer comes back.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Checkout`](/elements/upcoming/checkout/overview) group. Render `<CheckoutElement />` inside it (React), or call `checkout.create('checkout', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Checkout, CheckoutElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Checkout /* options */>
            <CheckoutElement />
          </Checkout>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const checkout = window.WhopElements().checkout.create({ /* options */ });
      checkout.create('checkout').mount('#checkout-checkout');
    </script>
    ```
  </CodeGroup>
</div>

## Props

*This element takes no consumer props.*

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<CheckoutElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                                 | Targets                                                                                                                                                                         |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.whop-Address`                       | The address form root                                                                                                                                                           |
| `.whop-AddressErrorSummary`           | The summary line shown when validation reveals missing or invalid fields                                                                                                        |
| `.whop-AddressField`                  | One field cell in the address form                                                                                                                                              |
| `.whop-AddressFieldError`             | The error line under an address field (full layout)                                                                                                                             |
| `.whop-AddressFieldInput`             | A text input in the address form                                                                                                                                                |
| `.whop-AddressFieldInputInvalid`      | Added to an address input while it fails validation                                                                                                                             |
| `.whop-AddressFieldInvalid`           | Added to a compact field cell while it fails validation                                                                                                                         |
| `.whop-AddressFieldLabel`             | The label above an address field (full layout)                                                                                                                                  |
| `.whop-AddressFieldSelect`            | A select (country, state, organization type) in the address form                                                                                                                |
| `.whop-AddressLine2Toggle`            | The "Add address line 2" text button shown while line 2 is collapsed                                                                                                            |
| `.whop-AddressManualEntry`            | The "Enter address manually" text button below the collapsed form — expands the full country format                                                                             |
| `.whop-AddressSuggestion`             | One suggestion row in the autocomplete overlay                                                                                                                                  |
| `.whop-AddressSuggestionActive`       | Added to the keyboard/pointer-active suggestion row                                                                                                                             |
| `.whop-AddressSuggestionManual`       | The "Enter address manually" row closing the suggestions list                                                                                                                   |
| `.whop-AddressSuggestions`            | The autocomplete suggestions overlay anchored to the address line 1 field                                                                                                       |
| `.whop-Card`                          | The card element root                                                                                                                                                           |
| `.whop-CardError`                     | The error pane shown when the card configuration cannot load                                                                                                                    |
| `.whop-CardField`                     | One card field cell — number, expiry, or CVC                                                                                                                                    |
| `.whop-CardFieldError`                | The Invalid / Incomplete message under a card field                                                                                                                             |
| `.whop-CardFieldGroup`                | The grouped card fields — number on top, expiry and CVC below                                                                                                                   |
| `.whop-CardFieldInput`                | The bordered input container around a PCI field                                                                                                                                 |
| `.whop-CardFieldInputFocused`         | Added to the input container while its field is focused                                                                                                                         |
| `.whop-CardFieldInputInvalid`         | Added to the input container while its field is invalid or incomplete                                                                                                           |
| `.whop-CardFieldRow`                  | The compact single-row card field group — number flexing, expiry and CVC fixed-width to the right                                                                               |
| `.whop-CardLabel`                     | The "Card information" label above the field group                                                                                                                              |
| `.whop-CardSaveNotice`                | The save-for-future-purchases consent line                                                                                                                                      |
| `.whop-Checkout`                      | The checkout element root                                                                                                                                                       |
| `.whop-CheckoutBreakdown`             | The itemized rows under the total — discounts, tax, and anything else that changes the price                                                                                    |
| `.whop-CheckoutBreakdownPending`      | The placeholder shown for a row whose figure is still being calculated                                                                                                          |
| `.whop-CheckoutBreakdownRow`          | One itemized row under the total                                                                                                                                                |
| `.whop-CheckoutCollection`            | The collection column — email, payment methods, and the pay flow                                                                                                                |
| `.whop-CheckoutCompleted`             | The success face shown once the checkout completed                                                                                                                              |
| `.whop-CheckoutCurrencyNote`          | The conversion disclosure — what the charge converted from, and at what rate                                                                                                    |
| `.whop-CheckoutCurrencyRow`           | The pay-in-currency row — the conversion disclosure, the switch affordance, and its refusal line                                                                                |
| `.whop-CheckoutCurrencyToggle`        | The "pay in another currency" affordance                                                                                                                                        |
| `.whop-CheckoutDetails`               | The order-details column — summary, currency, promo. Sits beside the collection column in wide containers, above it in narrow ones                                              |
| `.whop-CheckoutDetailsToggle`         | The narrow-container affordance that opens the order-details sheet                                                                                                              |
| `.whop-CheckoutDueToday`              | The "due today" qualifier on the total, shown when something is charged today and later charges follow                                                                          |
| `.whop-CheckoutError`                 | The retryable error line under the payment surface                                                                                                                              |
| `.whop-CheckoutExpired`               | The face shown when the session expired before completing                                                                                                                       |
| `.whop-CheckoutFieldError`            | Every inline field-level error line (email, promo, currency)                                                                                                                    |
| `.whop-CheckoutLayout`                | The two-column/stacked layout row — order details and collection side by side in wide containers, stacked in narrow ones                                                        |
| `.whop-CheckoutNextActionNotice`      | The line explaining a step the server requires before this checkout can be paid                                                                                                 |
| `.whop-CheckoutPayButton`             | The pay button                                                                                                                                                                  |
| `.whop-CheckoutPolicyLink`            | Each link to a seller-published policy document in the terms disclosure                                                                                                         |
| `.whop-CheckoutPrice`                 | The price block — centered under the seller line in a narrow container, left-aligned beside the collection column                                                               |
| `.whop-CheckoutPromoActions`          | The apply/remove button pair                                                                                                                                                    |
| `.whop-CheckoutPromoApplied`          | The applied-promo confirmation line                                                                                                                                             |
| `.whop-CheckoutPromoApply`            | The apply-promo button                                                                                                                                                          |
| `.whop-CheckoutPromoInput`            | The promo code input                                                                                                                                                            |
| `.whop-CheckoutPromoRemove`           | The remove-promo button                                                                                                                                                         |
| `.whop-CheckoutPromoRow`              | The promo code affordance — a pill that grows into the input                                                                                                                    |
| `.whop-CheckoutQuantity`              | The quantity line, shown above 1                                                                                                                                                |
| `.whop-CheckoutRequirementInput`      | A collected value’s input                                                                                                                                                       |
| `.whop-CheckoutRequirementLabel`      | A collected value’s label                                                                                                                                                       |
| `.whop-CheckoutRequirementRequired`   | The marker beside a value an answer is required for                                                                                                                             |
| `.whop-CheckoutRequirementRow`        | One collected value — its label, its input, and its inline error                                                                                                                |
| `.whop-CheckoutRequirements`          | The requirements form — every value this checkout collects, rendered as one block in the order the server declared                                                              |
| `.whop-CheckoutSchedule`              | The billing-terms block under the total — trial length, renewal price and period, installment count, initial fee, and access window                                             |
| `.whop-CheckoutScheduleLine`          | Each line of the billing-terms block                                                                                                                                            |
| `.whop-CheckoutSecurity`              | The secured-by-Whop footer shown in the checkout-branding preview                                                                                                               |
| `.whop-CheckoutSeller`                | The seller title line                                                                                                                                                           |
| `.whop-CheckoutSummary`               | The order summary block — seller, items, and the live total                                                                                                                     |
| `.whop-CheckoutSummaryHead`           | The seller line, with the order-details trigger opposite it in a narrow container                                                                                               |
| `.whop-CheckoutTerms`                 | The terms disclosure under the pay button — the seller policies and the Whop buyer terms                                                                                        |
| `.whop-CheckoutTermsAccept`           | The explicit terms-acceptance row, rendered only when the session requires an explicit act of acceptance                                                                        |
| `.whop-CheckoutTermsCheckbox`         | The terms-acceptance checkbox                                                                                                                                                   |
| `.whop-CheckoutTotal`                 | The quoted total the buyer pays                                                                                                                                                 |
| `.whop-CheckoutTotalOriginal`         | The pre-promo total, struck through beside the discounted one                                                                                                                   |
| `.whop-CheckoutUncollectable`         | The line shown when the checkout requires something this surface cannot collect                                                                                                 |
| `.whop-CompletePayment`               | The completion surface root                                                                                                                                                     |
| `.whop-CompletePaymentError`          | The error pane                                                                                                                                                                  |
| `.whop-CompletePaymentFrame`          | The framed PSP step                                                                                                                                                             |
| `.whop-CompletePaymentHint`           | The auto-update hint line                                                                                                                                                       |
| `.whop-CompletePaymentInstructions`   | The bank-transfer instruction rows                                                                                                                                              |
| `.whop-CompletePaymentSettled`        | The resting-state pane shown as the dialog closes                                                                                                                               |
| `.whop-CompletePaymentSpinner`        | The waiting spinner                                                                                                                                                             |
| `.whop-CompletePaymentTitle`          | The dialog title                                                                                                                                                                |
| `.whop-Email`                         | The email element root                                                                                                                                                          |
| `.whop-EmailError`                    | The invalid-email message under the field                                                                                                                                       |
| `.whop-EmailInput`                    | The email input                                                                                                                                                                 |
| `.whop-EmailInputInvalid`             | Added to the input while the value is not a plausible email                                                                                                                     |
| `.whop-EmailLabel`                    | The label above the email field                                                                                                                                                 |
| `.whop-EmailSignedIn`                 | The signed-in row under the locked field                                                                                                                                        |
| `.whop-EmailSignIn`                   | The Welcome back sign-in affordance shown for a recognized email                                                                                                                |
| `.whop-EmailSignInError`              | The sign-in failure message under the affordance                                                                                                                                |
| `.whop-EmailSignOut`                  | The control that returns the field to a different email                                                                                                                         |
| `.whop-Payment`                       | The payment element root                                                                                                                                                        |
| `.whop-PaymentBillingBlock`           | The payment element's internal billing address block                                                                                                                            |
| `.whop-PaymentCardFields`             | The inline card fields panel                                                                                                                                                    |
| `.whop-PaymentDetailIcon`             | The template icon beside the detail region's explainer                                                                                                                          |
| `.whop-PaymentDetailRegion`           | The expanded detail region for a selected method — collection surfaces first (inline card fields, declared inputs), then the explainer and disclosure lines as the bottom block |
| `.whop-PaymentDetailSubtext`          | The consent subtext under the explainer on wallet methods                                                                                                                       |
| `.whop-PaymentDetailText`             | The detail region's explainer line                                                                                                                                              |
| `.whop-PaymentError`                  | The error pane shown when methods cannot load or none are available                                                                                                             |
| `.whop-PaymentFieldError`             | The Invalid message under a declared input                                                                                                                                      |
| `.whop-PaymentFieldInput`             | A declared method input in the detail region                                                                                                                                    |
| `.whop-PaymentFieldInputInvalid`      | Added to a declared input while its value fails the declared format                                                                                                             |
| `.whop-PaymentFieldLabel`             | The label above a declared method input in the detail region                                                                                                                    |
| `.whop-PaymentMandateLink`            | The mandate terms link inside the mandate notice                                                                                                                                |
| `.whop-PaymentMandateNotice`          | The mandate authorization notice on methods whose matrix config declares a mandate                                                                                              |
| `.whop-PaymentMethod`                 | One payment method — the row plus its expanding detail region                                                                                                                   |
| `.whop-PaymentMethodDetail`           | The expanding region that reveals the selected method's detail — inline card fields, explainer, or declared inputs                                                              |
| `.whop-PaymentMethodIcon`             | The method icon on a row                                                                                                                                                        |
| `.whop-PaymentMethodLabel`            | The method display name on a row                                                                                                                                                |
| `.whop-PaymentMethodMoreSelect`       | The invisible native select stretched over the More tile                                                                                                                        |
| `.whop-PaymentMethodMoreTile`         | The compact overflow tile ending the capped tile row — stacked overflow-method icons over a chevron, its native select lists the remaining methods                              |
| `.whop-PaymentMethodPanel`            | The selected method's detail panel below the tile row (horizontal layout)                                                                                                       |
| `.whop-PaymentMethodRadio`            | The radio indicator on a method row                                                                                                                                             |
| `.whop-PaymentMethodRadioSelected`    | Added to the radio indicator while its method is selected                                                                                                                       |
| `.whop-PaymentMethodRow`              | The clickable payment method row                                                                                                                                                |
| `.whop-PaymentMethodRowSelected`      | Added to the method row while it is the selected method                                                                                                                         |
| `.whop-PaymentMethods`                | The payment method list                                                                                                                                                         |
| `.whop-PaymentMethodSeparated`        | Added to a method item while it renders as its own separated card                                                                                                               |
| `.whop-PaymentMethodsSeparated`       | Added to the method list while separated accordion items are on                                                                                                                 |
| `.whop-PaymentMethodTile`             | One method tile in the horizontal tile row                                                                                                                                      |
| `.whop-PaymentMethodTileRow`          | The method tile row (horizontal layout) — never scrolls; beyond the tile cap the overflow methods live in the compact More tile                                                 |
| `.whop-PaymentMethodTileSelected`     | Added to a method tile while it is the selected method                                                                                                                          |
| `.whop-PaymentMoreRow`                | The "N more payment methods" expander row                                                                                                                                       |
| `.whop-PaymentSavedMethod`            | One saved payment method specifically — carries PaymentMethod too                                                                                                               |
| `.whop-PaymentSavedMethodHint`        | The saved method's trailing detail — a card's expiry                                                                                                                            |
| `.whop-PaymentSavedMethodRow`         | The clickable saved method row specifically — carries PaymentMethodRow too                                                                                                      |
| `.whop-PaymentSavedMethodRowSelected` | The selected marker on a saved method row specifically                                                                                                                          |
| `.whop-PaymentSavedMethods`           | The saved-methods list specifically — carries PaymentMethods too, so one rule styles both lists                                                                                 |
| `.whop-PaymentSavedMethodSeparated`   | The separated marker on a saved method specifically                                                                                                                             |
| `.whop-PaymentSavedMore`              | The control that fetches the next page of saved payment methods                                                                                                                 |
| `.whop-PaymentSavedMoreSpinner`       | The spinner shown while the next page of saved payment methods loads                                                                                                            |
| `.whop-PaymentSaveNotice`             | The save-for-future-purchases consent line closing the detail region                                                                                                            |
| `.whop-PaymentSettlementNotice`       | The settlement-window hint on methods whose matrix config declares one                                                                                                          |
| `.whop-Verification`                  | The verification-code dialog body                                                                                                                                               |
| `.whop-VerificationDismiss`           | The continue-as-guest control shown when sign-in cannot be completed here                                                                                                       |
| `.whop-VerificationError`             | The failure message in the dialog                                                                                                                                               |
| `.whop-VerificationExpired`           | The expired pane — shown when the sign-in attempt can no longer be verified                                                                                                     |
| `.whop-VerificationHeading`           | The title and explainer block above the code row                                                                                                                                |
| `.whop-VerificationHint`              | The where-the-code-went explainer line                                                                                                                                          |
| `.whop-VerificationInput`             | The one-time-code input                                                                                                                                                         |
| `.whop-VerificationInputInvalid`      | Added to the code input after a failed attempt                                                                                                                                  |
| `.whop-VerificationInputSlot`         | One digit box of the one-time-code input                                                                                                                                        |
| `.whop-VerificationInputSlotActive`   | Added to the code slot the buyer is typing into                                                                                                                                 |
| `.whop-VerificationPending`           | The verifying… line while a submit is in flight                                                                                                                                 |
| `.whop-VerificationResend`            | The resend-code control, counting down the resend window                                                                                                                        |
| `.whop-VerificationRestart`           | The start-over control on the expired pane                                                                                                                                      |
| `.whop-VerificationTitle`             | The dialog's header wordmark                                                                                                                                                    |

```ts theme={null}
const checkout = whop.checkout.create({
  appearance: {
    classes: {
      'whop-Address': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressErrorSummary': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressField': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldSelect': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressLine2Toggle': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressManualEntry': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestion': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestionActive': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestionManual': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestions': { borderRadius: '8px', fontWeight: '600' },
      'whop-Card': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardField': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldGroup': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputFocused': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardSaveNotice': { borderRadius: '8px', fontWeight: '600' },
      'whop-Checkout': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutBreakdown': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutBreakdownPending': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutBreakdownRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutCollection': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutCompleted': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutCurrencyNote': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutCurrencyRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutCurrencyToggle': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutDetails': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutDetailsToggle': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutDueToday': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutExpired': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutLayout': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutNextActionNotice': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPayButton': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPolicyLink': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPrice': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPromoActions': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPromoApplied': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPromoApply': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPromoInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPromoRemove': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutPromoRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutQuantity': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutRequirementInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutRequirementLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutRequirementRequired': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutRequirementRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutRequirements': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutSchedule': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutScheduleLine': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutSecurity': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutSeller': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutSummary': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutSummaryHead': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutTerms': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutTermsAccept': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutTermsCheckbox': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutTotal': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutTotalOriginal': { borderRadius: '8px', fontWeight: '600' },
      'whop-CheckoutUncollectable': { borderRadius: '8px', fontWeight: '600' },
      'whop-CompletePayment': { borderRadius: '8px', fontWeight: '600' },
      'whop-CompletePaymentError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CompletePaymentFrame': { borderRadius: '8px', fontWeight: '600' },
      'whop-CompletePaymentHint': { borderRadius: '8px', fontWeight: '600' },
      'whop-CompletePaymentInstructions': { borderRadius: '8px', fontWeight: '600' },
      'whop-CompletePaymentSettled': { borderRadius: '8px', fontWeight: '600' },
      'whop-CompletePaymentSpinner': { borderRadius: '8px', fontWeight: '600' },
      'whop-CompletePaymentTitle': { borderRadius: '8px', fontWeight: '600' },
      'whop-Email': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailError': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailSignedIn': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailSignIn': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailSignInError': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailSignOut': { borderRadius: '8px', fontWeight: '600' },
      'whop-Payment': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentBillingBlock': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentCardFields': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentDetailIcon': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentDetailRegion': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentDetailSubtext': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentDetailText': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentError': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentFieldLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMandateLink': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMandateNotice': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethod': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodDetail': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodIcon': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodMoreSelect': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodMoreTile': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodPanel': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodRadio': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodRadioSelected': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodRowSelected': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethods': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodSeparated': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodsSeparated': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodTile': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodTileRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodTileSelected': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMoreRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethod': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethodHint': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethodRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethodRowSelected': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethods': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethodSeparated': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMore': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMoreSpinner': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSaveNotice': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSettlementNotice': { borderRadius: '8px', fontWeight: '600' },
      'whop-Verification': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationDismiss': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationError': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationExpired': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationHeading': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationHint': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationInputSlot': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationInputSlotActive': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationPending': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationResend': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationRestart': { borderRadius: '8px', fontWeight: '600' },
      'whop-VerificationTitle': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
checkout.update({
  appearance: { classes: { 'whop-Address': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Checkout>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# Checkout
Source: https://docs.whop.com/elements/upcoming/checkout/overview

Drives a full hosted checkout for one plan — price summary, promo codes, the currency the buyer pays in, and the whole payment collection surface (the payments elements, composed inside) — against the Whop checkout sessions API. Mount it with a `plan` and the element creates the checkout session itself; the session credential never leaves the element. Or resume a session you already hold by passing its `session` secret. The buyer pays inside the element; you get `onCompleted` with the payment id. A payment needing an off-site step (3DS, a bank page) is driven automatically — on whop.com the buyer is brought back into the restored checkout, and when you embed the element they return to the `returnUrl` you set. EVERY option here is CREATE-TIME: a checkout session is minted at mount from these values, so changing one later (`update()`, or new React props) refuses loudly instead of silently charging the booted order — mount a fresh checkout to change what is being bought.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

## Playground

Assemble the elements with sample data. Drive the controls, add and arrange elements, and watch events fire live:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Checkout } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Checkout /* options */>
            {/* mount elements here */}
          </Checkout>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const checkout = window.WhopElements().checkout.create({ /* options */ });
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `whop.checkout.create({ … })`, or as props on `<Checkout>` in React.

<ResponseField name="plan" type="string">
  An existing plan id (`plan_…`) — the element creates a checkout session for it. The plan IS the price; nothing about amounts can be asserted client-side. Set at create only: the session is minted from it, and changing it later refuses.
</ResponseField>

<ResponseField name="quantity" type="number">
  How many units to purchase. Plans that disallow multiples refuse values above 1. Set at create only: the session is minted with it, and changing it later refuses.
</ResponseField>

<ResponseField name="promoCode" type="string">
  A promo code to apply before the buyer ever sees the price — the discount is on the first quote, and the buyer can still change or remove it. Pass the code a marketing link carried: a code that has expired or was never valid opens the checkout at full price with the reason on the promo row, never a checkout that will not open. Set at create only.
</ResponseField>

<ResponseField name="affiliateCode" type="string">
  The affiliate this checkout is attributed to. Set at create only.
</ResponseField>

<ResponseField name="attribution" type="{ utmSource?: string | undefined; utmMedium?: string | undefined; utmCampaign?: string | undefined; utmTerm?: string | undefined; utmContent?: string | undefined; trackingLinkId?: string | undefined; funnelId?: string | undefined; source?: string | undefined; }">
  Where this sale came from, for the seller's reporting: the campaign parameters of the link the buyer arrived on. Everything here is recorded against the order and is never shown to the buyer. Set at create only.
</ResponseField>

<ResponseField name="metadata" type="Record<string, string>">
  Your own key/value pairs to record against the order and read back on the payment — order ids, cart ids, anything you reconcile against. Up to 40 string pairs. Set at create only.
</ResponseField>

<ResponseField name="returnUrl" type="string">
  Where the buyer lands after an off-site payment step. Https-only (http for localhost). Set at create only.
</ResponseField>

<ResponseField name="session" type="string">
  RESUME — a checkout session's `client_secret` your integration already holds (the session id is baked into it). The element restores that session instead of creating one. Set at create only: changing it later refuses (mount a fresh checkout for a different session).
</ResponseField>

<ResponseField name="appearance" type="Appearance">
  Visual customization for this group's elements. Overrides the global `WhopElements({ appearance })`; change it live with `update({ appearance })`.
</ResponseField>

<ResponseField name="locale" type="WhopElementsLocale">
  Locale for this group's element UI text. One of the app's built locales, overriding the global config; any other value falls back to the default locale.
</ResponseField>

<Note>The options are a union. Provide **exactly one** of these shapes, plus the shared event callbacks below:</Note>

* `{ plan: string; quantity?: number; promoCode?: string; affiliateCode?: string; attribution?: { utmSource?: string | undefined; utmMedium?: string | undefined; utmCampaign?: string | undefined; utmTerm?: string | undefined; utmContent?: string | undefined; trackingLinkId?: string | undefined; funnelId?: string | undefined; source?: string | undefined; }; metadata?: Record<string, string>; returnUrl?: string }`
* `{ session: string }`

## Events

Pass a callback in the create options / React props.

### `onChange`

The checkout advanced — fired after every confirm attempt with the session status and payment id (if one succeeded).

**Signature:** `((payload: { status: string; payment: string | null; }) => void)`

### `onCompleted`

The checkout finished — the confirm succeeded and the session is `completed`. `payment` is the created payment (`pay_…`).

**Signature:** `((payload: { payment: string; }) => void)`

### `onLoadingChange`

Fired when the grouped loading state changes. `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the Checkout handle, which is the return of `whop.checkout.create({ … })` (vanilla) or `useCheckout()` (React).

### `update`

Update the handle live: any of its options (`appearance` and `locale` included), propagated to every mounted element. React consumers never call it; updating the namespace component's props does the same.

**Signature:** `(options: Partial<CheckoutOptions>) => void`

## Elements

The elements this group mounts. Each has its own page:

**Alternatives.** These are exclusive; mount one at a time, and destroy it to mount another:

<CardGroup>
  <Card title="CheckoutElement" href="/elements/upcoming/checkout/checkout">
    The full checkout surface — order summary with the live quote, promo code entry, the currency the buyer pays in, everything this checkout has to collect from the buyer, the composed payment methods surface, and the pay flow. What it collects is whatever the seller set up (email, their own questions, a phone number, an explicit agreement to their terms), rendered together on one screen in the order they chose — so a seller who starts asking for something new needs no change here. Renders the whole purchase; the checkout controller owns the session and the credential. After a payment that needs an off-site step, this same surface renders the outcome the server reports when the buyer comes back.
  </Card>
</CardGroup>

## Flow surfaces

These internal elements open automatically during flows (for example a confirmation or verification step). They are not part of the consumer API, so you never mount, configure, or subscribe to them directly.

* **CheckoutDetailsElement** (`checkoutDetails`): The order-details sheet a narrow checkout opens for the promo code, currency and totals.


# AddressElement
Source: https://docs.whop.com/elements/upcoming/payments/address

Collects a billing or shipping address with per-country formats — the field set, order, required flags, and postal-code validation adapt to the selected country — plus address autocomplete on the street field. Drive your own forms off `onChange`, or call `validate()` / `getValues()` on the handle.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Payments`](/elements/upcoming/payments/overview) group. Render `<AddressElement />` inside it (React), or call `payments.create('address', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments, AddressElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            <AddressElement onChange={(payload) => console.log("change", payload)} />
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
      payments.create('address', { onChange: (payload) => console.log("change", payload) }).mount('#payments-address');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="layout" type="&#x22;full&#x22; | &#x22;compact&#x22;">
  `full` (default) stacks labeled fields; `compact` fuses them into one dense bordered group with placeholder labels. Defaults to `"full"`.
</ResponseField>

<ResponseField name="line2" type="&#x22;never&#x22; | &#x22;toggle&#x22; | &#x22;always&#x22;">
  Address line 2: always visible (default), revealed by a text button (`toggle`), or never collected. Defaults to `"always"`.
</ResponseField>

<ResponseField name="name" type="&#x22;split&#x22; | &#x22;combined&#x22; | &#x22;none&#x22;">
  The name row: one full-name field (default), split first/last fields, or none. Defaults to `"combined"`.
</ResponseField>

<ResponseField name="mode" type="&#x22;billing&#x22; | &#x22;shipping&#x22;">
  Which autocomplete family the fields advertise to the browser: `billing` (default) or `shipping`. Defaults to `"billing"`.
</ResponseField>

<ResponseField name="scope" type="&#x22;full&#x22; | &#x22;minimal&#x22;">
  `full` (default) collects the country's complete address format; `minimal` collects the AVS floor of ADDRESS fields only — country plus postal code. The name row is governed by the `name` prop independently of scope, and a rendered name row is required (set `name: 'none'` for a pure country+postal collection). Note: the standalone element never widens to a payment method's own declared billing floor — a card confirm requires the cardholder name, country, and postal code, so beside a card method keep `name` enabled or pass it in the confirm's `billingDetails`. Defaults to `"full"`.
</ResponseField>

<ResponseField name="organization" type="&#x22;name&#x22; | &#x22;none&#x22; | &#x22;name_with_type&#x22;">
  The organization row: hidden (default), a name field, or a name field plus a business/individual type select. Defaults to `"none"`.
</ResponseField>

<ResponseField name="defaultValues" type="{ name?: string | undefined; address?: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: &#x22;business&#x22; | &#x22;individual&#x22; | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country?: string | undefined; } | undefined; }">
  Seed values applied once before first paint (`address.country` is ISO2). Takes precedence over IP-country detection.
</ResponseField>

<ResponseField name="detectCountry" type="boolean">
  Default the country from the buyer's IP (resolved before first paint). Falls back to the controller's `countryHint`, then US. Defaults to `true`.
</ResponseField>

<ResponseField name="allowedCountries" type="string[]">
  Restrict the country select to these ISO2 codes. A single entry locks the country — the select stays openable and shows the one choice.
</ResponseField>

<ResponseField name="autocomplete" type="boolean">
  Google Places suggestions on the street-address field. When Places is unavailable (no key, blocked loader) the field is a plain input. Defaults to `true`.
</ResponseField>

<ResponseField name="customFields" type="({ key: string; label: string; type: &#x22;text&#x22; | &#x22;select&#x22; | &#x22;date&#x22; | &#x22;phone&#x22;; position: &#x22;after_name&#x22; | &#x22;after_organization&#x22; | &#x22;before_country&#x22; | &#x22;after_address&#x22;; required?: boolean | undefined; options?: string[] | undefined; format?: string | undefined; autocomplete?: string | undefined; })[]">
  Extra fields rendered inline with the same chrome: `{ key, label, type: text|select|date|phone, position: after_name|after_organization|before_country|after_address, required?, options?, format?, autocomplete? }`. Values are validated centrally and emitted under the separate `custom` bag.
</ResponseField>

<ResponseField name="countryHint" type="string">
  Optional ISO2 fallback for the country-detect chain (defaultValues > IP country > this > US) — e.g. derived from a checkout currency when it maps to exactly one country. Empty (default) = no hint. (When the payments controller later declares this element, its currency-derived hint wants to layer over this — the framework has no controller-OR-consumer prop source yet, so that wiring lands with that chunk.) Defaults to `""`.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onChange`

The address changed — `complete: true` means every required field for the selected country (plus any required custom fields) is filled and valid. `address` uses the confirmation-token billing\_details naming (`postal_code`, ISO2 `country`); custom field values ride the separate `custom` bag.

**Signature:** `((payload: { complete: boolean; address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; custom: Record<string, string>; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `validate`

Validate the whole form, revealing every error inline. Resolves `{ complete, address, errors }` — never throws; `errors` is empty exactly when `complete` is true. Error keys are the contract field keys (`postal_code`, `line1`, …), `custom:<key>` for custom fields, and the transient `form` key returned while the form is still loading.

**Signature:** `() => Promise<{ complete: boolean; address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; errors: Record<string, string>; }>`

### `getValues`

Read the current values without validating or revealing errors: `{ address, custom }`.

**Signature:** `() => Promise<{ address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; custom: Record<string, string>; }>`

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<AddressElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                            | Targets                                                                                             |
| -------------------------------- | --------------------------------------------------------------------------------------------------- |
| `.whop-Address`                  | The address form root                                                                               |
| `.whop-AddressErrorSummary`      | The summary line shown when validation reveals missing or invalid fields                            |
| `.whop-AddressField`             | One field cell in the address form                                                                  |
| `.whop-AddressFieldError`        | The error line under an address field (full layout)                                                 |
| `.whop-AddressFieldInput`        | A text input in the address form                                                                    |
| `.whop-AddressFieldInputInvalid` | Added to an address input while it fails validation                                                 |
| `.whop-AddressFieldInvalid`      | Added to a compact field cell while it fails validation                                             |
| `.whop-AddressFieldLabel`        | The label above an address field (full layout)                                                      |
| `.whop-AddressFieldSelect`       | A select (country, state, organization type) in the address form                                    |
| `.whop-AddressLine2Toggle`       | The "Add address line 2" text button shown while line 2 is collapsed                                |
| `.whop-AddressManualEntry`       | The "Enter address manually" text button below the collapsed form — expands the full country format |
| `.whop-AddressSuggestion`        | One suggestion row in the autocomplete overlay                                                      |
| `.whop-AddressSuggestionActive`  | Added to the keyboard/pointer-active suggestion row                                                 |
| `.whop-AddressSuggestionManual`  | The "Enter address manually" row closing the suggestions list                                       |
| `.whop-AddressSuggestions`       | The autocomplete suggestions overlay anchored to the address line 1 field                           |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-Address': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressErrorSummary': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressField': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldSelect': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressLine2Toggle': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressManualEntry': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestion': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestionActive': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestionManual': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestions': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
payments.update({
  appearance: { classes: { 'whop-Address': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Payments>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# CardElement
Source: https://docs.whop.com/elements/upcoming/payments/card

The drop-in card block: number, expiration, and security code pre-arranged as one field group. Reached through `payments.create("card")`; drive your pay button off `onChange`, then confirm with `payments.createConfirmationToken()`. Card numbers never touch your page or ours. Two arrangements via `layout`: 'stacked' (default) or 'compact' (one row).

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Payments`](/elements/upcoming/payments/overview) group. Render `<CardElement />` inside it (React), or call `payments.create('card', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

<Note>**Exclusive.** When using `CardElement`, you can't mount `PaymentElement` or `CardFields` in the same Payments handle. These are alternatives: mount one at a time, and destroy it to mount another.</Note>

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments, CardElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            <CardElement onChange={(payload) => console.log("change", payload)} />
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
      payments.create('card', { onChange: (payload) => console.log("change", payload) }).mount('#payments-card');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="layout" type="&#x22;compact&#x22; | &#x22;stacked&#x22;">
  Field arrangement: 'stacked' (default) puts the number on top with expiration and security code below; 'compact' is the classic single row — the number flexes, expiration and security code sit fixed-width to the right, all inside one visual container. Defaults to `"stacked"`.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onChange`

The card fields changed — `complete: true` means all three are filled so the confirm can run; drive your pay button off it. `brand` is the detected card network.

**Signature:** `((payload: { complete: boolean; brand: string; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<CardElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                         | Targets                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `.whop-Card`                  | The card element root                                                                             |
| `.whop-CardError`             | The error pane shown when the card configuration cannot load                                      |
| `.whop-CardField`             | One card field cell — number, expiry, or CVC                                                      |
| `.whop-CardFieldError`        | The Invalid / Incomplete message under a card field                                               |
| `.whop-CardFieldGroup`        | The grouped card fields — number on top, expiry and CVC below                                     |
| `.whop-CardFieldInput`        | The bordered input container around a PCI field                                                   |
| `.whop-CardFieldInputFocused` | Added to the input container while its field is focused                                           |
| `.whop-CardFieldInputInvalid` | Added to the input container while its field is invalid or incomplete                             |
| `.whop-CardFieldRow`          | The compact single-row card field group — number flexing, expiry and CVC fixed-width to the right |
| `.whop-CardSaveNotice`        | The save-for-future-purchases consent line                                                        |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-Card': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardField': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldGroup': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputFocused': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardSaveNotice': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
payments.update({
  appearance: { classes: { 'whop-Card': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Payments>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# CardFields
Source: https://docs.whop.com/elements/upcoming/payments/cardFields

The exploded card unit: three individually mountable, PCI-isolated fields (number, expiration, security code) under one completeness surface — for layouts the drop-in card element can't express. Reached through `payments.create("cardFields")`: place each field yourself, drive your pay button off `onChange`, confirm with `payments.createConfirmationToken()`. Card numbers never touch your page or ours.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

A **sub-controller** in the [`Payments`](/elements/upcoming/payments/overview) group. In vanilla, mint it with `payments.create('cardFields', { … })`. In React, render `<CardFields>` inside `<Payments>`: mounting mints it, unmounting destroys it. Either way you mount its elements off the handle you get back. Calling `destroy()` tears it down and frees its place for the alternatives, and a later `create('cardFields')` starts fresh.

<Note>**Exclusive.** When using `CardFields`, you can't mount `PaymentElement` or `CardElement` in the same Payments handle. These are alternatives: mount one at a time, and destroy it to mount another.</Note>

## Preview

A live, interactive demo of this sub-controller's default arrangement with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments, CardFields, CardNumberElement, CardExpiryElement, CardCvcElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            <CardFields>
              <CardNumberElement />
              <CardExpiryElement />
              <CardCvcElement />
            </CardFields>
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
      const cardFields = payments.create('cardFields', { /* options */ });
      cardFields.create('cardNumber').mount('#payments-cardFields-cardNumber');
      cardFields.create('cardExpiry').mount('#payments-cardFields-cardExpiry');
      cardFields.create('cardCvc').mount('#payments-cardFields-cardCvc');
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `payments.create('cardFields', { … })`, or as props on `<CardFields>` in React. Parent-injected props never appear here.

<ResponseField name="layout" type="&#x22;compact&#x22; | &#x22;stacked&#x22;">
  How the composed card faces draw their cell chrome: 'stacked' (default) shapes the number as the top cell with expiration and security code as the bottom row; 'compact' shapes all three as segments of one single-row container. The fused card element forwards its own `layout`; on the exploded face you own where each field mounts and every field draws fully independent chrome — all corners rounded, full border. Defaults to `"stacked"`.
</ResponseField>

<ResponseField name="publicKey" type="string">
  Advanced: a Basis Theory publishable key to use instead of reading the matrix card entry. The composing card faces supply it from the matrix they already hold; omitted, the unit fetches its own.
</ResponseField>

## Events

Pass a callback in the create options / React props.

### `onChange`

Field completeness changed — `complete: true` means all three fields are filled so the confirm can run; drive your pay button off it. `brand` is the detected card network.

**Signature:** `((payload: { complete: boolean; brand: string; }) => void)`

### `onLoadingChange`

Fired when the grouped loading state changes. `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the minted sub handle, which is the return of `payments.create('cardFields', { … })`.

### `tokenize`

Tokenize the three mounted fields into a card credential WITHOUT minting a confirmation token (also emitted to the declaring controller as `tokenized`) — the advanced seam; confirming a payment wants `payments.createConfirmationToken`. Validation failures land on the failing field and throw a legible error.

**Signature:** `(input: { accountId?: string | undefined; }) => Promise<{ token: string; }>`

### `collect`

The exploded face's collection — `payments.createConfirmationToken` (the confirm cascade) is the verb to call; this surface action is where its cardFields branch lands: tokenizes the fields and returns the collected bag the controller mints from.

**Signature:** `(input: { billingDetails?: { email?: string | undefined; name?: string | undefined; address?: { country?: string | undefined; line1?: string | undefined; city?: string | undefined; postal_code?: string | undefined; } | undefined; } | undefined; }) => Promise<{ paymentMethod: { type: string; category: string; card: { token: string; }; }; billingDetails: { email: string; name?: string | undefined; address?: { country?: string | undefined; line1?: string | undefined; city?: string | undefined; postal_code?: string | undefined; } | undefined; }; }>`

### `update`

Live-update the sub-controller's consumer props and `on<Event>` callbacks.

**Signature:** `(options: Partial<CardFieldsSubOptions>) => void`

### `destroy`

Tear the sub-controller down: its mounted elements are destroyed, its runtime state is discarded, and its exclusive slot is freed, and a later `create("cardFields")` boots fresh.

**Signature:** `() => void`

## Elements

The elements this sub-controller mounts. Each has its own page:

<CardGroup>
  <Card title="CardNumberElement" href="/elements/upcoming/payments/cardFields-cardNumber">
    The PCI card number field — a Basis Theory hosted input under frosted chrome. A child of the card unit; the card number never touches this page.
  </Card>

  <Card title="CardExpiryElement" href="/elements/upcoming/payments/cardFields-cardExpiry">
    The PCI card expiration field — a Basis Theory hosted input under frosted chrome. A child of the card unit.
  </Card>

  <Card title="CardCvcElement" href="/elements/upcoming/payments/cardFields-cardCvc">
    The PCI security code field — a Basis Theory hosted input under frosted chrome. A child of the card unit.
  </Card>
</CardGroup>


# CardCvcElement
Source: https://docs.whop.com/elements/upcoming/payments/cardFields-cardCvc

The PCI security code field — a Basis Theory hosted input under frosted chrome. A child of the card unit.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`CardFields`](/elements/upcoming/payments/cardFields) sub-controller in the [`Payments`](/elements/upcoming/payments/overview) group. Render `<CardCvcElement />` inside `<CardFields>` (React), or mint the sub and mount off it (vanilla): `payments.create('cardFields', { … }).create('cardCvc', { … })`. Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments, CardFields, CardCvcElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            <CardFields>
              <CardCvcElement />
            </CardFields>
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
      const cardFields = payments.create('cardFields', { /* options */ });
      cardFields.create('cardCvc').mount('#payments-cardFields-cardCvc');
    </script>
    ```
  </CodeGroup>
</div>

## Props

*This element takes no consumer props.*

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<CardCvcElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                         | Targets                                                               |
| ----------------------------- | --------------------------------------------------------------------- |
| `.whop-CardField`             | One card field cell — number, expiry, or CVC                          |
| `.whop-CardFieldError`        | The Invalid / Incomplete message under a card field                   |
| `.whop-CardFieldInput`        | The bordered input container around a PCI field                       |
| `.whop-CardFieldInputFocused` | Added to the input container while its field is focused               |
| `.whop-CardFieldInputInvalid` | Added to the input container while its field is invalid or incomplete |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-CardField': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputFocused': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
payments.update({
  appearance: { classes: { 'whop-CardField': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Payments>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# CardExpiryElement
Source: https://docs.whop.com/elements/upcoming/payments/cardFields-cardExpiry

The PCI card expiration field — a Basis Theory hosted input under frosted chrome. A child of the card unit.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`CardFields`](/elements/upcoming/payments/cardFields) sub-controller in the [`Payments`](/elements/upcoming/payments/overview) group. Render `<CardExpiryElement />` inside `<CardFields>` (React), or mint the sub and mount off it (vanilla): `payments.create('cardFields', { … }).create('cardExpiry', { … })`. Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments, CardFields, CardExpiryElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            <CardFields>
              <CardExpiryElement />
            </CardFields>
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
      const cardFields = payments.create('cardFields', { /* options */ });
      cardFields.create('cardExpiry').mount('#payments-cardFields-cardExpiry');
    </script>
    ```
  </CodeGroup>
</div>

## Props

*This element takes no consumer props.*

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<CardExpiryElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                         | Targets                                                               |
| ----------------------------- | --------------------------------------------------------------------- |
| `.whop-CardField`             | One card field cell — number, expiry, or CVC                          |
| `.whop-CardFieldError`        | The Invalid / Incomplete message under a card field                   |
| `.whop-CardFieldInput`        | The bordered input container around a PCI field                       |
| `.whop-CardFieldInputFocused` | Added to the input container while its field is focused               |
| `.whop-CardFieldInputInvalid` | Added to the input container while its field is invalid or incomplete |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-CardField': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputFocused': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
payments.update({
  appearance: { classes: { 'whop-CardField': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Payments>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# CardNumberElement
Source: https://docs.whop.com/elements/upcoming/payments/cardFields-cardNumber

The PCI card number field — a Basis Theory hosted input under frosted chrome. A child of the card unit; the card number never touches this page.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`CardFields`](/elements/upcoming/payments/cardFields) sub-controller in the [`Payments`](/elements/upcoming/payments/overview) group. Render `<CardNumberElement />` inside `<CardFields>` (React), or mint the sub and mount off it (vanilla): `payments.create('cardFields', { … }).create('cardNumber', { … })`. Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments, CardFields, CardNumberElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            <CardFields>
              <CardNumberElement />
            </CardFields>
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
      const cardFields = payments.create('cardFields', { /* options */ });
      cardFields.create('cardNumber').mount('#payments-cardFields-cardNumber');
    </script>
    ```
  </CodeGroup>
</div>

## Props

*This element takes no consumer props.*

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<CardNumberElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                         | Targets                                                               |
| ----------------------------- | --------------------------------------------------------------------- |
| `.whop-CardField`             | One card field cell — number, expiry, or CVC                          |
| `.whop-CardFieldError`        | The Invalid / Incomplete message under a card field                   |
| `.whop-CardFieldInput`        | The bordered input container around a PCI field                       |
| `.whop-CardFieldInputFocused` | Added to the input container while its field is focused               |
| `.whop-CardFieldInputInvalid` | Added to the input container while its field is invalid or incomplete |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-CardField': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputFocused': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
payments.update({
  appearance: { classes: { 'whop-CardField': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Payments>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# EmailElement
Source: https://docs.whop.com/elements/upcoming/payments/email

Collects the buyer's email — the one email truth for the checkout: while this element is mounted its value rides `payments.createConfirmationToken` automatically (explicit `billingDetails.email` input still wins), exactly like the address element owns the billing address. It also recognizes returning buyers (Link-style): once a complete email matches a Whop account, a "Welcome back" sign-in affordance appears; choosing it pops a verification-code dialog, and a verified sign-in unlocks the buyer's saved payment methods in the payment element. Signing in is always optional — a guest checkout proceeds on the email alone.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Payments`](/elements/upcoming/payments/overview) group. Render `<EmailElement />` inside it (React), or call `payments.create('email', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments, EmailElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            <EmailElement onChange={(payload) => console.log("change", payload)} />
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
      payments.create('email', { onChange: (payload) => console.log("change", payload) }).mount('#payments-email');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="label" type="boolean">
  Render the built-in localized label above the field. Hosts that render their own label pass false — the input keeps a localized aria-label either way. Defaults to `true`.
</ResponseField>

<ResponseField name="defaultValue" type="string">
  Seed value applied once at mount. Defaults to `""`.
</ResponseField>

<ResponseField name="placeholder" type="string">
  Placeholder text for the email input. Empty (default) renders `you@example.com`. Defaults to `""`.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onChange`

The email changed — `complete: true` means it is a plausible address. Fires with the signed-in email when the buyer signs in. The controller consumes the same event to feed `createConfirmationToken`.

**Signature:** `((payload: { email: string; complete: boolean; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<EmailElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                     | Targets                                                          |
| ------------------------- | ---------------------------------------------------------------- |
| `.whop-Email`             | The email element root                                           |
| `.whop-EmailError`        | The invalid-email message under the field                        |
| `.whop-EmailInput`        | The email input                                                  |
| `.whop-EmailInputInvalid` | Added to the input while the value is not a plausible email      |
| `.whop-EmailLabel`        | The label above the email field                                  |
| `.whop-EmailSignedIn`     | The signed-in row under the locked field                         |
| `.whop-EmailSignIn`       | The Welcome back sign-in affordance shown for a recognized email |
| `.whop-EmailSignInError`  | The sign-in failure message under the affordance                 |
| `.whop-EmailSignOut`      | The control that returns the field to a different email          |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-Email': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailError': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailSignedIn': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailSignIn': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailSignInError': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailSignOut': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
payments.update({
  appearance: { classes: { 'whop-Email': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Payments>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# Payments
Source: https://docs.whop.com/elements/upcoming/payments/overview

Drives a payment collection surface against the Whop Payments API. Charge config is a plan id OR the inline currency/amount — a plan resolves client-side to the same shape, one path either way. Mount ONE of its faces — the payment element (the full method list), the fused card element, or the exploded card-fields unit — then `payments.createConfirmationToken({ billingDetails })` is the ONE confirm verb for all of them: it tokenizes the selection and mints a confirmation token your server confirms with a secret key; the payment's client_secret then drives any pending step via `handleNextAction`.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

## Playground

Assemble the elements with sample data. Drive the controls, add and arrange elements, and watch events fire live:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            {/* mount elements here */}
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `whop.payments.create({ … })`, or as props on `<Payments>` in React.

<ResponseField name="accountId" type="string">
  OPTIONLESS — the statics rail (`WhopElements.payments.handleNextAction`) boots the namespace handle with no options; no collection face can be created on such a handle (they refuse loudly — pass a plan or currency+amount to collect).
</ResponseField>

<ResponseField name="plan" type="string">
  An existing plan id (`plan_…`) — resolved client-side into the inline shape (currency, amount, method configuration); a plan is a preset for the same one config. Pass a plan OR the inline currency/amount, never both.
</ResponseField>

<ResponseField name="returnUrl" type="string">
  Where the buyer lands after an off-site step (bank page, 3DS). Defaults to the mounting page.
</ResponseField>

<ResponseField name="setupFutureUsage" type="&#x22;off_session&#x22; | &#x22;on_session&#x22;">
  Attest the element should display save-consent and mint vault-capable tokens: `off_session` or `on_session`.
</ResponseField>

<ResponseField name="previewWalletAvailability" type="WalletAvailability">
  Presentation-only wallet facts for deterministic previews. Live checkouts leave this unset and use the host probe.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO currency the checkout charges in — filters the method matrix.
</ResponseField>

<ResponseField name="amount" type="number">
  Charge amount in minor units — methods whose bounds exclude it are not offered.
</ResponseField>

<ResponseField name="paymentMethodConfiguration" type="{ enabled?: string[] | undefined; disabled?: string[] | undefined; include_platform_defaults?: boolean | undefined; }">
  Seller method filtering in the API's own shape (`enabled`, `disabled`, `include_platform_defaults`): disabled types are removed, enabled re-adds against the account's offered set, and with `include_platform_defaults: false` only enabled types remain. A plan carries its own.
</ResponseField>

<ResponseField name="appearance" type="Appearance">
  Visual customization for this group's elements. Overrides the global `WhopElements({ appearance })`; change it live with `update({ appearance })`.
</ResponseField>

<ResponseField name="locale" type="WhopElementsLocale">
  Locale for this group's element UI text. One of the app's built locales, overriding the global config; any other value falls back to the default locale.
</ResponseField>

<Note>The options are a union. Provide **exactly one** of these shapes, plus the shared event callbacks below:</Note>

* `{ accountId: string; plan: string; returnUrl?: string; setupFutureUsage?: "off_session" | "on_session"; previewWalletAvailability?: WalletAvailability }`
* `{ accountId: string; currency: string; amount: number; paymentMethodConfiguration?: { enabled?: string[] | undefined; disabled?: string[] | undefined; include_platform_defaults?: boolean | undefined; }; returnUrl?: string; setupFutureUsage?: "off_session" | "on_session"; previewWalletAvailability?: WalletAvailability }`
* `{ accountId?: undefined; plan?: undefined; currency?: undefined; amount?: undefined; paymentMethodConfiguration?: undefined; returnUrl?: string; setupFutureUsage?: "off_session" | "on_session"; previewWalletAvailability?: WalletAvailability }`

## Events

Pass a callback in the create options / React props.

### `onConfirmationToken`

A confirmation token was minted (also returned by `createConfirmationToken()`). Confirm it server-side with your secret key.

**Signature:** `((payload: { id: string; type: string; }) => void)`

### `onLoadingChange`

Fired when the grouped loading state changes. `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the Payments handle, which is the return of `whop.payments.create({ … })` (vanilla) or `usePayments()` (React).

### `createConfirmationToken`

Mint a confirmation token from whatever the buyer selected — the ONE confirm verb, for every face, called from YOUR pay button on the payments handle. A card selection tokenizes inside the mounted face (pass the billing details your checkout collected — email required; card also requires name and address with line1 + country). Returns `{ confirmationToken, type }`; confirm it server-side with your secret key, then call `WhopElements.payments.handleNextAction(...)`. Runs on your page (host-side), not in the controller iframe.

**Signature:** `(input: { billingDetails?: { email?: string | undefined; name?: string | undefined; address?: { country?: string | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; } | undefined; } | undefined; }) => Promise<{ confirmationToken: string; type: string; }>`

### `update`

Update the handle live: any of its options (`appearance` and `locale` included), propagated to every mounted element. React consumers never call it; updating the namespace component's props does the same.

**Signature:** `(options: Partial<PaymentsOptions>) => void`

## Static methods

Available before anything mounts. Call them on the namespace accessor: `whop.payments.<method>(…)` (vanilla, where `whop = WhopElements(…)`) or `useWhop().payments.<method>(…)` (React). Useful when no element is on the page, e.g. handling a post-redirect next action.

### `handleNextAction`

Drive a confirmed payment's pending step to a resting state with NO element mounted — the universal completion surface. The `clientSecret` alone identifies the payment — its tag is embedded in the secret, so there is no separate payment id to pass (or mismatch). A frameable step (`next_action.render` includes `inline` — 3DS challenges, most wallet/redirect rails) runs in a dismissible dialog on YOUR page and the promise resolves in place with the payment's fresh status (`redirected: false`; a dismissed dialog resolves with the still-pending status — re-offer at will). A full-page-only step redirects THIS tab (`redirected: true`) and the hosted return landing brings the buyer back to your `return_url` — or parks them on a hosted receipt when you never set one. Pass `returnUrl` to set or override that destination right here: it's PATCHed onto the payment under the client\_secret before the step runs (the innermost layer of the layered return\_url; only a full-page step navigates to it — the dialog resolves in place, and a failed PATCH rejects before any step runs). No pending step resolves immediately. Called as `WhopElements.payments.handleNextAction(...)`.

**Signature:** `(input: { clientSecret: string; returnUrl?: string | undefined; pollIntervalMs?: number | undefined; }) => Promise<{ status: string; redirected: boolean; lastPaymentError: { code?: string | null | undefined; decline_code?: string | null | undefined; message?: string | null | undefined; } | null; }>`

## Returned objects

Live objects returned by the methods above. Hold the reference and call it on your page; these are capabilities, not serializable data.

## `WalletAvailability`

Host-probed wallet facts (payment-request.ts canMakePayment reduced to serializable data): matrix single-type reads ∩ device capability ∩ (Google) origin clearance.

### `applePay`

**Signature:** `boolean`

### `googlePay`

**Signature:** `boolean`

## Elements

The elements this group mounts. Each has its own page:

<CardGroup>
  <Card title="AddressElement" href="/elements/upcoming/payments/address">
    Collects a billing or shipping address with per-country formats — the field set, order, required flags, and postal-code validation adapt to the selected country — plus address autocomplete on the street field. Drive your own forms off `onChange`, or call `validate()` / `getValues()` on the handle.
  </Card>

  <Card title="EmailElement" href="/elements/upcoming/payments/email">
    Collects the buyer's email — the one email truth for the checkout: while this element is mounted its value rides `payments.createConfirmationToken` automatically (explicit `billingDetails.email` input still wins), exactly like the address element owns the billing address. It also recognizes returning buyers (Link-style): once a complete email matches a Whop account, a "Welcome back" sign-in affordance appears; choosing it pops a verification-code dialog, and a verified sign-in unlocks the buyer's saved payment methods in the payment element. Signing in is always optional — a guest checkout proceeds on the email alone.
  </Card>
</CardGroup>

**Alternatives.** These are exclusive; mount one at a time, and destroy it to mount another:

<CardGroup>
  <Card title="PaymentElement" href="/elements/upcoming/payments/payment">
    The drop-in payment method picker: shows the payment methods this seller accepts for the charge — filtered live by currency, amount, and seller configuration — and collects what the chosen method needs: card fields, billing address, method-specific inputs, and any required disclosures. Drive your pay button off the `change` event, call `payments.createConfirmationToken()` on click, confirm the token server-side with your secret key, then pass any pending step to `payments.handleNextAction(...)`. The `addressChange` event reports the billing address it collects as the buyer fills it in, so your checkout can quote tax, rate shipping, or update anything else that depends on the address. Two arrangements via `layout`: a stacked list (default) or a horizontal tile row.
  </Card>

  <Card title="CardElement" href="/elements/upcoming/payments/card">
    The drop-in card block: number, expiration, and security code pre-arranged as one field group. Reached through `payments.create("card")`; drive your pay button off `onChange`, then confirm with `payments.createConfirmationToken()`. Card numbers never touch your page or ours. Two arrangements via `layout`: 'stacked' (default) or 'compact' (one row).
  </Card>

  <Card title="CardFields" href="/elements/upcoming/payments/cardFields">
    The exploded card unit: three individually mountable, PCI-isolated fields (number, expiration, security code) under one completeness surface — for layouts the drop-in card element can't express. Reached through `payments.create("cardFields")`: place each field yourself, drive your pay button off `onChange`, confirm with `payments.createConfirmationToken()`. Card numbers never touch your page or ours. *(sub-controller, 3 elements)*
  </Card>
</CardGroup>

## Flow surfaces

These internal elements open automatically during flows (for example a confirmation or verification step). They are not part of the consumer API, so you never mount, configure, or subscribe to them directly.

* **AddressSuggestionsElement** (`addressSuggestions`): The address autocomplete overlay — suggestion rows plus "Enter address manually", anchored beside the street field.
* **BillingAddressSuggestionsElement** (`billingAddressSuggestions`): The billing address autocomplete overlay — suggestion rows plus "Enter address manually", anchored beside the billing street field.
* **VerificationCodeElement** (`verificationCode`): The buyer sign-in code dialog — popped by the payments controller when a recognized buyer chooses to sign in (payment-api.md §6). Collects the one-time code, verifies it against the pending session with the session's own client\_secret, offers a resend behind the session's resend window, and surfaces every verification failure honestly (wrong code, expired code, rate limit, an account that must finish sign-in from its emailed link). On success the session token flows to the controller internally and the dialog closes.
* **CompletePaymentElement** (`completePayment`): The hosted completion surface `payments.handleNextAction` presents as a detached modal: it drives a pending payment step — a framed PSP flow, bank-transfer instructions, a confirmation wait — to a resting state, polling the payment status under its scoped client\_secret, and closes itself when the payment rests. Never mounted directly.


# PaymentElement
Source: https://docs.whop.com/elements/upcoming/payments/payment

The drop-in payment method picker: shows the payment methods this seller accepts for the charge — filtered live by currency, amount, and seller configuration — and collects what the chosen method needs: card fields, billing address, method-specific inputs, and any required disclosures. Drive your pay button off the `change` event, call `payments.createConfirmationToken()` on click, confirm the token server-side with your secret key, then pass any pending step to `payments.handleNextAction(...)`. The `addressChange` event reports the billing address it collects as the buyer fills it in, so your checkout can quote tax, rate shipping, or update anything else that depends on the address. Two arrangements via `layout`: a stacked list (default) or a horizontal tile row.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Payments`](/elements/upcoming/payments/overview) group. Render `<PaymentElement />` inside it (React), or call `payments.create('payment', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

<Note>**Exclusive.** When using `PaymentElement`, you can't mount `CardElement` or `CardFields` in the same Payments handle. These are alternatives: mount one at a time, and destroy it to mount another.</Note>

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Payments, PaymentElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Payments /* options */>
            <PaymentElement onChange={(payload) => console.log("change", payload)} onAddressChange={(payload) => console.log("addressChange", payload)} />
          </Payments>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const payments = window.WhopElements().payments.create({ /* options */ });
      payments.create('payment', {
        onChange: (payload) => console.log("change", payload),
        onAddressChange: (payload) => console.log("addressChange", payload)
      }).mount('#payments-payment');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="fields" type="{ billingDetails?: &#x22;full&#x22; | &#x22;minimal&#x22; | &#x22;never&#x22; | undefined; }">
  Which internal collection blocks render. `billingDetails: 'minimal'` (default) collects each method's DECLARED payment minimum — exactly the billing fields the method's matrix entry declares (card: name on card, country, postal code — never a street address; most redirect and wallet methods declare nothing and render no block at all). `'full'` opts every fresh method into name plus the complete country format — for hosts who want a full billing address (tax-style collection is a checkout concern, not a payment requirement). `'never'` hides the block — pass the address in `createConfirmationToken({ billingDetails })` instead. The block's country select offers only the countries the method supports for the charge currency (a single-country method locks it). Defaults to `{"billingDetails":"minimal"}`.
</ResponseField>

<ResponseField name="layout" type="&#x22;accordion&#x22; | &#x22;horizontal&#x22;">
  Presentation of the method picker: 'accordion' (default) stacks the methods in a vertical list, each expanding its detail inline; 'horizontal' lays the methods out as a row of equal-width tiles (never scrolling — beyond four methods the row ends in a More tile whose native selector lists the rest, and a method picked there holds the last tile spot until the next pick) with the selected method's detail below. Selection and confirm behavior are identical in both. Defaults to `"accordion"`.
</ResponseField>

<ResponseField name="separated" type="boolean">
  Accordion layout only: render each method as its own visually separate card with spacing between items, instead of the fused list. Ignored while `layout` is 'horizontal'. Defaults to `false`.
</ResponseField>

<ResponseField name="order" type="string[]">
  Display ordering of the methods, in every layout: listed types render first in the given order, unlisted types keep their relative order after them. Presentation only — never affects which methods are available. Defaults to `[]`.
</ResponseField>

<ResponseField name="autoSelect" type="boolean">
  Select the first offered method automatically once the methods resolve (default true) — respects `order` and emits `selected` + `change` exactly like a click. One-shot: it never re-fires after the buyer interacts, and it does nothing when no method is offered. Set false to mount with nothing selected. Separately from this flag, when a live charge update drops the SELECTED method off the list the selection falls back to the first offered method (an element with nothing selected stays blank). Defaults to `true`.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onChange`

The selection changed — `complete: true` means a method is chosen (and, for card, its fields are filled; for methods declaring required inputs, those are filled and valid) so the confirm can run; drive your pay button off it. `method` carries the selected entry's matrix metadata (category, per-currency country list, amount bounds) so your page can react — e.g. narrow its own country field. `supportsBuyerFee` says whether a charge on the chosen method carries Whop's buyer service fee, so a checkout can re-price the total it shows before the buyer pays.

**Signature:** `((payload: { complete: boolean; type?: string | undefined; supportsBuyerFee?: boolean | undefined; method?: { type: string; category: string; template: string; display_name: string; countries: ({ country: string; min_amount: number | null; max_amount: number | null; })[]; min_amount: number | null; max_amount: number | null; } | undefined; }) => void)`

### `onAddressChange`

The billing address the element collects itself changed — quote tax off it, rate your own shipping off it, or drive any address-dependent part of your page off it. Carries the whole postal address: `country` (ISO2) always, plus `line1`, `line2`, `city`, `state` and `postal_code` whenever the country's format collects them (a key is absent when the form has no value for it — several countries have no state or no postal code at all). Debounced \~300ms and emitted only on a real change, so it maps one-to-one onto a quote. `complete: true` means the whole billing block is filled and valid. Fires only while the element collects the address itself — with `fields.billingDetails: 'never'`, or beside a live address element (which collapses the internal block), drive your quote off that surface's own `change` instead.

**Signature:** `((payload: { complete: boolean; address: { line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `select`

Select a payment method imperatively. `select('cashapp')` runs the same path a buyer's click does — the tile expands, `selected` and `change` fire (a card selection stays `complete: false` until its fields are filled). A type that isn't offered — unknown, seller-disabled, or amount-gated off the list — refuses with `code: 'METHOD_NOT_OFFERED'`. `select(null)` clears the selection, emitting `change { complete: false }`. Pair with `autoSelect={false}` (which mounts the element blank) for full external control of the selection.

**Signature:** `(input: string | null) => Promise<void>`

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<PaymentElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                                 | Targets                                                                                                                                                                         |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.whop-Address`                       | The address form root                                                                                                                                                           |
| `.whop-AddressErrorSummary`           | The summary line shown when validation reveals missing or invalid fields                                                                                                        |
| `.whop-AddressField`                  | One field cell in the address form                                                                                                                                              |
| `.whop-AddressFieldError`             | The error line under an address field (full layout)                                                                                                                             |
| `.whop-AddressFieldInput`             | A text input in the address form                                                                                                                                                |
| `.whop-AddressFieldInputInvalid`      | Added to an address input while it fails validation                                                                                                                             |
| `.whop-AddressFieldInvalid`           | Added to a compact field cell while it fails validation                                                                                                                         |
| `.whop-AddressFieldLabel`             | The label above an address field (full layout)                                                                                                                                  |
| `.whop-AddressFieldSelect`            | A select (country, state, organization type) in the address form                                                                                                                |
| `.whop-AddressLine2Toggle`            | The "Add address line 2" text button shown while line 2 is collapsed                                                                                                            |
| `.whop-AddressManualEntry`            | The "Enter address manually" text button below the collapsed form — expands the full country format                                                                             |
| `.whop-AddressSuggestion`             | One suggestion row in the autocomplete overlay                                                                                                                                  |
| `.whop-AddressSuggestionActive`       | Added to the keyboard/pointer-active suggestion row                                                                                                                             |
| `.whop-AddressSuggestionManual`       | The "Enter address manually" row closing the suggestions list                                                                                                                   |
| `.whop-AddressSuggestions`            | The autocomplete suggestions overlay anchored to the address line 1 field                                                                                                       |
| `.whop-CardField`                     | One card field cell — number, expiry, or CVC                                                                                                                                    |
| `.whop-CardFieldError`                | The Invalid / Incomplete message under a card field                                                                                                                             |
| `.whop-CardFieldGroup`                | The grouped card fields — number on top, expiry and CVC below                                                                                                                   |
| `.whop-CardFieldInput`                | The bordered input container around a PCI field                                                                                                                                 |
| `.whop-CardFieldInputFocused`         | Added to the input container while its field is focused                                                                                                                         |
| `.whop-CardFieldInputInvalid`         | Added to the input container while its field is invalid or incomplete                                                                                                           |
| `.whop-CardLabel`                     | The "Card information" label above the field group                                                                                                                              |
| `.whop-Payment`                       | The payment element root                                                                                                                                                        |
| `.whop-PaymentBillingBlock`           | The payment element's internal billing address block                                                                                                                            |
| `.whop-PaymentCardFields`             | The inline card fields panel                                                                                                                                                    |
| `.whop-PaymentDetailIcon`             | The template icon beside the detail region's explainer                                                                                                                          |
| `.whop-PaymentDetailRegion`           | The expanded detail region for a selected method — collection surfaces first (inline card fields, declared inputs), then the explainer and disclosure lines as the bottom block |
| `.whop-PaymentDetailSubtext`          | The consent subtext under the explainer on wallet methods                                                                                                                       |
| `.whop-PaymentDetailText`             | The detail region's explainer line                                                                                                                                              |
| `.whop-PaymentError`                  | The error pane shown when methods cannot load or none are available                                                                                                             |
| `.whop-PaymentFieldError`             | The Invalid message under a declared input                                                                                                                                      |
| `.whop-PaymentFieldInput`             | A declared method input in the detail region                                                                                                                                    |
| `.whop-PaymentFieldInputInvalid`      | Added to a declared input while its value fails the declared format                                                                                                             |
| `.whop-PaymentFieldLabel`             | The label above a declared method input in the detail region                                                                                                                    |
| `.whop-PaymentMandateLink`            | The mandate terms link inside the mandate notice                                                                                                                                |
| `.whop-PaymentMandateNotice`          | The mandate authorization notice on methods whose matrix config declares a mandate                                                                                              |
| `.whop-PaymentMethod`                 | One payment method — the row plus its expanding detail region                                                                                                                   |
| `.whop-PaymentMethodDetail`           | The expanding region that reveals the selected method's detail — inline card fields, explainer, or declared inputs                                                              |
| `.whop-PaymentMethodIcon`             | The method icon on a row                                                                                                                                                        |
| `.whop-PaymentMethodLabel`            | The method display name on a row                                                                                                                                                |
| `.whop-PaymentMethodMoreSelect`       | The invisible native select stretched over the More tile                                                                                                                        |
| `.whop-PaymentMethodMoreTile`         | The compact overflow tile ending the capped tile row — stacked overflow-method icons over a chevron, its native select lists the remaining methods                              |
| `.whop-PaymentMethodPanel`            | The selected method's detail panel below the tile row (horizontal layout)                                                                                                       |
| `.whop-PaymentMethodRadio`            | The radio indicator on a method row                                                                                                                                             |
| `.whop-PaymentMethodRadioSelected`    | Added to the radio indicator while its method is selected                                                                                                                       |
| `.whop-PaymentMethodRow`              | The clickable payment method row                                                                                                                                                |
| `.whop-PaymentMethodRowSelected`      | Added to the method row while it is the selected method                                                                                                                         |
| `.whop-PaymentMethods`                | The payment method list                                                                                                                                                         |
| `.whop-PaymentMethodSeparated`        | Added to a method item while it renders as its own separated card                                                                                                               |
| `.whop-PaymentMethodsSeparated`       | Added to the method list while separated accordion items are on                                                                                                                 |
| `.whop-PaymentMethodTile`             | One method tile in the horizontal tile row                                                                                                                                      |
| `.whop-PaymentMethodTileRow`          | The method tile row (horizontal layout) — never scrolls; beyond the tile cap the overflow methods live in the compact More tile                                                 |
| `.whop-PaymentMethodTileSelected`     | Added to a method tile while it is the selected method                                                                                                                          |
| `.whop-PaymentMoreRow`                | The "N more payment methods" expander row                                                                                                                                       |
| `.whop-PaymentSavedMethod`            | One saved payment method specifically — carries PaymentMethod too                                                                                                               |
| `.whop-PaymentSavedMethodHint`        | The saved method's trailing detail — a card's expiry                                                                                                                            |
| `.whop-PaymentSavedMethodRow`         | The clickable saved method row specifically — carries PaymentMethodRow too                                                                                                      |
| `.whop-PaymentSavedMethodRowSelected` | The selected marker on a saved method row specifically                                                                                                                          |
| `.whop-PaymentSavedMethods`           | The saved-methods list specifically — carries PaymentMethods too, so one rule styles both lists                                                                                 |
| `.whop-PaymentSavedMethodSeparated`   | The separated marker on a saved method specifically                                                                                                                             |
| `.whop-PaymentSavedMore`              | The control that fetches the next page of saved payment methods                                                                                                                 |
| `.whop-PaymentSavedMoreSpinner`       | The spinner shown while the next page of saved payment methods loads                                                                                                            |
| `.whop-PaymentSaveNotice`             | The save-for-future-purchases consent line closing the detail region                                                                                                            |
| `.whop-PaymentSettlementNotice`       | The settlement-window hint on methods whose matrix config declares one                                                                                                          |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-Address': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressErrorSummary': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressField': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressFieldSelect': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressLine2Toggle': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressManualEntry': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestion': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestionActive': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestionManual': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressSuggestions': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardField': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldGroup': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputFocused': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-Payment': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentBillingBlock': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentCardFields': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentDetailIcon': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentDetailRegion': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentDetailSubtext': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentDetailText': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentError': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentFieldError': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentFieldInput': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentFieldInputInvalid': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentFieldLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMandateLink': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMandateNotice': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethod': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodDetail': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodIcon': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodLabel': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodMoreSelect': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodMoreTile': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodPanel': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodRadio': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodRadioSelected': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodRowSelected': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethods': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodSeparated': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodsSeparated': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodTile': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodTileRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMethodTileSelected': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentMoreRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethod': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethodHint': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethodRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethodRowSelected': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethods': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMethodSeparated': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMore': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSavedMoreSpinner': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSaveNotice': { borderRadius: '8px', fontWeight: '600' },
      'whop-PaymentSettlementNotice': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
payments.update({
  appearance: { classes: { 'whop-Address': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Payments>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# ActivityElement
Source: https://docs.whop.com/elements/upcoming/wallet/activity

An account's ledger activity: every movement of money in or out, newest first. The list pages as the viewer scrolls, and rows report which one was tapped instead of navigating, so you can open your own detail screen.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

<Tabs>
  <Tab title="Web">
    Belongs to the [`Wallet`](/elements/upcoming/wallet/overview) group. Render `<ActivityElement />` inside it (React), or call `wallet.create('activity', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

    ## Preview

    A live, interactive demo of this element with sample data:

    <div>
      <div />

      <div />
    </div>

    ## Usage

    <div>
      <CodeGroup>
        ```tsx React theme={null}
        import { WhopElements, Wallet, ActivityElement } from "@whop/elements-react";
        import { loadWhop } from "@whop/elements";

        function Example() {
          return (
            <WhopElements elements={loadWhop()}>
              <Wallet /* options */>
                <ActivityElement onActivitySelected={(payload) => console.log("activitySelected", payload)} onDateRangeChanged={(payload) => console.log("dateRangeChanged", payload)} />
              </Wallet>
            </WhopElements>
          );
        }
        ```

        ```html Vanilla theme={null}
        <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
        <script type="module">
          const wallet = window.WhopElements().wallet.create({ /* options */ });
          wallet.create('activity', {
            onActivitySelected: (payload) => console.log("activitySelected", payload),
            onDateRangeChanged: (payload) => console.log("dateRangeChanged", payload)
          }).mount('#wallet-activity');
        </script>
        ```
      </CodeGroup>
    </div>

    ## Props

    <ResponseField name="currency" type="string">
      Only show activity for this currency. Without it, activity from every currency is shown.
    </ResponseField>

    <ResponseField name="accessToken" type="string">
      A scoped token for the read. An account needs `company:balance:read`, and a user needs `user:balance:read`. Mint it on your server with `POST /v1/access_tokens`. Without it the read uses the viewer's own session, which only works same-origin.
    </ResponseField>

    <ResponseField name="canOpenCardTransactionDetails" type="boolean">
      When off, card transaction rows render inert (no click, no hover) instead of firing `activitySelected`. Use it when you know the viewer isn't allowed to see those details. Defaults to `true`.
    </ResponseField>

    ### Direct mode only

    *These props exist only on the in-process (direct-mode) component. The hosted embed never carries them, and the element renders without them.*

    <ResponseField name="emptyState" type="direct mode only">
      Direct-mode only. An optional empty-state override for first-party hosts. Embeds ignore it and render the built-in empty copy.
    </ResponseField>

    ## Events

    Pass a callback in the create options (or React prop) to receive these.

    ### `onActivitySelected`

    A row was clicked. Open your own detail view or route for it; the element never navigates.

    **Signature:** `((payload: { activity: LedgerActivity; }) => void)`

    ### `onDateRangeChanged`

    The viewer changed the date filter through the filter row rather than through `setDateRange`. Clear any range selection of your own, like a chart brush, that no longer matches.

    **Signature:** `((payload: { dateRange: { start: string; end: string; } | null; }) => void)`

    ### `onLoaderStart`

    Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

    **Signature:** `(() => void)`

    ### `onReady`

    Fired once the element has booted and painted its first complete frame.

    **Signature:** `(() => void)`

    ### `onError`

    Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

    **Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

    ## Methods

    Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

    ### `refresh`

    Re-fetch the account's activity from the first page. Call it after a mutation made elsewhere (a deposit, a send) so the list reflects it without waiting for the cache to expire.

    **Signature:** `() => Promise<void>`

    ### `setDateRange`

    Set the date filter from outside the element, for example wiring a chart brush selection into the list. Pass `null` to clear it.

    **Signature:** `(input: ActivityDateRangeOverride | null) => Promise<void>`

    ### `mount`

    Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

    **Signature:** `(target: string | HTMLElement) => void`

    ### `destroy`

    Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

    **Signature:** `() => void`

    ### `update`

    Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

    **Signature:** `(options: Partial<ActivityElementProps>) => void`

    ## Styling

    Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

    | Class                   | Targets                                                          |
    | ----------------------- | ---------------------------------------------------------------- |
    | `.whop-ActivityRow`     | One ledger activity row — its icon, title, timestamp, and amount |
    | `.whop-ActivitySurface` | The activity feed — title, filters, and up to every fetched row  |

    ```ts theme={null}
    const wallet = whop.wallet.create({
      appearance: {
        classes: {
          'whop-ActivityRow': { borderRadius: '8px', fontWeight: '600' },
          'whop-ActivitySurface': { borderRadius: '8px', fontWeight: '600' }
        }
      }
    });

    // restyle live at any point, the same shape through update()
    wallet.update({
      appearance: { classes: { 'whop-ActivityRow': { fontWeight: '700' } } }
    });
    ```

    In React, pass the same object as the `appearance` prop on `<Wallet>`; `appearance` also applies globally at `WhopElements({ appearance })`.
  </Tab>

  <Tab title="Swift">
    <div>
      <div>
        `ActivityElement` shows an account's ledger activity: payments, payouts, transfers, swaps and disputes, newest first. It loads its own data and pages as the viewer scrolls, so the only thing you have to pass in is the account id. Pass a closure as well and you get the row the viewer tapped. It never navigates, so routing stays yours.

        ### Usage

        ```swift theme={null}
        import SwiftUI
        import WhopElements

        // WhopSDK.configure(tokenProvider:) runs once at app launch. See Getting started.
        struct ActivityScreen: View {
            var body: some View {
                ScrollView {
                    ActivityElement(
                        accountId: "biz_xxxx"
                    ) { activity in
                        print(activity.title, activity.amount)
                    }
                    .padding()
                }
            }
        }
        ```

        ### Parameters

        <ResponseField name="accountId" type="String">
          Whose ledger to list, given as a company's `biz_…` tag or a user's `user_…` tag. Both work directly; the feed reads the tag without resolving a ledger first.
        </ResponseField>

        <ResponseField name="showsTitle" type="Bool">
          Shows the built-in "Activity" heading. Defaults to `true`. Turn it off when your screen already has one.
        </ResponseField>

        <ResponseField name="onActivitySelected" type="((WalletActivity) -> Void)?">
          Called with the row the viewer tapped. The view never navigates, so route to your own detail screen.
        </ResponseField>

        ### `WalletActivity`

        What a selection hands back:

        * `id: String`: stable per row
        * `title: String` / `subtitle: String`: the row's two lines
        * `amount: Decimal`: signed, negative for money out
        * `currencyCode: String`
        * `postedAt: Date`
        * `isIncoming: Bool`

        ### States

        Shows a skeleton list while the first page loads, `No activity found` when the ledger has no movements, and the failure message with a `Try again` button when the read fails. If a later page fails, the rows already loaded stay on screen and a `Try again` appears at the bottom.

        ### Good to know

        * **Give it a scroll container.** The feed is a `LazyVStack` and pages as its last row appears, so outside a `ScrollView` it renders page one and never loads another.
        * Takes `biz_…` and `user_…` tags directly, so unlike the other wallet views it never has to resolve a ledger first.

        <Note>
          Authentication is set once for every element, not per element, so `WhopSDK.configure(tokenProvider:)` at app launch is enough. A view mounted before it lands renders a spinner and picks the token up when it arrives. See [Getting started](/elements/upcoming/getting-started) for the token provider. Theme with the `.whopTheme(_:)` modifier.
        </Note>
      </div>

      <div>
        <div>
          <iframe title="ActivityElement running on an iPhone simulator" />
        </div>
      </div>
    </div>
  </Tab>
</Tabs>


# Balances
Source: https://docs.whop.com/elements/upcoming/wallet/balances

Two views of an account's money. The balance view shows the total, a chart of how it changed, and a picker for the time range. The list view shows the holdings that make up that total, valued in dollars.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

<Tabs>
  <Tab title="Web">
    A **sub-controller** in the [`Wallet`](/elements/upcoming/wallet/overview) group. In vanilla, mint it with `wallet.create('balances', { … })`. In React, render `<Balances>` inside `<Wallet>`: mounting mints it, unmounting destroys it. Either way you mount its elements off the handle you get back. Calling `destroy()` tears it down, and a later `create('balances')` starts fresh.

    ## Preview

    A live, interactive demo of this sub-controller's default arrangement with sample data:

    <div>
      <div />

      <div />
    </div>

    ## Usage

    <div>
      <CodeGroup>
        ```tsx React theme={null}
        import { WhopElements, Wallet, Balances, BalanceElement, ListElement } from "@whop/elements-react";
        import { loadWhop } from "@whop/elements";

        function Example() {
          return (
            <WhopElements elements={loadWhop()}>
              <Wallet /* options */>
                <Balances>
                  <BalanceElement />
                  <ListElement />
                </Balances>
              </Wallet>
            </WhopElements>
          );
        }
        ```

        ```html Vanilla theme={null}
        <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
        <script type="module">
          const wallet = window.WhopElements().wallet.create({ /* options */ });
          const balances = wallet.create('balances', { /* options */ });
          balances.create('balance').mount('#wallet-balances-balance');
          balances.create('list').mount('#wallet-balances-list');
        </script>
        ```
      </CodeGroup>
    </div>

    ## Options

    Pass these to `wallet.create('balances', { … })`, or as props on `<Balances>` in React. Parent-injected props never appear here.

    *Balances takes no options.*

    ## Events

    Pass a callback in the create options / React props.

    ### `onLoadingChange`

    Fired when the grouped loading state changes. `true` while any mounted element is still loading.

    **Signature:** `((loading: boolean) => void)`

    ## Methods

    Call these on the minted sub handle, which is the return of `wallet.create('balances', { … })`.

    ### `update`

    Live-update the sub-controller's consumer props and `on<Event>` callbacks.

    **Signature:** `(options: Partial<BalancesSubOptions>) => void`

    ### `destroy`

    Tear the sub-controller down: its mounted elements are destroyed, its runtime state is discarded, and its exclusive slot is freed, and a later `create("balances")` boots fresh.

    **Signature:** `() => void`
  </Tab>

  <Tab title="Swift">
    <div>
      <div>
        [`BalanceElement`](/elements/upcoming/wallet/balances-balance#swift) and [`ListElement`](/elements/upcoming/wallet/balances-list#swift) are SwiftUI views from the [`WhopElements`](https://github.com/whopio/whopsdk-elements-swift) package. Both take an account id. Each loads its own data and holds its own state, so you can use one on its own or put both on the same screen. The example below is the whole integration.

        ### Usage

        ```swift theme={null}
        import SwiftUI
        import WhopElements

        // WhopSDK.configure(tokenProvider:) runs once at app launch. See Getting started.
        struct WalletScreen: View {
            let account = "biz_xxxx"

            var body: some View {
                ScrollView {
                    VStack(spacing: 24) {
                        BalanceElement(accountId: account)
                        ListElement(accountId: account)
                    }
                    .padding()
                }
            }
        }
        ```

        ### Parameters

        <ResponseField name="accountId" type="String">
          The account whose money the view reads, given as a company's `biz_…` tag. A `user_…` tag reads the viewer's own balance and needs viewer authentication (`WhopSDK.configureWithOAuth`), not an account token.
        </ResponseField>

        ### States

        Each view manages its own states, so neither blocks the other from rendering.

        ### Good to know

        * They share no state and load independently, so you can use one alone or both as below.
        * Read the detail on [`BalanceElement`](/elements/upcoming/wallet/balances-balance#swift) and [`ListElement`](/elements/upcoming/wallet/balances-list#swift); [`ActivityElement`](/elements/upcoming/wallet/activity#swift) lists the movements behind them.

        <Note>
          Authentication is set once for every element, not per element, so `WhopSDK.configure(tokenProvider:)` at app launch is enough. A view mounted before it lands renders a spinner and picks the token up when it arrives. See [Getting started](/elements/upcoming/getting-started) for the token provider. Theme with the `.whopTheme(_:)` modifier.
        </Note>
      </div>

      <div>
        <div>
          <iframe title="BalanceElement running on an iPhone simulator" />
        </div>
      </div>
    </div>
  </Tab>
</Tabs>

## Elements

The elements this sub-controller mounts. Each has its own page:

<CardGroup>
  <Card title="BalanceElement" href="/elements/upcoming/wallet/balances-balance">
    An account's balance and a chart of how it changed. The total and its change sit at the top, the chart below that, and the time range buttons at the bottom. The viewer can read individual points on the chart and switch the time range themselves.
  </Card>

  <Card title="ListElement" href="/elements/upcoming/wallet/balances-list">
    The holdings behind an account's balance. Every currency and token gets its own row, showing its name and its value in dollars, largest first. Rows can report which one the viewer tapped, so you can open your own screen for it.
  </Card>
</CardGroup>


# BalanceElement
Source: https://docs.whop.com/elements/upcoming/wallet/balances-balance

An account's balance and a chart of how it changed. The total and its change sit at the top, the chart below that, and the time range buttons at the bottom. The viewer can read individual points on the chart and switch the time range themselves.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

<Tabs>
  <Tab title="Web">
    Belongs to the [`Balances`](/elements/upcoming/wallet/balances) sub-controller in the [`Wallet`](/elements/upcoming/wallet/overview) group. Render `<BalanceElement />` inside `<Balances>` (React), or mint the sub and mount off it (vanilla): `wallet.create('balances', { … }).create('balance', { … })`. Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

    ## Preview

    A live, interactive demo of this element with sample data:

    <div>
      <div />

      <div />
    </div>

    ## Usage

    <div>
      <CodeGroup>
        ```tsx React theme={null}
        import { WhopElements, Wallet, Balances, BalanceElement } from "@whop/elements-react";
        import { loadWhop } from "@whop/elements";

        function Example() {
          return (
            <WhopElements elements={loadWhop()}>
              <Wallet /* options */>
                <Balances>
                  <BalanceElement onRangeChanged={(payload) => console.log("rangeChanged", payload)} onRangeBrushed={(payload) => console.log("rangeBrushed", payload)} />
                </Balances>
              </Wallet>
            </WhopElements>
          );
        }
        ```

        ```html Vanilla theme={null}
        <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
        <script type="module">
          const wallet = window.WhopElements().wallet.create({ /* options */ });
          const balances = wallet.create('balances', { /* options */ });
          balances.create('balance', {
            onRangeChanged: (payload) => console.log("rangeChanged", payload),
            onRangeBrushed: (payload) => console.log("rangeBrushed", payload)
          }).mount('#wallet-balances-balance');
        </script>
        ```
      </CodeGroup>
    </div>

    ## Props

    <ResponseField name="accessToken" type="string">
      A scoped token for the reads. An account needs `company:balance:read` for the total and `stats:read` for the chart; a user's own balance needs `user:balance:read`. Mint it on your server with `POST /v1/access_tokens`, and set a fresh one before it expires. Without it the reads use the viewer's own session, which only works same-origin. Defaults to `""`.
    </ResponseField>

    <ResponseField name="range" type="&#x22;1D&#x22; | &#x22;1W&#x22; | &#x22;1M&#x22; | &#x22;1Y&#x22; | &#x22;ALL&#x22;">
      The time range to open on. The buttons change it from there, or set this prop again to control it yourself. Defaults to `"1M"`.
    </ResponseField>

    <ResponseField name="openedAt" type="string">
      When the account was opened, as an ISO timestamp. `ALL` starts here instead of at its five-year default, so an account older than that keeps its full history. Defaults to `""`.
    </ResponseField>

    <ResponseField name="accountName" type="string">
      Adds the account name to the label: `Total balance · Acme` normally, and `Acme balance on Jul 9` while the viewer reads a point. Without it the label is just `Total balance`. Defaults to `""`.
    </ResponseField>

    <ResponseField name="brush" type="{ from: string; to: string; } | null">
      The selected range on the chart, as ISO timestamps. Set it to control the selection yourself, or `null` to clear the one the viewer made. Echo back what `rangeBrushed` reports, and clearing a filter elsewhere on your page clears the selection here too. Defaults to `null`.
    </ResponseField>

    <ResponseField name="includeOwnedAccounts" type="boolean">
      For a user, total their own money plus every account they own instead of their own money alone. Ignored for an account, which is a single account already. Defaults to `false`.
    </ResponseField>

    <ResponseField name="hideTotal" type="boolean">
      Hide the total and its change, leaving the chart and the range buttons. Defaults to `false`.
    </ResponseField>

    <ResponseField name="hideChart" type="boolean">
      Hide the chart, leaving the total and the range buttons. Defaults to `false`.
    </ResponseField>

    <ResponseField name="height" type="number">
      How tall the chart is drawn, in pixels. Defaults to `210`.
    </ResponseField>

    ## Events

    Pass a callback in the create options (or React prop) to receive these.

    ### `onRangeChanged`

    The visible time range changed. Mirror it if something else on your page reads the same period.

    **Signature:** `((payload: { range: "1D" | "1W" | "1M" | "1Y" | "ALL"; }) => void)`

    ### `onRangeBrushed`

    The viewer dragged across the chart to select a range, or cleared the selection (`null`). Gives ISO timestamps plus the range they were read in, so you can filter your own views, like an activity list or a table, to the same period.

    **Signature:** `((payload: { from: string; to: string; range: "1D" | "1W" | "1M" | "1Y" | "ALL"; } | null) => void)`

    ### `onLoaderStart`

    Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

    **Signature:** `(() => void)`

    ### `onReady`

    Fired once the element has booted and painted its first complete frame.

    **Signature:** `(() => void)`

    ### `onError`

    Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

    **Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

    ## Methods

    Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

    ### `mount`

    Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

    **Signature:** `(target: string | HTMLElement) => void`

    ### `destroy`

    Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

    **Signature:** `() => void`

    ### `update`

    Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

    **Signature:** `(options: Partial<BalanceElementProps>) => void`

    ## Styling

    Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

    | Class                       | Targets                                    |
    | --------------------------- | ------------------------------------------ |
    | `.whop-Balance`             | The total, its line, and the window picker |
    | `.whop-BalanceBrushSummary` | The measured stretch                       |
    | `.whop-BalanceChart`        | The balance line                           |
    | `.whop-BalanceRanges`       | The window picker                          |
    | `.whop-BalanceTotal`        | The total and its move                     |

    ```ts theme={null}
    const wallet = whop.wallet.create({
      appearance: {
        classes: {
          'whop-Balance': { borderRadius: '8px', fontWeight: '600' },
          'whop-BalanceBrushSummary': { borderRadius: '8px', fontWeight: '600' },
          'whop-BalanceChart': { borderRadius: '8px', fontWeight: '600' },
          'whop-BalanceRanges': { borderRadius: '8px', fontWeight: '600' },
          'whop-BalanceTotal': { borderRadius: '8px', fontWeight: '600' }
        }
      }
    });

    // restyle live at any point, the same shape through update()
    wallet.update({
      appearance: { classes: { 'whop-Balance': { fontWeight: '700' } } }
    });
    ```

    In React, pass the same object as the `appearance` prop on `<Wallet>`; `appearance` also applies globally at `WhopElements({ appearance })`.
  </Tab>

  <Tab title="Swift">
    <div>
      <div>
        `BalanceElement` shows an account's total balance, a chart of how that balance changed, and a row of buttons for picking the time range. It loads its own data and handles its own loading and error states, so the only thing you have to pass in is the account id. The root is a `VStack`, so it sizes to its content and fills the width you give it.

        ### Usage

        ```swift theme={null}
        import SwiftUI
        import WhopElements

        // WhopSDK.configure(tokenProvider:) runs once at app launch. See Getting started.
        struct WalletScreen: View {
            var body: some View {
                BalanceElement(
                    accountId: "biz_xxxx",
                    range: .oneMonth
                )
            }
        }
        ```

        ### Parameters

        <ResponseField name="accountId" type="String">
          The account whose money the view reads, given as a company's `biz_…` tag. A `user_…` tag reads the viewer's own balance and needs viewer authentication (`WhopSDK.configureWithOAuth`), not an account token.
        </ResponseField>

        <ResponseField name="currency" type="String">
          The currency the total and chart are shown in. Defaults to `"usd"`.
        </ResponseField>

        <ResponseField name="range" type="WalletBalanceRange">
          The time range the chart opens on: `.oneDay`, `.oneWeek`, `.oneMonth`, `.oneYear`, `.all`. Defaults to `.oneMonth`, and the viewer can change it with the picker.
        </ResponseField>

        ### States

        Shows a placeholder chart while the data loads. If the comparison period fails, the change is hidden rather than guessed, so any number on screen is one that was actually measured. An account id that can't be resolved shows `Couldn't load this account.` instead of spinning.

        ### Good to know

        * Press and drag across the chart to scrub it. The headline follows the point under your finger, and returns to the total when you let go.
        * Balance history is company-only today, so a `user_…` account renders the total without a chart.
        * Pairs with [`ListElement`](/elements/upcoming/wallet/balances-list#swift), which breaks the same total into individual holdings.

        <Note>
          Authentication is set once for every element, not per element, so `WhopSDK.configure(tokenProvider:)` at app launch is enough. A view mounted before it lands renders a spinner and picks the token up when it arrives. See [Getting started](/elements/upcoming/getting-started) for the token provider. Theme with the `.whopTheme(_:)` modifier.
        </Note>
      </div>

      <div>
        <div>
          <iframe title="BalanceElement running on an iPhone simulator" />
        </div>
      </div>
    </div>
  </Tab>
</Tabs>


# ListElement
Source: https://docs.whop.com/elements/upcoming/wallet/balances-list

The holdings behind an account's balance. Every currency and token gets its own row, showing its name and its value in dollars, largest first. Rows can report which one the viewer tapped, so you can open your own screen for it.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

<Tabs>
  <Tab title="Web">
    Belongs to the [`Balances`](/elements/upcoming/wallet/balances) sub-controller in the [`Wallet`](/elements/upcoming/wallet/overview) group. Render `<ListElement />` inside `<Balances>` (React), or mint the sub and mount off it (vanilla): `wallet.create('balances', { … }).create('list', { … })`. Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

    ## Preview

    A live, interactive demo of this element with sample data:

    <div>
      <div />

      <div />
    </div>

    ## Usage

    <div>
      <CodeGroup>
        ```tsx React theme={null}
        import { WhopElements, Wallet, Balances, ListElement } from "@whop/elements-react";
        import { loadWhop } from "@whop/elements";

        function Example() {
          return (
            <WhopElements elements={loadWhop()}>
              <Wallet /* options */>
                <Balances>
                  <ListElement onBalanceSelected={(payload) => console.log("balanceSelected", payload)} onAccountSelected={(payload) => console.log("accountSelected", payload)} />
                </Balances>
              </Wallet>
            </WhopElements>
          );
        }
        ```

        ```html Vanilla theme={null}
        <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
        <script type="module">
          const wallet = window.WhopElements().wallet.create({ /* options */ });
          const balances = wallet.create('balances', { /* options */ });
          balances.create('list', {
            onBalanceSelected: (payload) => console.log("balanceSelected", payload),
            onAccountSelected: (payload) => console.log("accountSelected", payload)
          }).mount('#wallet-balances-list');
        </script>
        ```
      </CodeGroup>
    </div>

    ## Props

    <ResponseField name="accessToken" type="string">
      A scoped token for the read. An account needs `company:balance:read`; a user's holdings or owned-account list needs `user:balance:read`. Mint it on your server with `POST /v1/access_tokens`. Without it the read uses the viewer's own session, which only works same-origin.
    </ResponseField>

    <ResponseField name="includeOwnedAccounts" type="boolean">
      For a user's `user_…` account, list their personal balance followed by every owned account the backend returns instead of listing the holdings inside their personal account. Ignored for an account. Defaults to `false`.
    </ResponseField>

    <ResponseField name="showSourceCurrency" type="boolean">
      Show each row in the currency it is held in (€4.20, 0.00000009 cbBTC) and put the dollar value underneath. Off by default, so every row is in dollars. Defaults to `false`.
    </ResponseField>

    <ResponseField name="showUsdEquivalent" type="boolean">
      Keep the dollar value under a holding shown in its own currency. Only applies when `showSourceCurrency` is on. Defaults to `true`.
    </ResponseField>

    <ResponseField name="showPersonalAccount" type="boolean">
      Keep the personal row when `includeOwnedAccounts` is on. Turn it off if your app has no personal account to open. Defaults to `true`.
    </ResponseField>

    ## Events

    Pass a callback in the create options (or React prop) to receive these.

    ### `onBalanceSelected`

    A holding row was clicked, with `includeOwnedAccounts` off. `key` is `usd` for the combined dollar row, otherwise the holding symbol (`cbBTC`, `EUR`), and `kind` tells you which of the three it is so you can route without classifying symbols yourself. The element never navigates.

    **Signature:** `((payload: { key: string; kind: "usd" | "cash" | "asset"; }) => void)`

    ### `onAccountSelected`

    An account row was clicked, with `includeOwnedAccounts` on. `accountId` is the personal `user_…` tag or an owned `biz_…` tag, and `kind` lets you route without inspecting it. The element never navigates.

    **Signature:** `((payload: { accountId: string; kind: "personal" | "business"; }) => void)`

    ### `onLoaderStart`

    Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

    **Signature:** `(() => void)`

    ### `onReady`

    Fired once the element has booted and painted its first complete frame.

    **Signature:** `(() => void)`

    ### `onError`

    Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

    **Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

    ## Methods

    Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

    ### `mount`

    Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

    **Signature:** `(target: string | HTMLElement) => void`

    ### `destroy`

    Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

    **Signature:** `() => void`

    ### `update`

    Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

    **Signature:** `(options: Partial<ListElementProps>) => void`

    ## Styling

    Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

    | Class                   | Targets                                             |
    | ----------------------- | --------------------------------------------------- |
    | `.whop-BalanceRow`      | One balance row — its icon, name, value and chevron |
    | `.whop-BalancesSurface` | The balances list — one row per holding or account  |

    ```ts theme={null}
    const wallet = whop.wallet.create({
      appearance: {
        classes: {
          'whop-BalanceRow': { borderRadius: '8px', fontWeight: '600' },
          'whop-BalancesSurface': { borderRadius: '8px', fontWeight: '600' }
        }
      }
    });

    // restyle live at any point, the same shape through update()
    wallet.update({
      appearance: { classes: { 'whop-BalanceRow': { fontWeight: '700' } } }
    });
    ```

    In React, pass the same object as the `appearance` prop on `<Wallet>`; `appearance` also applies globally at `WhopElements({ appearance })`.
  </Tab>

  <Tab title="Swift">
    <div>
      <div>
        `ListElement` shows what an account holds: every currency and token on its own row, valued in dollars, largest first. It loads its own data, so the only thing you have to pass in is the account id. Pass a closure as well and the rows become tappable. The root is a `VStack`, so it sizes to its content and fills the width you give it.

        ### Usage

        ```swift theme={null}
        import SwiftUI
        import WhopElements

        // WhopSDK.configure(tokenProvider:) runs once at app launch. See Getting started.
        struct WalletScreen: View {
            var body: some View {
                ListElement(
                    accountId: "biz_xxxx"
                ) { balance in
                    print(balance.symbol)
                }
            }
        }
        ```

        ### Parameters

        <ResponseField name="accountId" type="String">
          The account whose money the view reads, given as a company's `biz_…` tag. A `user_…` tag reads the viewer's own balance and needs viewer authentication (`WhopSDK.configureWithOAuth`), not an account token.
        </ResponseField>

        <ResponseField name="onBalanceSelected" type="((WalletBalance) -> Void)?">
          Called with the row the viewer tapped. Omit it and the rows render without chevrons, and tapping does nothing.
        </ResponseField>

        ### `WalletBalance`

        What a selection hands back:

        * `id: String`: stable per row
        * `symbol: String`: `USD`, `BTC`, …
        * `displayName: String`: the name shown on the row
        * `amountUsd: Decimal`: the row's value in dollars
        * `isCrypto: Bool`: a crypto holding rather than fiat

        ### States

        Shows two placeholder rows while the balances load. An account id that can't be resolved shows `Couldn't load this account.` If the balance read itself fails, the list renders empty rather than showing an error.

        ### Good to know

        * It doesn't scroll on its own, so put it in a `ScrollView` when it shares a screen with other content.
        * Pairs with [`BalanceElement`](/elements/upcoming/wallet/balances-balance#swift), which shows the same account's total and how it changed.

        <Note>
          Authentication is set once for every element, not per element, so `WhopSDK.configure(tokenProvider:)` at app launch is enough. A view mounted before it lands renders a spinner and picks the token up when it arrives. See [Getting started](/elements/upcoming/getting-started) for the token provider. Theme with the `.whopTheme(_:)` modifier.
        </Note>
      </div>

      <div>
        <div>
          <iframe title="ListElement running on an iPhone simulator" />
        </div>
      </div>
    </div>
  </Tab>
</Tabs>


# CardsElement
Source: https://docs.whop.com/elements/upcoming/wallet/cards

Lists the account's active issued cards, most recently issued first. Needs an `accessToken`. The title and rows are click targets that emit events instead of navigating — a host wires up its own routing and card-detail UI.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Wallet`](/elements/upcoming/wallet/overview) group. Render `<CardsElement />` inside it (React), or call `wallet.create('cards', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Wallet, CardsElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Wallet /* options */>
            <CardsElement onCardSelected={(payload) => console.log("cardSelected", payload)} onViewAllSelected={(payload) => console.log("viewAllSelected", payload)} onAddCardRequested={(payload) => console.log("addCardRequested", payload)} />
          </Wallet>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const wallet = window.WhopElements().wallet.create({ /* options */ });
      wallet.create('cards', {
        onCardSelected: (payload) => console.log("cardSelected", payload),
        onViewAllSelected: (payload) => console.log("viewAllSelected", payload),
        onAddCardRequested: (payload) => console.log("addCardRequested", payload)
      }).mount('#wallet-cards');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="accessToken" type="string">
  A scoped token for the privileged read — needs `payout:account:read`. Mint it on your server with `POST /v1/access_tokens`. Omitted, the read carries the viewer's own session, which only answers same-origin.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Off, the element fetches nothing and keeps the title and "+" button visible with an empty body — for a host that only wants to fetch once some precondition (card issuing being active for this account, say) is true. Defaults to `true`.
</ResponseField>

<ResponseField name="limit" type="number | null">
  Cap the rows shown, most recently issued first. `null` shows every active card. Defaults to `null`.
</ResponseField>

<ResponseField name="disableRedirect" type="boolean">
  Render the title as plain, unclickable text instead of a click target. Off by default, in which case clicking the title emits `viewAllSelected` for you to route to the full cards list — the element never navigates. Defaults to `false`.
</ResponseField>

<ResponseField name="hideAddButton" type="boolean">
  Hide the "+" button. Off by default, in which case clicking it emits `addCardRequested`. Defaults to `false`.
</ResponseField>

### Direct mode only

*These props exist only on the in-process (direct-mode) component. The hosted embed never carries them, and the element renders without them.*

<ResponseField name="emptyState" type="direct mode only">
  Direct-mode only. Optional empty-state override for first-party hosts. Omitted in embeds — the built-in empty copy renders instead.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onCardSelected`

A card row was clicked. Open your own card details for it — the element never navigates.

**Signature:** `((payload: { cardId: string; }) => void)`

### `onViewAllSelected`

The title was clicked. Only fires when `disableRedirect` is false.

**Signature:** `((payload: Record<string, never>) => void)`

### `onAddCardRequested`

The "+" button was clicked. Only fires when `hideAddButton` is false.

**Signature:** `((payload: Record<string, never>) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `refresh`

Re-fetch the account's cards. Call it after a mutation made elsewhere (rename, freeze, cancel, a new card) so the list reflects it without waiting for the cache to expire.

**Signature:** `() => Promise<void>`

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<CardsElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                | Targets                                                           |
| -------------------- | ----------------------------------------------------------------- |
| `.whop-CardRow`      | One issued card — its icon, nickname, and last4                   |
| `.whop-CardsSurface` | The issued-cards list — title, add button, and up to 'limit' rows |

```ts theme={null}
const wallet = whop.wallet.create({
  appearance: {
    classes: {
      'whop-CardRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-CardsSurface': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
wallet.update({
  appearance: { classes: { 'whop-CardRow': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Wallet>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# DepositElement
Source: https://docs.whop.com/elements/upcoming/wallet/deposit

Funds a Whop account. Renders an amount field and the account's live funding rails — crypto (a per-network deposit address with its QR) and bank transfer (the wire fields for each settlement currency) — resolved from the account id with no credentials, so it works on any page. Cards and platform balance are opt-in: pass `savedCards`, `allowNewCard`, or `showPlatformBalance` and the element collects the amount and the choice, then emits `cardDepositRequested` / `addCardRequested` / `platformBalanceSelected` and waits for you to call `showStep({ step: 'amount' })` when your own screen is done.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Wallet`](/elements/upcoming/wallet/overview) group. Render `<DepositElement />` inside it (React), or call `wallet.create('deposit', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

<Note>This element can be mounted **inline** (`create`) or opened as a **modal** overlay (`createOverlay`).</Note>

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Wallet, DepositElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Wallet /* options */>
            <DepositElement onDepositInitiated={(payload) => console.log("depositInitiated", payload)} onCardDepositRequested={(payload) => console.log("cardDepositRequested", payload)} onAddCardRequested={(payload) => console.log("addCardRequested", payload)} onBankSelected={(payload) => console.log("bankSelected", payload)} onPlatformBalanceSelected={(payload) => console.log("platformBalanceSelected", payload)} onDepositConfirmed={(payload) => console.log("depositConfirmed", payload)} onStepChanged={(payload) => console.log("stepChanged", payload)} onDismissed={(payload) => console.log("dismissed", payload)} />
          </Wallet>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const wallet = window.WhopElements().wallet.create({ /* options */ });
      wallet.create('deposit', {
        onDepositInitiated: (payload) => console.log("depositInitiated", payload),
        onCardDepositRequested: (payload) => console.log("cardDepositRequested", payload),
        onAddCardRequested: (payload) => console.log("addCardRequested", payload),
        onBankSelected: (payload) => console.log("bankSelected", payload),
        onPlatformBalanceSelected: (payload) => console.log("platformBalanceSelected", payload),
        onDepositConfirmed: (payload) => console.log("depositConfirmed", payload),
        onStepChanged: (payload) => console.log("stepChanged", payload),
        onDismissed: (payload) => console.log("dismissed", payload)
      }).mount('#wallet-deposit');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="amount" type="string">
  Prefill the amount and make it read-only — for flows that already know what is owed. An amount at or below zero, or above 9,999,999, is ignored. Defaults to `""`.
</ResponseField>

<ResponseField name="showCrypto" type="boolean">
  Offer the crypto rail when the account has a deposit address. Defaults to `true`.
</ResponseField>

<ResponseField name="showBank" type="boolean">
  Offer the bank-transfer rail when the account has wire instructions. Defaults to `true`.
</ResponseField>

<ResponseField name="savedCards" type="DepositSavedCard[]">
  Cards you already hold for this payer, rendered as funding rows. Choosing one emits `cardDepositRequested` with the amount — the element never charges a card. Defaults to `[]`.
</ResponseField>

<ResponseField name="allowNewCard" type="boolean">
  Add an "Add card" row that emits `addCardRequested` so you can open your own card-collection flow. Defaults to `false`.
</ResponseField>

<ResponseField name="showPlatformBalance" type="boolean">
  Offer a "Platform balance" row that emits `platformBalanceSelected` immediately, with no amount step. Defaults to `false`.
</ResponseField>

<ResponseField name="cardFee" type="DepositCardFee | null">
  Processing fees to preview under the amount when a card row is selected. `percentageFee` is in percentage POINTS (`2.9` is 2.9%); `fixedFee` and `radarFee` are major units (`0.3` is \$0.30). Defaults to `null`.
</ResponseField>

<ResponseField name="preferredMethodId" type="string">
  Preselect a rail by id (`bank`, `crypto`, `platform_balance`, or a saved card id). Continue stays disabled while that rail is not yet offered, rather than funding through another one. Defaults to `""`.
</ResponseField>

<ResponseField name="deferBankToHost" type="boolean">
  Emit `bankSelected` and stay on the amount screen instead of showing the wire fields — for hosts that run their own step (a verification, an onboarding) first. Because that host owns the rail, the row is then offered even before the account has instructions to show. Defaults to `false`.
</ResponseField>

<ResponseField name="confirmCryptoDeposit" type="boolean">
  Show an "I have deposited my funds" button on the crypto screen that emits `depositConfirmed`, so you can start watching for the transfer. Defaults to `false`.
</ResponseField>

<ResponseField name="initialStep" type="&#x22;amount&#x22; | &#x22;bank&#x22; | &#x22;crypto&#x22;">
  Open straight onto a rail instead of the picker. `crypto` and `bank` need no amount; their back button emits `dismissed` because there is no picker behind them. Defaults to `"amount"`.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onDepositInitiated`

The payer confirmed an amount and a rail. Fires for every rail, before any instructions render — the analytics/funnel hook.

**Signature:** `((payload: { method: "card" | "bank" | "crypto" | "platform_balance"; amount: number; currency: string; paymentMethodId?: string | undefined; }) => void)`

### `onCardDepositRequested`

A saved card was chosen. Charge it on your side, then call `showStep({ step: "amount" })` to return the element to the picker.

**Signature:** `((payload: { amount: number; currency: string; paymentMethodId: string; }) => void)`

### `onAddCardRequested`

The "Add card" row was picked — open your card-collection flow.

**Signature:** `((payload: Record<string, never>) => void)`

### `onBankSelected`

The bank rail was chosen while `deferBankToHost` is set — run your step, then show the fields yourself or call `showStep({ step: "bank" })`.

**Signature:** `((payload: Record<string, never>) => void)`

### `onPlatformBalanceSelected`

The platform-balance row was picked. It carries no amount — your own screen collects that.

**Signature:** `((payload: Record<string, never>) => void)`

### `onDepositConfirmed`

The payer said they sent the crypto. `since` is a unix-seconds floor to start matching incoming transfers from (it looks slightly back in time, so a transfer sent moments before the click still matches).

**Signature:** `((payload: { network: string; token: string; networkLabel: string; since: number; }) => void)`

### `onStepChanged`

The visible screen changed.

**Signature:** `((payload: { step: "amount" | "bank" | "crypto"; }) => void)`

### `onDismissed`

The payer backed out of a rail the element was opened directly onto — close the surface holding it.

**Signature:** `((payload: Record<string, never>) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `showStep`

Move the element to a screen. `{ step: "amount" }` is how you hand control back after settling a card or platform-balance deposit on your side.

**Signature:** `(input: { step: "amount" | "bank" | "crypto"; }) => Promise<void>`

### `refresh`

Re-resolve the account's funding rails. Call it after anything on your side changes what the account can offer — finishing bank onboarding, for instance — so the new rail appears without waiting for the cache to expire.

**Signature:** `() => Promise<void>`

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<DepositElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                  | Targets                                         |
| ---------------------- | ----------------------------------------------- |
| `.whop-DepositSurface` | The deposit element root — one screen at a time |

```ts theme={null}
const wallet = whop.wallet.create({
  appearance: {
    classes: {
      'whop-DepositSurface': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
wallet.update({
  appearance: {
    classes: { 'whop-DepositSurface': { fontWeight: '700' } }
  }
});
```

In React, pass the same object as the `appearance` prop on `<Wallet>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# Wallet
Source: https://docs.whop.com/elements/upcoming/wallet/overview

Drives an account's money surfaces. `deposit` returns live funding rails; `send` moves money to a recipient or creates a public claim link; `withdraw` collects a payout request; `balances` holds two faces — the holdings list, and the balance block drawing value over a window; `cards` lists issued cards; and `activity` lists ledger movements. Every surface but `deposit` can use the viewer's session when no token is provided.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

## Playground

Assemble the elements with sample data. Drive the controls, add and arrange elements, and watch events fire live:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Wallet } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Wallet /* options */>
            {/* mount elements here */}
          </Wallet>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const wallet = window.WhopElements().wallet.create({ /* options */ });
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `whop.wallet.create({ … })`, or as props on `<Wallet>` in React.

<ResponseField name="currency" type="string">
  ISO currency the amount field displays in. An unknown code falls back to USD. Defaults to `"usd"`.
</ResponseField>

<ResponseField name="accountId" type="string">
  Whose money these surfaces read: an account's `biz_…` tag, or a user's own `user_…` tag — a user reads their own balance, so their tag only answers for the viewer themselves.
</ResponseField>

<ResponseField name="appearance" type="Appearance">
  Visual customization for this group's elements. Overrides the global `WhopElements({ appearance })`; change it live with `update({ appearance })`.
</ResponseField>

<ResponseField name="locale" type="WhopElementsLocale">
  Locale for this group's element UI text. One of the app's built locales, overriding the global config; any other value falls back to the default locale.
</ResponseField>

## Events

Pass a callback in the create options / React props.

### `onLoadingChange`

Fired when the grouped loading state changes. `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the Wallet handle, which is the return of `whop.wallet.create({ … })` (vanilla) or `useWallet()` (React).

### `update`

Update the handle live: any of its options (`appearance` and `locale` included), propagated to every mounted element. React consumers never call it; updating the namespace component's props does the same.

**Signature:** `(options: Partial<WalletOptions>) => void`

## Returned objects

Live objects returned by the methods above. Hold the reference and call it on your page; these are capabilities, not serializable data.

## `ActivityDateRangeOverride`

The public surface of `ActivityDateRangeOverride`.

### `start`

**Signature:** `string`

### `end`

**Signature:** `string`

### `includeTime`

**Signature:** `boolean | undefined`

### `postedAfter`

**Signature:** `string | undefined`

### `postedBefore`

**Signature:** `string | undefined`

### `displayPostedAfter`

**Signature:** `string | undefined`

### `displayPostedBefore`

**Signature:** `string | undefined`

## `LedgerActivity`

The public surface of `LedgerActivity`.

### `object`

**Signature:** `"ledger_activity"`

### `id`

Ledger activity ID.

**Signature:** `string`

### `line_type`

The ledger line category this activity was posted under.

**Signature:** `"ad_budget_release" | "ad_campaign_budget" | "ad_publisher_payout" | "ad_publisher_payout_received" | "ad_spend_charge" | "affiliate_fee" | "airdrop" | "airdrop_link_created" | "airdrop_link_redeemed" | "airdrop_link_returned" | "airdrop_reversal" | "application_fee" | "application_fee_payout" | "bank_transfer" | "billing_percentage_fee" | "buyer_fee" | "card_spend_authorization" | "card_spend_authorization_void" | "card_spend_refund" | "company_referral" | "cross_border_percentage_fee" | "currency_conversion_incoming" | "currency_conversion_outgoing" | "dispute_alert_fee" | "dispute_hold_adjustment" | "fraud_prevention_fee" | "fx_percentage_fee" | "high_risk_merchant_fee" | "installment_default" | "internal_balance_transfer_incoming" | "internal_balance_transfer_outgoing" | "legacy_crypto_payment" | "legacy_payment" | "legacy_payment_refund" | "license_sale" | "license_sale_commission" | "license_sale_revenue" | "misc_purchase" | "misc_refund" | "misc_reversal" | "onchain_deposit" | "onchain_swap_target" | "onchain_wallet_transfer_incoming" | "onchain_wallet_transfer_outgoing" | "orchestration_percentage_fee" | "passthrough_gmv" | "payment_dispute" | "payment_dispute_adjustment" | "payment_dispute_fee" | "payment_dispute_reversal" | "payment_gross" | "payment_gross_reversal" | "payment_processing_fixed_fee" | "payment_processing_percentage_fee" | "payment_referral" | "payment_referral_reversal" | "payment_refund" | "payment_refund_reversal" | "payment_revshare" | "payment_revshare_payout" | "payment_revshare_refund" | "payment_revshare_reversal" | "payout_fee" | "platform_affiliate_payment" | "platform_affiliate_payment_reversal" | "platform_balance_payment" | "platform_balance_payment_refund" | "platform_balance_transfer_incoming" | "platform_balance_transfer_outgoing" | "platform_covered_dispute" | "promo_reversal" | "referral_bonus" | "resolution_center_refund" | "revshare_percentage_fee" | "sales_tax_fee" | "sales_tax_remittance" | "sales_tax_remittance_reversal" | "software_rental_revshare" | "software_rental_transaction" | "stripe_domestic_processing_fee" | "stripe_international_processing_fee" | "three_ds_fixed_fee" | "topup" | "topup_fee" | "topup_reversal" | "treasury_payin" | "whop_processing_fee" | "withdrawal" | "withdrawal_clawback" | "withdrawal_clawback_reversal" | "withdrawal_reclassification" | "withdrawal_reversal"`

### `amount`

Signed amount in the currency's smallest precision units.

**Signature:** `string`

### `currency`

Currency for this ledger activity.

**Signature:** `{ code: string; precision: string; }`

### `posted_at`

When the activity posted to the ledger.

**Signature:** `string`

### `available_at`

ISO 8601 timestamp these funds became (or are scheduled to become) withdrawable: the posted time for already-settled funds, or 00:00:00 UTC on the scheduled release date for pending funds. Present only on inflows entering the balance (payments, top-ups, incoming transfers/affiliate); null on withdrawals, refunds, disputes and on-chain rows. The available\_after/before filters window on its UTC settlement date.

**Signature:** `string | null`

### `created_at`

When the activity record was created.

**Signature:** `string | null`

### `resource`

Resource associated with this ledger activity.

**Signature:** `{ object: "account"; id: string; title: string | null; route: string | null; logo_url: string | null; } | { object: "user"; id: string; name: string | null; username: string | null; profile_picture_url: string | null; } | { object: "bounty"; id: string; title: string; status: string; } | { object: "ledger_account"; id: string; owner: { object: "account"; id: string; title: string | null; route: string | null; logo_url: string | null; } | { object: "user"; id: string; name: string | null; username: string | null; profile_picture_url: string | null; } | null; } | { object: "payment_method"; id: string; payment_method_type: string | null; gateway_type: string | null; card: { brand: string | null; last4: string | null; exp_month: number | null; exp_year: number | null; } | null; bank: { bank_name: string | null; account_name: string | null; last4: string | null; account_type: string | null; } | null; email_identifier: string | null; } | { object: "payout_method"; id: string; nickname: string | null; institution_name: string | null; account_reference: string | null; provider: string | null; destination_currency_code: string | null; } | { object: "card_transaction"; id: string; card_id: string | null; merchant_name: string | null; merchant_icon_url: string | null; merchant_category: string | null; status: string | null; usd_amount: string | null; local_amount: string | null; local_currency: string | null; cashback_usd: string | null; authorized_at: string | null; posted_at: string | null; declined_reason: string | null; } | null`

### `source`

Source of this ledger activity.

**Signature:** `{ object: string; id: string; status?: string | null | undefined; reason?: string | null | undefined; claim_url?: string | null | undefined; amount_float?: number | null | undefined; created_at?: string | null | undefined; estimated_arrival?: string | null | undefined; payer_name?: string | null | undefined; payout_token_nickname?: string | null | undefined; tx_hash?: string | null | undefined; sender_address?: string | null | undefined; chain?: string | null | undefined; from_amount?: string | null | undefined; from_currency?: string | null | undefined; to_amount?: string | null | undefined; to_currency?: string | null | undefined; payout_destination?: { payer_name?: string | null | undefined; icon_url?: string | null | undefined; } | null | undefined; [key: string]: unknown; } | null`

### `account`

The viewer account that owns this row's ledger. Present only when the response aggregates owned accounts (include\_owned\_accounts=true); omitted otherwise.

**Signature:** `{ object: "account"; id: string; title: string | null; route: string | null; logo_url: string | null; } | { object: "user"; id: string; name: string | null; username: string | null; profile_picture_url: string | null; } | undefined`

### `ledger_account_id`

The ledger account (a ldgr\_ identifier) this row belongs to. Present only when the response aggregates owned accounts (include\_owned\_accounts=true); omitted otherwise. Pair it with `account` to scope drawers and dashboard links to the owning business.

**Signature:** `string | null | undefined`

## `DepositSavedCard`

A card the consumer already holds for this account — the element renders it as a funding row and hands the choice back through `cardDepositRequested`; it never charges a card itself.

### `id`

Payment-method id echoed back in `cardDepositRequested`.

**Signature:** `string`

### `label`

Row label, e.g. `Visa •••• 4242`.

**Signature:** `string`

### `cardBrand`

Brand key used to pick the row icon — `visa`, `mastercard`, `amex`, `discover`, `jcb`.

**Signature:** `string | null | undefined`

## `DepositCardFee`

The public surface of `DepositCardFee`.

### `percentageFee`

Percentage POINTS, not a fraction: `2.9` means 2.9%.

**Signature:** `number`

### `fixedFee`

Flat fee in major units: `0.3` means \$0.30.

**Signature:** `number`

### `radarFee`

Fraud-screening fee in major units.

**Signature:** `number`

## `WithdrawalQuoteSpeed`

The public surface of `WithdrawalQuoteSpeed`.

### `estimatedArrival`

**Signature:** `string | null | undefined`

### `fee`

**Signature:** `number`

### `totalReceived`

**Signature:** `number`

### `currency`

**Signature:** `string | undefined`

### `destinationCurrency`

**Signature:** `string | undefined`

### `exchangeRate`

**Signature:** `number | undefined`

### `minLimit`

**Signature:** `number | undefined`

### `maxLimit`

**Signature:** `number | null | undefined`

## `WithdrawalQuote`

The public surface of `WithdrawalQuote`.

### `amount`

**Signature:** `number`

### `currency`

**Signature:** `string`

### `destinationCurrency`

**Signature:** `string`

### `exchangeRate`

**Signature:** `number`

### `minLimit`

**Signature:** `number`

### `maxLimit`

**Signature:** `number | null | undefined`

### `standard`

**Signature:** `WithdrawalQuoteSpeed | null | undefined`

### `instant`

**Signature:** `WithdrawalQuoteSpeed | null | undefined`

## `WithdrawalMethod`

The public surface of `WithdrawalMethod`.

### `id`

**Signature:** `string`

### `nickname`

**Signature:** `string | null | undefined`

### `accountReference`

**Signature:** `string | null | undefined`

### `payerName`

**Signature:** `string | null | undefined`

### `destinationCurrency`

**Signature:** `string`

### `isDefault`

**Signature:** `boolean`

### `iconUrl`

**Signature:** `string | null | undefined`

### `deliveryType`

**Signature:** `string`

### `supportsStandard`

**Signature:** `boolean`

### `supportsInstant`

**Signature:** `boolean`

### `bankVerificationState`

**Signature:** `string | null | undefined`

### `unavailableReason`

**Signature:** `string | null | undefined`

### `feeStructure`

**Signature:** `{ percentage: number; fixedAmount: number; currency: string; } | null | undefined`

### `standardEstimatedArrival`

**Signature:** `string | null | undefined`

### `instantEstimatedArrival`

**Signature:** `string | null | undefined`

### `quote`

**Signature:** `WithdrawalQuote | null | undefined`

## `WithdrawalRequiredField`

The public surface of `WithdrawalRequiredField`.

### `id`

**Signature:** `string`

### `label`

**Signature:** `string`

### `inputType`

**Signature:** `string`

### `required`

**Signature:** `boolean`

### `sensitive`

**Signature:** `boolean`

### `placeholder`

**Signature:** `string | null | undefined`

### `validation`

**Signature:** `string | null | undefined`

### `options`

**Signature:** `string[] | null | undefined`

## `WithdrawalSupportedMethod`

The public surface of `WithdrawalSupportedMethod`.

### `id`

**Signature:** `string`

### `name`

**Signature:** `string | null | undefined`

### `iconUrl`

**Signature:** `string | null | undefined`

### `deliveryType`

**Signature:** `string`

### `supportsStandard`

**Signature:** `boolean`

### `supportsInstant`

**Signature:** `boolean`

### `supportsPlaid`

**Signature:** `boolean | undefined`

### `quotes`

**Signature:** `WithdrawalQuote[]`

### `requiredFields`

**Signature:** `WithdrawalRequiredField[]`

## `WithdrawalLimits`

The public surface of `WithdrawalLimits`.

### `standard`

**Signature:** `{ maxAmount: number; errorMessage?: string | null | undefined; }`

### `instant`

**Signature:** `{ maxAmount: number; dailyAmountRemaining?: number | null | undefined; errorMessage?: string | null | undefined; }`

## `WithdrawalCreateMethodInput`

The public surface of `WithdrawalCreateMethodInput`.

### `country`

**Signature:** `string`

### `supportedPayoutMethodId`

**Signature:** `string`

### `destinationCurrency`

**Signature:** `string`

### `nickname`

**Signature:** `string`

### `fields`

**Signature:** `Record<string, string>`

## `WithdrawalRequest`

The public surface of `WithdrawalRequest`.

### `amount`

**Signature:** `number`

### `currency`

**Signature:** `string`

### `payoutMethodId`

**Signature:** `string`

### `presentedFee`

**Signature:** `number`

### `speed`

**Signature:** `"standard" | "instant"`

### `acknowledgeBankWarning`

**Signature:** `boolean | undefined`

## `SendRecipient`

The public surface of `SendRecipient`.

### `id`

**Signature:** `string`

### `name`

**Signature:** `string | null`

### `username`

**Signature:** `string | null`

### `profilePicUrl`

**Signature:** `string | null`

### `kind`

**Signature:** `"business" | "user" | "email"`

## Elements

The elements this group mounts. Each has its own page:

<CardGroup>
  <Card title="Balances" href="/elements/upcoming/wallet/balances">
    Two views of an account's money. The balance view shows the total, a chart of how it changed, and a picker for the time range. The list view shows the holdings that make up that total, valued in dollars. *(sub-controller, 2 elements)*
  </Card>

  <Card title="ActivityElement" href="/elements/upcoming/wallet/activity">
    An account's ledger activity: every movement of money in or out, newest first. The list pages as the viewer scrolls, and rows report which one was tapped instead of navigating, so you can open your own detail screen.
  </Card>

  <Card title="DepositElement" href="/elements/upcoming/wallet/deposit">
    Funds a Whop account. Renders an amount field and the account's live funding rails — crypto (a per-network deposit address with its QR) and bank transfer (the wire fields for each settlement currency) — resolved from the account id with no credentials, so it works on any page. Cards and platform balance are opt-in: pass `savedCards`, `allowNewCard`, or `showPlatformBalance` and the element collects the amount and the choice, then emits `cardDepositRequested` / `addCardRequested` / `platformBalanceSelected` and waits for you to call `showStep({ step: 'amount' })` when your own screen is done.
  </Card>

  <Card title="WithdrawElement" href="/elements/upcoming/wallet/withdraw">
    Collects a withdrawal amount and saved payout method, groups standard and instant delivery choices with live fees and arrival estimates, collects a new payout method when needed, and presents a confirmation screen before emitting the final withdrawal request.
  </Card>

  <Card title="SendElement" href="/elements/upcoming/wallet/send">
    Sends money from an account to a recipient — a user, another business, or a public claim link anyone can redeem. Renders its own recipient search resolved from the account id with no credentials beyond the account's own token. Needs an `accessToken` scoped to `payout:withdraw_funds`; business recipient search additionally needs `company:authorized_user:read` and `member:basic:read`, and business claim links need `airdrop_link:manage` — a host without one of those scopes should turn off the matching prop rather than leave a row that will 403.
  </Card>

  <Card title="CardsElement" href="/elements/upcoming/wallet/cards">
    Lists the account's active issued cards, most recently issued first. Needs an `accessToken`. The title and rows are click targets that emit events instead of navigating — a host wires up its own routing and card-detail UI.
  </Card>
</CardGroup>


# SendElement
Source: https://docs.whop.com/elements/upcoming/wallet/send

Sends money from an account to a recipient — a user, another business, or a public claim link anyone can redeem. Renders its own recipient search resolved from the account id with no credentials beyond the account's own token. Needs an `accessToken` scoped to `payout:withdraw_funds`; business recipient search additionally needs `company:authorized_user:read` and `member:basic:read`, and business claim links need `airdrop_link:manage` — a host without one of those scopes should turn off the matching prop rather than leave a row that will 403.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Wallet`](/elements/upcoming/wallet/overview) group. Render `<SendElement />` inside it (React), or call `wallet.create('send', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

<Note>This element can be mounted **inline** (`create`) or opened as a **modal** overlay (`createOverlay`).</Note>

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Wallet, SendElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Wallet /* options */>
            <SendElement onStepChanged={(payload) => console.log("stepChanged", payload)} onSendCompleted={(payload) => console.log("sendCompleted", payload)} onLinkCreated={(payload) => console.log("linkCreated", payload)} onDone={(payload) => console.log("done", payload)} />
          </Wallet>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const wallet = window.WhopElements().wallet.create({ /* options */ });
      wallet.create('send', {
        onStepChanged: (payload) => console.log("stepChanged", payload),
        onSendCompleted: (payload) => console.log("sendCompleted", payload),
        onLinkCreated: (payload) => console.log("linkCreated", payload),
        onDone: (payload) => console.log("done", payload)
      }).mount('#wallet-send');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="accessToken" type="string">
  A scoped token for the privileged read/write — needs `payout:withdraw_funds` (plus `company:authorized_user:read` and `member:basic:read` for recipient search, `airdrop_link:manage` for claim links). Omitted, the read carries the viewer's own session, which only answers same-origin.
</ResponseField>

<ResponseField name="canSearchRecipients" type="boolean">
  Off, only the team/other-business list shows — no search box. For a host that knows the viewer lacks `member:basic:read`. Defaults to `true`.
</ResponseField>

<ResponseField name="canCreateLink" type="boolean">
  Off, the "Send via link" row is hidden. For a host that knows the viewer lacks `airdrop_link:manage`. Defaults to `true`.
</ResponseField>

<ResponseField name="initialRecipient" type="SendRecipient | null">
  Skip the picker and open straight onto this recipient's amount screen — for a "pay this person" action row. No back button is shown in that case, matching there being no picker behind it. Defaults to `null`.
</ResponseField>

<ResponseField name="initialCurrency" type="string">
  Preselect a currency in the amount screen's picker. Falls back to `currency`, then USD. Defaults to `""`.
</ResponseField>

### Direct mode only

*These props exist only on the in-process (direct-mode) component. The hosted embed never carries them, and the element renders without them.*

<ResponseField name="elevationHandler" type="direct mode only">
  Called when a transfer needs step-up verification — resolve it once the viewer completes that, and the send retries automatically. Direct-mode only; a host that omits it just sees the transfer fail on a step-up challenge.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onStepChanged`

The visible screen changed.

**Signature:** `((payload: { step: "enter_amount" | "select_recipient" | "create_link" | "link_success" | "success"; }) => void)`

### `onSendCompleted`

A transfer succeeded. Refresh anything on your side reading the account's balance or activity.

**Signature:** `((payload: { recipient: SendRecipient; amount: number; currency: string; }) => void)`

### `onLinkCreated`

A claim link was created. Refresh anything on your side reading the account's balance.

**Signature:** `((payload: { claimUrl: string; amount: number; redeemableCount: number; }) => void)`

### `onDone`

The viewer clicked "Done" on a success screen — close the surface holding it.

**Signature:** `((payload: Record<string, never>) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `refresh`

Re-fetch the account's balances and recipient list. Call it after anything on your side changes what it can offer.

**Signature:** `() => Promise<void>`

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<SendElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class               | Targets                                      |
| ------------------- | -------------------------------------------- |
| `.whop-SendSurface` | The send element root — one screen at a time |

```ts theme={null}
const wallet = whop.wallet.create({
  appearance: {
    classes: {
      'whop-SendSurface': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
wallet.update({
  appearance: { classes: { 'whop-SendSurface': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Wallet>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# WithdrawElement
Source: https://docs.whop.com/elements/upcoming/wallet/withdraw

Collects a withdrawal amount and saved payout method, groups standard and instant delivery choices with live fees and arrival estimates, collects a new payout method when needed, and presents a confirmation screen before emitting the final withdrawal request.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Wallet`](/elements/upcoming/wallet/overview) group. Render `<WithdrawElement />` inside it (React), or call `wallet.create('withdraw', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

<Note>This element can be mounted **inline** (`create`) or opened as a **modal** overlay (`createOverlay`).</Note>

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Wallet, WithdrawElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Wallet /* options */>
            <WithdrawElement onAmountChanged={(payload) => console.log("amountChanged", payload)} onCountryChanged={(payload) => console.log("countryChanged", payload)} onSupportedMethodChanged={(payload) => console.log("supportedMethodChanged", payload)} onAddMethodRequested={(payload) => console.log("addMethodRequested", payload)} onPlaidLinkRequested={(payload) => console.log("plaidLinkRequested", payload)} onMethodVerificationCompleted={(payload) => console.log("methodVerificationCompleted", payload)} onWithdrawalRequested={(payload) => console.log("withdrawalRequested", payload)} />
          </Wallet>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const wallet = window.WhopElements().wallet.create({ /* options */ });
      wallet.create('withdraw', {
        onAmountChanged: (payload) => console.log("amountChanged", payload),
        onCountryChanged: (payload) => console.log("countryChanged", payload),
        onSupportedMethodChanged: (payload) => console.log("supportedMethodChanged", payload),
        onAddMethodRequested: (payload) => console.log("addMethodRequested", payload),
        onPlaidLinkRequested: (payload) => console.log("plaidLinkRequested", payload),
        onMethodVerificationCompleted: (payload) => console.log("methodVerificationCompleted", payload),
        onWithdrawalRequested: (payload) => console.log("withdrawalRequested", payload)
      }).mount('#wallet-withdraw');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="methods" type="WithdrawalMethod[]">
  Saved payout methods with quotes for the current amount. Defaults to `[]`.
</ResponseField>

<ResponseField name="availableBalance" type="number">
  Settled balance available to standard payout methods. Defaults to `0`.
</ResponseField>

<ResponseField name="pendingBalance" type="number">
  Pending balance that may be available to instant payout methods. Defaults to `0`.
</ResponseField>

<ResponseField name="payoutCountry" type="string">
  The payout account's ISO 3166-1 alpha-2 country. Defaults to `"US"`.
</ResponseField>

<ResponseField name="supportedMethods" type="WithdrawalSupportedMethod[]">
  Payout methods available to add in the selected country, including required fields. Defaults to `[]`.
</ResponseField>

<ResponseField name="supportedMethodsLoading" type="boolean">
  Whether supported payout methods are loading for the selected country. Defaults to `false`.
</ResponseField>

<ResponseField name="limits" type="WithdrawalLimits">
  Live standard and instant withdrawal limits. Defaults to `{"standard":{"maxAmount":0},"instant":{"maxAmount":0}}`.
</ResponseField>

<ResponseField name="loading" type="boolean">
  Whether payout methods and limits are loading. Defaults to `false`.
</ResponseField>

<ResponseField name="quoteLoading" type="boolean">
  Whether the current amount is being repriced. Defaults to `false`.
</ResponseField>

<ResponseField name="savingMethod" type="boolean">
  Whether a new payout method is being saved. Defaults to `false`.
</ResponseField>

<ResponseField name="submitting" type="boolean">
  Whether the confirmed withdrawal is being created. Defaults to `false`.
</ResponseField>

<ResponseField name="error" type="string">
  A host-side error to show inside the current screen. Defaults to `""`.
</ResponseField>

<ResponseField name="bankWarning" type="boolean">
  True when the last withdrawal was refused because the bank could not confirm the account holder name. Shows a fix-or-confirm choice; confirming re-emits withdrawalRequested with acknowledgeBankWarning set. Set this back to false when handling each withdrawalRequested — the choice appears on the change to true, so a flag left true hides every later refusal. Defaults to `false`.
</ResponseField>

<ResponseField name="createdMethodId" type="string">
  The most recently created method, selected when it appears in methods. Defaults to `""`.
</ResponseField>

<ResponseField name="plaidUnavailable" type="boolean">
  Set when the payer backed out of Plaid Link or it failed to open. Unlocks manual entry on a rail that otherwise requires linking. Defaults to `false`.
</ResponseField>

<ResponseField name="linkingBank" type="boolean">
  Whether a bank link is in progress — the Plaid session is open, or the linked method is being saved. Defaults to `false`.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onAmountChanged`

The amount changed and should be repriced.

**Signature:** `((payload: { amount: number; }) => void)`

### `onCountryChanged`

The add-method country changed and supported methods should be refreshed.

**Signature:** `((payload: { country: string; }) => void)`

### `onSupportedMethodChanged`

A supported payout method was selected and its exact required fields should be loaded.

**Signature:** `((payload: { country: string; supportedPayoutMethodId: string; destinationCurrency: string; }) => void)`

### `onAddMethodRequested`

The payer submitted the dynamic add-payout-method form.

**Signature:** `((payload: WithdrawalCreateMethodInput) => void)`

### `onPlaidLinkRequested`

The payer chose to link their bank through Plaid instead of typing details. Open Plaid Link on receipt.

**Signature:** `((payload: { country: string; supportedPayoutMethodId: string; destinationCurrency: string; }) => void)`

### `onMethodVerificationCompleted`

The newly added payout method finished its verification step.

**Signature:** `((payload: Record<string, never>) => void)`

### `onWithdrawalRequested`

The payer confirmed the final withdrawal details. Create the withdrawal on receipt.

**Signature:** `((payload: WithdrawalRequest) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<WithdrawElementProps>) => void`

## Styling

This element exposes no targetable class names. Use `appearance` (theme, accent color, variables) to restyle it.


# Websites
Source: https://docs.whop.com/elements/upcoming/websites/overview

An account's websites: every site built on whop.app plus every domain the Whop Pixel reports, with traffic per domain. Mount `websites` and it lists them with visitors, page views, trend, and most-viewed pages. Reading stats is privileged, so it needs an `accessToken` — except inside Whop's own app, where the viewer's session carries the read.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

## Playground

Assemble the elements with sample data. Drive the controls, add and arrange elements, and watch events fire live:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Websites } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Websites /* options */>
            {/* mount elements here */}
          </Websites>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const websites = window.WhopElements().websites.create({ /* options */ });
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `whop.websites.create({ … })`, or as props on `<Websites>` in React.

<ResponseField name="windowDays" type="number">
  How many days of traffic the table covers, from 1 to 90. @default 30 Defaults to `30`.
</ResponseField>

<ResponseField name="includeApps" type="boolean">
  List websites built on whop.app from the moment they exist, with zeros until traffic arrives. Turn off to show only domains the pixel reports. @default true Defaults to `true`.
</ResponseField>

<ResponseField name="pendingWebsites" type="PendingWebsite[]">
  Websites you have just added that are not live yet — `{ domain, kind }`, where `kind` is `deploy` for a whop.app site waiting on its first deploy or `events` for a site waiting on its first pixel events. They render as waiting rows so a site never looks lost right after setup, and the table polls while any is outstanding. Defaults to `[]`.
</ResponseField>

<ResponseField name="showVerify" type="boolean">
  Add a pixel-check button to each row. The element only reports the press through `onVerifyRequested` — opening the site and deciding the outcome is yours, because a popup opened by your own page is the one browsers trust. Defaults to `false`.
</ResponseField>

<ResponseField name="showSettings" type="boolean">
  Add a settings button to whop.app rows. The element only reports the press through `onSettingsRequested` — the editing surface is yours. Defaults to `false`.
</ResponseField>

<ResponseField name="verifyTarget" type="string">
  Which row the check in progress belongs to — the `target` from the `verifyRequested` event you are handling. Defaults to `""`.
</ResponseField>

<ResponseField name="verifyStatus" type="&#x22;idle&#x22; | &#x22;waiting&#x22; | &#x22;connected&#x22; | &#x22;not-detected&#x22; | &#x22;blocked&#x22;">
  How the check in progress is going, shown on that row’s button: `waiting`, `connected`, `not-detected`, or `blocked` when the popup was blocked. Defaults to `"idle"`.
</ResponseField>

<ResponseField name="accessToken" type="string">
  A scoped token for the reads — stats need `stats:read`, and the whop.app website list reads apps (rows degrade to traffic-only if the token can’t). Mint it on your server with `POST /v1/access_tokens` and set a fresh one before it expires. Omitted, the reads carry the viewer’s own session, which only answers same-origin.
</ResponseField>

<ResponseField name="accountId" type="string">
  The company whose websites these surfaces read — `biz_…`.
</ResponseField>

<ResponseField name="appearance" type="Appearance">
  Visual customization for this group's elements. Overrides the global `WhopElements({ appearance })`; change it live with `update({ appearance })`.
</ResponseField>

<ResponseField name="locale" type="WhopElementsLocale">
  Locale for this group's element UI text. One of the app's built locales, overriding the global config; any other value falls back to the default locale.
</ResponseField>

## Events

Pass a callback in the create options / React props.

### `onLoadingChange`

Fired when the grouped loading state changes. `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the Websites handle, which is the return of `whop.websites.create({ … })` (vanilla) or `useWebsites()` (React).

### `update`

Update the handle live: any of its options (`appearance` and `locale` included), propagated to every mounted element. React consumers never call it; updating the namespace component's props does the same.

**Signature:** `(options: Partial<WebsitesOptions>) => void`

## Returned objects

Live objects returned by the methods above. Hold the reference and call it on your page; these are capabilities, not serializable data.

## `PendingWebsite`

The public surface of `PendingWebsite`.

### `domain`

**Signature:** `string`

### `kind`

**Signature:** `"events" | "deploy"`

## Elements

The elements this group mounts. Each has its own page:

<CardGroup>
  <Card title="WebsitesElement" href="/elements/upcoming/websites/websites">
    An account's websites in one table: every site built on whop.app — listed from the moment it exists, zeros until traffic arrives — merged by hostname with every domain the Whop Pixel reports. Rows for the whop.app sites carry a Whop mark, so the two sources stay apart even when both have traffic. Each row shows a page-view trend, unique visitors, page views, and the last day an event arrived. Expanding a domain loads its most-viewed pages, and each page-view figure opens the breakdown of which events made it up. Set `showVerify` to add a per-row button that asks the page hosting this element to open the site and confirm the pixel is firing; set `showSettings` to add a settings button on whop.app rows that reports the click through `onSettingsRequested` — your page owns the actual editing.
  </Card>

  <Card title="PixelSetupElement" href="/elements/upcoming/websites/pixel-setup">
    Installs the Whop Pixel and wires conversion events: copy the snippet, check a page for it, confirm the events fire. Mount it inline, or inside your own overlay.
  </Card>
</CardGroup>


# PixelSetupElement
Source: https://docs.whop.com/elements/upcoming/websites/pixel-setup

Installs the Whop Pixel and wires conversion events: copy the snippet, check a page for it, confirm the events fire. Mount it inline, or inside your own overlay.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Websites`](/elements/upcoming/websites/overview) group. Render `<PixelSetupElement />` inside it (React), or call `websites.create('pixel-setup', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

<Note>This element can be mounted **inline** (`create`) or opened as a **modal** overlay (`createOverlay`).</Note>

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Websites, PixelSetupElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Websites /* options */>
            <PixelSetupElement onRedirectUrlChanged={(payload) => console.log("redirectUrlChanged", payload)} onScanned={(payload) => console.log("scanned", payload)} onFinished={(payload) => console.log("finished", payload)} onEventVerified={(payload) => console.log("eventVerified", payload)} />
          </Websites>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const websites = window.WhopElements().websites.create({ /* options */ });
      websites.create('pixel-setup', {
        onRedirectUrlChanged: (payload) => console.log("redirectUrlChanged", payload),
        onScanned: (payload) => console.log("scanned", payload),
        onFinished: (payload) => console.log("finished", payload),
        onEventVerified: (payload) => console.log("eventVerified", payload)
      }).mount('#websites-pixel-setup');
    </script>
    ```
  </CodeGroup>
</div>

## Props

<ResponseField name="accountId" type="string">
  The company (`biz_…`) whose pixel this is. Required — the snippet, scans and invites all run against it. Defaults to `""`.
</ResponseField>

<ResponseField name="accessToken" type="string">
  A scoped token for the scans and the developer invite. Mint it on your server with `POST /v1/access_tokens` and set a fresh one before it expires. Omitted, the calls carry the viewer’s own session, which only answers same-origin.
</ResponseField>

<ResponseField name="destinationUrl" type="string">
  The page to check, scanned on mount. Leave it blank and the wizard asks for one. Read once at boot, so `update()` will not retarget mid-flow — mint a fresh mount for a different page. Defaults to `""`.
</ResponseField>

<ResponseField name="eventName" type="string">
  Optional. An event that must fire on that page (`lead`, `schedule`, `view_content`, …); the events step blocks until it is detected. Unset, every event is offered and none is required. Events Whop records server-side (`purchase`, `subscribe`, trials, checkout steps) are ignored. Read once at boot. Defaults to `""`.
</ResponseField>

<ResponseField name="redirectUrl" type="string">
  A URL the destination redirects to, when the event fires there instead. The merchant can also set one in the wizard — listen for `redirectUrlChanged` and pass it back next time. Defaults to `""`.
</ResponseField>

<ResponseField name="initialStep" type="&#x22;events&#x22; | &#x22;install&#x22;">
  Where the wizard opens: the install step, or straight onto `events` when the pixel is already there and only the conversion event is missing. Defaults to `"install"`.
</ResponseField>

<ResponseField name="showIntro" type="boolean">
  Open on the "why a pixel" splash. Turn it off where the merchant already knows why they are here — a campaign flow that sends them in mid-launch — and the wizard opens straight on the install step. Defaults to `true`.
</ResponseField>

<ResponseField name="showInviteDeveloper" type="boolean">
  Offer the "Invite a developer to install it" path. Hide it where the people using your embed should not be inviting members onto the Whop team behind it. Defaults to `true`.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onRedirectUrlChanged`

The merchant set or cleared a redirect URL in the wizard. Persist it and pass it back as `redirectUrl` next time.

**Signature:** `((payload: { url: string; }) => void)`

### `onScanned`

A pixel scan settled. Fires for every URL the wizard checks, so your own install badge can follow it. `primary` marks the page being set up: the funnel checker scans whatever else the merchant lists, other hostnames included, so gate on it before you treat a result as being about their site.

**Signature:** `((payload: { url: string; status: "installed" | "missing" | "unreachable"; installed: boolean; primary: boolean; }) => void)`

### `onFinished`

Done was pressed. Re-check the page yourself — this says the wizard finished, not that your requirements are met.

**Signature:** `((payload: Record<string, never>) => void)`

### `onEventVerified`

The merchant walked their funnel with "Verify live" and this event fired — proof it is wired where a server-side scan cannot reach.

**Signature:** `((payload: { url: string; event: string; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<PixelSetupElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                     | Targets                                          |
| ------------------------- | ------------------------------------------------ |
| `.whop-PixelSetupSurface` | The pixel setup wizard root — one step at a time |

```ts theme={null}
const websites = whop.websites.create({
  appearance: {
    classes: {
      'whop-PixelSetupSurface': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
websites.update({
  appearance: {
    classes: { 'whop-PixelSetupSurface': { fontWeight: '700' } }
  }
});
```

In React, pass the same object as the `appearance` prop on `<Websites>`; `appearance` also applies globally at `WhopElements({ appearance })`.


# WebsitesElement
Source: https://docs.whop.com/elements/upcoming/websites/websites

An account's websites in one table: every site built on whop.app — listed from the moment it exists, zeros until traffic arrives — merged by hostname with every domain the Whop Pixel reports. Rows for the whop.app sites carry a Whop mark, so the two sources stay apart even when both have traffic. Each row shows a page-view trend, unique visitors, page views, and the last day an event arrived. Expanding a domain loads its most-viewed pages, and each page-view figure opens the breakdown of which events made it up. Set `showVerify` to add a per-row button that asks the page hosting this element to open the site and confirm the pixel is firing; set `showSettings` to add a settings button on whop.app rows that reports the click through `onSettingsRequested` — your page owns the actual editing.

<Info>**Upcoming.** These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development, not yet part of a stable release.*

Belongs to the [`Websites`](/elements/upcoming/websites/overview) group. Render `<WebsitesElement />` inside it (React), or call `websites.create('websites', { … })` on the handle (vanilla). Consumer props and `on<Event>` callbacks both go in the create options / JSX props.

## Preview

A live, interactive demo of this element with sample data:

<div>
  <div />

  <div />
</div>

## Usage

<div>
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Websites, WebsitesElement } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Websites /* options */>
            <WebsitesElement onWebsiteToggled={(payload) => console.log("websiteToggled", payload)} onWebsitesLoaded={(payload) => console.log("websitesLoaded", payload)} onVerifyRequested={(payload) => console.log("verifyRequested", payload)} onSettingsRequested={(payload) => console.log("settingsRequested", payload)} />
          </Websites>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const websites = window.WhopElements().websites.create({ /* options */ });
      websites.create('websites', {
        onWebsiteToggled: (payload) => console.log("websiteToggled", payload),
        onWebsitesLoaded: (payload) => console.log("websitesLoaded", payload),
        onVerifyRequested: (payload) => console.log("verifyRequested", payload),
        onSettingsRequested: (payload) => console.log("settingsRequested", payload)
      }).mount('#websites-websites');
    </script>
    ```
  </CodeGroup>
</div>

## Props

*This element takes no consumer props.*

### Direct mode only

*These props exist only on the in-process (direct-mode) component. The hosted embed never carries them, and the element renders without them.*

<ResponseField name="emptyState" type="direct mode only">
  Direct-mode only. Optional empty-state override for first-party hosts. Omitted in embeds — the built-in empty copy renders instead.
</ResponseField>

## Events

Pass a callback in the create options (or React prop) to receive these.

### `onWebsiteToggled`

A domain row was expanded or collapsed to show or hide its pages.

**Signature:** `((payload: { domain: string; expanded: boolean; }) => void)`

### `onWebsitesLoaded`

The list of domains arrived or changed — use it to drop any `pendingWebsites` that are now live.

**Signature:** `((payload: { domains: string[]; }) => void)`

### `onVerifyRequested`

The pixel-check button was pressed. Open `url` and watch for pixel events on your side, then push the outcome back through the handle’s `verifyStatus` so the button reflects it.

**Signature:** `((payload: { target: string; url: string; }) => void)`

### `onSettingsRequested`

The settings button on a whop.app row was pressed. The element only reports the click — open your own editing surface for the app.

**Signature:** `((payload: { appId: string; route: string; domain: string; }) => void)`

### `onLoaderStart`

Fired the moment the element's own loading skeleton has painted inside its frame. This is the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes `onReady`; most consumers only need `onReady`.

**Signature:** `(() => void)`

### `onReady`

Fired once the element has booted and painted its first complete frame.

**Signature:** `(() => void)`

### `onError`

Fired when the element fails to load or crashes; the element shows its own error fallback. `message` is human-readable; framework refusals also carry `code` (e.g. `HOST_SOURCE_FAILED`, with `sourceKey` naming the failed hostState key) so hosts can switch on codes, never message text.

**Signature:** `((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)`

## Methods

Call these on the element handle, which is the return of `create` (vanilla) or the component `ref` (React).

### `mount`

Place the element on the page: appends its container to `target` (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it; the component mounts itself.

**Signature:** `(target: string | HTMLElement) => void`

### `destroy`

Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it; unmounting the component does it.

**Signature:** `() => void`

### `update`

Change this element's consumer props after mount, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same.

**Signature:** `(options: Partial<WebsitesElementProps>) => void`

## Styling

Each part below is a stable class name, safe to depend on. Restyle a part by mapping its class to a **style declaration object** under `appearance.classes` (properties camelCase or kebab-case, values as strings with units, the same shape as React's `style` prop). The element renders in its own frame, so page stylesheets can't reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.

| Class                 | Targets                                          |
| --------------------- | ------------------------------------------------ |
| `.whop-WebsitesTable` | The websites element root — the table of domains |

```ts theme={null}
const websites = whop.websites.create({
  appearance: {
    classes: {
      'whop-WebsitesTable': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// restyle live at any point, the same shape through update()
websites.update({
  appearance: { classes: { 'whop-WebsitesTable': { fontWeight: '700' } } }
});
```

In React, pass the same object as the `appearance` prop on `<Websites>`; `appearance` also applies globally at `WhopElements({ appearance })`.