> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API v3 (legacy)

> Legacy: the v3 REST API is superseded by API v4. This page summarizes v3 concepts, authentication keys, and a resource-to-v4 mapping for existing integrations. New integrations should use v4.

<Warning>
  **API v3 is legacy. Use [API v4](/reference/v4/overview) 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](/api-reference/users/retrieve-a-user) tab.
</Warning>

## Base URL

All v3 requests are made to:

```
https://api.qonversion.io/v3
```

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](https://dash.qonversion.io). The v3 API uses two Bearer tokens with different privileges:

| Key             | Prefix                          | Used for                                                                                                                                |
| --------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Project Key** | none (sandbox keys use `test_`) | Standard requests: retrieve/create users, properties, identities; retrieve entitlements; retrieve/create products; **record purchases** |
| **Secret Key**  | `sk_`                           | Access-modifying operations: **grant / revoke entitlements**                                                                            |

<Warning>
  The Secret Key must only be stored on your server. **Never embed it in Android, iOS, or web app code.**
</Warning>

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](/docs/properties-reference) 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:

| Type       | Code                   | Meaning                                                     |
| ---------- | ---------------------- | ----------------------------------------------------------- |
| `request`  | `invalid_data`         | Validation failed; see `_meta.fields` for details           |
| `request`  | `invalid_request`      | Unrecognized request URL                                    |
| `request`  | `control_unauthorized` | Authorization required                                      |
| `request`  | `not_implemented`      | Functionality at the requested address is not implemented   |
| `resource` | `not_found`            | Requested resource not found                                |
| `resource` | `already_exists`       | Requested resource already exists                           |
| `logical`  | `purchase_fraud`       | Could not validate purchase with the store, potential fraud |
| `logical`  | `relation_not_found`   | Nested objects could not be found or associated             |
| `internal` | `storage_error`        | Data was not saved                                          |
| `internal` | `network_error`        | Internal services interaction failed                        |
| `internal` | `unknown_error`        | Unknown reason                                              |

## 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.

| v3 resource     | v4 equivalent                                             | v3 spec (API Reference)                                                             |
| --------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Users           | [Users (v4)](/reference/v4/users)                         | [Retrieve a user](/api-reference/users/retrieve-a-user)                             |
| User Properties | [User Properties (v4)](/reference/v4/user-properties)     | [Retrieve user properties](/api-reference/user-properties/retrieve-user-properties) |
| Identity        | [Identities (v4)](/reference/v4/identities)               | [Retrieve an identity](/api-reference/identity/retrieve-an-identity)                |
| Entitlements    | [Entitlements (v4)](/reference/v4/entitlements)           | [Retrieve entitlements](/api-reference/entitlements/retrieve-entitlements)          |
| Purchases       | [Purchases (v4)](/reference/v4/purchases)                 | [Create a purchase](/api-reference/purchases/create-a-purchase)                     |
| Products        | [Products (v4)](/reference/v4/products)                   | [List products](/api-reference/products/list-products)                              |
| Authentication  | [Authentication (v4)](/reference/v4/authentication)       | —                                                                                   |
| Handling errors | [Handling Errors (v4)](/reference/v4/handling-api-errors) | —                                                                                   |