{"info":{"_postman_id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","name":"Botsi API v1 (Legacy)","description":"

The Botsi v1 Web API is a legacy API for managing user profiles, choosing paywalls, recording events, and validating or restoring purchases from your server.

This collection covers selected v1 workflows: Profiles, Paywalls, Events, and Purchases. It includes shared authentication, scripts that save values for later requests, response checks, and saved examples. Profile deletion, direct access grants and revocations, and transaction reporting are outside this collection.

Set up the collection

Find your app's secret key on the App configuration page in the Botsi dashboard. Set secretKey in a Postman environment. Keep the saved collection value blank.
\n
Set customerUserId to your user's ID and placementId to a placement configured for the same app. Review the device, OS, platform, and app version in Create a Profile. Use an Android profile and store: play_store for a Google Play workflow, or an Apple profile and store: app_store for an App Store workflow.
\n

The setup script skips requests with missing variables and writes the variable names to the Postman Console. Use a current Postman version that supports pm.execution.skipRequest().

Base URL

Use these settings to connect to the production API:

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

Setting	Production value
`baseUrl`	`https://app.botsi.com/api`
`apiVersion`	`v1`
Full request path	`https://app.botsi.com/api/v1/web-api/...`

v1 is not available at api.botsi.com****. That host serves v2 and returns 404 for v1 requests.

Authentication

All requests use the authentication setting saved on the collection. Send the secret key itself in the Authorization header:

Authorization: <secretKey>\nContent-Type: application/json\n\n

Do not add Bearer or Api-Key before the key. A missing key, an unknown key, or a key with a prefix returns 403 Forbidden. Your app's public key also returns 403; it is used by the mobile SDK, not for these requests.

Request order

Create a Profile for the user. Use customerUserId to link the profile to your own user record.
\n
Add custom attributes if you have more information about the user.
\n
Fetch Paywall and save the returned paywallSessionId.
\n
Send Paywall Shown Event once when the paywall appears. Include that paywallSessionId. The Explicit Fields request is an alternative for existing integrations. Do not send both for the same view.
\n
Validate the purchase using the one request that matches the store and purchase type. Include the details from the paywall actually shown. The Google subscription, free-trial, and one-time examples are alternatives.
\n

The collection scripts save values for later requests, so you do not need to copy them manually. Keep these generated variables in the collection; environment or runner data values with the same names would override them:

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

Request	Variables saved
Create a Profile	`profileId`
Add Custom Attribute	`customAttributeId`
Fetch Paywall	`paywallSessionId`, `paywallId`, `abTestId`, `aiPricingModelId`, `isExperiment`

In request bodies, keep , , , and outside quotation marks. The first three must be numbers; isExperiment must be true or false.

Response status codes

\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`	A `PATCH`, `PUT`, or `DELETE` request succeeded. The response contains the requested data.
`201`	A `POST` request succeeded. All v1 POST requests return `201`, including Fetch Paywall and Send Events. The v1 OpenAPI documentation lists these as `200`, but the API returns `201`.
`400`	Check the request fields and values. Examples include a missing user ID, a product that is not configured for the store, or an invalid `paywallSessionId`.
`403`	The secret key is missing or invalid, or Google returned a forbidden response.
`404`	The profile, placement, paywall, or store transaction was not found.
`410`	Google reports that the purchase is no longer available to query.
`500`, `502`, `503`, `504`	The server could not complete the request. See retry guidance below.

For 4xx errors, check the request and store response before trying again. For 5xx errors, wait before retrying and increase the delay if failures continue. No API rate limit is configured in the reviewed application code. Google can return other 4xx statuses; a Google rate-limit response is returned by this implementation as 500.

If Fetch Paywall fails, show your default paywall. Fetch it early and keep a saved response ready, so the user does not have to wait for retries. Retry failed events carefully because repeated views are counted separately. For Apple validation, a transaction whose purchase date is before the current UTC day is skipped even when the response is 201. Use the restore workflow for earlier purchases and check the returned access details.

Error responses

An error response contains ok: false, a readable message, and the HTTP status in status:

{\n  \"ok\": false,\n  \"message\": \"Profile not found with provided customerUserId user-123 appId: 4021\",\n  \"status\": 404\n}\n\n

Use status to decide how to handle an error. v1 has no separate error code. Log message for troubleshooting, but do not rely on its wording staying the same.

Most validation errors appear in one comma-separated message. Event errors use Event[].: , with semicolons between fields and commas between rules for the same field. Store error wording can vary. Google API error messages start with Google API error:.

Profile IDs and access details

Use a profile that belongs to the app identified by your secret key. v1 does not consistently check app ownership when a request supplies profileId. This affects profile updates, custom attributes, paywall and event requests, and purchase validation and restore. Where supported, customerUserId looks up the user within your app. If both IDs are sent, profileId generally takes priority; custom attributes can fall back to customerUserId when that profile ID is not found.

Profile responses include personal information. The accessLevels and subscriptions objects are built from the profile's single linked access record, using the access level ID and store product ID as keys. Both can be empty. nonSubscriptions is always {}. These objects are not a complete purchase history.

A successful response is not proof that new access was granted. Purchase processing can be skipped, and some product types do not update profile access. Check the returned access status and expiry before enabling paid features. The collection tests check response structure and request fields; they do not prove that a purchase was saved or new access was granted.

Migrating from V1 to V2

\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

Detail	v1: this collection	v2
URL	`app.botsi.com/api/v1/web-api/...`	`api.botsi.com/v2/...`
Your user ID	`customerUserId`	`appUserId`
User's IP address in the request	`ip`	`ipAddress`; the profile response still uses `ip`
Invalid authentication	`403`	`401`
Error fields	`ok`, `message`, `status`	`error`, `code`
Successful POST	`201`	`200`, or `201` when creating a profile
Fetch Paywall	Requires `store`; product fields depend on the store	Requires only `profileId` and `placementId`; products are grouped by store
Events	An array of supported event types; uses a token or separate fields	One `paywall_shown` object; uses a token
Custom attributes	Add one, add several, or update by `attrId`	Add several or update by key
Purchase validation	Apple requires `source`; both stores require `isExperiment` and `aiPricingModelId`. Returns the full profile.	These fields are optional. Returns selected fields without personal information and checks that `profileId` belongs to the app.
Other requests	Profile updates and purchase restores	Not available

","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"2219874","collectionId":"261346bd-8303-45f1-9c1e-e1b68f0e656b","publishedId":"2sBYAxRVaz","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-09-09T15:44:00.000Z"},"item":[{"name":"1. Profiles","item":[{"name":"Create a Profile","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test('Status is 201', () => pm.expect(pm.response.code).to.eql(201));","if (pm.response.code === 201) {"," const body = pm.response.json();"," pm.test('Response confirms success', () => pm.expect(body.ok).to.eql(true));",""," pm.test('Response includes the current profile and access objects', () => {"," pm.expect(body.data.profileId).to.be.a('string').and.not.empty;"," pm.expect(body.data).to.have.property('customerUserId');"," pm.expect(body.data.accessLevels).to.be.an('object');"," pm.expect(body.data.subscriptions).to.be.an('object');"," pm.expect(body.data.nonSubscriptions).to.deep.equal({});"," });",""," if (body.ok && body.data && typeof body.data.profileId === 'string') {"," pm.collectionVariables.set('profileId', body.data.profileId);"," if (body.data.customerUserId) pm.collectionVariables.set('customerUserId', body.data.customerUserId);"," }","}"],"id":"f5f22aa6-46f2-4df3-b93d-eefbb695a6b0"}}],"id":"d9948265-1a73-4fe8-83c2-bc414bae7ee9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"customerUserId\": \"user-123\",\n \"country\": \"US\",\n \"device\": \"iPhone 15 Pro Max\",\n \"os\": \"iOS 17.0\",\n \"platform\": \"ios\",\n \"appVersion\": \"1.0.0\",\n \"appBuild\": \"100\",\n \"locale\": \"en_US\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"ip\": \"203.0.113.7\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/profiles","description":"

Create a profile when the user first opens your app. AI Pricing, subscriptions, and paywall tracking all require a profile.

Required fields

country, device, os, platform, and appVersion.

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

Use a two-letter country code for country. Botsi also accepts uppercase three-letter codes it can convert. A three-letter code it cannot convert causes a 500 error in v1, rather than a 400 validation error.

Optional fields

customerUserId, locale, appBuild, advertisingId, ip, email, phone, gender, idfa, and username.

customerUserId links the profile to your own user record. Later requests can use it to find the profile.
ip must be a valid IPv4 or IPv6 address.
email must be a valid email address.

How it works

Sending the same customerUserId again returns the existing profile without changing its fields or recording another profile_created event.
Unknown fields are ignored. Use customerUserId and ip in v1. The v2 names appUserId and ipAddress are ignored, which can leave the profile without a customerUserId.
On Apple platforms, a device code such as iPhone16,2 is converted to its product name, iPhone 15 Pro Max. A readable device name is kept as sent.

Response

Returns the profile, including personal information. The accessLevels and subscriptions objects come from the profile's single linked access record. Both can be empty, and nonSubscriptions is always {}. They are not a complete purchase history. v2 returns fewer profile fields.

The collection script saves data.profileId as profileId for later requests.

Source: api/src/web-api/profiles/profiles.controller.ts, dto/create-profile.dto.ts, api/src/profiles/profile.mapper.ts

Update a user's profile. You can also use this request to read the profile and check the user's access after validating a purchase.

Required fields

customerUserId: a non-empty user ID.
appVersion: the current app version. Include it on every update, even if it has not changed.

Optional fields

profileId, country, device, os, platform, advertisingId, appBuild, email, phone, gender, idfa, username, locale, and ip.

Only the fields you send are explicitly updated. The profile update timestamp also changes.

Choosing the profile

Normally, Botsi finds the profile using customerUserId. If you also send profileId, Botsi uses that ID to find the profile and writes the supplied customerUserId to it. A mismatched pair changes the profile's user ID. Omit profileId unless you intend to do this.

A customerUserId from another app returns 404.

Reading a profile

v1 has no GET request for profiles. Sending customerUserId and the current appVersion returns the profile, but still performs an update and refreshes updatedDate. This is not a read-only request.

Response

Returns the full profile, including access levels, subscriptions, and custom attributes.

The accessLevels and subscriptions objects come from the profile's single linked access record. Both can be empty, and nonSubscriptions is always {}. They are not a complete purchase history.

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/src/web-api/profiles/profiles.controller.ts, dto/update-profile.dto.ts, api/src/profiles/profiles.service.ts (updateProfileByCustomerUserId)

Add one custom attribute to a profile. Attributes store extra information about the user and can help Botsi's AI Pricing models. To add several at once, use Add Custom Attributes (bulk).

Required fields

profileId or customerUserId.
custom: an object with key and value. Both must be strings.

How it works

If you send both user IDs, Botsi tries profileId first. If that profile is not found, it tries customerUserId. Sending neither returns 400.

Adding the same key twice creates two separate attributes with different IDs. To change an existing value, use Update Custom Attribute with the ID returned when the attribute was added.

Response

Returns the attribute with its new id. The collection script saves it as customAttributeId for the update request.

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/src/web-api/profiles/profiles.controller.ts, dto/create-custom-attribute-body.dto.ts, profiles.docs.ts

Add several custom attributes to a profile in one request.

Required fields

profileId or customerUserId.
custom: an array with at least one { \"key\": \"...\", \"value\": \"...\" } object. Both values must be strings.

An empty custom array returns 400.

Response

Returns the profile's complete custom array, including attributes added earlier. Each new attribute gets its own ID. Existing attributes with the same key are kept, so duplicate keys are possible.

The related v2 request, POST /v2/custom-attributes, returns only the attributes added by that request.

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/src/web-api/profiles/profiles.controller.ts, dto/create-custom-attributes-body.dto.ts, api/src/profiles/profiles.service.ts (addCustomAttributesToProfile)

Change an existing custom attribute's key, value, or both. For example, change a user's plan from premium to vip.

Required fields

profileId or customerUserId.
attrId: the attribute ID returned by an add request.
custom: an object containing both key and value.

Both the key and value are saved, so this request can also rename an attribute. v1 finds the attribute by ID; v2 uses its key.

Response

Returns 200 with { \"ok\": true, \"data\": { \"key\": \"...\", \"value\": \"...\", \"id\": \"...\" } }. The id is the supplied attrId. This response is returned even if no attribute matches that ID; in that case, no attribute value changes.

To confirm the update, read the profile with Update a Profile (PATCH /profiles) and check its custom attributes. v2 instead returns 404 for missing keys.

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/src/web-api/profiles/profiles.controller.ts, dto/update-custom-attribute-body.dto.ts, api/src/repositories/profiles/profiles-repository.service.ts (updateCustomAttr)

Create and update the profile Botsi keeps for each user. Add custom attributes to store more information about the user. Create a profile before using the other requests in this collection.

v1 uses customerUserId to identify your user. v2 calls this field appUserId. In v1, you can add one attribute, add several at once, or update an attribute by its ID.

Source: api/src/web-api/profiles/

\n","_postman_id":"ca587bbe-9d63-49e3-a7ca-7ca32f915627","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","name":"Botsi API v1 (Legacy)","type":"collection"}}},{"name":"2. Paywalls","item":[{"name":"Fetch Paywall","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test('Status is 201', () => pm.expect(pm.response.code).to.eql(201));","if (pm.response.code === 201) {"," const body = pm.response.json();"," pm.test('Response confirms success', () => pm.expect(body.ok).to.eql(true));",""," pm.test('Paywall includes the fields used by later requests', () => {"," pm.expect(body.data.id).to.be.a('number');"," pm.expect(body.data.paywallSessionId).to.be.a('string').and.not.empty;"," pm.expect(body.data.isExperiment).to.be.a('boolean');"," pm.expect(body.data.placementId).to.be.a('string');"," pm.expect(body.data.sourceProducts).to.be.an('array');"," const sent = JSON.parse(pm.variables.replaceIn(pm.request.body.raw));"," pm.expect(body.data.placementId).to.eql(sent.placementId);"," });"," pm.test('Paywall does not include both A/B and AI model IDs', () => {"," pm.expect(body.data.abTestId !== undefined && body.data.aiPricingModelId !== undefined).to.eql(false);"," });"," pm.test('Product fields match the v1 response format', () => {"," for (const product of body.data.sourceProducts) {"," pm.expect(product.botsiProductId).to.be.a('number');"," pm.expect(product.isConsumable).to.be.a('boolean');"," if (product.sourceProductId !== undefined && product.sourceProductId !== null) {"," pm.expect(product.sourceProductId).to.be.a('string');"," }"," pm.expect(product.sourcePoductId).to.eql(product.sourceProductId);"," }"," });"," if (body.ok && body.data && typeof body.data.paywallSessionId === 'string') {"," const data = body.data;"," pm.collectionVariables.set('paywallSessionId', data.paywallSessionId);"," pm.collectionVariables.set('paywallId', String(data.id));"," pm.collectionVariables.set('abTestId', String(data.abTestId === undefined ? 0 : data.abTestId));"," pm.collectionVariables.set('aiPricingModelId', String(data.aiPricingModelId === undefined ? 0 : data.aiPricingModelId));"," pm.collectionVariables.set('isExperiment', String(data.isExperiment));"," }","}"],"id":"69d0f3ce-9520-4c26-b015-aac5d349acb0"}}],"id":"a5d86632-a057-45b6-b47b-f11b7fc27182","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"\",\n \"profileId\": \"\",\n \"store\": \"app_store\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/paywalls","description":"

Get the paywall to display for a user at a placement. Create the user's profile first. Botsi selects a paywall you configured in the dashboard, including any A/B test or AI Pricing selection.

Required fields

placementId.
store: app_store, play_store, stripe, web2wave, or custom.
profileId or customerUserId. If both are sent, profileId is used. Sending neither returns 400.

store is required in v1 and determines which product fields are returned. It does not change the paywall selection. An A/B test with an unchanged test salt and variant configuration selects consistently for the same profile. AI traffic allocation and pricing decisions can change between requests. Save the details of the paywall actually shown and use those details when reporting its view and purchase.

Optional fields

languageLocale, deviceTypeModel, osVersion, and attributionSource.

Each must be a non-empty string when included. These fields are accepted but are not used by the v1 paywall selection code. AI Pricing reads device, OS, locale, country, and custom attributes from the stored profile. Update the profile to change those values.

Response fields

\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	Description
`id`	Paywall ID. Use it as `paywallId` in requests that send separate paywall fields.
`externalId`, `name`, `remoteConfigs`, `revision`	Paywall settings from the dashboard.
`abTestId`, `abTestName`	Included only for an A/B test selection.
`aiPricingModelId`	Included only for an AI Pricing selection. A response never includes both this ID and an A/B test ID.
`isExperiment`	Always included. `true` when the AI model selected the paywall; `false` for its default version and for other selection types.
`placementId`	The placement ID sent in the request.
`paywallSessionId`	Always included. A protected token that links later events to this selection. Save it and send it as returned.
`sourceProducts`	An array of products attached to the paywall. Its fields depend on `store`.

Product fields by store

Each product includes botsiProductId and isConsumable. sourceProductId and its misspelled duplicate, sourcePoductId, contain the store product ID when available. These ID fields can be null or absent. The spelling sourcePoductId reflects the API response.

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

Store	Additional fields
`app_store`	Uses the App Store product ID. Includes `promotionalOfferId` and `winBackOfferId`, which are null when not applicable. `appStoreOfferType` comes from this paywall's offer and may be absent.
`play_store`	`basePlanId`, `offerIds` (the offers this paywall may show), and `offerId` (this product's offer).
`stripe`, `web2wave`, `custom`	All three use the Stripe product ID, `sourcePriceId`, and `trialPeriodDays` in v1. Values depend on the product's Stripe settings; choosing `web2wave` or `custom` does not force them to null.

Only entries with no linked product are left out. A product without an ID for the requested store can still appear. Check that the returned ID is usable before offering the product for purchase.

When to call

Fetch the paywall early, such as just after creating the profile, and save the response before the user reaches the paywall. Response time varies with the pricing service and other dependencies. This API does not guarantee a 2-second response limit.

If the request fails with a 5xx error, show your default paywall instead of making the user wait for retries.

Saved variables

The collection script saves paywallSessionId, id as paywallId, abTestId, aiPricingModelId, and isExperiment for event and purchase requests. Missing A/B test and AI model IDs are saved as 0.

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/src/web-api/paywalls/paywalls.controller.ts, api/src/web-api/ai-pricing/dto/ai-pricing-model.dto.ts, api/src/sdk/paywalls/dto/response/botsi-paywall.dto.ts, api/web-api-ab-testing.md

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","name":"Botsi API v1 (Legacy)","type":"collection"}},"urlObject":{"path":["v1","web-api","paywalls"],"host":["https://app.botsi.com/api"],"query":[],"variable":[]}},"response":[{"id":"a8e16e5e-32a0-488b-8395-d28e79cdf0b8","name":"201 Created: AI Pricing paywall (App Store)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"ai-placement-id\",\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"store\": \"app_store\",\n \"languageLocale\": \"en-US\",\n \"deviceTypeModel\": \"iPhone 15 Pro Max\",\n \"osVersion\": \"iOS 17.0\",\n \"attributionSource\": \"organic\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/paywalls"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"aiPricingModelId\": 32,\n \"id\": 42,\n \"externalId\": \"paywall_premium_v2\",\n \"name\": \"Premium Paywall\",\n \"remoteConfigs\": null,\n \"revision\": 3,\n \"sourceProducts\": [\n {\n \"botsiProductId\": 1201,\n \"isConsumable\": false,\n \"sourceProductId\": \"com.example.premium.monthly\",\n \"sourcePoductId\": \"com.example.premium.monthly\",\n \"appStoreOfferType\": \"introductory\",\n \"promotionalOfferId\": null,\n \"winBackOfferId\": null\n }\n ],\n \"placementId\": \"ai-placement-id\",\n \"isExperiment\": true,\n \"paywallSessionId\": \"v1.eyJhIjo0MDIxLCJ3Ijo0MiwiaSI6MTc4ODk1NTIwMCwicCI6ImFpLXBsYWNlbWVudC1pZCIsIngiOjEsInUiOiIwMDcyMTAyYS1jMDBjLTRlYTUtOTI3MS0xYjZlOTc1ZjJkNjMiLCJtIjozMn0.6m9pLEKJ1BnbQ6AFCDgN-0BXc0o8n3n5yQrPOS-jaPQ\"\n }\n}"},{"id":"e1e6aa33-dd9f-4693-b3c0-7c9d8bdf2aa1","name":"201 Created: A/B test paywall (Google Play)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"onboarding_pricing_framing\",\n \"customerUserId\": \"user-123\",\n \"store\": \"play_store\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/paywalls"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"abTestId\": 77,\n \"abTestName\": \"Annual vs Lifetime Hero Framing\",\n \"id\": 905,\n \"externalId\": \"paywall_premium_v2\",\n \"name\": \"Variant B\",\n \"remoteConfigs\": null,\n \"revision\": 3,\n \"sourceProducts\": [\n {\n \"botsiProductId\": 1201,\n \"sourceProductId\": \"premium_monthly\",\n \"sourcePoductId\": \"premium_monthly\",\n \"basePlanId\": \"monthly-base\",\n \"offerIds\": [\n \"freetrial-7d\"\n ],\n \"offerId\": null,\n \"isConsumable\": false\n }\n ],\n \"placementId\": \"onboarding_pricing_framing\",\n \"isExperiment\": false,\n \"paywallSessionId\": \"v1.eyJhIjo0MDIxLCJ3Ijo5MDUsImkiOjE3ODg5NTUyMDAsInAiOiJvbmJvYXJkaW5nX3ByaWNpbmdfZnJhbWluZyIsIngiOjAsInUiOiIwMDcyMTAyYS1jMDBjLTRlYTUtOTI3MS0xYjZlOTc1ZjJkNjMiLCJ0Ijo3N30.N6_lkU9P1qSHPrYz4Kwhnekj1pQiFPB-dxgqUsrfB64\"\n }\n}"},{"id":"287182e0-c21c-474b-b11f-6735eea40349","name":"201 Created: Standard paywall (Stripe)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"ai-placement-id\",\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"store\": \"stripe\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/paywalls"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"id\": 42,\n \"externalId\": \"paywall_premium_v2\",\n \"name\": \"Premium Paywall\",\n \"remoteConfigs\": null,\n \"revision\": 3,\n \"sourceProducts\": [\n {\n \"botsiProductId\": 1201,\n \"sourceProductId\": \"prod_QxA1b2C3\",\n \"sourcePoductId\": \"prod_QxA1b2C3\",\n \"sourcePriceId\": \"price_1OaBcMonthly\",\n \"trialPeriodDays\": 7,\n \"isConsumable\": false\n }\n ],\n \"placementId\": \"ai-placement-id\",\n \"isExperiment\": false,\n \"paywallSessionId\": \"v1.eyJhIjo0MDIxLCJ3Ijo0MiwiaSI6MTc4ODk1NTIwMCwicCI6ImFpLXBsYWNlbWVudC1pZCIsIngiOjAsInUiOiIwMDcyMTAyYS1jMDBjLTRlYTUtOTI3MS0xYjZlOTc1ZjJkNjMifQ.x7XHorYc1uUdM0INp0EUtWFaBjg1kxvpEj7xn_r6UKM\"\n }\n}"},{"id":"e5e7b84f-0135-4e89-a458-bbd12b9b46e9","name":"404 Not Found: Placement missing or no paywall configured","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"main-onboarding\",\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"store\": \"app_store\",\n \"languageLocale\": \"en-US\",\n \"deviceTypeModel\": \"iPhone 15 Pro Max\",\n \"osVersion\": \"iOS 17.0\",\n \"attributionSource\": \"organic\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/paywalls"},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"No paywall found for the provided placement ID \\\"main-onboarding\\\" in app ID 4021. The audience does not have a paywall, AB test, or AI pricing model configured.\",\n \"status\": 404\n}"},{"id":"7702b819-cfc6-40d7-ab2a-7a4db835e654","name":"400 Bad Request: Missing user ID","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"ai-placement-id\",\n \"store\": \"app_store\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/paywalls"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"No profileId or customerUserId provided.\",\n \"status\": 400\n}"},{"id":"1a18760a-d623-4964-99c1-7e85e023b4b3","name":"500 Internal Server Error: Show your default paywall","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"ai-placement-id\",\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"store\": \"app_store\",\n \"languageLocale\": \"en-US\",\n \"deviceTypeModel\": \"iPhone 15 Pro Max\",\n \"osVersion\": \"iOS 17.0\",\n \"attributionSource\": \"organic\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/paywalls"},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"Server Error.\",\n \"status\": 500\n}"},{"id":"9d239bca-11c4-4322-9140-3c0c6352b597","name":"201 Created: Product has no App Store ID","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"placementId\": \"ai-placement-id\",\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"store\": \"app_store\",\n \"languageLocale\": \"en-US\",\n \"deviceTypeModel\": \"iPhone 15 Pro Max\",\n \"osVersion\": \"iOS 17.0\",\n \"attributionSource\": \"organic\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/paywalls"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"aiPricingModelId\": 32,\n \"id\": 42,\n \"externalId\": \"paywall_premium_v2\",\n \"name\": \"Premium Paywall\",\n \"remoteConfigs\": null,\n \"revision\": 3,\n \"sourceProducts\": [\n {\n \"botsiProductId\": 102,\n \"isConsumable\": false,\n \"sourceProductId\": null,\n \"sourcePoductId\": null,\n \"promotionalOfferId\": null,\n \"winBackOfferId\": null\n }\n ],\n \"placementId\": \"ai-placement-id\",\n \"isExperiment\": true,\n \"paywallSessionId\": \"v1.eyJhIjo0MDIxLCJ3Ijo0MiwiaSI6MTc4ODk1NTIwMCwicCI6ImFpLXBsYWNlbWVudC1pZCIsIngiOjEsInUiOiIwMDcyMTAyYS1jMDBjLTRlYTUtOTI3MS0xYjZlOTc1ZjJkNjMiLCJtIjozMn0.6m9pLEKJ1BnbQ6AFCDgN-0BXc0o8n3n5yQrPOS-jaPQ\"\n }\n}"}],"_postman_id":"a5d86632-a057-45b6-b47b-f11b7fc27182"}],"id":"32ec7670-7c7d-4a8c-8460-c3ed6949e039","description":"

Get the paywall selected for a user at a placement. It may be a standard paywall, an A/B test version, or an AI Pricing selection.

The response includes paywallSessionId. Send this value when reporting a paywall view so Botsi can link the view to the selected paywall.

Source: api/src/web-api/paywalls/, api/web-api-ab-testing.md

\n","_postman_id":"32ec7670-7c7d-4a8c-8460-c3ed6949e039","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","name":"Botsi API v1 (Legacy)","type":"collection"}}},{"name":"3. Events","item":[{"name":"Send Paywall Shown Event","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test('Status is 201', () => pm.expect(pm.response.code).to.eql(201));","if (pm.response.code === 201) {"," const body = pm.response.json();"," pm.test('Response confirms success', () => pm.expect(body.ok).to.eql(true));",""," pm.test('Event response contains no data field', () => pm.expect(body).to.not.have.property('data'));",""," pm.test('The view request includes a session token', () => {"," const sent = JSON.parse(pm.variables.replaceIn(pm.request.body.raw))[0];"," pm.expect(sent.paywallSessionId).to.be.a('string').and.not.empty;"," });","}"],"id":"0ddcae04-77f0-4c74-ba88-34fd637d38d5"}}],"id":"22a2d099-5427-42b7-a86e-a63990bcc222","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"profileId\": \"\",\n \"eventType\": \"paywall_shown\",\n \"paywallSessionId\": \"\"\n }\n]","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/events","description":"

Send this event immediately after the paywall appears. Botsi uses it to count views and compare them with purchases. Fetching a paywall does not count as a view.

Required fields

Each event needs just three fields when using a token:

profileId or customerUserId.
eventType: paywall_shown.
paywallSessionId: the value returned by Fetch Paywall.

The token supplies paywallId, placementId, abTestId, aiPricingModelId, and isExperiment, so you do not need to send those fields separately.

Token rules

For fields present in the token, Botsi saves the token's values and records any mismatch with separately sent values. Separate values for fields absent from the token are not cleared. Send only the token and required event fields to avoid carrying unrelated test details.
An invalid token, a token whose signature cannot be verified, or a token from another app returns 400. No events are saved. A token signed for another app normally returns the generic invalid-token message because the signature check fails first. An outdated abTestId sent as a separate field is instead accepted as sent.
For paywall_shown, tokens are valid for 24 hours after Fetch Paywall creates them by default. After that, fetch a new paywall before reporting the view. Other event types accept tokens of any age.

Send one event per view. Sending the same event twice counts two views.

Sending events

Send a JSON array of event objects. An empty array or a single object returns 400.
Every event needs profileId or customerUserId. Use the same identifier field and value throughout the request. The API compares profileId when present, otherwise customerUserId; it does not resolve each event separately before comparing. Different identifier values return 400; an unknown customerUserId returns 404.
Each event is checked separately. Field errors use Event[<index>].<field>: <rule>.
timestamp is optional. Use milliseconds since January 1, 1970 (Unix time). If omitted, Botsi uses the current time.
Botsi gets country and store from the profile, not the event body.
Events record analytics only. To grant or update a user's access, validate the store purchase using a request in folder 4.

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/src/web-api/events/events.controller.ts, events.service.ts, pipes/validate-events-array.pipe.ts, api/src/web-api/paywall-session/paywall-session-resolver.service.ts, api/web-api-events-confluence.md

Record a paywall view by sending the paywall and test fields separately. This older method is still supported but is deprecated. Use Send Paywall Shown Event with paywallSessionId for new integrations.

Copy the values from Fetch Paywall carefully. Incorrect values are generally saved as sent and can link results to the wrong test.

Required fields

Without a token, every event type requires:

profileId or customerUserId.
eventType.
aiPricingModelId: a number. Use 0 if the response had no AI model ID.
isExperiment: true or false. Use false if the response had no AI Pricing selection.

Recommended tracking fields

For correct paywall tracking, also send paywallId and placementId on paywall_shown. The API accepts events without these fields, but the view may not be linked correctly. Include abTestId when Fetch Paywall returns an A/B test selection.

Keep , , , and outside quotation marks in the request body. The first three must be numbers; the last must be true or false.

Automatic correction

For paywall_shown, Botsi changes isExperiment: false to true if its saved paywall selection shows that the AI model was used. No other fields are corrected, and this correction does not change the response.

Sending events

Send a JSON array of event objects. An empty array or a single object returns 400.
Every event needs profileId or customerUserId. Use the same identifier field and value throughout the request. The API compares profileId when present, otherwise customerUserId; it does not resolve each event separately before comparing. Different identifier values return 400; an unknown customerUserId returns 404.
Each event is checked separately. Field errors use Event[<index>].<field>: <rule>.
timestamp is optional. Use milliseconds since January 1, 1970 (Unix time). If omitted, Botsi uses the current time.
Botsi gets country and store from the profile, not the event body.
Events record analytics only. To grant or update a user's access, validate the store purchase using a request in folder 4.

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/web-api-ab-testing.md (Appendix: the explicit-field loop), api/src/analytics/types/events/create-profile-event.dto.ts

Record paywall views so Botsi can compare views with purchases and improve AI Pricing selections.

v1 accepts an array of events for one user in each request. v2 accepts one paywall_shown object.

Source: api/src/web-api/events/, api/web-api-events-confluence.md

\n","_postman_id":"73c53e43-5f81-478c-af7c-23300d5d3d59","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","name":"Botsi API v1 (Legacy)","type":"collection"}}},{"name":"4. Validate Purchases","item":[{"name":"Validate Apple Store Purchase","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test('Status is 201', () => pm.expect(pm.response.code).to.eql(201));","if (pm.response.code === 201) {"," const body = pm.response.json();"," pm.test('Response confirms success', () => pm.expect(body.ok).to.eql(true));",""," pm.test('Response includes the current profile and access objects', () => {"," pm.expect(body.data.profileId).to.be.a('string').and.not.empty;"," pm.expect(body.data).to.have.property('customerUserId');"," pm.expect(body.data.accessLevels).to.be.an('object');"," pm.expect(body.data.subscriptions).to.be.an('object');"," pm.expect(body.data.nonSubscriptions).to.deep.equal({});"," });",""," pm.test('Submitted purchase tracking fields have the expected types', () => {"," const sent = JSON.parse(pm.variables.replaceIn(pm.request.body.raw));"," pm.expect(sent.aiPricingModelId).to.be.a('number');"," pm.expect(sent.isExperiment).to.be.a('boolean');"," for (const field of ['paywallId', 'abTestId']) {"," if (sent[field] !== undefined) pm.expect(sent[field]).to.be.a('number');"," }"," });"," // These checks do not prove that the purchase was processed or access was granted.",""," pm.test('Apple purchase source is supported', () => {"," const sent = JSON.parse(pm.variables.replaceIn(pm.request.body.raw));"," pm.expect(sent.source).to.be.oneOf(['purchasing', 'restore', 'observing']);"," });","}"],"id":"0b40eee8-8369-41a8-b891-8a06b37442ce"}}],"id":"364c4122-2857-4c9c-9db1-4598b95c453f","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 \"productId\": \"\",\n \"transactionId\": \"\",\n \"originalTransactionId\": \"\",\n \"source\": \"purchasing\",\n \"environment\": \"production\",\n \"isSubscription\": true,\n \"placementId\": \"\",\n \"paywallId\": ,\n \"abTestId\": ,\n \"isExperiment\": ,\n \"aiPricingModelId\": \n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/apple-store/validate","description":"

Validate a new App Store purchase promptly after completion. When the transaction is processed, Botsi records the purchase and updates access for the period confirmed by Apple. Some requests return successfully without processing the purchase; see Purchase handling below.

Required fields

profileId or customerUserId, plus productId, transactionId, originalTransactionId, source, isExperiment, and aiPricingModelId.

\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	Type	Description
`productId`	string	The product ID from the purchase. It must match the App Store Product ID configured in Botsi.
`transactionId`	string	The transaction ID from StoreKit.
`originalTransactionId`	string	The original transaction ID from StoreKit.
`source`	string	`purchasing`, `restore`, or `observing`. Use `purchasing` for a new purchase.
`isExperiment`	boolean	The value returned by Fetch Paywall.
`aiPricingModelId`	number	The model ID returned by Fetch Paywall, or `0`.

Optional fields

\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	Type	Description
`placementId`	string	The placement used to fetch the paywall.
`paywallId`	number	`data.id` from Fetch Paywall.
`abTestId`	number	`data.abTestId` from an A/B test selection.
`isSubscription`	boolean	Whether the purchase is a subscription.
`environment`	string	Set `production` for production purchases. If omitted, Botsi tries both Apple purchase environments.

Other optional fields: sourceProductId, originalPrice, discountPrice, priceLocale, storeCountry, promotionalOfferId, and offer.

If you include offer, its fields are:

\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	Accepted values
`periodUnit`	`day`, `week`, `month`, `year`, `unknown`
`numberOfUnits`	The number of period units.
`type`	`pay_as_you_go`, `pay_up_front`, `free_trial`, `unknown`
`category`	`introductory`, `promotional`, `code`, `win_back`, `unknown`

Purchase handling

source: restore skips purchase processing and returns 201 with the current profile after settings checks. Request logging still occurs. Use Restore Apple Store Purchases to restore earlier purchases.
Processing is also skipped when the transaction is already recorded, a processing lock is held, or Apple's transaction purchase date is not the current UTC date. These paths still return 201 with the current profile.
source: purchasing determines how Botsi looks for an already recorded transaction. Revalidating a recorded transaction does not create another event.
Do not treat 201 alone as proof of new access. Check the returned access status and expiry. For earlier purchases, use the restore workflow.

Finding the StoreKit IDs

StoreKit: get the transaction IDs from SKPaymentTransaction. The product ID is SKPaymentTransaction.payment.productIdentifier.
StoreKit 2: get all three IDs from the Transaction object.

Linking the purchase to a paywall

Purchase validation does not accept paywallSessionId. Copy paywallId, isExperiment, and aiPricingModelId from Fetch Paywall, and include abTestId for an A/B test selection.

v1 requires isExperiment and aiPricingModelId. If there was no AI Pricing selection, send false and 0, respectively. These fields are optional in v2.

Keep , , , and outside quotation marks in the request body. The first three must be numbers; the last must be true or false.

Response

Returns the current profile, including personal information. A successful response can contain unchanged access details. The accessLevels and subscriptions objects come from the profile's single linked access record. Both can be empty, and nonSubscriptions is always {}. They are not a complete purchase history. Check access status and expiry before enabling paid features. v2 returns fewer fields.

Prefer customerUserId when available. That lookup is limited to your app. Unlike v2, v1 does not check that a supplied profileId belongs to your app.

Source: api/src/web-api/purchases/purchases.controller.ts, dto/validate-token.dto.ts, api/src/sdk/purchases/dto/validate-token.dto.ts, apple-purchase.service.ts

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","name":"Botsi API v1 (Legacy)","type":"collection"}},"urlObject":{"path":["v1","web-api","purchases","apple-store","validate"],"host":["https://app.botsi.com/api"],"query":[],"variable":[]}},"response":[{"id":"6b393e42-d7d3-4447-99b5-0fd78e2e90c3","name":"201 Created: Purchase access granted","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"productId\": \"com.example.premium.monthly\",\n \"transactionId\": \"2000000871590381\",\n \"originalTransactionId\": \"2000000261699248\",\n \"source\": \"purchasing\",\n \"environment\": \"production\",\n \"isSubscription\": true,\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/apple-store/validate"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"createdDate\": \"2026-09-09T10:30:00.000Z\",\n \"linkedProfileIds\": null,\n \"state\": \"subscribed\",\n \"customerUserId\": \"user-123\",\n \"migrationProfileId\": null,\n \"country\": \"US\",\n \"device\": \"iPhone 15 Pro Max\",\n \"os\": \"iOS 17.0\",\n \"platform\": \"ios\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"appBuild\": \"100\",\n \"appVersion\": \"1.0.0\",\n \"botsiSdkVersion\": null,\n \"custom\": [],\n \"email\": null,\n \"phone\": null,\n \"gender\": null,\n \"idfa\": null,\n \"username\": null,\n \"locale\": \"en_US\",\n \"ip\": \"203.0.113.7\",\n \"createdAt\": null,\n \"ipCountry\": null,\n \"appleConsumptionConsent\": null,\n \"birthday\": null,\n \"age\": null,\n \"totalRevenueUsd\": 9.99,\n \"updatedDate\": \"2026-09-09T10:30:00.000Z\",\n \"accessLevels\": {\n \"premium\": {\n \"id\": 5150,\n \"createdDate\": \"2026-09-09T10:31:00.000Z\",\n \"isActive\": true,\n \"sourceProductId\": \"com.example.premium.monthly\",\n \"sourceBasePlanId\": null,\n \"sourcePurchaseToken\": null,\n \"store\": \"app_store\",\n \"activatedAt\": null,\n \"isLifetime\": false,\n \"isRefund\": false,\n \"willRenew\": true,\n \"isInGracePeriod\": false,\n \"cancellationReason\": null,\n \"offerId\": null,\n \"startsAt\": null,\n \"renewedAt\": \"2026-09-09T10:31:00.000Z\",\n \"expiresAt\": \"2026-10-09\",\n \"revokedAt\": null,\n \"activeIntroductoryOfferType\": null,\n \"activePromotionalOfferType\": null,\n \"activePromotionalOfferId\": null,\n \"unsubscribedAt\": null,\n \"billingIssueDetectedAt\": null\n }\n },\n \"subscriptions\": {\n \"com.example.premium.monthly\": {\n \"id\": 5150,\n \"createdDate\": \"2026-09-09T10:31:00.000Z\",\n \"isActive\": true,\n \"sourceProductId\": \"com.example.premium.monthly\",\n \"sourceBasePlanId\": null,\n \"sourcePurchaseToken\": null,\n \"store\": \"app_store\",\n \"activatedAt\": null,\n \"isLifetime\": false,\n \"isRefund\": false,\n \"willRenew\": true,\n \"isInGracePeriod\": false,\n \"cancellationReason\": null,\n \"offerId\": null,\n \"startsAt\": null,\n \"renewedAt\": \"2026-09-09T10:31:00.000Z\",\n \"expiresAt\": \"2026-10-09\",\n \"revokedAt\": null,\n \"activeIntroductoryOfferType\": null,\n \"activePromotionalOfferType\": null,\n \"activePromotionalOfferId\": null,\n \"unsubscribedAt\": null,\n \"billingIssueDetectedAt\": null\n }\n },\n \"nonSubscriptions\": {}\n }\n}"},{"id":"507b5c04-2526-4e96-86fa-9b66251af12a","name":"404 Not Found: Transaction not found by Apple","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"productId\": \"com.example.premium.monthly\",\n \"transactionId\": \"2000000871590381\",\n \"originalTransactionId\": \"2000000261699248\",\n \"source\": \"purchasing\",\n \"environment\": \"production\",\n \"isSubscription\": true,\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/apple-store/validate"},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"Transaction not found. originalTransactionId: 2000000261699248\",\n \"status\": 404\n}"},{"id":"2faf7c3d-8240-4282-9158-91289bb5197d","name":"400 Bad Request: App Store connection not configured","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"productId\": \"com.example.premium.monthly\",\n \"transactionId\": \"2000000871590381\",\n \"originalTransactionId\": \"2000000261699248\",\n \"source\": \"purchasing\",\n \"environment\": \"production\",\n \"isSubscription\": true,\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/apple-store/validate"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"No ios settings found\",\n \"status\": 400\n}"},{"id":"d6545b71-58ca-4666-b479-6306296e388b","name":"400 Bad Request: Missing required v1 fields","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"productId\": \"com.example.premium.monthly\",\n \"transactionId\": \"2000000871590381\",\n \"originalTransactionId\": \"2000000261699248\"\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/apple-store/validate"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"source must be one of the following values: restore, purchasing, observing, isExperiment must be a boolean value, isExperiment should not be null or undefined, aiPricingModelId must be a number conforming to the specified constraints, aiPricingModelId should not be null or undefined\",\n \"status\": 400\n}"},{"id":"8ed841f2-e81b-4966-b7da-1673baf0080f","name":"201 Created: Earlier purchase skipped; current profile returned","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"productId\": \"com.example.premium.monthly\",\n \"transactionId\": \"2000000000000001\",\n \"originalTransactionId\": \"2000000000000001\",\n \"source\": \"purchasing\",\n \"environment\": \"production\",\n \"isSubscription\": true,\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/apple-store/validate"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"createdDate\": \"2026-09-09T10:30:00.000Z\",\n \"linkedProfileIds\": null,\n \"state\": \"never-subscribed\",\n \"customerUserId\": \"user-123\",\n \"migrationProfileId\": null,\n \"country\": \"US\",\n \"device\": \"iPhone 15 Pro Max\",\n \"os\": \"iOS 17.0\",\n \"platform\": \"ios\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"appBuild\": \"100\",\n \"appVersion\": \"1.0.0\",\n \"botsiSdkVersion\": null,\n \"custom\": [],\n \"email\": null,\n \"phone\": null,\n \"gender\": null,\n \"idfa\": null,\n \"username\": null,\n \"locale\": \"en_US\",\n \"ip\": \"203.0.113.7\",\n \"createdAt\": null,\n \"ipCountry\": null,\n \"appleConsumptionConsent\": null,\n \"birthday\": null,\n \"age\": null,\n \"totalRevenueUsd\": 0,\n \"updatedDate\": \"2026-09-09T10:30:00.000Z\",\n \"accessLevels\": {},\n \"subscriptions\": {},\n \"nonSubscriptions\": {}\n }\n}"}],"_postman_id":"364c4122-2857-4c9c-9db1-4598b95c453f"},{"name":"Validate Google Play Purchase: Subscription","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test('Status is 201', () => pm.expect(pm.response.code).to.eql(201));","if (pm.response.code === 201) {"," const body = pm.response.json();"," pm.test('Response confirms success', () => pm.expect(body.ok).to.eql(true));",""," pm.test('Response includes the current profile and access objects', () => {"," pm.expect(body.data.profileId).to.be.a('string').and.not.empty;"," pm.expect(body.data).to.have.property('customerUserId');"," pm.expect(body.data.accessLevels).to.be.an('object');"," pm.expect(body.data.subscriptions).to.be.an('object');"," pm.expect(body.data.nonSubscriptions).to.deep.equal({});"," });",""," pm.test('Submitted purchase tracking fields have the expected types', () => {"," const sent = JSON.parse(pm.variables.replaceIn(pm.request.body.raw));"," pm.expect(sent.aiPricingModelId).to.be.a('number');"," pm.expect(sent.isExperiment).to.be.a('boolean');"," for (const field of ['paywallId', 'abTestId']) {"," if (sent[field] !== undefined) pm.expect(sent[field]).to.be.a('number');"," }"," });"," // These checks do not prove that the purchase was processed or access was granted.","}"],"id":"78837d79-2257-4309-aa65-be6a38c5d8cc"}}],"id":"cd70d68a-ad02-4cc5-b0af-55fc34255786","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 \"token\": \"\",\n \"productId\": \"\",\n \"environment\": \"production\",\n \"placementId\": \"\",\n \"paywallId\": ,\n \"abTestId\": ,\n \"isExperiment\": ,\n \"aiPricingModelId\": ,\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 9990000,\n \"currencyCode\": \"USD\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/play-store/validate","description":"

Validate a completed Google Play subscription. When the purchase is processed, Botsi checks the token with Google, records the purchase, and updates subscription access. A request skipped because it is already processing can still return the current profile.

Required fields

profileId or customerUserId, plus productId, token, isExperiment, and aiPricingModelId.

\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	Type	Description
`token`	string	The purchase token from `getPurchaseToken()` in the Google Play Billing Library.
`productId`	string	The Play Store Product ID configured in Botsi. This is `sourceProductId` in a Fetch Paywall response for `play_store`.
`isExperiment`	boolean	The value returned by Fetch Paywall.
`aiPricingModelId`	number	The model ID returned by Fetch Paywall, or `0`.

Optional fields

\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

Field	Type	Description
`placementId`	string	The placement used to fetch the paywall.
`paywallId`	number	`data.id` from Fetch Paywall.
`abTestId`	number	`data.abTestId` from an A/B test selection.
`isSubscription`	boolean	Whether the purchase is a subscription.
`environment`	string	Set `production` for production purchases. See the environment rule below.
`subscriptionOfferDetails`	object	The purchased subscription offer from `ProductDetails.getSubscriptionOfferDetails()`.
`oneTimePurchaseOfferDetails`	object	Required during processing of a one-time purchase; use the One-Time Purchase request for that workflow.

Send the offer object that matches the purchase. The input validator allows both objects or neither; it does not enforce a one-object rule. One-time purchase processing still requires price details. For subscriptions, use the purchased base plan and offer returned by Google Play, rather than assuming the first offer is the right one.

Environment

Set environment: production explicitly for production purchases. The API has no default for this field. In a production store configuration, omitting it causes the revenue event to be skipped, even if access is updated.

Offer details

For subscriptionOfferDetails, include basePlanId (string), offerId (string, if the product has a store offer), and a pricingPhases array.

Each pricing phase contains:

\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	Type	Description
`priceAmountMicros`	number	Price in millionths of a currency unit. For example, `9990000` is USD 9.99.
`currencyCode`	string	A three-letter currency code in ISO 4217 format, such as `USD`.
`billingPeriod`	string	A billing period in ISO 8601 format, such as `P1M` for one month.
`recurrenceMode`	number	The Google Play value describing how the phase repeats.
`billingCycleCount`	number	The number of billing cycles in the phase.

For oneTimePurchaseOfferDetails, include priceAmountMicros (number) and currencyCode (ISO 4217 string).

Linking the purchase to a paywall

Purchase validation does not accept paywallSessionId. Copy paywallId, isExperiment, and aiPricingModelId from Fetch Paywall, and include abTestId for an A/B test selection.

v1 requires isExperiment and aiPricingModelId. If there was no AI Pricing selection, send false and 0, respectively. These fields are optional in v2.

Keep , , , and outside quotation marks in the request body. The first three must be numbers; the last must be true or false.

Response

Prefer customerUserId when available. That lookup is limited to your app. Unlike v2, v1 does not check that a supplied profileId belongs to your app.

Source: api/src/web-api/purchases/purchases.controller.ts, dto/validate-token.dto.ts, api/src/sdk/purchases/dto/validate-token.dto.ts, google-purchase.service.ts

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","name":"Botsi API v1 (Legacy)","type":"collection"}},"urlObject":{"path":["v1","web-api","purchases","play-store","validate"],"host":["https://app.botsi.com/api"],"query":[],"variable":[]}},"response":[{"id":"a3e6dd32-99d0-4058-9a1b-1dc7268fac08","name":"201 Created: Purchase access granted","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"token\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"productId\": \"premium_monthly\",\n \"environment\": \"production\",\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32,\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"monthly-base\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 9990000,\n \"currencyCode\": \"USD\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/play-store/validate"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": true,\n \"data\": {\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"createdDate\": \"2026-09-09T10:30:00.000Z\",\n \"linkedProfileIds\": null,\n \"state\": \"subscribed\",\n \"customerUserId\": \"user-123\",\n \"migrationProfileId\": null,\n \"country\": \"US\",\n \"device\": \"Pixel 9\",\n \"os\": \"Android 15\",\n \"platform\": \"android\",\n \"advertisingId\": \"6D92078A-8246-4BA4-AE5B-76104861E7DC\",\n \"appBuild\": \"100\",\n \"appVersion\": \"1.0.0\",\n \"botsiSdkVersion\": null,\n \"custom\": [],\n \"email\": null,\n \"phone\": null,\n \"gender\": null,\n \"idfa\": null,\n \"username\": null,\n \"locale\": \"en_US\",\n \"ip\": \"203.0.113.7\",\n \"createdAt\": null,\n \"ipCountry\": null,\n \"appleConsumptionConsent\": null,\n \"birthday\": null,\n \"age\": null,\n \"totalRevenueUsd\": 9.99,\n \"updatedDate\": \"2026-09-09T10:30:00.000Z\",\n \"accessLevels\": {\n \"premium\": {\n \"id\": 5150,\n \"createdDate\": \"2026-09-09T10:31:00.000Z\",\n \"isActive\": true,\n \"sourceProductId\": \"premium_monthly\",\n \"sourceBasePlanId\": \"monthly-base\",\n \"sourcePurchaseToken\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"store\": \"play_store\",\n \"activatedAt\": null,\n \"isLifetime\": false,\n \"isRefund\": false,\n \"willRenew\": true,\n \"isInGracePeriod\": false,\n \"cancellationReason\": null,\n \"offerId\": null,\n \"startsAt\": null,\n \"renewedAt\": \"2026-09-09T10:31:00.000Z\",\n \"expiresAt\": \"2026-10-09\",\n \"revokedAt\": null,\n \"activeIntroductoryOfferType\": null,\n \"activePromotionalOfferType\": null,\n \"activePromotionalOfferId\": null,\n \"unsubscribedAt\": null,\n \"billingIssueDetectedAt\": null\n }\n },\n \"subscriptions\": {\n \"premium_monthly\": {\n \"id\": 5150,\n \"createdDate\": \"2026-09-09T10:31:00.000Z\",\n \"isActive\": true,\n \"sourceProductId\": \"premium_monthly\",\n \"sourceBasePlanId\": \"monthly-base\",\n \"sourcePurchaseToken\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"store\": \"play_store\",\n \"activatedAt\": null,\n \"isLifetime\": false,\n \"isRefund\": false,\n \"willRenew\": true,\n \"isInGracePeriod\": false,\n \"cancellationReason\": null,\n \"offerId\": null,\n \"startsAt\": null,\n \"renewedAt\": \"2026-09-09T10:31:00.000Z\",\n \"expiresAt\": \"2026-10-09\",\n \"revokedAt\": null,\n \"activeIntroductoryOfferType\": null,\n \"activePromotionalOfferType\": null,\n \"activePromotionalOfferId\": null,\n \"unsubscribedAt\": null,\n \"billingIssueDetectedAt\": null\n }\n },\n \"nonSubscriptions\": {}\n }\n}"},{"id":"8f42c6ab-126a-45c1-98b9-4ea64de82105","name":"403 Forbidden: Google rejected the purchase token","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"token\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"productId\": \"premium_monthly\",\n \"environment\": \"production\",\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32,\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"monthly-base\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 9990000,\n \"currencyCode\": \"USD\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/play-store/validate"},"status":"Forbidden","code":403,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"Google API error: The purchase token was not found.\",\n \"status\": 403\n}"},{"id":"f771ae9d-ba8f-48bb-8772-215d84d58e9f","name":"400 Bad Request: productId not configured for Google Play","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"token\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"productId\": \"premium_monthly\",\n \"environment\": \"production\",\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32,\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"monthly-base\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 9990000,\n \"currencyCode\": \"USD\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/play-store/validate"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"No product found for app: 4021. productId: premium_monthly\",\n \"status\": 400\n}"},{"id":"c05f8008-4c78-4b29-a865-65a7b257e70f","name":"400 Bad Request: Google Play connection not configured","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"token\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"productId\": \"premium_monthly\",\n \"environment\": \"production\",\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32,\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"monthly-base\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 9990000,\n \"currencyCode\": \"USD\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/play-store/validate"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"Android settings doesn't have packageName\",\n \"status\": 400\n}"},{"id":"e8d51496-485b-401d-8271-2a5bd977db86","name":"410 Gone: Purchase no longer available to query","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"profileId\": \"0072102a-c00c-4ea5-9271-1b6e975f2d63\",\n \"token\": \"algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5\",\n \"productId\": \"premium_monthly\",\n \"environment\": \"production\",\n \"placementId\": \"ai-placement-id\",\n \"paywallId\": 42,\n \"abTestId\": 0,\n \"isExperiment\": true,\n \"aiPricingModelId\": 32,\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"monthly-base\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 9990000,\n \"currencyCode\": \"USD\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/play-store/validate"},"status":"Gone","code":410,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"{\n \"ok\": false,\n \"message\": \"Google API error: The subscription purchase is no longer available for query.\",\n \"status\": 410\n}"}],"_postman_id":"cd70d68a-ad02-4cc5-b0af-55fc34255786"},{"name":"Validate Google Play Purchase: Subscription with Free Trial","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test('Status is 201', () => pm.expect(pm.response.code).to.eql(201));","if (pm.response.code === 201) {"," const body = pm.response.json();"," pm.test('Response confirms success', () => pm.expect(body.ok).to.eql(true));",""," pm.test('Response includes the current profile and access objects', () => {"," pm.expect(body.data.profileId).to.be.a('string').and.not.empty;"," pm.expect(body.data).to.have.property('customerUserId');"," pm.expect(body.data.accessLevels).to.be.an('object');"," pm.expect(body.data.subscriptions).to.be.an('object');"," pm.expect(body.data.nonSubscriptions).to.deep.equal({});"," });",""," pm.test('Submitted purchase tracking fields have the expected types', () => {"," const sent = JSON.parse(pm.variables.replaceIn(pm.request.body.raw));"," pm.expect(sent.aiPricingModelId).to.be.a('number');"," pm.expect(sent.isExperiment).to.be.a('boolean');"," for (const field of ['paywallId', 'abTestId']) {"," if (sent[field] !== undefined) pm.expect(sent[field]).to.be.a('number');"," }"," });"," // These checks do not prove that the purchase was processed or access was granted.",""," pm.test('Free trial request includes a zero-price phase', () => {"," const sent = JSON.parse(pm.variables.replaceIn(pm.request.body.raw));"," pm.expect(sent.subscriptionOfferDetails.pricingPhases.some(phase => phase.priceAmountMicros === 0)).to.eql(true);"," });","}"],"id":"2e4b3b88-d5c7-41d9-952c-16e868ddebe5"}}],"id":"7d4b0b58-648c-4820-a1e0-8423d12e8789","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 \"token\": \"\",\n \"productId\": \"\",\n \"environment\": \"production\",\n \"placementId\": \"\",\n \"paywallId\": ,\n \"abTestId\": ,\n \"isExperiment\": ,\n \"aiPricingModelId\": ,\n \"subscriptionOfferDetails\": {\n \"basePlanId\": \"\",\n \"offerId\": \"\",\n \"pricingPhases\": [\n {\n \"priceAmountMicros\": 0,\n \"currencyCode\": \"USD\",\n \"billingPeriod\": \"P1W\",\n \"recurrenceMode\": 2,\n \"billingCycleCount\": 1\n },\n {\n \"priceAmountMicros\": 9990000,\n \"currencyCode\": \"USD\",\n \"billingPeriod\": \"P1M\",\n \"recurrenceMode\": 1,\n \"billingCycleCount\": 0\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://app.botsi.com/api/v1/web-api/purchases/play-store/validate","description":"

Validate a Google Play subscription with a free trial. This uses the same endpoint and required fields as Validate Google Play Purchase: Subscription.

Free trial details

Include a pricingPhases entry with priceAmountMicros: 0, along with its billingPeriod, recurrenceMode, and billingCycleCount. Botsi uses this zero-price phase to identify the free trial. Without it, the purchase is recorded as a paid subscription and revenue may be overstated.

Place the free trial phase first, followed by the paid phase that starts when the trial ends.

The example uses:

recurrenceMode: 2 and billingCycleCount: 1 for the trial phase, which runs once.
recurrenceMode: 1 for the paid phase, which continues to repeat.

Use the values from the ProductDetails object returned to your app by Google Play.

Set environment to production for production purchases. See Validate Google Play Purchase: Subscription for the full field list and environment rules.

Linking the purchase to a paywall

Purchase validation does not accept paywallSessionId. Copy paywallId, isExperiment, and aiPricingModelId from Fetch Paywall, and include abTestId for an A/B test selection.

v1 requires isExperiment and aiPricingModelId. If there was no AI Pricing selection, send false and 0, respectively. These fields are optional in v2.

Keep , , , and outside quotation marks in the request body. The first three must be numbers; the last must be true or false.

Response

Prefer customerUserId when available. That lookup is limited to your app. Unlike v2, v1 does not check that a supplied profileId belongs to your app.

Source: api/src/sdk/purchases/google-purchase.service.ts

Validate a one-time Google Play purchase. This uses the same endpoint and common required fields as Validate Google Play Purchase: Subscription, plus the price details below.

One-time purchase details

Include oneTimePurchaseOfferDetails with a non-empty currencyCode and a nonzero priceAmountMicros. If either is missing, or the price is zero, processing returns 400. Send this object for a one-time purchase. The input validator does not reject a body merely because it also contains subscriptionOfferDetails.

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

Field	Description
`priceAmountMicros`	Price in millionths of a currency unit. For example, `29990000` is USD 29.99.
`currencyCode`	A three-letter currency code in ISO 4217 format, such as `USD`.

Botsi uses the product's configured period, such as consumable, lifetime, or non-subscription, to decide whether the purchase is a one-time purchase. The offer details object alone does not determine the purchase type.

Set environment to production for production purchases. See Validate Google Play Purchase: Subscription for the full field list and environment rules.

Linking the purchase to a paywall

Purchase validation does not accept paywallSessionId. Copy paywallId, isExperiment, and aiPricingModelId from Fetch Paywall, and include abTestId for an A/B test selection.

v1 requires isExperiment and aiPricingModelId. If there was no AI Pricing selection, send false and 0, respectively. These fields are optional in v2.

Keep , , , and outside quotation marks in the request body. The first three must be numbers; the last must be true or false.

Response

Prefer customerUserId when available. That lookup is limited to your app. Unlike v2, v1 does not check that a supplied profileId belongs to your app.

Access behavior

Lifetime products update the profile's access. Other one-time products record the purchase without this access update. A 201 response does not by itself confirm that paid access was granted.

Source: api/src/sdk/purchases/google-purchase.service.ts

Restore a user's App Store purchases after a reinstall or a move to a new device. Botsi reads the transactions from the receipt and restores the associated access to the profile.

Required fields

profileId or customerUserId.
receipt: the full app receipt encoded as base64. Set it in appleReceipt. This v1 request parses an app receipt and does not accept a StoreKit 2 transaction ID in this field.

Optional fields

storeCountry, appVersion, appBuild, device, locale, os, and botsiSdkVersion.

App setup

Your app must have a public key configured, the same key used by the mobile SDK. If it does not, the request returns 400 with App has no public key. Continue to use the secret key in this request's Authorization header.

Response

Returns the current profile after restore processing. Check the access details to confirm the result. The accessLevels and subscriptions objects come from the profile's single linked access record. Both can be empty, and nonSubscriptions is always {}. They are not a complete purchase history.

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/src/web-api/purchases/purchases.controller.ts, dto/restore-purchase.dto.ts, api/src/sdk/purchases/apple-purchase.service.ts (restoreApplePurchases)

Restore a user's Google Play purchases to a profile. Botsi checks each item against Google's purchase history.

Required fields

attributes.profileId or attributes.customerUserId.
attributes.items: an array of objects containing productId and purchaseToken. Send the purchases you want to restore. An empty array is accepted and returns the current profile after app settings checks; it restores nothing.

Put the user ID inside attributes for this request.

Optional item fields

Each item can include productDetails, with subscriptionOfferDetails or oneTimePurchaseOfferDetails.

subscriptionOfferDetails is an array for restore requests. Purchase validation uses an object instead.
Items whose productDetails include oneTimePurchaseOfferDetails are restored as one-time purchases. Other items are restored as subscriptions.

App setup

Your app must have a public key configured. If it does not, the request returns 400 with App has no public key. Continue to use the secret key in this request's Authorization header.

Response

Profile ownership: Use a profile from the app identified by your secret key. This v1 request does not check app ownership when using profileId. A customerUserId lookup is limited to your app.

Source: api/src/web-api/purchases/purchases.controller.ts, dto/restore-purchase.dto.ts, api/src/sdk/purchases/google-purchase.service.ts (restoreGooglePurchases)

Validate App Store and Google Play purchases, or restore a user's earlier purchases to a profile.

Purchase validation links a purchase to the paywall that led to it. Neither validation endpoint accepts paywallSessionId. Send the paywall and test details from Fetch Paywall as separate fields: paywallId, abTestId, isExperiment, and aiPricingModelId.

All validation and restore requests return the full profile, including personal information and purchase access details. v2 returns fewer validation fields without personal information and does not offer restore endpoints.

Source: api/src/web-api/purchases/

\n","_postman_id":"32bcdf99-c75e-4563-b161-04c6b8dc8665","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","id":"261346bd-8303-45f1-9c1e-e1b68f0e656b","name":"Botsi API v1 (Legacy)","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]}},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["// Use the same variable precedence as the request's Authorization header.","const key = pm.variables.get('secretKey');","const raw = pm.request.body && pm.request.body.raw || '';","const missing = Array.from(new Set(Array.from(raw.matchAll(/\\{\\{([A-Za-z_][A-Za-z0-9_]*)\\}\\}/g), match => match[1])))"," .filter(name => pm.variables.get(name) === undefined || pm.variables.get(name) === null || pm.variables.get(name) === '');","let setupError = '';","if (!key) {"," setupError = 'Set secretKey in your Postman environment before sending requests.';","} else if (/^(Bearer|Api-Key)\\s/i.test(key)) {"," setupError = 'Use the secret key itself, without a Bearer or Api-Key prefix.';","} else if (pm.variables.get('baseUrl') !== 'https://app.botsi.com/api' || pm.variables.get('apiVersion') !== 'v1') {"," setupError = 'Use baseUrl https://app.botsi.com/api and apiVersion v1 for this production collection.';","} else if (missing.length) {"," setupError = 'Set these variables before sending the request: ' + missing.join(', ');","}","if (setupError) {"," console.error(setupError);"," pm.execution.skipRequest();","}"],"id":"9f0c3f32-491c-4d55-bb56-73de0ed570f0"}},{"listen":"test","script":{"type":"text/javascript","exec":["if (pm.response.code >= 400) {"," pm.test('Error contains ok, message, and status', () => {"," const error = pm.response.json();"," pm.expect(error).to.have.property('ok', false);"," pm.expect(error.message).to.be.a('string');"," pm.expect(error.status).to.eql(pm.response.code);"," });","}"],"id":"4957b284-790f-44a3-91b1-04ca10f85de4"}}],"variable":[{"key":"baseUrl","value":"https://app.botsi.com/api","type":"string","description":"Use `https://app.botsi.com/api` for the production API. Combined with `apiVersion` to build request URLs. v1 is not available at `api.botsi.com`."},{"key":"apiVersion","value":"v1","type":"string","description":"The API version used in request URLs: `v1`."},{"key":"secretKey","value":"","type":"string","description":"Your app secret key from the dashboard App configuration page. Sent directly in the `Authorization` header, without `Bearer` or another prefix. Keep the saved value blank and set it in a Postman environment."},{"key":"customerUserId","value":"user-123","type":"string","description":"The user ID from your own system. Links the Botsi profile across devices. Requests using this ID look for the user within your app. v2 calls this field `appUserId`."},{"key":"profileId","value":"","type":"string","description":"Saved automatically by Create a Profile for use in later requests."},{"key":"placementId","value":"","type":"string","description":"The ID of a placement configured in your dashboard. Set this before running the collection."},{"key":"store","value":"app_store","type":"string","description":"Required by Fetch Paywall. Selects the product fields to return: `app_store`, `play_store`, `stripe`, `web2wave`, or `custom`."},{"key":"storeProductId","value":"","type":"string","description":"A product ID configured in Botsi for the selected store and attached to the paywall used by your placement. Used by Validate Apple Store Purchase. Set an App Store product ID before running that request."},{"key":"storeEnvironment","value":"production","type":"string","description":"Set to `production` for the production purchase workflow. Included explicitly in purchase validation requests."},{"key":"paywallSessionId","value":"","type":"string","description":"Saved automatically by Fetch Paywall. By default, valid for `paywall_shown` events for 24 hours after the fetch. Other event types accept it at any age."},{"key":"paywallId","value":"","type":"string","description":"Saved automatically from `data.id` by Fetch Paywall. Keep this variable outside quotation marks in request bodies because its value must be a number."},{"key":"abTestId","value":"","type":"string","description":"Saved automatically from `data.abTestId` by Fetch Paywall, or set to `0` if no A/B test was selected. Keep it outside quotation marks in request bodies because its value must be a number."},{"key":"aiPricingModelId","value":"","type":"string","description":"Saved automatically from `data.aiPricingModelId` by Fetch Paywall, or set to `0` if no AI Pricing model was selected. Keep it outside quotation marks in request bodies because its value must be a number."},{"key":"isExperiment","value":"","type":"string","description":"Saved automatically by Fetch Paywall. Keep it outside quotation marks in request bodies because its value must be `true` or `false`."},{"key":"customAttributeId","value":"","type":"string","description":"Saved automatically by Add Custom Attribute. Used as `attrId` by Update Custom Attribute."},{"key":"appleTransactionId","value":"","type":"string","description":"Transaction ID from the actual App Store purchase. Set before Apple validation."},{"key":"appleOriginalTransactionId","value":"","type":"string","description":"Original transaction ID from the actual App Store purchase. Set before Apple validation."},{"key":"appleReceipt","value":"","type":"string","description":"Full base64 app receipt for Apple restore. Keep the saved value blank and set it in a Postman environment. A transaction ID is not an app receipt."},{"key":"googlePurchaseToken","value":"","type":"string","description":"Token for the Google Play purchase being validated or restored. Keep the saved value blank and set it in a Postman environment."},{"key":"googleSubscriptionProductId","value":"","type":"string","description":"Google Play subscription product ID configured in Botsi for this app."},{"key":"googleOneTimeProductId","value":"","type":"string","description":"Google Play one-time product ID configured in Botsi for this app."},{"key":"googleBasePlanId","value":"","type":"string","description":"Base plan ID for the purchased Google Play subscription. Must match the store and Botsi product configuration."},{"key":"googleOfferId","value":"","type":"string","description":"Offer ID for the purchased Google Play free-trial offer. Set before running the Free Trial request."}]}