Integrate Reverse Shipments

Carriyo differentiates between forward and reverse shipments. A forward shipment originates from the merchant and is delivered to the customer, while a reverse shipment starts at the customer's address and is returned to the merchant, typically due to a customer return.

Although similar, forward and reverse shipments have distinct characteristics:

  1. Reporting : Enables merchants to manage, analyze, and report forward and reverse shipment data separately. For example, you can set separate service levels for reverse shipments and monitor their performance independently.
  2. Carrier operations : Allows carriers to apply different operational processes for managing reverse shipments.
  3. Collection instructions : Some carriers require a separate collection instruction for reverse shipments to schedule the pickup from the customer.

Integration flow

Step 1: Create a reverse shipment

When a customer return is initiated, create a reverse shipment in Carriyo. The key difference from a forward shipment is that the pickup is the customer's address and the dropoff is your store or warehouse.

API Endpoint: POST /shipments

Copy
Copied
{
  "merchant": "YOUR-MERCHANT-ID",
  "entity_type": "REVERSE",
  "references": {
    "partner_order_reference": "ORD-10042",
    "partner_shipment_reference": "RET-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" }
    }
  ],
  "pickup": {
    "contact_name": "Ali Hassan",
    "contact_phone": "+971561234567",
    "address1": "Villa 12, Al Barsha 1",
    "city": "Dubai",
    "state": "Dubai",
    "country": "AE"
  },
  "dropoff": {
    "partner_location_code": "DUBAI-WH-01"
  },
  "collection_schedule": {
    "from": "2026-04-18T09:00:00.000+04:00",
    "to": "2026-04-18T18:00:00.000+04:00"
  }
}

Important: Set "entity_type": "REVERSE" to designate the shipment as a reverse shipment. This affects carrier selection, reporting, and operational handling.

Notice how the addresses are swapped compared to a forward shipment:

  • pickup — the customer's address (where the carrier collects the return)
  • dropoff — your warehouse or store (where the return is delivered), typically referenced by partner_location_code

Step 2: Request collection (if required)

Depending on the carrier, reverse shipments may require a separate collection request to schedule the carrier pickup from the customer. There are three ways to handle this:

Option A: Automatic (recommended) — Enable the "Auto mark ready-to-ship" setting on the carrier account via the Carriyo dashboard. When enabled, Carriyo automatically sends the collection request to the carrier when the shipment is booked.

Option B: Via dashboard — Your operations team manually marks the shipment as "Ready to Ship" in the Carriyo dashboard when the customer confirms they are ready for collection.

Option C: Via API — Trigger the collection request programmatically when your system confirms the customer is ready.

API Endpoint: POST /shipments/{shipment_id}/ready-to-ship

Step 3: Receive status updates via webhook

Set up webhooks to track the reverse shipment through its lifecycle:

  • Booked event — The return shipment was accepted by the carrier.
  • Out for Collection event — The carrier is on the way to collect the return from the customer.
  • Failed Collection Attempt event — The carrier attempted but failed to collect the return. You may need to reschedule or contact the customer.
  • Shipped / **In Transit event — The return is on its way back to your warehouse.
  • Delivered event — The return has been delivered to your warehouse/store.

See Working with Webhooks for setup instructions and retry logic.

Step 4: Handle errors

If the booking or collection request fails, the shipment moves to error status. To resolve, call the confirm or reprocess endpoint with the corrected fields in the request body. The body patches top-level elements — only include the elements you need to correct (e.g. invalid customer address, missing collection schedule). Carriyo will re-validate and attempt to book with the carrier again.

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

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

Reverse shipments vs. the Returns API

Carriyo offers two ways to handle customer returns:

Reverse shipment Returns API
What it does Creates a carrier booking for the physical return shipment Manages the full return request lifecycle — approval, rejection, refund tracking, item condition
When to use You only need the shipping logistics of the return You want to manage the end-to-end return process including business rules
Creates a shipment? Yes — directly Yes — a reverse shipment is created when the return request is approved and shipped
API Shipping API Returns API

If you use the Returns API, the reverse shipment is created automatically as part of the return request workflow — you don't need to create it separately via the Shipping API.

If you manage return approvals and business logic in your own system and only need Carriyo for the carrier booking and tracking, create reverse shipments directly via the Shipping API.

Draft reverse shipments

Like forward shipments, reverse shipments can also be created as drafts using the draft=true query parameter. This is useful when the return is initiated but the collection schedule or customer availability is not yet confirmed. You can update the shipment with collection details later and then confirm it.

See Integrate E-commerce Orders for more details on the draft → confirm flow.