> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nocotax.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices Overview

> Understand how invoices work in Nocotax and how to use them for your platform's business transactions.

## 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.

```bash theme={null}
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.

```bash theme={null}
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) |

```bash theme={null}
# 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](/billing-invoicing/invoices/payments) for detailed payment management.

## Multi-currency support

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

```bash theme={null}
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
```

<Note>
  Draft invoices don't have document numbers. Numbers are assigned only when you finalize the invoice via the `document_number` field.
</Note>

## 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 |

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/billing-invoicing/invoices/taxes) for detailed tax configuration.

## Common patterns

### Pattern 1: Simple sales invoice

```bash theme={null}
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

```bash theme={null}
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} \
```

<Tip>
  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.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Invoice Lifecycle" icon="arrow-progress" href="/billing-invoicing/invoices/lifecycle">
    Learn about invoice statuses and state transitions
  </Card>

  <Card title="Managing Taxes" icon="calculator" href="/billing-invoicing/invoices/taxes">
    Configure tax calculations on invoices
  </Card>

  <Card title="Payments" icon="credit-card" href="/billing-invoicing/invoices/payments">
    Track and reconcile invoice payments
  </Card>

  <Card title="API Reference" icon="code" href="https://app.nocotax.app/apidoc#tag/Invoices">
    Explore the complete invoices API
  </Card>
</CardGroup>