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:
- Your organization set up with
ownership=self
- Customer organizations created with
ownership=external and role BUYER
- Tax registrations configured for jurisdictions where you sell
- 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
| Parameter | Description |
|---|
flow | Must be sales for customer invoicing |
customer_id | The customer organization ID |
currency | Three-letter ISO currency code |
automatic_tax_calculation.enabled | Set to true to calculate tax automatically |
items | Array 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}
- Assign a sequential invoice number
- Set the invoice date to the current date
- Calculate
due_date based on payment_terms (if provided)
- Update the customer’s accounts receivable (AR) balance
- Lock the invoice from further modifications
- 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 '{}'
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"
}
}'
- 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:
| Status | Description |
|---|
OPEN | Invoice is due but the due date hasn’t passed |
DUE | Invoice is past its due date and unpaid |
PAID | Invoice has been fully paid |
PARTIALLY_PAID | Invoice has received partial payment |
amount_remaining field always shows how much is still owed.
Handling corrections
To correct a finalized invoice, issue a credit note:
- Create a credit note referencing the original invoice
- Finalize the credit note
- The credit note automatically reduces the
amount_remaining on the invoice
- If needed, issue a new corrected invoice
Learn more about credit notes →
Next steps
