AnomalyArmor Trial Codes API

openapi: 3.2.0
info:
  title: Anomalyarmor Ai Trial Codes API
  version: 1.0.0
  contact:
    name: AnomalyArmor Support
    url: https://anomalyarmor.ai/support
  license:
    name: Proprietary
  description: 'Operations tagged trial-codes across 3 of this provider''s published API definitions: anomalyarmor.ai-openapi.json, app.anomalyarmor.ai-openapi.json, docs.anomalyarmor.ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:8000
  description: Development server
- url: https://api.anomalyarmor.ai
  description: Production server
tags:
- name: trial-codes
paths:
  /api/v1/billing/trial-codes/validate:
    post:
      tags:
      - trial-codes
      summary: Validate Trial Code
      description: 'Validate a trial code without redeeming it.


        This endpoint is PUBLIC (no authentication required) to allow

        users to check code validity before signing up or signing in.


        Security note: Only returns whether code is valid and trial duration.

        Does not expose sensitive code details.'
      operationId: validate_trial_code_api_v1_billing_trial_codes_validate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateTrialCodeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: http://localhost:8000
      description: Development server
    - url: https://api.anomalyarmor.ai
      description: Production server
  /api/v1/billing/trial-codes/redeem:
    post:
      tags:
      - trial-codes
      summary: Redeem Trial Code
      description: 'Redeem a trial code for the current user''s company.


        This will:

        1. Validate the code

        2. Record the redemption

        3. Update the company''s subscription to FREE_TRIAL status with trial_end date'
      operationId: redeem_trial_code_api_v1_billing_trial_codes_redeem_post
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemTrialCodeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: http://localhost:8000
      description: Development server
    - url: https://api.anomalyarmor.ai
      description: Production server
  /api/v1/billing/trial-codes/complete-signup-with-code:
    post:
      tags:
      - trial-codes
      summary: Complete Signup With Code
      description: 'Complete signup for a user who signed up with a trial code.


        TECH-657: Called AFTER Clerk authentication. Handles two cases:

        1. User has no company yet: Creates company and subscription

        2. User already has company (from Clerk webhook): Updates existing subscription


        The Clerk webhook typically creates the company before this endpoint is called,

        so case 2 is the common path. We check if the subscription is eligible for

        trial code application (free_trial, trialing, or incomplete status).


        Transaction Flow:

        1. Validate code

        2. Get or create company and subscription

        3. Update subscription with target plan from code if specified

        4. Record redemption

        5. Commit only if ALL steps succeed'
      operationId: complete_signup_with_code_api_v1_billing_trial_codes_complete_signup_with_code_post
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteSignupWithCodeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: http://localhost:8000
      description: Development server
    - url: https://api.anomalyarmor.ai
      description: Production server
  /api/v1/billing/trial-codes/redeem-with-cancel:
    post:
      tags:
      - trial-codes
      summary: Redeem With Cancel
      description: 'Redeem a trial code for an existing paying customer.


        TECH-657: Cancels the Stripe subscription (triggers prorated credit),

        then applies the trial with the target plan.


        Transaction Safety (order prevents data loss):

        1. Validate code

        2. Record redemption (marks code as used)

        3. Update subscription to trial with target plan

        4. Clear Stripe IDs in DB

        5. COMMIT DB FIRST (ensures trial is active before touching Stripe)

        6. Cancel Stripe subscription (external call, may fail)


        Why commit before Stripe cancel:

        - If DB commit fails: Customer keeps Stripe subscription (safe rollback)

        - If Stripe cancel fails after commit: Customer has trial + Stripe sub

        (recoverable via manual cancellation, customer is not left without access)

        - Previous approach risk: If Stripe succeeds but commit fails, customer

        loses Stripe sub AND doesn''t get trial (unrecoverable data loss)'
      operationId: redeem_with_cancel_api_v1_billing_trial_codes_redeem_with_cancel_post
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemWithCancelRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: http://localhost:8000
      description: Development server
    - url: https://api.anomalyarmor.ai
      description: Production server
components:
  schemas:
    ValidateTrialCodeRequest:
      properties:
        code:
          type: string
          maxLength: 50
          minLength: 3
          title: Code
          description: Trial code to validate
      type: object
      required:
      - code
      title: ValidateTrialCodeRequest
      description: Request to validate a trial code.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CompleteSignupWithCodeRequest:
      properties:
        code:
          type: string
          maxLength: 50
          minLength: 3
          title: Code
          description: Trial code to redeem
        company_name:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Company Name
          description: Optional company name. Defaults to email domain.
      type: object
      required:
      - code
      title: CompleteSignupWithCodeRequest
      description: 'Request to complete signup with a trial code (TECH-657).


        Called AFTER Clerk authentication to create company and subscription.'
    RedeemTrialCodeRequest:
      properties:
        code:
          type: string
          maxLength: 50
          minLength: 3
          title: Code
          description: Trial code to redeem
      type: object
      required:
      - code
      title: RedeemTrialCodeRequest
      description: Request to redeem a trial code.
    StandardResponse:
      properties:
        success:
          type: boolean
          title: Success
        data:
          anyOf:
          - {}
          - type: 'null'
          title: Data
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      required:
      - success
      title: StandardResponse
      description: Standard API response wrapper.
    RedeemWithCancelRequest:
      properties:
        code:
          type: string
          maxLength: 50
          minLength: 3
          title: Code
          description: Trial code to redeem
      type: object
      required:
      - code
      title: RedeemWithCancelRequest
      description: 'Request to redeem a trial code with subscription cancellation (TECH-657).


        For existing paying customers: cancels Stripe subscription and applies trial.'
    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
x-refined-from:
- anomalyarmor.ai-openapi.json
- app.anomalyarmor.ai-openapi.json
- docs.anomalyarmor.ai-openapi.json