openapi: 3.2.0
info:
  title: Teliax Customer/Billing API
  version: 1.0.0
  contact: {}
  description: 'Operations tagged Customer/Billing across 2 of this provider''s published API definitions: teliax-warp-openapi.json, teliax-warp-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: //api.warp.ringer.tel
tags:
- name: Customer/Billing
paths:
  /v1/billing/balance:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Returns the current balance snapshot for the authenticated customer (current balance, credit limit, available, suspension flag, currency). Errors: NO_ACTIVE_CUSTOMER, INTERNAL_ERROR.'
      tags:
      - Customer/Billing
      summary: Get your account balance
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.Balance'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
      operationId: getV1BillingBalance
      x-operation-id-source: derived
    servers:
    - url: //api.warp.ringer.tel
  /v1/billing/ledger:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Returns your ledger journal (most recent first). limit defaults to 100; values outside (0, 500] are ignored. Errors: NO_ACTIVE_CUSTOMER, INTERNAL_ERROR.

        Rolls the ledger up per SKU so a customer can see what a period was spent on. The raw journal (GET /v1/billing/ledger) remains the reconciliation surface for a single charge.'
      tags:
      - Customer/Billing
      summary: Per-SKU ledger statement for a date range
      parameters:
      - description: Max rows (1-500)
        name: limit
        in: query
        schema:
          type: integer
          default: 100
      - description: Inclusive start, RFC3339 or YYYY-MM-DD. Defaults to 30 days ago.
        name: from
        in: query
        schema:
          type: string
      - description: Exclusive end, RFC3339 or YYYY-MM-DD. Defaults to now.
        name: to
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.LedgerStatement'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
      operationId: getV1BillingLedger
      x-operation-id-source: derived
    servers:
    - url: //api.warp.ringer.tel
  /v1/billing/ledger/statement:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Returns your ledger journal (most recent first). limit defaults to 100; values outside (0, 500] are ignored. Errors: NO_ACTIVE_CUSTOMER, INTERNAL_ERROR.

        Rolls the ledger up per SKU so a customer can see what a period was spent on. The raw journal (GET /v1/billing/ledger) remains the reconciliation surface for a single charge.'
      tags:
      - Customer/Billing
      summary: Per-SKU ledger statement for a date range
      parameters:
      - description: Max rows (1-500)
        name: limit
        in: query
        schema:
          type: integer
          default: 100
      - description: Inclusive start, RFC3339 or YYYY-MM-DD. Defaults to 30 days ago.
        name: from
        in: query
        schema:
          type: string
      - description: Exclusive end, RFC3339 or YYYY-MM-DD. Defaults to now.
        name: to
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.LedgerStatement'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
      operationId: getV1BillingLedgerStatement
      x-operation-id-source: derived
    servers:
    - url: //api.warp.ringer.tel
  /v1/invoices:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Lists your invoices, newest period first. Errors: NO_ACTIVE_CUSTOMER, INTERNAL_ERROR.'
      tags:
      - Customer/Billing
      summary: List invoices
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_repository.InvoiceListItem'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
      operationId: getV1Invoices
      x-operation-id-source: derived
    servers:
    - url: //api.warp.ringer.tel
  /v1/invoices/{id}:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Returns one of your invoices in full (header, lines, tax lines, applications). 404 when the invoice is not found or not owned by you. Errors: NO_ACTIVE_CUSTOMER, NOT_FOUND, INTERNAL_ERROR.'
      tags:
      - Customer/Billing
      summary: Get an invoice
      parameters:
      - description: Invoice id
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_repository.InvoiceDetail'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
      operationId: getV1InvoicesById
      x-operation-id-source: derived
    servers:
    - url: //api.warp.ringer.tel
  /v1/invoices/{id}/html:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Returns one of your invoices as a branded HTML document. Failure responses are JSON. 404 when not found or not owned. Errors: NO_ACTIVE_CUSTOMER, NOT_FOUND, INTERNAL_ERROR.'
      tags:
      - Customer/Billing
      summary: Render your invoice as HTML
      parameters:
      - description: Invoice id
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Branded invoice HTML
          content:
            text/html:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            text/html:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '404':
          description: Not Found
          content:
            text/html:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '500':
          description: Internal Server Error
          content:
            text/html:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
      operationId: getV1InvoicesByIdHtml
      x-operation-id-source: derived
    servers:
    - url: //api.warp.ringer.tel
  /v1/invoices/{id}/pdf:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Renders one of your invoices to PDF on demand. Failure responses are JSON. 503 when the PDF render service is unconfigured or fails. Errors: NO_ACTIVE_CUSTOMER, NOT_FOUND, GATEWAY_UNAVAILABLE.'
      tags:
      - Customer/Billing
      summary: Render your invoice as PDF
      parameters:
      - description: Invoice id
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Invoice PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
          content:
            application/pdf:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '404':
          description: Not Found
          content:
            application/pdf:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        '503':
          description: Service Unavailable
          content:
            application/pdf:
              schema:
                allOf:
                - $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIResponse'
                - type: object
                  properties:
                    error:
                      $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
      operationId: getV1InvoicesByIdPdf
      x-operation-id-source: derived
    servers:
    - url: //api.warp.ringer.tel
