Organizations and Locations

Gateway’s current tenant model is organization-first:

• Organization is the top-level business boundary.
• Location is an operational endpoint under an organization.
• Legacy merchantId values still exist in parts of the wire format, but they identify the concrete location record.

Data model

Organization
  ├─ owns many Locations
  ├─ owns credential profiles
  ├─ owns org-scoped configs
  │    ├─ tax configs
  │    ├─ gift-card configs
  │    └─ setup-intent defaults
  └─ owns org-scoped business objects
       ├─ gift cards
       ├─ customers
       ├─ products
       └─ subscriptions

Location
  ├─ belongs to exactly one Organization
  ├─ may override selected org defaults
  ├─ carries runtime state such as status / type / credential profile
  └─ is the operational unit used by checkout, in-person, and provisioning flows

Access-control summary

• Platform admins can read and write across organizations and locations.
• Organization-scoped portal users can operate on the organizations they are assigned to and their descendant locations.
• Location-scoped users or OAuth clients are restricted to their explicit location set.
• Internal service callers use Cloud Run IAM plus service-to-service identity and may cross organization boundaries where the workflow requires it.

Inheritance patterns

The rename is not just terminology. Several resources are intentionally organization-scoped with optional location overrides:

• Tax configuration: organization defaults with location-specific overrides where needed.
• Gift cards: redeemable across locations in the same organization.
• Credential profiles: managed at organization scope, then assigned to locations.

Important current caveat:

• the only unresolved runtime gap in this area is gift-card location- restriction enforcement at redemption; modeled rows exist, but runtime redemption is still organization-wide

Credential resolution

Credential selection is runtime, not just data-model structure:

• the gateway first checks for a location-specific credential-profile assignment
• if none exists, it falls back to the organization default profile

Only credential profiles in ACTIVE or ROTATING status are eligible to process transactions. Other statuses remain visible for admin workflow and audit purposes but do not participate in runtime credential resolution.

That pattern keeps external integrators on a small number of stable concepts:

• look up the organization for shared policy
• operate on a location for concrete runtime work
• avoid duplicating org-wide state across every location

SDK shape

The SDKs follow the same split:

• OrganizationsApi for organization-scoped resources
• LocationsApi for concrete location records and operational status
• MerchantsApi as a deprecated compatibility alias

Rename promises and non-promises

Safe statements:

• organization/location terminology is the primary model for new docs and SDK entry points
• merchantId still appears in some request/response fields, but it points at the concrete location record on the wire
• MerchantsApi still works as a compatibility alias during the launch-cutover window

Unsafe statements:

• that MerchantsApi is still the preferred API surface for new work
• that every legacy merchant* label in API payloads has already been renamed
• that every organization limits cross-location gift-card redemption by default even when no restriction rows are configured

For migration details, see SDK v2 Migration Guide.