Tax

Calculate tax

Computes tax for inline line items against your legal entity’s configured tax engine and stores the result, returning an id (with an expiry) you pass when issuing a receipt to pin these exact line items and amounts. Each call creates a new calculation; send an Idempotency-Key header to make a retry return the original calculation instead of a new one. Provide a buyer address (and optional tax ids for reverse-charge / exemption) and per-line canonical tax codes; an omitted code defaults to general business SaaS.

POST

tax

calculations

Calculate tax

curl --request POST \
  --url https://api.alguna.io/tax/calculations \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "USD",
  "customer": {
    "address": {
      "country": "USA",
      "city": "San Francisco",
      "line1": "123 Main St",
      "line2": "Suite 100",
      "postal_code": "94105",
      "state": "CA"
    },
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "buyer@example.com",
    "reference": "<string>",
    "tax_ids": [
      {
        "type": "eu_vat",
        "value": "DE123456789"
      }
    ]
  },
  "line_items": [
    {
      "amount": "100.00",
      "quantity": "1",
      "billing_period_end": "2026-02-01T00:00:00Z",
      "billing_period_start": "2026-01-01T00:00:00Z",
      "description": "Pro plan",
      "reference": "line_1",
      "tax_code": "txcd_business_saas"
    }
  ],
  "legal_entity_id": "<string>",
  "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
  "tax_behavior": "exclusive"
}
'

import requests

url = "https://api.alguna.io/tax/calculations"

payload = {
    "currency": "USD",
    "customer": {
        "address": {
            "country": "USA",
            "city": "San Francisco",
            "line1": "123 Main St",
            "line2": "Suite 100",
            "postal_code": "94105",
            "state": "CA"
        },
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "buyer@example.com",
        "reference": "<string>",
        "tax_ids": [
            {
                "type": "eu_vat",
                "value": "DE123456789"
            }
        ]
    },
    "line_items": [
        {
            "amount": "100.00",
            "quantity": "1",
            "billing_period_end": "2026-02-01T00:00:00Z",
            "billing_period_start": "2026-01-01T00:00:00Z",
            "description": "Pro plan",
            "reference": "line_1",
            "tax_code": "txcd_business_saas"
        }
    ],
    "legal_entity_id": "<string>",
    "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
    "tax_behavior": "exclusive"
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    currency: 'USD',
    customer: {
      address: {
        country: 'USA',
        city: 'San Francisco',
        line1: '123 Main St',
        line2: 'Suite 100',
        postal_code: '94105',
        state: 'CA'
      },
      first_name: 'Jane',
      last_name: 'Doe',
      email: 'buyer@example.com',
      reference: '<string>',
      tax_ids: [{type: 'eu_vat', value: 'DE123456789'}]
    },
    line_items: [
      {
        amount: '100.00',
        quantity: '1',
        billing_period_end: '2026-02-01T00:00:00Z',
        billing_period_start: '2026-01-01T00:00:00Z',
        description: 'Pro plan',
        reference: 'line_1',
        tax_code: 'txcd_business_saas'
      }
    ],
    legal_entity_id: '<string>',
    merchant_id: 'mrch_01H8XGJWBWBAQ4PLwXYZ',
    tax_behavior: 'exclusive'
  })
};

fetch('https://api.alguna.io/tax/calculations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "currency": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "line_items": [
    {
      "tax_amount": "6.60",
      "tax_rate": "8.25",
      "taxable_amount": "80.00",
      "billing_period_end": "2023-11-07T05:31:56Z",
      "billing_period_start": "2023-11-07T05:31:56Z",
      "reference": "<string>",
      "tax_reason": "<string>",
      "tax_type": "<string>"
    }
  ],
  "total_tax": "<string>",
  "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ"
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

Authorizations

Authorization

string

header

required

API key authentication. Pass your API key as a Bearer token.

Headers

Alguna-Version

enum<string>

required

Available options:

2026-04-01

Idempotency-Key

string

A unique string used to ensure the request is processed exactly once. If you retry a request with the same idempotency key within 24 hours, the original response is returned without re-executing the operation.

Maximum string length: 255

Example:

"ik_a1b2c3d4e5f6"

Body

application/json

currency

string

required

ISO 4217 currency code

Example:

"USD"

customer

object

required

Who is being taxed

Show child attributes

line_items

object[]

required

Line items to tax

Show child attributes

legal_entity_id

string | null

Selling legal entity; defaults to the org's default when omitted

