API Reference

The Carriyo REST API gives you full control over managing your shipping and return process in Carriyo.

The host for Carriyo API requests is https://api.carriyo.com/.

All requests must be made over HTTPS. The API does not support HTTP.

You will need a Carriyo account to use the Carriyo API. Click here to sign up

REST

What does ‘REST API’ mean anyway? When we say the Carriyo API is based on REST, we mean our API is accessed using the HTTP protocol at a predefined set of URLs. The URLs represent the various resources, on which one or actions can be performed using HTTP methods like GET, POST, PUT, PATCH and DELETE.

Versioning

Currently, there is only one version of the Carriyo API, which is used by all our clients.

However, we continuously update our API. We publish these changes in our release notes. The vast majority of these changes are backwards-compatible. For example, we can add new optional fields to the API request or add new fields to the API response, and these changes are considered backwards-compatible.

Sometimes, we do make changes that may not be backwards compatible. A non backwards-compatible change is a breaking change that alters the documented behaviour, input or ouput of the API in a way that existing client applications cannot continue to use the API without a change on their side. For instance, the addition of a new mandatory field in the API request or a removing an existing field in the API response, are example of non backwards-compatible changes.

When we plan to make a non backwards-compatible (breaking) change to the API, we will send a deprecation notice for the such changes well in advance. We will always give you at least six months notice before any breaking changes are deployed to our API, to allow you to adapt the integration on your side.

JSON Payload

The Carriyo REST API endpoints consume and produce standard application/json payloads. Please use Content-type: application/json in your HTTP header when sending POST, PUT or PATCH requests to ensure that payloads are encoded correctly,

When processing the JSON response, you must ensure that any unrecognised fields in JSON responses are ignored, or handled in a way that it does not cause the client application to crash. The Carriyo API considers the addition of new fields to be backward-compatible for existing clients, and assumes the clients will handle them correctly. In addition, please ensure that your client application does not rely on the presence of undocumented fields. Any undocumented fields or endpoints can be removed or changed at any time without prior notice.

Security

All access to the Carriyo API must be over HTTPS. It is not possible to connect to the API via HTTP (without SSL/TLS). API authorization uses OAuth 2.0 bearer tokens. For more information, see Authentication

HTTPS traffic to Carriyo API is secured through Transport Layer Security (TLS 1.2). The certificates are signed by trusted authorities using a trusted root certificate. The API user must keep their systems updated regarding SSL/TLS capabilities as well as trusted root certificates. All certificates, including the server certificate and any intermediary certificates in the certificate chain, are transmitted as part of the TLS handshake.

Please note, the Carriyo SSL certificates are renewed automatically approximately 60 days before the expiry of the current certificate. This is an automatic activity and it is the obligation of the API user to check on the expiration dates of all certificates in the chain and to renew them whenever necessary.

Error Handling

Carriyo uses HTTP response status codes to indicate the success or failure of your API requests. If your request fails, Carriyo returns an error using the appropriate status code.

In general, there are three status code ranges you can expect:

• 2xx success status codes confirm that your request worked as expected
• 4xx error status codes indicate an error because of the information provided (for example, a required parameter was omitted)
• 5xx error status codes are rare and indicate an error with Carriyo's servers

Carriyo returns an error codes for some 4xx errors that can be handled programatically. For instance, when a phone number is invalid Carriyo returns the error code phonenumberinvalid.

Click here to see the full list of Shipping error codes

Rate Limits

Carriyo APIs are rate-limited to ensure our platform remains stable and fair for everyone. We request developers to use industry standard practices for limiting calls, caching results, and re-trying requests responsibly. When you exceed the limit by making too many requests too quickly, the requests may begin ti throttle and you may receive the "429 Too Many Requests" response.

Carriyo applies different rate limits for different Carriyo pricing plans. Here is a quick summary of what limits apply.

API Permissions

When you create a client application in Carriyo, you can assign one or more permissions to allow the client application to access the resources in Carriyo. The permissions you assign depend on what actions your application will perform in Carriyo. For instance, if your application will only read shipment data then you can assign only READ permission for Shipments.

Here is the list of all supported permissions: