{"info":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","description":"

Every endpoint documented in the Botsi API reference, in the order the AI Pricing flow calls them.

Setup

Set the secretKey variable to your app’s secret key, from the App configuration page in the dashboard at https://app.botsi.com.
Set placementId to a Placement configured in your dashboard.
Run the requests top to bottom, or use the Collection Runner.

Keep the key out of source control. Prefer setting secretKey in a Postman environment or as an initial-value-blank secret variable rather than saving it into the collection.

Authentication

Every request sends the secret key in the Authorization header, configured once at the collection level and inherited by each request.

Authorization: \nContent-Type: application/json\n

The header value is the key itself. There is no Bearer and no Api-Key prefix. Adding a prefix is the most common cause of an authentication failure that looks like a wrong key.

Never ship this key in a mobile binary or browser bundle: it authorizes every endpoint here, including reading Profiles and validating purchases.

The call sequence

Create a Profile for each user.
Publish custom attributes on that Profile, if you have additional user metadata.
Fetch the Paywall and persist the paywallSessionId it returns.
Send a paywall_shown event with that paywallSessionId.
Validate purchases if using IAP with App Store or Google Play.

Requests are chained through collection variables. Create a Profile writes profileId; Fetch Paywall writes paywallSessionId, paywallId, aiPricingModelId, and isExperiment. Running the collection in order therefore needs no manual copying.

paywallId, aiPricingModelId, and isExperiment are interpolated unquoted in the purchase-validation bodies, because the API expects two numbers and a boolean. Keep them unquoted if you edit those bodies.

Status codes

2xx means success, 4xx means something in your request needs changing, and 5xx means the failure was on Botsi’s side.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Meaning
`200`	The request succeeded. The body carries the requested data
`201`	The request succeeded and created a resource, such as a Profile
`204`	The request succeeded with nothing to return
`400`	A required parameter is missing: no `profileId`, or an empty `custom` array
`401`	No valid API key in the `Authorization` header
`403`	The key is valid but lacks permission for that resource
`404`	The resource does not exist
`422`	Well-formed but semantically wrong: a string where a number was expected
`429`	Rate limited. Back off and retry
`500` `502` `503` `504`	Server-side failure. Retry with backoff

429 and 5xx are the only codes worth retrying without changing the request first.

Error format

Errors return a JSON object with a human-readable message and a machine-readable code:

{\n  \"error\": \"Internal error\",\n  \"code\": \"paywall_fetch_failed\"\n}\n

Branch on code. The error string is for humans reading logs and may change.

One exception to retrying

A failed Fetch Paywall should fall back, not block. Retrying a 5xx with backoff is correct for events and validation, where the data matters and arriving late is fine. In front of a user waiting on a Paywall, serve your baseline variant instead.

Fidelity notes

Request bodies and response examples are taken verbatim from the API reference. Two places required judgement, each flagged in the relevant description:

401 and 400 bodies are shown in the documented { error, code } envelope, but the docs do not print the specific strings for those cases except on Send Paywall Shown Event, whose four messages are verbatim.
recurrenceMode values on Google pricing phases follow the Google Play Billing Library convention; the Botsi docs require the field but do not enumerate its values.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"2219874","collectionId":"e0698370-1beb-443b-968a-1ac87f4be07e","publishedId":"2sBYAvwB8S","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-09-04T15:22:33.000Z"},"item":[{"name":"1. Profiles","item":[{"name":"Create a Profile","event":[{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":["pm.test('Status is 200 OK or 201 Created', () => {"," pm.expect(pm.response.code).to.be.oneOf([200, 201]);","});","","const body = pm.response.json();","","pm.test('Response uses the documented { ok, data } envelope', () => {"," pm.expect(body).to.have.property('ok', true);","});","","pm.test('Response carries a profileId', () => {"," pm.expect(body.data).to.have.property('profileId').that.is.a('string');","});","","// Chain the new Profile into the rest of the collection.","pm.collectionVariables.set('profileId', body.data.profileId);","if (body.data.appUserId) {"," pm.collectionVariables.set('appUserId', body.data.appUserId);","}"],"id":"f7d577ec-e5fe-4af9-9d53-2353ea932fb1"}}],"id":"ff7d9df9-1bde-427a-9954-4d42556af769","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"country\": \"US\",\n \"device\": \"iPhone 15 Pro Max\",\n \"os\": \"iOS 17.0\",\n \"platform\": \"ios\",\n \"appVersion\": \"1.0.0\",\n \"appUserId\": \"user-123\",\n \"locale\": \"en_US\",\n \"appBuild\": \"100\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"ipAddress\": \"203.0.113.7\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/profiles","description":"

Call this on first app launch. It creates the Profile every other operation depends on — AI Pricing, subscriptions, and Paywall tracking all need one to exist.

Required: country, device, os, platform, appVersion.

platform accepts android, ios, ipados, tvos, macos, watchos, visionos, and stripe.

appUserId is documented as Recommended rather than required: it ties the Botsi Profile to the user record in your own system and lets the same person be recognised on a second device.

Optional and stored: appUserId, locale, appBuild, advertisingId, ipAddress, email, phone, gender, idfa, username.

Accepted but discarded — the API strips any field it does not model, so these are silently ignored rather than rejected: currency, billingCountry, timezone, osVersion, sessionId, pushToken. They are not stored and never appear in the response.

country takes a 2-letter alpha-2 code, or an uppercase 3-letter alpha-3 code that Botsi can map. An unmappable 3-letter value is rejected with 400.

The test script stores data.profileId into the profileId collection variable, so every later request in this collection resolves against the Profile you just created.

Source: content/api-reference/create-profile.md

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","type":"collection"}},"urlObject":{"path":["v2","profiles"],"host":["https://api.botsi.com"],"query":[],"variable":[]}},"response":[{"id":"579544fe-9577-454f-a46b-677fc37d5517","name":"201 Created","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"country\": \"US\",\n \"device\": \"iPhone 15 Pro Max\",\n \"os\": \"iOS 17.0\",\n \"platform\": \"ios\",\n \"appVersion\": \"1.0.0\",\n \"appUserId\": \"user-123\",\n \"locale\": \"en_US\",\n \"appBuild\": \"100\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"ipAddress\": \"203.0.113.7\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/profiles"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"appUserId\": \"user-123\",\n \"country\": \"US\",\n \"locale\": \"en_US\",\n \"ip\": \"203.0.113.7\",\n \"device\": \"iPhone 15 Pro Max\",\n \"os\": \"iOS 17.0\",\n \"platform\": \"ios\",\n \"appVersion\": \"1.0.0\",\n \"appBuild\": \"100\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"createdAt\": \"2026-08-27T10:30:00.000Z\",\n \"updatedAt\": \"2026-08-27T10:30:00.000Z\"\n }\n}"},{"id":"21f0dcb2-ec3c-43af-a290-3ce7a4528e73","name":"401 Unauthorized — missing or prefixed key","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"country\": \"US\",\n \"device\": \"iPhone 15 Pro Max\",\n \"os\": \"iOS 17.0\",\n \"platform\": \"ios\",\n \"appVersion\": \"1.0.0\",\n \"appUserId\": \"user-123\",\n \"locale\": \"en_US\",\n \"appBuild\": \"100\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"ipAddress\": \"203.0.113.7\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/profiles"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"No valid API key provided.\",\n \"code\": \"unauthorized\"\n}"},{"id":"69980851-3c4e-4b44-91d4-55e1041d0a7a","name":"400 Bad Request — unmappable country","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"country\": \"US\",\n \"device\": \"iPhone 15 Pro Max\",\n \"os\": \"iOS 17.0\",\n \"platform\": \"ios\",\n \"appVersion\": \"1.0.0\",\n \"appUserId\": \"user-123\",\n \"locale\": \"en_US\",\n \"appBuild\": \"100\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"ipAddress\": \"203.0.113.7\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/profiles"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"country must be a 2-letter ISO 3166-1 alpha-2 code or an uppercase 3-letter alpha-3 code\",\n \"code\": \"bad_request\"\n}"}],"_postman_id":"ff7d9df9-1bde-427a-9954-4d42556af769"},{"name":"Add Custom Attributes","event":[{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":["pm.test('Status is 200 OK or 201 Created', () => {"," pm.expect(pm.response.code).to.be.oneOf([200, 201]);","});","","const body = pm.response.json();","","pm.test('Response uses the documented { ok, data } envelope', () => {"," pm.expect(body).to.have.property('ok', true);","});","","pm.test('Every submitted attribute comes back with an id', () => {"," const sent = JSON.parse(pm.request.body.raw).custom.length;"," pm.expect(body.data).to.be.an('array').with.lengthOf(sent);"," body.data.forEach((attribute) => pm.expect(attribute).to.have.property('id'));","});"],"id":"c57ace06-60e2-460a-a725-47aebc943820"}}],"id":"64336719-9506-4158-8e6b-43fe195d2d65","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"\",\n \"custom\": [\n {\n \"key\": \"user_level\",\n \"value\": \"premium\"\n },\n {\n \"key\": \"subscription_type\",\n \"value\": \"annual\"\n },\n {\n \"key\": \"referral_source\",\n \"value\": \"facebook\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/custom-attributes","description":"

Custom attributes enrich a Profile with metadata. Provide as much as possible for better results from the Botsi AI Pricing Models.

Required: profileId, and a custom array holding at least one { key, value } object. Both key and value are strings.

An empty custom array is rejected with 400.

Source: content/api-reference/add-profile-attributes.md

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","type":"collection"}},"urlObject":{"path":["v2","custom-attributes"],"host":["https://api.botsi.com"],"query":[],"variable":[]}},"response":[{"id":"b4d05833-f526-4450-bc3d-c4e324b761d9","name":"200 OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"\",\n \"custom\": [\n {\n \"key\": \"user_level\",\n \"value\": \"premium\"\n },\n {\n \"key\": \"subscription_type\",\n \"value\": \"annual\"\n },\n {\n \"key\": \"referral_source\",\n \"value\": \"facebook\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/custom-attributes"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": [\n {\n \"id\": \"abc123\",\n \"key\": \"user_level\",\n \"value\": \"premium\"\n },\n {\n \"id\": \"def456\",\n \"key\": \"subscription_type\",\n \"value\": \"annual\"\n },\n {\n \"id\": \"ghi789\",\n \"key\": \"referral_source\",\n \"value\": \"facebook\"\n }\n ]\n}"},{"id":"812897bf-aca2-4b7d-8c4a-8eed2cb2b55f","name":"400 Bad Request — empty custom array","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"\",\n \"custom\": [\n {\n \"key\": \"user_level\",\n \"value\": \"premium\"\n },\n {\n \"key\": \"subscription_type\",\n \"value\": \"annual\"\n },\n {\n \"key\": \"referral_source\",\n \"value\": \"facebook\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/custom-attributes"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"custom must contain at least 1 elements\",\n \"code\": \"bad_request\"\n}"},{"id":"35825a23-e5b3-47bb-a06d-3fb75ff2fc6c","name":"404 Not Found — unknown profile","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"\",\n \"custom\": [\n {\n \"key\": \"user_level\",\n \"value\": \"premium\"\n },\n {\n \"key\": \"subscription_type\",\n \"value\": \"annual\"\n },\n {\n \"key\": \"referral_source\",\n \"value\": \"facebook\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/custom-attributes"},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"No profile found by id: 0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"code\": \"not_found\"\n}"}],"_postman_id":"64336719-9506-4158-8e6b-43fe195d2d65"},{"name":"Update Custom Attributes","event":[{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":["pm.test('Status is 200 OK', () => pm.response.to.have.status(200));","","const body = pm.response.json();","","pm.test('Response uses the documented { ok, data } envelope', () => {"," pm.expect(body).to.have.property('ok', true);","});","","pm.test('Updated values are echoed back', () => {"," const sent = JSON.parse(pm.request.body.raw).custom;"," sent.forEach((attribute) => {"," const returned = body.data.find((item) => item.key === attribute.key);"," pm.expect(returned, `attribute ${attribute.key}`).to.not.be.undefined;"," pm.expect(returned.value).to.eql(attribute.value);"," });","});"],"id":"c5ca2de0-e943-4a81-bf8b-36afdc390a52"}}],"id":"34cbb9bb-bad0-4e64-bd22-d7e261616902","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"\",\n \"custom\": [\n {\n \"key\": \"user_level\",\n \"value\": \"vip\"\n },\n {\n \"key\": \"subscription_type\",\n \"value\": \"annual\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/custom-attributes","description":"

Update existing attribute values, as when a user upgrades from premium to vip.

Identify the user with profileId. Each attribute is targeted by custom[].key.

Required: profileId, and a custom array holding at least one { key, value } object.

An empty custom array is rejected with 400.

Source: content/api-reference/update-profile-attributes.md

The update is atomic: if any key in custom is missing on the Profile, nothing is written and the 404 names the missing keys. Use POST to create attributes.

Create the record Botsi keeps for one of your users, and enrich it with metadata. Every other operation depends on a Profile existing.

Source: content/api-reference/create-profile.md, add-profile-attributes.md, update-profile-attributes.md

\n","_postman_id":"5099d256-27c6-4be5-9618-026c6f64ba7b","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","type":"collection"}}},{"name":"2. Paywalls","item":[{"name":"Fetch Paywall","event":[{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":["pm.test('Status is 200 OK', () => pm.response.to.have.status(200));","","const body = pm.response.json();","","pm.test('Response uses the documented { ok, data } envelope', () => {"," pm.expect(body).to.have.property('ok', true);","});","","pm.test('Response carries the fields the later calls need', () => {"," const data = body.data;"," pm.expect(data).to.have.property('id').that.is.a('number');"," pm.expect(data).to.have.property('paywallSessionId').that.is.a('string');"," pm.expect(data).to.have.property('aiPricingModelId');"," pm.expect(data).to.have.property('isExperiment');"," pm.expect(data).to.have.property('paywallProducts').that.is.an('array');","});","","pm.test('Each product carries a keyed row id and one block per store', () => {"," const products = body.data.paywallProducts;"," pm.expect(products).to.be.an('array').that.is.not.empty;",""," for (const product of products) {"," pm.expect(product).to.have.property('paywallProductId').that.is.a('number');"," pm.expect(product).to.have.property('name').that.is.a('string');"," pm.expect(product).to.have.property('period').that.is.a('string');",""," // All five blocks are always present as a key: an object, or null when"," // the product has no identity on that store (BTSI-191)."," for (const store of ['appStore', 'playStore', 'stripe', 'web2wave', 'custom']) {"," pm.expect(product, `${store} key is always present`).to.have.property(store);",""," if (product[store] !== null) {"," // productId inside a block is non-nullable: its presence is what"," // makes the block exist at all."," pm.expect(product[store].productId, `${store}.productId`).to.be.a('string').and.not.empty;"," }"," }"," }",""," // The flat productId and offer fields moved inside the store blocks, and"," // Botsi has never modelled a store-level discount."," pm.expect(products[0]).to.not.have.property('productId');"," pm.expect(products[0]).to.not.have.property('discountId');","});","","// Attribution chain. paywallId, aiPricingModelId and isExperiment are written","// as bare literals so they interpolate unquoted into the validation bodies,","// where the API expects a number and a boolean rather than strings.","pm.collectionVariables.set('paywallSessionId', body.data.paywallSessionId);","pm.collectionVariables.set('paywallId', String(body.data.id));","pm.collectionVariables.set('aiPricingModelId', String(body.data.aiPricingModelId));","pm.collectionVariables.set('isExperiment', String(body.data.isExperiment));","","// The token is only valid for a paywall_shown event for 24 hours.","console.log('paywallSessionId expires', new Date(Date.now() + 86400000).toISOString());"],"id":"f48ec667-db92-460e-a153-5f4bce79bf36"}}],"id":"19963bad-1843-4676-b54a-c3bd22efbfa8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"\",\n \"placementId\": \"ai-placement-id\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/paywall","description":"

Once a Profile exists, call this at any time to retrieve the Paywall variant the AI Pricing Model selected for that user. The response identifies which of your pre-configured paywalls to display.

Required: profileId, placementId. Those two fields are the whole request.

Any other field is stripped before validation rather than rejected, so a client still sending store, locale, country, ip or storeCountry keeps working — those values are ignored, and resolution uses the Profile data Botsi already holds.

One call answers for every store, so a multi-store integrator fetches a Placement's Paywall once rather than once per store. That also means one A/B or AI-pricing decision and one paywallSessionId per impression.

Product shape

Each entry in data.paywallProducts describes one product attached to the Paywall, followed by one nested block per store:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Meaning
`paywallProductId`	Number identifying this entry within `paywallProducts`
`name`	Product name as configured in Botsi
`period`	`weekly`, `monthly`, `2_months`, `3_months`, `6_months`, `annual`, `lifetime`, `consumable`, or `non_subscription`
`appStore`	`productId`, `offerId`, `promotionalOfferId`, `offerType` — or `null`
`playStore`	`productId`, `basePlanId`, `offerId` — or `null`
`stripe`	`productId`, `priceId`, `trialPeriodDays` — or `null`
`web2wave`	`productId` — or `null`
`custom`	`productId` — or `null`

A block is null when the product has no identifier for that store, and productId inside a block is never null, so if (!product.playStore) is a well-defined \"not sold on Google Play\" check. Under the earlier flat shape, a product with no Google id and a genuine mapping bug both arrived as productId: null.

paywallProductId is the id of the row attaching the product to the Paywall, not the product's own id. One product can be attached to the same Paywall twice under different offers, and this keeps those entries distinguishable.

The App Store offer fields come from the offer attached to this entry, not from the product. On Google Play, \"no base plan\" and \"no offer\" are stored as empty strings and returned as null; only a missing Google Play product id nulls the whole block.

Botsi does not model a store-level discount or coupon concept, so there is no discountId — use offerId together with offerType.

Timing

Do not call this synchronously at render time. The response typically takes around 40 ms but can take up to 2 seconds depending on prediction speed. Trigger it early — immediately after the Profile is created is a good moment — and have the response cached before the user reaches the Paywall.

Failure behaviour

A 5xx here should fall back, not block. Retrying with backoff is right for events and validation, where arriving late is fine. In front of a user waiting on a Paywall, serve your baseline variant instead.

The test script stores paywallSessionId, id (as paywallId), aiPricingModelId, and isExperiment into collection variables, which the event and purchase-validation requests then consume.

Source: content/api-reference/fetch-paywall.md

Retrieve the Paywall variant the AI Pricing Model selected for a user and Placement.

Source: content/api-reference/fetch-paywall.md

\n","_postman_id":"aef788c3-7b3d-47b6-b674-d8f6a8552d7b","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","type":"collection"}}},{"name":"3. Events","item":[{"name":"Send Paywall Shown Event","event":[{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":["pm.test('Status is 200 OK', () => pm.response.to.have.status(200));","","const body = pm.response.json();","","pm.test('Response is the documented acknowledgement — { ok } with no data', () => {"," pm.expect(body).to.have.property('ok', true);\n pm.expect(body).to.not.have.property('data');","});","","pm.test('A paywallSessionId was available to send', () => {"," pm.expect(pm.collectionVariables.get('paywallSessionId'), 'run Fetch Paywall first').to.be.a('string').and.not.empty;","});"],"id":"16cb7fb4-fc4d-47fe-98ce-15f816c64e96"}}],"id":"44c4e52f-d34f-4512-bebd-76b39fc45475","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"eventType\": \"paywall_shown\",\n \"paywallSessionId\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/events","description":"

Call this immediately after the Paywall is displayed. The impression is what conversion is measured against, and what lets the model learn from the outcome.

The request body is a single JSON object. Sending a JSON array — v1's shape — is rejected with 400 Request body must be a single event object, not an array.

The whole accepted field set is two fields: eventType (must be paywall_shown) and paywallSessionId (from data.paywallSessionId on the Fetch Paywall response). Everything else about the event — paywall, placement, A/B test, AI-pricing model, and the profile itself — is derived server-side from the token.

Any other field is rejected, not ignored. Sending profileId or customerUserId gets a 400 naming the field: the signed token is the single source of identity, so a client value that disagrees with it is an error worth being told about rather than silently overridden.

Impressions are not deduplicated. Sending the same event twice for one paywallSessionId records two impressions, so send it once per Paywall view.

Working with the token

Every Fetch Paywall response includes a unique paywallSessionId. It is roughly 200 characters today with no fixed maximum — store it in TEXT or VARCHAR(512). One token per Paywall fetch.

A paywall_shown event is accepted for 24 hours after the fetch that minted the token. Send it later and the request is rejected; fetch a new Paywall before reporting the view. Transactions do not expire this way.

Source: content/api-reference/paywall-shown-event.md

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","type":"collection"}},"urlObject":{"path":["v2","events"],"host":["https://api.botsi.com"],"query":[],"variable":[]}},"response":[{"id":"9cb6238d-410e-440b-94d9-9f3f791999d9","name":"200 OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"eventType\": \"paywall_shown\",\n \"paywallSessionId\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/events"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true\n}"},{"id":"09992f29-b1f4-4b4a-b86c-c24bd39228d7","name":"400 Bad Request — invalid token","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"eventType\": \"paywall_shown\",\n \"paywallSessionId\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/events"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"paywallSessionId is not a valid Botsi paywall session token.\",\n \"code\": \"bad_request\"\n}"},{"id":"4ce0ee28-c22a-4534-a2ff-ce7f4670e958","name":"400 Bad Request — expired token","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"eventType\": \"paywall_shown\",\n \"paywallSessionId\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/events"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"paywallSessionId has expired for this event type. Fetch a new paywall before reporting the view.\",\n \"code\": \"bad_request\"\n}"},{"id":"05ec1e53-85b7-4a18-be66-c6562603d597","name":"400 Bad Request — body sent as an array","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"eventType\": \"paywall_shown\",\n \"paywallSessionId\": \"\"\n }\n]","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/events"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Request body must be a single event object, not an array\",\n \"code\": \"bad_request\"\n}"},{"id":"762c64bd-8fe9-4ffe-adf2-4794a1d59ed0","name":"400 Bad Request — identity field sent","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"eventType\": \"paywall_shown\",\n \"paywallSessionId\": \"\",\n \"profileId\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/events"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"profileId is not accepted on v2 events; the profile is taken from the paywallSessionId that minted the paywall\",\n \"code\": \"bad_request\"\n}"}],"_postman_id":"44c4e52f-d34f-4512-bebd-76b39fc45475"}],"id":"9ca09b83-3dce-4de5-85ec-95dfd7c22c05","description":"

Record Paywall exposure, so the model can learn from what followed.

Source: content/api-reference/paywall-shown-event.md

\n","_postman_id":"9ca09b83-3dce-4de5-85ec-95dfd7c22c05","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","type":"collection"}}},{"name":"4. Purchases","item":[{"name":"Validate Apple Store Purchase","event":[{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":["pm.test('Status is 200 OK', () => pm.response.to.have.status(200));","","const body = pm.response.json();","","pm.test('Response uses the documented { ok, data } envelope', () => {"," pm.expect(body).to.have.property('ok', true);","});","","pm.test('Response returns the updated Profile', () => {"," pm.expect(body.data).to.have.property('profileId');"," pm.expect(body.data).to.have.property('accessLevels');"," pm.expect(body.data).to.have.property('subscriptions');","});","","pm.test('Purchase stayed attached to the experiment that produced it', () => {"," const sent = JSON.parse(pm.request.body.raw);"," pm.expect(sent.paywallId, 'paywallId').to.be.a('number');"," pm.expect(sent.aiPricingModelId, 'aiPricingModelId').to.be.a('number');"," pm.expect(sent.isExperiment, 'isExperiment').to.be.a('boolean');","});"],"id":"573593fc-76b2-4d6f-a1ec-26b0a967bf19"}}],"id":"48bee783-c4a7-4fd1-88a5-942f7d078689","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"source\": \"purchasing\",\n \"productId\": \"premium_annual\",\n \"isSubscription\": true,\n \"originalTransactionId\": \"2000000261699248\",\n \"environment\": \"sandbox\",\n \"transactionId\": \"2000000871590381\",\n \"profileId\": \"\",\n \"isExperiment\": true,\n \"aiPricingModelId\": 32\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/purchases/apple-store/validate","description":"

Call this after a purchase completes in your app. It confirms the transaction with Apple and records the revenue against the Profile and the Paywall that produced it.

Required: profileId, productId, transactionId, originalTransactionId.

Optional: placementId, paywallId, abTestId, isSubscription, environment, source, isExperiment, aiPricingModelId.

isExperiment and aiPricingModelId are optional on v2 (they are required on the SDK surface). Omitting them still validates the purchase — see the attribution note below for why you should send them anyway.

source is optional and defaults to purchasing when omitted. It is load-bearing: restore short-circuits validation entirely, and purchasing selects the deduplication key. Send it deliberately.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description
`transactionId`	string	Transaction identifier from the StoreKit payment object
`originalTransactionId`	string	Original transaction identifier from the StoreKit payment object
`productId`	string	Product identifier from the payment object. Must match the Product configured in Botsi
`placementId`	string	The Placement used to fetch the Paywall
`paywallId`	number	The internal Paywall ID, from `data.id` on the Fetch Paywall response
`isExperiment`	boolean	The value Fetch Paywall returned
`aiPricingModelId`	number	The model ID Fetch Paywall returned
`environment`	string	`production` for live apps, `sandbox` for testing
`profileId`	string	Required. Botsi profile ID from Create a Profile
`isSubscription`	boolean	Optional. Whether the purchase is a subscription
`source`	string	Optional. `restore`, `purchasing`, or `observing`

