Get Started

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.

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

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

{
  "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:

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:

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

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 for supplier setup and Shipping Options for the shared shipping vocabulary.