FlashData Billing API

openapi: 3.2.0
info:
  title: FlashData Customer Billing API
  version: 0.2.0-draft
  summary: FlashData control-plane API contract
  description: Google search, YouTube data and media downloads, with endpoints for jobs, accounts, API keys and billing. See /docs for request examples and setup guides.
  contact:
    name: FlashData Engineering
servers:
- url: https://api.flashdata.dev/v2
  description: Management API
tags:
- name: Billing
paths:
  /billing/subscription:
    get:
      operationId: getSubscription
      tags:
      - Billing
      summary: Read the effective Stripe subscription
      security:
      - cookieSession: []
      responses:
        '200':
          description: Subscription or PAYG entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /billing/checkout-sessions:
    post:
      operationId: createCheckoutSession
      tags:
      - Billing
      summary: Create a Stripe-hosted Checkout Session
      description: Subscriptions and published credit packs use priceId. A custom top-up uses amountMinor instead (USD cents, $10 to $999,999.99); the server calculates credits at the fixed credit value and creates a private one-time Stripe price. Product, provider price, currency, success URL and cancel URL are never accepted from the browser. Credits are granted only after a verified paid event for the quoted amount.
      security:
      - cookieSession: []
        csrfToken: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                additionalProperties: false
                required:
                - priceId
                properties:
                  priceId:
                    type: string
                    pattern: ^prc_
                  purchaseType:
                    type: string
                    enum:
                    - subscription
                    - top_up
                    default: subscription
              - type: object
                additionalProperties: false
                required:
                - amountMinor
                - purchaseType
                properties:
                  amountMinor:
                    type: integer
                    minimum: 1000
                    maximum: 99999999
                    description: Custom top-up amount in USD cents.
                  purchaseType:
                    type: string
                    const: top_up
      responses:
        '201':
          description: Stripe Checkout Session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedSession'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/BillingUnavailable'
  /billing/subscription-changes:
    post:
      operationId: createSubscriptionChange
      tags:
      - Billing
      summary: Upgrade the current Stripe subscription to a higher published price
      description: The server verifies that the FlashData price is active, available in the current livemode, USD-denominated, recurring, the same interval, and strictly more expensive than the current subscription price. Product, provider price, currency and proration options are never accepted from the browser. Local entitlement and credits change only after a verified provider event is projected.
      security:
      - cookieSession: []
        csrfToken: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - priceId
              properties:
                priceId:
                  type: string
                  pattern: ^prc_
      responses:
        '201':
          description: Subscription change submitted to Stripe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionChange'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/BillingUnavailable'
  /billing/portal-sessions:
    post:
      operationId: createBillingPortalSession
      tags:
      - Billing
      summary: Create a Stripe Customer Portal Session
      security:
      - cookieSession: []
        csrfToken: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '201':
          description: Stripe Customer Portal Session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedSession'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/BillingUnavailable'
  /billing/subscription-cancellation:
    post:
      operationId: setSubscriptionCancellation
      tags:
      - Billing
      summary: Schedule or undo cancellation of the current paid subscription
      description: Setting cancelAtPeriodEnd to true schedules cancellation at the current billing period end; false keeps the subscription. Entitlements update after a verified Stripe subscription event. This endpoint never cancels immediately or issues a refund.
      security:
      - cookieSession: []
        csrfToken: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - cancelAtPeriodEnd
              properties:
                cancelAtPeriodEnd:
                  type: boolean
      responses:
        '202':
          description: Cancellation update submitted to Stripe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCancellationChange'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '503':
          $ref: '#/components/responses/BillingUnavailable'
  /billing/invoices:
    get:
      operationId: listInvoices
      tags:
      - Billing
      summary: List Stripe invoice projections
      security:
      - cookieSession: []
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Invoices
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Page'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /billing/payments:
    get:
      operationId: listBillingPayments
      tags:
      - Billing
      summary: List account-scoped top-up and refund payment projections
      security:
      - cookieSession: []
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: One-time payment history without provider secrets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPaymentPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication required or invalid
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ValidationError:
      description: Request validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: Resource state or idempotency conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: Authenticated but not permitted, or CSRF validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    BillingUnavailable:
      description: The billing catalog or provider is not configured or is temporarily unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    UpstreamError:
      description: An upstream provider failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Resource not found or not owned by the caller
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    PlanLimits:
      type: object
      additionalProperties: false
      required:
      - concurrency
      - maxBatchSize
      - maxPendingJobs
      properties:
        concurrency:
          type: integer
          minimum: 1
        maxBatchSize:
          type: integer
          minimum: 1
        maxPendingJobs:
          type: integer
          minimum: 1
    Problem:
      type: object
      additionalProperties: false
      required:
      - type
      - title
      - status
      - code
      - requestId
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        code:
          type: string
          pattern: ^[a-z0-9_]+$
        detail:
          type: string
        requestId:
          type: string
          pattern: ^req_
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
    SubscriptionCancellationChange:
      type: object
      additionalProperties: false
      required:
      - id
      - cancelAtPeriodEnd
      - status
      properties:
        id:
          type: string
          pattern: ^sub_
        cancelAtPeriodEnd:
          type: boolean
        status:
          type: string
          enum:
          - submitted
    SubscriptionChange:
      type: object
      additionalProperties: false
      required:
      - id
      - fromPriceId
      - toPriceId
      - effective
      - status
      properties:
        id:
          type: string
          pattern: ^sub_
          description: FlashData subscription public ID. Entitlement still updates only after a verified provider event.
        fromPriceId:
          type: string
          pattern: ^prc_
        toPriceId:
          type: string
          pattern: ^prc_
        effective:
          type: string
          enum:
          - immediate
        status:
          type: string
          enum:
          - submitted
    PlanUsagePrices:
      type: object
      additionalProperties: false
      required:
      - googlePer1kCents
      - youtubePer1kCents
      - downloadPerTbCents
      properties:
        googlePer1kCents:
          type: integer
          minimum: 0
          description: Google request price per 1,000 successful requests, in USD cents.
        youtubePer1kCents:
          type: integer
          minimum: 0
          description: Standard YouTube request price per 1,000 successful requests, in USD cents.
        downloadPerTbCents:
          type: integer
          minimum: 0
          description: Download price per decimal TB (1,000,000,000,000 bytes), in USD cents.
    FieldError:
      type: object
      additionalProperties: false
      required:
      - field
      - code
      - message
      properties:
        field:
          type: string
        code:
          type: string
        message:
          type: string
    Page:
      type: object
      additionalProperties: false
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items: {}
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      additionalProperties: false
      required:
      - hasMore
      - limit
      properties:
        nextCursor:
          type:
          - string
          - 'null'
        previousCursor:
          type:
          - string
          - 'null'
        hasMore:
          type: boolean
        limit:
          type: integer
          minimum: 1
          maximum: 100
    PlanPrice:
      type: object
      additionalProperties: false
      required:
      - id
      - currency
      - unitAmount
      - credits
      - type
      - interval
      properties:
        id:
          type: string
          pattern: ^prc_
        currency:
          type: string
          const: USD
        unitAmount:
          type: integer
          minimum: 0
          description: USD cents
        credits:
          type: number
          minimum: 0
          multipleOf: 0.001
          description: Credits granted by a successful one-time top-up; zero for recurring prices.
        type:
          type: string
          enum:
          - recurring
          - one_time
        interval:
          type:
          - string
          - 'null'
          enum:
          - month
          - year
          - null
    BillingPayment:
      description: Account-scoped top-up projection. Refund state is updated only from verified provider events; this API does not initiate refunds.
      type: object
      additionalProperties: false
      required:
      - id
      - purchaseType
      - status
      - currency
      - amount
      - refundedAmount
      - credits
      - reversedCredits
      - createdAt
      properties:
        id:
          type: string
          pattern: ^pay_
        purchaseType:
          type: string
          const: top_up
        status:
          type: string
          enum:
          - pending
          - paid
          - partially_refunded
          - refunded
          - failed
        currency:
          type: string
          const: USD
        amount:
          type: integer
          minimum: 0
          description: USD cents
        refundedAmount:
          type: integer
          minimum: 0
          description: USD cents
        credits:
          type: number
          minimum: 0
          multipleOf: 0.001
        hostedInvoiceUrl:
          type:
          - string
          - 'null'
          format: uri
          description: Stripe-hosted HTTPS invoice URL, when Stripe created an invoice for this top-up.
        invoiceNumber:
          type:
          - string
          - 'null'
          description: Stripe invoice number, when available.
        reversedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
          description: Cumulative credits removed by append-only payment_reversal entries; never exceeds credits.
        paidAt:
          type:
          - string
          - 'null'
          format: date-time
        refundedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    Invoice:
      type: object
      additionalProperties: false
      required:
      - id
      - number
      - status
      - currency
      - total
      - amountPaid
      - refundedAmount
      - billingReason
      - createdAt
      - periodStart
      - periodEnd
      properties:
        id:
          type: string
          pattern: ^inv_
        number:
          type: string
        status:
          type: string
          enum:
          - draft
          - open
          - paid
          - void
          - uncollectible
        currency:
          type: string
          const: USD
        total:
          type: integer
          description: USD cents
        amountPaid:
          type: integer
          description: USD cents
        refundedAmount:
          type: integer
          minimum: 0
          description: Cumulative USD cents observed from verified provider events.
        billingReason:
          type:
          - string
          - 'null'
          enum:
          - subscription_create
          - subscription_cycle
          - subscription_update
          - null
        hostedInvoiceUrl:
          type:
          - string
          - 'null'
          format: uri
          description: Stripe-hosted HTTPS invoice URL. Production Web clients accept only Stripe-controlled *.stripe.com origins.
        createdAt:
          type: string
          format: date-time
        paidAt:
          type:
          - string
          - 'null'
          format: date-time
        periodStart:
          type:
          - string
          - 'null'
          format: date-time
        periodEnd:
          type:
          - string
          - 'null'
          format: date-time
    Plan:
      type: object
      additionalProperties: false
      required:
      - id
      - slug
      - name
      - description
      - includedCredits
      - limits
      - prices
      - features
      - usagePrices
      properties:
        id:
          type: string
          pattern: ^plan_
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        includedCredits:
          type: number
          minimum: 0
          multipleOf: 0.001
          description: Credits included in each paid subscription cycle; zero for Pay As You Go.
        limits:
          $ref: '#/components/schemas/PlanLimits'
        prices:
          type: array
          items:
            $ref: '#/components/schemas/PlanPrice'
        features:
          type: array
          items:
            type: string
        usagePrices:
          $ref: '#/components/schemas/PlanUsagePrices'
    HostedSession:
      type: object
      additionalProperties: false
      required:
      - id
      - url
      - expiresAt
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
          description: Provider-hosted HTTPS URL on a Stripe-controlled *.stripe.com host. Web clients must validate the origin and redirect from a server-only boundary.
        expiresAt:
          type: string
          format: date-time
    Subscription:
      type: object
      description: Effective entitlement projection. `status=payg` and `id=null` means no billing subscription record exists.
      additionalProperties: false
      required:
      - status
      - plan
      - cancelAtPeriodEnd
      - usageRates
      properties:
        id:
          type:
          - string
          - 'null'
          pattern: ^sub_
        status:
          type: string
          enum:
          - payg
          - trialing
          - active
          - past_due
          - grace
          - cancelled
        plan:
          $ref: '#/components/schemas/Plan'
        usageRates:
          type: object
          description: Account-specific configured credit rates. Query rates come from the account entitlement, not the public plan catalog. One TB is 1,000,000,000,000 bytes; download charges are settled against actual bytes and rounded per result.
          additionalProperties: false
          required:
          - customized
          - queries
          - downloadCreditsPerTb
          properties:
            customized:
              type: boolean
              description: True when an administrator configured rates for this account.
            queries:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - source
                - name
                - creditsPerRequest
                properties:
                  source:
                    type: string
                  name:
                    type: string
                  creditsPerRequest:
                    type: number
                    minimum: 0
            downloadCreditsPerTb:
              type: number
              minimum: 0
        currentPeriodStart:
          type:
          - string
          - 'null'
          format: date-time
        currentPeriodEnd:
          type:
          - string
          - 'null'
          format: date-time
        cancelAtPeriodEnd:
          type: boolean
        graceEndsAt:
          type:
          - string
          - 'null'
          format: date-time
    BillingPaymentPage:
      type: object
      additionalProperties: false
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingPayment'
        pagination:
          $ref: '#/components/schemas/Pagination'
  parameters:
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
        maxLength: 512
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 255
  securitySchemes:
    dataApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: FlashData API key. Job access is restricted to the key's source scopes.
    agentRegistrationProof:
      type: http
      scheme: bearer
      description: Persist a cryptographically random 32-byte base64url proof and exact request BEFORE sending; recover only with the same proof and body. Not an OAuth token.
    cookieSession:
      type: apiKey
      in: cookie
      name: __Host-fd_session
      description: Opaque Web session. The browser cannot read this cookie.
    agentSetupCredential:
      type: http
      scheme: bearer
      description: Temporary setup credential for status and claim creation only. Not a data API key.
    csrfToken:
      type: apiKey
      in: header
      name: X-CSRF-Token
    agentIdentityKey:
      type: http
      scheme: bearer
      description: Ordinary FlashData API key in Authorization Bearer, only on agent identity. Data queries use X-API-Key instead.
    agentHandoffProof:
      type: http
      scheme: bearer
      description: Proof used to recover the owner key and acknowledge installation. Never sent to a data query.