SUsuperwall
Paywalls V2

Push Headless Version

Changed on

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

Request

  • Base URL
    https://api.superwall.com
  • URL
    https://api.superwall.com/v2/paywalls/{id}/versions
  • Auth
    • HTTP bearer
    • or API key in cookie accounts_superwall_token
    • or HTTP bearer

Path parameters

idstring required

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.

localesstring[]

The locales this snapshot ships message catalogs for, as BCP 47 tags. Stored with the version so a preview can offer the same language switcher the paywall supports.

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 introductory offer eligibility

allowed_hostsstring[]

Extra origins the served Content-Security-Policy permits this snapshot to call, as https://host[:port]. Stored with the version and written alongside the snapshot, so the runtime widens connect-src for exactly this snapshot. Superwall and Stripe are always reachable; everything else a paywall calls must be named here or the browser refuses the request. Omitted means the default policy applies unchanged.

Response

Success

object'paywall.version' required

Object type, always paywall.version

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

  • 523b4734dfabRevision changes
    • info

      added the new optional request property ///

  • 778a11cd2c15Revision changes
    • warning

      added the new credentials_missing enum value to the / response property for the response status

    • warning

      added the new credentials_missing enum value to the / response property for the response status

    • warning

      added the new credentials_missing enum value to the / response property for the response status

    • warning

      added the new credentials_missing enum value to the / response property for the response status

    • warning

      added the new credentials_missing enum value to the / response property for the response status

    • warning

      added the new credentials_missing enum value to the / response property for the response status

    • warning

      added the new credentials_missing enum value to the / response property for the response status

    • info

      added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 to the response body anyOf list for the response status

    • info

      removed subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 from the response body anyOf list for the response status