Table of contents

ShaQ Express Public API Documentation

Welcome to the ShaQ Express Public API. This documentation provides partners and developers with the endpoints needed to seamlessly manage packages, shipments, and receive tracking updates.

API Environment

• Version: 1.0
• Development Base URL: https://test-partner.shaqexpress.com/api/v1

---

Standard Headers

All requests made to the API should contain the following standard HTTP headers:

Header	Type	Description
Content-Type	application/json	Requires JSON requested bodies
Accept	application/json	Expects JSON response bodies

(Note: Protected endpoints will also require an Authorization: Bearer <token> header, which you acquire from logging in).

---

Package Statuses

Our system uses various statuses to track the lifecycle of a package. Below is the comprehensive list of statuses you may receive:

📦 Pending & Collection

• pending : Package is yet to be received from Partner
• received : Package has been received from Partner
• ready_for_pickup : Package is ready for customer pickup

🚚 Transit & Dispatch

• shipped : Package has been shipped by Partner
• assigned : Package has been assigned to a Rider
• in_transit : Package is in transit to closest warehouse
• dispatched : Package is en-route to be delivered

✅ Delivery Outcomes

• confirmed : Customer has been called and delivery confirmed
• delivered : Package was successfully delivered to customer

⚠️ Issues & Exceptions

• not_delivered : Attempted delivery but couldn't complete it
• rescheduled : Package delivery rescheduled for new delivery attempt
• customer_hold : Delivery is on hold based on customer request
• customer_unreachable : Delivery is on hold because customer is unreachable
• suspected_scam : Delivery is on hold due to suspected scam

🔙 Returns

• return_in_progress : Package is being prepared to be sent back to Partner
• returned_to_sender : Package has been sent back to Partner
• return_home : Package is being returned to ShaQ Express central warehouse after multiple unsuccessful delivery to prepare for being returned to partner

---

API Endpoints

Login

POST /auth/login

Get authentication token for subsequent requests. As a security measure the token is valid for 7 days after which a new one will have to be generated using the /auth/login route.

Request

Parameter	Type	Description
identifier	string	required.
secret	string	required.

Response

200

{
    "message": "Request successful",
    "data": {
        "token": "UtXdU9HODhjdmtTNkRtUWNsVlM4OWI1d2Z2TXVIanlkRk"
    }
}

Get Packages

GET /packages?page=1&limit=1

Get all packages

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Response

200

{
    "message": "Request successful",
    "data": {
        "list": [
            {
                "partnerRef": "FGVHKJ567",
                "trackingNumber": "20250410X51DIQ",
                "customerName": "Kwaku Ananse",
                "customerPhone1": "+233244100200",
                "customerPhone2": null,
                "sourceCountry": "Ghana",
                "sourceAddressLine1": "Accra Spintex",
                "sourceAddressLine2": null,
                "destinationCountry": "Ghana",
                "destinationRegion": "Greater Accra",
                "destinationCity": "Accra",
                "destinationAddressLine1": "UPSA Hall, Room 3",
                "destinationAddressLine2": null,
                "destinationPostalCode": null,
                "length": 0,
                "height": 5,
                "weight": 1.2,
                "description": "iPhone 16 pro max black edge silver back casing",
                "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
                "units": 1,
                "type": "box",
                "value": "300.00",
                "amountToCollect": "300.00",
                "paymentCollector": "shaq",
                "handling": "normal",
                "specialInstructions": null,
                "status": "delivered",
                "statusDescription": "Package was successfully delivered to customer",
                "latitude": null,
                "longitude": null,
                "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
                "dateCreated": "2025-04-10 11:15",
                "items": [
                    {
                        "name" : "iPhone 6",
                        "quantity" : 1,
                    },
                    {
                        "name" : "iPhone 14 Pro",
                        "quantity" : 2,
                    }
                ]
            },
            {
                "partnerRef": "FGVHKJ567",
                "trackingNumber": "20250410X51DIQ",
                "customerName": "Kwaku Ananse",
                "customerPhone1": "+233244100200",
                "customerPhone2": null,
                "sourceCountry": "Ghana",
                "sourceAddressLine1": "Accra Spintex",
                "sourceAddressLine2": null,
                "destinationCountry": "Ghana",
                "destinationRegion": "Greater Accra",
                "destinationCity": "Accra",
                "destinationAddressLine1": "UPSA Hall, Room 3",
                "destinationAddressLine2": null,
                "destinationPostalCode": null,
                "length": 0,
                "height": 5,
                "weight": 1.2,
                "description": "iPhone 16 pro max black edge silver back casing",
                "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
                "units": 1,
                "type": "box",
                "value": "300.00",
                "amountToCollect": "300.00",
                "paymentCollector": "shaq",
                "handling": "normal",
                "specialInstructions": null,
                "status": "pending",
                "statusDescription": "Package is yet to be received from Partner.",
                "latitude": null,
                "longitude": null,
                "proofPhotoUrl": null,
                "dateCreated": "2025-04-10 11:15",
                "items": [
                    {
                        "name" : "iPhone 6",
                        "quantity" : 1,
                    }
                ]
            }
        ],
        "meta": {
            "total": 2,
            "perPage": 15,
            "currentPage": 1,
            "lastPage": 1
        }
    }
}

