Skip to main content

SDK v2 Migration Guide

Gateway SDK v2 is the organization/location rename release.

What changed​

  • LocationsApi is now the primary surface for location records.
  • OrganizationsApi owns organization-scoped resources and credential-profile lifecycle.
  • MerchantsApi remains available as a deprecated compatibility alias.
  • New code should prefer organizationId and locationId terminology in app-level models and routes.

Kotlin migration​

Replace:

  • GatewayAdminClient.merchants

With:

  • GatewayAdminClient.locations
  • GatewayAdminClient.organizations

Notes:

  • MerchantsApi still delegates to LocationsApi.
  • Existing wire-level merchantId values still identify the concrete location row.

TypeScript migration​

Replace:

  • client.merchants

With:

  • client.locations
  • client.organizations

Notes:

  • Compatibility aliases remain available for the current cutover window.
  • New org-scoped features should land on OrganizationsApi or LocationsApi, not on MerchantsApi.

Explicit compatibility promises​

Safe statements:

  • MerchantsApi still delegates to the location-backed runtime path
  • existing merchantId fields still carry the concrete location identifier on the wire
  • new app state should prefer organizationId and locationId naming

Unsafe statements:

  • that MerchantsApi is still the preferred surface for greenfield features
  • that every wire field has already been renamed away from merchantId
  • that downstream apps should keep introducing new merchant* state just because the compatibility alias still exists

Closeout checklist​

  • SDK examples prefer locations / organizations over merchants
  • docs explain where legacy merchantId values still remain on the wire
  • compatibility aliases are described as transitional, not normative

Conceptual model​

See Organizations and Locations for the access-control and inheritance model behind the rename.

Source-of-truth draft​

The longer-form migration draft also lives in-repo at: