Skip to content

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.

Info Value
version 1.0
Dev 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 into main regional hub
  • warehouse_received : Package has been received at a regional warehouse for onward delivery
  • collected : Package has been collected from Partner by ShaQ Express
  • 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_picked : Package has been picked up from the customer for return to partner
  • return_in_progress : Package is being prepared to be sent back to Partner
  • returned_to_sender : Package has been sent back to Partner
  • return_to_central : 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",
        "eta": "2026-04-20 - 2026-04-22",
        "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",
        "eta": "2026-04-20 - 2026-04-22",
        "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",
    "eta": "2026-04-20 - 2026-04-22",
    "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
      },
      {
        "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
}

Cancel Order

POST /packages/{partnerRef}/cancel

Cancel a fulfillment order.

Headers

Parameter Type Description
Authorization bearer Required.

Response

200

{
  "message": "Order cancelled successfully",
  "data": null
}

400

{
  "message": "Order cannot be cancelled. Order cancellation failed",
  "data": null
}

404

{
  "message": "Order not found",
  "data": null
}

Create Single Package

POST /packages

Create a single package

Headers

Parameter Type Description
Authorization bearer Required.

Request

Parameter Type Description
tracking_number string optional.
partner_ref string required. Must be unique.
customer_name string required.
customer_phone_1 string required.
customer_phone_2 string optional.
source_country_iso2 string required.
source_address_line_1 string required.
source_address_line_2 string optional.
destination_region string required if region_id is empty.
destination_city string required.
destination_address_line_1 string required.
destination_address_line_2 string optional.
destination_postal_code string optional.
length decimal optional.
height decimal optional.
weight decimal optional.
description string required.
units string required.
type string required . in parcel, box
handling string required . in normal, fragile
special_instructions string optional.
latitude decimal optional.
longitude decimal optional.
value decimal required.
amount_to_collect decimal optional. defaults to package value.
payment_collector string optional. in shaq, partner (This parameter can only be sent when ShaQ Express is the payment collector. It specifies who is responsible for collecting payment from the customer for the package and is intended for special cases where the partner handles the collection instead. If not provided, the default agreed payment collector configuration will be used.)
items array required. {name, quantity}
region_id integer required if destination_region is empty.

Response

200

{
  "message": "Package created successfully",
  "data": {
    "partnerRef": "UNIQUE-REF-001",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "altPhone": 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",
    "units": 1,
    "type": "box",
    "handling": "normal",
    "specialInstructions": null,
    "status": "pending",
    "statusDescription": "Package is yet to be received by Partner",
    "landmark": null,
    "proofPhotoUrl": null,
    "partner": "Demo Partner",
    "scheduleDate": null,
    "deliveryFee": null,
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "paymentStatus": null,
    "date": "2025-04-10 11:15",
    "deliveredAt": null,
    "eta": "2026-04-20 - 2026-04-22",
    "deliveryAttempts": 0,
    "items": [
      { "name": "iPhone 6", "quantity": 1 },
      { "name": "iPhone 14 Pro", "quantity": 2 }
    ]
  }
}

404

{
  "message": "No Region with name {destination_region} found",
  "data": null
}

Create Bulk 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 (This parameter can only be sent when ShaQ Express is the payment collector. It specifies who is responsible for collecting payment from the customer for the package and is intended for special cases where the partner handles the collection instead. If not provided, the default agreed payment collector configuration will be used.)
packages.*.items array required. {name, quantity}
packages.*.region_id integer required if destination_region is empty.

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 (This parameter can only be sent when ShaQ Express is the payment collector. It specifies who is responsible for collecting payment from the customer for the package and is intended for special cases where the partner handles the collection instead. If not provided, the default agreed payment collector configuration will be used.)
packages.*.items array required.
packages.*.region_id integer required if destination_region is empty.

Response

200

{
  "message": "Shipment created successfully",
  "data": {
    "reference": "PAR-20260322053800"
  }
}

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",
        "eta": "2026-04-20 - 2026-04-22",
        "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",
    "eta": "2026-04-20 - 2026-04-22",
    "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.",
    "eta": "2026-04-20 - 2026-04-22",
    "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 Updates Through Webhook

POST /YOUR_WEBHOOK_URL

We will POST to your webhook URL whenever a tracked event occurs on a package.

Envelope

Every webhook payload shares the same top-level envelope:

