API Concepts

The Carriyo REST API gives you full control over managing your shipping and returns process. All requests to the API must be made over HTTPS.

The base URL for the Carriyo API is: https://api.carriyo.com/.

To use the API, you need a Carriyo account. Sign up here.

REST API Overview

The Carriyo API follows REST principles, meaning it uses the HTTP protocol and a predefined set of URLs to represent various resources. HTTP methods like GET, POST, PUT, PATCH, and DELETE allow you to perform different actions on these resources.

API Versioning

Currently, there is only one version of the Carriyo API, which is actively used by all clients. The API is continuously updated, and changes are published in our release notes. Most updates are backward-compatible, such as adding new optional fields or additional response fields.

Breaking Changes

If we introduce a non-backward-compatible (breaking) change, we will notify you in advance. Examples of breaking changes include:

• Adding a new mandatory field in the API request.
• Removing an existing field from the API response.

We always provide at least six months' notice for breaking changes, allowing time to adapt your integration.

JSON Payload Handling

Carriyo's API endpoints consume and produce JSON payloads. Ensure you include the header: Content-type: application/json

Best Practices

• Handle unknown fields : Your client application should ignore any unrecognized fields in responses.
• Avoid reliance on undocumented fields : These fields may change or be removed without notice.

Security

All access to the Carriyo API is secured using HTTPS. Carriyo uses OAuth 2.0 bearer tokens for API authorization. For more details, see our Authentication Guide.

TLS Security

• Carriyo secures all traffic with Transport Layer Security (TLS 1.2) .
• SSL certificates are signed by trusted authorities.
• Certificates are renewed automatically 60 days before expiry. It is the responsibility of the API user to ensure their systems are up to date.

Error Handling

Carriyo uses HTTP status codes to communicate the success or failure of API requests. Common status codes include:

For some 4xx errors, Carriyo returns specific error codes that can be handled programmatically. For example, the error phone_number_invalid is returned when a phone number is incorrectly formatted.

Click here to view the full list of shipping error codes.

Rate Limits

To ensure platform stability, Carriyo enforces rate limits on API requests. We encourage developers to implement industry best practices like request limiting, caching, and retry mechanisms. If rate limits are exceeded, the response will be: 429 Too Many Requests

Rate limits vary by Carriyo pricing plan:

API Permissions

When creating a client application in Carriyo, you assign specific permissions based on what actions the application will perform. Permissions can be read-only or read and write.

Conclusion

The Carriyo API offers powerful tools to manage your shipping processes programmatically. By following REST standards, ensuring security via HTTPS, and using proper error handling and rate-limiting strategies, you can seamlessly integrate Carriyo into your business operations.