Calculate Tax, Then Create an Invoice or Bill

Public invoice and bill creation does not calculate tax. The DualEntry UI always calculates tax first, then creates the record with the tax result on each line. API clients must follow the same flow. This guide shows how to call the V2 tax calculator, map its result onto invoice line items, and create the invoice: POST /public/v2/taxes/calculate/ → map tax fields → POST /public/v2/invoices/. The same flow applies to bills using vendor_id in place of customer_id.

A shipping address on the invoice alone does not add tax. Pass the buyer address on the calculate call as transaction_buyer_address instead. The shipping_address you send on the invoice itself is for fulfillment only and has no effect on the tax calculation.

Prerequisites

V2 API (/public/v2/...)
X-API-KEY header with your organization’s API key (authenticating your requests)
The company is set up for the correct tax regime (GST, VAT, or US sales tax)
The customer (or vendor) has is_taxable set to true when tax should apply

Step 1: Resolve IDs

Look up the company, customer or vendor, and item IDs the calculate call needs:

Need	Endpoint
Company	`GET /public/v2/companies/`
Customer	`GET /public/v2/customers/`
Vendor	`GET /public/v2/vendors/`
Item	`GET /public/v2/items/`
GST rates (optional lookup)	`GET /public/v2/gst-tax-rates/`
VAT rates (optional lookup)	`GET /public/v2/vat-rates/`

Step 2: Calculate tax

Send the resolved IDs and item lines to the calculate endpoint:

curl -X POST https://api.dualentry.com/public/v2/taxes/calculate/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": 1,
    "customer_id": 2,
    "transaction_buyer_address": {
      "country": "US",
      "region": "CA",
      "postal_code": "94105",
      "city": "San Francisco",
      "line1": "123 Main St"
    },
    "transaction_date": "2026-09-16",
    "currency_code": "USD",
    "items": [
      {
        "item_id": 3,
        "quantity": "1.000000",
        "unit_price": "100.000000"
      }
    ]
  }'

Required:

company_id
customer_id (money-in, e.g. invoices) or vendor_id (money-out, e.g. bills), not both

Usually also send:

items: each with item_id, quantity, and unit_price (item_id may be null for a vendor expense line)
transaction_buyer_address: the destination address, required for US sales tax
transaction_date and currency_code: required for US sales tax
supply_date: filters VAT/GST rates by their validity window

The response type is one of:

`type`	Meaning
`SALES_TAX`	US sales tax
`VAT`	VAT regimes
`GST`	Canada, Australia, New Zealand, Singapore, India, and similar GST/GST-like regimes
`NONE`	No tax calculated. HTTP 200 with a `reason`; this is not an error.

For GST and VAT, the first calculate call often returns available_rates. Pick a rate, send it on the line as selected_gst_tax_rate_id or selected_vat_rate_id, then calculate again with that rate selected.

Step 3: Map the result onto each invoice line

Copy each field from the calculator response onto the matching field in the invoice line’s tax object:

Calculator result field	Invoice line `tax` field
`tax_code`	`code`
`tax_rate`	`rate`
`tax_amount`	`amount`
`is_taxable`	`is_taxable`
`tax_exempt_amount`	`tax_exempt_amount`
`tax_metadata`	`tax_metadata`
`selected_vat_rate_id`	`vat_rate_id`
`selected_gst_tax_rate_id`	`gst_tax_rate_id`

Also carry the line amount over: calculator unit_price → invoice line rate.

Step 4: Create the invoice

Send the mapped tax fields on each line when you create the invoice:

curl -X POST https://api.dualentry.com/public/v2/invoices/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": 1,
    "customer_id": 2,
    "date": "2026-09-16",
    "due_date": "2026-10-16",
    "currency_iso_4217_code": "USD",
    "exchange_rate": "1.0",
    "record_status": "posted",
    "shipping_address": {
      "country": "US",
      "state": "CA",
      "postal_code": "94105",
      "city": "San Francisco",
      "street": "123 Main St"
    },
    "items": [
      {
        "item_id": 3,
        "quantity": "1.000000",
        "rate": "100.000000",
        "position": 1,
        "tax": {
          "code": "SALES-TAX-US-CA",
          "rate": "0.0875",
          "amount": "8.75",
          "is_taxable": true,
          "tax_exempt_amount": "0.00",
          "tax_metadata": {}
        }
      }
    ]
  }'

