Ads - Whop Docs

This page documents @whop/elements@1.0.0-beta.0 and @whop/elements-react@1.0.0-beta.0.

Pre-release, not yet part of a stable release.

Playground

Assemble the elements with example data. Drive the controls, add and arrange elements, and watch events fire live:

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>
  );
}

<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>

Options

Pass these to whop.ads.create({ … }), or as props on <Ads> in React.

string

Whop account ID, prefixed biz_, whose advertising this reads. Required; this is not an ad account ID. Defaults to "".

string

A scoped token every surface under this handle reads and writes with. Mint one token for the whole handle, not one per element. Work out the scopes of every element you are going to mount, request them on a single token, and set it here — the handle projects that one credential into each element’s frame, so a second token per surface buys nothing and leaves you several expiration dates to track instead of one. Mint it on your server with POST /api/v1/access_tokens and set a fresh one with update({ accessToken }) before it expires. Mounting everything needs ad_campaign:read/:create, ad_group:read, ad:read, stats:read, the :update/:delete scopes the table’s row actions use, company:basic:read for the pixel checks campaign-creator runs, and payment:charge plus user:email:read to add an ad-spend card. Mounting fewer surfaces can ask for fewer scopes — still on the one token. Omitted, the calls carry the viewer’s own session, which only answers same-origin.

CrossLinksConfig

Where the reporting table’s click and result counts link on your site — typically the pages where you mounted the tracking namespace’s people and events elements. people and events are absolute base URLs (https://…); the table appends the same query params those elements take as props (?source=whop:adcamp_…:*&event=…&from=…&to=…), so the target page can hydrate its element straight from its URL. A relative URL would resolve against the element frame, so one is treated as unset; unset links render the counts as plain figures. Defaults to {}.

Appearance

Visual customization for this group’s elements. Overrides the global WhopElements({ appearance }). Change it live with update({ appearance }).

WhopElementsLocale

Locale for this group’s element UI text. Set it to one of the app’s built locales to override the global configuration. Any other value falls back to the default locale.

Events

Pass callbacks in the create options or 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`

Runs when the grouped loading state changes. The value is true while any mounted element is still loading. Signature: ((loading: boolean) => void)

Methods

Call these on the Ads handle from whop.ads.create({ … }) or useAds().

`update`

Merges new handle options into every mounted element. In React, change the namespace props instead. Signature: (options: Partial<AdsOptions>) => void

Types

Named types used throughout this page.

`CrossLinksConfig`

The consumer-facing shape of an element’s links prop. people/events are base URLs the canonical query params are appended to; person is a template whose {personId} and {identifier} placeholders are replaced with the row’s URL-encoded values.