@whop/elements 1.0.0-beta.4 → 1.0.0-beta.6

package/checkout.d.cts

@@ -11,17 +11,21 @@
  */
 export interface CheckoutOptions {
 	/**
-	 * Existing plan ID, prefixed `plan_`. The element creates a checkout session for it, and the plan defines the price; nothing about amounts can be asserted client-side. Every checkout is created from this or a `checkoutConfiguration` — omitting both refuses loudly at mount. Set at create only: the session is minted from it, and changing it later refuses.
+	 * Existing plan ID, prefixed `plan_`. Shorthand for an `items` array containing this plan and `quantity`. The plan defines the price; nothing about amounts can be asserted client-side. Pass either `plan`, `items`, or a `checkoutConfiguration`. Set at create only: the session is minted from it, and changing it later refuses.
 	 */
 	plan?: string;
-	/**
-	 * Existing checkout configuration ID, prefixed `ch_`. The element creates the checkout session from it: the configuration names the plan being sold (or, in `setup` mode, no plan — the checkout saves a payment method and charges nothing) and seeds its own affiliate code, metadata, redirect and payment-method presets — an option passed here beside it wins over the configuration’s copy, field by field. Pass `plan` alongside only to set `quantity`; it must be the configuration’s own plan, which can never be swapped out from under its presets. Set at create only.
-	 */
-	checkoutConfiguration?: string;
 	/**
 	 * 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. @default 1
 	 */
 	quantity?: number;
+	/**
+	 * The plans in this checkout and how many units of each to purchase. Every item must belong to the same seller and use compatible billing terms; the API validates the complete cart and prices it as one charge. Pass this instead of `plan`, `quantity`, or `checkoutConfiguration`. Set at create only: the session is minted from this exact cart, and changing it later refuses.
+	 */
+	items?: CheckoutItemInput[];
+	/**
+	 * Existing checkout configuration ID, prefixed `ch_`. The element creates the checkout session from it: the configuration names the plan being sold (or, in `setup` mode, no plan — the checkout saves a payment method and charges nothing) and seeds its own affiliate code, metadata, redirect and payment-method presets — an option passed here beside it wins over the configuration’s copy, field by field. Pass `plan` alongside only to set `quantity`; it must be the configuration’s own plan, which can never be swapped out from under its presets. Set at create only.
+	 */
+	checkoutConfiguration?: 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.
 	 */
@@ -64,7 +68,18 @@ export interface CheckoutOptions {
  * Consumer props for the "checkout" element. Set at create (or as `<CheckoutElement />` JSX props), and updatable live via `update()`.
  * @see https://docs.whop.com/elements/latest/checkout/checkout
  */
-export interface CheckoutElementProps {}
+export interface CheckoutElementProps {
+	/**
+	 * Prefills the buyer email the host page already knows: the authenticated first-party viewer’s, the one a checkout link carried, or the one a merchant page collected before mounting. A session that already holds its buyer’s email wins over it. Empty (default) leaves the field for the buyer.
+	 * @default ""
+	 */
+	buyerEmail?: string;
+	/**
+	 * Keeps the buyer from editing the prefilled `buyerEmail` — an invoice link names who it was issued to. Only holds while the field still shows that email; a session email that already differs is never locked to it, and without a `buyerEmail` there is nothing to lock.
+	 * @default false
+	 */
+	lockBuyerEmail?: boolean;
+}
 
 /**
  * The live handle for a mounted "checkout" element. Returned by `create("checkout")`; in React, the component's `ref`.
@@ -95,6 +110,16 @@ export interface CheckoutElementHandle {
  * @see https://docs.whop.com/elements/latest/checkout/checkout
  */
 export interface CheckoutElementCreateOptions {
+	/**
+	 * Prefills the buyer email the host page already knows: the authenticated first-party viewer’s, the one a checkout link carried, or the one a merchant page collected before mounting. A session that already holds its buyer’s email wins over it. Empty (default) leaves the field for the buyer.
+	 * @default ""
+	 */
+	buyerEmail?: string;
+	/**
+	 * Keeps the buyer from editing the prefilled `buyerEmail` — an invoice link names who it was issued to. Only holds while the field still shows that email; a session email that already differs is never locked to it, and without a `buyerEmail` there is nothing to lock.
+	 * @default false
+	 */
+	lockBuyerEmail?: boolean;
 	/**
 	 * Runs after the loading skeleton first paints and before `onReady`.
 	 */
@@ -115,7 +140,7 @@ export interface CheckoutElementCreateOptions {
  */
 export interface ExpressCheckoutElementProps {
 	/**
-	 * Which wallets may render — a filter over what the buyer’s device actually offers. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first whatever order this lists. An empty list renders nothing (warned in dev builds). Apple Pay also needs the page’s domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain) — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the Apple Pay button stays hidden.
+	 * Which wallets may render — a filter over what the buyer’s device actually offers. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first whatever order this lists. An empty list renders nothing (warned in dev builds). Both wallets need the page’s domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain) — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the buttons stay hidden. Offering Google Pay on your own site is subject to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos).
 	 * @default ["apple_pay","google_pay"]
 	 */
 	wallets?: ("apple_pay" | "google_pay")[];
@@ -156,7 +181,7 @@ export interface ExpressCheckoutElementHandle {
  */
 export interface ExpressCheckoutElementCreateOptions {
 	/**
-	 * Which wallets may render — a filter over what the buyer’s device actually offers. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first whatever order this lists. An empty list renders nothing (warned in dev builds). Apple Pay also needs the page’s domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain) — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the Apple Pay button stays hidden.
+	 * Which wallets may render — a filter over what the buyer’s device actually offers. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first whatever order this lists. An empty list renders nothing (warned in dev builds). Both wallets need the page’s domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain) — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the buttons stay hidden. Offering Google Pay on your own site is subject to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos).
 	 * @default ["apple_pay","google_pay"]
 	 */
 	wallets?: ("apple_pay" | "google_pay")[];
@@ -190,7 +215,7 @@ export interface CheckoutHandle {
 	 */
 	create(name: "checkout", options?: CheckoutElementCreateOptions): CheckoutElementHandle;
 	/**
-	 * One-press Apple Pay and Google Pay buttons for a checkout — the OS payment sheet collects whatever the session still needs (the buyer's email, a phone number where the seller collects one, a shipping address for physical goods, and in Apple Pay a promo code where the seller offers entry) and one press finishes the purchase. It shares the checkout's entry slot with the full checkout element, so a handle mounts exactly one of the two: this button alone where the purchase is simple enough for a sheet to finish, or the full checkout surface for everything else. Renders only the wallets the buyer's device can actually pay with — and the checkout's own payment method configuration allows — using the served button art, and renders nothing where no wallet is available. Apple Pay additionally requires the page's domain to be a verified payment method domain: first-party whop.com pages are pre-approved, and any other site must register its domain through the Payment Method Domains API before the button renders there. A checkout the sheet cannot honestly finish — a waitlist join, a transfer, a form question only a page can ask — refuses loudly instead of rendering a doomed button.
+	 * One-press Apple Pay and Google Pay buttons for a checkout — the OS payment sheet collects whatever the session still needs (the buyer's email, a phone number where the seller collects one, a shipping address for physical goods, and in Apple Pay a promo code where the seller offers entry) and one press finishes the purchase. It shares the checkout's entry slot with the full checkout element, so a handle mounts exactly one of the two: this button alone where the purchase is simple enough for a sheet to finish, or the full checkout surface for everything else. Renders only the wallets the buyer's device can actually pay with — and the checkout's own payment method configuration allows — using the served button art, and renders nothing where no wallet is available. Both wallets require the page's domain to be a verified payment method domain: first-party whop.com pages are pre-approved, and any other site must register its domain through the Payment Method Domains API before either button renders there. Offering Google Pay on your own site is subject to the Google Pay API Terms of Service. A checkout the sheet cannot honestly finish — a waitlist join, a transfer, a form question only a page can ask — refuses loudly instead of rendering a doomed button.
 	 * Exclusive slot `entry`. Mount exactly one of: checkout | expressCheckout.
 	 */
 	create(name: "expressCheckout", options?: ExpressCheckoutElementCreateOptions): ExpressCheckoutElementHandle;
@@ -210,6 +235,20 @@ export interface CheckoutHandle {
  */
 export interface CheckoutStatics {}
 
+/**
+ * Declared from the app's `CheckoutItemInput`, referenced by a host-capability surface.
+ */
+export interface CheckoutItemInput {
+	/**
+	 * Existing plan ID, prefixed `plan_`.
+	 */
+	plan: string;
+	/**
+	 * Number of units to purchase. Defaults to 1; plans can disallow quantities above 1.
+	 */
+	quantity?: number | undefined;
+}
+
 /**
  * Checkout attribution recorded with the session. The element maps these fields to `POST /api/v1/checkout_sessions`; empty values are omitted, and `country` is resolved by the API.
  * Declared from the app's `CheckoutAttributionInput`, referenced by a host-capability surface.

package/checkout.d.ts

@@ -11,17 +11,21 @@
  */
 export interface CheckoutOptions {
 	/**
-	 * Existing plan ID, prefixed `plan_`. The element creates a checkout session for it, and the plan defines the price; nothing about amounts can be asserted client-side. Every checkout is created from this or a `checkoutConfiguration` — omitting both refuses loudly at mount. Set at create only: the session is minted from it, and changing it later refuses.
+	 * Existing plan ID, prefixed `plan_`. Shorthand for an `items` array containing this plan and `quantity`. The plan defines the price; nothing about amounts can be asserted client-side. Pass either `plan`, `items`, or a `checkoutConfiguration`. Set at create only: the session is minted from it, and changing it later refuses.
 	 */
 	plan?: string;
-	/**
-	 * Existing checkout configuration ID, prefixed `ch_`. The element creates the checkout session from it: the configuration names the plan being sold (or, in `setup` mode, no plan — the checkout saves a payment method and charges nothing) and seeds its own affiliate code, metadata, redirect and payment-method presets — an option passed here beside it wins over the configuration’s copy, field by field. Pass `plan` alongside only to set `quantity`; it must be the configuration’s own plan, which can never be swapped out from under its presets. Set at create only.
-	 */
-	checkoutConfiguration?: string;
 	/**
 	 * 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. @default 1
 	 */
 	quantity?: number;
+	/**
+	 * The plans in this checkout and how many units of each to purchase. Every item must belong to the same seller and use compatible billing terms; the API validates the complete cart and prices it as one charge. Pass this instead of `plan`, `quantity`, or `checkoutConfiguration`. Set at create only: the session is minted from this exact cart, and changing it later refuses.
+	 */
+	items?: CheckoutItemInput[];
+	/**
+	 * Existing checkout configuration ID, prefixed `ch_`. The element creates the checkout session from it: the configuration names the plan being sold (or, in `setup` mode, no plan — the checkout saves a payment method and charges nothing) and seeds its own affiliate code, metadata, redirect and payment-method presets — an option passed here beside it wins over the configuration’s copy, field by field. Pass `plan` alongside only to set `quantity`; it must be the configuration’s own plan, which can never be swapped out from under its presets. Set at create only.
+	 */
+	checkoutConfiguration?: 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.
 	 */
@@ -64,7 +68,18 @@ export interface CheckoutOptions {
  * Consumer props for the "checkout" element. Set at create (or as `<CheckoutElement />` JSX props), and updatable live via `update()`.
  * @see https://docs.whop.com/elements/latest/checkout/checkout
  */
-export interface CheckoutElementProps {}
+export interface CheckoutElementProps {
+	/**
+	 * Prefills the buyer email the host page already knows: the authenticated first-party viewer’s, the one a checkout link carried, or the one a merchant page collected before mounting. A session that already holds its buyer’s email wins over it. Empty (default) leaves the field for the buyer.
+	 * @default ""
+	 */
+	buyerEmail?: string;
+	/**
+	 * Keeps the buyer from editing the prefilled `buyerEmail` — an invoice link names who it was issued to. Only holds while the field still shows that email; a session email that already differs is never locked to it, and without a `buyerEmail` there is nothing to lock.
+	 * @default false
+	 */
+	lockBuyerEmail?: boolean;
+}
 
 /**
  * The live handle for a mounted "checkout" element. Returned by `create("checkout")`; in React, the component's `ref`.
@@ -95,6 +110,16 @@ export interface CheckoutElementHandle {
  * @see https://docs.whop.com/elements/latest/checkout/checkout
  */
 export interface CheckoutElementCreateOptions {
+	/**
+	 * Prefills the buyer email the host page already knows: the authenticated first-party viewer’s, the one a checkout link carried, or the one a merchant page collected before mounting. A session that already holds its buyer’s email wins over it. Empty (default) leaves the field for the buyer.
+	 * @default ""
+	 */
+	buyerEmail?: string;
+	/**
+	 * Keeps the buyer from editing the prefilled `buyerEmail` — an invoice link names who it was issued to. Only holds while the field still shows that email; a session email that already differs is never locked to it, and without a `buyerEmail` there is nothing to lock.
+	 * @default false
+	 */
+	lockBuyerEmail?: boolean;
 	/**
 	 * Runs after the loading skeleton first paints and before `onReady`.
 	 */
@@ -115,7 +140,7 @@ export interface CheckoutElementCreateOptions {
  */
 export interface ExpressCheckoutElementProps {
 	/**
-	 * Which wallets may render — a filter over what the buyer’s device actually offers. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first whatever order this lists. An empty list renders nothing (warned in dev builds). Apple Pay also needs the page’s domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain) — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the Apple Pay button stays hidden.
+	 * Which wallets may render — a filter over what the buyer’s device actually offers. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first whatever order this lists. An empty list renders nothing (warned in dev builds). Both wallets need the page’s domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain) — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the buttons stay hidden. Offering Google Pay on your own site is subject to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos).
 	 * @default ["apple_pay","google_pay"]
 	 */
 	wallets?: ("apple_pay" | "google_pay")[];
@@ -156,7 +181,7 @@ export interface ExpressCheckoutElementHandle {
  */
 export interface ExpressCheckoutElementCreateOptions {
 	/**
-	 * Which wallets may render — a filter over what the buyer’s device actually offers. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first whatever order this lists. An empty list renders nothing (warned in dev builds). Apple Pay also needs the page’s domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain) — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the Apple Pay button stays hidden.
+	 * Which wallets may render — a filter over what the buyer’s device actually offers. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first whatever order this lists. An empty list renders nothing (warned in dev builds). Both wallets need the page’s domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain) — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the buttons stay hidden. Offering Google Pay on your own site is subject to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos).
 	 * @default ["apple_pay","google_pay"]
 	 */
 	wallets?: ("apple_pay" | "google_pay")[];
@@ -190,7 +215,7 @@ export interface CheckoutHandle {
 	 */
 	create(name: "checkout", options?: CheckoutElementCreateOptions): CheckoutElementHandle;
 	/**
-	 * One-press Apple Pay and Google Pay buttons for a checkout — the OS payment sheet collects whatever the session still needs (the buyer's email, a phone number where the seller collects one, a shipping address for physical goods, and in Apple Pay a promo code where the seller offers entry) and one press finishes the purchase. It shares the checkout's entry slot with the full checkout element, so a handle mounts exactly one of the two: this button alone where the purchase is simple enough for a sheet to finish, or the full checkout surface for everything else. Renders only the wallets the buyer's device can actually pay with — and the checkout's own payment method configuration allows — using the served button art, and renders nothing where no wallet is available. Apple Pay additionally requires the page's domain to be a verified payment method domain: first-party whop.com pages are pre-approved, and any other site must register its domain through the Payment Method Domains API before the button renders there. A checkout the sheet cannot honestly finish — a waitlist join, a transfer, a form question only a page can ask — refuses loudly instead of rendering a doomed button.
+	 * One-press Apple Pay and Google Pay buttons for a checkout — the OS payment sheet collects whatever the session still needs (the buyer's email, a phone number where the seller collects one, a shipping address for physical goods, and in Apple Pay a promo code where the seller offers entry) and one press finishes the purchase. It shares the checkout's entry slot with the full checkout element, so a handle mounts exactly one of the two: this button alone where the purchase is simple enough for a sheet to finish, or the full checkout surface for everything else. Renders only the wallets the buyer's device can actually pay with — and the checkout's own payment method configuration allows — using the served button art, and renders nothing where no wallet is available. Both wallets require the page's domain to be a verified payment method domain: first-party whop.com pages are pre-approved, and any other site must register its domain through the Payment Method Domains API before either button renders there. Offering Google Pay on your own site is subject to the Google Pay API Terms of Service. A checkout the sheet cannot honestly finish — a waitlist join, a transfer, a form question only a page can ask — refuses loudly instead of rendering a doomed button.
 	 * Exclusive slot `entry`. Mount exactly one of: checkout | expressCheckout.
 	 */
 	create(name: "expressCheckout", options?: ExpressCheckoutElementCreateOptions): ExpressCheckoutElementHandle;
@@ -210,6 +235,20 @@ export interface CheckoutHandle {
  */
 export interface CheckoutStatics {}
 
+/**
+ * Declared from the app's `CheckoutItemInput`, referenced by a host-capability surface.
+ */
+export interface CheckoutItemInput {
+	/**
+	 * Existing plan ID, prefixed `plan_`.
+	 */
+	plan: string;
+	/**
+	 * Number of units to purchase. Defaults to 1; plans can disallow quantities above 1.
+	 */
+	quantity?: number | undefined;
+}
+
 /**
  * Checkout attribution recorded with the session. The element maps these fields to `POST /api/v1/checkout_sessions`; empty values are omitted, and `country` is resolved by the API.
  * Declared from the app's `CheckoutAttributionInput`, referenced by a host-capability surface.