Overview
Under Workspace Settings -> Company & Regional (/settings/workspace/general, /settings/workspace/company, and /settings/workspace/regional), workspace administrators configure the corporate identity (Account Settings API), billing tax profile (PUT /api/v1/billing/settings & PUT /api/v1/billing/tax-profile), and regional formatting defaults shared across all pass templates, public download portals, analytics time-series rollups, and Stripe tax invoices.
Workspace Metadata & Regional Configuration Flow
Important: Always verify and save your Company Legal Name, Billing Address, and VAT / Tax ID (
PUT /api/v1/billing/settings) before executing a paid plan upgrade or renewal. Generated PDF tax invoices (GET /api/v1/billing/invoices/:id/download) are immutable once finalized by the billing engine.
Workspace Profile (Account Settings API) & Tax Profile (Billing API)
The base customer resource (GET /api/v1/customer/:id and PUT /api/v1/customer/:id, validated strictly against request payload with forbidNonWhitelisted) manages core workspace identity, while PUT /api/v1/billing/settings stores VAT/tax invoicing metadata (request payload):
| Field | Endpoint (DTO) | Operational Impact | |
|---|---|---|---|
name / companyName | PUT /api/v1/customer/:id (request payload) | Workspace display name and corporate organization name printed on passes. | |
email / notificationEmails | PUT /api/v1/customer/:id | Primary workspace contact email and operational alert recipient list. | |
street, zipCode, city, state, country | PUT /api/v1/customer/:id | Registered office address fields (street2 optional). | |
subdomain / domain / logo / icon | PUT /api/v1/customer/:id | Workspace slug, custom domain binding, and logo/icon URLs. | |
exportFormat (`'legacy' | 'new'`) | PUT /api/v1/customer/:id | Default CSV column layout for workspace exports. |
taxId, vatNumber, billingEmail, address | PUT /api/v1/billing/settings (request payload) | EU VAT number (e.g. DE301928374), tax ID, and invoice recipient metadata printed on Stripe PDF invoices. |
Updating Workspace Profile via API (PUT /api/v1/customer/:id)
PUT /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"name": "Phenix Hospitality Europe",
"companyName": "Phenix Hospitality GmbH",
"email": "passes@phenix-hospitality.example.com",
"street": "Friedrichstrasse 114A",
"zipCode": "10117",
"city": "Berlin",
"country": "DE",
"exportFormat": "new"
}
Response Payload (200 OK)
{
"id": "cus_89a12b34-56c7-4d89-9e01-23456789abcd",
"name": "Phenix Hospitality Europe",
"companyName": "Phenix Hospitality GmbH",
"email": "passes@phenix-hospitality.example.com",
"street": "Friedrichstrasse 114A",
"city": "Berlin",
"zipCode": "10117",
"country": "DE",
"exportFormat": "new",
"isActive": true,
"updatedAt": "2026-11-16T09:33:12.000Z"
}
Workspace Regional Settings (request payload)
Regional settings (GET /api/v1/customer/:customerId/regional-settings and PUT /api/v1/customer/:customerId/regional-settings) define the temporal, currency, and localization defaults via request payload:
-
1
timezone(IANA string, max 50 chars): Determines midnight cutoffs for daily analytics buckets (GET /api/v1/analytics), workflow schedules, andOncePerDayRulescanner cooldown resets. -
2
countryIso(ISO 3166-1 alpha-2, e.g.,"DE"): Primary country jurisdiction for the workspace. -
3
defaultCurrency(ISO 4217 3-letter code, e.g.,"EUR"): Default denomination forPREPAID_CARDstored-value ledgers and retail POS redemptions (POST /v1/pos/redeem). -
4
defaultLocale(BCP-47 tag, e.g.,"de-DE"): Fallback language served on public download pages (/d/:slug,/s/:token) and transactional emails. -
5
dataResidencyRegion(optional string, e.g.,"eu-central-1"): Workspace data residency metadata.
Updating Regional Settings via API
PUT /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd/regional-settings HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"timezone": "Europe/Berlin",
"countryIso": "DE",
"defaultCurrency": "EUR",
"defaultLocale": "de-DE",
"dataResidencyRegion": "eu-central-1"
}
{
"customerId": "cus_89a12b34-56c7-4d89-9e01-23456789abcd",
"timezone": "Europe/Berlin",
"countryIso": "DE",
"defaultCurrency": "EUR",
"defaultLocale": "de-DE",
"dataResidencyRegion": "eu-central-1",
"updatedAt": "2026-11-16T09:34:00.000Z"
}
Related Documentation
-
Configure custom vanity domains (
CNAME) and branded SMTP/DKIM email senders in Custom Branding & White-Label Options. -
Download VAT-compliant PDF invoices in Invoices & Billing History.
-
Manage multi-workspace agency hierarchies in Multi-Client Management.
