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
A project publishable key, which ships inside apps. Send the end user's distinct id in x-distinct-id with it.
In: header
Header parameters
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.
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"
The project's publishable key, vh_pk_…. A test key, vh_pk_test_…, works with store sandbox and test purchases.
The app's bundle id on iOS or package name on Android, which picks the project's store configuration for purchases and promotional offers.
The end user's most preferred locale, such as en-US.
The app's version, such as 2.4.1.
true when the app sent the request from the background, otherwise false.
Value in
- "true"
- "false"
true when the app is a debug build, otherwise false. Only debug builds can make simulated development purchases.
Value in
- "true"
- "false"
A random id, new for every request, such as a lowercase UUID.
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"
The platform the app runs on, such as ios, android or web. Records where a new person signed up.
The device's manufacturer, such as Apple or Google.
The device's model, such as iPhone15,2; in a browser, its navigator.platform.
native in an app, browser in a web page.
Value in
- "native"
- "browser"
The version of the app hosting the SDK; native SDKs send the app's version, the web SDK leaves it out.
The operating system's version, such as 17.4; in a browser, its user agent.
The end user's preferred locales, most preferred first, separated by commas, such as en-US,de-DE.
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"
The version of the SDK making the request, such as 1.4.0.
The app store storefront (country) the end user buys from, when the SDK knows it.
The newest flow package format version the SDK's paywall engine reads.
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.
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.
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"}Response body
application/json
application/json
application/json
application/json
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
- Retrieve the person
GET - Identify a person
POST - Update the person's attributes
POST - Sync a store transaction
POST - Sign a promotional offer
POST - Record a development purchase
POST - Evaluate feature flags
POST - Retrieve the SDK schema
GET - Register a push device
POST - Refresh a push device
POST - Unregister a push device
POST
Something wrong or missing on this page? Tell us by email or on Discord.