# Shipping Options

Maintain freight terms, carriers, FOB terms, freight methods, and border crossing points.

Canonical HTML: https://developer.shelfcycle.com/guides/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

| Endpoint | Scope | Use it for |
| --- | --- | --- |
| `GET /shipping-options` | `shipping-options:read` | List and filter the organization's Shipping Options vocabulary. |
| `GET /shipping-options/{id}` | `shipping-options:read` | Read one selected option and its current update time. |
| `POST /shipping-options` | `shipping-options:write` | Preview or create one option. |
| `PATCH /shipping-options/{id}` | `shipping-options:write` | Preview or update an option's value or source ID. |
| `POST /shipping-options/{id}/{archive|unarchive}` | `shipping-options:write` | Preview, retire, or restore one option. |

`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:

| Type | Business use |
| --- | --- |
| `SO_FREIGHT_TERMS` | Sales Order Freight Terms |
| `PO_FREIGHT_TERMS` | Purchase Order Freight Terms |
| `SO_SHIPPING_CARRIER` | Sales Order Shipping Carrier |
| `SO_SHIPPING_FOB` | Sales Order Shipping FOB |
| `SO_FREIGHT_METHOD` | Sales Order Freight Method |
| `BORDER_CROSSING_POINT` | Border Crossing Point |

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:

```bash
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:

```bash
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`:

```bash
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.

```bash
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:

```bash
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.

> **Guardrail**: Keep the option type with every ID and source identifier. Read the current row before changing or retiring it, and use the exact Shipping Options route instead of treating payment terms, warehouse IDs, or supplier names as the same vocabulary.