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

# Managing Taxes on Invoices

> Learn how to configure and calculate taxes on invoices, from automatic calculations to manual control.

## Overview

Nocotax provides flexible tax management for invoices, allowing you to either let the system automatically calculate taxes based on registrations and rules, or manually specify tax rates for complete control.

Proper tax configuration ensures:

* Compliance with local tax regulations
* Accurate tax collection and reporting
* Correct input tax recovery on purchases
* Simplified tax filing and reconciliation

## Tax calculation approaches

Nocotax supports two approaches to tax calculation on invoices:

### Automatic tax calculation (recommended)

The system automatically determines applicable tax rates and calculates tax amounts based on:

* Your tax registrations
* Customer/supplier tax registrations
* Transaction type (B2B vs B2C)
* Product tax codes
* Applicable tax rules

**When to use**: Most scenarios, especially for platforms selling across multiple jurisdictions.

### Manual tax calculation

You specify exact tax rates and jurisdictions for each invoice, overriding automatic calculation.

**When to use**: Special cases, legacy data migration, or when you have custom tax calculation logic.

<Note>
  By default, taxes are not calculated automatically. You must explicitly enable automatic tax calculation or provide manual tax configuration.
</Note>

## Automatic tax calculation

Enable automatic tax calculation when creating an invoice:

```bash theme={null}
curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  https://api.nocotax.app/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [
      {
        "description": "SaaS Subscription",
        "quantity": 1,
        "unit_extratax_amount": 9900,
        "product": {
          "tax_code": "D10000000"
        }
      }
    ]
  }'
```

### How automatic calculation works

When `automatic_tax_calculation.enabled: true`, Nocotax:

1. **Identifies the tax jurisdiction**: Based on supplier and customer locations
2. **Determines tax registration status**: Checks if you're registered where tax applies
3. **Applies tax rules**: Uses B2B vs B2C rules, reverse charge, exemptions, etc.
4. **Calculates rates**: Applies the correct tax rate for each line item
5. **Computes totals**: Calculates line-level and invoice-level tax amounts

### Tax codes

Tax codes categorize your products or services for tax purposes. They help Nocotax apply the correct tax treatment:

```bash theme={null}
curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  https://api.nocotax.app/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [
      {
        "description": "Software License",
        "quantity": 1,
        "unit_extratax_amount": 10000,
        "product": {
          "tax_code": "D10000000"
        }
      },
      {
        "description": "General furniture",
        "quantity": 3,
        "unit_extratax_amount": 999,
        "product": {
          "tax_code": "P10000000"
        }
      },
      {
        "description": "Consulting",
        "quantity": 1,
        "unit_extratax_amount": 50000,
        "product": {
          "tax_code": "S10000000"
        }
      }
    ]
  }'
```

**Standard tax codes**:

* `D10000000`: Digital goods and services (SaaS, software, digital content)
* `S10000000`: Services (consulting, professional services)
* `P10000000`: Physical goods (products, merchandise)

<Note>
  Tax codes are optional when automatic calculation is enabled. If omitted, Nocotax uses the default tax treatment for digital goods.
</Note>

### Tax determination factors

Automatic tax calculation considers multiple factors:

#### 1. Supplier tax registrations

Your tax registrations determine where you can charge tax:

```
You're registered for VAT in France and Germany
Sales to French customers: Charge French VAT
Sales to German customers: Charge German VAT
Sales to Spanish customers: Depends on registration and thresholds
```

See [Tax Registrations Configuration](/tax-registrations) for setup details.

#### 2. Customer tax registrations

Customer tax status affects tax treatment:

| Scenario                                  | Tax Treatment                 |
| ----------------------------------------- | ----------------------------- |
| B2C (no VAT number)                       | Charge VAT at applicable rate |
| B2B (valid VAT number, different country) | Reverse charge (0% VAT)       |
| B2B (valid VAT number, same country)      | Usually charge VAT            |
| B2B (invalid VAT number)                  | Treat as B2C, charge VAT      |

#### 3. Transaction location

Where the transaction is deemed to take place:

* **Goods**: Usually where goods are delivered
* **Services**: Depends on service type and recipient location
* **Digital services**: Customer's location

#### 4. Product type

Different products may have different tax rates:

* Standard rate (e.g., 20% in France)
* Reduced rate (e.g., 5.5% for books in France)
* Super-reduced rate (e.g., 2.1% for essentials in Spain)
* Zero rate
* Exempt

### Result of automatic calculation

After automatic calculation, the invoice contains calculated tax data:

