Skip to content
Help Center Guide · Account & Workspace Settings
3 min readVerified 2026-11-16

Company Settings

Manage organization profile, legal/tax metadata, default brand sender name, and custom domain bindings.

In This Guide

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
WORKSPACE IDENTITY & REGIONAL SETTINGS PROPAGATION
STAGE 01 DASHBOARD / API CONFIGURATION LAYER
Corporate & Legal Identity
GET/ PUT /api/v1/customer/:idPUT/api/v1/billing/settings
companyName, VAT/Tax ID, Address
Regional & Data Residency Settings
`GET / PUT/api/v1/customer/
:customerId/regional-settings`
timezone, countryIso, currency
STAGE 02 DOWNSTREAM SYSTEM CONSUMERS
Billing & Tax Engine
PDF Invoice Headers
Reverse-Charge VAT
Analytics & Mechanics
Daily Bucket Cutoffs
Stored-Value Ledger
Template & PassFlow
Default Currency
Subdomain Routing

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):

FieldEndpoint (DTO)Operational Impact
name / companyNamePUT /api/v1/customer/:id (request payload)Workspace display name and corporate organization name printed on passes.
email / notificationEmailsPUT /api/v1/customer/:idPrimary workspace contact email and operational alert recipient list.
street, zipCode, city, state, countryPUT /api/v1/customer/:idRegistered office address fields (street2 optional).
subdomain / domain / logo / iconPUT /api/v1/customer/:idWorkspace slug, custom domain binding, and logo/icon URLs.
exportFormat (`'legacy''new'`)PUT /api/v1/customer/:idDefault CSV column layout for workspace exports.
taxId, vatNumber, billingEmail, addressPUT /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)

HTTP
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)

JSON
{
  "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. 1
    timezone (IANA string, max 50 chars): Determines midnight cutoffs for daily analytics buckets (GET /api/v1/analytics), workflow schedules, and OncePerDayRule scanner cooldown resets.
  2. 2
    countryIso (ISO 3166-1 alpha-2, e.g., "DE"): Primary country jurisdiction for the workspace.
  3. 3
    defaultCurrency (ISO 4217 3-letter code, e.g., "EUR"): Default denomination for PREPAID_CARD stored-value ledgers and retail POS redemptions (POST /v1/pos/redeem).
  4. 4
    defaultLocale (BCP-47 tag, e.g., "de-DE"): Fallback language served on public download pages (/d/:slug, /s/:token) and transactional emails.
  5. 5
    dataResidencyRegion (optional string, e.g., "eu-central-1"): Workspace data residency metadata.

Updating Regional Settings via API

HTTP
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"
}
JSON
{
  "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"
}

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.