Managing Taxes on Invoices

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

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 amounts for each line item, overriding automatic calculation. When to use: Special cases, legacy data migration, or when you have custom tax calculation logic.

Automatic tax calculation

Enable automatic tax calculation when creating an invoice:

curl https://api.nocotax.app/invoices \
  -X POST \
  -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": [
      {
        "title": "SaaS Subscription",
        "quantity": 1,
        "unit_extratax_amount": "99.00",
        "product": {
          "tax_code": "D10000000"
        }
      }
    ]
  }'

How automatic calculation works

When automatic_tax_calculation.enabled: true, Nocotax:

Identifies the tax jurisdiction: Based on supplier and customer locations
Determines tax registration status: Checks if you’re registered where tax applies
Applies tax rules: Uses B2B vs B2C rules, reverse charge, exemptions, etc.
Calculates rates: Applies the correct tax rate for each line item
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:

"items": [
  {
    "title": "Software License",
    "quantity": 1,
    "unit_extratax_amount": "100.00",
    "product": {
      "tax_code": "D10000000"
    }
  },
  {
    "title": "General furniture",
    "quantity": 3,
    "unit_extratax_amount": "9.99",
    "product": {
      "tax_code": "P10000000"
    }
  },
  {
    "title": "Consulting",
    "quantity": 1,
    "unit_extratax_amount": "500.00",
    "product": {
      "tax_code": "S10000000"
    }
  }
]

Prefix	Class
`D`	Digital goods
`P`	Physical goods
`S`	Services
`L`	Localizable services

Tax codes are optional when automatic calculation is enabled. If omitted, Nocotax uses the default tax treatment for your business type (digital goods)

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

{
  "total_extratax_amount": 9900,
  "total_tax_amount": 1980,
  "total_tax_included_amount": 11880,
  "taxes": [
    {
      "tax_id": "eu-vat",
      "jurisdiction": "FR",
      "percentage": "20.0"
    }
  ]
}

In this example, the invoice is for €99.00 excluding tax: the 20% VAT is €19.80 and the total is €118.80. All totals are integers in the smallest currency unit.

Default vs explicit tax registration numbers

When creating invoices, you can control which tax registration numbers appear on the invoice.

Default behavior

By default, Nocotax automatically selects the appropriate tax registration number for each organization based on the transaction:

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

How default selection works: For the supplier (seller):

Nocotax uses the tax registration relevant to the transaction jurisdiction
If you have multiple registrations (e.g., standard + OSS), the most appropriate one is selected
Example: Selling to a German customer, your German VAT number or EU OSS number is used

For the customer (buyer):

If the customer has a tax registration in the transaction jurisdiction, it’s included
For B2B transactions, the customer’s VAT number is validated and included
For B2C transactions, no customer tax number is required

Explicit tax registration numbers

You can override the default behavior and explicitly specify which tax registration numbers to use:

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "customer_id": "org_customer_123",
    "supplier_tax_registration_ids": ["taxreg_your_de_vat"],
    "customer_tax_registration_ids": ["taxreg_customer_de"],
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [...]
  }'

When to use explicit IDs:

You have multiple registrations and need to specify which one to use
Testing specific tax scenarios
Ensuring a particular registration appears on the invoice
Handling edge cases with complex tax setups

Explicitly setting incorrect tax registration IDs can result in wrong tax calculations. Use the default behavior unless you have a specific reason to override.

Example: Multiple registrations

If your platform has both a standard and an OSS registration in the EU: Default: Nocotax picks the best registration (German standard VAT or EU OSS):

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "customer_id": "org_german_customer",
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [...]
  }'

Explicit: force the use of the OSS registration:

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "customer_id": "org_german_customer",
    "supplier_tax_registration_ids": ["taxreg_your_oss_eu"],
    "automatic_tax_calculation": {
      "enabled": true
    },
    "items": [...]
  }'

Manual tax calculation

For complete control over tax amounts, disable automatic calculation and specify tax manually:

curl https://api.nocotax.app/invoices \
  -X POST \
  -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": false
    },
    "items": [
      {
        "title": "Product",
        "quantity": 1,
        "unit_extratax_amount": "100.00",
        "taxes": [{ "tax_id": "eu-vat", "percentage": "20" }]
      },
      {
        "title": "Service",
        "quantity": 2,
        "unit_extratax_amount": "50.00"
      }
    ]
  }'

