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 \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "items": [
      {
        "description": "Monthly Subscription",
        "quantity": 1,
        "unit_extratax_amount": 9900
      }
    ]
  }'

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 \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "purchases",
    "currency": "EUR",
    "supplier_id": "org_hosting_provider",
    "items": [
      {
        "description": "Cloud Hosting - January",
        "quantity": 1,
        "unit_extratax_amount": 50000
      }
    ]
  }'

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 \
  -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 \
  -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:

description: What’s being sold
quantity: How many units
unit_extratax_amount: Price per unit excluding tax (in smallest currency unit)
extratax_amount: Total line amount excluding tax (quantity × unit_extratax_amount)
unit_tax_included_amount: Price per unit including tax
tax_included_amount: Total line amount including tax (quantity × unit_tax_included_amount)
taxes: A breakdown of taxes at the line item level.

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, PAID, PARTIALLY_PAID
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 \
  -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 in smallest currency unit

All monetary values in Nocotax are specified in the smallest currency unit:

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

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

This approach eliminates rounding errors 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 \
  -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": [
      {
        "description": "Enterprise Plan - Annual",
        "quantity": 1,
        "unit_extratax_amount": 99000,
        "product": {
          "tax_code": "D10000000" // (Digital goods, SaaS)
        }
      },
      {
        "description": "Additional Storage (100GB)",
        "quantity": 5,
        "unit_extratax_amount": 1000,
        "product": {
          "tax_code": "D10000000" // (Digital goods, SaaS)
        }
      },
      {
        "description": "Premium Support",
        "quantity": 1,
        "unit_extratax_amount": 25000,
        "product": {
          "tax_code": "S10000000" // (Services)
        }
      }
    ]
  }'

Line item attributes

Each line item includes:

description (required): Text description of the item
quantity (required): Number of units
unit_extratax_amount (optional): Price per unit excluding tax.
product.tax_code (optional): Tax category for automatic tax calculation

Calculated fields (returned in response):

extratax_amount: quantity × unit_extratax_amount
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 \
  -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": [
      {
        "description": "Consulting Services - 10 hours",
        "quantity": 10,
        "unit_extratax_amount": 15000,
        "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 \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "purchases",
    "currency": "USD",
    "supplier_id": "org_supplier_789",
    "items": [
      {
        "description": "Office Supplies",
        "quantity": 1,
        "unit_extratax_amount": 45000
      }
    ]
  }'

# 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/v1/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 in smallest currency unit

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

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 in smallest currency unit

​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 in smallest currency unit

Working with line items

Line item attributes

Tax information

Common patterns

Pattern 1: Simple sales invoice

Pattern 2: Recording a supplier invoice

Next steps