Field Type Description
event string The event type. See Webhook Events below.
event_id string Unique UUID per delivery. Use for idempotency/deduplication.
api_version string Payload version e.g. v1
occurred_at string ISO 8601 UTC timestamp of when the event occurred
data object Event-specific payload. Shape varies by event — see below.

Webhook Events

package.status_updated

Fired whenever a package status changes.

Field Type Description
tracking_number string ShaQ Express tracking number
partner_ref string Your reference for the package
status string The new status. See Package Statuses for values
description string Human-readable description of the status
comment string Additional context or comment. May be null
meta object Extra data. Includes proof_url when status is delivered 
{
  "event": "package.status_updated",
  "event_id": "018e2b3c-7f4a-7c2d-9e1b-4a8f3d2c6b5a",
  "api_version": "v1",
  "occurred_at": "2025-05-29T10:30:00Z",
  "data": {
    "tracking_number": "20250410X51DIQ",
    "partner_ref": "FGVHKJ567",
    "status": "delivered",
    "description": "Package was successfully delivered to customer",
    "comment": null,
    "meta": {
      "proof_url": "https://example.com/proof.jpg"
    }
  }
}
package.amount_to_collect_updated

Fired when the amount to collect of a package is revised, always requested from and approved by Client.

Field Type Description
tracking_number string ShaQ Express tracking number
partner_ref string Your reference for the package
status string Package status at the time of revision. See Package Statuses for values
meta.old_amount_to_collect number Previous amount to collect
meta.new_amount_to_collect number Revised amount to collect
meta.currency string Currency code e.g. GHS
meta.reason string Reason for revision 
{
  "event": "package.amount_to_collect_updated",
  "event_id": "039g4d5e-9h6c-9e4f-1g3d-6c0h5f4e8d7c",
  "api_version": "v1",
  "occurred_at": "2025-05-29T09:00:00Z",
  "data": {
    "tracking_number": "20250410X51DIQ",
    "partner_ref": "FGVHKJ567",
    "status": "received",
    "meta": {
      "old_amount_to_collect": 25.0,
      "new_amount_to_collect": 35.0,
      "currency": "GHS",
      "reason": "Items changed"
    }
  }
}

Expected Response

Your endpoint must return a 2xx response to acknowledge receipt of the webhook. Any non-2xx response will be retried up to 3 times.

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

Webhook Requirements

To ensure reliable delivery and prevent webhook timeouts, please adhere to the following guidelines:

*   **Response Timeout:** Your server must return a `2xx` status code within **10 seconds** of receiving the payload.
*   **Asynchronous Processing:** Acknowledge receipt of the webhook immediately, and process any database operations, business logic, or external notifications asynchronously (e.g., using a background queue/worker).
*   **Deduplication & Idempotency:** Use the `event_id` provided in the payload envelope to ensure idempotency. Keep a log of processed event IDs and skip processing if the ID has already been seen.
*   **Expect Duplicates:** Your endpoint must be prepared to handle duplicate deliveries gracefully in case of network retries or transient connection issues.

Create Package Replacement

POST /packages/replacement
background-color: var(--md-code-bg-color) Description: Create one or two packages to replace an existing package. The rule field determines how many packages are required and what action each must carry.

Headers

Parameter Type Description
Authorization bearer Required.

Rules

Rule Packages Required Actions Required
deliver 1 action = deliver
return 1 action = return
return_deliver 2 One return, one deliver

Request

Parameter Type Description
rule string Required. One of deliver, return, return_deliver
packages array Required. 1–2 package objects. Must satisfy the rule constraints above

Package Object

Each item in the packages array must conform to the following shape:

Parameter Type Description
action string Required. One of deliver, return. Must align with rule
partner_ref string Required. Must be unique
customer_name string Required
customer_phone_1 string Required. Valid mobile number
customer_phone_2 string Optional
source_country_iso2 string Required. Valid ISO2 country code
source_address_line_1 string Required
source_address_line_2 string Optional
destination_country_iso2 string Required. Valid ISO2 country code
destination_region string Required if region_id is absent
destination_city string Required
destination_address_line_1 string Required
destination_address_line_2 string Optional
destination_postal_code string Optional
landmark string Optional
region_id integer Required if destination_region is absent
length decimal Optional
height decimal Optional
weight decimal Optional
description string Required
units number Required
type string Required. One of parcel, box
value decimal Required. Minimum 0
amount_to_collect decimal Optional. Minimum 0
handling string Required. One of normal, fragile
payment_collector string optional. in shaq, partner (This parameter can only be sent when ShaQ Express is the payment collector. It specifies who is responsible for collecting payment from the customer for the package and is intended for special cases where the partner handles the collection instead. If not provided, the default agreed payment collector configuration will be used.)
items array Required. Array of { name: string, quantity: number }. Can be empty
special_instructions string Optional
latitude decimal Optional
longitude decimal Optional

