Skip to main content

​
Overview

Customer invoicing is the sales flow where your platform issues invoices to end customers. This guide covers the complete lifecycle from creating a draft invoice through payment reconciliation.

​
Prerequisites

Before you can issue customer invoices, ensure you have:
  1. Your organization set up with ownership=self
  2. Customer organizations created with ownership=external and role BUYER
  3. Tax registrations configured for jurisdictions where you sell
  4. Product/service definitions with appropriate tax categories

​
Invoice lifecycle

Every invoice follows this lifecycle: 
DRAFT → FINALIZED → (CANCELLED)
  • DRAFT: Invoice is being prepared, can be modified
  • FINALIZED: Invoice is issued, has a sequential number and date
  • CANCELLED: Invoice is voided (not yet implemented)

​
Step 1: Create a draft invoice

Create a sales invoice with up to 10 line items in a single API call. 
curl https://api.nocotax.app/invoices \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "customer_id": "org_customer_123",
    "currency": "EUR",
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [
      {
        "description": "Premium Subscription - Monthly",
        "quantity": 1,
        "unit_extratax_amount": 2900,
        "tax_code": "D10000000"
      },
      {
        "description": "Additional User Seat",
        "quantity": 3,
        "unit_amount": 500,
        "tax_code": "D10000000"
      }
    ]
  }'

​
Key parameters

ParameterDescription
flowMust be sales for customer invoicing
customer_idThe customer organization ID
currencyThree-letter ISO currency code
automatic_tax_calculation.enabledSet to true to calculate tax automatically
itemsArray of up to 10 invoice line items

​
Amounts

All monetary amounts are in the currency’s smallest unit (cents for EUR/USD, etc.).
Setting automatic_tax_calculation.enabled: true will calculate tax based on:
  • Supplier and customer tax registrations
  • Product tax categories
  • Applicable tax rules for the transaction

​
Step 2: Review the draft

The created invoice is in DRAFT status. You can:
  • Review the calculated tax amounts
  • Modify line items if needed
  • Add payment terms or due dates
  • Update billing addresses
While in draft status, the invoice has no invoice number and does not affect AP/AR balances.

​
Step 3: Finalize the invoice

When ready to issue the invoice, finalize it: 
curl https://api.nocotax.app/invoices/inv_123/finalize \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY}
Finalizing the invoice will:
  1. Assign a sequential invoice number
  2. Set the invoice date to the current date
  3. Calculate due_date based on payment_terms (if provided)
  4. Update the customer’s accounts receivable (AR) balance
  5. Lock the invoice from further modifications
  6. Generate the PDF file representing the invoice
Once finalized, an invoice cannot be modified. To correct a finalized invoice, issue a credit note instead.

​
Step 4: Mark as paid

When you receive payment from the customer, mark the invoice as paid: 
curl https://api.nocotax.app/invoices/inv_123/attach_payment \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{}'
This marks the invoice as paid and updates the customer’s AR balance.

​
Recording partial or detailed payments

To record specific payment details: 
curl https://api.nocotax.app/invoices/inv_123/attach_payment \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_data": {
      "amount": 2500,
      "currency": "EUR",
      "transaction_type": "payment",
      "reference": "STRIPE_ch_abc123"
    }
  }'
This allows you to:
  • Record partial payments
  • Link to external payment references (Stripe, bank transfers, etc.)
  • Track payment dates separately from invoice dates

​
Payment status

Nocotax automatically tracks invoice payment status:
StatusDescription
OPENInvoice is due but the due date hasn’t passed
DUEInvoice is past its due date and unpaid
PAIDInvoice has been fully paid
PARTIALLY_PAIDInvoice has received partial payment
The amount_remaining field always shows how much is still owed.

​
Handling corrections

To correct a finalized invoice, issue a credit note:
  1. Create a credit note referencing the original invoice
  2. Finalize the credit note
  3. The credit note automatically reduces the amount_remaining on the invoice
  4. If needed, issue a new corrected invoice
Learn more about credit notes →

​
Next steps

Self-Billing Guide

Learn how to record supplier purchases

Credit Notes

Issue corrections and refunds

Tax Calculations

Understand tax calculation logic

API Reference

View complete API documentation