External carrier integration
When a shipping is handed to a carrier that OMS does not book itself, the tracking of the shipment reaches OMS through this integration. It is built by whoever follows the shipment for the merchant — the carrier, a shipping platform, or the warehouse when it ships with its own carrier contracts — and has two goals:
- Set the tracking information of the shipping handed over to you: tracking number, tracking URL and carrier. This step is always required.
- Report the tracking events as the shipment progresses — in transit, out for delivery, delivered, or an exception or a failure — so that OMS, the customer care and the customer see where the parcel is. 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.
This integration applies only to shippings whose carrier booking is not managed by OMS (bookingStatus: unmanaged): a per-project choice, configured by Calicantus during onboarding. The orders reach OMS through the e-commerce channel and the parcels are prepared by the warehouse: the scope described here is only the tracking exchange between the carrier and OMS.
How the integration works
Identify the shipping
Every operation addresses a shipping by its OMS id — the id of an entry of Order.shippings. How that id reaches you is part of the handover agreed with Calicantus during onboarding: typically the system that hands you the parcel passes it along with the shipment data. You can read the shipping, with its recipient address and parcels, with the order query, documented in Get order details.
A shipping waiting for your tracking has bookingStatus: unmanaged, no trackingNumber and a null tracking status. Things to know about orders explains the three statuses of a shipping.
Set the tracking information
As soon as the shipment is registered on your side, record its tracking on the shipping with the shippingTrackingSet mutation: the tracking number, the tracking URL and the carrier — identified by one of the codes returned by the shippingCarriers query. OMS records the first tracking event, info_received, and the shipping's status moves from null to info_received.
Things to know:
- Set the tracking before reporting any event: events on a shipping without tracking information are rejected.
- Each shipping accepts the tracking information once.
The Report the tracking of a shipping guide documents the field-by-field rules with verified examples.
Report the tracking events
Every time the shipment changes state, report it with the shippingEventCreate mutation: the new status — in_transit, out_for_delivery, exception, delivered or failed — and a message describing the event. Each event updates the shipping's status and is appended to its history. 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.
Things to know:
deliveredandfailedclose the tracking: every further event is rejected. Once delivered, the order isdeliveredtoo.- Report each event with the time it occurred according to the carrier: the time of the
deliveredevent is the delivery date of the order, from which the return terms are computed. - Report a
failedevent when the parcel will not be delivered (returned to sender, lost): anexceptionis a temporary issue (a failed delivery attempt, a customs hold) after which the shipment goes on.
The Report the tracking of a shipping guide documents the field-by-field rules with verified examples.
What you need to get started
Everything below is agreed with and configured by Calicantus — to start the onboarding, contact developers@calicant.us:
- API credentials — the integration authenticates like any other API client: see Authentication. The shippings you can act on belong to the orders of the channels assigned to your API user: a shipping of another channel is not found.
- The handover of the shipping id — how the OMS id of each shipping reaches you with the parcel, defined with Calicantus during onboarding.
- Your carrier code — the carriers known to OMS are listed by the
shippingCarriersquery; if yours is missing, Calicantus adds it.
Before going live, also review the core concepts of the API in Getting started — in particular Errors and Rate limiting.