Calculate B2B commercial invoices

Request

x-api-key: <your-api-key>

Content-Type: application/json

Request body

Response

{
  "calculatedLineItems": [],
  "invoiceSummary": {
    "currency": "EUR",
    "decimalPlaces": 12,
    "grandTotal": 3,
    "grossSubtotal": 16.25,
    "invoiceNumber": "<invoice number>",
    "netTaxableTotal": 3,
    "totalDiscounts": 3,
    "totalTax": 3.74
  },
  "status": "success",
  "taxBreakdown": [
    {
      "calculatedTaxAmount": 19.99,
      "taxCategory": "general",
      "taxRate": 4.28,
      "taxableBaseAmount": 19.99
    }
  ],
  "taxExemptionRule": {
    "isReverseChargeApplied": true,
    "legalNotice": "<legal notice>"
  },
  "tokensDeducted": 1
}

What it does

Calculate B2B commercial invoices with multi-currency decimal precision (ISO 4217), EU Reverse-Charge tax zero-rating, line-item discount distribution, and tax category summaries

Request

Body

Field	Type	Required	Description
`buyer`	object	yes
`↳ countryCode`	string	yes
`↳ isB2B`	boolean	no
`↳ name`	string	no
`↳ vatNumber`	string	no
`currency`	string	yes	ISO 4217 3-letter currency code (e.g., "EUR", "USD", "GBP", "PLN", "JPY")
`globalDiscountAmount`	number	no
`invoiceNumber`	string	yes	Unique commercial invoice identifier string
`lineItems`	array<object>	yes
`↳ description`	string	yes
`↳ discountAmount`	number	no
`↳ quantity`	number	yes
`↳ taxCategory`	string	no
`↳ taxRate`	number	no
`↳ unitPrice`	number	yes
`seller`	object	yes
`↳ countryCode`	string	yes
`↳ name`	string	no
`↳ vatNumber`	string	no

Example request

{
  "buyer": {
    "countryCode": "PL",
    "isB2B": true,
    "name": "Ada Lovelace",
    "vatNumber": "PL8993033031"
  },
  "currency": "EUR",
  "globalDiscountAmount": 0,
  "invoiceNumber": "<invoice number>",
  "lineItems": [],
  "seller": {
    "countryCode": "PL",
    "name": "Ada Lovelace",
    "vatNumber": "PL8993033031"
  }
}

Response

Field	Type	Description
`calculatedLineItems`	array<object>
`↳ allocatedGlobalDiscount`	number
`↳ appliedTaxRate`	number
`↳ description`	string
`↳ grossAmount`	number
`↳ itemIndex`	integer
`↳ lineDiscount`	number
`↳ lineTotal`	number
`↳ netTaxableAmount`	number
`↳ quantity`	number
`↳ taxAmount`	number
`↳ unitPrice`	number
`invoiceSummary`	object
`↳ currency`	string
`↳ decimalPlaces`	integer
`↳ grandTotal`	number
`↳ grossSubtotal`	number
`↳ invoiceNumber`	string
`↳ netTaxableTotal`	number
`↳ totalDiscounts`	number
`↳ totalTax`	number
`status`	string
`taxBreakdown`	array<object>
`↳ calculatedTaxAmount`	number
`↳ taxCategory`	string
`↳ taxRate`	number
`↳ taxableBaseAmount`	number
`taxExemptionRule`	object
`↳ isReverseChargeApplied`	boolean
`↳ legalNotice`	string
`tokensDeducted`	integer

Example response

{
  "calculatedLineItems": [],
  "invoiceSummary": {
    "currency": "EUR",
    "decimalPlaces": 12,
    "grandTotal": 3,
    "grossSubtotal": 16.25,
    "invoiceNumber": "<invoice number>",
    "netTaxableTotal": 3,
    "totalDiscounts": 3,
    "totalTax": 3.74
  },
  "status": "success",
  "taxBreakdown": [
    {
      "calculatedTaxAmount": 19.99,
      "taxCategory": "general",
      "taxRate": 4.28,
      "taxableBaseAmount": 19.99
    }
  ],
  "taxExemptionRule": {
    "isReverseChargeApplied": true,
    "legalNotice": "<legal notice>"
  },
  "tokensDeducted": 1
}

Errors

Every error answers with the same envelope: an HTTP status, a machine code and a sentence.

