info:
  title: Developer API
  version: 2.0.0
security:
  - BearerAuth: []
servers:
  - url: https://api.revenuecat.com/v2
openapi: 3.0.3
tags:
  - name: Integration
    description: Operations about integrations.
paths:
  /projects/{project_id}/integrations/webhooks:
    get:
      summary: List webhook integrations
      operationId: list-webhook-integrations
      x-revenuecat-rate-limiting-domain: project_configuration
      x-scopes:
        - project_configuration:integrations:read
      x-release-status: public
      tags:
        - Integration
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - 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/ListWebhookIntegrations'
          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>project_configuration:integrations:read</code>. This endpoint
        belongs to the <strong>Project Configuration</strong> domain, which has
        a default rate limit of <strong>60 requests per minute</strong>.
    post:
      summary: Create a webhook integration
      operationId: create-webhook-integration
      x-revenuecat-rate-limiting-domain: project_configuration
      x-scopes:
        - project_configuration:integrations:read_write
      x-release-status: public
      tags:
        - Integration
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookIntegrationInput'
              additionalProperties: false
      responses:
        '201':
          description: Webhook integration created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookIntegration'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '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>project_configuration:integrations:read_write</code>. This
        endpoint belongs to the <strong>Project Configuration</strong> domain,
        which has a default rate limit of <strong>60 requests per
        minute</strong>.
  /projects/{project_id}/integrations/webhooks/{webhook_integration_id}:
    get:
      summary: Get a webhook integration
      operationId: get-webhook-integration
      x-revenuecat-rate-limiting-domain: project_configuration
      x-scopes:
        - project_configuration:integrations:read
      x-release-status: public
      tags:
        - Integration
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: webhook_integration_id
          in: path
          description: The ID of the webhook integration
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
          example: wh_1234567890abcdef
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookIntegration'
          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>project_configuration:integrations:read</code>. This endpoint
        belongs to the <strong>Project Configuration</strong> domain, which has
        a default rate limit of <strong>60 requests per minute</strong>.
    post:
      summary: Update a webhook integration
      operationId: update-webhook-integration
      x-revenuecat-rate-limiting-domain: project_configuration
      x-scopes:
        - project_configuration:integrations:read_write
      x-release-status: public
      tags:
        - Integration
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: webhook_integration_id
          in: path
          description: The ID of the webhook integration
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
          example: wh_1234567890abcdef
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookIntegrationInput'
              additionalProperties: false
      responses:
        '200':
          description: Webhook integration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookIntegration'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '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>project_configuration:integrations:read_write</code>. This
        endpoint belongs to the <strong>Project Configuration</strong> domain,
        which has a default rate limit of <strong>60 requests per
        minute</strong>.
    delete:
      summary: Delete a webhook integration
      operationId: delete-webhook-integration
      x-revenuecat-rate-limiting-domain: project_configuration
      x-scopes:
        - project_configuration:integrations:read_write
      x-release-status: public
      tags:
        - Integration
      parameters:
        - name: project_id
          description: ID of the project
          required: true
          in: path
          schema:
            type: string
            maxLength: 255
            example: proj1ab2c3d4
        - name: webhook_integration_id
          in: path
          description: The ID of the webhook integration
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
          example: wh_1234567890abcdef
      responses:
        '200':
          description: Webhook integration deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedObject'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '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>project_configuration:integrations:read_write</code>. This
        endpoint belongs to the <strong>Project Configuration</strong> domain,
        which has a default rate limit of <strong>60 requests per
        minute</strong>.