merchant_id

string | null

Existing sub-merchant the receipt is issued for; you remain the seller of record. Create the merchant before referencing it here. Requires the merchants entitlement

Example:

"mrch_01H8XGJWBWBAQ4PLwXYZ"

tax_behavior

enum<string> | null

Whether line amounts exclude (default) or already include tax

Available options:

exclusive,

inclusive

Example:

"exclusive"

Response

Success

currency

string

required

Currency of the amounts

expires_at

string<date-time>

required

When the calculation stops being issuable

string

required

Id of the persisted calculation; pass it when issuing a receipt to pin these results

line_items

object[]

required

Per-line tax breakdown

Show child attributes

total_tax

string

required

Sum of per-line tax amounts

merchant_id

string | null

Sub-merchant the calculation was made for; a document issued from it inherits this attribution

Example:

"mrch_01H8XGJWBWBAQ4PLwXYZ"

⌘I

Calculate tax

curl --request POST \
  --url https://api.alguna.io/tax/calculations \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "USD",
  "customer": {
    "address": {
      "country": "USA",
      "city": "San Francisco",
      "line1": "123 Main St",
      "line2": "Suite 100",
      "postal_code": "94105",
      "state": "CA"
    },
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "buyer@example.com",
    "reference": "<string>",
    "tax_ids": [
      {
        "type": "eu_vat",
        "value": "DE123456789"
      }
    ]
  },
  "line_items": [
    {
      "amount": "100.00",
      "quantity": "1",
      "billing_period_end": "2026-02-01T00:00:00Z",
      "billing_period_start": "2026-01-01T00:00:00Z",
      "description": "Pro plan",
      "reference": "line_1",
      "tax_code": "txcd_business_saas"
    }
  ],
  "legal_entity_id": "<string>",
  "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
  "tax_behavior": "exclusive"
}
'

import requests

url = "https://api.alguna.io/tax/calculations"

payload = {
    "currency": "USD",
    "customer": {
        "address": {
            "country": "USA",
            "city": "San Francisco",
            "line1": "123 Main St",
            "line2": "Suite 100",
            "postal_code": "94105",
            "state": "CA"
        },
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "buyer@example.com",
        "reference": "<string>",
        "tax_ids": [
            {
                "type": "eu_vat",
                "value": "DE123456789"
            }
        ]
    },
    "line_items": [
        {
            "amount": "100.00",
            "quantity": "1",
            "billing_period_end": "2026-02-01T00:00:00Z",
            "billing_period_start": "2026-01-01T00:00:00Z",
            "description": "Pro plan",
            "reference": "line_1",
            "tax_code": "txcd_business_saas"
        }
    ],
    "legal_entity_id": "<string>",
    "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ",
    "tax_behavior": "exclusive"
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    currency: 'USD',
    customer: {
      address: {
        country: 'USA',
        city: 'San Francisco',
        line1: '123 Main St',
        line2: 'Suite 100',
        postal_code: '94105',
        state: 'CA'
      },
      first_name: 'Jane',
      last_name: 'Doe',
      email: 'buyer@example.com',
      reference: '<string>',
      tax_ids: [{type: 'eu_vat', value: 'DE123456789'}]
    },
    line_items: [
      {
        amount: '100.00',
        quantity: '1',
        billing_period_end: '2026-02-01T00:00:00Z',
        billing_period_start: '2026-01-01T00:00:00Z',
        description: 'Pro plan',
        reference: 'line_1',
        tax_code: 'txcd_business_saas'
      }
    ],
    legal_entity_id: '<string>',
    merchant_id: 'mrch_01H8XGJWBWBAQ4PLwXYZ',
    tax_behavior: 'exclusive'
  })
};

fetch('https://api.alguna.io/tax/calculations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "currency": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "line_items": [
    {
      "tax_amount": "6.60",
      "tax_rate": "8.25",
      "taxable_amount": "80.00",
      "billing_period_end": "2023-11-07T05:31:56Z",
      "billing_period_start": "2023-11-07T05:31:56Z",
      "reference": "<string>",
      "tax_reason": "<string>",
      "tax_type": "<string>"
    }
  ],
  "total_tax": "<string>",
  "merchant_id": "mrch_01H8XGJWBWBAQ4PLwXYZ"
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

{
  "detail": "<string>",
  "status": 123
}

API Reference

Examples

SDKs

API Reference

Webhooks

Calculate tax

Authorizations

Headers

Body

Response