Get single Package

GET /packages/{partnerRef}

Get package details

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Response

200

{
    "message": "Request successful",
    "data": {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceCountry": "Ghana",
        "sourceAddressLine1": "Accra Spintex",
        "sourceAddressLine2": null,
        "destinationCountry": "Ghana",
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "units": 1,
        "type": "box",
        "value": "300.00",
        "amountToCollect": "300.00",
        "paymentCollector": "shaq",
        "handling": "normal",
        "specialInstructions": null,
        "status": "not_delivered",
        "statusDescription": "Attempted delivery but couldn't complete it.",
        "latitude": null,
        "longitude": null,
        "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "dateCreated": "2025-04-10 11:15",
        "items": [
            {
                "name" : "iPhone 6",
                "quantity" : 1,
            },
            {
                "name" : "iPhone 14 Pro",
                "quantity" : 2,
            }
        ],
        "replacementType": "end",
        "previousOrderId": 411968,
         "trackingHistory": [
            {
                "name": "not_delivered",
                "description": "Attempted delivery but couldn't complete it.",
                "date": "2025-07-16 09:00",
                "comment": "Customer was unreachable upon arrival. Package rescheduled for 2nd delivery attempt."
            },
            {
                "name": "dispatched",
                "description": "Package is en-route to deliver.",
                "date": "2025-07-15 15:45",
                "comment": null
            },
            {
                "name": "confirmed",
                "description": "Customer has been called and delivery confirmed.",
                "date": "2025-07-15 15:45",
                "comment": null
            },
            {
                "name": "received",
                "description": "Package has been received from Partner.",
                "date": "2025-07-15 15:38",
                "comment": null
            },
            {
                "name": "pending",
                "description": "Package is yet to be received by Partner.",
                "date": "2025-07-14 10:38",
                "comment": null
            }
        ]
    }
}

Delete pending Package

DELETE /packages/{partnerRef}

Delete a package. Only pending packages can be deleted

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Response

200

{
    "message": "Package deleted",
    "data": null
}

Create Packages

POST /packages/bulk

Create multiple packages

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Request

Parameter	Type	Description
packages	array	required.
packages.*.tracking_number	string	optional.
packages.*.partner_ref	string	required.
packages.*.customer_name	string	required.
packages.*.customer_phone_1	string	required.
packages.*.customer_phone_2	string	optional.
packages.*.source_country_iso2	string	required.
packages.*.source_address_line_1	string	required.
packages.*.source_address_line_2	string	optional.
packages.*.destination_region	string	required if region_id is empty.
packages.*.destination_city	string	required.
packages.*.destination_address_line_1	string	required.
packages.*.destination_address_line_2	string	optional.
packages.*.destination_postal_code	string	optional.
packages.*.length	decimal	optional.
packages.*.height	decimal	optional.
packages.*.weight	decimal	optional.
packages.*.description	string	required.
packages.*.units	string	required.
packages.*.type	string	required . in parcel, box
packages.*.handling	string	required . in normal, fragile
packages.*.special_instructions	string	optional.
packages.*.latitude	decimal	optional.
packages.*.longitude	decimal	optional.
packages.*.value	decimal	required.
packages.*.amount_to_collect	decimal	optional. defaults to package value.
packages.*.payment_collector	string	optional. in shaq, partner (Specify who collects money from customer. Defaults to agreed payment collector indicated in business agreement.)
packages.*.items	array	required.
packages.*.region_id	integer	required if destination_region is empty.
packages.*.items	array	required.

Response

200

{
    "message": "Packages created successfully",
    "data": null
}

Create Shipment

POST /shipments

Create a shipment that represents the physical shipment of packages that will be sent to ShaQ Express.

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Request

