POST /api/billing/v1/calculate

A dry run. It computes the exact totals a document would get — using the same integer-agorot engine that issuing uses — and issues nothing. Use it on a checkout page to show the customer the number that will be billed, with the VAT breakdown.

Read-only: it works while the account is dormant and in sandbox, and is not plan-gated. It still needs a valid key and counts toward the 600 requests/minute limit.

Request#

Native shape (key in a header):

http

POST /api/billing/v1/calculate
X-Api-Key: bk_…
Content-Type: application/json

json

{
  "document": {
    "docType": 3,
    "taxIncluded": true,
    "vatBp": 1800,
    "lines": [
      { "name": "מוצר חייב", "quantityMilli": 1000, "unitPriceAgorot": 11800, "vatBp": 1800 },
      { "name": "מוצר פטור", "quantityMilli": 1000, "unitPriceAgorot": 5000, "vatBp": 0 }
    ]
  }
}

Or the Invoice4U-compatible shape (shekels, key as token), identical to create-document's: {"doc": {"DocumentType": 3, "Items": […]}, "token": "<key>"}. In that shape the compat validation applies (VAT 0 or 18%, Items and ApiIdentifier required).

Only lines is needed for the math; taxIncluded defaults to true here when omitted. Line and document discounts, roundTotal and per-line vatBp behave exactly as on issue. Receipts (docType: 2) force VAT to 0.

Unlike create-document, the native shape is not field-validated here: there is no VAT-rate check and no integer check, so garbage in gives garbage out. Send the same values you will send to create-document.

Response#

json

{
  "currency": "ILS",
  "taxIncluded": true,
  "lines": [
    { "name": "מוצר חייב", "quantityMilli": 1000, "unitPriceAgorot": 11800, "vatBp": 1800, "totalAgorot": 11800 },
    { "name": "מוצר פטור", "quantityMilli": 1000, "unitPriceAgorot": 5000, "vatBp": 0, "totalAgorot": 5000 }
  ],
  "subtotalAgorot": 16800,
  "discountAgorot": 0,
  "roundingAgorot": 0,
  "netAgorot": 15000,
  "vatAgorot": 1800,
  "totalAgorot": 16800
}

Field	Meaning
`lines[].totalAgorot`	Line total after the line discount, in the document's price semantics (incl./excl. VAT per `taxIncluded`).
`subtotalAgorot`	Sum of line totals after line discounts, before the document discount.
`discountAgorot`	Document discount actually applied.
`roundingAgorot`	Signed adjustment to reach a whole-shekel total (`roundTotal`).
`netAgorot`	Total without VAT.
`vatAgorot`	VAT, computed and summed per line — only taxable lines contribute.
`totalAgorot`	Gross total after discount and rounding — the number that would be billed.

The response does not include vatMode handling, the mixed-VAT split (taxableNet / exemptNet) or currency conversion; currency is echoed from the request (default ILS).

Errors#

400 body is not JSON · 401 bad key · 422 {"error":"document.lines is required"} (no lines) or the compatible-shape mapper's message · 429 rate limited. See errors.