Taxes
Taxes
Tax rate management with support for historical rate changes. Each tax can have multiple rates with different valid_from dates to track rate changes over time.
The Taxe object
Attributes
Classification for API tax lookups (e.g., "standard", "reduced", "zero"). Unique per entity. Can be used instead of rate when creating documents.
Whether this is the default tax for new documents. Only one tax per entity can be default.
Create a new tax
/taxesCreate a new tax with one or more tax rates.
Each rate can specify a valid_from date to track historical changes (defaults to 1970-01-01 if not provided).
Rates are automatically sorted by valid_from date (newest first).
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Body parameters
Classification for API tax lookups (e.g., "standard", "reduced", "zero"). Unique per entity. Can be used instead of rate when creating documents.
Whether this is the default tax for new documents. Only one tax per entity can be default.
Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.
curl -X POST "https://eu.spaceinvoices.com/taxes" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-entity-id: YOUR_ENTITY_ID" \
-H "Content-Type: application/json" \
-d '{
"tax_rates": [
{
"rate": 22
}
]
}'Returns
Classification for API tax lookups (e.g., "standard", "reduced", "zero"). Unique per entity. Can be used instead of rate when creating documents.
Whether this is the default tax for new documents. Only one tax per entity can be default.
{
"id": "tax_6595a27b5d35015c3ef0c3fd",
"name": "22%",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"tax_rates": [
{
"rate": 22,
"valid_from": "1970-01-01T00:00:00.000Z"
}
],
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-01-01T00:00:00.000Z",
"deleted_at": null
}List all taxes
/taxesRetrieve a paginated list of taxes with optional filtering and sorting. Supports cursor-based pagination, flexible JSON querying with MongoDB-style operators, and sorting. Each tax may contain multiple historical rates.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Number of results per request.
Default: 10
Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.
Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.
Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.
Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with - for descending order. When paginating, reuse cursors only with the same effective ordering.
JSON query object for filtering results. Supports MongoDB-style operators.
Supported operators:
- equals or direct value - Exact match (default)
- gte - Greater than or equal
- lte - Less than or equal
- gt - Greater than
- lt - Less than
- in - Value in array
- notIn - Value not in array
- contains - String contains (case-insensitive)
- startsWith - String starts with
- endsWith - String ends with
- between - Value between two numbers/dates [min, max]
Allowed fields: id, name, is_default, created_at, updated_at
Examples:
- {"total": {"gte": 1000}} - Invoices over 1000
- {"customer.name": {"contains": "Acme"}} - Customer name contains "Acme"
- {"date": {"between": ["2025-01-01", "2025-12-31"]}} - Date range
Full-text search query to filter results across multiple fields.
Searches are case-insensitive and match partial strings.
Searches across all text fields including names, descriptions, addresses, and metadata values.
When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.
curl "https://eu.spaceinvoices.com/taxes" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-entity-id: YOUR_ENTITY_ID"Returns
{
"data": [
{
"id": "tax_6595a27b5d35015c3ef0c3fd",
"name": "22%",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"tax_rates": [
{
"rate": 22,
"valid_from": "1970-01-01T00:00:00.000Z"
}
],
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-01-01T00:00:00.000Z",
"deleted_at": null
},
{
"id": "tax_6595a27b5d35015c3ef0c3fe",
"name": "Standard VAT",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"tax_rates": [
{
"rate": 22,
"valid_from": "1970-01-01T00:00:00.000Z"
}
],
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-01-01T00:00:00.000Z",
"deleted_at": null
}
],
"pagination": {
"total": 2,
"next_cursor": null,
"prev_cursor": null,
"has_more": false
}
}Add new tax rate(s)
/taxes/{id}Add one or more new tax rates to an existing tax.
New rates are merged with existing rates and automatically sorted by valid_from date (newest first).
Use this to track historical tax rate changes.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier
Body parameters
Set to true to make this the default tax (unsets other defaults)
curl -X PATCH "https://eu.spaceinvoices.com/taxes/{id}" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-entity-id: YOUR_ENTITY_ID" \
-H "Content-Type: application/json" \
-d '{
"tax_rates": [
{
"rate": 25,
"valid_from": "2025-01-01T00:00:00.000Z"
}
]
}'Returns
Classification for API tax lookups (e.g., "standard", "reduced", "zero"). Unique per entity. Can be used instead of rate when creating documents.
Whether this is the default tax for new documents. Only one tax per entity can be default.
{
"id": "tax_6595a27b5d35015c3ef0c3fd",
"name": "22%",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"tax_rates": [
{
"rate": 25,
"valid_from": "2025-01-01T00:00:00.000Z"
},
{
"rate": 22,
"valid_from": "2024-01-01T00:00:00.000Z"
},
{
"rate": 20,
"valid_from": "2020-01-01T00:00:00.000Z"
}
],
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"deleted_at": null
}Replace tax rates
/taxes/{id}Replace all tax rates on a tax with a new set of rates.
This completely replaces the existing tax_rates array.
Use this when you need to remove rates or completely restructure the rate history.
Optionally update the name as well.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier
Body parameters
Classification for API tax lookups (e.g., "standard", "reduced", "zero"). Unique per entity. Can be used instead of rate when creating documents.
Whether this is the default tax for new documents. Only one tax per entity can be default.
Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.
curl -X PUT "https://eu.spaceinvoices.com/taxes/{id}" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-entity-id: YOUR_ENTITY_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated VAT",
"tax_rates": [
{
"rate": 21,
"valid_from": "2025-01-01T00:00:00.000Z"
},
{
"rate": 19,
"valid_from": "2020-01-01T00:00:00.000Z"
}
],
"metadata": {
"category": "vat",
"region": "EU"
}
}'Returns
Classification for API tax lookups (e.g., "standard", "reduced", "zero"). Unique per entity. Can be used instead of rate when creating documents.
Whether this is the default tax for new documents. Only one tax per entity can be default.
{
"id": "tax_6595a27b5d35015c3ef0c3fd",
"name": "Updated VAT",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"tax_rates": [
{
"rate": 21,
"valid_from": "2025-01-01T00:00:00.000Z"
},
{
"rate": 19,
"valid_from": "2020-01-01T00:00:00.000Z"
}
],
"metadata": {
"category": "vat",
"region": "EU"
},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"deleted_at": null
}Delete a tax
/taxes/{id}Soft delete a tax. The tax will be moved to the trash and can be restored later.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier
curl -X DELETE "https://eu.spaceinvoices.com/taxes/{id}" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-entity-id: YOUR_ENTITY_ID"Permanently delete a tax
/taxes/{id}/permanentPermanently delete a soft-deleted tax. Only taxes in the trash can be permanently deleted.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier
curl -X DELETE "https://eu.spaceinvoices.com/taxes/{id}/permanent" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-entity-id: YOUR_ENTITY_ID"Restore a deleted tax
/taxes/{id}/restoreRestore a soft-deleted tax from the trash.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier
curl -X POST "https://eu.spaceinvoices.com/taxes/{id}/restore" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-entity-id: YOUR_ENTITY_ID"Returns
Classification for API tax lookups (e.g., "standard", "reduced", "zero"). Unique per entity. Can be used instead of rate when creating documents.
Whether this is the default tax for new documents. Only one tax per entity can be default.
{
"id": "tax_6595a27b5d35015c3ef0c3fd",
"name": "22%",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"tax_rates": [
{
"rate": 22,
"valid_from": "1970-01-01T00:00:00.000Z"
}
],
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-01-01T00:00:00.000Z",
"deleted_at": null
}