Attribution fields are not optional in practice

This endpoint does not accept paywallSessionId. The token shortcut applies to Send Paywall Shown Event only. Keep passing paywallId, isExperiment, and aiPricingModelId exactly as Fetch Paywall returned them.

Omit them and the purchase still validates, but it detaches from the experiment that produced it, so the model gets no credit for the revenue it earned.

paywallId, aiPricingModelId, and isExperiment are interpolated unquoted in the body below, because the API expects two numbers and a boolean. Keep them unquoted if you edit the body.

Finding the identifiers

StoreKit. transactionId and originalTransactionId come from the SKPaymentTransaction object. The Product identifier is SKPaymentTransaction.payment.productIdentifier, and the original price is on SKProduct.

StoreKit 2. All three come from the Transaction object, and the original price from Product.

Source: content/api-reference/purchases/validate-apple.md

Call this after a purchase completes in your app. It confirms the transaction with Google Play and records the revenue against the Profile and the Paywall that produced it.

Required: profileId, productId, token.

Optional: placementId, paywallId, abTestId, isSubscription, environment, isExperiment, aiPricingModelId, and exactly one of subscriptionOfferDetails / oneTimePurchaseOfferDetails.

isExperiment and aiPricingModelId are optional on v2 (required on the SDK surface).

⚠️ Send environment explicitly. It has no default: a missing value is treated as non-production, which silently drops the revenue event. production for live apps, sandbox for testing.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter	Type	Description
`token`	string	The token uniquely identifying this purchase for an item and user pair
`productId`	string	Must match the Play Store Product ID configured in Botsi. Use `sourceProductId` from the Products response
`placementId`	string	The Placement used to fetch the Paywall
`paywallId`	number	The internal Paywall ID, from `data.id` on the Fetch Paywall response
`isExperiment`	boolean	The value Fetch Paywall returned
`aiPricingModelId`	number	The model ID Fetch Paywall returned
`environment`	string	`production` for live apps, `sandbox` for testing
`profileId`	string	Required. Botsi profile ID from Create a Profile
`subscriptionOfferDetails`	object	For a subscription. From `ProductDetails.getSubscriptionOfferDetails()`, usually the first item
`oneTimePurchaseOfferDetails`	object	For a one-time purchase

