comecerodocs
Shipments

Create a shipment

POST
/orders/{order_id}/shipments

Records a parcel sent for the order: the items and quantities in it, and the carrier and tracking number. Each item is marked fulfilled once all of its units have shipped. When that makes the whole order fulfilled, any pending (authorized) payment is captured (money moves) and the order:fulfilled event fires. The shipment:created event fires and the customer is sent the shipment email.

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

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

order_id*string

The order 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

A new shipment for an order. Saving it marks order items fulfilled once every unit has shipped. When that makes the whole order fulfilled, any pending (authorized) payment is captured and order:fulfilled fires. The shipment:created event fires and the customer gets the shipment email.

items?array<>

The order items in the parcel. At least one.

Items1 <= items
date_shipped?string

When the parcel left or will leave. Can be in the past or the future. Defaults to now.

Formatdate-time
courier?string

The carrier, for example UPS. See the shipment object for the carriers that get a tracking link made for them.

Lengthlength <= 50
tracking_number?string

The tracking number.

tracking_url?string

The tracking page. Leave it out for known carriers.

Lengthlength <= 256

Response Body

The new 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.

curl -X POST 'https://api.comecero.com/api/v1/orders/string/shipments' \  -H 'Content-Type: application/json' \  -d '{  "items": [    {      "item_id": "1",      "quantity": 2    }  ],  "courier": "UPS",  "tracking_number": "1Z999AA10123456784"}'
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}

Overview

Previous Page

List shipments GET

Lists the shipments on your account, oldest first unless you send `desc=true`. To create one, use `POST /orders/{order_id}/shipments`. The list is cursor-based: use `after_item` and `before_item` (or the `next_page_url` and `previous_page_url` in the response). It is ordered by the date named in `date_type`: `date_created` (default) or `date_modified`. `sort_by` is ignored. Needs a secret or trusted token. Limited tokens get `403`.