> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/api-reference-app/billing-or-withholding-tax.md).

# Billing | Withholding Tax

## GET /v1/billing/withholding-tax/categories

> Get the withholding tax categories of your organization.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"WithholdingTaxCategoryList":{"required":["items","self","total"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WithholdingTaxCategory"},"description":"The withholding tax categories, ordered by name."},"total":{"type":"integer","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of the withholding tax category collection of your organization."},"WithholdingTaxCategory":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax category.","format":"int32"},"name":{"type":"string","description":"Name of the withholding tax category, unique within your organization.","nullable":true},"description":{"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax category of your organization: the kind of income an offer produces\n(e.g. software license, equipment rental, technical service). Withholding tax rules set the rate per country."},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/categories":{"get":{"tags":["Billing | Withholding Tax"],"summary":"Get the withholding tax categories of your organization.","responses":{"200":{"description":"The withholding tax categories, ordered by name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxCategoryList"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## POST /v1/billing/withholding-tax/categories

> Create a withholding tax category for your organization.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"CreateWithholdingTaxCategoryRequest":{"required":["name"],"type":"object","properties":{"name":{"maxLength":100,"minLength":1,"type":"string","description":"Name of the withholding tax category, unique within your organization."},"description":{"maxLength":500,"minLength":0,"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true}},"additionalProperties":false,"description":"Body for creating a withholding tax category."},"WithholdingTaxCategory":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax category.","format":"int32"},"name":{"type":"string","description":"Name of the withholding tax category, unique within your organization.","nullable":true},"description":{"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax category of your organization: the kind of income an offer produces\n(e.g. software license, equipment rental, technical service). Withholding tax rules set the rate per country."},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/categories":{"post":{"tags":["Billing | Withholding Tax"],"summary":"Create a withholding tax category for your organization.","requestBody":{"description":"The name of the category, unique within your organization, and an optional description.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWithholdingTaxCategoryRequest"}}}},"responses":{"201":{"description":"The created withholding tax category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxCategory"}}}},"400":{"description":"Bad request: Name missing or longer than 100 characters, or description longer than 500 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: A category with this name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## GET /v1/billing/withholding-tax/categories/{categoryId}

> Get a single withholding tax category of your organization.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"WithholdingTaxCategory":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax category.","format":"int32"},"name":{"type":"string","description":"Name of the withholding tax category, unique within your organization.","nullable":true},"description":{"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax category of your organization: the kind of income an offer produces\n(e.g. software license, equipment rental, technical service). Withholding tax rules set the rate per country."},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/categories/{categoryId}":{"get":{"tags":["Billing | Withholding Tax"],"summary":"Get a single withholding tax category of your organization.","parameters":[{"name":"categoryId","in":"path","description":"ID of the withholding tax category.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"The withholding tax category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxCategory"}}}},"403":{"description":"Forbidden: The category does not exist, belongs to another organization or access is denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## DELETE /v1/billing/withholding-tax/categories/{categoryId}

> Delete a withholding tax category of your organization.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/categories/{categoryId}":{"delete":{"tags":["Billing | Withholding Tax"],"summary":"Delete a withholding tax category of your organization.","parameters":[{"name":"categoryId","in":"path","description":"ID of the withholding tax category.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"204":{"description":"The category was deleted."},"403":{"description":"Forbidden: The category does not exist, belongs to another organization or access is denied.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: The category is still used by offers, billing items or withholding tax rules.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Patch the name and description of a withholding tax category of your organization.

> Offers, billing items and rules reference the category by id; a rename does not change any tax result.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"WithholdingTaxCategoryPatchRequest":{"required":["patchDocument"],"type":"object","properties":{"patchDocument":{"$ref":"#/components/schemas/JsonPatchDocument_WithholdingTaxCategoryPatch"}},"additionalProperties":false,"description":"JSON Patch request for a withholding tax category."},"JsonPatchDocument_WithholdingTaxCategoryPatch":{"type":"object","properties":{"operations":{"type":"array","items":{"$ref":"#/components/schemas/Operation_WithholdingTaxCategoryPatch"},"nullable":true}},"additionalProperties":false},"Operation_WithholdingTaxCategoryPatch":{"type":"object","properties":{"value":{"nullable":true},"path":{"type":"string","nullable":true},"op":{"type":"string","nullable":true},"from":{"type":"string","nullable":true}},"additionalProperties":false},"WithholdingTaxCategory":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax category.","format":"int32"},"name":{"type":"string","description":"Name of the withholding tax category, unique within your organization.","nullable":true},"description":{"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax category of your organization: the kind of income an offer produces\n(e.g. software license, equipment rental, technical service). Withholding tax rules set the rate per country."},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/categories/{categoryId}":{"patch":{"tags":["Billing | Withholding Tax"],"summary":"Patch the name and description of a withholding tax category of your organization.","description":"Offers, billing items and rules reference the category by id; a rename does not change any tax result.","parameters":[{"name":"categoryId","in":"path","description":"ID of the withholding tax category.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The patch request containing the JSON Patch document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxCategoryPatchRequest"}},"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxCategoryPatchRequest"}}}},"responses":{"200":{"description":"The updated withholding tax category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxCategory"}}}},"400":{"description":"Bad request: Invalid patch, name missing or longer than 100 characters, or description longer than 500 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: The category does not exist, belongs to another organization or access is denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: A category with this name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get the withholding tax rules of your organization.

> Rules with the same category, customer and countries never overlap in time. A customer-specific rule wins over the rule for all customers.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"WithholdingTaxRuleList":{"required":["items","self","total"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WithholdingTaxRule"},"description":"The withholding tax rules, ordered by category, target country, customer (general rules first) and ValidFrom (latest first)."},"total":{"type":"integer","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of the withholding tax rule collection of your organization."},"WithholdingTaxRule":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax rule.","format":"int32"},"category":{"$ref":"#/components/schemas/WithholdingTaxCategory"},"customerId":{"type":"integer","description":"ID of the customer the rule is limited to; null for all customers.","format":"int32","nullable":true},"customerName":{"type":"string","description":"Name of the customer the rule is limited to.","nullable":true},"sourceCountryIso2":{"type":"string","description":"Seller country (ISO 3166-1 alpha-2).","nullable":true},"targetCountryIso2":{"type":"string","description":"Buyer country of the invoice address (ISO 3166-1 alpha-2).","nullable":true},"rate":{"type":"number","description":"Withheld rate in percent.","format":"double"},"agreement":{"$ref":"#/components/schemas/WithholdingTaxAgreement"},"invoiceNote":{"type":"string","description":"Note printed on the invoice when the rule applies.","nullable":true},"validFrom":{"type":"string","description":"First day the rule applies (date of supply).","format":"date-time"},"validTo":{"type":"string","description":"Last day the rule applies; null for open-ended.","format":"date-time","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax rule of your organization: the rate withheld for a category between\na seller and a buyer country. A customer-specific rule wins over the rule for all customers; rules with the same\ncategory, customer and countries never overlap in time."},"WithholdingTaxCategory":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax category.","format":"int32"},"name":{"type":"string","description":"Name of the withholding tax category, unique within your organization.","nullable":true},"description":{"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax category of your organization: the kind of income an offer produces\n(e.g. software license, equipment rental, technical service). Withholding tax rules set the rate per country."},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"WithholdingTaxAgreement":{"enum":["Gross","Net"],"type":"string","description":"How a withholding tax is settled with the customer.\nGross: the invoice is unchanged, only the note is printed. Net: the invoice is grossed up by a surcharge (Rate / (100 - Rate))."},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/rules":{"get":{"tags":["Billing | Withholding Tax"],"summary":"Get the withholding tax rules of your organization.","description":"Rules with the same category, customer and countries never overlap in time. A customer-specific rule wins over the rule for all customers.","responses":{"200":{"description":"The withholding tax rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxRuleList"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a withholding tax rule for your organization.

> The category must be one of your organization; the customer, when set, must be a customer your organization bills.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"CreateWithholdingTaxRuleRequest":{"required":["categoryId","rate","sourceCountryIso2","targetCountryIso2","validFrom"],"type":"object","properties":{"categoryId":{"type":"integer","description":"ID of a withholding tax category of your organization.","format":"int32"},"customerId":{"type":"integer","description":"ID of a customer of your organization to limit the rule to; omit for all customers.","format":"int32","nullable":true},"sourceCountryIso2":{"minLength":1,"type":"string","description":"Seller country (ISO 3166-1 alpha-2), usually the country of your default billing address."},"targetCountryIso2":{"minLength":1,"type":"string","description":"Buyer country of the invoice address (ISO 3166-1 alpha-2)."},"rate":{"type":"number","description":"Withheld rate in percent, at least 0 and below 100.","format":"double"},"agreement":{"$ref":"#/components/schemas/WithholdingTaxAgreement"},"invoiceNote":{"type":"string","description":"Note printed on the invoice when the rule applies, at most 1000 characters.","nullable":true},"validFrom":{"type":"string","description":"First day the rule applies (date of supply).","format":"date-time"},"validTo":{"type":"string","description":"Last day the rule applies; omit for open-ended.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"Body for creating a withholding tax rule."},"WithholdingTaxAgreement":{"enum":["Gross","Net"],"type":"string","description":"How a withholding tax is settled with the customer.\nGross: the invoice is unchanged, only the note is printed. Net: the invoice is grossed up by a surcharge (Rate / (100 - Rate))."},"WithholdingTaxRule":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax rule.","format":"int32"},"category":{"$ref":"#/components/schemas/WithholdingTaxCategory"},"customerId":{"type":"integer","description":"ID of the customer the rule is limited to; null for all customers.","format":"int32","nullable":true},"customerName":{"type":"string","description":"Name of the customer the rule is limited to.","nullable":true},"sourceCountryIso2":{"type":"string","description":"Seller country (ISO 3166-1 alpha-2).","nullable":true},"targetCountryIso2":{"type":"string","description":"Buyer country of the invoice address (ISO 3166-1 alpha-2).","nullable":true},"rate":{"type":"number","description":"Withheld rate in percent.","format":"double"},"agreement":{"$ref":"#/components/schemas/WithholdingTaxAgreement"},"invoiceNote":{"type":"string","description":"Note printed on the invoice when the rule applies.","nullable":true},"validFrom":{"type":"string","description":"First day the rule applies (date of supply).","format":"date-time"},"validTo":{"type":"string","description":"Last day the rule applies; null for open-ended.","format":"date-time","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax rule of your organization: the rate withheld for a category between\na seller and a buyer country. A customer-specific rule wins over the rule for all customers; rules with the same\ncategory, customer and countries never overlap in time."},"WithholdingTaxCategory":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax category.","format":"int32"},"name":{"type":"string","description":"Name of the withholding tax category, unique within your organization.","nullable":true},"description":{"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax category of your organization: the kind of income an offer produces\n(e.g. software license, equipment rental, technical service). Withholding tax rules set the rate per country."},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/rules":{"post":{"tags":["Billing | Withholding Tax"],"summary":"Create a withholding tax rule for your organization.","description":"The category must be one of your organization; the customer, when set, must be a customer your organization bills.","requestBody":{"description":"Category, optional customer, seller and buyer country, rate, agreement, invoice note and validity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWithholdingTaxRuleRequest"}}}},"responses":{"201":{"description":"The created withholding tax rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxRule"}}}},"400":{"description":"Bad request: Missing or invalid values, a foreign category or customer, or validTo before validFrom.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: The validity period overlaps another rule for this category, customer and countries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## GET /v1/billing/withholding-tax/rules/{ruleId}

> Get a single withholding tax rule of your organization.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"WithholdingTaxRule":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax rule.","format":"int32"},"category":{"$ref":"#/components/schemas/WithholdingTaxCategory"},"customerId":{"type":"integer","description":"ID of the customer the rule is limited to; null for all customers.","format":"int32","nullable":true},"customerName":{"type":"string","description":"Name of the customer the rule is limited to.","nullable":true},"sourceCountryIso2":{"type":"string","description":"Seller country (ISO 3166-1 alpha-2).","nullable":true},"targetCountryIso2":{"type":"string","description":"Buyer country of the invoice address (ISO 3166-1 alpha-2).","nullable":true},"rate":{"type":"number","description":"Withheld rate in percent.","format":"double"},"agreement":{"$ref":"#/components/schemas/WithholdingTaxAgreement"},"invoiceNote":{"type":"string","description":"Note printed on the invoice when the rule applies.","nullable":true},"validFrom":{"type":"string","description":"First day the rule applies (date of supply).","format":"date-time"},"validTo":{"type":"string","description":"Last day the rule applies; null for open-ended.","format":"date-time","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax rule of your organization: the rate withheld for a category between\na seller and a buyer country. A customer-specific rule wins over the rule for all customers; rules with the same\ncategory, customer and countries never overlap in time."},"WithholdingTaxCategory":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax category.","format":"int32"},"name":{"type":"string","description":"Name of the withholding tax category, unique within your organization.","nullable":true},"description":{"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax category of your organization: the kind of income an offer produces\n(e.g. software license, equipment rental, technical service). Withholding tax rules set the rate per country."},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"WithholdingTaxAgreement":{"enum":["Gross","Net"],"type":"string","description":"How a withholding tax is settled with the customer.\nGross: the invoice is unchanged, only the note is printed. Net: the invoice is grossed up by a surcharge (Rate / (100 - Rate))."},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/rules/{ruleId}":{"get":{"tags":["Billing | Withholding Tax"],"summary":"Get a single withholding tax rule of your organization.","parameters":[{"name":"ruleId","in":"path","description":"ID of the withholding tax rule.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"The withholding tax rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxRule"}}}},"403":{"description":"Forbidden: The rule does not exist, belongs to another organization or access is denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a withholding tax rule of your organization.

> Issued invoices keep their withholding tax values.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/rules/{ruleId}":{"delete":{"tags":["Billing | Withholding Tax"],"summary":"Delete a withholding tax rule of your organization.","description":"Issued invoices keep their withholding tax values.","parameters":[{"name":"ruleId","in":"path","description":"ID of the withholding tax rule.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"204":{"description":"The rule was deleted."},"403":{"description":"Forbidden: The rule does not exist, belongs to another organization or access is denied.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Patch a withholding tax rule of your organization.

> The patched rule is validated as a whole. Issued invoices keep their values; the change applies to invoices created afterwards.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Billing | Withholding Tax"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"WithholdingTaxRulePatchRequest":{"required":["patchDocument"],"type":"object","properties":{"patchDocument":{"$ref":"#/components/schemas/JsonPatchDocument_WithholdingTaxRulePatch"}},"additionalProperties":false,"description":"JSON Patch request for a withholding tax rule."},"JsonPatchDocument_WithholdingTaxRulePatch":{"type":"object","properties":{"operations":{"type":"array","items":{"$ref":"#/components/schemas/Operation_WithholdingTaxRulePatch"},"nullable":true}},"additionalProperties":false},"Operation_WithholdingTaxRulePatch":{"type":"object","properties":{"value":{"nullable":true},"path":{"type":"string","nullable":true},"op":{"type":"string","nullable":true},"from":{"type":"string","nullable":true}},"additionalProperties":false},"WithholdingTaxRule":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax rule.","format":"int32"},"category":{"$ref":"#/components/schemas/WithholdingTaxCategory"},"customerId":{"type":"integer","description":"ID of the customer the rule is limited to; null for all customers.","format":"int32","nullable":true},"customerName":{"type":"string","description":"Name of the customer the rule is limited to.","nullable":true},"sourceCountryIso2":{"type":"string","description":"Seller country (ISO 3166-1 alpha-2).","nullable":true},"targetCountryIso2":{"type":"string","description":"Buyer country of the invoice address (ISO 3166-1 alpha-2).","nullable":true},"rate":{"type":"number","description":"Withheld rate in percent.","format":"double"},"agreement":{"$ref":"#/components/schemas/WithholdingTaxAgreement"},"invoiceNote":{"type":"string","description":"Note printed on the invoice when the rule applies.","nullable":true},"validFrom":{"type":"string","description":"First day the rule applies (date of supply).","format":"date-time"},"validTo":{"type":"string","description":"Last day the rule applies; null for open-ended.","format":"date-time","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax rule of your organization: the rate withheld for a category between\na seller and a buyer country. A customer-specific rule wins over the rule for all customers; rules with the same\ncategory, customer and countries never overlap in time."},"WithholdingTaxCategory":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"ID of the withholding tax category.","format":"int32"},"name":{"type":"string","description":"Name of the withholding tax category, unique within your organization.","nullable":true},"description":{"type":"string","description":"Description of the withholding tax category, e.g. which kind of income it covers.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"HATEOAS representation of a withholding tax category of your organization: the kind of income an offer produces\n(e.g. software license, equipment rental, technical service). Withholding tax rules set the rate per country."},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"WithholdingTaxAgreement":{"enum":["Gross","Net"],"type":"string","description":"How a withholding tax is settled with the customer.\nGross: the invoice is unchanged, only the note is printed. Net: the invoice is grossed up by a surcharge (Rate / (100 - Rate))."},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/billing/withholding-tax/rules/{ruleId}":{"patch":{"tags":["Billing | Withholding Tax"],"summary":"Patch a withholding tax rule of your organization.","description":"The patched rule is validated as a whole. Issued invoices keep their values; the change applies to invoices created afterwards.","parameters":[{"name":"ruleId","in":"path","description":"ID of the withholding tax rule.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The patch request containing the JSON Patch document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxRulePatchRequest"}}}},"responses":{"200":{"description":"The updated withholding tax rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithholdingTaxRule"}}}},"400":{"description":"Bad request: Invalid patch or values, a foreign category or customer, or validTo before validFrom.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: The rule does not exist, belongs to another organization or access is denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: The validity period overlaps another rule for this category, customer and countries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://hub.equipme.io/development/api-reference-app/billing-or-withholding-tax.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