subscriptionOfferDetails and oneTimePurchaseOfferDetails are mutually exclusive — send one, never both.

subscriptionOfferDetails: basePlanId (string), offerId (string, if the Product has an offer configured in the store), pricingPhases (array).

Each pricingPhases entry: priceAmountMicros (number — 1,000,000 micro-units is one unit of currency), currencyCode (ISO 4217), billingPeriod (ISO 8601), recurrenceMode (number), billingCycleCount (number).

oneTimePurchaseOfferDetails: priceAmountMicros (number, e.g. 9990000 for $9.99), currencyCode (ISO 4217).

Attribution fields are not optional in practice

Omit them and the purchase still validates, but it detaches from the experiment that produced it, so the model gets no credit for the revenue it earned.

paywallId, aiPricingModelId, and isExperiment are interpolated unquoted in the body below, because the API expects two numbers and a boolean. Keep them unquoted if you edit the body.

Finding the token

The purchase token comes from getPurchaseToken() in the Google Play Billing Library.

Source: content/api-reference/purchases/validate-google.md

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","type":"collection"}},"urlObject":{"path":["v2","purchases","play-store","validate"],"host":["https://api.botsi.com"],"query":[],"variable":[]}},"response":[{"id":"97a97e98-ef27-4a16-9cea-6490ab8ce8cd","name":"200 OK (shape inferred — see description)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"token\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"placementId\": \"ai-placement-id\",\n \"productId\": \"monthly\",\n \"paywallId\": 42,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32,\n \"environment\": \"sandbox\",\n \"profileId\": \"\",\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"1month-sub\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 359990000,\n \"currencyCode\": \"UAH\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/purchases/play-store/validate"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"profileId\": \"55bbd5f3-6de8-4d3b-8a55-006e6af6e3dd\",\n \"appUserId\": \"user-123\",\n \"state\": \"subscribed\",\n \"totalRevenueUsd\": 8.72,\n \"accessLevels\": {},\n \"subscriptions\": {},\n \"nonSubscriptions\": {}\n }\n}"}],"_postman_id":"7d35bc7a-c541-4ccd-9984-4110ddff9eaa"},{"name":"Validate Google Play Purchase — subscription with free trial","event":[{"listen":"test","script":{"type":"text/javascript","packages":{},"exec":["pm.test('Status is 200 OK', () => pm.response.to.have.status(200));","","const body = pm.response.json();","","pm.test('Response uses the documented { ok, data } envelope', () => {"," pm.expect(body).to.have.property('ok', true);","});","","pm.test('A zero-priced phase is present, so the trial is not booked as revenue', () => {"," const sent = JSON.parse(pm.request.body.raw);"," const phases = sent.subscriptionOfferDetails.pricingPhases;"," pm.expect(phases.some((phase) => phase.priceAmountMicros === 0)).to.be.true;","});"],"id":"949ff502-b86f-4640-881f-db27eb17fe3b"}}],"id":"231af14c-36e3-4870-84fa-2378045e20bb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"token\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"placementId\": \"ai-placement-id\",\n \"productId\": \"monthly\",\n \"paywallId\": 42,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32,\n \"environment\": \"sandbox\",\n \"profileId\": \"\",\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"1month-sub\",\n \"offerId\": \"freetrial-7d\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 0,\n \"currencyCode\": \"UAH\",\n \"billingPeriod\": \"P1W\",\n \"recurrenceMode\": 2,\n \"billingCycleCount\": 1\n },\n {\n \"priceAmountMicros\": 359990000,\n \"currencyCode\": \"UAH\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.botsi.com/v2/purchases/play-store/validate","description":"

