> ## 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. # Grant an entitlement to a user > Grants an entitlement definition to a specific user, optionally with an expiry time. Attempting to extend or modify a user entitlement whose source is a paid purchase (store or Stripe) returns `422 paid_entitlement`. ## OpenAPI ````yaml /api-reference/rest-api-v4.yaml post /users/{user_id}/entitlements openapi: 3.0.3 info: title: Qonversion REST API v4 version: '4.0' description: >- Qonversion REST API v4 follows REST standards. It has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. servers: - url: https://api.qonversion.io/v4 description: Production security: - secretAuth: [] tags: - name: Users description: Retrieve Qonversion users - name: User Properties description: Manage user-level attributes - name: Identities description: Link Qonversion users to your own auth IDs - name: Entitlements description: Entitlement definitions and user grants - name: Purchases description: A user's purchase history - name: Products description: Products configured in the Qonversion dashboard - name: Customers description: Aggregated customer records, properties, permissions, and metrics - name: Segments description: Dynamic and system segments of users - name: Experiments description: Paywall and offering A/B experiments - name: Screens description: No-code paywall screens — CRUD, publish, analytics - name: Analytics description: Charts, cards, cohorts, LTV, and insights - name: Exports description: Asynchronous data exports - name: Events description: Event catalog - name: Scheduled Reports description: Recurring reports delivered to external destinations - name: Integrations description: Third-party integrations configuration - name: Automations description: Event-driven automations - name: Project Settings description: Project-level configuration, secret, and store credentials paths: /users/{user_id}/entitlements: post: tags: - Entitlements summary: Grant an entitlement to a user description: >- Grants an entitlement definition to a specific user, optionally with an expiry time. Attempting to extend or modify a user entitlement whose source is a paid purchase (store or Stripe) returns `422 paid_entitlement`. operationId: v4GrantUserEntitlement parameters: - name: user_id in: path required: true schema: type: string description: User identifier. example: QON_3af4c5b8a4d24f21b72e9d0c8aef9d4e requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V4GrantEntitlementRequest' responses: '201': description: Entitlement granted. headers: Location: schema: type: string description: Canonical URL of the granted user entitlement. content: application/json: schema: $ref: '#/components/schemas/V4UserEntitlement' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/V4Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/V4Error' '404': description: User or entitlement not found content: application/json: schema: $ref: '#/components/schemas/V4Error' '409': description: Entitlement already granted content: application/json: schema: $ref: '#/components/schemas/V4Error' '415': description: Unsupported Content-Type content: application/json: schema: $ref: '#/components/schemas/V4Error' '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/V4Error' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/V4Error' security: - secretAuth: [] components: schemas: V4GrantEntitlementRequest: type: object required: - entitlement_id properties: entitlement_id: type: string description: Identifier of the entitlement definition to grant. example: premium expires_at: type: integer format: int64 description: >- Unix timestamp (seconds) when the entitlement expires. Use `0` (or omit the field) to grant the entitlement with no expiry. Negative values and past timestamps are rejected with 400. default: 0 example: 1767225600 V4UserEntitlement: type: object required: - object - id - url - is_active - source properties: object: type: string enum: - user_entitlement id: type: string description: Unique entitlement identifier. example: premium url: type: string description: Canonical API path. example: /v4/users/QON_3af4c5b8a4d24f21b72e9d0c8aef9d4e/entitlements/premium is_active: type: boolean description: Whether the entitlement is currently active. source: type: string description: Source of the entitlement grant (open enum). x-extensible-enum: - appstore - playstore - stripe - manual - unknown started_at: type: string format: date-time nullable: true description: Timestamp when the entitlement became active (ISO 8601 UTC). example: '2025-09-15T12:30:00Z' expires_at: type: string format: date-time nullable: true description: >- Timestamp when the entitlement expires (ISO 8601 UTC). Null if no expiry. example: '2026-09-15T12:30:00Z' product: $ref: '#/components/schemas/V4UserEntitlementProduct' nullable: true description: Product associated with this entitlement, if any. V4Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - request - resource - logical - internal code: type: string description: | Machine-readable snake_case error code. Examples include `invalid_data`, `invalid_request`, `invalid_product_id`, `not_found`, `already_exists`, `offering_already_exists`, `product_not_in_project`, `cannot_set_main_directly`, `cannot_demote_main`, `cannot_patch_experiment_variant`, `cannot_delete_experiment_variant`, and `cannot_setmain_experiment_variant`. Resource-specific codes are documented on the corresponding reference page. message: type: string description: Human-readable description. May change; do not parse. details: type: array nullable: true description: Per-field validation errors, present on 400 validation failures. items: type: object properties: field: type: string message: type: string V4UserEntitlementProduct: type: object required: - product_id properties: product_id: type: string description: Product identifier. example: premium_monthly subscription: $ref: '#/components/schemas/V4UserEntitlementSubscription' nullable: true description: Subscription details, if the product is a subscription. V4UserEntitlementSubscription: type: object required: - renew_state - current_period_type properties: renew_state: type: string description: >- Current renewal state. Subscription is omitted entirely for non-renewable products. enum: - will_renew - canceled - billing_issue current_period_type: type: string description: Current billing period type. enum: - normal - trial - intro securitySchemes: secretAuth: type: http scheme: bearer bearerFormat: sk_… description: >- Bearer authentication using the project **Secret Key** (prefixed with `sk_`, or `test_sk_` for sandbox). All v4 public endpoints require the Secret Key — see [Authentication](/reference/v4/authentication). Never expose the Secret Key in client-side code. ````