Invoice Lifecycle

Status Transition Rules

Not all status transitions are permitted. Here’s what’s allowed:

From	To	Allowed?
`DRAFT`	`OPEN`	✅ (finalize)
`OPEN`	`PAID`	✅
`OPEN`	`VOID`	✅
`OPEN`	`UNCOLLECTIBLE`	✅
`UNCOLLECTIBLE`	`PAID`	✅ (late payment)
`UNCOLLECTIBLE`	`VOID`	✅
`UNCOLLECTIBLE`	`OPEN`	❌ Cannot reopen
`VOID`	anything	❌ Void is permanent
`PAID`	anything	❌ Cannot change paid invoices

Managing Invoice Status

Mark as Paid

POST /api/v1/invoices/<invoice_id>/pay

Update Status with Note

curl -X PATCH https://api.fluxrate.co/api/v1/invoices/<invoice_id>/status \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<token>" \
  -d '{
    "status": "VOID",
    "note": "Duplicate invoice — customer was double-billed"
  }'

Editing Draft Invoices

DRAFT invoices can be edited (line items, due date, customer):

curl -X PUT https://api.fluxrate.co/api/v1/invoices/<invoice_id> \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<token>" \
  -d '{
    "due_date": "2025-02-14T00:00:00Z",
    "line_items": [
      {
        "description": "Pro subscription (Feb 2025)",
        "quantity": 1,
        "unit_amount": 49.00
      },
      {
        "description": "API calls overage (12,000 calls)",
        "quantity": 12000,
        "unit_amount": 0.001
      }
    ]
  }'

Only DRAFT invoices can be edited. Once finalized to OPEN, the invoice is immutable.

Deleting an Invoice

DELETE /api/v1/invoices/<invoice_id>

Only DRAFT invoices can be deleted. This is permanent.

Invoice Metadata

Status changes can be annotated with notes and are stored in meta_data:

{
  "meta_data": {
    "status_change_note": "Customer dispute resolved",
    "status_change_timestamp": "2025-01-15T14:30:00Z",
    "previous_status": "OPEN"
  }
}

Get Started

Product Guide

Developer Guides

Invoice Lifecycle

Status Transition Rules

Managing Invoice Status

Mark as Paid

Update Status with Note

Editing Draft Invoices

Deleting an Invoice

Invoice Metadata

​Status Transition Rules

​Managing Invoice Status

​Mark as Paid

​Update Status with Note

​Editing Draft Invoices

​Deleting an Invoice

​Invoice Metadata

Status Transition Rules

Managing Invoice Status

Mark as Paid

Update Status with Note

Editing Draft Invoices

Deleting an Invoice

Invoice Metadata