Equity Rank Stripe API

openapi: 3.2.0
info:
  title: Equity Rank Com Stripe API
  version: 0.1.0
  description: 'Operations tagged stripe across 2 of this provider''s published API definitions: openapi.json, equity-rank-com-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Stripe
paths:
  /api/stripe/checkout:
    post:
      tags:
      - Stripe
      summary: Create Checkout Session
      description: 'Creates a Stripe Checkout session with a 7-day free trial.


        - Authenticated (JWT required) but does NOT require an active subscription

        (the user is trying to subscribe for the first time or re-subscribe).

        - Creates a Stripe Customer first, then links it to the Checkout session.

        - Returns {url: ''https://checkout.stripe.com/...''} for the frontend redirect.'
      operationId: create_checkout_session_api_stripe_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/stripe/portal:
    post:
      tags:
      - Stripe
      summary: Create Portal Session
      description: 'Creates a Stripe Customer Portal session for self-serve billing management.


        - Requires an active subscription (402 if none).

        - Looks up stripe_customer_id from public.subscriptions.

        - Returns {url: ''https://billing.stripe.com/...''} for frontend redirect.'
      operationId: create_portal_session_api_stripe_portal_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortalRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/stripe/founder-slots:
    get:
      tags:
      - Stripe
      summary: Get Founder Slots
      description: 'Returns remaining founder cohort slots — public endpoint, no auth required.

        Used by the pricing page to display the scarcity counter.

        Returns {remaining: int, max: int, active: bool}.

        active=false when the founder price ID is not configured (feature disabled).


        The displayed count MUST be the true used_slots value. A prior revision

        inflated it with a +63 display baseline; a fabricated "claimed" count is

        false scarcity (FTC deceptive-practice exposure) and is not permitted on

        any purchase surface.'
      operationId: get_founder_slots_api_stripe_founder_slots_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/stripe/webhook:
    post:
      tags:
      - Stripe
      summary: Stripe Webhook
      description: 'Receive and process Stripe webhook events.


        Security:

        - Verifies Stripe-Signature header using stripe.Webhook.construct_event.

        - Returns 400 on invalid signature (must use raw bytes — request.body()).


        Idempotency:

        - Checks processed_webhook_events table before processing.

        - Inserts event_id after success.

        - Returns 200 even if event already processed (Stripe retries on non-2xx).


        Handled events:

        - customer.subscription.created → upsert subscriptions row

        - customer.subscription.updated → upsert subscriptions row

        - customer.subscription.deleted → set status=''cancelled'', owner alert

        - invoice.paid → owner payment-received alert

        - invoice.payment_failed → set status=''past_due''

        - payment_method.attached → set has_payment_method=true'
      operationId: stripe_webhook_api_stripe_webhook_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/stripe/subscription:
    delete:
      tags:
      - Stripe
      summary: Cancel Subscription
      description: 'Cancel the user''s Stripe subscription at period end.

        The subscription remains active until current_period_end, then cancels.

        Returns the updated subscription status.'
      operationId: cancel_subscription_api_stripe_subscription_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/stripe/account:
    delete:
      tags:
      - Stripe
      summary: Delete Account
      description: 'Permanently delete the user''s account.

        Steps:

        1. Cancel any active Stripe subscription immediately (not at period end)

        2. Record email in trial_used_emails so re-signup can''t get another trial

        3. Delete the Supabase auth user (cascades to all user data via RLS)

        Returns {ok: True} on success.'
      operationId: delete_account_api_stripe_account_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
components:
  schemas:
    CheckoutRequest:
      properties:
        plan:
          type: string
          enum:
          - monthly
          - annual
          title: Plan
          default: monthly
        tier:
          type: string
          enum:
          - starter
          - plus
          - pro
          - advisor
          - founder
          title: Tier
          default: pro
        success_url:
          type: string
          title: Success Url
          default: ''
        cancel_url:
          type: string
          title: Cancel Url
          default: ''
      type: object
      title: CheckoutRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PortalRequest:
      properties:
        return_url:
          type: string
          title: Return Url
          default: ''
      type: object
      title: PortalRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- openapi.json
- equity-rank-com-openapi.yml