Invoice

An Invoice is a cumulative billing statement that aggregates charges for a payer over a defined billing period. Unlike one-time payments (which are settled per-request) or subscriptions (which are pre-paid recurring plans), invoices are post-paid — the payer consumes the service throughout the period and settles all charges at the end.

Invoices are the core of the ItPay Protocol's cumulative payment capability, enabling pay-as-you-go billing for AI services where usage is metered by tokens, requests, processing time, or any other unit.

---

Fields

Field	Type	Description
id	string (UUIDv7)	Globally unique invoice identifier
service_id	string	The ServiceManifest id for the billed service
payer	Party	Identity of the party responsible for payment
period	BillingPeriod	The time range this invoice covers
line_items	LineItem[]	Individual charge entries comprising the invoice
total	Money	Total amount due
status	Status	Current state of the invoice
due_date	string (ISO 8601)	Deadline for payment before the invoice becomes overdue
paid_at	string (ISO 8601)	Timestamp when the invoice was paid
created_at	string (ISO 8601)	Timestamp of invoice generation
updated_at	string (ISO 8601)	Timestamp of last status change

Party

Field	Type	Description
agent_id	string	Unique ID of the paying agent
human_id	string	Optional — ID of the human user responsible

BillingPeriod

Field	Type	Description
start	string (ISO 8601)	Start of the billing period
end	string (ISO 8601)	End of the billing period

LineItem

Field	Type	Description
date	string (ISO 8601)	Date/time of the chargeable event
description	string	What the charge is for
quantity	number	Number of units consumed
unit	string	Unit of measurement (e.g. "token", "request", "second")
rate	number	Price per unit in the invoice currency
amount	number	Total line amount (quantity × rate) in minor currency units

Money

Field	Type	Description
currency	string (ISO 4217)	Currency code
amount	number	Total amount due in minor currency units (e.g. cents)

Status

Status	Description
open	Invoice has been generated and is awaiting payment
paid	Invoice has been settled in full
overdue	due_date has passed without payment
void	Invoice has been invalidated (e.g. due to dispute or adjustment)

---

JSON Example

{
  "id": "inv_01J7YB5C6D7E8F9G0H1I2J3K4",
  "service_id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
  "payer": {
    "agent_id": "agent_cli_a1b2c3d4",
    "human_id": "user_abc_789"
  },
  "period": {
    "start": "2026-05-01T00:00:00Z",
    "end": "2026-05-31T23:59:59Z"
  },
  "line_items": [
    {
      "date": "2026-05-01T08:12:33Z",
      "description": "Document summary — annual_report_2025.pdf (89 pages)",
      "quantity": 12460,
      "unit": "token",
      "rate": 0.003,
      "amount": 37
    },
    {
      "date": "2026-05-07T14:30:01Z",
      "description": "Document summary — meeting_notes_may6.txt (12 pages)",
      "quantity": 1800,
      "unit": "token",
      "rate": 0.003,
      "amount": 5
    },
    {
      "date": "2026-05-14T09:05:47Z",
      "description": "Document summary — research_paper_quantum.pdf (234 pages)",
      "quantity": 32760,
      "unit": "token",
      "rate": 0.003,
      "amount": 98
    },
    {
      "date": "2026-05-22T16:44:12Z",
      "description": "Document summary — contract_draft_v3.docx (56 pages)",
      "quantity": 7840,
      "unit": "token",
      "rate": 0.003,
      "amount": 24
    },
    {
      "date": "2026-05-29T11:20:08Z",
      "description": "Document summary — technical_spec.pdf (178 pages)",
      "quantity": 24920,
      "unit": "token",
      "rate": 0.003,
      "amount": 75
    }
  ],
  "total": {
    "currency": "USD",
    "amount": 239
  },
  "status": "open",
  "due_date": "2026-06-07T23:59:59Z",
  "paid_at": null,
  "created_at": "2026-06-01T00:00:00Z",
  "updated_at": "2026-06-01T00:00:00Z"
}

---

State Machine

                ┌──────────┐
                │  open    │
                └──┬───┬───┘
           pays    │   │ due_date  │ void
                   │   │ passes    │
                   ▼   ▼           │
            ┌───────────┐          │
            │  overdue  │          │
            └─────┬─────┘          │
                  │ pays           │
                  ▼                ▼
            ┌──────────┐    ┌──────────┐
            │  paid    │    │  void    │
            └──────────┘    └──────────┘

Transitions

From	To	Trigger
open	paid	Full payment is received before the due date
open	overdue	due_date passes without full payment
open	void	Provider voids the invoice (e.g. adjustment, dispute)
overdue	paid	Full payment is received after the due date
overdue	void	Provider voids the overdue invoice
paid	—	Terminal state — no further transitions
void	—	Terminal state — no further transitions

---

Key Behaviors

• Post-paid by design: Invoices are generated at the end of a billing period based on recorded usage. This contrasts with subscriptions (pre-paid) and one-time payments (per-request).
• Line items are immutable: Once an invoice is generated, its line items cannot be changed. Corrections require voiding the invoice and generating a new one with adjusted line items.
• Partial payments: By default, the protocol requires full payment of the total.amount to transition the invoice to paid. Partial payments are supported at the channel level but are reflected in the invoice only after the full amount is settled.
• Overdue handling: When an invoice becomes overdue, the provider may block further service access until payment is received. The provider determines the grace period and service degradation policy.
• Reconciliation: Each line item's amount is the product of quantity × rate rounded to the nearest minor currency unit. The total.amount is the sum of all line item amounts. Discrepancies (e.g. due to rounding) are resolved in the provider's favour.
• Invoice vs PaymentIntent: An invoice generates a PaymentIntent of type "cumulative" when the payer initiates settlement. The PaymentIntent tracks the real-time payment status, while the Invoice is the authoritative billing record.