Bagster - Carrier Logistics Platform

Authentication

All API requests require an API key passed in the X-API-Key header.

curl -H "X-API-Key: bgst_your_api_key" \
  https://your-domain.com/api/v1/carriers/quote

Base URL

https://your-domain.com/api/v1

Endpoints

GET/carriers/quote

Get shipping quotes from available carriers.

Query Parameters

origin_countryTurkey or China (required)

destination_countryAfrican country name (required)

weight_kgPackage weight in kg (required)

Example Request

GET /api/v1/carriers/quote?origin_country=Turkey&destination_country=Nigeria&weight_kg=5

Example Response

{
  "origin_country": "Turkey",
  "destination_country": "Nigeria",
  "weight_kg": 5,
  "quotes": [
    {
      "carrier_id": "uuid",
      "carrier_name": "Fast Logistics",
      "price_per_kg": 12.50,
      "total_price": 62.50,
      "estimated_days": 7
    }
  ]
}

POST/orders/create

Create a new shipping order with automatic carrier assignment.

Request Body

origin_countryTurkey or China (required)

destination_countryAfrican country name (required)

weight_kgPackage weight in kg (required)

customer_nameRecipient name (required)

customer_phoneRecipient phone (required)

customer_addressDelivery address (required)

order_referenceYour order ID (optional)

carrier_idSpecific carrier UUID (optional)

Example Request

POST /api/v1/orders/create
Content-Type: application/json

{
  "origin_country": "Turkey",
  "destination_country": "Nigeria",
  "weight_kg": 5,
  "customer_name": "John Doe",
  "customer_phone": "+234 123 456 7890",
  "customer_address": "123 Lagos Street, Lagos, Nigeria",
  "order_reference": "ORD-12345"
}

Example Response

{
  "success": true,
  "order": {
    "id": "uuid",
    "order_reference": "ORD-12345",
    "tracking_number": "TRK-A3B2C1-7D8E",
    "carrier_id": "uuid",
    "origin_country": "Turkey",
    "destination_country": "Nigeria",
    "weight_kg": 5,
    "total_price": 62.50,
    "status": "assigned",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

GET/orders/:tracking_number

Get order status and tracking information.

Path Parameters

tracking_numberOrder tracking number (required)

Example Response

{
  "tracking_number": "TRK-A3B2C1-7D8E",
  "order_reference": "ORD-12345",
  "status": "in_transit",
  "origin_country": "Turkey",
  "destination_country": "Nigeria",
  "weight_kg": 5,
  "total_price": 62.50,
  "carrier": {
    "name": "Fast Logistics",
    "origin_country": "Turkey"
  },
  "estimated_delivery": "2025-01-22T00:00:00Z",
  "timeline": [
    {
      "status": "created",
      "timestamp": "2025-01-15T10:30:00Z",
      "description": "Order created"
    },
    {
      "status": "assigned",
      "timestamp": "2025-01-15T10:30:00Z",
      "description": "Carrier assigned"
    },
    {
      "status": "pickup_done",
      "timestamp": "2025-01-16T14:00:00Z",
      "description": "Package picked up"
    },
    {
      "status": "in_transit",
      "timestamp": "2025-01-17T08:00:00Z",
      "description": "Package in transit"
    }
  ]
}

Order Statuses

pendingOrder created, awaiting carrier assignment

assignedCarrier assigned to the order

pickup_donePackage picked up from origin

in_transitPackage in transit to destination

deliveredPackage delivered to customer

cancelledOrder cancelled

Error Codes

400Bad Request - Invalid parameters

401Unauthorized - Invalid or missing API key

404Not Found - Resource not found

500Internal Server Error

Support

For API support, contact us at api@bagster.io