1. Create Shipment

Carriyo expects an API to create a new shipment in the carrier system.

Carriyo has an extensive shipment model, and we can generally pass all the information required by the carrier to create a shipment. This includes the merchant's order and shipment reference, pickup address, dropoff address, shipment value, items, parcel weight, dimensions etc.

Tracking Number

Carriyo expects to pass all the required information to register a new shipment and expects a unique tracking number (a.k.a AWB number) back from the carrier. We save the tracking number in the Carriyo database and use it for future operations on the shipment, such as generating a label, tracking shipment status etc.

Some carriers may have multiple unique number or ID per shipment. In these cases, we need the carrier to identify a single unique number or ID that is external facing and can be used by Carriyo and the merchant to identify and track the shipment.

In some cases, where a client chooses to use a Carriyo generated label, we also print the tracking number on the label in the form of a barcode or QR code.

Forward vs Reverse Shipments

As Carriyo is a retail platform, it supports two types of shipments - Forward and Reverse. Both these types are the same in the Carriyo model, except the direction in which the shipment is travelling.

A forward shipment is travelling from the merchant to the end customer, where as a reverse shipment is travelling from the end customer to the mechant.

We need to know how the carrier API supports reverse shipment, and if there are any differences then those need to be highlighted for us to correctly create forward and reverse shipments in the carrier system. You may require additional paramters whilst creating a reverse shipment, or you may have a different endpoint for reverse shipments. We can support these differences as long as this is documented and communicated clearly in your API.

Multi Parcel Shipments

Some of our clients ship multiple parcels per shipment, which we support fully. Hene, we require the carrier API to support the capability to create a shipment with multiple parcels. When a shipment with multiple parcels is created, we can accept multiple tracking numbers one per parcel, however, we still expect an overall tracking number for the shipment. This is important because Carriyo tracks shipment status NOT parcel status.

DO YOU COMPLY?
  1. What is your unique tracking number for shipment?
  2. How do you distinguish between forward and reverse shipments?
  3. How do you support multi parcel shipments?
NOTE
  1. The create shipment endpoint must return a unique ID in the response, which CARRIYO will use as tracking number to track the shipment status.
  2. The API should return a response ideally within 1 or 2 seconds, under normal conditions. CARRIYO will assume the shipment request as failed if no response is received within 30 seconds. If the no response is received within 30s for the shipment creation request, but the shipment was created on your system, then reprocessing the shipment may be rejected by your system as a duplicate if you have a uniqueness check for merchant's e-com order or shipment reference.
  3. If the shipment creation fails in your system, then return a user friendly error, so an end user can manually resolve the error and retry the booking.