Validate Google Play Store Purchase

POST https://api.botsi.com/v2/purchases/play-store/validate

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.

Identify the user with profileId.

Request body#

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

isExperiment and aiPricingModelId are optional on the v2 API, though the SDK surface requires them.

Send environment explicitly. It has no default.

A missing environment is treated as non-production, which silently drops the revenue event. The call still succeeds, so nothing surfaces until the revenue is missing from your reports.

Send production for live apps and sandbox for testing.

Send one offer object, never both

subscriptionOfferDetails and oneTimePurchaseOfferDetails are mutually exclusive. Which one you send depends on whether you are validating a subscription or a one-time purchase.

Like the Apple endpoint, this one does not accept paywallSessionId. Keep passing paywallId, isExperiment, and aiPricingModelId.

subscriptionOfferDetails#

Parameter	Type	Description
`basePlanId`	string	The base plan ID for the subscription Product
`offerId`	string	The offer ID, if the Product has an offer configured in the store
`pricingPhases`	array	The pricing phases for the subscription

Each entry in pricingPhases:

Parameter	Type	Description
`priceAmountMicros`	number	Price in micro-units. 1,000,000 micro-units is one unit of currency
`currencyCode`	string	ISO 4217 currency code
`billingPeriod`	string	The billing period, in ISO 8601 format
`recurrenceMode`	number	The recurrence mode of the phase
`billingCycleCount`	number	How many cycles the period applies for

oneTimePurchaseOfferDetails#

Parameter	Type	Description
`priceAmountMicros`	number	Price in micros, for example `9990000` for $9.99
`currencyCode`	string	ISO 4217 code, for example `USD`

A missing zero-priced phase turns a trial into revenue

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.

Example requests#

Which offer object you send depends on what the user bought. A subscription with an introductory free trial carries two pricing phases: the zero-priced trial, then the phase that charges once it ends.

curl -X POST "https://api.botsi.com/v2/purchases/play-store/validate" \
  -H "Authorization: $BOTSI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5",
    "placementId": "fresh_placement",
    "productId": "monthly",
    "paywallId": 569,
    "isExperiment": true,
    "aiPricingModelId": 32,
    "environment": "production",
    "profileId": "55bbd5f3-6de8-4d3b-8a55-006e6af6e3dd",
    "subscriptionOfferDetails": {
      "basePlanId": "1month-sub",
      "pricingPhases": [
        {
          "priceAmountMicros": 359990000,
          "currencyCode": "UAH",
          "billingPeriod": "P1M",
          "recurrenceMode": 1,
          "billingCycleCount": 0
        }
      ]
    }
  }'

curl -X POST "https://api.botsi.com/v2/purchases/play-store/validate" \
  -H "Authorization: $BOTSI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5",
    "placementId": "fresh_placement",
    "productId": "monthly",
    "paywallId": 569,
    "isExperiment": true,
    "aiPricingModelId": 32,
    "environment": "production",
    "profileId": "55bbd5f3-6de8-4d3b-8a55-006e6af6e3dd",
    "subscriptionOfferDetails": {
      "basePlanId": "1month-sub",
      "offerId": "freetrial-7d",
      "pricingPhases": [
        {
          "priceAmountMicros": 0,
          "currencyCode": "UAH",
          "billingPeriod": "P1W",
          "recurrenceMode": 2,
          "billingCycleCount": 1
        },
        {
          "priceAmountMicros": 359990000,
          "currencyCode": "UAH",
          "billingPeriod": "P1M",
          "recurrenceMode": 1,
          "billingCycleCount": 0
        }
      ]
    }
  }'

curl -X POST "https://api.botsi.com/v2/purchases/play-store/validate" \
  -H "Authorization: $BOTSI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "algojlnkodhhjceoicbpjngh.AO-J1Owvcga8j2uUoKEpn5AnvpSFr8dxEFm0c6qk5",
    "placementId": "fresh_placement",
    "productId": "lifetime_unlock",
    "paywallId": 569,
    "isExperiment": true,
    "aiPricingModelId": 32,
    "environment": "production",
    "profileId": "55bbd5f3-6de8-4d3b-8a55-006e6af6e3dd",
    "oneTimePurchaseOfferDetails": {
      "priceAmountMicros": 9990000,
      "currencyCode": "USD"
    }
  }'

Finding the token#

The purchase token comes from getPurchaseToken() in the Google Play Billing Library. Google's own documentation on verifying purchases before granting entitlements covers where it appears in the billing flow.

Response#

A successful validation returns the updated Profile, including its Access Levels, subscriptions, and total revenue. Read state and accessLevels to decide what the user now has access to.

{
  "ok": true,
  "data": {
    "profileId": "55bbd5f3-6de8-4d3b-8a55-006e6af6e3dd",
    "appUserId": "user-123",
    "state": "subscribed",
    "totalRevenueUsd": 8.72,
    "accessLevels": {},
    "subscriptions": {},
    "nonSubscriptions": {}
  }
}

accessLevels, subscriptions, and nonSubscriptions are keyed objects, empty when the Profile has no entries of that kind. The shape matches Validate Apple Store Purchase, so a single handler can process either store's response.