openapi: 3.0.0
info:
  title: Entitlements | REST API v1 Reference
  version: '1.0'
  description: RevenueCat API v1 endpoint reference for Entitlements.
servers:
  - url: https://api.revenuecat.com/v1
security:
  - BearerAuth: []
tags:
  - name: entitlements
    description: >-
      Part of the [REST API v1 Reference](/docs/api-v1).


      Operations about entitlements.


      #### Endpoints


      - [Grant an
      Entitlement](#tag/entitlements/operation/grant-a-promotional-entitlement)
      — `POST
      /subscribers/{app_user_id}/entitlements/{entitlement_identifier}/promotional`

      - [Revoke Granted
      Entitlements](#tag/entitlements/operation/revoke-promotional-entitlements)
      — `POST
      /subscribers/{app_user_id}/entitlements/{entitlement_identifier}/revoke_promotionals`
    x-displayName: Entitlements
  - name: Endpoint Reference
    x-traitTag: true
    description: >
      All API v1 resources, one page each. General concepts (authentication,
      request format, URL parameters) live on the [API v1
      overview](/docs/api-v1).


      - [Customer Info Model](/docs/api-v1/customer-info-model) — full schema
      reference

      - [Customers](/docs/api-v1/customers) — 4 endpoints

      - [Entitlements](/docs/api-v1/entitlements) — 2 endpoints

      - [Offerings](/docs/api-v1/offerings) — 3 endpoints

      - [Offerings Model](/docs/api-v1/offerings-model) — full schema reference

      - [Transactions](/docs/api-v1/transactions) — 6 endpoints
paths:
  /subscribers/{app_user_id}/entitlements/{entitlement_identifier}/promotional:
    post:
      summary: Grant an Entitlement
      tags:
        - entitlements
      description: >
        Grants a Customer an entitlement. Does not override or defer a store
        transaction, applied simultaneously.


        > Note: Requests with an `end_time_ms` within 2 hours of an active
        promotional entitlement’s expiration are treated as duplicates and won't
        extend it. This is common in sandbox renewal testing.
      operationId: grant-a-promotional-entitlement
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
        - name: entitlement_identifier
          in: path
          description: >-
            The identifier for the entitlement you want to grant to the
            Customer.
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                end_time_ms:
                  type: integer
                  format: int64
                  description: >-
                    A Unix epoch in milliseconds for when the entitlement should
                    expire. The entitlement will always be granted immediately.
                    If not provided then `duration` must be provided.
                  example: 1709196532093
                duration:
                  type: string
                  enum:
                    - daily
                    - three_day
                    - weekly
                    - two_week
                    - monthly
                    - two_month
                    - three_month
                    - six_month
                    - yearly
                    - lifetime
                  description: >-
                    How long of a duration to grant the entitlement for.  If not
                    provided then `end_time_ms` must be provided.
                  deprecated: true
                start_time_ms:
                  type: integer
                  format: int64
                  description: >-
                    A Unix epoch in milliseconds used to determine the
                    expiration date, by adding `duration` to `start_time_ms`.
                    Regardless of what `start_time_ms` is set to, the
                    entitlement will always be granted immediately. If
                    `start_time_ms` is not provided, the `duration` will be
                    added to the current time to determine the expiration date.
                  example: 1709195668093
                  deprecated: true
            example:
              start_time_ms: 1709195668093
              end_time_ms: 1709196532093
      responses:
        '201':
          description: >
            Entitlement was successfully granted.


            Returns the updated [Customer
            Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
  /subscribers/{app_user_id}/entitlements/{entitlement_identifier}/revoke_promotionals:
    post:
      summary: Revoke Granted Entitlements
      tags:
        - entitlements
      description: >-
        Revokes all granted entitlements for a given entitlement identifier and
        App User ID.
      operationId: revoke-promotional-entitlements
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
        - name: entitlement_identifier
          in: path
          description: >-
            The identifier for the entitlement you want to revoke from the
            Customer.
          schema:
            type: string
          required: true
      responses:
        '200':
          description: >
            Entitlement was successfully revoked.


            Returns the updated [Customer
            Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
components:
  schemas:
    Subscriber:
      type: object
      description: Snapshot of information about a Customer.
      properties:
        request_date:
          type: string
          description: Date of the request in ISO 8601 format.
          example: '2019-07-26T17:40:10Z'
        request_date_ms:
          type: integer
          format: int64
          description: Date of the request in milliseconds since Epoch.
          example: 1564162810884
        subscriber:
          type: object
          description: Information about the Customer.
          properties:
            entitlements:
              type: object
              description: >-
                Dictionary of the entitlements of this Customer (including any
                expired entitlements).
              additionalProperties:
                type: object
                description: >-
                  One entitlement granted to this Customer. If the customer was
                  granted this entitlement through multiple purchases, then the
                  information about the purchase with the furthest-out
                  expiration date is included.
                properties:
                  expires_date:
                    type: string
                    description: >-
                      Date when the entitlement expires / expired (in ISO 8601
                      format, may be in the past). `null` if it is a lifetime
                      entitlement.
                    example: '2024-12-12T14:04:03Z'
                    nullable: true
                  grace_period_expires_date:
                    type: string
                    description: >-
                      Date when any potential grace period of the entitlement
                      expires / expired (in ISO 8601 format, may be in the
                      past). `null` if the Customer has never been in a grace
                      period.
                    example: '2024-12-12T14:04:03Z'
                    nullable: true
                  product_identifier:
                    type: string
                    description: >
                      The identifier of the product that is responsible for this
                      entitlement being granted.<br><br>Please note: in some
                      cases, if there are problems with validating the purchase
                      with the store, the correct product identifier might
                      temporarily be unavailable.
                    example: onetime
                  purchase_date:
                    type: string
                    description: >-
                      Time of the last purchase or renewal of the product that
                      grants this entitlement (in ISO 8601 format).
                    example: '2019-04-05T21:52:45Z'
            first_seen:
              type: string
              description: >-
                The ISO 8601 datetime string corresponding to when the Customer
                was first seen by RevenueCat.
              example: '2019-02-21T00:08:41Z'
            last_seen:
              type: string
              description: >-
                The ISO 8601 datetime string corresponding to when the Customer
                was last seen by RevenueCat.
              example: '2019-02-21T00:08:41Z'
            management_url:
              type: string
              description: >
                URL to manage the active subscription of the Customer.


                If the Customer has an active App Store subscription, this will
                point to the App Store. If the Customer has an active Play Store
                subscription, it will point there. Amazon subscriptions point to
                the Amazon subscription management page, Paddle subscriptions
                point to the Paddle Customer Portal, and RevenueCat Web Billing
                subscriptions point to the RevenueCat Web Billing Customer
                Portal. For Stripe Billing subscriptions, this returns the
                configured Stripe Customer Portal URL or a custom URL. If no
                Stripe Customer Portal URL is configured, this will be null.


                If there are no active subscriptions it will be null.


                If the Customer has multiple active subscriptions for different
                platforms, this will take the value of the OS in the
                `X-Platform` header into consideration:

                - If the request was made on an OS for which there are active
                subscriptions, this will return the URL for the store that
                matches the header.

                - If the request was made on a different OS or the OS was not
                included in the X-Platform header, this will return the URL for
                the store of the subscription with the farthest future
                expiration date.
              example: https://apps.apple.com/account/subscriptions
            non_subscriptions:
              type: object
              description: >-
                Non-subscription purchases of the Customer, keyed by the product
                identifier.
              additionalProperties:
                type: array
                description: >-
                  One non-subscription product purchased by the customer.
                  Contains an array of the individual purchases of the product.
                items:
                  type: object
                  properties:
                    display_name:
                      type: string
                      description: >-
                        The display name of the product as configured in the
                        RevenueCat dashboard.
                      example: Lifetime Access
                    id:
                      type: string
                      example: cadba0c81b
                      description: A unique ID of the purchase.
                    is_sandbox:
                      type: boolean
                      description: Whether or not the purchase was made in sandbox mode.
                      example: false
                    price:
                      type: object
                      description: >-
                        The price of the transaction in the currency the product
                        was purchased in.
                      properties:
                        amount:
                          type: number
                          example: 9.99
                        currency:
                          type: string
                          example: USD
                    purchase_date:
                      type: string
                      example: '2019-04-05T21:52:45Z'
                      description: Date of the purchase (in ISO 8601 format).
                    store:
                      type: string
                      example: app_store
                      description: >
                        Identifier of the store of the purchase:

                        - `app_store`: The product was purchased through Apple
                        App Store.

                        - `mac_app_store`: The product was purchased through the
                        Mac App Store.

                        - `play_store`: The product was purchased through the
                        Google Play Store.

                        - `amazon`: The product was purchased through the Amazon
                        Appstore.

                        - `stripe`: The product was purchased through Stripe.

                        - `roku`: The product was purchased through Roku.

                        - `paddle`: The product was purchased through Paddle.
                    store_transaction_id:
                      type: string
                      description: >-
                        The identifier associated with the purchase in the
                        underlying store.
                      example: '1000000819074923'
            original_app_user_id:
              type: string
              example: XXX-XXXXX-XXXXX-XX
              description: >-
                The App User ID under which this Customer was first known to
                RevenueCat.
            original_application_version:
              type: string
              example: '1.0'
              description: >-
                *Only available on iOS*. This will be `null` until an iOS
                receipt is sent for the Customer. After a receipt has been sent,
                it will indicate the first App Store version of your app that
                the Customer installed.
            original_purchase_date:
              type: string
              example: '2019-01-30T23:54:10Z'
              description: >-
                **Only available on iOS**. The date that the app was first
                purchased/downloaded by the Customer. Will be `null` if no
                receipt is recorded for the Customer. Useful for [Migrating
                Subscriptions](/docs/migrating-to-revenuecat/migrating-existing-subscriptions).
            other_purchases:
              type: object
              properties: {}
              deprecated: true
            subscriber_attributes:
              description: >-
                A dictionary of any Attributes set on this Customer. **Only
                included in responses to requests made with a secret API key**.
              type: object
              additionalProperties:
                type: object
                description: An Attribute set on the Customer object.
                example:
                  favorite_color:
                    value: red
                    updated_at_ms: 1564162810884
                properties:
                  value:
                    type: string
                    description: The value of the attribute.
                    example: red
                  updated_at_ms:
                    type: integer
                    format: int64
                    description: >-
                      The time that the Attribute was last updated, in
                      milliseconds since Epoch.
                    example: 1564162810884
            subscriptions:
              type: object
              description: >-
                Subscription purchases of the Customer, keyed by the product
                identifier.
              additionalProperties:
                type: object
                description: One subscription product purchased by the Customer.
                properties:
                  auto_resume_date:
                    type: string
                    description: >-
                      Date when the subscription will automatically resume after
                      being paused (in ISO 8601 format). Google Play only.
                    example: null
                  billing_issues_detected_at:
                    type: string
                    example: null
                    description: >-
                      Date when RevenueCat detected any billing issues with this
                      subscription (in ISO 8601 format). If and when the billing
                      issue gets resolved, this field is set to `null`. Note the
                      subscription may still be active, check the `expires_date`
                      attribute.
                  expires_date:
                    type: string
                    example: '2019-08-14T21:07:40Z'
                    description: >-
                      Date when the subscription expires/expired (in ISO 8601
                      format).
                  display_name:
                    type: string
                    description: >-
                      The display name of the product as configured in the
                      RevenueCat dashboard.
                    example: Monthly Subscription
                  grace_period_expires_date:
                    type: string
                    example: '2019-08-14T21:07:40Z'
                    description: >-
                      Date when any grace period for this subscription
                      expires/expired (in ISO 8601 format). `null` if the
                      Customer has never been in a grace period.
                  is_sandbox:
                    type: boolean
                    description: Whether or not the purchase was made in sandbox mode.
                    example: false
                  original_purchase_date:
                    type: string
                    example: '2019-02-21T00:42:05Z'
                    description: >-
                      Date when this subscription first started (in ISO 8601
                      format). This property does not update with renewals. On
                      iOS, this property also does not update for product
                      changes within a subscription group or resubscriptions by
                      lapsed subscribers.
                  ownership_type:
                    type: string
                    enum:
                      - PURCHASED
                      - FAMILY_SHARED
                    description: >
                      How the Customer received access to this subscription:

                      - `PURCHASED`: The Customer purchased the product.

                      - `FAMILY_SHARED`: The Customer has access to the product
                      via their family.
                  period_type:
                    type: string
                    enum:
                      - normal
                      - trial
                      - intro
                    description: >
                      Type of the current subscription period_type:

                      - `normal`: The product is in a normal period (default)

                      - `trial`: The product is in a free trial period

                      - `intro`: The product is in an introductory pricing
                      period
                    example: NORMAL
                  price:
                    type: object
                    description: >-
                      The price of the transaction in the currency the product
                      was purchased in. Can be 0 for free trials.
                    properties:
                      amount:
                        type: number
                        example: 9.99
                      currency:
                        type: string
                        example: USD
                  purchase_date:
                    type: string
                    description: >-
                      Date when the last subscription period started (in ISO
                      8601 format).
                    example: '2019-07-14T20:07:40Z'
                  refunded_at:
                    type: string
                    description: >-
                      Date when RevenueCat detected a refund of this
                      subscription.
                    example: null
                  store:
                    type: string
                    example: app_store
                    description: >
                      Identifier of the store of the purchase:

                      - `app_store`: The product was purchased through Apple App
                      Store.

                      - `mac_app_store`: The product was purchased through the
                      Mac App Store.

                      - `play_store`: The product was purchased through the
                      Google Play Store.

                      - `amazon`: The product was purchased through the Amazon
                      Appstore.

                      - `stripe`: The product was purchased through Stripe.

                      - `promotional`: The product was [granted via
                      RevenueCat](#tag/entitlements/operation/grant-a-promotional-entitlement).

                      - `roku`: The product was purchased through Roku.

                      - `paddle`: The product was purchased through Paddle.
                  store_transaction_id:
                    type: string
                    example: GPA.6801-7988-0152-76034..5
                    description: |
                      Identifier of the purchase in the store's API.
                  unsubscribe_detected_at:
                    type: string
                    description: >-
                      Date when RevenueCat detected that auto-renewal was turned
                      off for this subsription (in ISO 8601 format). Note the
                      subscription may still be active, check the `expires_date`
                      attribute.
                    example: '2019-07-17T22:48:38Z'
      example:
        value: &ref_0
          request_date: '2019-07-26T17:40:10Z'
          request_date_ms: 1564162810884
          subscriber:
            entitlements:
              pro_cat:
                expires_date: null
                grace_period_expires_date: null
                product_identifier: onetime
                purchase_date: '2019-04-05T21:52:45Z'
            first_seen: '2019-02-21T00:08:41Z'
            management_url: https://apps.apple.com/account/subscriptions
            non_subscriptions:
              onetime:
                - id: cadba0c81b
                  is_sandbox: true
                  purchase_date: '2019-04-05T21:52:45Z'
                  store: app_store
            original_app_user_id: XXX-XXXXX-XXXXX-XX
            original_application_version: '1.0'
            original_purchase_date: '2019-01-30T23:54:10Z'
            other_purchases: {}
            subscriptions:
              annual:
                auto_resume_date: null
                billing_issues_detected_at: null
                expires_date: '2019-08-14T21:07:40Z'
                grace_period_expires_date: null
                is_sandbox: true
                original_purchase_date: '2019-02-21T00:42:05Z'
                ownership_type: PURCHASED
                period_type: normal
                purchase_date: '2019-07-14T20:07:40Z'
                refunded_at: null
                store: play_store
                store_transaction_id: GPA.6801-7988-0152-76034..5
                unsubscribe_detected_at: '2019-07-17T22:48:38Z'
              onemonth:
                auto_resume_date: null
                billing_issues_detected_at: null
                expires_date: '2019-06-17T22:47:55Z'
                grace_period_expires_date: null
                is_sandbox: true
                original_purchase_date: '2019-02-21T00:42:05Z'
                ownership_type: PURCHASED
                period_type: normal
                purchase_date: '2019-06-17T22:42:55Z'
                refunded_at: null
                store: app_store
                store_transaction_id: 1000000652379790
                unsubscribe_detected_at: '2019-06-17T22:48:38Z'
              rc_promo_pro_cat_monthly:
                auto_resume_date: null
                billing_issues_detected_at: null
                expires_date: '2019-08-26T01:02:16Z'
                grace_period_expires_date: null
                is_sandbox: false
                original_purchase_date: '2019-07-26T01:02:16Z'
                ownership_type: FAMILY_SHARED
                period_type: normal
                purchase_date: '2019-07-26T01:02:16Z'
                refunded_at: null
                store: promotional
                store_transaction_id: a42db3af39530cb82b17eaf9c6576393
                unsubscribe_detected_at: null
  examples:
    Subscriber:
      value: *ref_0
  securitySchemes:
    BearerAuth:
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication. Allowed headers -- Authorization: Bearer
        <api_key>
      scheme: bearer
      type: http
