StabisoDocs

API reference

Withholding tax

Operation Summary Scope Idempotency-Key
GET /v1/entities/{entity}/withholding-tax Get the withholding tax kept back from vendors in a period read
GET /v1/entities/{entity}/withholding-tax/codes List the withholding tax codes for vendors read

GET /v1/entities/{entity}/withholding-tax

Get the withholding tax kept back from vendors in a period

Every posted bill and vendor credit note that kept withholding tax back: the vendor, the bill, the net amount the tax was taken on, the rate, the tax in the document currency and in the functional currency as booked, and the code with whom it is paid to; totals per code and currency. A cash discount taken on such a bill reduced its base and its tax in proportion: by bill date it is a row of its own (cash_discount), by payment date the bill's base and tax are less it. By bill date the functional total is what the period's bills and discounts booked on the withholding tax account (role vendor_withholding_payable); by payment date each payment's part is at the rate of its day. Paying the authority is a payment from the bank to that account (a bank line booked to it, or a journal entry): it is not a control account. Read-only. 422 when start is after end.
Required scope read (admin implies every scope)
Operation id get_report_v1_entities__entity__withholding_tax_get

Parameters

In Name Type Required Description
path entity string yes Entity code, e.g. CH01 (GET /v1/entities).
query start string (date) yes The first day of the period, ISO 8601.
query end string (date) yes The last day of the period, not before start.
query basis "bill_date" | "payment_date" bill_date (default): the tax of the bills and vendor credit notes dated in the period, and of the cash discounts taken in it, as booked; payment_date: the part of each bill's tax that payments made in the period released, at their rates, for authorities that are owed the tax when the vendor is paid. (default "bill_date")
query format "csv" | "json" json (default) or csv: one row per document, its columns the fields of rows (their meanings are those of the fields). (default "json")

Example request

curl "$ERP_URL/v1/entities/CH01/withholding-tax?start=2026-09-01&end=2026-09-30" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status Meaning Body
200 JSON or CSV. WithholdingReport, text/csv
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
404 The resource does not exist, or belongs to another organization (not_found). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "entity": "string",
  "functional_currency": "string",
  "start": "2026-09-21",
  "end": "2026-09-21",
  "basis": "bill_date",
  "account": "string",
  "rows": [
    {
      "document_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "number": "string",
      "their_reference": "string",
      "kind": "string",
      "document_date": "2026-09-21",
      "vendor": "string",
      "vendor_name": "string",
      "vendor_country": "string",
      "vendor_vat_number": "string",
      "code": "string",
      "description": "string",
      "authority": "string",
      "rate": "string",
      "currency": "string",
      "base": "string",
      "withheld": "string",
      "paid": "string",
      "amount": "string",
      "amount_functional": "string"
    }
  ],
  "totals": [
    {
      "code": "string",
      "currency": "string",
      "documents": 1,
      "base": "string",
      "amount": "string",
      "amount_functional": "string"
    }
  ],
  "total_functional": "string"
}

GET /v1/entities/{entity}/withholding-tax/codes

List the withholding tax codes for vendors

The withholding tax codes of the company's country a vendor can carry (withholding_code on the vendor): Germany Paragraph 50a EStG, Italy ritenuta d'acconto, Spain IRPF, the US NRA and backup withholding, and others, each with its rate and whom it is paid to. A vendor may also carry custom with a rate of its own. account is where bills book the tax.
Required scope read (admin implies every scope)
Operation id list_codes_v1_entities__entity__withholding_tax_codes_get

Parameters

In Name Type Required Description
path entity string yes Entity code, e.g. CH01 (GET /v1/entities).

Example request

curl "$ERP_URL/v1/entities/CH01/withholding-tax/codes" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status Meaning Body
200 OK WithholdingCodes
401 Missing or invalid API key (unauthorized). ErrorEnvelope
403 The caller lacks the required scope (missing_right, with scope), the key belongs to no person where a person is needed (forbidden), or the approval policy denies the action (policy_denied, with action and rule_id). ErrorEnvelope
404 The resource does not exist, or belongs to another organization (not_found). ErrorEnvelope
422 Validation failed: the error envelope (validation_failed). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and fields lists each error with pydantic's loc, type and msg beside its sentence (message) and its parts, to word it in another language: items (name and number from 1: line 2), field (its name as sent) and the rule it breaks with its limit, count and choices (none for a validator's own sentence); FastAPI's own detail list stays beside the envelope. HTTPValidationError

