Invoices Lifecycle

​

Invoice states

​

draft

• No invoice number or date
• Does not affect AP/AR balances
• Can update amounts, line items, tax
• Can be deleted

​

finalized

• Has sequential invoice number
• Has official invoice date
• Due date calculated (if payment_terms provided)
• Affects AP/AR balances
• Immutable - corrections require credit notes

​

cancelled

​

State transitions

draft → finalize → finalized → cancel → cancelled

​

Creating an invoice

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "items": [
      {
        "title": "Monthly Subscription",
        "quantity": 1,
        "unit_extratax_amount": "99.00"
      }
    ]
  }'

​

Finalizing an invoice

curl https://api.nocotax.app/invoices/inv_123/finalize \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY}

1. Invoice number assigned
2. Invoice date set to today
3. Due date calculated (from payment_terms)
4. AP/AR balances updated
5. Invoice locked from changes

​

Payment status

​

Working with finalized invoices

​

Attaching payments

​

Cancelling an invoice

curl https://api.nocotax.app/invoices/inv_123/cancel \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY}

1. The invoice status becomes cancelled
2. A credit note with the same items as the invoice is created. Credit notes that already exist on the invoice do not change this
3. The invoice can no longer be modified

​

Correcting errors

curl https://api.nocotax.app/credit_notes \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "invoice_id": 'inv_123',
    "items": [
      {
        "title": "Monthly Subscription",
        "quantity": 1,
        "unit_extratax_amount": "99.00"
      }
    ]
  }'

​

Best practices

• Review drafts carefully before finalizing
• Finalize invoices promptly - don’t leave in draft
• Use payment_terms for automatic due date calculation
• Issue credit notes for corrections, never modify finalized invoices
• Track payment status for automated reminders