OpenAPI 3.1, 18 operations: ingest, rate, invoice, credit, dispute, reconcile.

openapi: 3.1.0
info:
  title: Reliance Intelligence — Metering, Billing, Settlement & Revenue Platform API
  version: 1.0.0
  description: |
    Internal + partner API for the capacity (GPU-hour) and token (inference) businesses.

    ## Non-negotiable conventions
    - **Money is integer minor units** (paise for INR, cents for USD) in every field ending `_minor`.
      Rates and quantities are **decimal strings**, never JSON numbers — IEEE-754 cannot represent
      them exactly and rating must be byte-reproducible.
    - **Every mutating call requires `Idempotency-Key`.** Replaying a key within 7 days returns the
      ORIGINAL response with `Idempotent-Replay: true`. Same key + different body = `409`.
    - **Time is RFC3339 UTC** with microsecond precision. Billing periods are evaluated in
      `Asia/Kolkata` for Indian selling entities; the boundary conversion happens once, in the
      period resolver, never ad hoc in a service.
    - **Nothing is deleted.** Corrections are compensating records. `DELETE` exists only for
      draft objects that were never issued.
    - **Pagination** is cursor-based (`page[size]`, `page[after]`); offset paging is not offered
      because the event tables are append-only and large.
  contact: { name: Platform Billing Engineering, email: billing-eng@ril-intelligence.in }

servers:
  - url: https://billing.internal.ril-intelligence.in/v1
    description: Production (in-jamnagar-1 primary, in-mumbai-2 standby)
  - url: https://billing.stage.internal.ril-intelligence.in/v1
    description: Staging

security:
  - mtls: []
  - oauth2: [billing.read]

tags:
  - name: Metering
    description: Usage-event ingestion and query. The only write path for billable quantities.
  - name: Pricing
    description: Versioned price books. Four-eyes gated.
  - name: Rating
    description: Deterministic conversion of usage to money.
  - name: Billing
    description: Invoice assembly, issue, credit notes, India e-invoicing (IRN).
  - name: Settlement
    description: Payments, application, TDS, dunning, disputes.
  - name: Contracts
    description: Take-or-pay reservations and committed-spend drawdown.
  - name: Revenue
    description: Ind AS 115 schedules, deferred revenue, RPO/backlog.
  - name: Assurance
    description: Three-way match, breaks, leakage findings.

