> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Tax Details

> Set the tax and legal-entity details for a space

# 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](/api-reference/spaces/create-space))
and configure each seller's tax identity here, so every sale is billed and
receipted under the correct entity.

Requires the `spaces:write` scope.

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

## Path Parameters

<ParamField path="spaceIdentifier" type="string" required>
  The space's `identifier` (its slug).
</ParamField>

## Request Body

<ParamField body="tax_type" type="string">
  `VAT` or `Sales Tax`.
</ParamField>

<ParamField body="vat_number" type="string">
  The legal entity's VAT / tax registration number.
</ParamField>

<ParamField body="vat_rate" type="number">
  Tax rate as a percentage, `0`–`100` (e.g. `22` for Italy's 22% VAT).
</ParamField>

<ParamField body="legal_entity_name" type="string">
  Registered legal entity name that appears on receipts.
</ParamField>

<ParamField body="legal_entity_address" type="string">
  Registered legal entity address that appears on receipts.
</ParamField>

<ParamField body="country" type="string">
  Country of the legal entity (ISO code or name).
</ParamField>

<ParamField body="is_eu" type="boolean">
  Whether the entity is in the EU (affects VAT handling).
</ParamField>

<ParamField body="is_valid_vat_number" type="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.
</ParamField>

<ParamField body="notes_on_receipts" type="string">
  Free-text note printed on this space's receipts.
</ParamField>

<ParamField body="email" type="string">
  Optional. Updates the space's contact email (stored on the space, not inside
  `tax_details`).
</ParamField>

## Response

Returns the updated space — same schema as
[Get Space](/api-reference/spaces/get-space) — with the new `tax_details`.

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Validation failed",
    "details": { "fieldErrors": { "vat_rate": ["Number must be less than or equal to 100"] } }
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Space not found"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "insufficient_scope",
    "message": "This API key does not have 'write' access to 'spaces'.",
    "required_scope": "spaces:write"
  }
  ```
</ResponseExample>