Same endpoint as the plain subscription request, sent with the zero-priced phase that identifies a free trial.

Botsi identifies a free trial by a pricingPhases element with priceAmountMicros set to 0, alongside its usual billingPeriod, recurrenceMode, and billingCycleCount. Leave that phase out and the event is read as a paid subscription, which inflates your revenue statistics with money nobody paid.

The zero-priced phase comes first, followed by the phase that charges once the trial ends.

Note on values: the docs specify that recurrenceMode and billingCycleCount must be present but do not enumerate their valid values. The recurrenceMode: 2 / billingCycleCount: 1 pairing on the trial phase follows the Google Play Billing Library convention for a finite recurring phase, and recurrenceMode: 1 the convention for infinite recurring. Confirm against the ProductDetails object your app actually receives.

Source: content/api-reference/purchases/validate-google.md

Same endpoint as the subscription requests, sent with oneTimePurchaseOfferDetails instead of subscriptionOfferDetails. The two are mutually exclusive — send one, never both.

oneTimePurchaseOfferDetails takes priceAmountMicros (9990000 is $9.99) and currencyCode (ISO 4217).

Source: content/api-reference/purchases/validate-google.md

Confirm a store transaction and attach it to the Paywall that produced it. Neither endpoint accepts paywallSessionId — pass paywallId, isExperiment, and aiPricingModelId through from Fetch Paywall instead. Both reply with a strict subset of the Profile: profileId, appUserId, state, totalRevenueUsd, accessLevels, subscriptions, nonSubscriptions — never the PII the Profile row carries.

