Integrate E-commerce Orders

If you're not using a fulfillment system such as an OMS or WMS, and you are unable to use one of our pre-built connectors, you can integrate your e-commerce orders via API. In this setup, you will typically create a draft shipment in Carriyo when a customer order is received. A shipment in draft status allows the merchant to fulfill the items (pick and pack) before confirming the shipment. Once the shipment is confirmed, it is booked with the selected carrier, a tracking number is generated, and a label is produced.

Creating a draft shipment provides early visibility into your shipments from the moment the customer order is received.

Using a connector instead? If your e-commerce platform is Shopify, WooCommerce, Magento, or Salesforce Commerce Cloud, consider using one of Carriyo's pre-built connectors — they handle order sync automatically without custom API integration.

Integration flow

Step 1: Create a draft shipment

When a customer places an order on your e-commerce platform, create a draft shipment in Carriyo. At this stage you typically have the order details (items, customer address, payment) but haven't picked and packed yet — so parcel details and pickup location may not be known.

API Endpoint: POST /shipments?draft=true

Include the data you have at order time:

{
  "merchant": "YOUR-MERCHANT-ID",
  "entity_type": "FORWARD",
  "references": {
    "partner_order_reference": "ORD-10042",
    "partner_shipment_reference": "ORD-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" }
    }
  ],
  "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"
  }
}

Note: The draft=true query parameter is what makes this a draft shipment. Without it, Carriyo treats the request as a confirmed shipment and attempts to book with a carrier immediately.

The draft shipment is now visible in the Carriyo dashboard, giving your operations team early visibility into incoming orders.

Step 2: Confirm the shipment

Once the order is fulfilled (items picked and packed), confirm the shipment. Carriyo validates all required fields, assigns a carrier (based on your automation rules), books the shipment, and generates a tracking number and label.

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

The confirm endpoint accepts a request body, so you can add any missing data and confirm in a single call. The body works like a patch — any top-level element you include (e.g. parcels, pickup) replaces the corresponding element on the shipment, while elements you omit are left unchanged. This lets you pass the data that wasn't available at draft creation time — such as parcel details and pickup location — together with the confirm action.

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

Tip: If all required data was already provided at draft creation time, you can call confirm with an empty body.

Alternatively, if your operations team handles fulfillment manually, they can confirm shipments directly from the Carriyo dashboard.

Step 3: Receive the booking result via webhook

After confirmation, 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.
• Default Label Generated event — The label is ready. If you manage label printing externally, use this event to trigger printing in your system.
• Error event — The booking failed. See Step 4 for how to handle this.

See Working with Webhooks for setup instructions and retry logic.

Step 4: Handle errors

If the booking fails (e.g. missing required fields, carrier rejection, invalid address), the shipment moves to error status. You can fix the data and rebook in a single call using the confirm endpoint — include the corrected fields in the request body:

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

Like Step 2, 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.

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.

Common causes of booking errors:

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

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

What data to pass at each stage

Note: All fields marked as required at confirm must be present on the shipment — either from the original draft or included in the confirm request body. You can spread the data across both steps as suits your workflow.

Carrier assignment

When a shipment is 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.