Documentation

Quickstart

1. Create an account

Sign up at duty27.com/signup and confirm your email. New accounts start on the Free tier — 500 calculations/month, no credit card required.

2. Get your API credentials

Your client ID and secret are generated automatically when your signup is confirmed — by the time you first open your account page, they're already there. The secret is shown in plaintext exactly once — copy it then. After that it's hidden for good; use Regenerate key if you ever need to see it again (this invalidates the old one).

3. Exchange your credentials for an access token

Duty27 uses the OAuth2 client_credentials grant. POST your client ID and secret to Cognito's token endpoint to get a short-lived access token.

curl -X POST 'https://auth.duty27.com/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  -d 'grant_type=client_credentials&scope=duty27-api/access'

const res = await fetch('https://auth.duty27.com/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + btoa('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET')
  },
  body: 'grant_type=client_credentials&scope=duty27-api/access'
});
const { access_token } = await res.json();

import requests

res = requests.post(
    'https://auth.duty27.com/oauth2/token',
    auth=('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET'),
    data={'grant_type': 'client_credentials', 'scope': 'duty27-api/access'}
)
access_token = res.json()['access_token']

4. Make your first calculation

Send the access token as a Bearer token on POST /v1/calculate.

curl -X POST 'https://api.duty27.com/v1/calculate' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_code": "DE",
    "date": "2026-08-19",
    "amount": "100.00",
    "amount_type": "NET",
    "b2b": false
  }'

const res = await fetch('https://api.duty27.com/v1/calculate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    country_code: 'DE',
    date: '2026-08-19',
    amount: '100.00',
    amount_type: 'NET',
    b2b: false
  })
});
const result = await res.json();

import requests

res = requests.post(
    'https://api.duty27.com/v1/calculate',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'country_code': 'DE',
        'date': '2026-08-19',
        'amount': '100.00',
        'amount_type': 'NET',
        'b2b': False
    }
)
result = res.json()

Authentication

Duty27 uses OAuth2 client_credentials — no user is involved, your backend authenticates as itself using the client ID and secret from your account page.

Token endpoint

POST your credentials as HTTP Basic auth (or client_id/client_secret form fields) to https://auth.duty27.com/oauth2/token with grant_type=client_credentials. You'll get back a short-lived access_token.

Scope

Request scope=duty27-api/access. This is the only scope your credentials are authorized for.

Token lifetime

Access tokens are short-lived. There's no refresh-token flow for machine-to-machine credentials — when a token expires, request a new one the same way you got the first.

Which routes use this token

This access token is used for POST /v1/calculate and the transaction-archive write routes: POST /v1/transactions, POST /v1/transactions/{orderId}/evidence, and POST /v1/transactions/{orderId}/refund. Everything else — reading back an archived transaction, usage, credentials, billing — lives on the web dashboard and uses your browser session instead.

Endpoints

POST /v1/calculate

Calculates VAT for a single sale.

Response fields:

Every successful response also carries an X-Monthly-Calls-Remaining header — how many of your plan's included calls are left this billing period (Free: your remaining calls before you're capped; Growth/Scale: your remaining calls before overage billing starts, floored at 0). FREE_TIER_LIMIT_EXCEEDED responses carry it too, reading 0. RATE_LIMIT_EXCEEDED responses instead carry a Retry-After header — seconds until you can safely retry.

curl -X POST 'https://api.duty27.com/v1/calculate' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_code": "FR",
    "date": "2026-08-19",
    "amount": "250.00",
    "amount_type": "GROSS",
    "b2b": true,
    "buyer_vat_number": "123456789",
    "seller_vat_country_override": "DE",
    "seller_vat_number_override": "987654321"
  }'

const res = await fetch('https://api.duty27.com/v1/calculate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    country_code: 'FR',
    date: '2026-08-19',
    amount: '250.00',
    amount_type: 'GROSS',
    b2b: true,
    buyer_vat_number: '123456789',
    seller_vat_country_override: 'DE',
    seller_vat_number_override: '987654321'
  })
});
if (res.status === 429) {
  const retryAfterSeconds = res.headers.get('Retry-After');
  // wait retryAfterSeconds, then retry
}
const result = await res.json();

