info:
  title: Developer API
  version: 2.0.0
security:
  - BearerAuth: []
servers:
  - url: https://api.revenuecat.com/v2
openapi: 3.0.3
tags:
  - name: Invoice
    description: Operations about invoices.
paths:
  /projects/{project_id}/customers/{customer_id}/invoices:
    get:
      summary: Get a list of the customer's invoices
      operationId: list-customer-invoices
      x-revenuecat-rate-limiting-domain: customer_information
      x-scopes:
        - customer_information:invoices:read
      x-release-status: public
      tags:
        - Invoice
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: customer_id
          in: path
          description: ID of the customer
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 1500
            example: 19b8de26-77c1-49f1-aa18-019a391603e2
        - name: starting_after
          in: query
          required: false
          description: >-
            Pagination cursor. Pass the id of the last item from the previous
            page to fetch the next page; omit for the first page.
          schema:
            type: string
            example: ent12354
        - name: limit
          in: query
          required: false
          description: >-
            Maximum number of items to return per page. Values below 1 or above
            100 are clamped to that range rather than rejected.
          schema:
            type: integer
            example: 10
            default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomerInvoices'
          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>customer_information:invoices:read</code>. This endpoint belongs
        to the <strong>Customer Information</strong> domain, which has a default
        rate limit of <strong>480 requests per minute</strong>.
  /projects/{project_id}/customers/{customer_id}/invoices/{invoice_id}/file:
    get:
      summary: Get an invoice
      operationId: get-invoice
      x-revenuecat-rate-limiting-domain: customer_information
      x-scopes:
        - customer_information:invoices:read
      x-release-status: public
      tags:
        - Invoice
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: customer_id
          in: path
          description: ID of the customer
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 1500
            example: 19b8de26-77c1-49f1-aa18-019a391603e2
        - name: invoice_id
          in: path
          description: ID of the invoice
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 1500
            example: rcbin1a2b3c4d5e
      responses:
        '302':
          description: File found. Needs to be downloaded from the location header
          headers:
            location:
              description: The URL to download the invoice pdf
              schema:
                type: string
                format: uri
        '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>customer_information:invoices:read</code>. This endpoint belongs
        to the <strong>Customer Information</strong> domain, which has a default
        rate limit of <strong>480 requests per minute</strong>.
components:
  schemas:
    ListCustomerInvoices:
      type: object
      required:
        - items
        - next_page
        - object
        - url
      title: CustomerInvoicesList
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value. Always has the value `list`.
          enum:
            - list
          type: string
        items:
          description: Details about each object.
          items:
            $ref: '#/components/schemas/Invoice'
          type: array
        next_page:
          description: >-
            URL to access the next page of the customer's invoice. If not
            present / null, there is no next page
          type: string
          nullable: true
          example: >-
            /v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/invoices?starting_after=rcbin1a2b3c4d5e
        url:
          description: The URL where this list can be accessed.
          maxLength: 5000
          type: string
          example: >-
            /v2/projects/proj1ab2c3d4/customers/19b8de26-77c1-49f1-aa18-019a391603e2/invoices
      additionalProperties: false
    Invoice:
      type: object
      required:
        - id
        - total_amount
        - line_items
        - issued_at
        - paid_at
        - invoice_url
        - object
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - invoice
          type: string
        id:
          description: The id of the invoice
          nullable: false
          type: string
          minLength: 1
          maxLength: 255
          example: rcbin1a2b3c4d5e
        total_amount:
          $ref: '#/components/schemas/MonetaryAmount'
        line_items:
          description: >-
            List of line items that are part of the invoice. Each line item
            represents a product that was purchased.
          title: InvoiceLiteItemList
          nullable: false
          items:
            $ref: '#/components/schemas/InvoiceLineItem'
          type: array
        issued_at:
          description: The date when the invoiced was issued in ms since epoch
          nullable: false
          type: integer
          format: int64
          example: 1658399423658
        paid_at:
          description: The date when the invoiced was paid in ms since epoch
          nullable: true
          type: integer
          format: int64
          example: 1658399423658
        invoice_url:
          description: URL to download the invoice pdf
          nullable: true
          type: string
          example: >-
            https://api.revenuecat.com/v2/projects/proj1ab2c3d4/customers/cust1ab2c3d4/invoices/inv1ab2c3d4/file
      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
    MonetaryAmount:
      type: object
      required:
        - currency
        - gross
        - tax
        - proceeds
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        gross:
          description: Total revenue generated (excluding taxes and commission)
          nullable: false
          type: number
          example: 9.99
        commission:
          description: >-
            Store commission or payment processor fees deducted from gross
            revenue (if any)
          nullable: false
          type: number
          example: 2.99
        tax:
          description: Estimated taxes deducted from gross revenue
          nullable: false
          type: number
          example: 0.75
        proceeds:
          description: Net revenue after store commission / fees and taxes
          nullable: false
          type: number
          example: 6.25
      additionalProperties: true
    InvoiceLineItem:
      type: object
      required:
        - product_identifier
        - product_display_name
        - product_duration
        - quantity
        - unit_amount
        - object
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the same value.
          enum:
            - invoice.line_item
          type: string
        product_identifier:
          description: The product identifier
          nullable: false
          type: string
          minLength: 1
          maxLength: 255
          example: rc_1w_199
        product_display_name:
          description: The display name of the product
          nullable: true
          type: string
          minLength: 1
          maxLength: 1500
          example: Premium Monthly 2023
        product_duration:
          type: string
          pattern: >-
            ^(-?)P(?=\d|T\d)(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)([DW]))?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$
          nullable: true
          description: The duration of the subscription in ISO-8601 standard
          example: P1M
        quantity:
          description: Total purchased items
          nullable: false
          type: integer
          example: 1
        unit_amount:
          $ref: '#/components/schemas/MonetaryAmount'
      additionalProperties: false
    Currency:
      type: string
      description: ISO 4217 currency code
      nullable: false
      example: USD
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BRL
        - BSD
        - BTC
        - BTN
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHF
        - CLF
        - CLP
        - CNH
        - CNY
        - COP
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GGP
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - IMP
        - INR
        - IQD
        - IRR
        - ISK
        - JEP
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRU
        - MUR
        - MVR
        - MWK
        - MXN
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLL
        - SOS
        - SRD
        - SSP
        - STD
        - STN
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VEF
        - VES
        - VND
        - VUV
        - WST
        - XAF
        - XAG
        - XAU
        - XCD
        - XDR
        - XOF
        - XPD
        - XPF
        - XPT
        - YER
        - ZAR
        - ZMW
        - ZWL
  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
