Shipping Options

Keep the freight terms, carriers, FOB terms, freight methods, and border crossing points used by sales and purchasing workflows aligned with connected systems.

Endpoints

GET /me reports current access under effectiveCapabilities.shippingOptions and writeReadiness.shippingOptions. Read and write scopes are separate, so a maintenance workflow can be granted only the access it needs.

Choose the option type

Every option carries one of six stable type values:

Shipping freight terms belong to this directory. Customer and supplier payment terms remain available through GET /payment-terms with Company Reference access.

List and select options

The default request returns active options across all six types. Narrow by type, matching text in q, or an exact externalId when the workflow already has source identity:

curl "$SHELFCYCLE_API_BASE_URL/shipping-options?type=SO_SHIPPING_CARRIER&q=ground" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Shipping setup sync"

Each row returns id, type, value, nullable externalId, nullable archivedAt, and updatedAt. Use includeArchived=true when the workflow intentionally reviews retired choices.

The response metadata reports coverage.total, coverage.returned, and coverage.complete. The directory returns as one bounded result rather than using a continuation cursor. If the returned coverage is narrower than the matching total, add a type, text, or source-ID filter before selecting an option.

After choosing an exact ID, read its current state before an update or lifecycle action:

curl "$SHELFCYCLE_API_BASE_URL/shipping-options/shipping-option-id" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

Preview and create an option

Use a stable Idempotency-Key for a new source event. Preview the same intended request with dryRun=true:

curl "$SHELFCYCLE_API_BASE_URL/shipping-options?dryRun=true" \
  -X POST \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shipping-carrier:source-1042" \
  -d '{
    "type": "SO_SHIPPING_CARRIER",
    "value": "Northstar Ground",
    "externalId": "source-1042"
  }'

Review the readiness response, then send the identical request without dryRun=true. A new option returns 201 with the saved row and changed: true. Repeating the completed source event returns the existing row with changed: false.

Source IDs are interpreted within the selected type. Keep type, externalId, and the source record together. When no source ID is available, the type and trimmed value identify an existing option before a new row is created.

Update a value or source ID

Read the option first and use its latest updatedAt value in If-Match. The option's type remains fixed; update value, externalId, or both.

curl "$SHELFCYCLE_API_BASE_URL/shipping-options/shipping-option-id?dryRun=true" \
  -X PATCH \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2026-09-15T18:30:00.000Z" \
  -d '{
    "value": "Northstar Ground Freight"
  }'

After review, send the same PATCH without dryRun=true. The response returns the saved row, its new updatedAt value, and whether anything changed. If the option changed after your read, fetch it again and rebuild the update from its current state.

Archive or restore an option

Archive one outdated choice with its latest updatedAt value and an empty body:

curl "$SHELFCYCLE_API_BASE_URL/shipping-options/shipping-option-id/archive?dryRun=true" \
  -X POST \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2026-09-15T18:35:00.000Z" \
  -d '{}'

Apply the reviewed action without dryRun=true. The lifecycle receipt reports action, archived, changed, and the new updatedAt. Restore the same record through /unarchive using that latest timestamp. Archiving preserves the option's identity and does not change existing documents that already reference its value.