curl -X PUT \
-H "X-API-KEY: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"tax_type": "VAT",
"vat_number": "IT12345678901",
"vat_rate": 22,
"legal_entity_name": "ACME Milan SRL",
"legal_entity_address": "Via Roma 1, 20121 Milano",
"country": "IT",
"is_eu": true,
"notes_on_receipts": "Grazie per il tuo acquisto"
}' \
"https://www.gomry.com/api/v1/spaces/milan/tax-details"
{
"data": {
"id": "AbCdEfGhIjKlMnOpQrSt",
"identifier": "milan",
"name": "Milan",
"status": "active",
"tax_details": {
"tax_type": "VAT",
"vat_number": "IT12345678901",
"vat_rate": 22,
"legal_entity_name": "ACME Milan SRL",
"legal_entity_address": "Via Roma 1, 20121 Milano",
"country": "IT",
"is_eu": true,
"is_valid_vat_number": false,
"notes_on_receipts": "Grazie per il tuo acquisto"
},
"created_at": "2025-03-01T10:00:00.000Z",
"updated_at": "2025-07-15T12:30:00.000Z"
}
}
{
"error": "Validation failed",
"details": { "fieldErrors": { "vat_rate": ["Number must be less than or equal to 100"] } }
}
{
"error": "Space not found"
}
{
"error": "insufficient_scope",
"message": "This API key does not have 'write' access to 'spaces'.",
"required_scope": "spaces:write"
}
Spaces
Set Tax Details
Set the tax and legal-entity details for a space
PUT
/
spaces
/
{spaceIdentifier}
/
tax-details
curl -X PUT \
-H "X-API-KEY: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"tax_type": "VAT",
"vat_number": "IT12345678901",
"vat_rate": 22,
"legal_entity_name": "ACME Milan SRL",
"legal_entity_address": "Via Roma 1, 20121 Milano",
"country": "IT",
"is_eu": true,
"notes_on_receipts": "Grazie per il tuo acquisto"
}' \
"https://www.gomry.com/api/v1/spaces/milan/tax-details"
{
"data": {
"id": "AbCdEfGhIjKlMnOpQrSt",
"identifier": "milan",
"name": "Milan",
"status": "active",
"tax_details": {
"tax_type": "VAT",
"vat_number": "IT12345678901",
"vat_rate": 22,
"legal_entity_name": "ACME Milan SRL",
"legal_entity_address": "Via Roma 1, 20121 Milano",
"country": "IT",
"is_eu": true,
"is_valid_vat_number": false,
"notes_on_receipts": "Grazie per il tuo acquisto"
},
"created_at": "2025-03-01T10:00:00.000Z",
"updated_at": "2025-07-15T12:30:00.000Z"
}
}
{
"error": "Validation failed",
"details": { "fieldErrors": { "vat_rate": ["Number must be less than or equal to 100"] } }
}
{
"error": "Space not found"
}
{
"error": "insufficient_scope",
"message": "This API key does not have 'write' access to 'spaces'.",
"required_scope": "spaces:write"
}
Set Tax Details
Sets the tax / legal-entity details for a space: the legal entity name and address, VAT number and rate, tax type, country, and receipt notes applied to that space’s sales and receipts. This is the merchant-of-record knob. A marketplace using Gomry as merchant of record can provision one space per seller (Create Space) and configure each seller’s tax identity here, so every sale is billed and receipted under the correct entity. Requires thespaces:write scope.
This endpoint uses PUT (full replace) semantics: the request replaces the
entire
tax_details object. Any field you omit is reset to its default (empty
string / 0 / false). Send the complete set of values you want each time.This capability is intentionally not exposed through the AI assistant (Aven)
or the MCP server — tax identity affects what buyers are charged and what their
receipts say, so it is changed only through this explicitly-scoped API key
endpoint or the dashboard.
GENERAL has no persisted document and therefore no
tax details.Path Parameters
string
required
The space’s
identifier (its slug).Request Body
string
VAT or Sales Tax.string
The legal entity’s VAT / tax registration number.
number
Tax rate as a percentage,
0–100 (e.g. 22 for Italy’s 22% VAT).string
Registered legal entity name that appears on receipts.
string
Registered legal entity address that appears on receipts.
string
Country of the legal entity (ISO code or name).
boolean
Whether the entity is in the EU (affects VAT handling).
boolean
Whether the VAT number has been validated. You may set this if you validate
externally; Gomry does not re-run VIES validation on this endpoint.
string
Free-text note printed on this space’s receipts.
string
Optional. Updates the space’s contact email (stored on the space, not inside
tax_details).Response
Returns the updated space — same schema as Get Space — with the newtax_details.
curl -X PUT \
-H "X-API-KEY: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"tax_type": "VAT",
"vat_number": "IT12345678901",
"vat_rate": 22,
"legal_entity_name": "ACME Milan SRL",
"legal_entity_address": "Via Roma 1, 20121 Milano",
"country": "IT",
"is_eu": true,
"notes_on_receipts": "Grazie per il tuo acquisto"
}' \
"https://www.gomry.com/api/v1/spaces/milan/tax-details"
{
"data": {
"id": "AbCdEfGhIjKlMnOpQrSt",
"identifier": "milan",
"name": "Milan",
"status": "active",
"tax_details": {
"tax_type": "VAT",
"vat_number": "IT12345678901",
"vat_rate": 22,
"legal_entity_name": "ACME Milan SRL",
"legal_entity_address": "Via Roma 1, 20121 Milano",
"country": "IT",
"is_eu": true,
"is_valid_vat_number": false,
"notes_on_receipts": "Grazie per il tuo acquisto"
},
"created_at": "2025-03-01T10:00:00.000Z",
"updated_at": "2025-07-15T12:30:00.000Z"
}
}
{
"error": "Validation failed",
"details": { "fieldErrors": { "vat_rate": ["Number must be less than or equal to 100"] } }
}
{
"error": "Space not found"
}
{
"error": "insufficient_scope",
"message": "This API key does not have 'write' access to 'spaces'.",
"required_scope": "spaces:write"
}