Key Concepts


Your account in Carriyo is identified using a unique tenant ID. If you have a business or enterprise plan with Carriyo, you will usually have a LIVE tenant and a SANDBOX tenant with different tenant IDs. You can integrate your test environment to the Carriyo SANDBOX tenant and your live environment to the Carriyo LIVE tenant.


You can create one or more merchants under your Carriyo account to represent the brands or business units within your business. For instance, if you have two brands under your business, you can create two mercahnts for each of the brands. A merchant functions like a sub account allowing your segretate data, access configuration per brand. You can also use a merchant to separate your business across different countries.

This feature is only available if you are subscribed to the Business or Enterprise plan. However, if you are on the Starter or Pro plan, then you can only have one merchant under your account.


Carriyo supports multiple entities to represent your shipping data and configuration. Here is a quick overview of each of the concepts that you will come across in Carriyo when using our Shipping module.


The Shipment object represents a unit of items shipped together from an origin to a destination, containing one or more parcels. A shipment can be of type FORWARD or REVERSE. A forward shipment represents a shipment going from the merchant to the customer, where as a reverse shipment represents a shipment going from the customer back to the merchant. Each shipment has two unique IDs - a Carriyo generated ID called the Shipment ID and a merchant generated ID called the Partner Shipment Refernece.

Carriyo also allows merchants to create a draft shipment, which essentially is a way to create a place holder shipment that is not yet confirmed. For instance, a draft shipment can be created in Carriyo as soon a customer’s order is received, and confirmed only when the items are picked and packed in the warehouse. Similarly, in the case of a return, a draft reverse shipment can be created when a return request is received from the customer, and confirmed once the merchant approves the return request.


A shipment attribute allows a merchant to extend the shipment model to pass additional custom information that is not supported natively in the Carriyo data model. As a merchant, you can define your own custom attributes and then use them in your shipment.

Carrier Accounts

A carrier account in Carriyo holds all the settings for a given account with your chosen carrier. The information in the carrier account varies depending upon the carrier and it usually includes infromation such as the account number, the API credentails (API key, username, password etc), the chosen service type etc. If you are business that uses multiple carriers for shipping, then you will have multiple carrier account. For instance, if you have an account with DHL and UPS, you will create two carrier accounts in Carriyo for each of your carrier with all the mandatory settings necessary to book and track your shipments. You can also setup multiple carrier accounts in Carriyo for the same carrier if you have multiple accounts with them for different service types or different countries etc.


A manifest is a collection of shipments that are shipped together from the same location with the same shipping partner. It acts as an instruction to the schedule the collection of the shipments with your carrier.

Automation Rules

Carriyo allows merchants to define rules for carrier selection. These rules are represented in Carriyo as Automation Rules. The automation rules have a set of conditions which assign an inbound shipment to the chosen carrier when the conditions match. The automation rules have a sequence of priorities and the rules are excuted based on this priority. The first rule to match the shipment will determine which carrier the shipment is assigned to. The automation rules are flexible and allow any attribute of the shipment to be used to determine carrier assignment. For example, you can create conditions based on the pickup or dropoff location, the delivery type, the parcel weight, dimensions or any other attribute of the shipment as per your requirement and also assign limits on the number shipments that can be assigned to the carrier.

Service Levels

A service level in Carriyo allows merchants to define their expected timeline for a shipment. The service levels can be applied for each stage of the shipment journey, namely processing (time for processing the shipment in the warehouse or store), collection (time for the carrier to collect the shipment) and delivery (time for the carrier to deliver once shipment is collected). You can also setup the service level customer promise covering the end to end timeline for delivery from the time the customer places an order. The service levels work in the same way as automation rules in terms of the sequence of priority and the conditions to allow you to define different service levels based on your requirements for different types of shipments.


The Carriyo Returns module is used by merchants to manage customer returns. The return journey begins with a customer making a return request. The merchant can manage the entire flow; from approval and tracking the reverse shipment, to finally receiving, QA'ing and refunding the customer for the return.

Return Requests

A return request is the entity that represents the customer's request to return. The request holds information such as the items to return, the reason for return, the expected resolution and information such as the pickup location for the return etc.

Return Reasons

The merchant can configure a custom list of return reasons based on their business requirement. These reasons are presented as options to the customer on the return portal. Common examples include "Not as described online", "Arrived damaged", "Wrong colour or size" etc.

Rejection Reasons

The merchant can also configure a custom list of rejection reasons to use when rejecting a customer's request for return. These reasons are presented to the merchant as options when rejecting a return, and is used to communicate back to the customer.

Return Resolutions

Resolutions are outcomes that the customer is expecting from the return. The options can vary based on what the merchant offers but can be similar to "Credit Card Refund", "Store Credit", "Exchange" and so on.

Core Resources

Delivery Types

A Delivery type is used to represent the type of delivery service chosen by the customer. The delivery types are defined by the merchant and usually have values such as "Same Day", "Next Day", "International" and so on.


A location is usually a store or a warehouse that is used as a pickup or a dropoff point for shipments or return requests. The merchant can setup a location in Carriyo with a code, name, and the address, and use it when creating shipments or returns.

Order Types

An order type represents the order journey chosen by the customer. The order types are defined by the merchant and usually have values such as "Home Delivery", "Click & Collect" etc.

Time Slots

A timeslot is used for scheduling collections (pickup) and deliveries (dropoff). The timeslot has a code and name, along with the starting and ending time. The timeslot can be used as pre-configured options for the customer to choose when creating a shipment or a return.


A webhook enables Carriyo to push real-time updates to your system. Carriyo uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems. The webhook entity holds the configuration such as the triggers for the webhook, the URL to invoke, the headers to pass etc.