REST API v1

API Reference & Endpoints

Comprehensive endpoint definitions, request headers, parameters, and response schemas.

Authentication & Base URL

Production Base URL

https://api.stswasel.com/v1

Sandbox Base URL

https://sandbox-api.stswasel.com/v1

Pass your API key as a Bearer token in the Authorization HTTP request header: Authorization: Bearer <YOUR_API_KEY>.

POST/v1/shipments

Create Shipment

Creates a new consignment, generates an Airway Bill (AWB) number, and stages the order for courier pickup.

Request Payload

Request Body (JSON)

{
  "sender": {
    "name": "Acme Store Riyadh",
    "phone": "+966501234567",
    "city": "Riyadh",
    "address": "Olaya St, Building 14"
  },
  "recipient": {
    "name": "Sarah Al-Ghamdi",
    "phone": "+966559876543",
    "city": "Jeddah",
    "address": "Al-Zahra Dist, Villa 22"
  },
  "serviceType": "LAST_MILE_STANDARD",
  "codAmount": 285.00,
  "currency": "SAR",
  "pieces": 1,
  "weightKg": 1.5,
  "declaredValue": 285.00,
  "referenceId": "ORDER-98124"
}

Response (200 OK)

Response Body (JSON)

{
  "success": true,
  "trackingNumber": "WASEL-8942-KSA",
  "awbUrl": "https://api.stswasel.com/v1/awb/WASEL-8942-KSA.pdf",
  "status": "LABEL_CREATED",
  "estimatedDelivery": "2026-09-03T18:00:00Z",
  "createdAt": "2026-09-01T10:00:00Z"
}

GET/v1/shipments/{trackingNumber}/track

Track Shipment Status

Fetches the current real-time milestone progress, driver dispatch state, and complete event timeline.

Request Payload

Request Body (JSON)

GET /v1/shipments/WASEL-8942-KSA/track

Response (200 OK)

Response Body (JSON)

{
  "trackingNumber": "WASEL-8942-KSA",
  "status": "OUT_FOR_DELIVERY",
  "statusLabel": "Out for Delivery",
  "originCity": "Riyadh",
  "destinationCity": "Jeddah",
  "estimatedDelivery": "Today by 6:00 PM",
  "driver": {
    "name": "Ahmed K.",
    "phoneMasked": "+966 50 *** 891"
  },
  "events": [
    {
      "status": "OUT_FOR_DELIVERY",
      "location": "Jeddah North Distribution Hub",
      "timestamp": "2026-09-01T08:30:00Z",
      "description": "Courier dispatched for final doorstep delivery"
    },
    {
      "status": "IN_TRANSIT",
      "location": "Jeddah Central Sorting Facility",
      "timestamp": "2026-09-01T04:15:00Z",
      "description": "Inbound processing completed"
    },
    {
      "status": "PICKED_UP",
      "location": "Riyadh Logistics Center",
      "timestamp": "2026-08-31T17:00:00Z",
      "description": "Consignment received from merchant"
    }
  ]
}

POST/v1/rates/calculate

Calculate Shipping Rate

Returns real-time shipping rate estimates and expected delivery service levels between cities.

Request Payload

Request Body (JSON)

{
  "originCity": "Riyadh",
  "destinationCity": "Dammam",
  "weightKg": 2.0,
  "isCod": true,
  "codAmount": 150.00
}

Response (200 OK)

Response Body (JSON)

{
  "serviceOptions": [
    {
      "serviceCode": "SAME_DAY",
      "serviceName": "STS Wasel Same-Day Express",
      "rate": 35.00,
      "currency": "SAR",
      "estimatedDelivery": "Same Day (by 9:00 PM)"
    },
    {
      "serviceCode": "STANDARD_NEXT_DAY",
      "serviceName": "STS Wasel Next-Day Delivery",
      "rate": 22.00,
      "currency": "SAR",
      "estimatedDelivery": "Next Business Day"
    }
  ]
}