Skip to main content

Report the tracking of a shipping

Only for shippings handled by an external carrier

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.

note

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:

  1. 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.
  2. Report each tracking event with shippingEventCreate, every time the shipment changes state, up to delivered or failed. 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.

Request
query shippingCarriers {
  shippingCarriers {
    id
    code
    name
  }
}
Response
{
  "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:

  • trackingNumber is required: the tracking code assigned by the carrier.
  • trackingUrl is optional: the page where the shipment can be followed on the carrier's website.
  • carrierCode is optional: the code of a carrier returned by shippingCarriers, to replace the carrier assigned to the shipping at import. An unknown code is rejected with a NOT_FOUND error.

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.

Request
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
    }
  }
}
Response
{
  "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:

  • status is required: in_transit, out_for_delivery, exception, delivered or failed — the meaning of each value is documented on the ShippingEventCreateStatusInput enum reference. info_received is recorded by OMS when the tracking is set and cannot be reported.
  • message is optional: the description of the event, as you would show it to the recipient.
  • receivedAt is optional: when the event occurred, according to the carrier. Without it, OMS uses the time of the request. Send the carrier's time: the receivedAt of the delivered event is the delivery date of the order, from which the return terms are computed. The time OMS recorded the event is available separately as createdAt.

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.

Request
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
  }
}
Response
{
  "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.

Response
{
  "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
  }
}

Relevant permissions

The operations in this page require the following permissions on the API credentials — they are configured for you by Calicantus.

  • shipping:mutation:shipping_tracking_set
  • shipping_event:mutation:shipping_event_create
  • shipping_carrier:query:shipping_carriers
  • order:query:order
  • order:read
  • shipping:read
  • shipping_carrier:read
  • shipping_event:read