Carrier Accounts

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

List Carrier Accounts

GET/api/carrier-accounts

List all carrier accounts for the organization.

Requiredcarrier-accounts:read

Returns a paginated list of carrier accounts with their status and carrier details. Credentials 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`, `usps`, `dhl`, `ontrac`


curl -X GET "https://api.orderly.dev/api/carrier-accounts?carrier=fedex" \
  -H "Authorization: Bearer ord_sk_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "name": "FedEx Production",
      "carrier": "fedex",
      "account_number": "****5678",
      "status": "verified",
      "capabilities": ["labels", "rates", "tracking", "pickups"],
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1, "hasMore": false }
}

Get Carrier Account

GET/api/carrier-accounts/:id

Retrieve a single carrier account by ID.

Requiredcarrier-accounts:read

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


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

Create Carrier Account

POST/api/carrier-accounts

Requiredcarrier-accounts:write

Creates a new carrier account with the provided credentials. Some carriers require a verification step after creation.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name
`carrier`	string	Yes	Carrier code: `fedex`, `ups`, `usps`, `dhl`, `ontrac`
`credentials`	object	Yes	Carrier-specific credentials
`settings`	object	No	Additional carrier settings (e.g., default packaging)


curl -X POST "https://api.orderly.dev/api/carrier-accounts" \
  -H "Authorization: Bearer ord_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FedEx Production",
    "carrier": "fedex",
    "credentials": {
      "account_number": "123456789",
      "api_key": "...",
      "secret_key": "..."
    }
  }'

Update Carrier Account

PATCH/api/carrier-accounts/:id

Update a carrier account's name, credentials, or settings.

Requiredcarrier-accounts:write

Updates a carrier account. Changing credentials may require re-verification.


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

Delete Carrier Account

DELETE/api/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.dev/api/carrier-accounts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ord_sk_..."

Verify Carrier Account (MFA)

POST/api/carrier-accounts/:id/verify

Complete MFA verification for a carrier account.

Requiredcarrier-accounts:write

Some carriers (e.g., FedEx) require multi-factor authentication after initial setup. This endpoint submits the verification code to complete the process.

Request Body

Field	Type	Required	Description
`code`	string	Yes	MFA verification code


curl -X POST "https://api.orderly.dev/api/carrier-accounts/550e8400-e29b-41d4-a716-446655440000/verify" \
  -H "Authorization: Bearer ord_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Response


{
  "data": {
    "id": "uuid",
    "status": "verified",
    "verified_at": "2026-01-15T10:30:00Z"
  }
}