Integrate WMS or OMS System

If you use a fulfillment system such as an OMS or WMS, you can integrate with Carriyo by creating the shipment only after the order is fulfilled on your end (i.e. items are picked and packed). In this scenario, you bypass the draft shipment process and create a confirmed shipment directly with complete parcel and item data.

The confirmed shipment is immediately assigned to a carrier, booked, and a tracking number and label are generated.

Integration flow

Step 1: Create a confirmed shipment

After the items are picked and packed in your WMS/OMS, create a confirmed shipment in Carriyo with the full shipment details.

API Endpoint: POST /shipments

Note: Do not include the draft=true query parameter — omitting it creates a confirmed shipment that is booked with a carrier immediately.

{
  "merchant": "YOUR-MERCHANT-ID",
  "entity_type": "FORWARD",
  "references": {
    "partner_order_reference": "ORD-10042",
    "partner_shipment_reference": "SHP-10042"
  },
  "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" },
      "weight": { "value": 1.2, "unit": "kg" }
    }
  ],
  "parcels": [
    {
      "partner_parcel_reference": "parcel-001",
      "weight": { "value": 1.5, "unit": "kg" },
      "dimension": { "width": 35, "height": 25, "depth": 15, "unit": "cm" }
    }
  ],
  "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"
  }
}

Required fields for a confirmed shipment

Since the shipment is booked immediately, all required fields must be present in the request:

Step 2: Receive the booking result via webhook

After creation, Carriyo books the shipment with the carrier asynchronously. Set up a webhook to receive the result:

• Booked event — The shipment was successfully booked. The webhook payload includes the full Shipment Object with the carrier's tracking number ( carrier_tracking_no ) and label URL. Use this to send the label back to your WMS for printing.
• Default Label Generated event — The label is ready. If you manage label printing in your WMS, use this event to trigger automatic label printing.
• Error event — The booking failed. See Step 3 for how to handle this.

See Working with Webhooks for setup instructions and retry logic.

Extracting the label

When you receive a Booked or Default Label Generated webhook, the shipment object contains the label URL in the label field. You can download the label (typically a PDF or ZPL file) and send it to your WMS for printing.

Step 3: Handle errors

If the booking fails, the shipment moves to error status. Common causes include:

• Missing or inaccurate parcel weight/dimensions
• Invalid or incomplete pickup/dropoff address
• Carrier service unavailable for the route
• Missing item details required by the carrier

To resolve, call the confirm endpoint again with the corrected fields in the request body. The body patches top-level elements — only include the elements you need to correct. Carriyo will re-validate and attempt to book with the carrier again.

API Endpoint: POST /shipments/{shipment_id}/confirm

Alternatively, the reprocess endpoint can also be used to fix and rebook. Reprocess is more appropriate when the shipment was previously booked, cancelled, or returned and needs to be re-sent to a carrier.

See Shipment Validation Errors and Shipment Error Codes for error reference.

Carrier assignment

When a shipment is created as confirmed, Carriyo uses your configured automation rules to determine which carrier and service to use. Automation rules are set up via the Carriyo dashboard and can assign carriers based on destination, weight, payment mode, delivery type, and other conditions. If you haven't configured automation rules, you can also specify the carrier account explicitly on the shipment.

Difference from the e-commerce orders integration

If you want early visibility into orders before they are fulfilled, consider using the e-commerce orders integration with draft shipments instead.