Report the tracking of a shipping
The operations on this page apply only to shippings whose carrier booking is not managed by OMS — bookingStatus: unmanaged: the parcel is handed to a carrier outside OMS, and the carrier, or the system that follows the shipment for the merchant, reports the tracking through the API. This is a per-project choice, configured by Calicantus during onboarding.
The ids, tracking numbers, URLs and messages in these examples are placeholders — replace them with your own. The carriers listed depend on your environment.
A shipping handled by an external carrier starts with no tracking state: status is null, trackingNumber and events are empty (see Things to know about orders). The tracking is reported in two steps, in this order:
- Set the tracking information once, with
shippingTrackingSet: tracking number, tracking URL and carrier. OMS records the first tracking event,info_received. This step is always required. - Report each tracking event with
shippingEventCreate, every time the shipment changes state, up todeliveredorfailed. This step is not needed when, as agreed with Calicantus for your project, OMS follows the shipment on its own once the tracking is set.
Set the tracking before reporting any event: an event on a shipping without tracking information is rejected with a BAD_REQUEST error.
shippingId is the id of an entry of Order.shippings: read it with the order query, as shown in Get order details.
List the carriers
Use shippingCarriers to list the carriers known to OMS: the code identifies the carrier when you set the tracking. The list does not depend on the channel.
query shippingCarriers {
shippingCarriers {
id
code
name
}
}{
"data": {
"shippingCarriers": [
{
"id": "1",
"code": "UPS",
"name": "UPS"
},
{
"id": "2",
"code": "DHL",
"name": "DHL"
},
{
"id": "3",
"code": "BRT",
"name": "BRT"
},
{
"id": "8",
"code": "GLS",
"name": "GLS"
}
]
},
"extensions": {
"queryComplexity": 4,
"bucketBalance": 9996,
"bucketRestoreRate": 100
}
}Set the tracking information
Use shippingTrackingSet to record the tracking of the shipment. The mutation accepts a ShippingTrackingSetInput object — its reference lists all the available fields — and returns the updated Shipping.
Field notes:
trackingNumberis required: the tracking code assigned by the carrier.trackingUrlis optional: the page where the shipment can be followed on the carrier's website.carrierCodeis optional: thecodeof a carrier returned byshippingCarriers, to replace the carrier assigned to the shipping at import. An unknown code is rejected with aNOT_FOUNDerror.
The shipping must have bookingStatus: unmanaged: a shipping booked by OMS rejects the mutation with a BAD_REQUEST error. Each shipping accepts the tracking information once: a second call is rejected with a BAD_REQUEST error (Shipping info already received).
After the call the shipping's status is info_received and events holds the first event, created by OMS.
mutation shippingTrackingSet {
shippingTrackingSet(
shippingId: "6816"
input: {
trackingNumber: "1Z999AA10123456784"
trackingUrl: "https://www.ups.com/track?tracknum=1Z999AA10123456784"
carrierCode: "UPS"
}
) {
id
bookingStatus
status
trackingNumber
trackingUrl
carrier {
code
name
}
events {
id
status
message
receivedAt
}
}
}{
"data": {
"shippingTrackingSet": {
"id": "6816",
"bookingStatus": "unmanaged",
"status": "info_received",
"trackingNumber": "1Z999AA10123456784",
"trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
"carrier": {
"code": "UPS",
"name": "UPS"
},
"events": [
{
"id": "19172",
"status": "info_received",
"message": "Informazioni ricevute",
"receivedAt": "2026-10-16T15:14:33.675Z"
}
]
}
},
"extensions": {
"queryComplexity": 14,
"bucketBalance": 9976,
"bucketRestoreRate": 100
}
}Report a tracking event
Use shippingEventCreate every time the shipment changes state. The mutation accepts a ShippingEventCreateInput object — its reference lists all the available fields — and returns the ShippingEvent recorded.
Field notes:
statusis required:in_transit,out_for_delivery,exception,deliveredorfailed— the meaning of each value is documented on theShippingEventCreateStatusInputenum reference.info_receivedis recorded by OMS when the tracking is set and cannot be reported.messageis optional: the description of the event, as you would show it to the recipient.receivedAtis optional: when the event occurred, according to the carrier. Without it, OMS uses the time of the request. Send the carrier's time: thereceivedAtof thedeliveredevent is the delivery date of the order, from which the return terms are computed. The time OMS recorded the event is available separately ascreatedAt.
Each event updates the shipping's status and is appended to its events. The same status can be reported more than once (two in_transit events, for example). delivered and failed are final: once the shipping has reached one of them, every further event is rejected with a BAD_REQUEST error (Shipping status is already delivered or failed). Once delivered, the order is delivered too.
mutation shippingEventCreate {
shippingEventCreate(
shippingId: "6816"
input: {
status: in_transit
message: "Departed from facility, Milan"
receivedAt: "2026-10-16T09:12:00Z"
}
) {
id
status
message
receivedAt
createdAt
}
}{
"data": {
"shippingEventCreate": {
"id": "19173",
"status": "in_transit",
"message": "Departed from facility, Milan",
"receivedAt": "2026-10-16T09:12:00.000Z",
"createdAt": "2026-10-16T15:14:34.099Z"
}
},
"extensions": {
"queryComplexity": 6,
"bucketBalance": 9970,
"bucketRestoreRate": 100
}
}Read the tracking of a shipping
The tracking you reported is available on the shipping: status is the current state, events the full history, each event with the time it occurred (receivedAt) and the time OMS recorded it (createdAt). The events are returned in the order OMS recorded them: sort them by receivedAt for the order in which they occurred.
{
"data": {
"order": {
"id": "6568",
"shippings": [
{
"id": "6816",
"status": "delivered",
"trackingNumber": "1Z999AA10123456784",
"trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
"carrier": {
"code": "UPS",
"name": "UPS"
},
"events": [
{
"id": "19172",
"status": "info_received",
"message": "Informazioni ricevute",
"receivedAt": "2026-10-16T15:14:33.675Z",
"createdAt": "2026-10-16T15:14:33.705Z"
},
{
"id": "19173",
"status": "in_transit",
"message": "Departed from facility, Milan",
"receivedAt": "2026-10-16T09:12:00.000Z",
"createdAt": "2026-10-16T15:14:34.099Z"
},
{
"id": "19174",
"status": "out_for_delivery",
"message": "Out for delivery",
"receivedAt": "2026-10-16T13:05:00.000Z",
"createdAt": "2026-10-16T15:14:34.408Z"
},
{
"id": "19175",
"status": "delivered",
"message": "Delivered to the recipient",
"receivedAt": "2026-10-16T14:30:00.000Z",
"createdAt": "2026-10-16T15:14:34.625Z"
}
]
}
]
}
},
"extensions": {
"queryComplexity": 16,
"bucketBalance": 9942,
"bucketRestoreRate": 100
}
}