Source: content/api-reference/purchases/validate-apple.md, validate-google.md

\n","_postman_id":"8ef60873-796b-406b-b58c-a740e0cfa6b1","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e0698370-1beb-443b-968a-1ac87f4be07e","id":"e0698370-1beb-443b-968a-1ac87f4be07e","name":"Botsi API v2","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]}},"event":[{"listen":"prerequest","script":{"type":"text/javascript","packages":{},"exec":["// Fail loudly rather than reading a 401 as a wrong key.","const key = pm.collectionVariables.get('secretKey') || pm.environment.get('secretKey');","if (!key) {"," throw new Error('Set the secretKey variable to your app secret key before sending requests.');","}","if (/^(Bearer|Api-Key)\\s/i.test(key)) {"," throw new Error('Send the key raw. Botsi expects no Bearer or Api-Key prefix in the Authorization header.');","}"],"id":"f7d5cf3f-f998-4791-b7bd-1735011e2f20"}}],"variable":[{"key":"baseUrl","value":"https://api.botsi.com","type":"string","description":"API host. Combined with apiVersion to form the documented base URL."},{"key":"apiVersion","value":"v2","type":"string","description":"API version segment."},{"key":"secretKey","value":"","type":"string","description":"Your app secret key, from the App configuration page in the dashboard. Sent raw in the Authorization header with no scheme prefix. Leave the stored value blank and set it per environment."},{"key":"profileId","value":"","type":"string","description":"Set automatically by Create a Profile."},{"key":"appUserId","value":"user-123","type":"string","description":"Your own internal app user ID, which links the Profile across devices."},{"key":"placementId","value":"ai-placement-id","type":"string","description":"A Placement configured in your dashboard. Set this before running."},{"key":"storeEnvironment","value":"sandbox","type":"string","description":"production for live apps, sandbox for testing."},{"key":"paywallSessionId","value":"","type":"string","description":"Set automatically by Fetch Paywall. Valid for a paywall_shown event for 24 hours."},{"key":"paywallId","value":"42","type":"string","description":"Set automatically by Fetch Paywall from data.id. Interpolated unquoted, because the API expects a number."},{"key":"aiPricingModelId","value":"32","type":"string","description":"Set automatically by Fetch Paywall. Interpolated unquoted, because the API expects a number."},{"key":"isExperiment","value":"true","type":"string","description":"Set automatically by Fetch Paywall. Interpolated unquoted, because the API expects a boolean."}]}