<CodeGroup>
  ```bash Request theme={null}
  curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
    https://api.nocotax.app/invoices \
    -H "Content-Type: application/json" \
    -d '{
      "flow": "sales",
      "currency": "EUR",
      "customer_id": "org_customer_123",
      "automatic_tax_calculation": {
        "enabled": true
      },
      "items": [
        {
          "description": "SaaS Subscription",
          "quantity": 1,
          "unit_extratax_amount": 9900,
          "product": {
            "tax_code": "D10000000"
          }
        }
      ]
    }'
  ```

  ```json Response theme={null}
  {
    "id": "inv_123",
    "flow": "sales",
    "currency": "EUR",
    "total_extratax_amount": 9900,
    "total_tax_amount": 1980,
    "total_tax_included_amount": 11880,
    "taxes": [
      {
        "tax_id": "eu-vat",
        "jurisdiction": "FR",
        "percentage": 20.0,
        "taxable_amount": 9900,
        "tax_amount": 1980
      }
    ]
  }
  ```
</CodeGroup>

## Manual tax calculation

For complete control over tax rates, disable automatic calculation and specify tax manually at the invoice level:

```bash theme={null}
curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  https://api.nocotax.app/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "automatic_tax_calculation": {
      "enabled": false
    },
    "items": [
      {
        "description": "Product",
        "quantity": 1,
        "unit_extratax_amount": 10000,
        "taxes": [
          {
            "jurisdiction": "FR",
            "percentage": 20,
            "tax_id": "eu-vat"
          }
        ],
      },
      {
        "description": "Service",
        "quantity": 2,
        "unit_extratax_amount": 5000,
        "taxes": [
          {
            "jurisdiction": "FR",
            "percentage": 20,
            "tax_id": "eu-vat"
          }
        ],
      }
    ]
  }'
```

The tax configuration applies to all line items on the invoice. Nocotax calculates the tax amounts based on the rates you provide.

### Explicit tax registration IDs

When using manual tax calculation, you can specify which tax registration numbers to use:

```bash theme={null}
curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  https://api.nocotax.app/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "supplier_tax_registration_id": "taxreg_your_de_vat",
    "customer_tax_registration_id": "taxreg_customer_de",
    "automatic_tax_calculation": {
      "enabled": false
    },
    "items": [...]
  }'
```

<Warning>
  Explicit tax registration IDs only work with manual tax calculation. You cannot specify registration IDs when automatic calculation is enabled.
</Warning>

### When to use manual tax

**Valid use cases**:

* Importing historical invoices with known tax rates
* Handling unusual tax situations not covered by rules
* Applying custom tax calculations from external systems
* Zero-rating or exempting specific transactions manually

**Risks and considerations**:

* You're responsible for tax accuracy
* No automatic compliance with tax rules
* Requires careful manual review
* May complicate tax reporting

<Warning>
  Manual tax calculation bypasses Nocotax's compliance features. Use automatic calculation whenever possible to ensure accuracy and compliance.
</Warning>

### Example: Zero-rated transaction

```bash theme={null}
curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  https://api.nocotax.app/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "automatic_tax_calculation": {
      "enabled": false
    },
    "items": [
      {
        "description": "Export goods",
        "quantity": 1,
        "unit_extratax_amount": 50000,
        "taxes": [
          {
            "jurisdiction": "FR",
            "percentage": 0,
            "tax_id": "eu-vat",
            "tax_exemption": {
              "type": "EXPORT"
            }
          }
        ],
      }
    ]
  }'
```

## Tax on different invoice flows

Tax treatment varies by invoice flow:

### Sales invoices (output tax)

Tax you charge to customers on sales:

```bash theme={null}
curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  https://api.nocotax.app/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [...]
  }'
```

* You collect tax from customers
* Tax increases the invoice total
* You must remit collected tax to authorities
* Reported on your VAT return as "output tax" or "sales tax"

### Purchase invoices (input tax)

Tax charged to you on purchases:

```bash theme={null}
curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  https://api.nocotax.app/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "purchases",
    "currency": "EUR",
    "supplier_id": "org_supplier_456",
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [...]
  }'
```

* Supplier charges you tax
* Tax increases what you pay
* You may be able to reclaim this tax (input tax deduction)
* Reported on your VAT return as "input tax"

## Common scenarios

### Scenario 1: EU B2B sale with reverse charge

<CodeGroup>
  ```bash Request theme={null}
  curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
    https://api.nocotax.app/invoices \
    -H "Content-Type: application/json" \
    -d '{
      "flow": "sales",
      "currency": "EUR",
      "customer_id": "org_german_business",
      "automatic_tax_calculation": {
        "enabled": true
      },
      "items": [
        {
          "description": "Software License",
          "quantity": 1,
          "unit_extratax_amount": 10000,
          "product": {
            "tax_code": "D10000000"
          }
        }
      ]
    }'
  ```

  ```json Response theme={null}
  {
    "id": "inv_123",
    "total_extratax_amount": 10000,
    "total_tax_amount": 0,
    "total_tax_included_amount": 10000,
    "taxes": [
      {
        "tax_id": "eu-vat",
        "jurisdiction": "FR",
        "percentage": 0,
        "tax_exemption": {
          "type": "REVERSE_CHARGE"
        },
        "taxable_amount": 10000,
        "tax_amount": 0
      }
    ]
  }
  ```
</CodeGroup>