Parameter	Type	Description
packages	array	required.
packages.*.tracking_number	string	optional.
packages.*.partner_ref	string	required.
packages.*.customer_name	string	required.
packages.*.customer_phone_1	string	required.
packages.*.customer_phone_2	string	optional.
packages.*.source_country_iso2	string	required.
packages.*.source_address_line_1	string	required.
packages.*.source_address_line_2	string	optional.
packages.*.destination_region	string	required if region_id is empty.
packages.*.destination_city	string	required.
packages.*.destination_address_line_1	string	required.
packages.*.destination_address_line_2	string	optional.
packages.*.destination_postal_code	string	optional.
packages.*.length	decimal	optional.
packages.*.height	decimal	optional.
packages.*.weight	decimal	optional.
packages.*.description	string	required.
packages.*.units	string	required.
packages.*.type	string	required . in parcel, box
packages.*.handling	string	required . in normal, fragile
packages.*.special_instructions	string	optional.
packages.*.latitude	decimal	optional.
packages.*.longitude	decimal	optional.
packages.*.value	decimal	required.
packages.*.amount_to_collect	decimal	optional. defaults to package value.
packages.*.payment_collector	string	optional. in shaq, partner (Specify who collects money from customer. If not provided, it will default to agreed payment collector indicated in business agreement.)
packages.*.items	array	required.
packages.*.region_id	integer	required if destination_region is empty.

Response

200

{
    "message": "Request successful",
    "data": {
        "reference": "PAR-20260322053800",
        "date": "2026-03-22 05:38",
        "packages": [
            {
                "partnerRef": "qwertyui1a1aaqweqqaqx",
                "trackingNumber": "C561819A",
                "customerName": "Hema Mirpuri",
                "customerPhone1": "+233244601165",
                "customerPhone2": null,
                "sourceAddressLine1": "Accra spintex basket junction",
                "sourceAddressLine2": null,
                "destinationRegion": "Greater Accra",
                "destinationCity": "Tesano",
                "destinationAddressLine1": "OPP total filling station Abeka tesano",
                "destinationAddressLine2": null,
                "destinationPostalCode": null,
                "length": 0,
                "height": 0,
                "weight": 0,
                "description": "Color Splicing Cotton Rope Storage Basket Toys Clothes Sundries Storage Basket AB-026 - Beige Yellow+White",
                "units": 7,
                "type": "parcel",
                "handling": "normal",
                "specialInstructions": null,
                "status": "pending",
                "statusDescription": "Package is yet to be received by Partner",
                "latitude": null,
                "longitude": null,
                "value": "1468.00",
                "amountToCollect": "1468.00",
                "paymentCollector": "shaq",
                "date": "2026-03-22 05:38",
                "trackingUrl": "https://dev.tracking-website.pages.dev/packages/C561819A",
                "items": [
                    {
                        "name": "14cm Alya Glass Cookie Holder - Transparent",
                        "quantity": 4
                    },
                    {
                        "name": "10.6 Color Splicing Cotton Rope Storage Basket Toys Clothes Sundries Storage Basket AB-026 - Beige Yellow+White",
                        "quantity": 1
                    },
                    {
                        "name": "6 Pieces Nossa 21cm Cake Plate Set",
                        "quantity": 1
                    }
                ]
            }
        ]
    }
}

Get single Shipment

GET /shipments/{reference}

Get package details

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Response

200

{
    "message": "Request successful",
    "data": {
        "reference": "SAAM-20260322053800",
        "date": "2026-03-22 05:38",
        "packages": [
            {
                "partnerRef": "qwertyui1a1aaqweqqaqx",
                "trackingNumber": "C561819A",
                "customerName": "Kwaku Ananse",
                "customerPhone1": "+233244100200",
                "customerPhone2": null,
                "sourceAddressLine1": "Accra spintex basket junction",
                "sourceAddressLine2": null,
                "destinationRegion": "Greater Accra",
                "destinationCity": "Accra",
                "destinationAddressLine1": "UPSA Hall, Room 3",
                "destinationAddressLine2": null,
                "destinationPostalCode": null,
                "length": 0,
                "height": 5,
                "weight": 1.2,
                "description": "iPhone 16 pro max black edge silver back casing",
                "units": 1,
                "type": "box",
                "handling": "normal",
                "specialInstructions": null,
                "status": "pending",
                "statusDescription": "Package is yet to be received by Partner",
                "latitude": null,
                "longitude": null,
                "value": "1468.00",
                "amountToCollect": "1468.00",
                "paymentCollector": "shaq",
                "date": "2026-03-22 05:38",
                "trackingUrl": "https://dev.tracking-website.pages.dev/packages/C561819A",
                "items": [
                    {
                        "name": "14cm Alya Glass Cookie Holder - Transparent",
                        "quantity": 4
                    },
                    {
                        "name": "10.6 Color Splicing Cotton Rope Storage Basket Toys Clothes Sundries Storage Basket AB-026 - Beige Yellow+White",
                        "quantity": 1
                    },
                    {
                        "name": "6 Pieces Nossa 21cm Cake Plate Set",
                        "quantity": 1
                    }
                ]
            }
        ]
    }
}

