Resolve a paywall

Resolves what a paywall location shows the person: the paywall and its deployed build (paywallRelease), with where to download it.

Answers null when the location does not exist, shows nothing, or shows a build this version of the SDK cannot display.

Guide: Install an SDK

Errors

This operation adds no error codes of its own. It can fail with the errors every operation shares, such as unauthenticated; see Errors.

More in SDK

Something wrong or missing on this page? Tell us by email or on Discord.

Header parameters

x-distinct-id*string

The distinct id of the end user the request acts for: the anonymous vh_anon_… id the SDK generated, or the id the app identified them with. At most 255 characters.

x-distinct-id-encoding?"percent"

percent when x-distinct-id holds the RFC 3986 percent-encoded UTF-8 form of an id that is not printable ASCII; leave it out when the header holds the id as is.

Value in

"percent"

x-publishable-key*string

The project's publishable key, vh_pk_…. A test key, vh_pk_test_…, works with store sandbox and test purchases.

x-client-bundle-id*string

The app's bundle id on iOS or package name on Android, which picks the project's store configuration for purchases and promotional offers.

x-client-locale?string

The end user's most preferred locale, such as en-US.

x-client-version?string

The app's version, such as 2.4.1.

x-is-backgrounded*string

true when the app sent the request from the background, otherwise false.

Value in

"true"
"false"

x-is-debug-build*string

true when the app is a debug build, otherwise false. Only debug builds can make simulated development purchases.

Value in

"true"
"false"

x-nonce?string

A random id, new for every request, such as a lowercase UUID.

x-observer-mode*string

true when the SDK runs in observer mode: another billing integration owns purchases and the SDK only reports them. Otherwise false.

Value in

"true"
"false"

x-platform*string

The platform the app runs on, such as ios, android or web. Records where a new person signed up.

x-platform-brand?string

The device's manufacturer, such as Apple or Google.

x-platform-device?string

The device's model, such as iPhone15,2; in a browser, its navigator.platform.

x-platform-flavor*string

native in an app, browser in a web page.

Value in

"native"
"browser"

x-platform-flavor-version?string

The version of the app hosting the SDK; native SDKs send the app's version, the web SDK leaves it out.

x-platform-version?string

The operating system's version, such as 17.4; in a browser, its user agent.

x-preferred-locales?string

The end user's preferred locales, most preferred first, separated by commas, such as en-US,de-DE.

x-sdk*string

The SDK making the request: ios, android, react-native or web. A native SDK driven by another reports the outer one, such as react-native.

Value in

"react-native"
"web"
"ios"
"android"

x-sdk-version*string

The version of the SDK making the request, such as 1.4.0.

x-storefront?string

The app store storefront (country) the end user buys from, when the SDK knows it.

x-ui-package-abi?string

The newest flow package format version the SDK's paywall engine reads.

x-ui-guest-abi?string

The newest component guest ABI version the SDK's paywall engine runs. Without it the other engine headers are ignored and only releases a guest ABI 1 engine without native components can show are served.

x-ui-native-components?string

The native components the SDK's paywall engine provides, as comma-separated id@version entries.

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

locationSlug*string

The slug of the location to show a paywall at.

Examples

curl -X POST "https://api.voidhash.com/api/v1/sdk/resolve-paywall" \  -H "x-distinct-id: user_8231" \  -H "x-publishable-key: vh_pk_..." \  -H "x-client-bundle-id: com.example.app" \  -H "x-is-backgrounded: true" \  -H "x-is-debug-build: true" \  -H "x-observer-mode: true" \  -H "x-platform: ios" \  -H "x-platform-flavor: native" \  -H "x-sdk: react-native" \  -H "x-sdk-version: 0.0.1-alpha.1" \  -H "Content-Type: application/json" \  -d '{    "locationSlug": "settings-upgrade"  }'

{  "location": {    "id": "pw_loc_e2r5t8y1u4i7o0p3a6s9d2f5",    "name": "Settings upgrade",    "slug": "settings-upgrade"  },  "showing": {    "id": "pw_loc_show_w4e8r2t6y0u3i7o1p5a9s3d7",    "type": "paywall_release",    "paywall": {      "id": "pw_h7d2k9m4x1c6v8b3n5q0w2e7",      "name": "Annual upsell",      "slug": "annual-upsell"    },    "paywallId": "pw_h7d2k9m4x1c6v8b3n5q0w2e7",    "paywallReleaseId": "pw_pub_n8m1q4w7e0r3t6z3x6c9v2b5",    "paywallRelease": {      "releaseId": "pw_pub_n8m1q4w7e0r3t6z3x6c9v2b5",      "version": 3,      "publishedAt": "2026-03-10T11:05:02.000Z",      "flowPackage": {        "abiVersion": 1,        "productIds": [          "pro_monthly",          "pro_annual"        ],        "sha256": "4f1c9a7e2b8d6035c1e9f4a2b7d0c8e3f6a19b5d2c7e0f8a3b6d9c1e4f7a2b5d",        "url": "https://api.voidhash.com/f/4f1c9a7e2b8d6035c1e9f4a2b7d0c8e3f6a19b5d2c7e0f8a3b6d9c1e4f7a2b5d.vhfp",        "kind": "paywall",        "shouldEndFlowOnPurchase": true      }    },    "startedAt": "2026-03-10T11:05:02.000Z"  }}

{  "_tag": "Api/SdkValidationError",  "message": "string"}

{  "_tag": "Api/AuthenticationError",  "cause": "string",  "message": "string"}

{  "_tag": "Api/SdkServiceError",  "cause": "string"}

Resolve a paywall

Errors

More in SDK

Resolve a paywall

Errors

More in SDK

Authorization

Header parameters

Request body

Examples

Response body

`application/json`

`application/json`

`application/json`

`application/json`

Resolve a paywall

Resolve a paywall

200application/json

400application/json

401application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`