Response

200

{
  "message": "Package replacement created successfully",
  "data": [
    {
      "partnerRef": "GH945214",
      "trackingNumber": "9F0FD9D5",
      "customerName": "Derrick Nti",
      "customerPhone1": "+233549632604",
      "customerPhone2": null,
      "sourceCountry": "Ghana",
      "sourceAddressLine1": "21 Abiriw Street",
      "sourceAddressLine2": null,
      "destinationCountry": "Ghana",
      "destinationRegion": "Greater Accra",
      "destinationCity": "Kwashieman",
      "destinationAddressLine1": "23 Abiriw Street",
      "destinationAddressLine2": null,
      "destinationPostalCode": null,
      "length": 30,
      "height": 20,
      "weight": 5.5,
      "description": "Test package",
      "labelUrl": null,
      "units": 1,
      "type": "box",
      "value": 20,
      "amountToCollect": 20,
      "paymentStatus": "unpaid",
      "handling": "normal",
      "specialInstructions": null,
      "status": "pending",
      "statusDescription": "Package is yet to be received by Partner",
      "latitude": null,
      "longitude": null,
      "receivedAt": null,
      "isReplacement": true,
      "action": "deliver",
      "items": [
        {
          "name": "Bluetooth",
          "quantity": 3
        }
      ],
      "rescheduledDate": null,
      "deliveredAt": null,
      "eta": null,
      "maxEta": null,
      "pickedAt": null,
      "packedAt": null,
      "cancelledAt": null,
      "trackingHistory": [
        {
          "name": "pending",
          "description": "Package is yet to be received by Partner",
          "date": "2026-05-04 12:16",
          "comment": null
        }
      ]
    },
    {
      "partnerRef": "GH545728",
      "trackingNumber": "A797CA0A",
      "customerName": "Kwabena Azaglo",
      "customerPhone1": "+233549632604",
      "customerPhone2": null,
      "sourceCountry": "Ghana",
      "sourceAddressLine1": "21 Abiriw Street",
      "sourceAddressLine2": null,
      "destinationCountry": "Ghana",
      "destinationRegion": "Greater Accra",
      "destinationCity": "Kwashieman",
      "destinationAddressLine1": "23 Abiriw Street",
      "destinationAddressLine2": null,
      "destinationPostalCode": null,
      "length": 30,
      "height": 20,
      "weight": 5.5,
      "description": "Test package",
      "labelUrl": null,
      "units": 1,
      "type": "box",
      "value": 20,
      "amountToCollect": 20,
      "paymentStatus": "unpaid",
      "handling": "normal",
      "specialInstructions": null,
      "status": "pending",
      "statusDescription": "Package is yet to be received by Partner",
      "latitude": null,
      "longitude": null,
      "receivedAt": null,
      "isReplacement": true,
      "action": "return",
      "items": [
        {
          "name": "Bluetooth",
          "quantity": 3
        }
      ],
      "rescheduledDate": null,
      "deliveredAt": null,
      "eta": null,
      "maxEta": null,
      "pickedAt": null,
      "packedAt": null,
      "cancelledAt": null,
      "trackingHistory": [
        {
          "name": "pending",
          "description": "Package is yet to be received by Partner",
          "date": "2026-05-04 12:16",
          "comment": null
        }
      ]
    }
  ]
}

Get Package Label

GET /packages/{partnerRef}/print-label

Get the label of a specific package

Headers

Parameter Type Description
Authorization bearer Required.

Response

200

{
  "message": "Label ready",
  "data": {
    "url": "https://d167icvhk5jowg.cloudfront.net/labels/20250410X51DIQ.pdf"
  }
}

202

{
  "message": "Label generation started. Please retry shortly.",
  "data": null
}

404

{
  "message": "Package not found",
  "data": null
}