DataAssist-IO Billing API

openapi: 3.2.0
info:
  title: DataAssist-IO Server Billing API
  version: 0.1.0
tags:
- name: Billing
paths:
  /billing:
    get:
      summary: Spa Billing
      operationId: spa_billing_billing_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Billing
  /api/billing/packs:
    get:
      tags:
      - Billing
      summary: Get Packs
      description: 'Returns public packs for the org''s region + any custom packs assigned to it.


        Region is derived from the org''s `billing_country` (IN → ''in'', else ''global'').

        If billing_country isn''t set yet, defaults to ''global''.


        Response is extended with `active_promo` when the org has a signup-attached

        promo that has not yet been consumed on any purchase. The SPA surfaces this

        as an auto-apply banner.'
      operationId: get_packs_api_billing_packs_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/billing/details:
    get:
      tags:
      - Billing
      summary: Get Billing Details Endpoint
      operationId: get_billing_details_endpoint_api_billing_details_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    put:
      tags:
      - Billing
      summary: Put Billing Details Endpoint
      operationId: put_billing_details_endpoint_api_billing_details_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingDetailsBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/billing/balance:
    get:
      tags:
      - Billing
      summary: Get Balance Endpoint
      operationId: get_balance_endpoint_api_billing_balance_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/billing/promo/validate:
    post:
      tags:
      - Billing
      summary: Validate Promo
      description: 'Lightweight validation called by the SPA when the user types a code.


        Returns either a successful preview ({valid, discount_amount, final_amount})

        or a structured error with a `code` the SPA can branch on. Does NOT

        consume the code — checkout/create is the only path that records an

        application.'
      operationId: validate_promo_api_billing_promo_validate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoValidateBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/billing/checkout:
    post:
      tags:
      - Billing
      summary: Checkout
      description: 'Create a Razorpay order and a pending credit_purchases row.


        Precondition: billing details must be complete (approach A — block paid

        checkout until name/address/country are filled).


        If `promo_code` is supplied, the price charged is the post-discount

        `final_amount`. The promo validation + the application-row INSERT happen

        in the same transaction as the credit_purchases INSERT — a stale code

        cannot lead to a credited purchase at the discounted price.'
      operationId: checkout_api_billing_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/billing/checkout/verify:
    post:
      tags:
      - Billing
      summary: Checkout Verify
      description: 'Client-side success callback from Razorpay Checkout JS.


        We verify the signature here, but the authoritative status flip + balance

        bump happens in the webhook (idempotent). This endpoint only acknowledges

        the client redirect so the SPA can show a success screen immediately.'
      operationId: checkout_verify_api_billing_checkout_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutVerifyBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/billing/checkout/abandon:
    post:
      tags:
      - Billing
      summary: Checkout Abandon
      description: 'User closed the Razorpay modal without paying — flip pending row to failed.


        Idempotent (only flips rows still in `pending`). Verifies with Razorpay

        BEFORE marking failed — if the payment was actually captured (e.g., a hard

        refresh ate the success callback), completes the purchase instead. Returns

        `{ok, status}` where status is one of `failed`, `completed`, `noop`.'
      operationId: checkout_abandon_api_billing_checkout_abandon_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutAbandonBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/billing/transactions/reconcile-pending:
    post:
      tags:
      - Billing
      summary: Reconcile Pending
      description: 'Scan this org''s non-terminal purchases and reconcile each against Razorpay.


        Called by the SPA when the Billing page loads. Handles two cases where a

        webhook never reached us:


        1. `payment.captured` lost → row stuck `pending`. We ask Razorpay, and

        if a payment is captured we flip to `completed` and credit the balance.

        2. `payment.failed` arrived but the subsequent retry''s `payment.captured`

        was lost → row is `failed` even though money moved. Same recovery —

        Razorpay returns the captured payment on the same order, we flip

        `failed → completed`.


        For (2) we time-bound the scan to the last 7 days so we don''t repeatedly

        query Razorpay for ancient genuinely-failed rows.'
      operationId: reconcile_pending_api_billing_transactions_reconcile_pending_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/billing/transactions:
    get:
      tags:
      - Billing
      summary: Get Transactions
      operationId: get_transactions_api_billing_transactions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/billing/transactions.csv:
    get:
      tags:
      - Billing
      summary: Get Transactions Csv
      operationId: get_transactions_csv_api_billing_transactions_csv_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/billing/transactions/{purchase_id}/invoice.pdf:
    get:
      tags:
      - Billing
      summary: Get Invoice Pdf
      operationId: get_invoice_pdf_api_billing_transactions__purchase_id__invoice_pdf_get
      parameters:
      - name: purchase_id
        in: path
        required: true
        schema:
          type: integer
          title: Purchase Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/billing/usage.csv:
    get:
      tags:
      - Billing
      summary: Get Usage Csv
      description: Usage CSV from audit_logs. Admin sees full org; viewer sees own.
      operationId: get_usage_csv_api_billing_usage_csv_get
      parameters:
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: From
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: To
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CheckoutAbandonBody:
      properties:
        purchase_id:
          type: integer
          title: Purchase Id
        reason:
          type: string
          title: Reason
          default: user_dismissed
      type: object
      required:
      - purchase_id
      title: CheckoutAbandonBody
    BillingDetailsBody:
      properties:
        billing_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Billing Name
        billing_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Billing Address
        billing_country:
          anyOf:
          - type: string
          - type: 'null'
          title: Billing Country
        tax_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tax Id
      type: object
      title: BillingDetailsBody
    CheckoutBody:
      properties:
        pack_id:
          type: string
          title: Pack Id
        promo_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Promo Code
      type: object
      required:
      - pack_id
      title: CheckoutBody
    PromoValidateBody:
      properties:
        code:
          type: string
          title: Code
        pack_id:
          type: string
          title: Pack Id
      type: object
      required:
      - code
      - pack_id
      title: PromoValidateBody
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CheckoutResponse:
      properties:
        purchase_id:
          type: integer
          title: Purchase Id
        razorpay_order_id:
          type: string
          title: Razorpay Order Id
        razorpay_key_id:
          type: string
          title: Razorpay Key Id
        amount:
          type: integer
          title: Amount
        currency:
          type: string
          title: Currency
        pack:
          additionalProperties: true
          type: object
          title: Pack
        promo_applied:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Promo Applied
      type: object
      required:
      - purchase_id
      - razorpay_order_id
      - razorpay_key_id
      - amount
      - currency
      - pack
      title: CheckoutResponse
    CheckoutVerifyBody:
      properties:
        purchase_id:
          type: integer
          title: Purchase Id
        razorpay_order_id:
          type: string
          title: Razorpay Order Id
        razorpay_payment_id:
          type: string
          title: Razorpay Payment Id
        razorpay_signature:
          type: string
          title: Razorpay Signature
      type: object
      required:
      - purchase_id
      - razorpay_order_id
      - razorpay_payment_id
      - razorpay_signature
      title: CheckoutVerifyBody