Bellator Schedule Intelligence Billing API

openapi: 3.2.0
info:
  title: Bellator Schedule Intelligence Billing API
  description: 'Bellator Schedule Intelligence APIs - Stateless Schedule Health APIs


    ## Features


    * **Schedule Analysis** - Comprehensive schedule health analysis

    * **Critical Path** - CPM-based critical path calculation

    * **Validation** - Schedule validation and quality checks

    * **Future: Resource Management** - Resource allocation and leveling

    * **Future: Simulation** - Monte Carlo and what-if analysis

    * **Future: AI Recommendations** - LLM-powered optimization suggestions


    ## Authentication


    API key authentication via `x-api-key` header or OAuth 2.0 Bearer token via `Authorization` header.


    ### API Key Authentication (Legacy)

    Include API key in `x-api-key` header.


    ### OAuth 2.0 / Azure AD Authentication (Recommended)

    Include Bearer token in `Authorization` header: `Authorization: Bearer `


    Tiers:

    - **Free**: 2,000 tasks, 100 req/min, 5MB payload

    - **Professional**: 5,000 tasks, 500 req/min, 25MB payload

    - **Enterprise**: 50,000 tasks, 2,000 req/min, 100MB payload

    - **Government**: 100,000+ tasks, 10,000 req/min, 500MB payload


    ## Usage Metering


    All API requests are metered and tracked for:

    - Request duration (milliseconds)

    - Task count processed

    - Token consumption (for LLM operations)

    - Estimated cost (USD)


    Metering events are emitted to logs and can be integrated with billing systems.


    ## Security


    * Tier-based task limits (500-100,000 tasks per request)

    * Tier-based payload limits (5-500 MB)

    * Input validation and sanitization

    * Tier-based rate limiting (100-10,000 requests per 60 seconds)'
  version: 0.4.0
tags:
- name: Billing
paths:
  /api/v1/billing/checkout:
    post:
      tags:
      - Billing
      summary: Create Stripe Checkout Session for Starter tier
      description: Creates a Stripe-hosted checkout session for the $29/mo Starter subscription. Requires a valid Entra External ID Bearer token. Redirect the user to `checkout_url` to complete payment.
      operationId: create_checkout_session_api_v1_billing_checkout_post
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/billing/checkout/reconcile:
    post:
      tags:
      - Billing
      summary: Reconcile completed Stripe checkout session
      description: Retrieves a completed Stripe Checkout Session by session_id and applies the same subscription activation logic as the webhook path. Intended as a local-development fallback when webhook forwarding is unavailable.
      operationId: reconcile_checkout_session_api_v1_billing_checkout_reconcile_post
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutReconcileRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutReconcileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/billing/portal:
    post:
      tags:
      - Billing
      summary: Create Stripe Customer Portal Session
      description: Creates a Stripe Customer Portal session for the authenticated user. Redirect the user to `portal_url` to manage their subscription, update payment methods, or download invoices. Requires an active Stripe customer (i.e., user must have checked out at least once).
      operationId: create_portal_session_api_v1_billing_portal_post
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/billing/azure-marketplace/webhook:
    post:
      tags:
      - Billing
      summary: Azure Marketplace Webhook
      description: 'Handle Azure Marketplace subscription lifecycle events.


        This endpoint is called by Microsoft when a customer subscribes, cancels,

        suspends, or changes plan via the Azure Marketplace SaaS offer.


        See: azure-marketplace-subscription-webhook-api-specification.md'
      operationId: azure_marketplace_webhook_api_v1_billing_azure_marketplace_webhook_post
      parameters:
      - name: x-ms-marketplace-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Ms-Marketplace-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Azure Marketplace Webhook Api V1 Billing Azure Marketplace Webhook Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/billing/settlement/overage-export:
    get:
      tags:
      - Billing
      summary: Export Overage Settlement
      description: Export overage settlement payloads for Stripe/Azure ingestion pipelines.
      operationId: export_overage_settlement_api_v1_billing_settlement_overage_export_get
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          enum:
          - all
          - stripe
          - azure
          type: string
          default: all
          title: Provider
      - name: format
        in: query
        required: false
        schema:
          enum:
          - json
          - csv
          type: string
          default: json
          title: Format
      - name: start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Start
      - name: end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: End
      - name: x-settlement-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Settlement-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CheckoutReconcileRequest:
      properties:
        session_id:
          type: string
          minLength: 1
          title: Session Id
          description: Stripe Checkout Session ID
      type: object
      required:
      - session_id
      title: CheckoutReconcileRequest
      description: Reconcile a completed checkout session into local subscription state.
    CheckoutReconcileResponse:
      properties:
        reconciled:
          type: boolean
          title: Reconciled
        tier:
          type: string
          title: Tier
        status:
          type: string
          title: Status
        customer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Customer Id
        subscription_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Subscription Id
      type: object
      required:
      - reconciled
      - tier
      - status
      title: CheckoutReconcileResponse
      description: Response from checkout reconciliation.
    PortalSessionResponse:
      properties:
        portal_url:
          type: string
          title: Portal Url
          description: Stripe Customer Portal URL — redirect user here
      type: object
      required:
      - portal_url
      title: PortalSessionResponse
      description: "Stripe Customer Portal session response.\n\nAttributes:\n    portal_url: Stripe-hosted portal URL; redirect user here."
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CheckoutSessionResponse:
      properties:
        checkout_url:
          type: string
          title: Checkout Url
          description: Stripe-hosted checkout URL — redirect user here
        session_id:
          type: string
          title: Session Id
          description: Stripe Checkout Session ID
      type: object
      required:
      - checkout_url
      - session_id
      title: CheckoutSessionResponse
      description: "Stripe Checkout Session response.\n\nAttributes:\n    checkout_url: Stripe-hosted checkout URL; redirect user here\n    session_id: Stripe session ID for reference"
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Required when API_KEY is configured.
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
          scopes:
            api.read: Read access to API
            api.write: Write access to API
      description: OAuth 2.0 / Azure AD authentication (recommended)
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token from OAuth 2.0 / Azure AD