Carrier-Account Ownership Model

Carrier Account Ownership Types

When you retrieve carrier accounts via GET /api/v1/carrierAccounts, the response is scoped by the x-tenant-id header you provide. Every carrier account returned is valid and available for use by that tenant — you should store and offer all of them, regardless of ownership type.

Each carrier account includes an ownershipType field with one of three values:

PLATFORM — Managed by iDrive and shared across tenants. Platform accounts are configured at the 3PL level, meaning all brands under a given 3PL have access to the same set of platform carrier accounts. These represent iDrive's negotiated rates and carrier relationships.

PARTNER — Carrier accounts brought into the system by a 3PL partner (sometimes referred to as "Bring Your Own Carrier" or BYOC). These are owned and managed at the 3PL partner level rather than by iDrive or an individual brand. 3PLs may allow their brands to ship on their partner level carrier account if they want.

BRAND — Carrier accounts that a brand has brought into the system themselves (sometimes referred to as "Bring Your Own Carrier" or BYOC). These are specific to the individual brand's tenant and reflect that brand's own carrier relationship and pricing.

	`PLATFORM`	`PARTNER`	`BRAND`
Managed by	iDrive	3PL partner	Individual brand
Configured at	iDrive level	3PL partner level	Brand tenant level
Scope of access	All brands under that 3PL	3PL controls; can extend to brands	That brand only
Rate source	iDrive's negotiated rates	3PL's own carrier contracts	Brand's own carrier contracts
BYOC?	No	Yes	Yes
Typical use case	Shared carrier pool with iDrive rate depth	3PL brings preferred carriers across their portfolio	Brand ships on its own negotiated rates

Key Behavior

Use all returned accounts. Do not filter by ownershipType when deciding which carrier accounts to store or present to users. If an account is returned for a given x-tenant-id, it is valid for that tenant.
IDs are unique per tenant. Even when multiple brands share the same underlying platform carrier, each brand receives a distinct carrierAccountId. You can safely use this ID as a unique identifier without concern for collisions across tenants.

Example Request

GET /api/v1/carrierAccounts
Headers:
  x-tenant-id: {brandTenantId}

The response will include all carrier accounts — platform, partner, and brand — that are available to the specified tenant.