info:
  title: Developer API
  version: 2.0.0
security:
  - BearerAuth: []
servers:
  - url: https://api.revenuecat.com/v2
openapi: 3.0.3
tags:
  - name: Charts & Metrics
    description: Operations about chart metrics.
paths:
  /projects/{project_id}/metrics/overview:
    get:
      summary: Get overview metrics for a project
      operationId: get-overview-metrics
      x-revenuecat-rate-limiting-domain: charts_metrics
      x-scopes:
        - charts_metrics:overview:read
      x-release-status: public
      tags:
        - Charts & Metrics
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: currency
          description: The currency to return metrics data in
          in: query
          schema:
            type: string
            enum:
              - USD
              - EUR
              - GBP
              - AUD
              - CAD
              - JPY
              - BRL
              - KRW
              - CNY
              - MXN
              - SEK
              - PLN
              - NZD
              - CHF
          example: EUR
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OverviewMetrics'
          headers:
            RevenueCat-Rate-Limit-Current-Usage:
              $ref: '#/components/headers/RateLimitCurrentUsage'
            RevenueCat-Rate-Limit-Current-Limit:
              $ref: '#/components/headers/RateLimitCurrentLimit'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/InternalError'
      description: >-
        This endpoint requires the following permission(s):
        <code>charts_metrics:overview:read</code>. This endpoint belongs to the
        <strong>Charts & Metrics</strong> domain, which has a default rate limit
        of <strong>25 requests per minute</strong>.
  /projects/{project_id}/metrics/revenue:
    get:
      summary: Get revenue for a project
      description: >-
        Returns the total revenue for the project across all of its apps for the

        given inclusive date range `[start_date, end_date]`. The value is
        expressed

        in the project's primary currency unless `currency` is provided.


        Use `revenue_type` to choose which revenue definition the `value`
        represents:

        gross `revenue` (default), `revenue_net_of_taxes`, or `proceeds` (net of
        both

        taxes and store commission — the amount the developer keeps).


        This endpoint is backed by the same realtime (v3) revenue chart that
        powers

        the dashboard. It is intended for cases where an app needs an
        authoritative

        revenue total without inferring it from the transaction list.


        Note that the most recent day in the range may be partial if it includes

        today, since transactions for today are still arriving.
         This endpoint requires the following permission(s): <code>charts_metrics:overview:read</code>. This endpoint belongs to the <strong>Charts & Metrics</strong> domain, which has a default rate limit of <strong>25 requests per minute</strong>.
      operationId: get-revenue-metric
      x-revenuecat-rate-limiting-domain: charts_metrics
      x-scopes:
        - charts_metrics:overview:read
      x-release-status: public
      tags:
        - Charts & Metrics
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: start_date
          description: Start date for the data range (ISO 8601 format)
          in: query
          required: true
          schema:
            type: string
            format: date
            example: '2024-01-01'
        - name: end_date
          description: End date for the data range (ISO 8601 format)
          in: query
          required: true
          schema:
            type: string
            format: date
            example: '2024-12-31'
        - name: currency
          description: The currency to return metrics data in
          in: query
          schema:
            type: string
            enum:
              - USD
              - EUR
              - GBP
              - AUD
              - CAD
              - JPY
              - BRL
              - KRW
              - CNY
              - MXN
              - SEK
              - PLN
              - NZD
              - CHF
          example: EUR
        - name: revenue_type
          in: query
          description: >
            Which revenue definition to return as the metric value:

            - `revenue`: gross revenue.

            - `revenue_net_of_taxes`: revenue with taxes subtracted.

            - `proceeds`: revenue net of both taxes and store commission (the
            amount the
              developer keeps).
          required: false
          schema:
            type: string
            enum:
              - revenue
              - revenue_net_of_taxes
              - proceeds
            default: revenue
          example: proceeds
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevenueMetric'
          headers:
            RevenueCat-Rate-Limit-Current-Usage:
              $ref: '#/components/headers/RateLimitCurrentUsage'
            RevenueCat-Rate-Limit-Current-Limit:
              $ref: '#/components/headers/RateLimitCurrentLimit'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/InternalError'
  /projects/{project_id}/charts/{chart_name}:
    get:
      summary: Get chart data
      description: >-
        Returns time-series data for a specific chart.


        **Response Structure**


        The response includes:

        - Chart metadata (category, display_name, description)

        - Time boundaries (start_date, end_date, last_computed_at)

        - Data values (array of data points)

        - Summary statistics

        - Segment information (when segmented)


        **Chart Types**


        Different charts may return data in slightly different formats:

        - Standard charts: values as arrays of data points with timestamps

        - Segmented charts: include segment information in the response

        - Cohort charts: see below


        **Cohort charts**


        Cohort-shaped charts (`cohort_explorer`, `prediction_explorer`,
        `subscription_retention`, ...)

        return `values` as `{cohort, period, value}` objects, where `period` is
        the **index into the

        `periods` array**, not a month number. Two things follow from that:


        - `periods[0]` describes the **cohort size** — a count of customers or
        subscriptions, with unit
          `#`. It is not the measure at month 0. On `cohort_explorer` its `display_name` is named after
          the `cohorting_date` selector (e.g. `New customers`).
        - The measure starts at `period: 1`, labelled by
        `periods[1].display_name` (typically `Month 0`).
          So `Month N` is at `period: N + 1`.

        Always read `periods[period].display_name`, `.unit` and `.scale` to
        interpret a data point rather

        than assuming `period` is the month number. On non-realtime charts
        (`realtime=false`) the same

        metadata is returned in `segments` instead of `periods`.


        **Filtering and Segmentation**


        Use the `/charts/{chart_name}/options` endpoint to discover available

        filters and segments for a specific chart before making requests.


        Segments and filters vary per chart and are separate lists — a dimension

        can be available as a filter but not as a segment. Requesting an

        unsupported segment or filter (or segmenting/filtering a chart that does

        not allow it) returns a 400 `parameter_error` that lists the supported

        segments. Check `get-chart-options-schema` first when unsure.


        Filter parameters vary by chart and can be passed as additional query
        parameters.


        **Aggregation**


        Use `aggregate` to request summary-only output for supported charts.

        When `aggregate` is provided, `values` is returned as an empty array and

        `summary` includes only the requested aggregate operations.


        **Incomplete data**

        For the most recent periods, data may be flagged as incomplete, and may
        not be appropriate to use for analysis.
         This endpoint requires the following permission(s): <code>charts_metrics:charts:read</code>. This endpoint belongs to the <strong>Charts & Metrics</strong> domain, which has a default rate limit of <strong>25 requests per minute</strong>.
      operationId: get-chart-data
      x-revenuecat-rate-limiting-domain: charts_metrics
      x-scopes:
        - charts_metrics:charts:read
      x-release-status: public
      tags:
        - Charts & Metrics
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: chart_name
          description: >
            Name of the chart to retrieve:

            - actives: Active (paying) subscriptions 

            - actives_movement: Period-over-period delta of active (paying)
            subscriptions

            - actives_new: New paying subscriptions, including trial
            conversions, resubscriptions, and product changes

            - arr: Annual recurring revenue

            - churn: Churn rate: active and expired subscriptions per period

            - cohort_explorer: allows measuring the performance of various
            cohort definitions over time for revenue, retained subscriptions,
            subscriptions that are still set to renew (not cancelled), and
            cohort LTV

            - conversion_to_paying: Conversion of new customers to paying

            - customers_new: Newly seen customers

            - initial_conversion: Initial conversion of new customers to paying
            within fixed windows (0, 3, 7, 14, 30 days, and unbounded)

            - ltv_per_customer: Realized LTV per customer, also known as ARPU,
            cohorted by first seen date

            - ltv_per_paying_customer: Realized LTV per paying customer, also
            known as ARPPU, cohorted by first seen date

            - mrr: Monthly recurring revenue

            - mrr_movement: Period-over-period delta of monthly recurring
            revenue

            - prediction_explorer: similar to cohort_explorer but including
            future predictions

            - refund_rate: transactions per period, refunds, refund rate

            - revenue: revenue (gross, net of taxes, or proceeds net of taxes
            and commissions) and number of transactions (subscriptions and
            non-subscriptions) per period

            - subscription_retention: Per-period retention of paying
            subscriptions by duration

            - subscription_status: Break down paying subscriptions, trials, MRR,
            ARR, or revenue by whether the subscription is set to renew,
            cancelled, or in billing recovery

            - trials: Active trials

            - trials_movement: Movement of active trials

            - trials_new: New trials

            - customers_active: Customers seen during the period (also known as
            DAU/MAU/WAU/etc.)

            - trial_conversion_rate: Number of trials started in a period and
            ratio of them converting to paying

            - non-subscription_purchases: Number of non-subscription purchases
            per period

            - ad_revenue: Estimated ad revenue per period (realtime only)

            - ad_impressions: Number of ad impressions per period (realtime
            only)

            - ad_clicks: Number of ad clicks per period (realtime only)

            - ad_monetized_customers: Customers who saw at least one monetized
            ad during the period, also known as daily ad-monetized users
            (realtime only)

            - ad_arpdau: Average ad revenue per daily ad-monetized customer
            (realtime only)

            - ad_rpm: Effective cost per mille (eCPM): ad revenue per thousand
            impressions (realtime only)

            - ad_fill_rate: Ratio of ad requests that were filled with an ad
            (realtime only)

            - ad_ctr: Ad click-through rate: clicks over impressions (realtime
            only)


            Charts marked as realtime only are served exclusively by Charts v3
            and

            require `realtime=true` (the default).
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            enum:
              - actives
              - actives_movement
              - actives_new
              - arr
              - churn
              - cohort_explorer
              - conversion_to_paying
              - customers_new
              - initial_conversion
              - ltv_per_customer
              - ltv_per_paying_customer
              - mrr
              - mrr_movement
              - prediction_explorer
              - refund_rate
              - revenue
              - subscription_retention
              - subscription_status
              - trials
              - trials_movement
              - trials_new
              - customers_active
              - trial_conversion_rate
              - non-subscription_purchases
              - ad_revenue
              - ad_impressions
              - ad_clicks
              - ad_monetized_customers
              - ad_arpdau
              - ad_rpm
              - ad_fill_rate
              - ad_ctr
            example: revenue
        - name: realtime
          description: >-
            Whether to request real-time (v3) charts. Defaults to true. Set to
            false to request the v2 charts.
          in: query
          schema:
            type: boolean
            default: true
        - name: filters
          description: JSON array of chart filters. Each filter is a ChartFilter object.
          in: query
          schema:
            type: string
          example: '[{"name":"country","values":["US","UK"]}]'
        - name: selectors
          description: JSON object of chart selectors.
          in: query
          schema:
            type: string
          example: '{"conversion_timeframe":"7_days","revenue_type":"proceeds"}'
        - name: aggregate
          description: >
            Comma-separated aggregate operations to return in `summary` without
            raw `values`.
          in: query
          style: form
          explode: false
          schema:
            type: array
            minItems: 1
            uniqueItems: true
            items:
              type: string
              enum:
                - average
                - total
            example: average,total
        - name: currency
          description: The currency to return metrics data in
          in: query
          schema:
            type: string
            enum:
              - USD
              - EUR
              - GBP
              - AUD
              - CAD
              - JPY
              - BRL
              - KRW
              - CNY
              - MXN
              - SEK
              - PLN
              - NZD
              - CHF
          example: EUR
        - name: resolution
          description: >
            Time resolution for the chart data.

            Use the chart options endpoint to discover available resolutions and
            their IDs.
          in: query
          schema:
            type: string
            example: '0'
        - name: start_date
          description: Start date for the data range (ISO 8601 format)
          in: query
          schema:
            type: string
            format: date
            example: '2024-01-01'
        - name: end_date
          description: End date for the data range (ISO 8601 format)
          in: query
          schema:
            type: string
            format: date
            example: '2024-12-31'
        - name: expand_periods
          description: >-
            Whether to expand the date range so the first period is complete
            (e.g. snap a weekly range back to the start of the week). Defaults
            to false, which only includes data from the exact start_date
            provided. Period labels are always aligned to period boundaries:
            with expand_periods=false and a mid-period start_date, the first
            period only aggregates data from start_date onwards and is marked as
            incomplete. Exception: charts of point-in-time (stock) metrics, such
            as active subscriptions or MRR, ignore this parameter entirely.
            Their values are snapshots measured exactly at each period boundary,
            so the first data point is always measured at the start of the
            period containing start_date (which can fall before start_date) and
            is not marked as incomplete, since a snapshot cannot be partial.
          in: query
          schema:
            type: boolean
            default: false
        - name: segment
          description: >
            Segment the data by this dimension. Must be one of the segments
            returned

            by the chart options schema endpoint for this chart; segments vary
            per

            chart, and unsupported segments return a 400 `parameter_error`
            listing

            the supported ones.
          in: query
          schema:
            type: string
            example: country
        - name: limit_num_segments
          description: >
            If set, limits the number of segments returned to the top N by
            value.

            All remaining segments are aggregated into an "Other" segment.

            Only applies when a segment is specified.
          in: query
          schema:
            type: integer
            minimum: 1
            example: 10
        - name: include_annotations
          in: query
          required: false
          description: >-
            When true, includes chart annotations for the project in the
            response, filtered to the chart's date window.
          schema:
            type: boolean
            default: false
            example: true
      responses:
        '200':
          description: Chart data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartData'
          headers:
            RevenueCat-Rate-Limit-Current-Usage:
              $ref: '#/components/headers/RateLimitCurrentUsage'
            RevenueCat-Rate-Limit-Current-Limit:
              $ref: '#/components/headers/RateLimitCurrentLimit'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/InternalError'
  /projects/{project_id}/charts/{chart_name}/options:
    get:
      summary: Get available options for a chart
      description: >-
        Returns configuration options for a specific chart.


        Use this endpoint to discover:

        - **Resolutions**: Available time granularities (day, week, month, etc.)

        - **Segments**: Dimensions you can segment the data by (country, store,
        product, etc.)

        - **Filters**: Available filters and their possible values


        The options returned are specific to the chart and may vary based on

        your project's data and configuration.


        **Usage**


        Call this endpoint before requesting chart data to:

        1. Build dynamic filter UIs

        2. Validate parameters before making chart data requests

        3. Discover available dimensions for analysis

        . This endpoint requires the following permission(s):
        <code>charts_metrics:charts:read</code>. This endpoint belongs to the
        <strong>Charts & Metrics</strong> domain, which has a default rate limit
        of <strong>25 requests per minute</strong>.
      operationId: get-chart-options
      x-revenuecat-rate-limiting-domain: charts_metrics
      x-scopes:
        - charts_metrics:charts:read
      x-release-status: public
      tags:
        - Charts & Metrics
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: chart_name
          description: >
            Name of the chart to retrieve:

            - actives: Active (paying) subscriptions 

            - actives_movement: Period-over-period delta of active (paying)
            subscriptions

            - actives_new: New paying subscriptions, including trial
            conversions, resubscriptions, and product changes

            - arr: Annual recurring revenue

            - churn: Churn rate: active and expired subscriptions per period

            - cohort_explorer: allows measuring the performance of various
            cohort definitions over time for revenue, retained subscriptions,
            subscriptions that are still set to renew (not cancelled), and
            cohort LTV

            - conversion_to_paying: Conversion of new customers to paying

            - customers_new: Newly seen customers

            - initial_conversion: Initial conversion of new customers to paying
            within fixed windows (0, 3, 7, 14, 30 days, and unbounded)

            - ltv_per_customer: Realized LTV per customer, also known as ARPU,
            cohorted by first seen date

            - ltv_per_paying_customer: Realized LTV per paying customer, also
            known as ARPPU, cohorted by first seen date

            - mrr: Monthly recurring revenue

            - mrr_movement: Period-over-period delta of monthly recurring
            revenue

            - prediction_explorer: similar to cohort_explorer but including
            future predictions

            - refund_rate: transactions per period, refunds, refund rate

            - revenue: revenue (gross, net of taxes, or proceeds net of taxes
            and commissions) and number of transactions (subscriptions and
            non-subscriptions) per period

            - subscription_retention: Per-period retention of paying
            subscriptions by duration

            - subscription_status: Break down paying subscriptions, trials, MRR,
            ARR, or revenue by whether the subscription is set to renew,
            cancelled, or in billing recovery

            - trials: Active trials

            - trials_movement: Movement of active trials

            - trials_new: New trials

            - customers_active: Customers seen during the period (also known as
            DAU/MAU/WAU/etc.)

            - trial_conversion_rate: Number of trials started in a period and
            ratio of them converting to paying

            - non-subscription_purchases: Number of non-subscription purchases
            per period

            - ad_revenue: Estimated ad revenue per period (realtime only)

            - ad_impressions: Number of ad impressions per period (realtime
            only)

            - ad_clicks: Number of ad clicks per period (realtime only)

            - ad_monetized_customers: Customers who saw at least one monetized
            ad during the period, also known as daily ad-monetized users
            (realtime only)

            - ad_arpdau: Average ad revenue per daily ad-monetized customer
            (realtime only)

            - ad_rpm: Effective cost per mille (eCPM): ad revenue per thousand
            impressions (realtime only)

            - ad_fill_rate: Ratio of ad requests that were filled with an ad
            (realtime only)

            - ad_ctr: Ad click-through rate: clicks over impressions (realtime
            only)


            Charts marked as realtime only are served exclusively by Charts v3
            and

            require `realtime=true` (the default).
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            enum:
              - actives
              - actives_movement
              - actives_new
              - arr
              - churn
              - cohort_explorer
              - conversion_to_paying
              - customers_new
              - initial_conversion
              - ltv_per_customer
              - ltv_per_paying_customer
              - mrr
              - mrr_movement
              - prediction_explorer
              - refund_rate
              - revenue
              - subscription_retention
              - subscription_status
              - trials
              - trials_movement
              - trials_new
              - customers_active
              - trial_conversion_rate
              - non-subscription_purchases
              - ad_revenue
              - ad_impressions
              - ad_clicks
              - ad_monetized_customers
              - ad_arpdau
              - ad_rpm
              - ad_fill_rate
              - ad_ctr
            example: revenue
        - name: realtime
          description: >-
            Whether to request real-time (v3) charts. Defaults to true. Set to
            false to request the v2 charts.
          in: query
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Chart options retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartOptions'
          headers:
            RevenueCat-Rate-Limit-Current-Usage:
              $ref: '#/components/headers/RateLimitCurrentUsage'
            RevenueCat-Rate-Limit-Current-Limit:
              $ref: '#/components/headers/RateLimitCurrentLimit'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    OverviewMetrics:
      type: object
      required:
        - metrics
        - object
        - currency
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - overview_metrics
          type: string
        metrics:
          description: Details about each overview metric.
          items:
            $ref: '#/components/schemas/OverviewMetric'
          type: array
        currency:
          description: >-
            The currency that monetary metric values are expressed in. Defaults
            to USD. When the request is authenticated with a developer JWT/OAuth
            token and no `currency` query parameter is provided, this reflects
            the developer's saved dashboard display currency.
          type: string
          enum:
            - USD
            - EUR
            - GBP
            - AUD
            - CAD
            - JPY
            - BRL
            - KRW
            - CNY
            - MXN
            - SEK
            - PLN
            - NZD
            - CHF
          example: EUR
      additionalProperties: false
    RevenueMetric:
      type: object
      additionalProperties: false
      required:
        - object
        - start_date
        - end_date
        - currency
        - value
        - revenue_type
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          type: string
          enum:
            - revenue_metric
          example: revenue_metric
        start_date:
          description: Start date of the revenue range, inclusive (ISO 8601 format).
          type: string
          format: date
          nullable: false
          example: '2026-01-01'
        end_date:
          description: End date of the revenue range, inclusive (ISO 8601 format).
          type: string
          format: date
          nullable: false
          example: '2026-01-31'
        currency:
          description: The ISO 4217 currency code that the revenue value is expressed in.
          type: string
          nullable: false
          example: USD
        value:
          description: >-
            Revenue for the date range, expressed in `currency`, for the revenue
            definition selected by the `revenue_type` request parameter.
            Two-decimal precision.
          type: number
          nullable: false
          example: 12345.67
        revenue_type:
          description: >-
            The revenue definition that `value` represents: `revenue` (gross),
            `revenue_net_of_taxes`, or `proceeds` (net of both taxes and store
            commission). Matches the `revenue_type` request parameter.
          type: string
          enum:
            - revenue
            - revenue_net_of_taxes
            - proceeds
          nullable: false
          example: proceeds
    ChartData:
      type: object
      description: Chart data response containing time-series data and metadata
      required:
        - object
        - category
        - display_type
        - display_name
        - description
        - resolution
        - values
        - yaxis
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - chart_data
          type: string
        category:
          description: Category the chart belongs to
          type: string
          example: revenue
        display_type:
          description: Type of chart visualization
          type: string
          example: line
        display_name:
          description: Human-readable name of the chart
          type: string
          example: Revenue
        description:
          description: Description of what the chart shows
          type: string
        documentation_link:
          description: Link to documentation for this chart
          nullable: true
          type: string
        last_computed_at:
          description: Timestamp when the chart data was last computed (ms since epoch)
          nullable: true
          type: integer
          format: int64
        start_date:
          description: Start date of the data range (ms since epoch)
          nullable: true
          type: integer
          format: int64
        end_date:
          description: End date of the data range (ms since epoch)
          nullable: true
          type: integer
          format: int64
        yaxis_currency:
          description: Currency used for monetary values
          type: string
          example: USD
        filtering_allowed:
          description: Whether filtering is allowed for this chart
          type: boolean
        segmenting_allowed:
          description: Whether segmentation is allowed for this chart
          type: boolean
        resolution:
          description: Time resolution of the data points
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
          example: day
        values:
          description: >
            Chart data points. Structure varies by chart type - can be arrays of
            numbers or objects with

            timestamps and values. Returned as an empty array when aggregate
            operations are requested.


            Cohort charts (`cohort_explorer`, `prediction_explorer`,
            `subscription_retention`, ...) return

            objects shaped `{cohort, period, value}`, optionally with
            `confidence`, `scale` and

            `incomplete`. `period` is the index into the `periods` array, not a
            month number: `periods[0]`

            is the cohort size (a customer or subscription count, unit `#`) and
            the measure starts at

            `period: 1`, which `periods[1].display_name` labels (typically
            `Month 0`). Read

            `periods[period]` for the label, unit and scale of each point
            instead of assuming `period` is

            the month number.
          type: array
          items:
            oneOf:
              - type: array
                items:
                  type: number
                  nullable: true
              - type: object
                additionalProperties: true
        summary:
          description: Summary statistics for the chart data
          nullable: true
          type: object
          additionalProperties: true
        yaxis:
          description: Y-axis configuration including unit
          type: string
          example: $
        segments:
          description: >
            Segment information when data is segmented, one entry per series in
            `values`. Non-realtime

            (`realtime=false`) cohort charts return their column metadata here
            instead of in `periods`.
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/ChartSeries'
        segments_limit:
          description: Maximum number of segments returned
          nullable: true
          type: integer
        periods:
          description: >
            Column metadata for cohort-shaped charts (`cohort_explorer`,
            `prediction_explorer`,

            `subscription_retention`, ...) on realtime charts. Positional: entry
            `i` describes the data

            points with `period: i` in `values`, so `len(periods)` is one more
            than the number of measure

            periods. `periods[0]` always describes the cohort size (unit `#`),
            and `periods[1]` is the

            first measure period (typically `Month 0`).
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/ChartSeries'
        measures:
          description: Measure definitions for the chart (v3 charts)
          nullable: true
          type: array
          items:
            type: object
            additionalProperties: true
        user_selectors:
          description: >-
            Currently selected values for user-configurable selectors (keyed by
            selector name)
          nullable: true
          type: object
          additionalProperties:
            type: string
        unsupported_params:
          description: >-
            Deprecated and always `null`. Unsupported parameters are rejected
            with a 400 error instead of being reported in the response.
          deprecated: true
          nullable: true
          type: object
          properties:
            filters:
              type: array
              items:
                type: string
            segment:
              type: string
              nullable: true
        annotations:
          description: >-
            Chart annotations for the project, filtered to the chart's date
            window. Only present when include_annotations=true is passed in the
            request.
          type: array
          items:
            $ref: '#/components/schemas/ChartAnnotation'
      additionalProperties: false
    ChartOptions:
      type: object
      description: Available options for filtering and segmenting a chart
      required:
        - object
        - resolutions
        - segments
        - filters
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - chart_options
          type: string
        resolutions:
          description: Available time resolutions for the chart
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Resolution ID to use in requests
              display_name:
                type: string
                description: Human-readable name
            required:
              - id
              - display_name
          example:
            - id: '0'
              display_name: day
            - id: '1'
              display_name: week
            - id: '2'
              display_name: month
        segments:
          description: Available segmentation options
          type: array
          items:
            $ref: '#/components/schemas/ChartSegmentOption'
        filters:
          description: Available filter options
          type: array
          items:
            $ref: '#/components/schemas/ChartFilterOption'
        user_selectors:
          description: User-configurable selectors for the chart (keyed by selector name)
          nullable: true
          type: object
          additionalProperties:
            type: object
            properties:
              default:
                type: string
                description: Default value for the selector
              display_name:
                type: string
                description: Human-readable name
              options:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    display_name:
                      type: string
                  required:
                    - id
                    - display_name
      additionalProperties: false
    OverviewMetric:
      type: object
      required:
        - id
        - name
        - description
        - unit
        - period
        - value
        - last_updated_at
        - last_updated_at_iso8601
        - object
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - overview_metric
          type: string
        id:
          description: Id of the overview metric
          nullable: false
          type: string
          minLength: 1
          maxLength: 255
          example: active_trials
        name:
          description: Display name of the overview metric
          nullable: false
          type: string
          example: Active Trials
        description:
          description: Description of the overview metric
          nullable: false
          type: string
        unit:
          description: Unit of the overview metric
          nullable: false
          type: string
          example: $
        period:
          description: >-
            Length of time during which metric data is collected in ISO 8601
            format. Zero period means metric data was collected now
          nullable: false
          type: string
          enum:
            - P0D
            - P28D
          example: P0D
        value:
          description: Value of the overview metric
          nullable: false
          type: number
          example: 34765
        last_updated_at:
          description: Last time the overview metric was updated in ms since epoch
          nullable: true
          type: integer
          format: int64
          example: 1658399423658
        last_updated_at_iso8601:
          description: >-
            Last time the overview metric was updated datetime in ISO 8601
            format
          nullable: true
          type: string
          format: date-time
          example: '2022-10-13T09:45:00.123Z'
      additionalProperties: false
    Error:
      type: object
      required:
        - type
        - message
        - retryable
        - object
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - error
          type: string
          example: error
        type:
          description: The error type
          type: string
          nullable: false
          enum:
            - parameter_error
            - resource_already_exists
            - resource_missing
            - idempotency_error
            - rate_limit_error
            - authentication_error
            - authorization_error
            - store_error
            - server_error
            - resource_locked_error
            - unprocessable_entity_error
            - invalid_request
            - entity_references_archived_entities
          example: parameter_error
        param:
          description: >-
            If the error is parameter-specific, the parameter related to the
            error
          type: string
          nullable: true
          example: customer_id
        doc_url:
          description: A URL to more information about the error reported
          type: string
          nullable: false
          example: https://errors.rev.cat/parameter-error
        message:
          type: string
          description: A message describing the reason of the error
          nullable: false
          example: id shouldn't be longer than 1,500 characters
        retryable:
          description: Indicates if the error is retryable or not
          type: boolean
          nullable: false
          example: false
        backoff_ms:
          description: >-
            The ms the client should wait before retrying the request. Only
            present for retryable errors.
          type: integer
          nullable: true
          example: null
        referenced_object_ids:
          description: >-
            The IDs of related objects relevant to the error, such as the
            archived entities that need to be made active before the operation
            can succeed.
          type: array
          items:
            type: string
          example:
            - prodabcd1234
            - prodwxyz5678
      additionalProperties: false
    ChartSeries:
      type: object
      description: >-
        Metadata describing one series (a segment, measure, or cohort period) of
        a chart, used to label and format the matching data points in `values`.
      required:
        - display_name
      properties:
        display_name:
          description: >-
            Human-readable label for the series. For cohort `periods`, index 0
            is named after the cohorting date (e.g. `New customers`) and later
            indices after the cohort age (e.g. `Month 0`, `Month 1`).
          type: string
          example: Month 0
        description:
          description: Longer explanation of what the series measures.
          type: string
          nullable: true
          example: Gross revenue generated by the cohort.
        unit:
          description: >-
            Unit the values of this series are expressed in. `#` means the
            values are counts, not amounts of the chart's measure.
          type: string
          example: $
        decimal_precision:
          description: >-
            Number of decimal places the values of this series should be
            rendered with.
          type: integer
          minimum: 0
          example: 2
        scale:
          description: >-
            Whether the values of this series are absolute amounts or
            percentages of a baseline.
          type: string
          enum:
            - absolute
            - relative
          example: absolute
        chartable:
          description: Whether the series is meaningful to plot.
          type: boolean
          example: true
        tabulable:
          description: Whether the series is meaningful to show as a table column.
          type: boolean
          example: true
        is_total:
          description: Whether the series aggregates all the others.
          type: boolean
          example: false
        is_other:
          description: Whether the series aggregates the segments beyond `segments_limit`.
          type: boolean
          example: false
        nested_measures:
          description: >-
            Per-measure metadata, when a segmented series carries more than one
            measure.
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ChartSeries'
      additionalProperties: true
    ChartAnnotation:
      type: object
      description: A chart annotation marking a significant event on charts.
      required:
        - object
        - id
        - description
        - start_date
        - end_date
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          type: string
          enum:
            - chart_annotation
          example: chart_annotation
        id:
          description: The ID of the chart annotation.
          type: string
          example: chartannot1a2b3c
        description:
          description: Human-readable description of the event this annotation represents.
          type: string
          example: App version 2.0 released
        start_date:
          description: The start date of the annotated period (ISO 8601 date format).
          type: string
          format: date
          example: '2024-01-15'
        end_date:
          description: >-
            The end date of the annotated period (ISO 8601 date format), or null
            if the annotation is a single-day event.
          type: string
          format: date
          nullable: true
          example: '2024-01-20'
      additionalProperties: false
    ChartSegmentOption:
      type: object
      description: A segmentation option for a chart
      required:
        - object
        - id
        - display_name
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - chart_segment_option
          type: string
        id:
          description: Unique identifier for the segment option
          type: string
          example: country
        display_name:
          description: Human-readable name for the segment option
          type: string
          example: Country
        group_display_name:
          description: Group name for organizing segment options
          nullable: true
          type: string
          example: Geography
      additionalProperties: true
    ChartFilterOption:
      type: object
      description: A filter option for a chart
      required:
        - object
        - id
        - display_name
        - options
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - chart_filter_option
          type: string
        id:
          description: Unique identifier for the filter
          type: string
          example: country
        display_name:
          description: Human-readable name for the filter
          type: string
          example: Country
        group_display_name:
          description: Group name for organizing filter options
          nullable: true
          type: string
          example: Geography
        options:
          description: Available values for this filter
          type: array
          items:
            type: object
            required:
              - id
              - display_name
            additionalProperties: true
            properties:
              id:
                description: Unique identifier for the option value
                type: string
                example: US
              display_name:
                description: Human-readable name for the option value
                type: string
                example: United States
      additionalProperties: true
  headers:
    RateLimitCurrentUsage:
      required: true
      description: >-
        The current number of requests used for the current limit (including the
        current request).
      schema:
        type: integer
      example: 25
    RateLimitCurrentLimit:
      required: true
      description: The rate limit for this endpoint, expressed in requests per minute.
      schema:
        type: integer
      example: 30
    RateLimitRetryAfter:
      required: true
      description: >-
        The number of seconds to wait before retrying a rate limited
        request.Only present when a request is rate limited.
      schema:
        type: integer
      example: 10
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - parameter_error
                      - invalid_request
          examples:
            parameter_error:
              value:
                object: error
                type: parameter_error
                param: customer_id
                message: id is too long
                retryable: false
                doc_url: https://errors.rev.cat/parameter-error
            invalid_request:
              value:
                object: error
                type: invalid_request
                message: Content-Type not application/json
                retryable: false
                doc_url: https://errors.rev.cat/invalid-request
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - authentication_error
            example:
              object: error
              type: authentication_error
              message: Invalid API key
              retryable: false
              doc_url: https://errors.rev.cat/authentication-error
    Forbidden:
      description: Access denied
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - authorization_error
            example:
              object: error
              type: authorization_error
              message: You're not authorized to access this resource
              retryable: false
              doc_url: https://errors.rev.cat/authorization-error
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - resource_missing
            example:
              object: error
              type: resource_missing
              message: Resource not found
              retryable: false
              doc_url: https://errors.rev.cat/resource-missing
    Locked:
      description: Locked
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - resource_locked_error
            example:
              object: error
              type: resource_locked_error
              message: The resource is currently being modified by a concurrent request
              retryable: true
              doc_url: https://errors.rev.cat/resource-locked-error
              backoff_ms: 1000
    RateLimited:
      description: >-
        The request could not be completed because the rate limiting domain for
        this endpoint is currently at its limit for this project.
      headers:
        RevenueCat-Rate-Limit-Current-Usage:
          $ref: '#/components/headers/RateLimitCurrentUsage'
        RevenueCat-Rate-Limit-Current-Limit:
          $ref: '#/components/headers/RateLimitCurrentLimit'
        Retry-After:
          $ref: '#/components/headers/RateLimitRetryAfter'
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - rate_limit_error
            example:
              object: error
              type: rate_limit_error
              message: Rate limit exceeded
              retryable: true
              doc_url: https://errors.rev.cat/rate-limit-error
              backoff_ms: 1000
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - server_error
            example:
              object: error
              type: server_error
              message: There was an internal server error
              retryable: true
              doc_url: https://errors.rev.cat/server-error
              backoff_ms: 1000
  securitySchemes:
    BearerAuth:
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication. Allowed headers -- Authorization: Bearer
        <api_key>
      scheme: bearer
      type: http