components:
  schemas:
    github_com_ringer-warp_api-gateway_internal_repository.InvoiceLineDetail:
      type: object
      properties:
        description:
          type: string
        extended_amount:
          type: number
        quantity:
          type: number
        section:
          type: string
        sku_code:
          type: string
        tax_code:
          type: string
        unit:
          type: string
        unit_price:
          type: number
    github_com_ringer-warp_api-gateway_internal_models.LedgerStatement:
      type: object
      properties:
        charge_total:
          description: 'ChargeTotal is the sum of negative lines only, which is the denominator

            the composition bar proportions against. Summing signed amounts would let

            a payment shrink the bar and misstate every share.'
          type: number
        from:
          type: string
        lines:
          type: array
          items:
            $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.LedgerSKUSummary'
        net_amount:
          description: NetAmount is the signed sum of every line — the period's balance movement.
          type: number
        to:
          type: string
    github_com_ringer-warp_api-gateway_internal_models.Meta:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
    github_com_ringer-warp_api-gateway_internal_repository.InvoiceDetail:
      type: object
      properties:
        amount_paid:
          type: number
        applications:
          type: array
          items:
            $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_repository.InvoiceApplicationItem'
        balance_due:
          type: number
        currency:
          type: string
        customer_id:
          type: string
        due_date:
          type: string
        fee_total:
          type: number
        id:
          type: string
        invoice_number:
          type: string
        issued_at:
          type: string
        lines:
          type: array
          items:
            $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_repository.InvoiceLineDetail'
        period_end:
          type: string
        period_start:
          type: string
        status:
          type: string
        subtotal:
          type: number
        tax_lines:
          type: array
          items:
            $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_repository.InvoiceTaxLineDetail'
        tax_total:
          type: number
        total:
          type: number
    github_com_ringer-warp_api-gateway_internal_repository.InvoiceListItem:
      type: object
      properties:
        amount_paid:
          type: number
        balance_due:
          type: number
        due_date:
          type: string
        id:
          type: string
        invoice_number:
          type: string
        issued_at:
          type: string
        period_end:
          type: string
        period_start:
          type: string
        status:
          type: string
        total:
          type: number
    github_com_ringer-warp_api-gateway_internal_models.LedgerSKUSummary:
      type: object
      properties:
        amount:
          description: 'Amount is signed, matching ledger convention: negative = charge.'
          type: number
        events:
          description: Events is the number of ledger rows behind this line.
          type: integer
        is_usage:
          description: 'IsUsage distinguishes a rated SKU from money-in, so the UI can present

            charges and credits differently without string-matching the label.'
          type: boolean
        quantity:
          description: 'Quantity/Unit are populated for usage-based lines; null for money-in

            rows (payments, credits, adjustments).'
          type: number
        sku_code:
          description: SKUCode is the billing SKU, or the txn_type for money-in rows.
          type: string
        unit:
          type: string
    github_com_ringer-warp_api-gateway_internal_models.Balance:
      type: object
      properties:
        available:
          type: number
        billing_suspended:
          type: boolean
        credit_limit:
          type: number
        currency:
          type: string
        current_balance:
          type: number
        customer_id:
          type: string
    github_com_ringer-warp_api-gateway_internal_repository.InvoiceTaxLineDetail:
      type: object
      properties:
        amount:
          type: number
        is_fee:
          type: boolean
        jurisdiction_code:
          type: string
        jurisdiction_name:
          type: string
        tax_type:
          type: string
        taxable_base:
          type: number
    github_com_ringer-warp_api-gateway_internal_models.APIResponse:
      type: object
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.APIError'
        meta:
          $ref: '#/components/schemas/github_com_ringer-warp_api-gateway_internal_models.Meta'
        success:
          type: boolean
    github_com_ringer-warp_api-gateway_internal_models.APIError:
      type: object
      properties:
        code:
          type: string
        details:
          type: object
          additionalProperties: true
        message:
          type: string
    github_com_ringer-warp_api-gateway_internal_repository.InvoiceApplicationItem:
      type: object
      properties:
        amount_applied:
          type: number
        applied_at:
          type: string
        created_by:
          type: string
        ledger_txn_id:
          type: string
  securitySchemes:
    ApiKeyAuth:
      description: 'API key auth: "Authorization: Bearer rk_..." (live) or "Bearer rk_test_..." (test label). Mint keys in the portal under Settings → API Keys.'
      type: apiKey
      name: Authorization
      in: header
x-refined-from:
- teliax-warp-openapi.json
- teliax-warp-openapi.yml