Record an order

This recipe records one order in Nocotax:

A sales invoice for the customer.
One or more lines on a purchase invoice for the supplier’s share (self-billing).

Principles

One order, one sales invoice. Put the order identifier of your system in order_reference.
Purchases are usually aggregated. A supplier invoice typically covers several orders over a period. Each line keeps the order_reference of its own order, so the link between sale and cost is never lost.
Always set period on lines: it is the service date, independent of when you invoice or pay. See Accounting periods.
Store the returned id (inv_...) next to your order. Lists can only be filtered by flow, customer_id and supplier_id, and creating the same document twice creates two documents.

1. Create the sales 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",
    "order_reference": "ORD-12345",
    "period": {
      "start": "2025-12-15T00:00:00Z",
      "end": "2025-12-15T00:00:00Z"
    },
    "automatic_tax_calculation": { "enabled": true },
    "items": [
      {
        "title": "Consulting session - 15 Dec 2025",
        "quantity": 1,
        "extratax_amount": 10000,
        "product": { "tax_code": "S10000000" }
      }
    ]
  }'

The line inherits order_reference and period from the document because it does not set its own. extratax_amount is an integer in the smallest currency unit (10000 = 100.00 EUR). Then finalize it:

curl https://api.nocotax.app/invoices/inv_123/finalize \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY}

2. Add the supplier cost to a purchase invoice

Create a purchase invoice for the supplier and period you settle together. Each order is a line with its own references:

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",
    "currency": "EUR",
    "issuer": { "type": "CUSTOMER" },
    "automatic_tax_calculation": { "enabled": true },
    "items": [
      {
        "title": "Payout - order ORD-12345",
        "order_reference": "ORD-12345",
        "period": { "start": "2025-12-15T00:00:00Z", "end": "2025-12-15T00:00:00Z" },
        "extratax_amount": 7000,
        "product": { "tax_code": "S10000000" }
      },
      {
        "title": "Payout - order ORD-12399",
        "order_reference": "ORD-12399",
        "period": { "start": "2025-12-20T00:00:00Z", "end": "2025-12-20T00:00:00Z" },
        "extratax_amount": 4200,
        "product": { "tax_code": "S10000000" }
      }
    ]
  }'

issuer.type = CUSTOMER marks the invoice as self-billed. See Self-billing for the legal framework and the full lifecycle.

More than 10 items

Creation accepts up to 10 items. While the invoice is a draft, add the others with add_items, then finalize.

curl https://api.nocotax.app/invoices/inv_456/add_items \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{ "items": [ { "title": "Payout - order ORD-12400", "order_reference": "ORD-12400", "extratax_amount": 3000 } ] }'

Choosing what a purchase invoice covers

Nocotax does not impose a granularity. What matters for reconciliation is that every cost line carries its order_reference and period. Common choices are one invoice per supplier and payout run, or one per supplier and month.

3. Check what you recorded

The response contains the totals (total_extratax_amount, total_tax_amount, total_tax_included_amount), in the smallest currency unit.
Compare the sum of your sales lines and cost lines per order_reference with your own data before going live.

Common mistakes

Mistake	Effect
Omitting `order_reference` on purchase lines	Cost cannot be matched to its sale.
Putting several orders under a single document-level `order_reference`	All lines inherit the same reference.
Omitting `period`	Reports use the invoice date, which is the day of finalization.
Mixing units: `unit_extratax_amount` is a decimal in the main unit, `extratax_amount` an integer in the smallest unit	Amounts off by 100. See amounts.
Retrying a creation call without checking your stored `id`	Duplicate documents.

Payments and payouts

Record customer payments and supplier payouts

Accounting periods

Understand which date drives which report

Getting started

Billing and invoicing

Implementation guides

Principles

1. Create the sales invoice

2. Add the supplier cost to a purchase invoice

More than 10 items

Choosing what a purchase invoice covers

3. Check what you recorded

Common mistakes

Next

Payments and payouts

Accounting periods

​Principles

​1. Create the sales invoice

​2. Add the supplier cost to a purchase invoice

​More than 10 items

​Choosing what a purchase invoice covers

​3. Check what you recorded

​Common mistakes

​Next

Payments and payouts

Accounting periods

Principles

1. Create the sales invoice

2. Add the supplier cost to a purchase invoice

More than 10 items

Choosing what a purchase invoice covers

3. Check what you recorded

Common mistakes

Next