import requests

res = requests.post(
    'https://api.duty27.com/v1/calculate',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'country_code': 'FR',
        'date': '2026-08-19',
        'amount': '250.00',
        'amount_type': 'GROSS',
        'b2b': True,
        'buyer_vat_number': '123456789',
        'seller_vat_country_override': 'DE',
        'seller_vat_number_override': '987654321'
    }
)
if res.status_code == 429:
    retry_after_seconds = res.headers.get('Retry-After')
    # wait retry_after_seconds, then retry
result = res.json()

POST /v1/transactions

Archives a completed sale as a permanent, tamper-evident record for OSS reporting and audits, and — for a qualifying cross-border B2C sale — accrues its value toward the €10,000 annual Article 59c threshold that /v1/calculate's cross_border_rate_basis reads. Independent of /v1/calculate: a rate lookup never guarantees a sale happened, so nothing here is written until you call this endpoint with a real, completed transaction.

Requires a paid tier: Scale, or Growth with the Transaction Archive Add-on. Free tier always gets 403 TIER_NOT_ELIGIBLE; Growth without the add-on gets 402 TRANSACTION_ARCHIVE_ADDON_REQUIRED.

Request fields (all under a JSON body with snake_case keys):

Cross-border threshold accrual: for a B2C sale where your account has a verified origin country on file, different from country_code, and BOTH are EU member states, this sale's net amount accrues toward the running €10,000 Article 59c total /v1/calculate's cross_border_rate_basis reads (see that field's own note). A sale to or from a non-EU country is out of scope entirely and never accrues, even though origin and destination differ. B2B sales never accrue — reverse charge already covers that case.

Currency conversion: a non-EUR cross-border sale's net_amount is converted to EUR before accruing, using the last ECB reference rate published on or before transaction_timestamp's date, divided (never inverted) and rounded to the nearest cent with exact half-cent results rounding up — the same convention EU Regulation 1103/97 mandates for euro conversions. If no rate is on file for that currency/date, the request is rejected with 422 NO_EXCHANGE_RATE_AVAILABLE before anything is archived, rather than silently mistracking the total.

Response fields (201):

curl -X POST 'https://api.duty27.com/v1/transactions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "order_id": "inv-2026-001234",
    "transaction_timestamp": "2026-08-25T12:15:00Z",
    "currency": "EUR",
    "net_amount": 100.00,
    "vat_amount": 20.00,
    "vat_rate": 20.00,
    "vat_type": "STANDARD",
    "country_code": "FR",
    "customer": {
      "type": "B2C",
      "name": "Jane Buyer",
      "billing_address": {
        "street": "1 Rue Exemple",
        "city": "Paris",
        "postal_code": "75001",
        "country_code": "FR"
      }
    },
    "evidence": {
      "ip_address": "203.0.113.5",
      "card_bin_country": "FR"
    }
  }'

const res = await fetch('https://api.duty27.com/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    order_id: 'inv-2026-001234',
    transaction_timestamp: '2026-08-25T12:15:00Z',
    currency: 'EUR',
    net_amount: 100.00,
    vat_amount: 20.00,
    vat_rate: 20.00,
    vat_type: 'STANDARD',
    country_code: 'FR',
    customer: {
      type: 'B2C',
      name: 'Jane Buyer',
      billing_address: {
        street: '1 Rue Exemple',
        city: 'Paris',
        postal_code: '75001',
        country_code: 'FR'
      }
    },
    evidence: {
      ip_address: '203.0.113.5',
      card_bin_country: 'FR'
    }
  })
});
const result = await res.json();

import requests

res = requests.post(
    'https://api.duty27.com/v1/transactions',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'order_id': 'inv-2026-001234',
        'transaction_timestamp': '2026-08-25T12:15:00Z',
        'currency': 'EUR',
        'net_amount': 100.00,
        'vat_amount': 20.00,
        'vat_rate': 20.00,
        'vat_type': 'STANDARD',
        'country_code': 'FR',
        'customer': {
            'type': 'B2C',
            'name': 'Jane Buyer',
            'billing_address': {
                'street': '1 Rue Exemple',
                'city': 'Paris',
                'postal_code': '75001',
                'country_code': 'FR'
            }
        },
        'evidence': {
            'ip_address': '203.0.113.5',
            'card_bin_country': 'FR'
        }
    }
)
result = res.json()

