Skip to main content

API Overview

The Shipping Channels API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL​

All API requests should be made to the following base URL:

https://api.shipping-channels.com/v1

API Versioning​

The Shipping Channels API is versioned through the URL path. The current version is v1. We may introduce new API versions in the future to maintain backward compatibility while adding new features.

Content Type​

API requests with a request body should specify the content type as JSON:

Content-Type: application/json

Authentication​

The Shipping Channels API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Authentication is provided by including your API key in the Authorization header of each request:

Authorization: Bearer YOUR_API_KEY

Failure to provide a valid API key will result in a 401 Unauthorized response.

Request Format​

The Shipping Channels API accepts request data in JSON format. Make sure to set the Content-Type header to application/json.

Response Format​

All responses are returned in JSON format. Successful responses will have a 2xx status code and include the requested data. Error responses will have a 4xx or 5xx status code and include an error message.

Example successful response:

{
  "data": {
    "id": "ch_123456",
    "name": "DHL Channel",
    "status": "active",
    "created_at": "2025-03-26T12:00:00Z",
    "updated_at": "2025-03-26T12:00:00Z"
  }
}

Example error response:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: name",
    "status": 400
  }
}

Pagination​

For endpoints that return lists of objects, the Shipping Channels API uses cursor-based pagination. The response will include a meta object with pagination details and a links object with URLs for the next and previous pages.

Example paginated response:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://api.shipping-channels.com/v1/shipping-channels",
    "per_page": 15,
    "to": 15,
    "total": 75
  },
  "links": {
    "first": "https://api.shipping-channels.com/v1/shipping-channels?page=1",
    "last": "https://api.shipping-channels.com/v1/shipping-channels?page=5",
    "next": "https://api.shipping-channels.com/v1/shipping-channels?page=2",
    "prev": null
  }
}

Rate Limits​

The Shipping Channels API enforces rate limits to ensure the stability and reliability of the service. Rate limits are applied on a per-API key basis. By default, each API key is allowed to make up to 100 requests per minute.

If you exceed the rate limit, the API will return a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before making another request.

Idempotency​

To prevent duplicate operations, some endpoints support idempotency. You can provide an Idempotency-Key header with a unique key for each request. If the same idempotency key is used for multiple requests, only the first request will be processed.

Idempotency-Key: a-unique-key-for-this-operation

CORS​

The Shipping Channels API supports Cross-Origin Resource Sharing (CORS) for AJAX requests from any origin. This allows you to interact securely with our API from a client-side web application.