Skip to main content
Every Kibble invoice has a status field that reflects where it sits in the payment lifecycle, and an overdue boolean derived from the due_date. You can check both with a lightweight status endpoint or retrieve the full invoice record depending on how much data you need.

​
Invoice statuses

The invoice exists in Kibble but the vendor has not been emailed. This happens when you create an invoice with send_now: false. The invoice stays in draft until you call POST /api/invoices/{id}/send.
Kibble has sent the invoice email to the vendor’s address. The vendor can open the hosted invoice page, view the PDF, and send USDC to the deposit address.
The deposit address received a USDC amount less than total_amount. The invoice remains open and the vendor can send the remaining balance to the same deposit address.
The deposit address received more USDC than total_amount. You will need to reconcile the difference with your vendor outside of Kibble.

​
Status lifecycle

draft ──► sent ──► paid
                ├──► partial
                └──► excess
An invoice moves from draft to sent when the vendor email is delivered. Once payment is detected on-chain, Kibble compares the received amount to total_amount and sets the final status to paid, partial, or excess.

​
Overdue detection

The overdue field is a boolean derived from the invoice’s due_date. It is true when today’s date is past the due_date and the invoice has not reached paid status. You can use this field to filter unpaid invoices that need follow-up. 
{
  "status": "sent",
  "overdue": true
}

​
Checking invoice status

Use the lightweight status endpoint when you only need status and overdue:
cURL
curl https://pay.kibble.sh/api/invoices/{id}/status

{
  "status": "paid",
  "overdue": false
}
Use the full invoice endpoint when you need line items, timestamps, vendor details, or snapshot fields:
cURL
curl https://pay.kibble.sh/api/invoices/{id}

{
  "id": "a1b2c3d4-...",
  "invoice_number": "INV-0001",
  "slug": "abc12345",
  "merchant_name_snapshot": "Acme SaaS",
  "merchant_address_snapshot": "123 Main St, SF",
  "vendor_name": "Vendor Co",
  "vendor_email": "vendor@example.com",
  "issue_date": "2026-04-28",
  "due_date": "2026-05-28",
  "total_amount": "1500.00",
  "status": "sent",
  "notes": "Net 30",
  "line_items": [
    {
      "description": "Consulting",
      "quantity": 10,
      "unit_price": "150.00",
      "line_total": "1500.00"
    }
  ],
  "overdue": false,
  "sent_at": "2026-04-28T12:00:00Z"
}
Poll GET /api/invoices/{id}/status rather than the full invoice endpoint when building a payment confirmation loop. It returns less data and is faster to parse.

​
Immutable fields

Three fields on an invoice are written once at creation time and never updated, regardless of any subsequent changes to your account:
FieldDescription
merchant_name_snapshotYour business name as it appeared when the invoice was created
merchant_address_snapshotYour business address as it appeared when the invoice was created
invoice_numberThe sequential invoice number (e.g., INV-0001) assigned at creation
This append-only design means your invoice records stay accurate even if you update your merchant profile later.