Update a shipment by its id (unambiguous amend)

patch

https://api.protectplus.io/shipments/by-id/{id}

Partial update (RFC 7396 merge semantics) of editable fields on a
specific shipment, identified by its immutable shipment_id (returned
by POST /shipments and echoed in every shipment response).

Use this instead of PATCH /shipments/{tracking_number} when a
tracking number is shared by several shipments (a clubbed parcel —
several orders shipped in one package). A shared tracking number can't
identify one shipment, so PATCH /shipments/{tracking_number} returns
409 ambiguous-tracking-number with the candidate shipment_ids;
pick one and amend it here.

The editable/immutable field rules, null (clear) semantics, and the
"at least one updatable field" requirement are identical to
PATCH /shipments/{tracking_number}.

Rate limit: 600 requests per minute per store, shared with
POST /shipments.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

string

required

The shipment's shipment_id (as returned by POST /shipments).

Body Params

At least one editable field must be present. tracking_number
and carrier are intentionally absent — they are immutable
and rejected by the validator if supplied.

order_number

string | null

Platform order number to associate with this shipment, or null to clear.

customer_email

string | null

tracking_url

string | null

Carrier deep-link override (use when the carrier-default URL is wrong).

shipped_at

date-time | null

eta

date-time | null

items

array of objects | null

Line-item enrichment for this shipment. Replaces any
existing items array (no per-item merge). See
ShipmentItem for the per-item shape.

items

servicelevel

object

Carrier service level. Sending null clears the field.

ship_to

object

Delivery address. Stored on the shipment and surfaced as address_to on responses. Sending null clears the field.

metadata

string | null

Free-form merchant-controlled metadata string.

totals

object

Order totals snapshot. Sending null clears the block.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Shipment updated. Returns the merged record plus a fields_changed array listing which fields were actually modified by this patch (useful for audit logs). Identical shape to PATCH /shipments/{tracking_number}.

401Missing, invalid, expired, or revoked JWT. Tokens expire 60 minutes after issuance — if detail is "token expired", re-mint via POST /auth/v1/token and retry with the new bearer.

404Shipment not found — no shipment with this id belongs to the authenticated store.

413Payload Too Large — the request body exceeds the 256 KB limit for this endpoint. Do NOT retry the request unchanged; reduce the payload (e.g. trim the items array) and re-send.

429Rate limit exceeded.

502Upstream service unreachable or returned an unexpected response.

504Upstream service timed out. Safe to retry.