Shipping Channels API

Welcome to the Shipping Channels API documentation. This comprehensive guide will help you integrate with our shipping solutions platform to create shipments, generate labels, track parcels, and receive real-time notifications.

Overview

Shipping Channels is a unified shipping platform that connects your application to multiple shipping providers through a single API. Instead of integrating with each carrier separately, you can use our API to:

Create shipments with automatic label generation
Track parcels across all carriers with standardized statuses
Manage multiple carriers through a single integration
Receive webhooks for real-time status updates

Key Features

Multi-Carrier Support

Integrate with 13+ shipping providers through a single API:

Provider	Code	Region
PPL	`ppl`	Czech Republic, Slovakia
DHL	`dhl`	Worldwide
DHL Poland	`dhl_pl`	Poland
DPD	`dpd`	Europe
DPD Poland	`dpd_pl`	Poland
GLS	`gls`	Europe
GLS Poland	`gls_pl`	Poland
SPX (Shopee Express)	`spx`	SE Asia, Central Europe
MRW	`mrw`	Spain, Portugal
Poste Italiane	`poste_italiane`	Italy, Europe, Americas
Allegro	`allegro`	Poland
Baselinker	`baselinker`	Multiple
OneDelivery	`onedelivery`	Czech Republic, Slovakia

Multi-Parcel Shipments

Create shipments with multiple parcels in a single API call. Each parcel receives its own tracking number, and labels are automatically combined into a single downloadable file.

Cash on Delivery (COD)

Support for COD payments with automatic product switching for providers that require separate COD products.

Real-Time Tracking

Monitor shipment status with standardized tracking statuses across all carriers. Receive webhook notifications when statuses change.

Label Generation

Generate shipping labels in multiple formats:

PDF - For standard office printers
ZPL - For Zebra thermal printers
EPL - For other thermal printers (provider-dependent)

Quick Start

1. Get Your API Key

2. Create a Shipping Channel

Configure your carrier credentials:

curl -X POST https://api.shipping-channels.com/v1/shipping-channels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My PPL Channel",
    "provider": "ppl",
    "settings": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "productType": "BUSS",
      "sandboxMode": true
    }
  }'

3. Create a Shipment

Create a shipment with one or more parcels:

curl -X POST https://api.shipping-channels.com/v1/shipments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_channel_id": "ch_123456",
    "label_format": "pdf",
    "sender_contact": {
      "company_name": "My Company",
      "email_address": "sender@example.com",
      "phone_number": "+420123456789"
    },
    "recipient_contact": {
      "first_name": "Jan",
      "last_name": "Novak",
      "email_address": "jan@example.com",
      "phone_number": "+420987654321"
    },
    "origin_address": {
      "street_name": "Hlavni",
      "house_number": "1",
      "city_name": "Praha",
      "postal_code": "11000",
      "country_code": "CZ"
    },
    "destination_address": {
      "street_name": "Namesti",
      "house_number": "5",
      "city_name": "Brno",
      "postal_code": "60200",
      "country_code": "CZ"
    },
    "parcels": [
      {
        "parcel_type": "package",
        "length_dimension": 30,
        "width_dimension": 20,
        "height_dimension": 15,
        "dimension_unit": "CM",
        "weight_amount": 2.5,
        "weight_unit": "KG"
      }
    ]
  }'

4. Download the Label

curl -X GET https://api.shipping-channels.com/v1/shipments/sh_123456/label \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API requests require authentication using API keys. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys can be created and managed from your dashboard. Keep your API keys secure and never expose them in client-side code.

Learn more about authentication.

Base URL

All API requests should be made to:

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

Request Format

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes*	`application/json` (for POST/PUT/PATCH requests)
`Accept`	No	`application/json`

Request Body

All request bodies should be valid JSON:

{
  "field_name": "value",
  "nested_object": {
    "property": "value"
  },
  "array_field": [
    { "item": 1 },
    { "item": 2 }
  ]
}

Response Format

All responses are returned in JSON format with a consistent structure.

Successful Response

{
  "data": {
    "id": "sh_123456",
    "status": "pending",
    ...
  },
  "message": "Shipment created successfully"
}

List Response (Paginated)

{
  "data": [
    { "id": "sh_123456", ... },
    { "id": "sh_123457", ... }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73
  },
  "links": {
    "first": "https://api.shipping-channels.com/v1/shipments?page=1",
    "last": "https://api.shipping-channels.com/v1/shipments?page=5",
    "prev": null,
    "next": "https://api.shipping-channels.com/v1/shipments?page=2"
  }
}

Error Response

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "The field_name field is required."
    ]
  }
}

HTTP Status Codes

Code	Description
`200`	OK - Request succeeded
`201`	Created - Resource created successfully
`204`	No Content - Request succeeded with no response body
`400`	Bad Request - Invalid request format
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource not found
`422`	Unprocessable Entity - Validation errors
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error
`503`	Service Unavailable - Provider unavailable

Common Use Cases

E-commerce Order Fulfillment

Customer places an order
Your system calls the API to create a shipment
Download and print the shipping label
Hand over parcel to carrier
Receive webhook notifications as package moves through delivery

Multi-Carrier Shipping

Create shipping channels for each carrier you use
Select the appropriate channel based on destination, service level, or cost
Create shipments through the unified API
Track all shipments regardless of carrier

Tracking Existing Shipments

Create a tracking parcel with the carrier's tracking number
Receive automatic status updates
Get webhook notifications on status changes
Display tracking information to your customers

Cash on Delivery

Configure COD settings in your shipping channel
Include cash_on_delivery_amount and cash_on_delivery_currency in shipment
System automatically handles COD product requirements
Receive confirmation when COD is collected

Guides

Get started with our detailed guides:

Guide	Description
Shipping Channels	Configure carrier connections
Shipments	Create and manage shipments
Tracking Parcels	Track shipments and status updates
Webhooks	Set up real-time notifications
Error Handling	Handle API errors gracefully

API Reference

Explore the complete API documentation:

Endpoint	Description
Shipping Channels	Manage carrier connections
Shipments	Create shipments and labels
Tracking Parcels	Track shipment status
Webhooks	Configure notifications

Rate Limits

API requests are subject to rate limiting to ensure fair usage. Current limits:

Plan	Requests per minute
Free	60
Standard	300
Enterprise	Custom

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. See Rate Limits for details.

Versioning

The API is versioned through the URL path (/v1/). We maintain backwards compatibility within a major version. Breaking changes will be released in a new version.

Current version: v1

Need Help?

Documentation: Browse our guides and API reference
FAQ: Check the Frequently Asked Questions
Support: Contact our support team for assistance

Changelog

Stay updated with the latest API changes and improvements. Major updates include:

Multi-parcel shipments - Create shipments with multiple parcels
Combined labels - Download all parcel labels in a single file
New providers - Added support for Allegro, Baselinker, and OneDelivery

Overview​

Key Features​

Multi-Carrier Support​

Multi-Parcel Shipments​

Cash on Delivery (COD)​

Real-Time Tracking​

Label Generation​

Quick Start​

1. Get Your API Key​

2. Create a Shipping Channel​

3. Create a Shipment​

4. Download the Label​

Authentication​

Base URL​

Request Format​

Headers​

Request Body​

Response Format​

Successful Response​

List Response (Paginated)​

Error Response​

HTTP Status Codes​

Common Use Cases​

E-commerce Order Fulfillment​

Multi-Carrier Shipping​

Tracking Existing Shipments​

Cash on Delivery​

Guides​

API Reference​

Rate Limits​

Versioning​

Need Help?​

Changelog​