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


      Operations about customers.


      #### Endpoints


      - [Get or Create Customer](#tag/customers/operation/subscribers) — `GET
      /subscribers/{app_user_id}`

      - [Delete Customer](#tag/customers/operation/delete-subscriber) — `DELETE
      /subscribers/{app_user_id}`

      - [Add Customer Attribution
      Data](#tag/customers/operation/subscribersattribution) — `POST
      /subscribers/{app_user_id}/attribution`

      - [Update Customer
      Attributes](#tag/customers/operation/update-subscriber-attributes) — `POST
      /subscribers/{app_user_id}/attributes`
    x-displayName: Customers
  - name: Endpoint Reference
    x-traitTag: true
    description: >
      All API v1 resources, one page each. General concepts (authentication,
      request format, URL parameters) live on the [API v1
      overview](/docs/api-v1).


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

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

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

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

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

      - [Transactions](/docs/api-v1/transactions) — 6 endpoints
paths:
  /subscribers/{app_user_id}:
    get:
      summary: Get or Create Customer
      tags:
        - customers
      description: >-
        Gets the latest [Customer
        Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for the
        customer with the given App User ID, or creates a new customer if it
        doesn't exist.
      operationId: subscribers
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID used with the mobile SDK.
          schema:
            type: string
          required: true
        - name: X-Platform
          in: header
          description: >-
            Optionally set the X-Platform header to update the Customer's
            `last_seen` field. Set to either `ios`, `android`, `amazon`,
            `macos`, `uikitformac`. Don't set this if you are calling the getter
            for informational purposes or using a secret API key to fetch the
            customer's attributes.
          schema:
            type: string
            example: ios
      responses:
        '200':
          description: >
            Success (customer found).


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


            Returns the [Customer
            Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              examples:
                Result:
                  $ref: '#/components/examples/Subscriber'
              schema:
                $ref: '#/components/schemas/Subscriber'
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    message: Bad parameters x
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Result:
                  value:
                    message: Invalid API key
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: false
    delete:
      summary: Delete Customer
      tags:
        - customers
      description: Permanently deletes a customer.
      operationId: delete-subscriber
      parameters:
        - name: app_user_id
          in: path
          description: >-
            The App User ID of the customer to be deleted (might be an aliased
            App User ID).
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Customer successfully deleted.
          content:
            application/json:
              schema:
                type: object
                required:
                  - app_user_id
                  - deleted
                properties:
                  app_user_id:
                    type: string
                    description: >-
                      The App User ID of the customer that was requested to be
                      deleted
                    example: XXX-XXXXX-XXXXX-XX
                  deleted:
                    type: boolean
                    description: Whether or not the customer was successfully deleted
                    example: true
      deprecated: false
  /subscribers/{app_user_id}/attribution:
    post:
      summary: Add Customer Attribution Data
      tags:
        - customers
      description: >-
        Attaches attribution data to a subscriber from specific supported
        networks.
      operationId: subscribersattribution
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID of the Customer.
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
                - network
              properties:
                data:
                  type: object
                  description: The data returned by the attribution network callbacks.
                  properties:
                    rc_idfa:
                      type: string
                      description: The idfa from AdSupport on iOS. (iOS Only)
                    rc_gps_adid:
                      type: string
                      description: >-
                        The Google Play Services Advertising identifier.
                        (Android Only)
                network:
                  type: string
                  description: |
                    The attribution network the data is coming from:
                    - 0: Apple Search AdSupport
                    - 1: Adjust
                    - 2: AppsFlyer
                    - 3: Branch
                    - 4: Tenjin
                    - 5: Facebook
                  enum:
                    - '0'
                    - '1'
                    - '2'
                    - '3'
                    - '4'
                    - '5'
      responses:
        '200':
          description: Attribution data was successfully posted.
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: true
  /subscribers/{app_user_id}/attributes:
    post:
      summary: Update Customer Attributes
      tags:
        - customers
      description: Updates attributes for a customer.
      operationId: update-subscriber-attributes
      parameters:
        - name: app_user_id
          in: path
          description: The App User ID used with the mobile SDK.
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                attributes:
                  properties:
                    key_name:
                      type: object
                      description: Mapping of keys to attribute values.
                      required:
                        - value
                      properties:
                        value:
                          type: string
                          description: >-
                            The value of the attribute. If the value is `null`
                            or an empty string, the attribute will be deleted.
                        updated_at_ms:
                          type: integer
                          format: int64
                          description: >-
                            UNIX epoch in milliseconds of when the attribute was
                            updated. This value is used to resolve conflicts, an
                            attribute will only be updated if the new
                            `updated_at_ms` value is newer than the value for
                            the stored attribute.
                          example: 1709195668093
                  required:
                    - key_name
                  type: object
      responses:
        '200':
          description: >
            Attributes were successfully updated.


            Returns the updated [Customer
            Info](/docs/api-v1/customer-info-model#tag/customer_info_model) for
            the Customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscriber'
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: 7263
                    message: Some customer attribute keys were unable to be saved.
                    attribute_errors:
                      - key_name: $email
                        message: Value is not a valid email address.
                      - key_name: invalid key name with spaces
                        message: Key name format is not valid.
                      - key_name: too_much_data
                        message: Value is too long.
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 7263
                  message:
                    type: string
                    example: Some customer attribute keys were unable to be saved.
                  attribute_errors:
                    type: array
                    items:
                      type: object
                      properties:
                        key_name:
                          type: string
                          example: $email
                        message:
                          type: string
                          example: Value is not a valid email address.
      deprecated: false
components:
  examples:
    Subscriber:
      value: &ref_0
        request_date: '2019-07-26T17:40:10Z'
        request_date_ms: 1564162810884
        subscriber:
          entitlements:
            pro_cat:
              expires_date: null
              grace_period_expires_date: null
              product_identifier: onetime
              purchase_date: '2019-04-05T21:52:45Z'
          first_seen: '2019-02-21T00:08:41Z'
          management_url: https://apps.apple.com/account/subscriptions
          non_subscriptions:
            onetime:
              - id: cadba0c81b
                is_sandbox: true
                purchase_date: '2019-04-05T21:52:45Z'
                store: app_store
          original_app_user_id: XXX-XXXXX-XXXXX-XX
          original_application_version: '1.0'
          original_purchase_date: '2019-01-30T23:54:10Z'
          other_purchases: {}
          subscriptions:
            annual:
              auto_resume_date: null
              billing_issues_detected_at: null
              expires_date: '2019-08-14T21:07:40Z'
              grace_period_expires_date: null
              is_sandbox: true
              original_purchase_date: '2019-02-21T00:42:05Z'
              ownership_type: PURCHASED
              period_type: normal
              purchase_date: '2019-07-14T20:07:40Z'
              refunded_at: null
              store: play_store
              store_transaction_id: GPA.6801-7988-0152-76034..5
              unsubscribe_detected_at: '2019-07-17T22:48:38Z'
            onemonth:
              auto_resume_date: null
              billing_issues_detected_at: null
              expires_date: '2019-06-17T22:47:55Z'
              grace_period_expires_date: null
              is_sandbox: true
              original_purchase_date: '2019-02-21T00:42:05Z'
              ownership_type: PURCHASED
              period_type: normal
              purchase_date: '2019-06-17T22:42:55Z'
              refunded_at: null
              store: app_store
              store_transaction_id: 1000000652379790
              unsubscribe_detected_at: '2019-06-17T22:48:38Z'
            rc_promo_pro_cat_monthly:
              auto_resume_date: null
              billing_issues_detected_at: null
              expires_date: '2019-08-26T01:02:16Z'
              grace_period_expires_date: null
              is_sandbox: false
              original_purchase_date: '2019-07-26T01:02:16Z'
              ownership_type: FAMILY_SHARED
              period_type: normal
              purchase_date: '2019-07-26T01:02:16Z'
              refunded_at: null
              store: promotional
              store_transaction_id: a42db3af39530cb82b17eaf9c6576393
              unsubscribe_detected_at: null
  schemas:
    Subscriber:
      type: object
      description: Snapshot of information about a Customer.
      properties:
        request_date:
          type: string
          description: Date of the request in ISO 8601 format.
          example: '2019-07-26T17:40:10Z'
        request_date_ms:
          type: integer
          format: int64
          description: Date of the request in milliseconds since Epoch.
          example: 1564162810884
        subscriber:
          type: object
          description: Information about the Customer.
          properties:
            entitlements:
              type: object
              description: >-
                Dictionary of the entitlements of this Customer (including any
                expired entitlements).
              additionalProperties:
                type: object
                description: >-
                  One entitlement granted to this Customer. If the customer was
                  granted this entitlement through multiple purchases, then the
                  information about the purchase with the furthest-out
                  expiration date is included.
                properties:
                  expires_date:
                    type: string
                    description: >-
                      Date when the entitlement expires / expired (in ISO 8601
                      format, may be in the past). `null` if it is a lifetime
                      entitlement.
                    example: '2024-12-12T14:04:03Z'
                    nullable: true
                  grace_period_expires_date:
                    type: string
                    description: >-
                      Date when any potential grace period of the entitlement
                      expires / expired (in ISO 8601 format, may be in the
                      past). `null` if the Customer has never been in a grace
                      period.
                    example: '2024-12-12T14:04:03Z'
                    nullable: true
                  product_identifier:
                    type: string
                    description: >
                      The identifier of the product that is responsible for this
                      entitlement being granted.<br><br>Please note: in some
                      cases, if there are problems with validating the purchase
                      with the store, the correct product identifier might
                      temporarily be unavailable.
                    example: onetime
                  purchase_date:
                    type: string
                    description: >-
                      Time of the last purchase or renewal of the product that
                      grants this entitlement (in ISO 8601 format).
                    example: '2019-04-05T21:52:45Z'
            first_seen:
              type: string
              description: >-
                The ISO 8601 datetime string corresponding to when the Customer
                was first seen by RevenueCat.
              example: '2019-02-21T00:08:41Z'
            last_seen:
              type: string
              description: >-
                The ISO 8601 datetime string corresponding to when the Customer
                was last seen by RevenueCat.
              example: '2019-02-21T00:08:41Z'
            management_url:
              type: string
              description: >
                URL to manage the active subscription of the Customer.


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


                If there are no active subscriptions it will be null.


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

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

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

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

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

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

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

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

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

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

                      - `PURCHASED`: The Customer purchased the product.

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

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

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

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

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

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

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

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

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

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

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

                      - `paddle`: The product was purchased through Paddle.
                  store_transaction_id:
                    type: string
                    example: GPA.6801-7988-0152-76034..5
                    description: |
                      Identifier of the purchase in the store's API.
                  unsubscribe_detected_at:
                    type: string
                    description: >-
                      Date when RevenueCat detected that auto-renewal was turned
                      off for this subsription (in ISO 8601 format). Note the
                      subscription may still be active, check the `expires_date`
                      attribute.
                    example: '2019-07-17T22:48:38Z'
      example:
        value: *ref_0
    Error:
      type: object
      description: Identifies an error that occurred while processing an API request.
      properties:
        message:
          type: string
          description: The error message.
          example: Invalid API key
        code:
          type: number
          description: A numeric error code.
          example: 7243
  securitySchemes:
    BearerAuth:
      bearerFormat: auth-scheme
      description: >-
        Bearer HTTP authentication. Allowed headers -- Authorization: Bearer
        <api_key>
      scheme: bearer
      type: http
