Carrier Accounts

Carrier accounts represent your shipping carrier credentials (FedEx, UPS, ColdTrack, etc.) used to generate labels, get rates, and schedule pickups. Credentials are encrypted at rest and redacted in all API responses.

Supported carriers: fedex, ups, coldtrack

List Carrier Accounts

GET/api/v1/carrier-accounts

List all carrier accounts for the organization.

Requiredcarrier-accounts:read

Returns a paginated list of carrier accounts with their status and capabilities. Credential values are redacted.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`carrier`	string	Filter by carrier code: `fedex`, `ups`, `coldtrack`
`status`	string	Filter by status: `active`, `inactive`, `error`


curl -X GET "https://api.orderly-hub.com/api/v1/carrier-accounts?carrier=fedex&status=active" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "org_uuid",
      "name": "FedEx Production",
      "carrier": "fedex",
      "credentials": {
        "accountNumber": "********",
        "childKey": "********",
        "childSecret": "********"
      },
      "supportsRating": true,
      "supportsPickup": true,
      "supportsLabels": true,
      "status": "active",
      "isTest": false,
      "metadata": {},
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}

Get Carrier Account

GET/api/v1/carrier-accounts/:id

Retrieve a single carrier account by ID.

Requiredcarrier-accounts:read

Returns the full carrier account details including capabilities and status. Credential values are redacted.


curl -X GET "https://api.orderly-hub.com/api/v1/carrier-accounts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org_uuid",
    "name": "FedEx Production",
    "carrier": "fedex",
    "credentials": {
      "accountNumber": "********",
      "childKey": "********",
      "childSecret": "********"
    },
    "supportsRating": true,
    "supportsPickup": true,
    "supportsLabels": true,
    "status": "active",
    "isTest": false,
    "metadata": {},
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-15T10:30:00Z"
  }
}

Create Carrier Account

POST/api/v1/carrier-accounts

Requiredcarrier-accounts:write

Creates a new carrier account with the provided credentials. Credentials are validated against the carrier-specific schema. Capabilities (rating, labels, pickup) are automatically set based on the carrier type.

For FedEx accounts, use the FedEx Registration flow instead.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name (1-100 characters)
`carrier`	string	Yes	Carrier code: `fedex`, `ups`, `coldtrack`
`credentials`	object	Yes	Carrier-specific credentials
`isTest`	boolean	No	Whether this is a test/sandbox account (default: false)
`metadata`	object	No	Custom key-value metadata


curl -X POST "https://api.orderly-hub.com/api/v1/carrier-accounts" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ColdTrack Production",
    "carrier": "coldtrack",
    "credentials": {
      "apiKey": "ct_live_abc123..."
    },
    "isTest": false
  }'

Response (201 Created)


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org_uuid",
    "name": "ColdTrack Production",
    "carrier": "coldtrack",
    "credentials": {
      "apiKey": "********"
    },
    "supportsRating": true,
    "supportsPickup": false,
    "supportsLabels": false,
    "status": "active",
    "isTest": false,
    "metadata": {},
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z"
  }
}

Update Carrier Account

PATCH/api/v1/carrier-accounts/:id

Update a carrier account's name, credentials, status, or metadata.

Requiredcarrier-accounts:write

Updates a carrier account. When updating credentials, the new values are merged with existing credentials so you only need to send the fields you want to change.

Request Body

Field	Type	Required	Description
`name`	string	No	Display name (1-100 characters)
`credentials`	object	No	Carrier-specific credentials (merged with existing)
`status`	string	No	Set status: `active` or `inactive`
`metadata`	object	No	Custom key-value metadata


curl -X PATCH "https://api.orderly-hub.com/api/v1/carrier-accounts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FedEx Production (Updated)",
    "status": "inactive"
  }'

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org_uuid",
    "name": "FedEx Production (Updated)",
    "carrier": "fedex",
    "credentials": {
      "accountNumber": "********",
      "childKey": "********",
      "childSecret": "********"
    },
    "supportsRating": true,
    "supportsPickup": true,
    "supportsLabels": true,
    "status": "inactive",
    "isTest": false,
    "metadata": {},
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

Delete Carrier Account

DELETE/api/v1/carrier-accounts/:id

Delete a carrier account.

Requiredcarrier-accounts:write

Permanently deletes a carrier account. This does not affect existing shipments that were created with this account.


curl -X DELETE "https://api.orderly-hub.com/api/v1/carrier-accounts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Test Carrier Credentials

POST/api/v1/carrier-accounts/:id/test

Test a carrier account's credentials by making a live API call to the carrier.

Requiredcarrier-accounts:write

Tests the stored credentials against the carrier’s API. If the test succeeds, the account status is set to active and any previous error is cleared. If it fails, the status is set to error with a descriptive error message.


curl -X POST "https://api.orderly-hub.com/api/v1/carrier-accounts/550e8400-e29b-41d4-a716-446655440000/test" \
  -H "Authorization: Bearer oh_..."

Response (success)


