Customer Invoicing

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. Only a finalized invoice can be cancelled, and cancelling it creates a credit note with the same items

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 \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "customer_id": "org_customer_123",
    "currency": "EUR",
    "order_reference": "ORD-12345",
    "period": {
      "start": "2025-12-15T00:00:00Z",
      "end": "2025-12-31T00:00:00Z"
    },
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [
      {
        "title": "Premium Subscription - Monthly",
        "quantity": 1,
        "unit_extratax_amount": "29.00",
        "product": {
          "tax_code": "D10000000"
        }
      },
      {
        "title": "Additional User Seat",
        "quantity": 3,
        "unit_extratax_amount": "5.00",
        "product": {
          "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
`order_reference`	Optional. Your order identifier, inherited by the lines. Needed to reconcile sales with supplier costs
`period`	Optional. Service period, inherited by the lines. Drives the accounting period

To record a complete order, including the supplier cost, see Record an order.

Amounts

Nocotax uses two conventions, and it is important not to mix them:

Accounting amounts (extratax_amount, tax_included_amount, totals, amount_remaining, payment amount…) are integers in the currency’s smallest unit: 9900 in USD = 99.00 USD.
Unit prices (unit_extratax_amount, unit_tax_included_amount) are decimal strings in the currency’s main unit: "99.2842" = 99.2842 USD.

In the example above, the first item costs "29.00" EUR per unit and the second "5.00" EUR per unit for 3 seats, so the line totals are 2900 and 1500 (in cents).

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:

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 '{}'

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:

`payment_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

A partially paid invoice keeps its open or due status. The 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

Cancelling an invoice

To void a finalized invoice entirely, use the cancel endpoint. Nocotax creates the matching credit note for you:

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

Learn more about credit notes →

Next steps

Record an order

Sales invoice and supplier cost for one order

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

Getting started

Billing and invoicing

Implementation guides

Overview

Prerequisites

Invoice lifecycle

Step 1: Create a draft invoice

Key parameters

Amounts

Step 2: Review the draft

Step 3: Finalize the invoice

Step 4: Mark as paid

Recording partial or detailed payments

Payment status

Handling corrections

Cancelling an invoice

Next steps

Record an order

Self-Billing Guide

Credit Notes

Tax Calculations

API Reference

​Overview

​Prerequisites

​Invoice lifecycle

​Step 1: Create a draft invoice

​Key parameters

​Amounts

​Step 2: Review the draft

​Step 3: Finalize the invoice

​Step 4: Mark as paid

​Recording partial or detailed payments

​Payment status

​Handling corrections

​Cancelling an invoice

​Next steps

Record an order

Self-Billing Guide

Credit Notes

Tax Calculations

API Reference

Overview

Prerequisites

Invoice lifecycle

Step 1: Create a draft invoice

Key parameters

Amounts

Step 2: Review the draft

Step 3: Finalize the invoice

Step 4: Mark as paid

Recording partial or detailed payments

Payment status

Handling corrections

Cancelling an invoice

Next steps