Integration requirements

This page covers what Carriyo needs from your API to integrate as a carrier connector. Two layers: the protocol expectations (REST, auth, webhooks) at the top, then the operations Carriyo expects you to support, each with the questions Carriyo will ask during the discovery call.

REST API

Carriyo integrates with carrier systems through REST APIs. Carriyo does not support batch or file-based integrations through FTP, EDI, or similar methods.

The preferred starting point is the Carriyo Plug & Play API specification. If you can't implement it, Carriyo can build a custom integration against your API, but you must provide a clear API specification (OpenAPI format) with detailed examples.

Carriyo builds one reusable connector per carrier. That connector serves all Carriyo merchants who use your service. To make that possible, provide a set of shared API credentials that Carriyo can use across all merchants, not per-merchant credentials.

Carriyo supports these authentication methods:

• Basic authentication
• OAuth 2.0
• Header-based API key authentication

Carriyo does not support clear-text usernames and passwords in the request body.

Response time: Carriyo expects all API calls to respond within 30 seconds.

Webhook support

Carriyo gives merchants real-time shipment visibility. That depends on carriers pushing status updates through webhooks. Carriyo processes each update immediately on receipt.

Carriyo prefers a one-time webhook setup on your side. Configure your system to recognize shipments that originate from Carriyo and push status updates to Carriyo automatically for all of them. This avoids per-merchant configuration every time a new merchant activates your carrier.

If you're using Plug & Play, the specification defines the webhook payload structure. If you're on a custom integration, Carriyo can work with your existing webhook structure, but the payload must include:

1. Tracking number, your unique tracking number for the shipment.
2. Status code, the current status.
3. Status change date, date and time the status changed.
4. Current location, current location of the shipment, including geo coordinates where available.
5. Additional details, driver name, driver phone, recipient name, proof of delivery, and similar fields where available.

---

Operations Carriyo expects you to support

The seven operations below are the integration surface area for most carriers. Not every carrier needs to support every operation, but Carriyo will ask about each during the discovery call so the connector design reflects what you actually offer.

1. Create shipment

Carriyo passes the full shipment payload (pickup address, dropoff address, items, parcel weight, dimensions, value, merchant references, etc.) to your create shipment endpoint. Your API returns a unique tracking number (AWB number) that Carriyo persists and uses for every subsequent operation on the shipment.

Special cases Carriyo needs to know about:

• Multiple identifiers per shipment: if your system issues more than one ID per shipment, nominate the single external-facing identifier Carriyo and the merchant should use.
• Forward vs reverse shipments: Carriyo supports both. If your reverse-shipment flow uses different parameters or a different endpoint, document the differences.
• Multi-parcel shipments: Carriyo supports multiple parcels per shipment. Your API must accept a list of parcels in the create-shipment call.

Confirm:

• Do you have a create-shipment endpoint that returns a unique tracking number?
• How do you support reverse shipments: same endpoint with a flag, or a separate endpoint?
• Do you support multiple parcels per shipment in a single call?

2. Fetch label

Some carriers return the label inline in the create-shipment response. Others expose a separate endpoint to fetch it. Carriyo supports both, but prefers a separate endpoint that returns a file URL for Carriyo to download.

Formats and sizes Carriyo accepts:

• PDF and ZPL are the most common; both supported.
• Image formats (PNG, JPG) are accepted; Carriyo converts to PDF for standardization.
• 4×6 inches (A6) is the most popular size; Carriyo expects you to support it. Other sizes (4×4, A4, etc.) are also accepted.

If your system doesn't generate labels at all, Carriyo can generate one for the merchant. Some merchants need custom label formats; in those cases, Carriyo may need additional fields (e.g., a Routing or Hub Code for sorting) printed on the label, which means your create-shipment response must return that data.

Confirm:

• Do you have a label endpoint, or do you return the label in the create-shipment response?
• What label sizes and formats do you generate?
• Do you accept Carriyo-generated custom labels for your ground operations?

3. Schedule collection

Some carriers collect on-demand the moment a shipment is ready; others require an explicit collection request. Carriyo supports both, but prefers a separate collection endpoint so merchants can schedule (and reschedule) collection independently of shipment creation.

Carriyo also supports sending collection requests in bulk, useful for high-volume merchants where one call covers many shipments.

Confirm:

• Do you have a separate endpoint to schedule shipment collection?
• Do you support bulk collection requests?
• What are the restrictions on scheduling (lead time, cutoff hours, day-of-week constraints)?

4. Schedule delivery

Carriyo can send delivery-schedule information to your API when the carrier supports it. The conversation Carriyo needs to have during integration design:

• Does your API accept a delivery time-window or date on the create-shipment call, on a separate endpoint, or both?
• Until what point in the shipment journey can the delivery be scheduled or rescheduled?
• What restrictions apply (lead time, slot availability, geographic coverage)?

Confirm:

• Do you support scheduled deliveries?
• Can deliveries be rescheduled after the shipment has been collected?
• What is the latest point a delivery slot can be changed?

5. Shipment cancellation

A shipment can be cancelled in Carriyo any time before it ships (i.e., before the carrier collects it). After collection, the shipment must complete its journey (delivered or returned to origin), Carriyo never sends a cancellation for a collected shipment.

When a merchant cancels in Carriyo, Carriyo notifies your API via a cancellation call.

Confirm:

• Do you have an API endpoint to cancel shipments?
• Can a cancelled shipment be rebooked later, or does that produce a duplicate-shipment error on your side?

6. Shipment tracking

Webhooks are the primary status-update channel (see Webhook support above). On top of that, Carriyo runs an on-demand polling safety net: if a shipment hasn't received a status update for 24 hours, Carriyo calls your tracking endpoint to refresh.

Your tracking endpoint must:

• Accept the tracking number as input.
• Return the full status history for the shipment: status code and status-change date for every status the shipment has been in, not just the current one.
• Include current location and additional details (driver, recipient, POD) where available, same as the webhook payload.

Confirm:

• Do you have a tracking endpoint that returns full status history (not just the latest status)?
• Does the response include the same level of detail as your webhook payloads?

7. Field mappings

Carriyo acts as an intermediary between merchants and carrier systems. To make the data on both sides line up, Carriyo handles mappings in two areas:

City, state, and area mappings. Carriyo maintains a comprehensive directory of states, cities, and areas for several countries. If your API expects specific location values different from what Carriyo holds, mappings translate between the two.

• Plug & Play integrations: mapping responsibility is on your side: translate the Carriyo values to your internal values within your endpoint.
• Custom integrations: Carriyo handles the mapping internally, provided you give Carriyo a comprehensive list of the values your API accepts.

The Carriyo geo list is available for download, see the Geo list reference.

Status mappings. Accurate translation between your shipment statuses and Carriyo's standard statuses is critical for merchant tracking.

• Plug & Play: you translate your internal statuses to the corresponding Carriyo statuses before sending the webhook or tracking response.
• Custom integrations: Carriyo handles the mapping internally, provided you supply the full list of statuses your carrier emits.

Mapping notes:

• Map forward and reverse shipments separately if your status set differs between them.
• All Carriyo red statuses are mandatory.
• Yellow statuses are optional: map any that apply.
• Grey statuses are internal to Carriyo; do not map.

The full Carriyo status list and meaning of each status code is available in the Status codes reference.

---