Shipments

Endpoints under /api2/shipment to register the order shipment with single or batch tracking, list existing shipments, look one up individually, add tracks to an existing shipment and resend customer emails.

REST JSON Bearer Token New in 2026

Overview

The shipments resource covers the entire logistics record: shipment creation (full or partial), tracking inclusion (single or multi-parcel), email resend and listing for carrier reconciliation. For shared family rules (pagination, dates, HTTP statuses, items handling), see the main Orders page.

Tracking modesSingle track_number or tracks[] batch.

Resolutionshipment_id, order_id or order_increment_id.

Recognized aliasesshipment, shipments, shippment, shippments.

opt

Partial itemsorder_item_id or sku + qty.

GET/api2/shipment

List shipments.

ListingFilters

page, limit, include_pagination Optional

Standard pagination.

order_id Optional

Internal order ID.

order_increment_id Optional

Order increment number.

increment_id Optional

Shipment increment number. A single value returns the detailed shipment.

created_from, created_to Optional

Created-at range.

sort, direction Optional

Accepted fields: entity_id, created_at, updated_at, increment_id.

Examples

GET /api2/shipment?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

GET /api2/shipment?order_id=123
Authorization: Bearer {{token}}

{
  "page": 1,
  "limit": 50,
  "include_pagination": 1,
  "order_increment_id": "100000123",
  "created_from": "2026-01-01",
  "created_to": "2026-12-31"
}

List responses use shipments. Lookup by ID or single increment_id uses shipment. Recognized aliases: /api2/shipments, /api2/shippment, /api2/shippments. The recommended canonical route is /api2/shipment.

GET/api2/shipment

Get a single shipment.

GET /api2/shipment?id=789
Authorization: Bearer {{token}}

GET /api2/shipment?increment_id=100000078
Authorization: Bearer {{token}}

POST/api2/shipment/create

Create a shipment fully or partially. The payload may include initial tracking via track_number (single object) or tracks (list).

ShippingTracking

order_id / order_increment_id

Order identifier. Use exactly one.

items Optional

Items to ship. If omitted, ships all available quantities.

send_email Optional

When true, sends the shipment email after saving.

comment Optional

Comment recorded on the shipment.

carrier_code, title, track_number Optional

Single tracking sent inline in the payload.

tracks Optional

List of tracking entries; each with carrier_code, title and track_number.

Full shipment with single tracking

POST /api2/shipment/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "send_email": true,
  "comment": "Shipment created by integration.",
  "carrier_code": "custom",
  "title": "Carrier",
  "track_number": "BR123456789"
}

Partial shipment with tracking list

POST /api2/shipment/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "items": [
    {"order_item_id": 10, "qty": 1},
    {"sku": "PRODUCT-001", "qty": 2}
  ],
  "tracks": [
    {
      "carrier_code": "custom",
      "title": "Carrier",
      "track_number": "BR123456789"
    }
  ]
}

POST/api2/shipment/track

Adds a tracking entry to an existing shipment. Does not create a shipment for the order. May receive shipment_id directly or resolve via order when there is a single shipment.

By `shipment_id`

POST /api2/shipment/track
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "shipment_id": 789,
  "carrier_code": "custom",
  "title": "Carrier",
  "track_number": "BR123456789"
}

By `order_increment_id`

POST /api2/shipment/track
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "carrier_code": "custom",
  "title": "Carrier",
  "track_number": "BR123456789"
}

By `order_id`

POST /api2/shipment/track
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "carrier_code": "custom",
  "title": "Carrier",
  "track_number": "BR123456789"
}

If the order has more than one shipment, send shipment_id or the shipment's increment_id to avoid ambiguity. Compatibility: POST /api2/shipment also creates tracking.

POST/api2/shipment/email

Resend the shipment email. Identify it with shipment_id, id or increment_id.

POST /api2/shipment/email
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "shipment_id": 789,
  "comment": "Resend requested by integration."
}

Supported usage patterns

Tested and certified combinations for the Shipments resource.

List today's shipmentsGET /api2/shipment?created_from=2026-05-07&include_pagination=1

Shipments for an orderGET /api2/shipment?order_increment_id=100000123

Full shipment with single trackPOST /api2/shipment/create + carrier_code + track_number

Multi-parcel shipmentPOST /api2/shipment/create + tracks[]

Add tracking to existing shipmentPOST /api2/shipment/track + shipment_id

Resend emailPOST /api2/shipment/email

Integration recommendations

Avoid

Relying on the /api2/shippment or /api2/shippments aliases in new code.
Trusting send_email=true alone instead of an explicit resend via /api2/shipment/email after SMTP failures.
Mixing order_id and order_increment_id in the same payload.

Orders with multiple shipments

When an order has more than one shipment, the /api2/shipment/track endpoint returns 400 Ambiguous shipment for order if it receives only order_id. Capture the shipment_id from the listing and pass it explicitly.

Common errors

Status	Sample body	When it happens
`400`	`{"error": "Invalid item"}`	An `items` entry without `order_item_id`/`sku` or with non-positive `qty`.
`400`	`{"error": "Cannot create shipment"}`	The order no longer accepts further shipping (e.g. fully shipped or canceled).
`400`	`{"error": "Ambiguous shipment for order"}`	`POST /api2/shipment/track` resolved by an order with multiple shipments — provide `shipment_id`.
`401`	`{"error": "Unauthorized"}`	Missing `Authorization` or expired token.
`404`	`{"error": "Order not found"}`	Unknown `order_id` or `order_increment_id`.
`404`	`{"error": "Shipment not found"}`	Unknown `shipment_id` or `increment_id`.
`409`	`{"error": "Conflict on save"}`	Duplicate or deadlock on concurrent writes.