openapi: "3.0.3"
info:
  title: "Billing and invoices API"
  version: "1.0.0"
  description: "The invoice number is generated by the billing service and must be unique across the whole tenant set. tax_rate_bp is expressed in basis points, so the valid range is zero to ten thousand and the check constraint says exactly that. A void invoice still keeps its lines, which is why the void status is an enum member rather than a deleted row. Currency is a three-letter code, and the CHECK constraint is the cheapest way to catch a currency field that received a currency symbol."
paths: {}
x-domain-id: "billing"
x-dialect: "postgres"
components:
  schemas:
    customers:
      type: "object"
      x-primary-key: "id"
      required: ["id", "email", "currency"]
      properties:
        id:
          type: "string"
          format: "uuid"
        email:
          type: "string"
          format: "email"
          x-unique: true
        currency:
          type: "string"
          minLength: 3
          maxLength: 3
    invoices:
      type: "object"
      x-primary-key: "id"
      required: ["id", "customer_id", "number", "status", "issued_at", "total_cents"]
      properties:
        id:
          type: "string"
          format: "uuid"
        customer_id:
          $ref: "#/components/schemas/customers"
        number:
          type: "string"
          x-unique: true
        status:
          type: "string"
          enum: ["draft", "open", "paid", "void"]
        issued_at:
          type: "string"
          format: "date-time"
        total_cents:
          type: "integer"
          minimum: 0
    invoice_lines:
      type: "object"
      x-primary-key: "id"
      required: ["id", "invoice_id", "description", "amount_cents", "tax_rate_bp"]
      properties:
        id:
          type: "string"
          format: "uuid"
        invoice_id:
          $ref: "#/components/schemas/invoices"
        description:
          type: "string"
        amount_cents:
          type: "integer"
        tax_rate_bp:
          type: "integer"
          minimum: 0
          maximum: 10000
