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

# Customer Invoicing

> Issue invoices to customers for goods or services sold through your platform as an undisclosed agent.

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

1. **Your organization set up** with `ownership=self`
2. **Customer organizations created** with `ownership=external` and role `BUYER`
3. **Tax registrations configured** for jurisdictions where you sell
4. **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.

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

> [!NOTE]
>
> 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:

```bash cURL theme={null}
curl https://api.nocotax.app/invoices/inv_123/finalize \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY}
```

Finalizing the invoice will:

1. Assign a sequential invoice number
2. Set the invoice date to the current date
3. Calculate `due_date` based on `payment_terms` (if provided)
4. Update the customer's accounts receivable (AR) balance
5. Lock the invoice from further modifications
6. Generate the PDF file representing the invoice

> [!WARNING]
>
> 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:

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

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

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

The `amount_remaining` field always shows how much is still owed.

## Handling corrections

To correct a finalized invoice, issue a credit note:

1. Create a credit note referencing the original invoice
2. Finalize the credit note
3. The credit note automatically reduces the `amount_remaining` on the invoice
4. If needed, issue a new corrected invoice

[Learn more about credit notes →](https://nocotax.mintlify.site/credit-notes)

## Next steps

> [card] [Self-Billing Guide](https://nocotax.mintlify.site/undisclosed-agent/self-billing)
>
> Learn how to record supplier purchases

> [card] [Credit Notes](https://nocotax.mintlify.site/credit-notes)
>
> Issue corrections and refunds

> [card] [Tax Calculations](https://nocotax.mintlify.site/tax-calculations)
>
> Understand tax calculation logic

> [card] [API Reference](https://app.nocotax.app/apidoc#tag/Invoices)
>
> View complete API documentation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.