Use the real values returned by your calculate call. The numbers above are examples only. You may still send shipping_address on the invoice for fulfillment; it does not replace the calculate step.

Canada GST example (two calculate calls)

GST and VAT regimes need a second calculate call once a rate is selected. Call A: list available rates Calculate without a selected rate first to see what DualEntry offers for this address:

curl -X POST https://api.dualentry.com/public/v2/taxes/calculate/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": 1,
    "customer_id": 2,
    "transaction_buyer_address": {
      "country": "CA",
      "region": "ON",
      "postal_code": "M5V 2T6",
      "city": "Toronto",
      "line1": "100 King St W"
    },
    "items": [
      {"item_id": 3, "quantity": "1.000000", "unit_price": "100.000000"}
    ]
  }'

This returns type: "GST" with data.place_of_supply ("ON") and data.available_rates listing candidate rate IDs. Pick one (for example, the Ontario HST rate) from available_rates or from GET /public/v2/gst-tax-rates/. Call B: calculate again with the selected rate Add the chosen rate ID to the line and calculate again to get the final tax amounts:

curl -X POST https://api.dualentry.com/public/v2/taxes/calculate/ \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": 1,
    "customer_id": 2,
    "transaction_buyer_address": {
      "country": "CA",
      "region": "ON",
      "postal_code": "M5V 2T6",
      "city": "Toronto",
      "line1": "100 King St W"
    },
    "items": [
      {
        "item_id": 3,
        "quantity": "1.000000",
        "unit_price": "100.000000",
        "selected_gst_tax_rate_id": 42
      }
    ]
  }'

Each returned line now has tax_code, tax_rate, tax_amount, and selected_gst_tax_rate_id set. Map those onto the invoice as in Step 3, then create the invoice using the values from call B.

US sales tax

Send transaction_buyer_address (include region and postal_code), transaction_date, and currency_code on calculate.
The response type is SALES_TAX.
Copy tax_code, tax_rate, and tax_amount onto the line’s tax object.
Create the invoice.

If the buyer address is missing, calculate returns type: "NONE" with a reason. Fix the address and calculate again before creating the invoice.

VAT

The first calculate call returns available_rates.
Send selected_vat_rate_id on the line and calculate again.
Set the invoice line’s tax.vat_rate_id from the same selected_vat_rate_id.
Create the invoice.

If calculate returns an error

The calculate endpoint returns errors for a few common mistakes:

Cause	Response
Neither `customer_id` nor `vendor_id` sent	HTTP 400, “Either customer_id or vendor_id is required”
Both `customer_id` and `vendor_id` sent	HTTP 400, “Provide customer_id or vendor_id, not both”
`company_id`, `customer_id`, or `vendor_id` doesn’t match an existing record	HTTP 404
An `item_id` doesn’t match an existing item	`type: "NONE"` with a `reason` explaining which item line failed

Fix the request and calculate again. A NONE result is not itself an error: it means DualEntry could not determine tax for this request, and the reason field says why.

Checklist before go-live

Call calculate before creating the invoice or bill
Pass the buyer/shipping address on calculate as transaction_buyer_address
For GST/VAT, select a rate from available_rates and calculate a second time
Copy every mapped tax field onto each line’s tax object
Confirm the invoice response shows items[].tax with the expected code, rate, and amount

This guide covers the calculate-then-create flow. Browse the individual V2 resources in the V2 API reference, including the calculate tax reference, GST rates, and product tax codes.

Get Started

API Keys

Working with the API

Tools & Integrations

Calculate Tax, Then Create an Invoice or Bill

Prerequisites

Step 1: Resolve IDs

Step 2: Calculate tax

Step 3: Map the result onto each invoice line

Step 4: Create the invoice

Canada GST example (two calculate calls)

US sales tax

VAT

If calculate returns an error

Checklist before go-live

​Prerequisites

​Step 1: Resolve IDs

​Step 2: Calculate tax

​Step 3: Map the result onto each invoice line

​Step 4: Create the invoice

​Canada GST example (two calculate calls)

​US sales tax

​VAT

​If calculate returns an error

​Checklist before go-live

​Related resources

Prerequisites

Step 1: Resolve IDs

Step 2: Calculate tax

Step 3: Map the result onto each invoice line

Step 4: Create the invoice

Canada GST example (two calculate calls)

US sales tax

VAT

If calculate returns an error

Checklist before go-live

Related resources