### Scenario 2: EU B2C sale via OSS

<CodeGroup>
  ```bash Request theme={null}
  curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
    https://api.nocotax.app/invoices \
    -H "Content-Type: application/json" \
    -d '{
      "flow": "sales",
      "currency": "EUR",
      "customer_id": "org_spanish_consumer",
      "automatic_tax_calculation": {
        "enabled": true
      },
      "items": [
        {
          "description": "E-book",
          "quantity": 1,
          "unit_extratax_amount": 999,
          "product": {
            "tax_code": "D10000000"
          }
        }
      ]
    }'
  ```

  ```json Response theme={null}
  {
    "id": "inv_456",
    "total_extratax_amount": 999,
    "total_tax_amount": 40,
    "total_tax_included_amount": 1039,
    "taxes": [
      {
        "tax_id": "eu-vat",
        "jurisdiction": "ES",
        "percentage": 4.0,
        "taxable_amount": 999,
        "tax_amount": 40
      }
    ]
  }
  ```
</CodeGroup>

### Scenario 3: Manual tax for specific rate

<CodeGroup>
  ```bash Request theme={null}
  curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
    https://api.nocotax.app/invoices \
    -H "Content-Type: application/json" \
    -d '{
      "flow": "sales",
      "currency": "EUR",
      "customer_id": "org_customer_123",
      "automatic_tax_calculation": {
        "enabled": false
      },
      "items": [
        {
          "description": "Books",
          "quantity": 3,
          "unit_extratax_amount": 1500,
          "taxes": [
            {
              "jurisdiction": "FR",
              "percentage": 5.5,
              "tax_id": "eu-vat"
            }
          ]
        }
      ]
    }'
  ```

  ```json Response theme={null}
  {
    "id": "inv_789",
    "total_extratax_amount": 4500,
    "total_tax_amount": 248,
    "total_tax_included_amount": 4748,
    "taxes": [
      {
        "tax_id": "eu-vat",
        "jurisdiction": "FR",
        "percentage": 5.5,
        "taxable_amount": 4500,
        "tax_amount": 248
      }
    ]
  }
  ```
</CodeGroup>

## Best practices

<AccordionGroup>
  <Accordion title="Always use automatic calculation for compliance">
    Unless you have a specific reason to manually control tax, enable automatic calculation. It ensures:

    * Accurate rates based on current tax rules
    * Proper B2B vs B2C treatment
    * Correct reverse charge application
    * Up-to-date compliance
  </Accordion>

  <Accordion title="Specify tax codes for accuracy">
    While optional, providing tax codes improves calculation accuracy, especially for products with reduced rates or special treatment:

    * `tax_code: 'ebooks'` may apply reduced rates
    * `tax_code: 'medical'` may apply exemptions
    * `tax_code: 'export'` may apply zero rates
  </Accordion>

  <Accordion title="Keep tax registrations current">
    Ensure your tax registrations in Nocotax match your actual registrations with tax authorities. Update them immediately when:

    * You register in a new jurisdiction
    * Registration numbers change
    * Registration types change (e.g., standard to OSS)
  </Accordion>

  <Accordion title="Validate customer tax numbers">
    For B2B sales, ensure customers provide valid tax registration numbers. Invalid numbers can result in:

    * Incorrect reverse charge application
    * Charging VAT when not required
    * Compliance issues during audits
  </Accordion>

  <Accordion title="Use default tax registration selection">
    Let Nocotax automatically select the appropriate tax registration numbers unless you have a specific reason to override. The default behavior is designed to ensure compliance.
  </Accordion>
</AccordionGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I change from automatic to manual tax after creating an invoice?">
    No, the tax calculation method is locked. You would need to create a new invoice with the desired method if you need to change this behaviour.
  </Accordion>

  <Accordion title="What happens if I don't specify any tax information?">
    If you enable automatic calculation but don't specify tax codes, Nocotax uses default tax treatment based on your business type and applicable rules. For manual calculation, omitting tax amounts means zero tax.
  </Accordion>

  <Accordion title="How do I handle tax-exempt customers?">
    Tax-exempt status is typically handled automatically when the customer has an appropriate tax registration number (e.g., charity VAT number). For special cases, you can use manual tax calculation with zero tax amounts.
  </Accordion>

  <Accordion title="Can I see how tax was calculated?">
    Yes. Invoices with automatic calculation include a `taxes` field showing jurisdictions, rates, taxable amounts, and tax amounts. This provides transparency into the calculation.
  </Accordion>

  <Accordion title="What if I disagree with the automatic calculation?">
    First, verify your tax registrations, customer information, and tax codes are correct. If the calculation still seems wrong, contact support with details. You can temporarily use manual calculation as a workaround.
  </Accordion>

  <Accordion title="Do I need to specify tax registration IDs for every invoice?">
    No. Default behavior is recommended—Nocotax automatically selects the appropriate tax registrations. Only specify explicitly when you have multiple registrations and need precise control.
  </Accordion>
</AccordionGroup>