API Reference

api reference

Everything you need to integrate the Serian ShipKit shipping API. Authenticate, quote rates, create labels, track parcels, and handle webhook events.

authentication

All API requests require a valid API key sent in the Authorization header.

Authorization: Bearer sk_live_YOUR_API_KEY

Generate API keys from your dashboard. Each key has specific scopes that control which endpoints it can access.

base url

https://api.serianshipkit.com

api scopes

Each API key is assigned scopes that control access to specific endpoints.

Scope	Description
rates:read	Get shipping rate quotes
shipments:create	Create shipments and labels
shipments:read	List and view shipments
shipments:cancel
tracking:read	Track shipments
addresses:validate	Validate shipping addresses
services:read	List available shipping services
pickups:create	Schedule carrier pickups
pickups:read	View pickup details
webhooks:manage	Manage webhook endpoints
manifests:manage
batches:create

webhook events

Subscribe to events to receive real-time notifications. Payloads are signed with HMAC-SHA256 using your webhook secret. Verify via the X-Webhook-Signature header.

shipment.createdshipment.updatedshipment.deliveredshipment.cancelledtracking.updatedlabel.created

error handling

All errors follow a consistent format. Every response includes a request_id for debugging.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "abc123def456"
}

Code	HTTP	Description
validation_error	400	Request body or parameters are invalid
unauthorized	401	Missing or invalid API key
forbidden	403	API key lacks required scope
not_found	404	Resource not found
rate_limit_exceeded	429	Too many requests
carrier_error	502	Carrier API returned an error
internal_error	500	Unexpected server error

api endpoints

POST/api/v1/ratesrates:read

Get real-time shipping rates from carriers

Request Body

{
  "carrier": "fedex (optional, defaults to fedex)",
  "shipper": {
    "name": "string",
    "street1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "GH"
  },
  "recipient": {
    "name": "string",
    "street1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "GH"
  },
  "parcels": [
    {
      "length": 20,
      "width": 15,
      "height": 10,
      "weight": 2.5,
      "dimension_unit": "CM",
      "weight_unit": "KG"
    }
  ]
}

Response Example

{
  "rates": [
    {
      "carrier": "fedex",
      "service_type": "FEDEX_INTERNATIONAL_PRIORITY",
      "service_name": "FedEx International Priority",
      "total_charge": 45.5,
      "currency": "USD",
      "estimated_delivery_days": 3
    }
  ],
  "request_id": "abc123"
}

POST/api/v1/shipmentsshipments:create

Create a shipment and generate a shipping label

Request Body

{
  "carrier": "fedex (optional)",
  "shipper": {
    "name": "string",
    "street1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "GH"
  },
  "recipient": {
    "name": "string",
    "street1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "GH"
  },
  "parcels": [
    {
      "length": 20,
      "width": 15,
      "height": 10,
      "weight": 2.5
    }
  ],
  "service_type": "FEDEX_INTERNATIONAL_PRIORITY",
  "label_format": "PDF | PNG | ZPL (default: PDF)"
}

Response Example

{
  "id": "shipment_abc123",
  "carrier": "fedex",
  "tracking_number": "1234567890",
  "label_url": "https://...",
  "rate": {
    "total_charge": 45.5,
    "currency": "USD"
  },
  "status": "created",
  "request_id": "abc123"
}

GET/api/v1/shipmentsshipments:read

List all shipments for your account

Query Parameters

limit	number	Results per page (default: 20)
offset	number	Pagination offset (default: 0)

GET/api/v1/trackingtracking:read

Track a shipment by tracking number

Query Parameters

tracking_number*	string	The tracking number
carrier	string	Carrier name (default: fedex)

Response Example

{
  "tracking_number": "1234567890",
  "carrier": "fedex",
  "status": "In Transit",
  "estimated_delivery": "2025-01-15T12:00:00Z",
  "events": [
    {
      "timestamp": "2025-01-12T08:00:00Z",
      "status": "PICKED_UP",
      "description": "Picked up",
      "location": "Accra, GA, GH"
    }
  ],
  "request_id": "abc123"
}

POST/api/v1/addresses/validateaddresses:validate

Validate and normalize a shipping address

Request Body

{
  "name": "string",
  "street1": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "country": "GH"
}

Response Example

{
  "is_valid": true,
  "normalized_address": {
    "name": "John Doe",
    "street1": "123 MAIN ST",
    "city": "ACCRA",
    "state": "GA",
    "zip": "00233",
    "country": "GH"
  },
  "messages": [],
  "request_id": "abc123"
}

POST/api/v1/servicesservices:read

Get available shipping services for a route

Request Body

{
  "origin": {
    "name": "string",
    "street1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "GH"
  },
  "destination": {
    "name": "string",
    "street1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "US"
  }
}

POST/api/v1/pickupspickups:create

Schedule a carrier pickup

Request Body

{
  "address": {
    "name": "string",
    "street1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "GH"
  },
  "pickup_date": "2025-01-15",
  "ready_time": "09:00",
  "close_time": "17:00",
  "carrier": "fedex (optional)"
}

POST/api/v1/webhookswebhooks:manage

Request Body

{
  "url": "https://your-site.com/webhooks/shipping",
  "events": [
    "shipment.created",
    "shipment.delivered",
    "tracking.updated"
  ]
}

GET/api/v1/webhookswebhooks:manage

List all webhook endpoints

PATCH/api/v1/webhookswebhooks:manage

Update a webhook endpoint

Request Body

{
  "webhook_id": "uuid",
  "url": "https://new-url.com/webhooks (optional)",
  "events": [
    "shipment.created (optional)"
  ],
  "is_active": "boolean (optional)"
}

DELETE/api/v1/webhooks?webhook_id=uuidwebhooks:manage

Delete a webhook endpoint