openapi: 3.0.0
info:
  title: RevenueCat API v1
  version: '1.0'
  description: >
    <div class="theme-admonition theme-admonition-info alert alert--info">
        <div class="heading">New to RevenueCat?</div>
        <div>Welcome! If you're adding subscriptions or other in-app purchases to your app, the RevenueCat SDK will handle most of the heavy-lifting without the need to interact with this API directly. See our <a href="/docs/getting-started/quickstart">Quickstart</a> for more information on getting started with RevenueCat.</div>
    </div>


    # About RevenueCat’s REST API


    RevenueCat provides a REST API for developers to perform customer and
    transaction related actions from their own server.


    Most of this API is geared toward client usage via RevenueCat’s SDK, but
    there are various endpoints that can be used for refunding purchases,
    granting promotional entitlements, and other sensitive actions that can only
    be done via a Secret API key from your server.


    ## Should I use this REST API or the RevenueCat SDK?


    If you’re adding subscriptions or other in-app purchases to your app for the
    first time or if you don’t have a backend that stores your Customers'
    receipts, you’re probably looking to implement the [RevenueCat
    SDK](/getting-started/installation).


    If you want to start migrating your existing users to RevenueCat and you
    have your Customers' receipts stored on your own server, or you want to
    check subscription status of your users from your own server, the REST API
    is a great solution.


    # Base URL


    The base URL for the RevenueCat REST API is `https://api.revenuecat.com/v1`.


    # Authentication


    Authentication for the RevenueCat REST API is achieved by setting the
    `Authorization` header with a valid API key. You'll find two types of API
    keys in your RevenueCat dashboard: _public_ and _secret_.


    Certain endpoints require secret keys, which should be kept out of any
    publicly accessible areas such as GitHub, client-side code, and so forth.
    See our [Authentication guide](/docs/welcome/authentication/) for more
    information.


    ```text title="Authorization Header"

    Authorization: Bearer YOUR_REVENUECAT_API_KEY

    ```


    # Making requests

    ## Request Payload


    The body of the `POST` requests should be encoded in JSON and have the
    'Content-Type' header set to 'application/json'.


    ```text title="Content-Type Header"

    Content-Type: application/json

    ```


    ```json title="Sample Body"

    {
      "app_user_id": "user-1456",
      "fetch_token": "MQABC...EFH1234="
    }

    ```


    # URL parameters


    For URL params, such as the `app_user_id`, make sure you URL encode them
    before using them.
servers:
  - url: https://api.revenuecat.com/v1
tags:
  - name: transactions
    description: Operations about transactions.
    x-displayName: Transactions
  - name: customers
    description: Operations about customers.
    x-displayName: Customers
  - name: offerings
    description: Operations about offerings.
    x-displayName: Offerings
  - name: entitlements
    description: Operations about entitlements.
    x-displayName: Entitlements
  - name: customer_info_model
    x-displayName: Customer Info
    description: >
      <SchemaDefinition schemaRef="#/components/schemas/Subscriber"
      exampleRef="#/components/examples/Subscriber" showReadOnly={true}
      showWriteOnly={true} />
  - name: offerings_model
    x-displayName: Offerings
    description: >
      <SchemaDefinition schemaRef="#/components/schemas/Offerings"
      exampleRef="#/components/examples/Offerings" showReadOnly={true}
      showWriteOnly={true} />
x-tagGroups:
  - name: Endpoint Reference
    tags:
      - transactions
      - customers
      - offerings
      - entitlements
  - name: Model Reference
    tags:
      - customer_info_model
      - offerings_model
