Update an existing shipment

patch

https://api.protectplus.io/shipments/{tracking_number}

Partial update (RFC 7396 merge semantics) of editable fields on an
existing shipment. Identify the shipment via the URL path; identity
fields are immutable.

Editable fields: order_number, customer_email, tracking_url,
shipped_at, eta, items, servicelevel, ship_to, metadata,
totals, return_label.

Use this to amend the merchant-provided prepaid return label on an
existing shipment (last write wins); send return_label: null to clear
it. Same payload shape as POST /shipments.

Immutable fields: tracking_number and carrier cannot be
changed (the request is rejected with 400 Bad Request). To change a
carrier, register the shipment again with POST /shipments.

Null semantics: sending null for a field clears it
(RFC 7396 merge-patch). Omitted fields are left untouched.

At least one updatable field must be present in the body — an
empty / no-op patch returns 400 Bad Request with a detail
message of "No updatable fields supplied".

Shared tracking numbers (clubbed parcels): if the tracking number
maps to MORE than one shipment (several orders shipped in one parcel),
it cannot identify a single shipment and this endpoint returns
409 Conflict (errors/ambiguous-tracking-number) with a candidates
list of the matching shipment ids — nothing is updated. Amend a
specific shipment via PATCH /shipments/by-id/{id}.

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

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

tracking_number

string

required

length ≤ 64

Tracking number identifying the shipment to update.

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.

return_label

object

Merchant-provided prepaid RETURN label for THIS package — the same payload shape as POST /shipments and PUT /orders/{order_number}/return-label. Distinct from the shipment's tracking_number (that tracks the parcel going TO the customer; this is the label the customer uses to send the item BACK). Amending it here overwrites the label on this shipment (last write wins); sending null clears it. Get Plus stores it on the shipment and the customer return flow renders it for the items that shipped in this package; Get Plus never generates or pays for it.

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).

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 matches this tracking number for the authenticated store. Register the shipment first with POST /shipments.

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.