comecerodocs
Shipments

Update a shipment

POST
/shipments/{shipment_id}

Changes the date shipped, carrier, tracking number, tracking URL or meta of a shipment. The items cannot be changed. The shipment:modified event fires. The customer is not emailed again.

Needs a secret or trusted token. Limited tokens get 403.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

shipment_id*string

The shipment id.

Query Parameters

expand?string

Comma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.

Request Body

application/json
  1. body

The fields you may change on a shipment. The items cannot be changed: delete the shipment and create a new one instead. The body cannot be empty. The shipment:modified event fires.

date_shipped?string

When the parcel left or will leave.

Formatdate-time
courier?|

The carrier.

Lengthlength <= 50
tracking_number?|

The tracking number.

tracking_url?|

The tracking page.

Lengthlength <= 256
meta?||

Your own data for the shipment, a string or an object. At most 2048 characters once serialized.

Response Body

The updated shipment.

application/json
  1. response

A parcel sent for an order: which items and how many, the carrier and the tracking number. Creating shipments marks order items fulfilled.

object*"shipment"

The object type. Always shipment.

Value in"shipment"
url*string

The full URL of the shipment.

Formaturi
shipment_id*string

The shipment id.

date_created*string

When the shipment was created.

Formatdate-time
date_modified*string

When the shipment was last changed.

Formatdate-time
date_shipped*string

When the parcel left or will leave. Defaults to the time the shipment was created.

Formatdate-time
test*boolean

True for a test shipment.

account_id*string

The account the shipment belongs to.

items*array<>

The order items in this shipment.

order?|

A link to the order, or the order when you send expand=order. The response has no separate order_id field: take it from this link.

courier*|

The carrier, up to 50 characters. For UPS, FedEx, USPS, DHL USA, DHL eCommerce, OnTrac, ICC Worldwide, LaserShip, Canada Post, Australia Post and Royal Mail (written exactly so), the API fills in tracking_url for you when you leave it empty.

tracking_number*|

The tracking number.

tracking_url*|

The tracking page, up to 256 characters. Filled in from courier and tracking_number when you leave it empty and the carrier is a known one.

notifications?|

A link to the emails sent about this shipment, or the list when you send expand=notifications on a single shipment.

meta?||

Your own data for the shipment, a string or an object. Not for limited tokens.

formatted?

Display dates. Only present when you send formatted=true.

Example Request
curl -X POST 'https://api.comecero.com/api/v1/shipments/string' \  -H 'Content-Type: application/json' \  -d '{  "tracking_number": "1Z999AA10123456799"}'
Example Response
{  "object": "shipment",  "url": "https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL",  "shipment_id": "0093718200417ShQ2xN8kL",  "date_created": "2026-11-04T09:30:00Z",  "date_modified": "2026-11-04T09:30:00Z",  "date_shipped": "2026-11-04T09:30:00Z",  "test": true,  "account_id": "AB1234",  "items": [    {      "object": "shipment_item",      "item_id": "1",      "product_id": "lens-cloth.test",      "name": "Lens cleaning cloth",      "quantity": 2,      "product": "https://api.comecero.com/api/v1/products/lens-cloth.test"    }  ],  "order": "https://api.comecero.com/api/v1/orders/2979-KXVST-674",  "courier": "UPS",  "tracking_number": "1Z999AA10123456784",  "tracking_url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784",  "notifications": "https://api.comecero.com/api/v1/shipments/0093718200417ShQ2xN8kL/notifications",  "meta": null}

Get a shipment GET

Returns one shipment. Secret and trusted tokens can read any shipment on the account. A limited token can read a shipment only when it is bound to it, and `meta` is left out for it.

Delete a shipment DELETE

Deletes a shipment, for example one entered by mistake. Order items that no longer have all their units shipped are marked not fulfilled again, and so is the order. A payment already captured stays captured. The `shipment:deleted` event fires. Needs a secret or trusted token. Limited tokens get `403`.