paths:
  /subscribers/{app_user_id}:
    get:
      summary: Get or Create Customer
      tags:
        - customers
      description: >-
        Gets the latest [Customer Info](#tag/customer_info_model) for the
        customer with the given App User ID, or creates a new customer if it
        doesn't exist.
      operationId: subscribers
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID used with the mobile SDK.
          schema:
            type: string
          required: true
        - name: X-Platform
          in: header
          description: >-
            Optionally set the X-Platform header to update the Customer's
            `last_seen` field. Set to either `ios`, `android`, `amazon`,
            `macos`, `uikitformac`. Don't set this if you are calling the getter
            for informational purposes or using a secret API key to fetch the
            customer's attributes.
          schema:
            type: string
            example: ios
      responses:
        '200':
          description: >
            Success (customer found).


            Returns the [Customer Info](#tag/customer_info_model) for the
            Customer.
          content:
            application/json:
              examples:
                Result:
                  $ref: '#/components/examples/Subscriber'
              schema:
                $ref: '#/components/schemas/Subscriber'
        '201':
          description: >
            Success (customer created).


            Returns the [Customer Info](#tag/customer_info_model) for the
            Customer.
          content:
            application/json:
              examples:
                Result:
                  $ref: '#/components/examples/Subscriber'
              schema:
                $ref: '#/components/schemas/Subscriber'
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    message: Bad parameters x
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Result:
                  value:
                    message: Invalid API key
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: false
    delete:
      summary: Delete Customer
      tags:
        - customers
      description: Permanently deletes a customer.
      operationId: delete-subscriber
      parameters:
        - name: app_user_id
          in: path
          description: >-
            The App User ID of the customer to be deleted (might be an aliased
            App User ID).
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Customer successfully deleted.
          content:
            application/json:
              schema:
                type: object
                required:
                  - app_user_id
                  - deleted
                properties:
                  app_user_id:
                    type: string
                    description: >-
                      The App User ID of the customer that was requested to be
                      deleted
                    example: XXX-XXXXX-XXXXX-XX
                  deleted:
                    type: boolean
                    description: Whether or not the customer was successfully deleted
                    example: true
      deprecated: false
  /receipts:
    post:
      summary: Create a Purchase
      tags:
        - transactions
      description: >-
        Records a purchase for a Customer from iOS, Android, Stripe, Roku and
        Paddle will create a Customer if they don't already exist.
      operationId: receipts
      parameters:
        - name: X-Platform
          in: header
          description: >-
            The platform this purchase is for. Either `ios`, `android`,
            `amazon`, `macos`, `uikitformac`, `stripe`, `roku`, or `paddle`
          required: true
          schema:
            type: string
            example: ios
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - app_user_id
                - fetch_token
              properties:
                app_user_id:
                  type: string
                  description: App User ID of the Customer the receipt is associated with.
                fetch_token:
                  type: string
                  description: >-
                    For iOS, the base64 encoded receipt file (or JWSTransaction
                    for StoreKit2), for Android the receipt token, for Amazon
                    the receipt, for Stripe the subscription ID or the Stripe
                    Checkout Session ID, for Roku the transaction ID, and for
                    Paddle the subscription ID or transaction ID.
                product_id:
                  type: string
                  description: >-
                    The Apple, Google, Amazon, Roku, or Paddle product
                    identifier or SKU. Required for Google.
                  example: com.my.product.iap
                price:
                  type: number
                  description: >-
                    The price of the product. **Required if you provide a
                    currency.**
                  example: 1.99
                  format: float
                currency:
                  type: string
                  description: >-
                    The currency of the product. The currency must be in [ISO
                    4217 format](https://en.wikipedia.org/wiki/ISO_4217).
                    **Required if you provide a price.**
                  example: USD
                  default: USD
                payment_mode:
                  type: string
                  description: >-
                    Optionally used by the iOS SDK to communicate intro pricing
                    periods. Either `pay_as_you_go = 0`, `pay_up_front = 1`, or
                    `free_trial = 2`. Defaults to `2` (free trial) if an
                    introductory period is detected in the receipt but this
                    value is not provided.
                introductory_price:
                  type: number
                  description: Introductory price paid
                  format: float
                is_restore:
                  type: boolean
                  description: >-
                    If true, the fetch token will trigger your configured
                    [restore
                    behavior](https://www.revenuecat.com/docs/restoring-purchases#restore-behavior)
                    for any other users sharing the same fetch token.
                  default: false
                  deprecated: true
                presented_offering_identifier:
                  type: string
                  description: >-
                    Optional. The offering that was presented to the Customer at
                    the time of purchase.  This will be attached to any new
                    transactions in this fetch token and will be available in
                    ETL exports and webhooks. This is mostly useful if you're
                    sending fetch tokens from your backend.
                attributes:
                  description: >-
                    Any [Attributes](/docs/customers/customer-attributes) to set
                    on the Customer as a dictionary keyed by the Attribute name.
                  additionalProperties:
                    description: A single Attribute to be set.
                    type: object
                    required:
                      - value
                    properties:
                      value:
                        type: string
                        description: >-
                          The value of the attribute. If the value is `null` or
                          an empty string, the attribute will be deleted.
                      updated_at_ms:
                        type: integer
                        format: int64
                        description: >-
                          UNIX epoch in milliseconds of when the attribute was
                          updated. This value is used to resolve conflicts, an
                          attribute will only be updated if the new
                          `updated_at_ms` value is newer than the value for the
                          stored attribute.
                        example: 1709195668093
                  type: object
      responses:
        '200':
          description: >
            Purchase was successfully posted.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer for which the purchase was posted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
  /subscribers/{app_user_id}/attribution:
    post:
      summary: Add Customer Attribution Data
      tags:
        - customers
      description: >-
        Attaches attribution data to a subscriber from specific supported
        networks.
      operationId: subscribersattribution
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
                - network
              properties:
                data:
                  type: object
                  description: The data returned by the attribution network callbacks.
                  properties:
                    rc_idfa:
                      type: string
                      description: The idfa from AdSupport on iOS. (iOS Only)
                    rc_gps_adid:
                      type: string
                      description: >-
                        The Google Play Services Advertising identifier.
                        (Android Only)
                network:
                  type: string
                  description: |
                    The attribution network the data is coming from:
                    - 0: Apple Search AdSupport
                    - 1: Adjust
                    - 2: AppsFlyer
                    - 3: Branch
                    - 4: Tenjin
                    - 5: Facebook
                  enum:
                    - '0'
                    - '1'
                    - '2'
                    - '3'
                    - '4'
                    - '5'
      responses:
        '200':
          description: Attribution data was successfully posted.
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: true
  /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](#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](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
  /subscribers/{app_user_id}/subscriptions/{product_identifier}/revoke:
    post:
      summary: 'Google Play: Refund and Revoke Subscription'
      tags:
        - transactions
      description: >-
        Immediately revokes access to a Google Subscription and issues a refund
        for the last purchase. If you want to refund a one-time Google purchase,
        see [refund a Google
        purchase](#tag/transactions/operation/revoke-a-google-subscription).
      operationId: revoke-a-google-subscription
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
        - name: product_identifier
          in: path
          description: >-
            The identifier of the product belonging to the subscription that is
            being revoked.
          schema:
            type: string
          required: true
      responses:
        '200':
          description: >
            Subscription was successfully refunded and revoked.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
  /subscribers/{app_user_id}/attributes:
    post:
      summary: Update Customer Attributes
      tags:
        - customers
      description: Updates attributes for a customer.
      operationId: update-subscriber-attributes
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID used with the mobile SDK.
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                attributes:
                  properties:
                    key_name:
                      type: object
                      description: Mapping of keys to attribute values.
                      required:
                        - value
                      properties:
                        value:
                          type: string
                          description: >-
                            The value of the attribute. If the value is `null`
                            or an empty string, the attribute will be deleted.
                        updated_at_ms:
                          type: integer
                          format: int64
                          description: >-
                            UNIX epoch in milliseconds of when the attribute was
                            updated. This value is used to resolve conflicts, an
                            attribute will only be updated if the new
                            `updated_at_ms` value is newer than the value for
                            the stored attribute.
                          example: 1709195668093
                  required:
                    - key_name
                  type: object
      responses:
        '200':
          description: >
            Attributes were successfully updated.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: 7263
                    message: Some customer attribute keys were unable to be saved.
                    attribute_errors:
                      - key_name: $email
                        message: Value is not a valid email address.
                      - key_name: invalid key name with spaces
                        message: Key name format is not valid.
                      - key_name: too_much_data
                        message: Value is too long.
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 7263
                  message:
                    type: string
                    example: Some customer attribute keys were unable to be saved.
                  attribute_errors:
                    type: array
                    items:
                      type: object
                      properties:
                        key_name:
                          type: string
                          example: $email
                        message:
                          type: string
                          example: Value is not a valid email address.
      deprecated: false
  /subscribers/{app_user_id}/subscriptions/{product_identifier}/defer:
    post:
      summary: 'Google Play: Defer a Subscription'
      tags:
        - transactions
      description: Defers the purchase of a Google Subscription to a later date.
      operationId: defer-a-google-subscription
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
        - name: product_identifier
          in: path
          description: >-
            The identifier of the product belonging to the subscription that is
            being deferred. This can be found in RevenueCat's Product catalog ->
            {Product} -> Subscription Id.
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                expiry_time_ms:
                  type: integer
                  format: int64
                  description: >-
                    The desired next expiry time to assign to the subscription,
                    in milliseconds since the Epoch. The given time must be
                    later/greater than the current expiry time for the
                    subscription. Either `expiry_time_ms` or `extend_by_days`
                    must be provided.
                  example: 1708417962662
                extend_by_days:
                  type: integer
                  minimum: 1
                  maximum: 365
                  description: >-
                    The number of days to extend the subscription renewal date.
                    Must be between 1 and 365. Either `expiry_time_ms` or
                    `extend_by_days` must be provided.
                  example: 30
      responses:
        '200':
          description: >
            Subscription was successfully deferred.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
  /subscribers/{app_user_id}/offerings/{offering_uuid}/override:
    post:
      summary: Override a Customer's Current Offering
      tags:
        - offerings
      description: Overrides the current Offering for a specific Customer
      operationId: override-offering
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
        - name: offering_uuid
          in: path
          description: >-
            The UUID for the offering you want to set as the override for the
            Customer. The UUID can be found in the URL of the offering. For
            example, the offering UUID in
            https://app.revenuecat.com/apps/abcd1234/offerings/ofrng1234567abc
            is `ofrng1234567abc`.
          schema:
            type: string
          required: true
      responses:
        '201':
          description: >
            Offering was successfully overridden.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
  /subscribers/{app_user_id}/offerings/override:
    delete:
      summary: Remove a Customer's Current Offering Override
      tags:
        - offerings
      description: >-
        Reset the offering overrides back to the current offering for a specific
        Customer
      operationId: delete-offering-override
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
      responses:
        '201':
          description: >
            Offering override was successfully removed.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
  /subscribers/{app_user_id}/offerings:
    get:
      summary: Get Offerings
      tags:
        - offerings
      description: Gets the offerings for your app.
      operationId: get-offerings
      parameters:
        - name: app_user_id
          in: path
          description: >-
            The App User ID used with the mobile SDK. The App User ID doesn't
            have to exist for the endpoint to work but it can affect the current
            offering depending on whether you have any
            [Experiments](https://www.revenuecat.com/docs/tools/experiments-v1)
            running or have [overridden the current
            offering](ref:override-offering) for this specific App User ID.
          schema:
            type: string
          required: true
        - name: X-Platform
          in: header
          description: >-
            Set the X-Platform header to fetch that platform's packages. Can be
            `ios`, `android`, `amazon`, `stripe`, `roku`, or `paddle`.

            This header is required if you use a legacy public API key to
            determine which store the products should be returned for. It is not
            required if you use a new, app-specific API key, in which case the
            products for the app associated with the API key will be returned.
          schema:
            type: string
            example: ios
      responses:
        '200':
          description: '[Offerings](#tag:offerings_model) for the Customer.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Offerings'
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Invalid Platform:
                  value:
                    code: 7000
                    message: Invalid Platform
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Secret API Key Used:
                  value: >-
                    {"code": 7243, "message": "Secret API keys should not be
                    used in your app."}
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 7243
                  message:
                    type: string
                    example: Secret API keys should not be used in your app.
      deprecated: false
  /subscribers/{app_user_id}/transactions/{store_transaction_identifier}/refund:
    post:
      summary: 'Google Play: Refund and Revoke Purchase'
      tags:
        - transactions
      description: >-
        Issues a refund for the specified transaction and revokes access. Works
        for subscription and non-subscription purchases that occurred in the
        last 365 days.
      operationId: refund-a-google-subscription
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
        - name: store_transaction_identifier
          in: path
          description: >-
            The identifier of the transaction to refund. Example:
            GPA.3309-9122-6177-45730
          schema:
            type: string
          required: true
      responses:
        '200':
          description: >
            Purchase was successfully refunded and revoked.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
  /subscribers/{app_user_id}/subscriptions/{store_transaction_identifier}/cancel:
    post:
      summary: 'Google Play: Cancel a Subscription'
      tags:
        - transactions
      description: >-
        Cancels a Google subscription. The subscription remains valid until its
        expiration time, but it will not renew.
      operationId: cancel-a-google-subscription
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
        - name: store_transaction_identifier
          in: path
          description: >-
            The identifier of the transaction to cancel. Example:
            GPA.3309-9122-6177-45730
          schema:
            type: string
          required: true
      responses:
        '200':
          description: >
            Subscription was successfully canceled.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
  /subscribers/{app_user_id}/subscriptions/{store_transaction_identifier}/extend:
    post:
      summary: 'App Store: Extend a Subscription'
      tags:
        - transactions
      description: >
        Extends the renewal date of an auto-renewable subscription for up to 90
        days for a specific customer.


        This uses Apple's [Extend a Subscription Renewal
        Date](https://developer.apple.com/documentation/appstoreserverapi/extend_a_subscription_renewal_date)
        API.


        **Requires a v1 Secret API key.**


        Note: Apple limits subscription extensions to two per year per customer.
        Apple immediately sends the customer an email notification of the
        extension.
      operationId: extend-an-apple-subscription
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
        - name: store_transaction_identifier
          in: path
          description: >-
            The store transaction identifier of the subscription to extend. Can
            be original transaction identifier or renewal transaction
            identifier. Example: 1000000819074923
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - extend_by_days
                - extend_reason_code
              properties:
                extend_by_days:
                  type: integer
                  minimum: 1
                  maximum: 90
                  description: >-
                    The number of days to extend the subscription renewal date.
                    Must be between 1 and 90.
                  example: 30
                extend_reason_code:
                  type: integer
                  minimum: 0
                  maximum: 3
                  description: >
                    The reason code for the subscription extension. See Apple's
                    [extendReasonCode](https://developer.apple.com/documentation/appstoreserverapi/extendreasoncode)
                    documentation.

                    - `0`: Undeclared - The renewal-date extension reason is
                    undeclared.

                    - `1`: Customer Satisfaction - The renewal-date extension is
                    for customer satisfaction.

                    - `2`: Other - The renewal-date extension is for a reason
                    other than the ones listed.

                    - `3`: Service Issue or Outage - The renewal-date extension
                    is due to a service issue or outage.
                  example: 1
      responses:
        '200':
          description: >
            Subscription was successfully extended.


            Returns the updated [Customer Info](#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
      deprecated: false
security:
  - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication. Allowed headers -- Authorization: Bearer
        <api_key>
      scheme: bearer
      type: http
  schemas:
    Error:
      type: object
      description: Identifies an error that occurred while processing an API request.
      properties:
        message:
          type: string
          description: The error message.
          example: Invalid API key
        code:
          type: number
          description: A numeric error code.
          example: 7243
    Offerings:
      example:
        value: &ref_1
          current_offering_id: default
          offerings:
            - description: The default offering
              identifier: default
              packages:
                - identifier: $rc_monthly
                  platform_product_identifier: monthly_free_trial
                - identifier: consumable
                  platform_product_identifier: consumable1
                - identifier: $rc_annual
                  platform_product_identifier: yearly_free_trial
            - description: The sale offeringg
              identifier: sale_offering
              packages:
                - identifier: $rc_monthly
                  platform_product_identifier: monthly_free_trial_sale
                - identifier: consumable
                  platform_product_identifier: consumable1_sale
                - identifier: $rc_annual
                  platform_product_identifier: yearly_free_trial_sale
      type: object
      description: Your app's [Offerings and Packages](/getting-started/entitlements).
      properties:
        current_offering_id:
          type: string
          description: >-
            The identifier of the current Offering for this Customer.
            [Targeting](/docs/tools/targeting), [Offering
            overrides](#tag/offerings/operation/override-offering), and
            [Experiments](/docs/tools/experiments-v1) affect this identifier
            depending on the App User ID.
          example: default
        offerings:
          type: array
          description: A list of available Offerings.
          items:
            type: object
            description: An Offering.
            properties:
              description:
                type: string
                description: The Offering's description.
                example: The default offering
              identifier:
                type: string
                description: The Offering's identifier.
                example: default
              packages:
                type: array
                description: The Packages of this Offering.
                items:
                  type: object
                  description: The Offering's packages.
                  properties:
                    identifier:
                      type: string
                      description: >-
                        The package's identifier. If you used one of
                        RevenueCat's default identifiers, it will be prefixed by
                        `$rc_`.
                      example: $rc_monthly
                    platform_product_identifier:
                      type: string
                      example: monthly_free_trial
                      description: >-
                        The identifier of the product in the store. This should
                        be used to fetch the product from Apple, Google, Amazon,
                        or Stripe depending on the platform. This field will be
                        populated only for the current app based on the API key
                        used and the `X-Platform` header.
    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
    Offerings:
      value: *ref_1
