Invoices Overview

What is an invoice?

An invoice is a commercial document issued by a seller to a buyer that records a transaction between two parties. In Nocotax, invoices are the primary way to document:

Sales to customers (revenue)
Purchases from suppliers (costs)
Commission arrangements between platforms and merchants

Every invoice in Nocotax represents a transaction between two organizations: a supplier (the party providing goods or services) and a customer (the party receiving them).

Invoice flows

Nocotax supports three invoice flows that determine the direction and purpose of the invoice:

Sales flow

The sales flow (flow=sales) represents invoices your platform issues to customers for goods or services you’ve sold. This is your outbound invoicing.

Your Platform (supplier) → Invoice → Customer

Common use cases:

SaaS subscription invoices
E-commerce order invoices
Service booking confirmations
Product sales

Key characteristics:

Increases your accounts receivable (AR)
Represents revenue for your business
You are the supplier, customer is the buyer
You charge tax (if applicable)

Example: Your platform sells a monthly subscription for €99 to a customer.

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"
      }
    ]
  }'

Purchases flow

The purchases flow (flow=purchases) represents invoices for goods or services you’ve purchased from suppliers. This is your inbound invoicing.

Supplier → Invoice → Your Platform (customer)

Common use cases:

Recording supplier invoices
Self-billing for marketplace payouts
Documenting costs and expenses
Tracking amounts owed to suppliers

Key characteristics:

Increases your accounts payable (AP)
Represents costs for your business
Supplier is the issuer, you are the customer
You may be able to claim input tax

Example: You receive an invoice from a hosting provider for €500.

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "purchases",
    "currency": "EUR",
    "supplier_id": "org_hosting_provider",
    "items": [
      {
        "title": "Cloud Hosting - January",
        "quantity": 1,
        "unit_extratax_amount": "500.00"
      }
    ]
  }'

Default vs explicit organization IDs

When creating invoices, you can choose to specify organization IDs explicitly or let Nocotax use default values based on your account configuration.

Default IDs (recommended)

If you omit supplier_id or customer_id, Nocotax will use default values based on the flow:

Flow	Default supplier_id	Default customer_id
`sales`	Your organization (self)	Must be specified
`purchases`	Must be specified	Your organization (self)

# Sales invoice - supplier_id defaults to your organization
curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "items": [...]
  }'

# Purchase invoice - customer_id defaults to your organization
curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -d '{
    "flow": "purchases",
    "currency": "EUR",
    "supplier_id": "org_supplier_456",
    "items": [...]
  }'

Invoice structure

Every invoice contains the following key components:

Header information

Basic invoice details:

Flow: Direction of the invoice (sales/purchases)
Supplier: Organization providing goods/services
Customer: Organization receiving goods/services
document_number: Sequential invoice number (assigned when finalized)
document_date: Invoice issue date (set when finalized)
Currency: Three-letter ISO currency code

Line items

Individual products or services on the invoice:

title: What’s being sold. Appears on the document
quantity: How many units (decimal, defaults to 1)
unit_extratax_amount: Price per unit excluding tax, as a decimal string in the currency’s main unit (e.g. "99.2842")
extratax_amount: Total line amount excluding tax, as an integer in the currency’s smallest unit (quantity × unit_extratax_amount, rounded)
unit_tax_included_amount: Price per unit including tax, as a decimal string in the currency’s main unit
tax_included_amount: Total line amount including tax, as an integer in the currency’s smallest unit
taxes: A breakdown of taxes at the line item level.

See Amounts: totals vs unit prices for the two conventions.

Tax breakdown

Detailed tax information per line and invoice:

tax_id: Tax identifier
percentage: Tax rate applied
jurisdiction: Where the tax applies
exemption: Exemption reason if applicable

Totals

Calculated amounts:

total_extratax_amount: Sum of all line items before tax
total_tax_amount: Total tax across all line items
total_tax_included_amount: Final amount including tax

Payment information