components:
  schemas:
    ListWebhookIntegrations:
      required:
        - items
        - object
        - url
      title: WebhookIntegrationList
      type: object
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the

            same value.
          enum:
            - list
          type: string
        items:
          description: Webhook integrations configured for the project.
          type: array
          items:
            $ref: '#/components/schemas/WebhookIntegration'
        next_page:
          description: >-
            URL to access the next page of webhook integrations. If not present
            / null, there is no next page
          type: string
          nullable: true
          example: >-
            /v2/projects/proj1ab2c3d4/integrations/webhooks?starting_after=whintgr1a2b3c4d
        url:
          description: The URL where this list can be accessed.
          maxLength: 5000
          type: string
          example: /v2/projects/proj1ab2c3d4/integrations/webhooks
      additionalProperties: false
    CreateWebhookIntegrationInput:
      type: object
      required:
        - name
        - url
      properties:
        name:
          description: The display name of the webhook integration
          type: string
          minLength: 1
          maxLength: 1500
          example: Customer updates webhook
        url:
          description: The URL RevenueCat will send webhook notifications to
          type: string
          format: uri
          maxLength: 5000
          example: https://hooks.example.com/revenuecat
        authorization_header:
          description: >-
            Optional authorization header that will be sent with webhook
            notifications
          type: string
          nullable: true
          maxLength: 5000
          example: Bearer 123456
        environment:
          description: The environment the webhook integration is configured for
          type: string
          nullable: true
          enum:
            - production
            - sandbox
            - null
        event_types:
          description: Event types that will trigger the webhook
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/WebhookEventType'
        app_id:
          description: The ID of the app the webhook integration is scoped to
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: app_1234567890abcdef
      additionalProperties: false
    WebhookIntegration:
      type: object
      required:
        - id
        - name
        - url
        - project_id
        - object
        - created_at
        - app_id
        - environment
      properties:
        object:
          description: >-
            String representing the object's type. Objects of the same type
            share the

            same value.
          enum:
            - webhook_integration
          type: string
        id:
          description: The ID of the webhook integration
          type: string
          minLength: 1
          maxLength: 255
          example: wh_1234567890abcdef
        project_id:
          description: The ID of the project the webhook integration belongs to
          type: string
          minLength: 1
          maxLength: 255
          example: proj_1234567890abcdef
        name:
          description: The display name of the webhook integration
          type: string
          minLength: 1
          maxLength: 1500
          example: Customer updates webhook
        url:
          description: The URL RevenueCat will send webhook notifications to
          type: string
          format: uri
          maxLength: 5000
          example: https://hooks.example.com/revenuecat
        environment:
          description: >-
            The environment the webhook integration is configured for. Only
            events for the selected environment will be sent.
          type: string
          nullable: true
          enum:
            - production
            - sandbox
            - null
        event_types:
          description: >-
            Event types that will trigger the webhook. Only events for the
            selected event types will be sent.
          type: array
          nullable: true
          items:
            type: string
            description: >-
              The event type. Known values include: initial_purchase, renewal,
              product_change, cancellation, billing_issue,
              non_renewing_purchase, uncancellation, transfer,
              subscription_paused, expiration, subscription_extended,
              invoice_issuance, temporary_entitlement_grant, refund_reversed,
              virtual_currency_transaction. New event types may be added in the
              future.
            example: initial_purchase
        app_id:
          description: >-
            The ID of the app the webhook integration is scoped to. If not
            provided, the webhook integration will be scoped to all apps in the
            project.
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: app_1234567890abcdef
        signing_secret:
          description: >-
            The plaintext HMAC signing secret. Only returned in the response to
            a rotate request.
          type: string
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
        created_at:
          description: >-
            The timestamp in ms since epoch when the webhook integration was
            created
          type: integer
          format: int64
          example: 1658399423658
      additionalProperties: false
    UpdateWebhookIntegrationInput:
      type: object
      properties:
        name:
          description: The display name of the webhook integration
          type: string
          minLength: 1
          maxLength: 1500
          example: Customer updates webhook
        url:
          description: The URL RevenueCat will send webhook notifications to
          type: string
          format: uri
          maxLength: 5000
          example: https://hooks.example.com/revenuecat
        authorization_header:
          description: >-
            Optional authorization header that will be sent with webhook
            notifications
          type: string
          nullable: true
          maxLength: 5000
          example: Bearer 123456
        environment:
          description: The environment the webhook integration is configured for
          type: string
          nullable: true
          enum:
            - production
            - sandbox
            - null
        event_types:
          description: Event types that will trigger the webhook
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/WebhookEventType'
        app_id:
          description: The ID of the app the webhook integration is scoped to
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: app_1234567890abcdef
      additionalProperties: false
    DeletedObject:
      type: object
      required:
        - object
        - id
        - deleted_at
      properties:
        object:
          description: The type of the deleted object
          enum:
            - app
            - chart_annotation
            - customer
            - discount
            - entitlement
            - experiment
            - offering
            - package
            - paywall
            - product
            - virtual_currency
            - webhook_integration
          type: string
        id:
          description: The ID of the deleted object
          nullable: false
          type: string
        deleted_at:
          nullable: false
          type: integer
          format: int64
          description: The date when the object was deleted in ms since epoch
          example: 1658399423658
      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
    WebhookEventType:
      type: string
      description: The type of event that triggers the webhook
      example: initial_purchase
      enum:
        - initial_purchase
        - renewal
        - product_change
        - cancellation
        - billing_issue
        - non_renewing_purchase
        - uncancellation
        - transfer
        - subscription_paused
        - expiration
        - subscription_extended
        - invoice_issuance
        - temporary_entitlement_grant
        - refund_reversed
        - virtual_currency_transaction
  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
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - resource_already_exists
                      - idempotency_error
                      - invalid_request
          examples:
            resource_already_exists:
              value:
                object: error
                type: resource_already_exists
                message: Name is already taken
                retryable: false
                doc_url: https://errors.rev.cat/resource-already-exists
            idempotency_error:
              value:
                object: error
                type: idempotency_error
                message: Idempotency key already used for a different request
                retryable: false
                doc_url: https://errors.rev.cat/idempotency-error
            invalid_request:
              value:
                object: error
                type: invalid_request
                message: Request conflicts with the current resource state
                retryable: false
                doc_url: https://errors.rev.cat/invalid-request
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - unprocessable_entity_error
                      - parameter_error
                      - store_error
                      - entity_references_archived_entities
          examples:
            unprocessable_entity:
              value:
                object: error
                type: unprocessable_entity_error
                message: Cannot delete a product that has purchases
                retryable: false
                doc_url: https://errors.rev.cat/unprocessable-entity-error
            parameter_error:
              value:
                object: error
                type: parameter_error
                message: Date must in the future
                retryable: false
                doc_url: https://errors.rev.cat/parameter-error
            store_error:
              value:
                object: error
                type: store_error
                message: There was a problem on the App Store
                retryable: true
                doc_url: https://errors.rev.cat/store-error
                backoff_ms: 1000
            entity_references_archived_entities:
              value:
                object: error
                type: entity_references_archived_entities
                message: >-
                  This offering references inactive products. You will need to
                  make the products active first before making the offering
                  active.
                retryable: false
                doc_url: https://errors.rev.cat/entity-references-archived-entities
                referenced_object_ids:
                  - prodabcd1234
                  - prodwxyz5678
  securitySchemes:
    BearerAuth:
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication. Allowed headers -- Authorization: Bearer
        <api_key>
      scheme: bearer
      type: http
