{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "CreateInvoiceRequest.json",
  "title": "Invoice (request)",
  "description": "Body for raising an invoice.",
  "type": "object",
  "properties": {
    "externalRef": {
      "type": "string",
      "description": "Your stable reference for this invoice, such as ws_42-2026-11. At most 100 characters, unique per organization. A repeat returns the existing invoice."
    },
    "customerId": {
      "type": "integer",
      "format": "int32",
      "description": "A customer in the organization."
    },
    "currency": {
      "type": "string",
      "enum": [
        "NGN",
        "USD",
        "CAD",
        "EUR",
        "GBP"
      ],
      "description": "A supported ISO currency code."
    },
    "dueDate": {
      "type": "string",
      "format": "date",
      "description": "When payment is due. Send YYYY-MM-DD."
    },
    "discount": {
      "type": "number",
      "format": "decimal",
      "description": "0 or more, and no more than the subtotal. Default 0."
    },
    "periodStart": {
      "type": "string",
      "format": "date",
      "description": "Billing period start. Send it together with periodEnd, or neither."
    },
    "periodEnd": {
      "type": "string",
      "format": "date",
      "description": "Billing period end. On or after periodStart."
    },
    "invoiceType": {
      "type": "string",
      "enum": [
        "setup",
        "build",
        "subscription",
        "usage",
        "performance",
        "mixed",
        "other"
      ],
      "description": "The kind of invoice."
    },
    "nextDueDate": {
      "type": "string",
      "format": "date",
      "description": "When the next cycle's invoice is due. Informational."
    },
    "comments": {
      "type": "string",
      "description": "A note for the organization's reviewers."
    },
    "lines": {
      "type": "array",
      "items": {
        "$ref": "InvoiceLineInput.json"
      },
      "description": "At least one line. The subtotal is the sum of the lines; you can't send a total."
    }
  },
  "required": [
    "customerId",
    "currency",
    "dueDate",
    "lines"
  ],
  "examples": [
    {
      "externalRef": "ws_42-2026-11",
      "customerId": 812,
      "currency": "NGN",
      "dueDate": "2026-11-15",
      "discount": 0,
      "periodStart": "2026-11-01",
      "periodEnd": "2026-11-30",
      "invoiceType": "subscription",
      "nextDueDate": "2026-12-01",
      "comments": "November subscription",
      "lines": [
        {
          "serviceId": 7,
          "quantity": 3,
          "unitPrice": 250000,
          "detail": "3 entities"
        },
        {
          "serviceId": 9,
          "amount": 50000
        }
      ]
    }
  ]
}