Sign in
Paywalls V2

Push Headless Version

Pushes a self-contained headless (code-first) paywall snapshot as a new immutable version: stores the content-addressed artifact and creates the version + snapshot. Production is untouched — promote makes a pushed version live. Pushing identical content returns the existing version. Requires paywalls:write scope.

post/v2/paywalls/{id}/versions

Path parameters

idstring required

Paywall ID

Paywall ID

Request body

htmlstring required

The self-contained HTML snapshot to push, at most 5 MB. Stored content-addressed: pushing identical content returns the existing version.

surfacestring

The framework surface identifier (directory name) this snapshot was built from — stamped into paywall metadata so repeated pushes bind to the same paywall.

web_checkout_destination'EXTERNAL' | 'IN_APP_BROWSER' | 'PAYMENT_SHEET' | 'PAYWALL' | 'PAYWALL_EMBEDDED' | 'PAYWALL_APPLE_PAY'

How this snapshot's config completes web checkout (checkout: sheet → PAYWALL_EMBEDDED, applePay → PAYWALL_APPLE_PAY, external → EXTERNAL). Stored with the version and stamped onto the paywall on promote — the same column editor paywalls set, so hosts request checkout directives identically for both.

background_color_hexstring

The paywall's light-mode background color as a hex string (#RRGGBB or #RRGGBBAA). Stored with the version and stamped onto the paywall on promote — the same column editor paywalls set. Native SDKs paint it behind the webview and derive the loading spinner from it, so it must match the paywall's own page background.

dark_background_color_hexstring

The paywall's dark-mode background color as a hex string (#RRGGBB or #RRGGBBAA). Stored with the version and stamped onto the paywall on promote. Optional — SDKs fall back to the light color in dark mode when absent.

on_device_cacheboolean

Whether SDKs cache this paywall on device. Stored with the version and stamped onto the paywall on promote. Omitted means enabled.

scroll_enabledboolean

Whether the paywall webview scrolls. Stored with the version and stamped onto the paywall on promote. Omitted means enabled.

game_controller_enabledboolean

Whether game controller input is forwarded to the paywall. Stored with the version and stamped onto the paywall on promote. Omitted means disabled.

introductory_offer_eligibility'automatic' | 'always_eligible' | 'always_ineligible'

How SDKs decide trial eligibility for this paywall's products. Stored with the version and stamped onto the paywall on promote. Omitted means automatic.

Response

Success

object'paywall.version' required

Object type, always paywall.version

idstring required

ID of the paywall

versionnumber required

The pushed version number

created_atstring required

ISO 8601 timestamp of when the version was created

snapshot_idstring required

Content hash (sha256) identifying the pushed snapshot

urlstring required

Immutable URL the pushed snapshot is served from

Changes

No recorded changes to this endpoint across all 1 revision of this API.