Update a Package

PATCH /packages/{partnerRef}

Update a specific package

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Request

Parameter	Type	Description
tracking_number	string	optional.
customer_name	string	optional.
customer_phone_1	string	optional.
customer_phone_2	string	optional.
source_country_iso2	string	optional.
source_address_line_1	string	optional.
source_address_line_2	string	optional.
destination_region	string	optional.
destination_city	string	optional.
destination_address_line_1	string	optional.
destination_address_line_2	string	optional.
destination_postal_code	string	optional.
length	decimal	optional.
height	decimal	optional.
weight	decimal	optional.
description	string	optional.
units	string	optional.
type	string	optional . in parcel, box
handling	string	optional . in normal, fragile
special_instructions	string	optional.
latitude	decimal	optional.
longitude	decimal	optional.
value	decimal	optional.
amount_to_collect	decimal	optional.
items	array	optional.

Response

200

{
    "message": "Request successful",
    "data": {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceCountry": "Ghana",
        "sourceAddressLine1": "Accra Spintex",
        "sourceAddressLine2": null,
        "destinationCountry": "Ghana",
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "units": 1,
        "type": "box",
        "value": "300.00",
        "amountToCollect": "300.00",
        "paymentCollector": "shaq",
        "handling": "normal",
        "specialInstructions": null,
        "status": "not_delivered",
        "statusDescription": "Attempted delivery but couldn't complete it.",
        "latitude": null,
        "longitude": null,
        "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "dateCreated": "2025-04-10 11:15",
        "items": [
            {
                "name" : "iPhone 6",
                "quantity" : 1,
            },
            {
                "name" : "iPhone 14 Pro",
                "quantity" : 2,
            }
        ],
         "trackingHistory": [
            {
                "name": "not_delivered",
                "description": "Attempted delivery but couldn't complete it.",
                "date": "2025-07-16 09:00",
                "comment": "Customer was unreachable upon arrival. Package rescheduled for 2nd delivery attempt."
            },
            {
                "name": "dispatched",
                "description": "Package is en-route to deliver.",
                "date": "2025-07-15 15:45",
                "comment": null
            },
        ]
    }
}

Track Package

GET /tracking/{trackingNumber}

Get tracking statuses of a specific package

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Response

200

{
    "message": "Package tracking",
    "data": {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "description": "Kitchen cabinet",
        "status": "shipped",
        "statusDescription": "Package has been shipped by Partner.",
        "items": [
            {
                "name" : "iPhone 6",
                "quantity" : 1,
            },
            {
                "name" : "iPhone 14 Pro",
                "quantity" : 2,
            }
        ],
        "tracking": [
            {
                "status": "shipped",
                "description": "Package has been shipped by Partner.",
                "date": "2025-04-10 15:17"
            },
            {
                "status": "pending",
                "description": "Package is yet to be shipped by Partner.",
                "date": "2025-04-10 15:16"
            },
            {
                "status": "shipped",
                "description": "Package has been shipped by Partner.",
                "date": "2025-04-10 15:15"
            },
            {
                "status": "shipped",
                "description": "Package has been shipped by Partner.",
                "date": "2025-04-10 15:15"
            },
            {
                "status": "pending",
                "description": "Package is yet to be shipped by Partner.",
                "date": "2025-04-10 15:14"
            }
        ]
    }
}

Get Regions

GET /setup/regions

Get all allowable regions

Headers

Parameter	Type	Description
Authorization	bearer	Required.

Response

200

{
    "message": "Request successful",
    "data": [
        {
            "id": 16,
            "name": "Western North"
        },
        {
            "id": 15,
            "name": "Ashanti"
        },
    ]
}

Receive Package Status Updates Through Webhook

POST /YOUR_WEBHOOK_URL

We will send package status updates to your webhook

Request

Parameter	Type	Description
partner_ref	string
tracking_number	string
status	string
description	string
comment	string
date	string	format : yyyy-mm-dd HH:mm:ss (UTC)

Response

200

{
    "message": "",
    "data": {
        "status": "OK"
    }
}