Pre-booked shipments

A pre-booked shipment is one that's already been booked with a carrier before it reaches Carriyo. You have a tracking number, you know the carrier, you have a label. Carriyo's role from there is post-booking: tracking, customer notifications, branded tracking page, returns. No re-booking happens.

Use this model when an existing logistics platform handles the booking, whether that's another multi-carrier shipping platform, a carrier-direct integration, or a 3PL. Carriyo adds the post-purchase experience on top.

What's different from a normal shipment

Pre-booked shipments skip the booking flow. Because Carriyo never calls the carrier, registration resolves synchronously: you supply your references, a tracking number, and an input carrier identifier, and the create response comes back already booked (if the input carrier maps to a configured carrier account) or error (if it doesn't). It doesn't need a full booking payload, no pickup, parcels, or payment. From there Carriyo goes straight to the tracking phase.

	Normal	Pre-booked
Carriyo books with carrier	Yes	No (already booked)
Tracking number	Generated by carrier on booking	Provided up-front
Label	Generated by carrier on booking	Provided up-front (or absent)
Carrier rate computation	Yes	Skipped
Status flow	pending → booked → …	booked directly, or error if the carrier doesn't map
Tracking events	Yes (carrier callbacks + proactive tracking)	Yes (same source)
Notifications, branded tracking	Yes	Yes

How tracking works for pre-booked

Carriyo tracks pre-booked shipments the same way it tracks shipments it has booked itself: directly with the carrier.

When a pre-booked shipment is created, the request supplies an input_carrier identifier alongside the carrier tracking number. The input carrier is mapped to a configured carrier account in Carriyo (the same carrier-account configuration used for direct bookings), which gives Carriyo the credentials and endpoints to talk to the carrier. From there, status flows in through the standard tracking mechanisms: carrier callbacks where supported, proactive periodic refreshes where not.

This means a pre-booked shipment behaves exactly like any other Carriyo shipment from booked onwards. Webhooks fire on each status transition, the customer-facing tracking page updates, notifications dispatch.

When to use this

• Migration scenarios. You're moving from a different multi-carrier shipping platform to Carriyo. Existing in-flight shipments are pre-booked; new ones use Carriyo's full booking flow.
• 3PL fulfillment. A 3PL handles fulfillment and booking centrally; you want your own customer-facing tracking and notifications branded to your store.
• Multi-system landscape. Several teams use different shipping platforms, but customer-facing CX should be unified. Carriyo provides consistent post-purchase CX across all of them.

When not to use this

• You can book directly via Carriyo. If Carriyo supports the carrier and the integration is working, book through Carriyo. Pre-booked is a workaround for cases where you can't.
• No carrier mapping for the input carrier. If the input_carrier value doesn't resolve to a configured carrier account, the shipment is created in error (invalid_input_carrier / no_carrier_assigned) and Carriyo can't track it. Fix the input_carrier value or the carrier configuration, then reprocess. The account must exist before you register the shipment.

How it fits with other modules

• Shipping. Pre-booked shipments are normal Shipment objects with the booking step skipped.
• Carrier configuration. The carrier account that input_carrier maps to provides the credentials Carriyo uses to track the shipment.
• Post-purchase CX. Most pre-booked use cases are CX-driven; the value is in the branded tracking experience.
• Webhooks. Your systems consume the same shipment status webhook as for normally-booked shipments.