Skip to main content

​
Overview

Create a shipment that groups parcels that will be dispatched together to e-CROSS’ consolidation hub. This is essential when you use your own first mile carrier to dispatch picked and packed parcels from your warehouse.
If the brand uses their own first mile carrier to dispatch parcels from their warehouse to e-CROSS’ consolidation hub, follow these instructions. If the brand relies on a pickup coordinated by e-CROSS, this step can be skipped.

​
Create Shipment

During the pick & pack process, you generate the first mile label to dispatch parcels to e-CROSS’ consolidation hub, usually grouping more than one parcel into a “master box”. Once this process is finished, create a Shipment on e-CROSS to inform which parcels are contained in this dispatch and which is the first mile tracking code.
The Shipment is essential to allow e-CROSS to pre-alert the consolidation hub about upcoming parcels to prevent any losses.
curl -X POST 'https://hermes.api.e-cross.tech/ext/shipments' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "parcelIds": ["MERCHANT387294640090BR"],
    "description": "Weekly dispatch",
    "expectedShipDate": "2025-06-01T15:00:00Z",
    "expectedDeliveryDate": "2025-06-03T15:00:00Z",
    "firstMileCarrierId": "USPS",
    "firstMileTrackingNumber": "FM1234567890"
  }'

{
  "id": "aa65bd71-33cf-40c1-bdc5-91b01344f659",
  "status": "CREATED",
  "parcelIds": [
    "MERCHANT387294640090BR"
  ],
  "description": "Weekly dispatch",
  "expectedShipDate": "2025-06-01T15:00:00Z",
  "expectedDeliveryDate": "2025-06-03T15:00:00Z",
  "firstMileCarrierId": "USPS",
  "firstMileTrackingNumber": "FM123456",
  "creationDate": "2025-06-01T10:43:59.080Z",
  "lastUpdateDate": "2025-06-01T10:43:59.080Z",
  "merchantId": "MERCHANT",
  "weight": 0.24,
  "type": "shipment"
}

​
Request Parameters

​
parcelIds
array
required
Array containing the parcelId values of parcels contained in this shipment. Each parcel ID corresponds to an order that has reached READY_FOR_SHIP status.
​
description
string
required
Human-readable description of the dispatch (e.g., “Weekly dispatch”, “Daily shipment”).
​
expectedShipDate
string
required
Expected date and time when the package will leave the fulfillment facility, in ISO 8601 format.
​
expectedDeliveryDate
string
required
Expected date and time when the package will arrive at the consolidation hub, in ISO 8601 format.
​
firstMileCarrierId
string
required
Identifier of the first mile carrier company (e.g., USPS, FedEx, DHL).
​
firstMileTrackingNumber
string
required
Tracking number or code of the first mile dispatch. This is the tracking code for the master box containing the parcels.

​
Response Fields

​
id
string
required
Unique identifier of this shipment.
​
status
string
required
Status of the shipment. Can be one of:
  • CREATED - Shipment has been created
  • SHIPPED - Shipment has been shipped
  • CANCELLED - Shipment was cancelled
​
parcelIds
array
required
Array containing the parcel IDs contained in this shipment.
​
description
string
required
Human-readable description of the dispatch.
​
expectedShipDate
string
required
Expected date when the package will leave the fulfillment facility.
​
expectedDeliveryDate
string
required
Expected date when the package will arrive at the consolidation hub.
​
firstMileTrackingNumber
string
required
Tracking number or code of the first mile dispatch.
​
weight
number
required
Total weight of the shipment in kilograms, generated by summing the weight of all parcels.
​
merchantId
string
required
The merchant ID.
​
creationDate
string
required
Date and time when the shipment was created.
​
lastUpdateDate
string
required
Date and time when the shipment was last updated.

​
How to Retrieve Parcel IDs

To retrieve the parcelId for each order, follow these steps:
1

Ensure order is ready

Make sure the order has reached the READY_FOR_SHIP status.
2

Retrieve the order

Retrieve the order via the “Get Order” or “Get Order by Sales Channel Id” APIs.
3

Find the parcelId

Find the parcelId in the following path: order.statusHistory[status="READY_FOR_SHIP"].eventData.parcelId
Alternatively, you can find the parcelId using the externalParcelId, which is the tracking number in the barcode on the shipping label. This can be identified by scanning the barcode or found in order.shipping.deliveries.lastMileTrackingNumber.

Get Shipment

Next: Learn how to retrieve shipment details