Example response (shape)

{
  "country": "string",
  "codes": [
    {
      "code": "string",
      "country": "string",
      "rate": "string",
      "name": "string",
      "authority": "string"
    }
  ],
  "account": "string",
  "account_name": "string"
}

Schemas

WithholdingCodeOut

Field Type Required Description
code string yes The code a vendor carries, e.g. IT-RA-20.
country string yes The country of the company that withholds it.
rate string yes The rate in percent of a bill's net amount before VAT.
name string yes What it is, with its legal basis.
authority string yes Whom the company pays it to, and with which return.

WithholdingCodes

The codes the company's vendors can carry, and where the tax is booked.

Field Type Required Description
country string yes The company's country, whose codes these are.
codes array of WithholdingCodeOut yes The table of the company's country; a vendor may also carry custom with a rate of its own (a treaty rate, say). Empty where the country has none (Switzerland).
account string or null yes The account the tax kept back is booked to (role vendor_withholding_payable); null when the chart has none, and bills of a vendor with withholding cannot be posted until one is given that role.
account_name string or null yes Its name.

WithholdingReport

The withholding tax kept back from vendors in a period, to file it and pay the authority.

Field Type Required Description
entity string yes The company's code.
functional_currency string yes The currency of the _functional amounts.
start string (date) yes The first day of the period.
end string (date) yes The last day of the period.
basis "bill_date" | "payment_date" yes bill_date: the tax of the bills dated in the period and of the cash discounts taken in it, as booked on the account; payment_date: the part the payments made in the period released, at their rates (Italy, Germany, Spain and the US owe the tax for the month or quarter the vendor is paid).
account string or null yes The withholding tax payable account.
rows array of WithholdingRow yes The documents, oldest first.
totals array of WithholdingTotal yes Per code and currency.
total_functional string yes All the tax counted, in the functional currency: by bill date, what the period's bills and cash discounts booked on the withholding tax account; by payment date, what the period's payments released at their rates.

WithholdingRow

One bill or vendor credit note that kept withholding tax back, or a cash discount that took tax off a bill.

Field Type Required Description
document_id string (uuid) yes The bill or credit note.
number string or null yes Our number of it, e.g. BILL-2026-000012.
their_reference string or null yes The vendor's own invoice number.
kind string yes purchase_bill, purchase_credit_note, or (by bill date) cash_discount: a cash discount taken on the bill, which reduced the base and the tax in proportion.
document_date string (date) yes The bill's date, when the tax was booked; for cash_discount the day of the payment that took it.
vendor string yes The vendor's code.
vendor_name string yes The vendor's name.
vendor_country string yes The vendor's country.
vendor_vat_number string or null yes The vendor's VAT or tax number.
code string yes The withholding code, e.g. IT-RA-20, or custom.
description string yes What the code is; for custom, the vendor's own rate.
authority string or null yes Whom the tax is paid to; null for custom.
rate string yes The rate in percent.
currency string yes The document currency; the amounts below are in it.
base string yes The net amount before VAT the tax was taken on; negative on a credit note and a cash discount. By payment date: less what cash discounts took off up to the period's end (the figure of the vendor's certificate).
withheld string yes The tax the document kept back, base times rate; negative on a credit note and a cash discount (they give tax back). By payment date: less what cash discounts took off up to the period's end.
paid string or null yes basis=payment_date: what payments to the vendor in the period settled on the bill; null by bill date.
amount string yes The tax this report counts in the period: by bill date all of withheld; by payment date the part of it the payments in the period released (the tax times what was paid over what the bill left to pay, the last payment all that is left), net of what their cash discounts took off.
amount_functional string yes amount in the company's functional currency: by bill date at the rate the bill was booked at; by payment date at the rate of each payment's day, as the authority is owed it (the payment moves it to that rate on the withholding tax account).

WithholdingTotal

Field Type Required Description
code string yes The withholding code.
currency string yes The document currency of amount.
documents integer yes How many rows: bills, credit notes and cash discounts.
base string yes Their net amounts the tax was taken on.
amount string yes The tax counted, in currency.
amount_functional string yes The same in the functional currency.
Stabiso, the Enterprise System of Record · generated from the code and its guides · release 6f03a5e846b3