payment_terms: Payment terms configuration (type and days)
due_date: When payment is expected
payment_status: open, due or paid (a partially paid invoice stays open or due; check amount_remaining)
amount_due: How much is still unpaid
amount_overpaid: If a payment is recorded, the amount that exceeds the amount_remaining at the time it is recorded
amount_paid: How much is recorded as paid
amount_remaining: How much is still unpaid

See Invoice Payments for detailed payment management.

Multi-currency support

Nocotax supports invoices in multiple currencies. Each invoice must specify its currency:

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -d '{
    "flow": "sales",
    "currency": "USD",
    "customer_id": "org_customer_123",
    "items": [...]
  }'

Important considerations:

Currency is required when creating an invoice
All amounts on an invoice must be in the same currency
Currency cannot be changed after invoice creation

Invoice numbering

Invoice numbers are assigned automatically when you finalize an invoice. Nocotax ensures:

Sequential numbering: Each invoice gets the next available number
Unique numbers: No duplicates within your account
Per-flow numbering: Sales and purchases can have separate sequences
Format customization: Configure your numbering format in settings

Example sequence:

INV-2025-001
INV-2025-002
INV-2025-003

Draft invoices don’t have document numbers. Numbers are assigned only when you finalize the invoice via the document_number field.

Amounts: totals vs unit prices

Nocotax uses two different conventions. Mixing them up is the most common integration mistake, so read this section carefully.

Kind of amount	Fields	Format	Example (USD)
Accounting amounts (totals)	`extratax_amount`, `tax_included_amount`, `total_*`, `amount_due`, `amount_paid`, `amount_remaining`, `transaction_data.amount`	Integer in the currency’s smallest unit	`9900` = 99.00 USD
Unit prices	`unit_extratax_amount`, `unit_tax_included_amount`	Decimal string in the currency’s main unit, up to 12 decimal places	`"99.2842"` = 99.2842 USD

Smallest units by currency:

Currency	Smallest Unit	Example
EUR, USD	Cents	€10.50 = 1050
GBP	Pence	£25.99 = 2599
JPY	Yen (no subunit)	¥1,000 = 1000

"unit_extratax_amount": "9900" is 9,900.00 in the invoice currency, not 99.00. If you have an amount in cents, either send it as extratax_amount: 9900 or divide it by 100 for unit_extratax_amount: "99.00".

Unit prices keep their full precision because they are multiplied by quantity; the resulting line total is then rounded to the smallest currency unit.

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "items": [
      {
        "title": "Product",
        "quantity": 2,
        "unit_extratax_amount": "29.50"
      }
    ]
  }'
# item extratax_amount and total_extratax_amount: 5900 (€59.00)

Keeping accounting amounts as integers eliminates rounding errors in totals and ensures precise calculations.

Working with line items

Invoices support up to 10 line items per invoice at creation:

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",
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [
      {
        "title": "Enterprise Plan - Annual",
        "quantity": 1,
        "unit_extratax_amount": "990.00",
        "product": {
          "tax_code": "D10000000" // (Digital goods, SaaS)
        }
      },
      {
        "title": "Additional Storage (100GB)",
        "quantity": 5,
        "unit_extratax_amount": "10.00",
        "product": {
          "tax_code": "D10000000" // (Digital goods, SaaS)
        }
      },
      {
        "title": "Premium Support",
        "quantity": 1,
        "unit_extratax_amount": "250.00",
        "product": {
          "tax_code": "S10000000" // (Services)
        }
      }
    ]
  }'

Line item attributes

Each line item includes:

title (required): Text description of the item, displayed on the document
quantity (optional): Number of units, defaults to 1
product.tax_code (optional): Tax category for automatic tax calculation
One amount (at least one is required; unit_extratax_amount and unit_tax_included_amount cannot be combined, nor extratax_amount and tax_included_amount):
- unit_extratax_amount: unit price excluding tax, decimal string in the main unit ("99.2842")
- unit_tax_included_amount: unit price including tax, decimal string in the main unit
- extratax_amount: line total excluding tax, integer in the smallest unit (9900)
- tax_included_amount: line total including tax, integer in the smallest unit
order_reference, period, taxes (optional): see the API reference

