SDKs / Python

Python SDK

The official Python client for the Serian ShipKit API. Includes type hints, automatic retries, and a clean Pythonic interface.

Installation

bash

pip install serianshipkit

Requires Python 3.9 or later.

Quick start

python

import os
from serianshipkit import SerianLogistics

sl = SerianLogistics(api_key=os.environ["SERIAN_API_KEY"])

# 1. Get rates
rates = sl.rates.list(
    shipper={
        "name": "Accra Warehouse",
        "street1": "12 Independence Ave",
        "city": "Accra",
        "state": "GA",
        "zip": "00233",
        "country": "GH",
    },
    recipient={
        "name": "Kwame Mensah",
        "street1": "45 Oxford St",
        "city": "London",
        "state": "LND",
        "zip": "W1D 2DZ",
        "country": "GB",
    },
    parcels=[
        {
            "length": 30,
            "width": 20,
            "height": 15,
            "weight": 2.5,
            "dimension_unit": "CM",
            "weight_unit": "KG",
        }
    ],
)

print(rates)  # list[dict]

# 2. Create a shipment with the cheapest rate
shipment = sl.shipments.create(
    {"rate_id": rates[0]["rate_id"], "reference": "ORDER-1234"}
)

print(shipment["tracking_number"])

Configuration

Parameter	Type	Default	Description
`api_key`	`str`	—	Your API key (`sk_live_` or `sk_test_`)
`base_url`	`str`	`https://api.serianshipkit.com`	Override the API base URL
`retries`	`int`	`2`	Number of automatic retries on 5xx / network errors

API reference

Rates

Method	HTTP	Description
`sl.rates.list(**body)`	`POST /rates`	Get shipping rates for a parcel

Shipments

Method	HTTP	Description
`sl.shipments.create(body, idempotency_key=None)`	`POST /shipments`	Create a shipment and generate a label
`sl.shipments.get(shipment_id)`	`GET /shipments/:id`	Retrieve a shipment by ID
`sl.shipments.list(**params)`	`GET /shipments`	List shipments with optional filters
`sl.shipments.cancel(shipment_id)`	`DELETE /shipments/:id`	Cancel a shipment

Tracking

Method	HTTP	Description
`sl.tracking.get(tracking_number, carrier=None)`	`GET /tracking`	Get tracking events for a shipment

Error handling

Every API error raises a SerianLogisticsError with structured metadata for logging or retry logic.

python

from serianshipkit import SerianLogistics, SerianLogisticsError

sl = SerianLogistics(api_key=os.environ["SERIAN_API_KEY"])

try:
    sl.shipments.get("ship_nonexistent")
except SerianLogisticsError as e:
    print(e.status)      # 404
    print(e.code)        # "shipment_not_found"
    print(e.request_id)  # "req_abc123"
    print(e.body)        # full error response body

Test mode

Use an API key prefixed with sk_test_ to hit the sandbox environment. Test-mode shipments never reach a carrier and labels are watermarked. Switch to sk_live_when you’re ready for production.

For full endpoint documentation, see the API Reference.