Get Paywall

POSThttps://app.botsi.com/api/v1/web-api/paywalls

After a profile has been created, call Get Paywall at any time to retrieve the paywall predicted by Botsi’s AI Pricing model. The response determines which paywall configuration to display to the user.

Follow the notes below for a successful request:

  • You must identify the user by providing either profileId or customerUserId, and specify the placementId configured on the Botsi dashboard.

  • If optional fields are omitted when sending the request, Botsi will automatically fall back to the values stored on the user profile.

    Performance and timing

    The Get Paywall API uses AI models to determine the best paywall for a user, which introduces specific latency considerations. You must implement this endpoint strategically to ensure a seamless experience within your application.

    The response typically takes about 40 ms but can take up to 2 seconds depending on the AI prediction speed. To maintain a smooth user interface, follow these implementation guidelines:

    • Avoid calling this endpoint synchronously at render time.

    • Trigger the request early in the user journey, such as immediately after a profile is created.

    • Ensure the response is received and cached before the user reaches the point where the paywall must be displayed.

Request Body

application/json

ParameterTypeRequiredDescription
profileIdstringOptionalBotsi profile ID. Provide either profileId or customerUserId
customerUserIdstringRecommendedYour internal user ID. Provide either profileId or customerUserId
placementIdstringRequiredPlacement ID configured in Botsi dashboard
localestringOptionalFalls back to profile value if omitted
countrystringOptionalFalls back to profile value if omitted
ipstringOptionalFalls back to profile value if omitted
storeCountrystringOptionalFalls back to profile value if omitted

Example Request

{
  "profileId": "0072102a-c00c-4ea5-9271-1b6e975f2d63",
  "placementId": "ai-placement-id"
}

cURL Example

curl -X POST "https://app.botsi.com/api/v1/web-api/paywalls"      -H "Authorization: {{secret_key}}"      -H "Content-Type: application/json"      -d ‘{
       "profileId": "0072102a-c00c-4ea5-9271-1b6e975f2d63",
       "placementId": "ai-placement-id"
     }’

Response

200Paywall retrieved

A successful request returns the selected paywall and metadata indicating whether it was served by the AI Pricing model.

Key properties you may want to store or forward to later steps include:

  • data.id - The internal paywall ID in Botsi.

  • data.externalId - The external paywall ID used in your app and the AI Pricing model. It can be added manually when configuring the Paywall in Botsi.

  • data.isExperiment - A boolean that indicates if the paywall was returned by the AI Pricing model.

  • data.aiPricingModelId - The ID of the AI Pricing model that served the paywall.

Critical: Store These Values for Attribution

You must store isExperiment and aiPricingModelId from this response and pass them back exactly as received to every downstream API call: Send Profile Event, Validate Apple Purchase, and Validate Google Purchase.

These fields determine whether a conversion is attributed to the AI Pricing experiment or to the control group. If they are omitted or incorrect, revenue will be misattributed between experiment and control — your experiment results will be unreliable, and the AI model will train on corrupted data, degrading future pricing predictions.

{
  "ok": true,
  "data": {
    "id": 42,
    "externalId": "paywall_premium_v2",
    "name": "Premium Paywall",
    "isExperiment": true,
    "aiPricingModelId": 32,
    "sourceProducts": [
      {
        "productId": "premium_monthly",
        "basePlanId": "monthly-base",
        "offerId": "intro-offer-7d",
        "promotionalOfferId": null,
        "discountId": null
      }
    ]
  }
}

Try It Out

https://app.botsi.com/api/v1/web-api
Response 
Click "Send API Request" to see the response here.

Previous

Create a Profile

Next

Send Profile Event