{
  "valid": true,
  "error": null
}

Response (failure)


{
  "valid": false,
  "error": "Authentication failed: invalid API key"
}

FedEx Account Registration

FedEx requires a multi-step registration flow with multi-factor authentication (MFA) to link a customer’s FedEx account. The flow is:

Register — Submit account details and receive MFA options
Request PIN — Request a verification PIN via SMS, call, or email
Verify — Submit the PIN or an invoice to complete verification

After successful verification, the carrier account status becomes active and API credentials (childKey/childSecret) are stored encrypted.

Step 1: Register FedEx Account

POST/api/v1/carrier-accounts/fedex/register

Start FedEx account registration and receive MFA options.

Requiredcarrier-accounts:write

Submits the FedEx account number, customer name, and address to initiate account linking. Creates a pending carrier account and returns the available MFA verification options.

If an account with the same FedEx account number already exists for the organization, it will be updated rather than duplicated.

Request Body

Field	Type	Required	Description
`accountNumber`	string	Yes	9-digit FedEx account number
`customerName`	string	Yes	Name on the FedEx account
`address`	object	Yes	Account holder address (see below)

Address object:

Field	Type	Required	Description
`streetLines`	string[]	Yes	Street address lines (at least one)
`city`	string	Yes	City
`stateOrProvinceCode`	string	No	State or province code (e.g., `NY`)
`postalCode`	string	Yes	Postal/ZIP code
`countryCode`	string	Yes	2-letter country code (e.g., `US`)
`residential`	boolean	No	Whether address is residential


curl -X POST "https://api.orderly-hub.com/api/v1/carrier-accounts/fedex/register" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "123456789",
    "customerName": "Acme Corp",
    "address": {
      "streetLines": ["123 Main St"],
      "city": "New York",
      "stateOrProvinceCode": "NY",
      "postalCode": "10001",
      "countryCode": "US"
    }
  }'

Response


{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "mfaOptions": {
    "mfaRequired": true,
    "email": "PU***@A***.COM",
    "phoneNumber": "***-***-4222",
    "options": {
      "invoice": "INVOICE",
      "secureCode": ["SMS", "CALL", "EMAIL"]
    }
  },
  "testModeBypass": false
}

Step 2a: Request FedEx PIN

POST/api/v1/carrier-accounts/fedex/request-pin

Request a verification PIN via SMS, phone call, or email.

Requiredcarrier-accounts:write

After registration, use this endpoint to request a verification PIN sent to the contact method on file with FedEx.

Request Body

Field	Type	Required	Description
`accountId`	string	Yes	Carrier account ID returned from registration
`option`	string	Yes	Delivery method: `SMS`, `CALL`, or `EMAIL`


curl -X POST "https://api.orderly-hub.com/api/v1/carrier-accounts/fedex/request-pin" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "option": "SMS"
  }'

Response


{
  "success": true,
  "message": "PIN sent via SMS"
}

Step 2b: Verify FedEx PIN

POST/api/v1/carrier-accounts/fedex/verify-pin

Submit the verification PIN to complete FedEx account linking.

Requiredcarrier-accounts:write

Submits the PIN received via SMS, call, or email. On success, the carrier account is activated with API credentials for making FedEx API calls on behalf of the linked account.

Request Body

Field	Type	Required	Description
`accountId`	string	Yes	Carrier account ID returned from registration
`pin`	string	Yes	The verification PIN received from FedEx


curl -X POST "https://api.orderly-hub.com/api/v1/carrier-accounts/fedex/verify-pin" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "pin": "123456"
  }'

Response (success)


{
  "verified": true
}

Response (failure)


{
  "verified": false,
  "error": "PIN verification failed"
}

Step 2c: Verify FedEx with Invoice

POST/api/v1/carrier-accounts/fedex/verify-invoice

Verify FedEx account using a recent invoice as an alternative to PIN verification.

Requiredcarrier-accounts:write

An alternative to PIN verification. If the FedEx account has the INVOICE option available in the MFA options, you can verify ownership by providing details from a recent FedEx invoice.

Request Body

Field	Type	Required	Description
`accountId`	string	Yes	Carrier account ID returned from registration
`invoiceInfo`	object	Yes	Invoice details (see below)

Invoice info object:

Field	Type	Required	Description
`invoiceNumber`	string	Yes	FedEx invoice number
`invoiceDate`	string	Yes	Invoice date in `YYYY-MM-DD` format
`invoiceAmount`	number	Yes	Invoice total amount
`currency`	string	No	Currency code (default: `USD`)


curl -X POST "https://api.orderly-hub.com/api/v1/carrier-accounts/fedex/verify-invoice" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceInfo": {
      "invoiceNumber": "INV-2026-001234",
      "invoiceDate": "2026-03-15",
      "invoiceAmount": 1542.87,
      "currency": "USD"
    }
  }'

Response (success)


{
  "verified": true
}

Response (failure)


{
  "verified": false,
  "error": "Invoice verification failed"
}