paths:
  /usage/events:batch:
    post:
      tags: [Metering]
      operationId: ingestUsageEvents
      summary: Ingest a batch of usage events
      description: |
        The single ingestion path. Accepts up to 5,000 events per call.

        **Partial success is the contract.** A batch never fails wholesale for a bad element:
        each event is accepted, deduplicated, or rejected individually and the response reports
        per-event outcomes. This exists because a producer that must drop an entire batch to get
        past one malformed event will drop *revenue*.

        **Dedup**: on `event_id`, 7-day window in the stream layer plus a permanent unique index
        in the rating ledger. A duplicate returns `deduplicated`, not an error.

        **Clock guard**: events with `occurred_at` more than 500 ms in the future, or older than
        the configured late-event window (default 72 h), are accepted but flagged
        `quarantined` — they land in the quarantine topic for operator disposition rather than
        being silently rated or silently lost.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [events]
              properties:
                events:
                  type: array
                  minItems: 1
                  maxItems: 5000
                  items: { $ref: '#/components/schemas/UsageEvent' }
      responses:
        '202':
          description: Batch accepted; see per-event results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted: { type: integer }
                  deduplicated: { type: integer }
                  quarantined: { type: integer }
                  rejected: { type: integer }
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        event_id: { type: string, format: uuid }
                        status: { type: string, enum: [accepted, deduplicated, quarantined, rejected] }
                        reason: { type: [string, 'null'] }
        '400': { $ref: '#/components/responses/BadRequest' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /usage/events/{event_id}:
    get:
      tags: [Metering]
      operationId: getUsageEvent
      summary: Fetch a raw usage event
      description: Disputes are settled by replaying raw events, not by arguing about aggregates. This endpoint is the evidence path and is retained for 25 months hot / 8 years cold.
      parameters:
        - name: event_id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UsageEvent' }
        '404': { $ref: '#/components/responses/NotFound' }

  /usage/aggregate:
    get:
      tags: [Metering]
      operationId: aggregateUsage
      summary: Aggregate billable metrics for a period
      description: |
        Read-only rollup used by the customer portal, the deal desk, and the completeness control.
        Returns both the aggregate and `event_count`, so the caller can assert completeness against
        the raw store rather than trusting a number.
      parameters:
        - { name: account_id, in: query, required: true, schema: { type: string } }
        - { name: from, in: query, required: true, schema: { type: string, format: date-time } }
        - { name: to, in: query, required: true, schema: { type: string, format: date-time } }
        - { name: group_by, in: query, schema: { type: string, example: 'sku,project_id,service_tier' } }
        - name: leg
          in: query
          description: Which reconciliation leg to aggregate. Defaults to intent (the billable leg).
          schema: { type: string, enum: [intent, reality], default: intent }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      type: object
                      properties:
                        key: { type: object, additionalProperties: { type: string } }
                        meter: { type: string }
                        quantity: { type: string, description: Decimal string. }
                        unit: { type: string }
                        event_count: { type: integer }

  /pricebooks:
    post:
      tags: [Pricing]
      operationId: createPriceBookVersion
      summary: Create a draft price-book version
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PriceBook' }
      responses:
        '201': { description: Draft created., content: { application/json: { schema: { $ref: '#/components/schemas/PriceBook' } } } }

  /pricebooks/{price_book_id}/versions/{version}:publish:
    post:
      tags: [Pricing]
      operationId: publishPriceBook
      summary: Publish a price-book version (four-eyes)
      description: |
        **Rejects with `422` if `approval.approved_by` equals `approval.authored_by`.** This is
        enforced in the API, not in policy documents, because the single most common source of
        material rating leakage is an unreviewed rate-table change.

        Publishing is effective-dated and never retroactive past a closed accounting period; an
        attempt to publish `effective_from` inside a closed period returns `409`.
      parameters:
        - { name: price_book_id, in: path, required: true, schema: { type: string } }
        - { name: version, in: path, required: true, schema: { type: integer } }
        - { $ref: '#/components/parameters/IdempotencyKey' }
      responses:
        '200': { description: Published. }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Unprocessable' }

  /rating/runs:
    post:
      tags: [Rating]
      operationId: createRatingRun
      summary: Rate (or re-rate) a period
      description: |
        Orchestrated as a Temporal workflow. `mode=dry_run` produces rated lines in a shadow
        namespace and a diff against the last committed run — this is the pre-close control and
        the mechanism by which a rating change is proven safe before it touches revenue.

        `mode=rerate` supersedes prior lines (setting `rating.rerate_of`) and emits reversal +
        replacement lines. It never mutates.
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tenant_id, period_start, period_end, mode]
              properties:
                tenant_id: { type: string }
                account_ids: { type: array, items: { type: string }, description: Omit for all accounts. }
                period_start: { type: string, format: date-time }
                period_end: { type: string, format: date-time }
                mode: { type: string, enum: [commit, dry_run, rerate] }
                reason: { type: [string, 'null'], description: Required for rerate. }
      responses:
        '202':
          description: Run started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id: { type: string }
                  workflow_id: { type: string }
                  status: { type: string, enum: [queued, running, completed, failed] }

  /rating/runs/{run_id}:
    get:
      tags: [Rating]
      operationId: getRatingRun
      summary: Rating run status, totals, and diff
      parameters: [{ name: run_id, in: path, required: true, schema: { type: string } }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id: { type: string }
                  status: { type: string }
                  engine_version: { type: string }
                  lines_created: { type: integer }
                  total_net_minor: { type: integer }
                  diff_vs_previous:
                    type: object
                    description: Present for dry_run. A material diff blocks the close until explained.
                    properties:
                      delta_net_minor: { type: integer }
                      accounts_changed: { type: integer }
                      largest_movers: { type: array, items: { type: object } }

  /rated-lines:
    get:
      tags: [Rating]
      operationId: listRatedLines
      summary: Query rated lines
      parameters:
        - { name: account_id, in: query, schema: { type: string } }
        - { name: invoice_id, in: query, schema: { type: [string, 'null'], description: 'Pass the literal string null to find UNBILLED usage.' } }
        - { name: period_start, in: query, schema: { type: string, format: date-time } }
        - { name: period_end, in: query, schema: { type: string, format: date-time } }
        - { $ref: '#/components/parameters/PageSize' }
        - { $ref: '#/components/parameters/PageAfter' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/RatedLineItem' } }
                  next_cursor: { type: [string, 'null'] }

  /invoices:assemble:
    post:
      tags: [Billing]
      operationId: assembleInvoice
      summary: Assemble a draft invoice from rated lines
      description: |
        Groups rated lines, resolves tax, applies statutory round-off once at document level, and
        allocates **no invoice number** — numbering happens at issue, so a failed assembly never
        burns a number in the gapless GST series.
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tenant_id, account_id, period_start, period_end]
              properties:
                tenant_id: { type: string }
                account_id: { type: string }
                period_start: { type: string, format: date-time }
                period_end: { type: string, format: date-time }
                include_unbilled_prior_periods: { type: boolean, default: true, description: Sweeps rated lines left unbilled by earlier cycles. Leaving this false is how unbilled usage ages. }
      responses:
        '201':
          description: Draft invoice.
          content: { application/json: { schema: { $ref: '#/components/schemas/Invoice' } } }

  /invoices/{invoice_id}:issue:
    post:
      tags: [Billing]
      operationId: issueInvoice
      summary: Issue an invoice (allocates number, triggers IRN)
      description: |
        Transactional sequence, all-or-nothing on the number allocation:
        1. Allocate the next number from the `(gstin, fy, series)` sequence under row lock.
        2. Persist the document as immutable; compute `pdf_sha256`.
        3. Enqueue IRN registration with the IRP (asynchronous, retried with backoff).

        The invoice reaches `issued` after step 2. IRP registration is **not** in the critical
        path — an IRP outage must never block billing — but `gst.irp_status` stays `pending`
        and the 30-day reporting clock is monitored (alert at T+7, page at T+21).
      parameters:
        - { name: invoice_id, in: path, required: true, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/IdempotencyKey' }
      responses:
        '200': { description: Issued., content: { application/json: { schema: { $ref: '#/components/schemas/Invoice' } } } }
        '409': { $ref: '#/components/responses/Conflict' }

  /invoices/{invoice_id}/credit-notes:
    post:
      tags: [Billing]
      operationId: createCreditNote
      summary: Issue a credit note against an invoice
      description: |
        The ONLY way to reduce an issued invoice. Requires `credit_reason`; reasons are
        governed — `billing_error` is the only value that counts against the billing-accuracy KPI,
        and `commercial_goodwill` above a threshold requires an approval reference.
        A credit note is itself a GST document and gets its own IRN.
      parameters:
        - { name: invoice_id, in: path, required: true, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/IdempotencyKey' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [credit_reason, lines]
              properties:
                credit_reason: { type: string, enum: [sla_credit, billing_error, commercial_goodwill, dispute_settlement, cancellation, rerate_adjustment] }
                approval_ref: { type: [string, 'null'] }
                lines: { type: array, items: { type: object } }
      responses:
        '201': { description: Credit note created., content: { application/json: { schema: { $ref: '#/components/schemas/Invoice' } } } }

  /invoices/{invoice_id}/irn:
    post:
      tags: [Billing]
      operationId: registerIRN
      summary: Register (or re-attempt) the invoice with the IRP
      description: Idempotent against the IRP's own duplicate-IRN response — a `2150 Duplicate IRN` from the portal is treated as SUCCESS and the returned IRN is stored, not as an error.
      parameters:
        - { name: invoice_id, in: path, required: true, schema: { type: string, format: uuid } }
        - { $ref: '#/components/parameters/IdempotencyKey' }
      responses:
        '200': { description: Registered. }
        '424': { description: IRP unavailable or rejected; retry scheduled. }

  /contracts/{contract_id}/commitment:
    get:
      tags: [Contracts]
      operationId: getCommitmentBalance
      summary: Take-or-pay / committed-spend position
      description: |
        Returns the drawdown state that the rating engine used, not a recomputation. Fields
        distinguish **consumed**, **committed**, **overage**, and **forfeited** — the last is the
        take-or-pay economics made visible, and customers who cannot see it dispute it.
      parameters: [{ name: contract_id, in: path, required: true, schema: { type: string } }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  contract_id: { type: string }
                  period_start: { type: string, format: date-time }
                  period_end: { type: string, format: date-time }
                  committed_minor: { type: integer }
                  consumed_minor: { type: integer }
                  overage_minor: { type: integer }
                  forfeited_minor: { type: integer }
                  rollover_minor: { type: integer }
                  rollover_expires_at: { type: [string, 'null'], format: date-time }

  /payments:
    post:
      tags: [Settlement]
      operationId: recordPayment
      summary: Record a receipt
      description: |
        Handles the Indian enterprise reality that customers remit **net of TDS**
        (typically 2% u/s 194J for technical services). A receipt short by exactly the expected
        TDS is applied as `paid_with_withholding` and does NOT open a dispute; the residual sits in a
        TDS-receivable control account until the Form 16A / 26AS credit is matched.
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [account_id, amount_minor, currency, value_date, method]
              properties:
                account_id: { type: string }
                amount_minor: { type: integer }
                currency: { type: string }
                value_date: { type: string, format: date }
                method: { type: string, enum: [neft, rtgs, upi, swift, card, credit_note_offset] }
                bank_reference: { type: [string, 'null'] }
                remittance_advice: { type: [array, 'null'], items: { type: object }, description: Invoice-level allocation supplied by the payer, when present. }
                withholding_minor: { type: integer, default: 0 }
      responses:
        '201': { description: Recorded and applied. }

  /reconciliation/runs:
    post:
      tags: [Assurance]
      operationId: runReconciliation
      summary: Execute the three-way match
      description: |
        Compares **intent** (control-plane allocation ledger) vs **reality** (node/serving telemetry)
        vs **billing** (rated + invoiced). Runs daily at 02:00 IST plus on demand. Breaks above the
        materiality threshold open findings with an owner and a closure SLA.
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tenant_id, date]
              properties:
                tenant_id: { type: string }
                date: { type: string, format: date }
                materiality_minor: { type: integer, default: 100000 }
      responses:
        '202': { description: Run started. }

  /reconciliation/breaks:
    get:
      tags: [Assurance]
      operationId: listBreaks
      summary: Open reconciliation breaks
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [open, investigating, resolved, accepted] } }
        - { name: category, in: query, schema: { type: string, enum: [unmetered_usage, meter_to_bill_gap, rating_error, entitlement_drift, sla_over_crediting, fraud, contract_leakage, tokenizer_drift] } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        break_id: { type: string }
                        category: { type: string }
                        account_id: { type: [string, 'null'] }
                        estimated_value_minor: { type: integer }
                        intent_qty: { type: string }
                        reality_qty: { type: string }
                        billed_qty: { type: string }
                        first_seen: { type: string, format: date-time }
                        status: { type: string }
                        owner: { type: [string, 'null'] }

  /revenue/schedules:
    get:
      tags: [Revenue]
      operationId: listRevenueSchedules
      summary: Ind AS 115 recognition schedule
      description: Period-by-period recognized, deferred, and unbilled-receivable amounts by performance obligation. This is the ledger's source for the revenue journal; finance does not re-derive it in a spreadsheet.
      parameters:
        - { name: tenant_id, in: query, required: true, schema: { type: string } }
        - { name: period, in: query, required: true, schema: { type: string, example: '2026-08' } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  period: { type: string }
                  recognized_minor: { type: integer }
                  deferred_closing_minor: { type: integer }
                  unbilled_receivable_minor: { type: integer }
                  variable_consideration_minor: { type: integer }
                  by_obligation: { type: array, items: { type: object } }

  /revenue/rpo:
    get:
      tags: [Revenue]
      operationId: getRPO
      summary: Remaining performance obligations (backlog)
      description: |
        Contracted-but-unrecognized revenue with expected conversion by period. This is the number
        lenders underwrite and the number that must tie to the disclosed backlog — it is computed
        from contract lines and delivery/acceptance state, never typed in.
      parameters:
        - { name: tenant_id, in: query, required: true, schema: { type: string } }
        - { name: as_of, in: query, required: true, schema: { type: string, format: date } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  as_of: { type: string, format: date }
                  total_rpo_minor: { type: integer }
                  expected_conversion:
                    type: array
                    items:
                      type: object
                      properties:
                        period: { type: string }
                        amount_minor: { type: integer }
                        contingent_on_acceptance_minor: { type: integer, description: The portion that converts only if capacity passes acceptance on schedule. Disclosing this separately is the honest version of backlog. }

components:
  securitySchemes:
    mtls: { type: mutualTLS }
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.internal.ril-intelligence.in/oauth2/token
          scopes:
            billing.read: Read billing data
            billing.write: Ingest usage and create documents
            billing.admin: Publish price books, issue credit notes

  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: "Client-generated UUID. Replay within 7 days returns the original response with `Idempotent-Replay: true`."
      schema: { type: string, format: uuid }
    PageSize:
      name: page[size]
      in: query
      schema: { type: integer, minimum: 1, maximum: 1000, default: 100 }
    PageAfter:
      name: page[after]
      in: query
      schema: { type: string }

  responses:
    BadRequest:
      description: Malformed request.
      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
    NotFound:
      description: Not found.
      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
    Conflict:
      description: State conflict (e.g. already issued, closed period, idempotency-key body mismatch).
      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
    Unprocessable:
      description: Semantically invalid (e.g. self-approved price book).
      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
    RateLimited:
      description: Too many requests.
      content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }

  schemas:
    Problem:
      type: object
      description: RFC 9457 problem details.
      properties:
        type: { type: string }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string }
        errors:
          type: array
          items:
            type: object
            properties:
              pointer: { type: string }
              code: { type: string }
              message: { type: string }
    UsageEvent:
      $ref: '../schemas/usage_event.envelope.schema.json'
    PriceBook:
      $ref: '../schemas/price_book.schema.json'
    RatedLineItem:
      $ref: '../schemas/rated_line_item.schema.json'
    Invoice:
      $ref: '../schemas/invoice.schema.json'