Integrate Pre-Booked Shipments

If you already have a system for booking shipments and generating labels, and you only plan to use Carriyo for shipment tracking, performance analysis, and enhancing the post-purchase experience, you can create pre-booked shipments in Carriyo. A pre-booked shipment is one that has already been booked with the carrier (outside Carriyo) and has an existing tracking number.

Pre-booked shipments created in Carriyo will be tracked automatically, and status updates will flow through the platform — enabling tracking pages, customer notifications (SMS, email, WhatsApp), and shipping performance analytics.

Integration flow

Step 1: Create a pre-booked shipment

After booking the shipment in your existing system, send the shipment details to Carriyo with the pre_booked flag and carrier tracking information.

API Endpoint: POST /shipments

{
  "merchant": "YOUR-MERCHANT-ID",
  "entity_type": "FORWARD",
  "references": {
    "partner_order_reference": "ORD-10042",
    "partner_shipment_reference": "SHP-10042"
  },
  "pre_booked": true,
  "pre_booking_info": {
    "input_carrier": "DHL",
    "carrier_tracking_no": "1234567890"
  },
  "payment": {
    "payment_mode": "PRE_PAID",
    "total_amount": 149.99,
    "currency": "AED"
  },
  "items": [
    {
      "description": "Running Shoes - Black, Size 44",
      "sku": "SHOE-RUN-BLK-44",
      "quantity": 1,
      "price": { "amount": 149.99, "currency": "AED" }
    }
  ],
  "pickup": {
    "partner_location_code": "DUBAI-WH-01"
  },
  "dropoff": {
    "contact_name": "Ali Hassan",
    "contact_phone": "+971561234567",
    "contact_email": "ali.hassan@example.com",
    "address1": "Villa 12, Al Barsha 1",
    "city": "Dubai",
    "state": "Dubai",
    "country": "AE"
  }
}

Pre-booking fields

Important: The carrier_tracking_no must be unique per carrier. If you attempt to create a pre-booked shipment with a tracking number that already exists in Carriyo for that carrier, the request will be rejected.

Recommended additional fields

While only merchant, references, pre_booked, and pre_booking_info are strictly required, including additional fields improves the tracking experience:

Step 2: Carriyo initiates tracking

Once the pre-booked shipment is created, Carriyo automatically begins polling the carrier for tracking updates using the provided carrier_tracking_no. Status updates are mapped to Carriyo's standardized status codes and reflected in the dashboard.

Step 3: Receive status updates via webhook

Set up webhooks to receive tracking updates as they happen:

• Shipped event — The carrier has collected the shipment.
• In Transit event — The shipment is moving through the carrier network.
• Out for Delivery event — The shipment is on its way to the customer.
• Delivered event — The shipment has been delivered.

These events can be used to trigger customer notifications, update your order management system, or feed into analytics.

See Working with Webhooks for setup instructions and retry logic. See Shipment Tracking for more details on key tracking events.

When to use pre-booked vs. standard shipments

Use pre-booked shipments when you want to keep your existing booking and labeling workflow but gain Carriyo's tracking, analytics, and customer communication capabilities.