Ship with Code

This is a general guide for anyone integrating delivery services. It provides a step guide to arrange your first delivery along with a description of the flow of events once your delivery is arranged.

Step Guide to Arrange Delivery

Step 1: Add all packaging items

Before you begin getting rates or arranging deliveries, the first thing you want to do is create the Packaging items that will be used to wrap your parcels. Packaging items are materials like Fliers, Boxes, Envelopes, etc.

Step 2: Create Pickup & Delivery Address

To start getting rates, first you need to create the pickup and delivery address for your particular shipment. If your intention is to simply get rates and you're not looking to arrange a delivery yet, you only need to provide the country, state and city for the pickup or delivery address. If you create an address in this way, once you're ready to arrange a delivery, you need to update the all other details such as phone, email, name, etc.

Step 3: Create Parcel

The final step to retrieving rates is to provide information on the items that are being delivered, you can do this by creating a parcel. To create a parcel, you need to provide informaiton for each item as described in the Parcel Item section as well as one of the packaging options created in Step 1.

Step 4: Retrieve Rates

With your pickup address, delivery address and created parcel, you're now ready to get rates! Simply call the get rates for shipment endpoint to retrieve rates from all active carriers on your account, that can complete the delivery.

Step 5: Arrange Pickup

Once you've generated a specific rate, there are 2 steps to complete your delivery.

First, you need to add a shipment with your pickup address, delivery address and parcel. When creating a shipment, you can also include metadata to provide additional context for your own applications.

Once the shipment is added, simply retrieve the shipment_id, include the rate_id from Step 4 and call the arrange pickup endpoint.

Flow of Events after Arranging Delivery

Once your delivery is arranged, T-Ship uses Webhook Events to keep your application up to date on changes to the status of your shipment. To receive webhook events, you have to create webhooks. To understand how to handle webhook events within your applications, please see the section on Handling Webhook Events.

Below, we'll give examples of events to look out for and possible actions to take within your applications when each event is triggered.

Shipment Created Event (shipment.created):

When you arrange pickup for a shipment, the shipment.created event is triggered. This event will contain the generated shipment with all the information needed to track the shipment as well as documentation such as Waybills, Commercial Invoice, etc. This information is usually contained in the extras object in the shipment.

Shipment Updated Event (shipment.updated):

As the shipment progresses through multiple stages, e.g. Rider Pickup, Transits through port of a different country, Customs clearance, etc. T-Ship will generate shipment.updated events. When this event is triggered, information on the latest update will be contained in the events object of the shipment.

If you're not concerned with detailed changes and simply want general updates, you can simply look out for changes in the status of the shipment, e.g. from "confirmed" to "in-transit" or from "in-transit" to "delivered".

For the best results, we recommend looking out for changes to the shipment events and also changes to the status. Shipment events allow you to keep your customers updated on every change over the course of the delivery, while the general changes can be used as triggers for notifications e.g. a status change from "confirmed" to "in-transit" can trigger a notification in your application to let a recipient know that their delivery is on the way.

Shipment Cancelled Event (shipment.cancelled):

If a shipment is cancelled, the shipment.cancelled event is generated. Shipments can be cancelled for a number of reasons:

• User cancelled shipment.

• Carrier cancels shipment for unforseen reason.

• Payment for shipment fails.

Once a shipment is cancelled, a reversal of funds is triggered to return the total amount paid to your wallet so you can re-arrange delivery. Please bear in mind that after a shipment is cancelled, you will need to repeat Steps 4 & 5 in the guide to re-arrange delivery.