`400`	The body or a parameter failed validation. The details array names the field.
`401`	No key, a revoked key or a wrong header. Send x-api-key.
`402`	The wallet cannot cover this call. Top up or wait for the monthly grant.
`404`	The resource does not exist, or it is not yours. Both answer identically and cost nothing.
`429`	Over the per-minute quota of your tier. Back off and retry.
`5xx`	Upstream refused or timed out. The call is not billed.

Code

curl -X POST 'https://app.castomapi.com/v1/verify/invoice-calculator' \
  -H 'x-api-key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"buyer": {"countryCode": "PL", "isB2B": true, "name": "Ada Lovelace", "vatNumber": "PL8993033031"}, "currency": "EUR", "globalDiscountAmount": 0, "invoiceNumber": "<invoice number>", "lineItems": [], "seller": {"countryCode": "PL", "name": "Ada Lovelace", "vatNumber": "PL8993033031"}}'

const res = await fetch('https://app.castomapi.com/v1/verify/invoice-calculator', {
  method: 'POST',
  headers: { 'x-api-key': '<your-api-key>', 'Content-Type': 'application/json' },
  body: JSON.stringify({"buyer": {"countryCode": "PL", "isB2B": true, "name": "Ada Lovelace", "vatNumber": "PL8993033031"}, "currency": "EUR", "globalDiscountAmount": 0, "invoiceNumber": "<invoice number>", "lineItems": [], "seller": {"countryCode": "PL", "name": "Ada Lovelace", "vatNumber": "PL8993033031"}})
});
const data = await res.json();
console.log(data);

import { request } from 'node:https';

// Node 18+ has fetch built in
const res = await fetch('https://app.castomapi.com/v1/verify/invoice-calculator', {
  method: 'POST',
  headers: { 'x-api-key': '<your-api-key>', 'Content-Type': 'application/json' },
  body: JSON.stringify({"buyer": {"countryCode": "PL", "isB2B": true, "name": "Ada Lovelace", "vatNumber": "PL8993033031"}, "currency": "EUR", "globalDiscountAmount": 0, "invoiceNumber": "<invoice number>", "lineItems": [], "seller": {"countryCode": "PL", "name": "Ada Lovelace", "vatNumber": "PL8993033031"}})
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    'https://app.castomapi.com/v1/verify/invoice-calculator',
    headers={'x-api-key': '<your-api-key>'},
    json={"buyer": {"countryCode": "PL", "isB2B": True, "name": "Ada Lovelace", "vatNumber": "PL8993033031"}, "currency": "EUR", "globalDiscountAmount": 0, "invoiceNumber": "<invoice number>", "lineItems": [], "seller": {"countryCode": "PL", "name": "Ada Lovelace", "vatNumber": "PL8993033031"}},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://app.castomapi.com/v1/verify/invoice-calculator');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['x-api-key: <your-api-key>', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['buyer' => ['countryCode' => 'PL', 'isB2B' => true, 'name' => 'Ada Lovelace', 'vatNumber' => 'PL8993033031'], 'currency' => 'EUR', 'globalDiscountAmount' => 0, 'invoiceNumber' => '<invoice number>', 'lineItems' => [], 'seller' => ['countryCode' => 'PL', 'name' => 'Ada Lovelace', 'vatNumber' => 'PL8993033031']]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);

Cost and limits

This operation needs no API key and costs nothing: called without a key it answers 200 and deducts zero tokens, up to 10 requests a minute per IP address.

Rate limits per minute

No key	10
Free	60
Pro	300
Enterprise	1200

Docs → Pricing

Questions

What does Calculate B2B commercial invoices cost?

This operation needs no API key and costs nothing: called without a key it answers 200 and deducts zero tokens, up to 10 requests a minute per IP address.

How do I authenticate?

Send your key in the x-api-key header. One key covers every metered endpoint; there is nothing to enable per endpoint.

Can I send an Authorization: Bearer token instead?

Not for a metered endpoint — those take the x-api-key header and nothing else. Bearer tokens belong to the account side: the dashboard and account APIs accept a JWT session, and castomapi-auth issues those through a standard OAuth2 handshake, with authorization code, client credentials and refresh grants. The auth service page covers it.

What are the limits?

10 requests a minute per IP with no key at all, 60 a minute on the free tier, 300 on Pro, 1200 on Enterprise. Above the no-key tier the quota is per account, across every endpoint.

OpenAPI: https://app.castomapi.com/docs/json

Request

Response

What it does

Request

Body

Example request

Response

Example response

Errors

Code

Cost and limits

Rate limits per minute

Questions

More in Verify

Where it fits