Locations

Manage merchant locations with country-specific fiscal configurations. All endpoints require authentication.

Create a location

POST /v1/locations

Creates a new merchant location for the authenticated account. The country field determines which validations apply.

Request body

Field	Type	Required	Description
name	string	Yes	Location name (max 255 chars)
country	string	Yes	ISO 3166-1 alpha-2 code (ES, IT, FR)
address	string	No	Physical address (max 500 chars)
tax_id	string	No	Tax identification number (max 50 chars)
country_config	object	Varies	Country-specific config. Required for Spain.

Examples

Spanish location with TicketBAI:

curl -X POST https://api.fiscalapi.com/v1/locations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "name": "Madrid Office",
    "country": "ES",
    "address": "Calle Gran Vía 1, 28013 Madrid",
    "tax_id": "B12345674",
    "country_config": {
      "system": "ticketbai",
      "territory_code": "48"
    }
  }'

French location (minimal):

curl -X POST https://api.fiscalapi.com/v1/locations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "name": "Paris Store",
    "country": "FR",
    "address": "10 Rue de Rivoli, 75001 Paris",
    "tax_id": "FR12345678901"
  }'

Response 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Madrid Office",
  "country": "ES",
  "address": "Calle Gran Vía 1, 28013 Madrid",
  "tax_id": "B12345674",
  "country_config": {
    "system": "ticketbai",
    "territory_code": "48"
  },
  "status": "active",
  "created_at": "2026-03-08T12:00:00Z",
  "updated_at": "2026-03-08T12:00:00Z"
}

Errors

Status	Error	Cause
400	Key: 'CreateRequest.Name'...	Missing required field
400	Spain locations require country_config with system field (ticketbai or verifactu)	Missing Spain config
400	Spain country_config.system must be "ticketbai" or "verifactu"	Invalid system value

---

List locations

GET /v1/locations

Returns a paginated list of locations for the authenticated account, ordered by created_at descending.

Query parameters

Parameter	Type	Default	Description
limit	integer	20	Items per page (max 100)
offset	integer	0	Pagination offset (max 10000)
country	string	--	Filter by ISO country code
status	string	--	Filter by active or inactive

Example

# List all locations
curl https://api.fiscalapi.com/v1/locations \
  -H "Authorization: Bearer fsk_test_abc123def456..."

# Filter by country and paginate
curl "https://api.fiscalapi.com/v1/locations?country=ES&limit=10&offset=0" \
  -H "Authorization: Bearer fsk_test_abc123def456..."

Response 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "account_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Madrid Office",
      "country": "ES",
      "address": "Calle Gran Vía 1, 28013 Madrid",
      "tax_id": "B12345674",
      "country_config": {
        "system": "ticketbai",
        "territory_code": "48"
      },
      "status": "active",
      "created_at": "2026-03-08T12:00:00Z",
      "updated_at": "2026-03-08T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

---

Get a location

GET /v1/locations/{id}

Returns a single location by ID, scoped to the authenticated account.

Path parameters

Parameter	Type	Description
id	uuid	Location UUID

Example

curl https://api.fiscalapi.com/v1/locations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer fsk_test_abc123def456..."

Response 200 OK

Returns a Location object.

Errors

Status	Error
404	location not found

---

Update a location

PATCH /v1/locations/{id}

Partially updates a location. Only supplied fields are modified.

info

The country and tax_id fields are immutable and cannot be changed after creation.

Request body

Field	Type	Description
name	string	Updated location name
address	string	Updated address
country_config	object	Updated country-specific config
status	string	active or inactive

Examples

Update name:

curl -X PATCH https://api.fiscalapi.com/v1/locations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{"name": "Madrid HQ"}'

Deactivate location:

curl -X PATCH https://api.fiscalapi.com/v1/locations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{"status": "inactive"}'

Switch fiscalization system:

curl -X PATCH https://api.fiscalapi.com/v1/locations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{"country_config": {"system": "verifactu"}}'

Response 200 OK

Returns the updated Location object.

---

Delete a location

DELETE /v1/locations/{id}

Soft-deletes a location. It will no longer appear in list queries.

Example

curl -X DELETE https://api.fiscalapi.com/v1/locations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer fsk_test_abc123def456..."

Response 204 No Content

No response body.

---

Location object

Field	Type	Description
id	uuid	Location identifier
account_id	uuid	Owning account identifier
name	string	Human-readable name
country	string	ISO 3166-1 alpha-2 country code
address	string	Physical address
tax_id	string	Tax identification number
country_config	object	Country-specific fiscalization config
status	string	active or inactive
cert_expiry	datetime	Certificate expiration (if applicable)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Spain country config

Field	Type	Required	Description
system	string	Yes	ticketbai or verifactu
territory_code	string	No	Territory code (e.g., 01=Alava, 20=Gipuzkoa, 48=Bizkaia)