Skip to main content
API v3 is legacy. Use API v4 for all new integrations. The v3 read endpoints remain available for existing integrations, but no new functionality is added to v3. This page consolidates the v3 concepts previously spread across separate reference pages. The full v3 operation reference lives in the REST API v3 section of the API Reference tab.

​
Base URL

All v3 requests are made to:
Requests must include an Authorization header with a Bearer token and, for POST/PUT/PATCH/DELETE requests, a Content-Type: application/json header. Responses are JSON-encoded.

​
Authentication: Project Key vs Secret Key

Both keys are found under Project Settings in the Qonversion dashboard. The v3 API uses two Bearer tokens with different privileges:
The Secret Key must only be stored on your server. Never embed it in Android, iOS, or web app code.
Project Keys with the test_ prefix (for example test_PV77YHL7qnGvsdmpTs7gimsxUvY-Znl2, the sample app key used in examples) target the sandbox environment; production keys have no prefix. There is also a separate API Key used only in the URL path of the Analytics API — it is not a v3 Bearer token.

​
Key concepts

  • Qonversion User ID — Auto-generated identifier prefixed with QON_ (for example QON_7791a27fc4e747412381842b36a), created by the SDK on first launch. It is the primary key for all v3 user operations.
  • Environment — Every user belongs to either prod or sandbox. Sandbox users do not affect production analytics.
  • Identity — Links a Qonversion User ID to your own auth system’s user ID, enabling cross-platform entitlement sharing. On another device, calling identify() with the same identity ID restores the user’s entitlements.
  • User Properties — Key-value attributes for segmentation, analytics filtering, and integrations. Qonversion-defined keys are prefixed with _q_ (for example _q_email, _q_appsflyer_user_id); any other key is a custom property. See the User Properties guide for the full list of defined keys.
  • Entitlement — An access right to premium features. Purchases grant entitlements automatically; you can also grant/revoke them via the API. An entitlement’s source is one of appstore, playstore, stripe, paddle, manual, or unknown.
  • Purchase — The v3 purchase endpoint records web/manual purchases: the request carries exactly one of stripe_store_data, paddle_store_data, app_store_data, or play_store_data. Stripe and Paddle are the typical paths; App Store and Google Play data are also accepted, though native purchases are normally recorded automatically by the SDK.
  • Product — Represents an in-app purchase or subscription configured in the dashboard, linked to store-specific identifiers (Apple, Google, Stripe). A product’s type is an integer enum 0–3 (0 = Subscription With Promo Period, 1 = Regular Subscription, 2 = Non-Recurring / Consumable, 3 = Non-Consumable / Lifetime) and its duration is 0–4 (0 = Weekly, 1 = Monthly, 2 = Three Monthly, 3 = Six Monthly, 4 = Annual).

​
HTTP status & error codes

v3 uses standard HTTP status codes: 200 success, 201 created, 204 no content, 400 bad request, 401 invalid key, 403 secret key required, 404 not found, 422 logical error, 5xx server error. Every error response shares a consistent envelope with an error object (type one of request, resource, logical, internal, plus a code and message) and a _meta object with a reference URL and field-level validation fields. The error.code values by type:

​
Resource → v4 equivalent

Each v3 resource has a v4 successor. Prefer v4 for new work; the v3 operation schemas remain in the REST API v3 section of the API Reference tab.