# Supplier carriers

Find carrier suppliers and maintain DOT numbers, MC numbers, and saved operating status.

Canonical HTML: https://developer.shelfcycle.com/guides/supplier-carriers

Find carrier suppliers and maintain their DOT number, MC number, and saved operating status alongside the supplier records your team already uses.

A supplier becomes a carrier when it has a carrier profile. Create the supplier first through `POST /suppliers`, then add its carrier profile. Supplier finder rows, detail reads, and create or update responses include `carrierProfile`, or `null` when no profile exists.

## Access

- `GET /suppliers?carrier=true` uses `suppliers:read`.
- `GET /suppliers/{id}/carrier-profile` accepts either `suppliers:read` or `search:read`, together with current Supplier viewing access.
- `PUT` and `DELETE /suppliers/{id}/carrier-profile` use `suppliers:write`, together with current Supplier update access.

`GET /me` reports available carrier-profile actions under `effectiveCapabilities.suppliers.carrierProfiles`. Preview the exact change with `dryRun=true` when your workflow needs a readiness check before saving.

## Find carrier suppliers

`carrier=true` finds suppliers with profiles; `carrier=false` finds suppliers without them. Either value is a sufficient filter by itself, and omitting `carrier` leaves carrier status unrestricted.

```bash
curl "$SHELFCYCLE_API_BASE_URL/suppliers?carrier=true&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Use `carrierProfile` on each row to review carrier details alongside supplier identity. Continue with the exact returned `meta.nextCursor` alone.

## Read the selected profile

```bash
curl "$SHELFCYCLE_API_BASE_URL/suppliers/supplier-id/carrier-profile" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

```json
{
  "data": {
    "supplierId": "supplier-id",
    "dotNumber": "1234567",
    "mcNumber": "MC-765432",
    "operatingStatus": "ACTIVE",
    "updatedAt": "2026-10-13T14:00:00.000Z"
  }
}
```

The response is `data: null` when the supplier has no carrier profile. Archived suppliers remain readable.

Use the carrier profile's own `updatedAt` for carrier changes. The supplier's `updatedAt` belongs to supplier profile changes; each timestamp applies to its own record.

## Create a carrier profile

Send all three fields on every PUT. Each can be `null`; `dotNumber` contains digits only when supplied. `operatingStatus` accepts `ACTIVE`, `AUTHORIZED_FOR_PROPERTY`, `NOT_AUTHORIZED`, or `OUT_OF_SERVICE`. It describes the saved value in ShelfCycle.

When the profile is absent, create it without `If-Match`:

```bash
curl "$SHELFCYCLE_API_BASE_URL/suppliers/supplier-id/carrier-profile" \
  -X PUT \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dotNumber": "1234567",
    "mcNumber": "MC-765432",
    "operatingStatus": "ACTIVE"
  }'
```

A new profile returns `201` with `status: "created"`. Repeating identical values returns `200` with `status: "unchanged"`, including when the first response was lost. A current request with different values needs the profile's latest `If-Match`.

## Replace carrier details

PUT replaces the complete profile. Include every value to retain and use `null` to clear a field. Read the current profile first, then send its exact `updatedAt` as `If-Match`:

```bash
curl "$SHELFCYCLE_API_BASE_URL/suppliers/supplier-id/carrier-profile" \
  -X PUT \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2026-10-13T14:00:00.000Z" \
  -d '{
    "dotNumber": "1234567",
    "mcNumber": null,
    "operatingStatus": "AUTHORIZED_FOR_PROPERTY"
  }'
```

A saved change returns `200` with `status: "updated"`. Identical values return `unchanged` regardless of `If-Match`. A changed request with a missing or outdated timestamp returns `409 stale_record`; read the profile again and review the newer values before retrying.

If a profile was removed after your read, sending its old `If-Match` returns `409 stale_record`. Read again before intentionally creating a new profile without that header.

Changing the saved operating status clears its prior checked date in the app, so the new status can be reviewed on its own.

## Preview a change

Add `?dryRun=true` to PUT or DELETE. For an update or removal, use the current profile timestamp just as you would when applying it. The response reports readiness and `impactAnalysis.currentUpdatedAt`; review it, then send the same intended change without `dryRun=true`.

Readiness checks use `supplier_carrier_profiles.put` and `supplier_carrier_profiles.delete`. When the status would change, `impactAnalysis.clearsOperatingStatusCheckedDate` identifies that effect. Archived suppliers return `422 archived_record` on writes.

## Remove a carrier profile

```bash
curl "$SHELFCYCLE_API_BASE_URL/suppliers/supplier-id/carrier-profile" \
  -X DELETE \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "If-Match: 2026-10-13T14:00:00.000Z"
```

Removal returns `200` with `status: "deleted"`, `changed: true`, and `carrierProfile: null`. An already-absent profile returns `status: "unchanged"`. With an existing profile, an outdated or missing `If-Match` returns `409 stale_record`.

The supplier leaves the supplier-backed order carrier choices and their carrier contact prefill. Its supplier record, documents, and carrier names already saved on orders stay intact. Recreate the carrier profile when the supplier should become a carrier again.

Successful writes return a `supplier_carrier_profile_receipt` with `status`, `changed`, `carrierProfile`, and a `verification` GET path. Use that path to confirm the current profile.

## Carrier choices and Shipping Options

Order carrier choices combine active Shipping Option carrier names with active supplier carriers. Matching names use the supplier's choice and contact details. A Shipping Option previously archived during conversion stays archived when the supplier's carrier profile is removed; restore that option separately if it should return.

Maintain a supplier carrier within the selected organization. See [Company profiles](/guides/company-profiles) for supplier setup and [Shipping Options](/guides/shipping-options) for the shared shipping vocabulary.