POST /v1/transactions/{orderId}/evidence

Attaches follow-up evidence to an order that got an EVIDENCE_MISMATCH or INSUFFICIENT_EVIDENCE warning when archived — for example a card BIN pulled from your payment processor's own records after the fact. The original record is never edited or replaced; this writes a separate, equally permanent record alongside it.

This is a documentation aid, not a compliance determination — Duty27 doesn't decide whether your evidence is sufficient, doesn't re-derive or change vat_amount/vat_rate on the original sale, and never marks a warning as "resolved." The warnings returned below tell you what the combined evidence looks like now; whether that's enough for your own recordkeeping is your call, same as vat_type and vat_rate are your own inputs elsewhere in this API.

Only accepted for an order that actually has a warning on file — an order archived cleanly returns 409 NO_WARNING_ON_RECORD. Requires the same tier as archiving itself (Scale, or Growth with the add-on).

Query parameters (both required, no default):

Request fields (all under a JSON body with snake_case keys; at least one of ip_address, card_bin_country, vies_consultation_number, bank_country, mobile_country_code, other_evidence, or note must be non-blank):

Response fields (201):

Every supplement you've submitted for an order is returned alongside the original record from your dashboard's own transaction lookup, and referenced (order_id + submitted_at, not the evidence content itself) in a dedicated file in your quarterly OSS report package — a paper trail to hand an auditor, without Duty27 asserting anything about what it proves.

curl -X POST 'https://api.duty27.com/v1/transactions/inv-2026-001234/evidence?year=2026&quarter=3' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "payment processor records",
    "card_bin_country": "FR"
  }'

const res = await fetch('https://api.duty27.com/v1/transactions/inv-2026-001234/evidence?year=2026&quarter=3', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source: 'payment processor records',
    card_bin_country: 'FR'
  })
});
const result = await res.json();

import requests

res = requests.post(
    'https://api.duty27.com/v1/transactions/inv-2026-001234/evidence',
    params={'year': 2026, 'quarter': 3},
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'source': 'payment processor records',
        'card_bin_country': 'FR'
    }
)
result = res.json()

POST /v1/transactions/{orderId}/refund

Records a full or partial refund against a previously archived transaction, for OSS reporting and audits. The original record is never edited; this writes a separate, equally permanent record alongside it.

Requires the same tier as archiving itself: Scale, or Growth with the Transaction Archive Add-on. Free tier gets 403 TIER_NOT_ELIGIBLE; Growth without the add-on gets 402 TRANSACTION_ARCHIVE_ADDON_REQUIRED.

Query parameters (both required, no default) — these identify the ORIGINAL transaction's storage partition, not the refund's own filing period:

Request fields (all under a JSON body with snake_case keys, amounts in the original transaction's currency):

Response fields (201):

curl -X POST 'https://api.duty27.com/v1/transactions/inv-2026-001234/refund?year=2026&quarter=3' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "refund_amount_net": 50.00,
    "refund_amount_vat": 10.00,
    "reason": "Partial return"
  }'

const res = await fetch('https://api.duty27.com/v1/transactions/inv-2026-001234/refund?year=2026&quarter=3', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    refund_amount_net: 50.00,
    refund_amount_vat: 10.00,
    reason: 'Partial return'
  })
});
const result = await res.json();

import requests

res = requests.post(
    'https://api.duty27.com/v1/transactions/inv-2026-001234/refund',
    params={'year': 2026, 'quarter': 3},
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'refund_amount_net': 50.00,
        'refund_amount_vat': 10.00,
        'reason': 'Partial return'
    }
)
result = res.json()

Errors

Every error response is a JSON body with a top-level error code and human-readable message. One error additionally nests endpoint-specific context under a details object: NO_RATE_DATA (422) nests country_code/date there.

A malformed /v1/calculate request (e.g. a missing required field) also returns INVALID_REQUEST (400) in the same { error, message } shape as every other row above — there's no separate response format to handle.