AlertCamp Subscriptions API

openapi: 3.2.0
info:
  title: AlertCamp Subscriptions API
  description: Service d'alertes de disponibilité SEPAQ pour le camping au Québec
  version: 0.1.0
tags:
- name: Subscriptions
paths:
  /api/v1/subscriptions/me:
    get:
      tags:
      - Subscriptions
      summary: Get My Subscription
      description: 'Get the current user''s subscription details.


        Creates an essai subscription if the user doesn''t have one.'
      operationId: get_my_subscription_api_v1_subscriptions_me_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/subscriptions/status:
    get:
      tags:
      - Subscriptions
      summary: Get Subscription Status
      description: 'Get subscription status and entitlements.


        Includes tier limits and current usage for quota validation.'
      operationId: get_subscription_status_api_v1_subscriptions_status_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/subscriptions/sync:
    post:
      tags:
      - Subscriptions
      summary: Sync Subscription
      description: 'Reconcile subscription state with RevenueCat REST API.


        Mobile calls this after Purchases.restorePurchases() so the backend

        tier matches RevenueCat''s view immediately, without waiting for a

        webhook (which is async and, for events like TRANSFER, may carry no

        actionable single-user payload).'
      operationId: sync_subscription_api_v1_subscriptions_sync_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/subscriptions/plans:
    get:
      tags:
      - Subscriptions
      summary: Get Subscription Plans
      description: 'Get available subscription plans with capacity info.


        - **v=2**: Returns full dynamic screen config (localized tiers, comparison

        table, feature list, provider site overrides).

        - **No v param / v=1**: Returns legacy format (backwards compat for old app versions).


        Plans are purchased via native IAP through RevenueCat SDK.'
      operationId: get_subscription_plans_api_v1_subscriptions_plans_get
      parameters:
      - name: v
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: 'API version: 2 for dynamic screen config'
          title: V
        description: 'API version: 2 for dynamic screen config'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/SubscriptionPlansResponse'
                - $ref: '#/components/schemas/SubscriptionScreenConfigResponse'
                title: Response Get Subscription Plans Api V1 Subscriptions Plans Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/subscriptions/waitlist:
    post:
      tags:
      - Subscriptions
      summary: Join Waitlist
      description: 'Join the waitlist for a tier that is at capacity.


        Uses the authenticated user''s email and ID.

        Duplicate (email, tier) pairs are handled gracefully.'
      operationId: join_waitlist_api_v1_subscriptions_waitlist_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaitlistRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitlistResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/subscriptions/dev/tier:
    put:
      tags:
      - Subscriptions
      summary: Dev Set Tier
      description: 'Development endpoint to directly set subscription tier.


        Only available in development environment.

        Bypasses RevenueCat for testing tier-based features.'
      operationId: dev_set_tier_api_v1_subscriptions_dev_tier_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-dev-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Dev-User-Id
      - name: x-app-version
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-App-Version
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevSetTierRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SubscriptionStatusResponse:
      properties:
        is_active:
          type: boolean
          title: Is Active
        is_trial:
          type: boolean
          title: Is Trial
        status:
          $ref: '#/components/schemas/SubscriptionStatusEnum'
        plan:
          anyOf:
          - $ref: '#/components/schemas/SubscriptionPlanEnum'
          - type: 'null'
        tier:
          allOf:
          - $ref: '#/components/schemas/SubscriptionTierEnum'
          default: essai
        pending_tier:
          anyOf:
          - $ref: '#/components/schemas/SubscriptionTierEnum'
          - type: 'null'
        trial_days_remaining:
          type: integer
          title: Trial Days Remaining
        current_period_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Current Period End
        entitlements:
          items:
            type: string
          type: array
          title: Entitlements
          default: []
        limits:
          anyOf:
          - $ref: '#/components/schemas/TierLimitsResponse'
          - type: 'null'
        usage:
          anyOf:
          - $ref: '#/components/schemas/QuotaUsageResponse'
          - type: 'null'
      type: object
      required:
      - is_active
      - is_trial
      - status
      - plan
      - trial_days_remaining
      - current_period_end
      title: SubscriptionStatusResponse
      description: Schema for subscription status check response.
    TierCapacityInfo:
      properties:
        capacity:
          anyOf:
          - type: integer
          - type: 'null'
          title: Capacity
        current_subscribers:
          type: integer
          title: Current Subscribers
          default: 0
        available_spots:
          anyOf:
          - type: integer
          - type: 'null'
          title: Available Spots
        is_available:
          type: boolean
          title: Is Available
          default: true
      type: object
      title: TierCapacityInfo
      description: Capacity information for a single tier.
    TierLimitsResponse:
      properties:
        max_alerts:
          type: integer
          title: Max Alerts
        max_sites_per_alert:
          type: integer
          title: Max Sites Per Alert
        max_total_sites:
          type: integer
          title: Max Total Sites
        max_total_alerts:
          type: integer
          title: Max Total Alerts
        sms_enabled:
          type: boolean
          title: Sms Enabled
        email_enabled:
          type: boolean
          title: Email Enabled
        ontario_parks_enabled:
          type: boolean
          title: Ontario Parks Enabled
      type: object
      required:
      - max_alerts
      - max_sites_per_alert
      - max_total_sites
      - max_total_alerts
      - sms_enabled
      - email_enabled
      - ontario_parks_enabled
      title: TierLimitsResponse
      description: Schema for tier limits.
    FeatureItemConfig:
      properties:
        icon:
          type: string
          title: Icon
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
      type: object
      required:
      - icon
      - title
      - description
      title: FeatureItemConfig
      description: A feature in the expandable feature list.
    SubscriptionResponse:
      properties:
        id:
          type: string
          title: Id
        user_id:
          type: string
          title: User Id
        status:
          $ref: '#/components/schemas/SubscriptionStatusEnum'
        plan:
          anyOf:
          - $ref: '#/components/schemas/SubscriptionPlanEnum'
          - type: 'null'
        tier:
          allOf:
          - $ref: '#/components/schemas/SubscriptionTierEnum'
          default: essai
        pending_tier:
          anyOf:
          - $ref: '#/components/schemas/SubscriptionTierEnum'
          - type: 'null'
        trial_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Trial Start
        trial_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Trial End
        current_period_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Current Period Start
        current_period_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Current Period End
        canceled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Canceled At
        cancel_at_period_end:
          type: boolean
          title: Cancel At Period End
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        is_active:
          type: boolean
          title: Is Active
        is_trial:
          type: boolean
          title: Is Trial
        trial_days_remaining:
          type: integer
          title: Trial Days Remaining
        days_until_renewal:
          anyOf:
          - type: integer
          - type: 'null'
          title: Days Until Renewal
      type: object
      required:
      - id
      - user_id
      - status
      - plan
      - trial_start
      - trial_end
      - current_period_start
      - current_period_end
      - canceled_at
      - cancel_at_period_end
      - created_at
      - updated_at
      - is_active
      - is_trial
      - trial_days_remaining
      - days_until_renewal
      title: SubscriptionResponse
      description: Schema for subscription response.
    DevSetTierRequest:
      properties:
        tier:
          type: string
          title: Tier
          description: 'Tier to set: essai, regular, pro'
      type: object
      required:
      - tier
      title: DevSetTierRequest
      description: Request schema for development tier setting endpoint.
    ProviderSiteOverride:
      properties:
        max_sites_per_alert:
          type: integer
          title: Max Sites Per Alert
        max_total_sites:
          type: integer
          title: Max Total Sites
      type: object
      required:
      - max_sites_per_alert
      - max_total_sites
      title: ProviderSiteOverride
      description: Site limit overrides for a provider.
    WaitlistResponse:
      properties:
        message:
          type: string
          title: Message
        already_registered:
          type: boolean
          title: Already Registered
          default: false
      type: object
      required:
      - message
      title: WaitlistResponse
      description: Response schema for waitlist operations.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    QuotaUsageResponse:
      properties:
        active_alerts:
          type: integer
          title: Active Alerts
        total_alerts:
          type: integer
          title: Total Alerts
        total_sites:
          type: integer
          title: Total Sites
        total_sites_by_bucket:
          additionalProperties:
            type: integer
          type: object
          title: Total Sites By Bucket
      type: object
      required:
      - active_alerts
      - total_alerts
      - total_sites
      title: QuotaUsageResponse
      description: Schema for current quota usage.
    SubscriptionScreenConfigResponse:
      properties:
        version:
          type: integer
          title: Version
          default: 1
        tiers:
          items:
            $ref: '#/components/schemas/TierTileConfig'
          type: array
          title: Tiers
          default: []
        paid_tiers:
          items:
            type: string
          type: array
          title: Paid Tiers
          default: []
        comparison_rows:
          items:
            $ref: '#/components/schemas/ComparisonRowConfig'
          type: array
          title: Comparison Rows
          default: []
        features:
          items:
            $ref: '#/components/schemas/FeatureItemConfig'
          type: array
          title: Features
          default: []
        provider_site_overrides:
          additionalProperties:
            additionalProperties:
              $ref: '#/components/schemas/ProviderSiteOverride'
            type: object
          type: object
          title: Provider Site Overrides
          default: {}
        capacity:
          additionalProperties:
            $ref: '#/components/schemas/TierCapacityInfo'
          type: object
          title: Capacity
          default: {}
        provider_config:
          additionalProperties:
            $ref: '#/components/schemas/ProviderConfig'
          type: object
          title: Provider Config
          default: {}
      type: object
      title: SubscriptionScreenConfigResponse
      description: v2 response for /plans endpoint — full subscription screen config.
    SubscriptionPlansResponse:
      properties:
        plans:
          items:
            $ref: '#/components/schemas/SubscriptionPlanInfo'
          type: array
          title: Plans
        trial_days:
          type: integer
          title: Trial Days
          default: 0
      type: object
      title: SubscriptionPlansResponse
      description: Schema for available subscription plans.
    SubscriptionStatusEnum:
      type: string
      enum:
      - trial
      - active
      - past_due
      - canceled
      - expired
      title: SubscriptionStatusEnum
      description: Subscription status states.
    WaitlistRequest:
      properties:
        desired_tier:
          allOf:
          - $ref: '#/components/schemas/SubscriptionTierEnum'
          description: Tier to join waitlist for
      type: object
      required:
      - desired_tier
      title: WaitlistRequest
      description: Request schema for joining a tier waitlist.
    ProviderConfig:
      properties:
        show_quota_banner:
          type: boolean
          title: Show Quota Banner
          default: true
      type: object
      title: ProviderConfig
      description: Provider-level configuration flags.
    SubscriptionPlanEnum:
      type: string
      enum:
      - monthly
      const: monthly
      title: SubscriptionPlanEnum
      description: Available subscription plans.
    SubscriptionPlanInfo:
      properties:
        tier:
          $ref: '#/components/schemas/SubscriptionTierEnum'
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        price_cad:
          type: number
          title: Price Cad
        interval:
          type: string
          title: Interval
          default: month
        features:
          items:
            type: string
          type: array
          title: Features
        capacity:
          anyOf:
          - type: integer
          - type: 'null'
          title: Capacity
        current_subscribers:
          type: integer
          title: Current Subscribers
          default: 0
        available_spots:
          anyOf:
          - type: integer
          - type: 'null'
          title: Available Spots
        is_available:
          type: boolean
          title: Is Available
          default: true
      type: object
      required:
      - tier
      - name
      - description
      - price_cad
      - features
      title: SubscriptionPlanInfo
      description: Schema for subscription plan information.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TierTileConfig:
      properties:
        tier:
          type: string
          title: Tier
        icon:
          type: string
          title: Icon
        price_cad:
          type: number
          title: Price Cad
        revenuecat_product_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Revenuecat Product Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        badge:
          anyOf:
          - type: string
          - type: 'null'
          title: Badge
        features:
          items:
            $ref: '#/components/schemas/TileFeatureRow'
          type: array
          title: Features
          default: []
      type: object
      required:
      - tier
      - icon
      - price_cad
      - name
      - description
      title: TierTileConfig
      description: Configuration for a single tier tile on the subscription screen.
    SubscriptionTierEnum:
      type: string
      enum:
      - essai
      - regular
      - pro
      title: SubscriptionTierEnum
      description: Subscription tier levels.
    ComparisonRowConfig:
      properties:
        label:
          type: string
          title: Label
        values:
          items:
            type: string
          type: array
          title: Values
        type:
          type: string
          title: Type
      type: object
      required:
      - label
      - values
      - type
      title: ComparisonRowConfig
      description: A row in the tier comparison table.
    TileFeatureRow:
      properties:
        icon:
          type: string
          title: Icon
        text:
          type: string
          title: Text
        highlight:
          type: boolean
          title: Highlight
          default: false
        highlight_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Highlight Color
      type: object
      required:
      - icon
      - text
      title: TileFeatureRow
      description: Feature row within a tier tile card.