The first item carries 20% VAT (€20.00) and the second has no taxes, so no tax applies on that line. The invoice totals are total_extratax_amount: 20000 (€200.00), total_tax_amount: 2000 (€20.00) and total_tax_included_amount: 22000 (€220.00), as integers in the smallest currency unit.

When to use manual tax

Valid use cases:

Importing historical invoices with known tax amounts
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

Manual tax calculation bypasses Nocotax’s compliance features. Use automatic calculation whenever possible to ensure accuracy and compliance.

Mixed manual and automatic

You cannot mix manual and automatic calculation within a single invoice. Each invoice must use one approach consistently:

# ❌ Not allowed: manual `taxes` on an item while automatic calculation is enabled
curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "automatic_tax_calculation": { "enabled": true },
    "items": [
      { "title": "Item 1", "quantity": 1, "unit_extratax_amount": "100.00" },
      {
        "title": "Item 2",
        "quantity": 1,
        "unit_extratax_amount": "50.00",
        "taxes": [{ "tax_id": "eu-vat", "percentage": "10" }]
      }
    ]
  }'

# ✓ Correct: all items carry their own taxes, automatic calculation disabled
curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "automatic_tax_calculation": { "enabled": false },
    "items": [
      {
        "title": "Item 1",
        "quantity": 1,
        "unit_extratax_amount": "100.00",
        "taxes": [{ "tax_id": "eu-vat", "percentage": "20" }]
      },
      {
        "title": "Item 2",
        "quantity": 1,
        "unit_extratax_amount": "50.00",
        "taxes": [{ "tax_id": "eu-vat", "percentage": "10" }]
      }
    ]
  }'

Tax on different invoice flows

Tax treatment varies by invoice flow:

Sales invoices (output tax)

Tax you charge to customers on sales:

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

The supplier is your own organization by default: you charge the tax.

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:

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

The customer is your own organization by default: you are charged the tax.

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”

Registration warnings

If you’re selling without proper registrations:

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "customer_id": "org_german_customer",
    "automatic_tax_calculation": { "enabled": true },
    "items": [...]
  }'

If you are not registered for tax in Germany, Nocotax may:

Show a warning about the missing registration
Apply your home country rate (if under thresholds)
Suggest registering for tax in Germany

Best practices

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

Specify tax codes for accuracy

While optional, providing a tax code improves calculation accuracy. A tax code is a class letter followed by 8 digits: D (digital goods), P (physical goods), S (services) or L (localizable services). The default codes are D10000000, S10000000, P10000000 and L10000000. A more specific code falls back to the default of its class when no dedicated rate exists.

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)

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

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.

Frequently Asked Questions

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.

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.

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.

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.

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.

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.

Getting started

Billing and invoicing

Implementation guides

Overview

Tax calculation approaches

Automatic tax calculation

Manual tax calculation

Automatic tax calculation

How automatic calculation works

Tax codes

Tax determination factors

1. Supplier tax registrations

2. Customer tax registrations

3. Transaction location

4. Product type

Result of automatic calculation

Default vs explicit tax registration numbers

Default behavior

Explicit tax registration numbers

Example: Multiple registrations

Manual tax calculation

When to use manual tax

Mixed manual and automatic

Tax on different invoice flows

Sales invoices (output tax)

Purchase invoices (input tax)

Registration warnings

Best practices

Frequently Asked Questions

​Overview

​Tax calculation approaches

​Automatic tax calculation

​Manual tax calculation

​Automatic tax calculation

​How automatic calculation works

​Tax codes

​Tax determination factors

​1. Supplier tax registrations

​2. Customer tax registrations

​3. Transaction location

​4. Product type

​Result of automatic calculation

​Default vs explicit tax registration numbers

​Default behavior

​Explicit tax registration numbers

​Example: Multiple registrations

​Manual tax calculation

​When to use manual tax

​Mixed manual and automatic

​Tax on different invoice flows

​Sales invoices (output tax)

​Purchase invoices (input tax)

​Registration warnings

​Best practices

​Frequently Asked Questions

Overview

Tax calculation approaches

Automatic tax calculation

Manual tax calculation

Automatic tax calculation

How automatic calculation works

Tax codes

Tax determination factors

1. Supplier tax registrations

2. Customer tax registrations

3. Transaction location

4. Product type

Result of automatic calculation

Default vs explicit tax registration numbers

Default behavior

Explicit tax registration numbers

Example: Multiple registrations

Manual tax calculation

When to use manual tax

Mixed manual and automatic

Tax on different invoice flows

Sales invoices (output tax)

Purchase invoices (input tax)

Registration warnings

Best practices

Frequently Asked Questions