Calculated fields (returned in response, whichever amount you sent):

extratax_amount: quantity × unit_extratax_amount, rounded to the smallest unit
unit_tax_included_amount: Unit price including tax
tax_included_amount: Total line amount including tax

Tax information

When automatic tax calculation is enabled, invoices include detailed tax breakdown:

{
  "total_extratax_amount": 10000,
  "total_tax_amount": 2000,
  "total_tax_included_amount": 12000,
  "taxes": [
    {
      "tax_id": "eu-vat",
      "percentage": 20.0,
      "jurisdiction": "FR",
      "taxable_amount": 10000,
      "tax_amount": 2000
    }
  ]
}

For cross-border transactions with exemptions:

{
  "taxes": [
    {
      "tax_id": "eu-vat",
      "percentage": 0.0,
      "jurisdiction": "ES",
      {
        "type": "REVERSE_CHARGE",
        "legal_notice": "Reverse Charge - Article 196 of Council Directive 2006/112/EC"
      },
      "taxable_amount": 10000,
      "tax_amount": 0
    }
  ]
}

See Managing Taxes for detailed tax configuration.

Common patterns

Pattern 1: Simple sales 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",
    "payment_terms": {
      "type": "NET",
      "days": 30
    },
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [
      {
        "title": "Consulting Services - 10 hours",
        "quantity": 10,
        "unit_extratax_amount": "150.00",
        "product": {
          "tax_code": "S10000000"
        }
      }
    ]
  }'

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

Pattern 2: Recording a supplier invoice

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "purchases",
    "currency": "USD",
    "supplier_id": "org_supplier_789",
    "items": [
      {
        "title": "Office Supplies",
        "quantity": 1,
        "unit_extratax_amount": "450.00"
      }
    ]
  }'

# Finalize and mark as paid
curl https://api.nocotax.app/invoices/inv_456/finalize \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY}

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

You can use negative amounts in line items to represent deductions, credits, or refunds. If you need to manage documents for cancellations, refunds or chargebacks, use credit notes instead.

Next steps

Invoice Lifecycle

Learn about invoice statuses and state transitions

Managing Taxes

Configure tax calculations on invoices

Payments

Track and reconcile invoice payments

API Reference

Explore the complete invoices API

Getting started

Billing and invoicing

Implementation guides

What is an invoice?

Invoice flows

Sales flow

Purchases flow

Default vs explicit organization IDs

Default IDs (recommended)

Invoice structure

Header information

Line items

Tax breakdown

Totals

Payment information

Multi-currency support

Invoice numbering

Amounts: totals vs unit prices

Working with line items

Line item attributes

Tax information

Common patterns

Pattern 1: Simple sales invoice

Pattern 2: Recording a supplier invoice

Next steps

Invoice Lifecycle

Managing Taxes

Payments

API Reference

​What is an invoice?

​Invoice flows

​Sales flow

​Purchases flow

​Default vs explicit organization IDs

​Default IDs (recommended)

​Invoice structure

​Header information

​Line items

​Tax breakdown

​Totals

​Payment information

​Multi-currency support

​Invoice numbering

​Amounts: totals vs unit prices

​Working with line items

​Line item attributes

​Tax information

​Common patterns

​Pattern 1: Simple sales invoice

​Pattern 2: Recording a supplier invoice

​Next steps

Invoice Lifecycle

Managing Taxes

Payments

API Reference

What is an invoice?

Invoice flows

Sales flow

Purchases flow

Default vs explicit organization IDs

Default IDs (recommended)

Invoice structure

Header information

Line items

Tax breakdown

Totals

Payment information

Multi-currency support

Invoice numbering

Amounts: totals vs unit prices

Working with line items

Line item attributes

Tax information

Common patterns

Pattern 1: Simple sales invoice

Pattern 2: Recording a supplier invoice

Next steps