API Reference

Complete reference for all Pathao Parcel Business API endpoints.

Base URL

All API requests are made relative to one of the following base URLs. Use the sandbox URL during development and the production URL when you go live.

Environment	Base URL
Production	`https://api.pathao.com`
Sandbox	`https://sandbox.pathao.com`

Example

POST/v1/business/order/quotation

Get Quotation

Get a delivery price quote without creating an order. Use this to display delivery fees to your customers before they commit.

Body Parameters

Name	Type	Required	Description
pickup_address_text	string	Required	Full pickup address text
estimated_pickup_address_latitude	number	Required	Pickup latitude coordinate
estimated_pickup_address_longitude	number	Required	Pickup longitude coordinate
receiver_address_text	string	Required	Full delivery address text
estimated_receiver_address_latitude	number	Required	Delivery latitude coordinate
estimated_receiver_address_longitude	number	Required	Delivery longitude coordinate
parcel_type	integer	Required	Type of parcel (1 = Document, 2 = Small, 3 = Medium, 4 = Large)

Request Body

Response

Code Examples

curl -X POST https://api.pathao.com/v1/business/order/quotation \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "pickup_address_text": "House 42, Road 11, Banani, Dhaka 1213",
    "estimated_pickup_address_latitude": 23.7937,
    "estimated_pickup_address_longitude": 90.4066,
    "receiver_address_text": "Flat 5B, Green Valley Apartments, Dhanmondi, Dhaka 1205",
    "estimated_receiver_address_latitude": 23.7465,
    "estimated_receiver_address_longitude": 90.3762,
    "parcel_type": 1
  }'

POST/v1/business/order/create

Create Order

Create a delivery order. The system validates inputs, calculates pricing, and returns order details with tracking URL.

Body Parameters

Name	Type	Required	Description
pickup_address_text	string	Required	Full pickup address text
estimated_pickup_address_latitude	number	Required	Pickup latitude coordinate
estimated_pickup_address_longitude	number	Required	Pickup longitude coordinate
receiver_address_text	string	Required	Full delivery address text
estimated_receiver_address_latitude	number	Required	Delivery latitude coordinate
estimated_receiver_address_longitude	number	Required	Delivery longitude coordinate
receiver_name	string	Required	Name of the parcel receiver
receiver_phone_number	string	Required	Receiver phone (11 digits, starts with 01)
parcel_type	integer	Required	Type of parcel (1 = Document, 2 = Small, 3 = Medium, 4 = Large)
driver_type	integer	Required	Vehicle type (1 = Motorcycle, 2 = Car)
is_freelancer	boolean	Required	Whether to assign a freelance rider
partner_reference_id	string	Optional	Your internal order reference ID
item_price	number	Optional	Declared value of the item in BDT
item_name	string	Optional	Description of the item being delivered
parcel_comment	string	Optional	Special delivery instructions
detailed_address	string	Optional	Additional address details (gate code, floor, etc.)

Request Body

Response

Code Examples

curl -X POST https://api.pathao.com/v1/business/order/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Idempotency-Key: unique-order-key-123" \
  -d '{
    "pickup_address_text": "House 42, Road 11, Banani, Dhaka 1213",
    "estimated_pickup_address_latitude": 23.7937,
    "estimated_pickup_address_longitude": 90.4066,
    "receiver_address_text": "Flat 5B, Green Valley Apartments, Dhanmondi",
    "estimated_receiver_address_latitude": 23.7465,
    "estimated_receiver_address_longitude": 90.3762,
    "receiver_name": "Mohammad Rahman",
    "receiver_phone_number": "01712345678",
    "parcel_type": 1,
    "driver_type": 1,
    "is_freelancer": true,
    "partner_reference_id": "ORD-2025-00123"
  }'

GET/v1/business/orders

List Orders

List all orders with filtering and pagination. Returns order summaries sorted by newest first.

Query Parameters

Name	Type	Required	Description
parcel_status	string	Optional	Filter by status (PENDING, ASSIGNED, ACCEPTED, etc.)
created_at_from	string	Optional	Start date filter (ISO 8601)
created_at_to	string	Optional	End date filter (ISO 8601)
page	integer	Optional	Page number (default: 1)
limit	integer	Optional	Items per page (default: 50, max: 200)

Response

Code Examples

curl -X GET "https://api.pathao.com/v1/business/orders?parcel_status=COMPLETED&page=1&limit=50" \
  -H "X-API-Key: your_api_key"

GET/v1/business/order/{order_id}

Get Order Details

Get complete details for a specific order including rider info and all timestamps.

Response

Code Examples

curl -X GET https://api.pathao.com/v1/business/order/PTH-PRC-2025-0001234 \
  -H "X-API-Key: your_api_key"

GET/v1/business/order/{order_id}/status

Get Order Status

Lightweight polling endpoint to check current order status. Use as a fallback when webhooks are unavailable.

Response

Code Examples

curl -X GET https://api.pathao.com/v1/business/order/PTH-PRC-2025-0001234/status \
  -H "X-API-Key: your_api_key"

POST/v1/business/order/{order_id}/cancel

Cancel Order

Cancel an existing order. Only allowed before pickup (status: PENDING, ASSIGNED, ACCEPTED, STARTED).

Body Parameters

Name	Type	Required	Description
cancellation_reason	string	Optional	Reason for cancellation

Request Body

Response

Code Examples

curl -X POST https://api.pathao.com/v1/business/order/PTH-PRC-2025-0001234/cancel \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"cancellation_reason": "Customer changed their mind"}'

POST/v1/business/order/{order_id}/retry

Retry Order

Retry a cancelled delivery. Creates a new delivery attempt reusing the original order details.

Response

Code Examples

curl -X POST https://api.pathao.com/v1/business/order/PTH-PRC-2025-0001234/retry \
  -H "X-API-Key: your_api_key"

API Reference

Complete reference for all Pathao Parcel Business API endpoints.

Base URL

All API requests are made relative to one of the following base URLs. Use the sandbox URL during development and the production URL when you go live.

Environment	Base URL
Production	`https://api.pathao.com`
Sandbox	`https://sandbox.pathao.com`

Example

# Production
https://api.pathao.com/v1/business/...

# Sandbox
https://sandbox.pathao.com/v1/business/...

Example

POST/v1/business/order/quotation

Get Quotation

Get a delivery price quote without creating an order. Use this to display delivery fees to your customers before they commit.

Body Parameters

Name	Type	Required	Description
pickup_address_text	string	Required	Full pickup address text
estimated_pickup_address_latitude	number	Required	Pickup latitude coordinate
estimated_pickup_address_longitude	number	Required	Pickup longitude coordinate
receiver_address_text	string	Required	Full delivery address text
estimated_receiver_address_latitude	number	Required	Delivery latitude coordinate
estimated_receiver_address_longitude	number	Required	Delivery longitude coordinate
parcel_type	integer	Required	Type of parcel (1 = Document, 2 = Small, 3 = Medium, 4 = Large)

Request Body

{
  "pickup_address_text": "House 42, Road 11, Banani, Dhaka 1213",
  "estimated_pickup_address_latitude": 23.7937,
  "estimated_pickup_address_longitude": 90.4066,
  "receiver_address_text": "Flat 5B, Green Valley Apartments, Dhanmondi, Dhaka 1205",
  "estimated_receiver_address_latitude": 23.7465,
  "estimated_receiver_address_longitude": 90.3762,
  "parcel_type": 1
}

Response

{
  "charge": 120,
  "distance": 8.5,
  "duration": 25,
  "time_to_pickup": 12
}

Code Examples

curl -X POST https://api.pathao.com/v1/business/order/quotation \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "pickup_address_text": "House 42, Road 11, Banani, Dhaka 1213",
    "estimated_pickup_address_latitude": 23.7937,
    "estimated_pickup_address_longitude": 90.4066,
    "receiver_address_text": "Flat 5B, Green Valley Apartments, Dhanmondi, Dhaka 1205",
    "estimated_receiver_address_latitude": 23.7465,
    "estimated_receiver_address_longitude": 90.3762,
    "parcel_type": 1
  }'

POST/v1/business/order/create

Create Order

Create a delivery order. The system validates inputs, calculates pricing, and returns order details with tracking URL.

Body Parameters

Name	Type	Required	Description
pickup_address_text	string	Required	Full pickup address text
estimated_pickup_address_latitude	number	Required	Pickup latitude coordinate
estimated_pickup_address_longitude	number	Required	Pickup longitude coordinate
receiver_address_text	string	Required	Full delivery address text
estimated_receiver_address_latitude	number	Required	Delivery latitude coordinate
estimated_receiver_address_longitude	number	Required	Delivery longitude coordinate
receiver_name	string	Required	Name of the parcel receiver
receiver_phone_number	string	Required	Receiver phone (11 digits, starts with 01)
parcel_type	integer	Required	Type of parcel (1 = Document, 2 = Small, 3 = Medium, 4 = Large)
driver_type	integer	Required	Vehicle type (1 = Motorcycle, 2 = Car)
is_freelancer	boolean	Required	Whether to assign a freelance rider
partner_reference_id	string	Optional	Your internal order reference ID
item_price	number	Optional	Declared value of the item in BDT
item_name	string	Optional	Description of the item being delivered
parcel_comment	string	Optional	Special delivery instructions
detailed_address	string	Optional	Additional address details (gate code, floor, etc.)

Request Body

{
  "pickup_address_text": "House 42, Road 11, Banani, Dhaka 1213",
  "estimated_pickup_address_latitude": 23.7937,
  "estimated_pickup_address_longitude": 90.4066,
  "receiver_address_text": "Flat 5B, Green Valley Apartments, Dhanmondi, Dhaka 1205",
  "estimated_receiver_address_latitude": 23.7465,
  "estimated_receiver_address_longitude": 90.3762,
  "detailed_address": "Call before arrival. Gate code: 1234",
  "receiver_name": "Mohammad Rahman",
  "receiver_phone_number": "01712345678",
  "parcel_type": 1,
  "item_price": 500,
  "driver_type": 1,
  "is_freelancer": true,
  "partner_reference_id": "ORD-2025-00123"
}

Response

{
  "order_id": "PTH-PRC-2025-0001234",
  "partner_reference_id": "ORD-2025-00123",
  "charge": 120,
  "distance": 8.5,
  "duration": 25,
  "time_to_pickup": 12,
  "parcel_status": "PENDING",
  "rider_id": null,
  "tracking_url": "https://track.pathao.com/parcel/PTH-PRC-2025-0001234",
  "created_at": "2025-01-19T14:30:00+06:00"
}

Code Examples

curl -X POST https://api.pathao.com/v1/business/order/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Idempotency-Key: unique-order-key-123" \
  -d '{
    "pickup_address_text": "House 42, Road 11, Banani, Dhaka 1213",
    "estimated_pickup_address_latitude": 23.7937,
    "estimated_pickup_address_longitude": 90.4066,
    "receiver_address_text": "Flat 5B, Green Valley Apartments, Dhanmondi",
    "estimated_receiver_address_latitude": 23.7465,
    "estimated_receiver_address_longitude": 90.3762,
    "receiver_name": "Mohammad Rahman",
    "receiver_phone_number": "01712345678",
    "parcel_type": 1,
    "driver_type": 1,
    "is_freelancer": true,
    "partner_reference_id": "ORD-2025-00123"
  }'

GET/v1/business/orders

List Orders

List all orders with filtering and pagination. Returns order summaries sorted by newest first.

Query Parameters

Name	Type	Required	Description
parcel_status	string	Optional	Filter by status (PENDING, ASSIGNED, ACCEPTED, etc.)
created_at_from	string	Optional	Start date filter (ISO 8601)
created_at_to	string	Optional	End date filter (ISO 8601)
page	integer	Optional	Page number (default: 1)
limit	integer	Optional	Items per page (default: 50, max: 200)

Response

{
  "data": [
    {
      "order_id": "PTH-PRC-2025-0001234",
      "partner_reference_id": "ORD-2025-00123",
      "parcel_status": "COMPLETED",
      "charge": 120,
      "created_at": "2025-01-19T14:30:00+06:00",
      "ride_completed_at": "2025-01-19T15:15:00+06:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 156,
    "total_pages": 4
  }
}

Code Examples

curl -X GET "https://api.pathao.com/v1/business/orders?parcel_status=COMPLETED&page=1&limit=50" \
  -H "X-API-Key: your_api_key"

GET/v1/business/order/{order_id}

Get Order Details

Get complete details for a specific order including rider info and all timestamps.

Response

{
  "order_id": "PTH-PRC-2025-0001234",
  "partner_reference_id": "ORD-2025-00123",
  "pickup_address_text": "House 42, Road 11, Banani, Dhaka 1213",
  "receiver_address_text": "Flat 5B, Green Valley Apartments, Dhanmondi",
  "receiver_name": "Mohammad Rahman",
  "receiver_phone_number": "01712345678",
  "parcel_status": "PICKED",
  "charge": 120,
  "distance": 8.5,
  "duration": 25,
  "rider_id": 12345,
  "rider_name": "Karim Ahmed",
  "rider_phone_number": "01898765432",
  "rider_latitude": 23.7890,
  "rider_longitude": 90.4012,
  "tracking_url": "https://track.pathao.com/parcel/PTH-PRC-2025-0001234",
  "created_at": "2025-01-19T14:30:00+06:00",
  "assigned_at": "2025-01-19T14:32:00+06:00",
  "picked_at": "2025-01-19T14:45:00+06:00",
  "ride_completed_at": null,
  "cancelled_at": null
}

Code Examples

curl -X GET https://api.pathao.com/v1/business/order/PTH-PRC-2025-0001234 \
  -H "X-API-Key: your_api_key"

GET/v1/business/order/{order_id}/status

Get Order Status

Lightweight polling endpoint to check current order status. Use as a fallback when webhooks are unavailable.

Response

{
  "order_id": "PTH-PRC-2025-0001234",
  "parcel_status": "PICKED",
  "updated_at": "2025-01-19T14:45:00+06:00"
}

Code Examples

curl -X GET https://api.pathao.com/v1/business/order/PTH-PRC-2025-0001234/status \
  -H "X-API-Key: your_api_key"

POST/v1/business/order/{order_id}/cancel

Cancel Order

Cancel an existing order. Only allowed before pickup (status: PENDING, ASSIGNED, ACCEPTED, STARTED).

Body Parameters

Name	Type	Required	Description
cancellation_reason	string	Optional	Reason for cancellation

Request Body

{
  "cancellation_reason": "Customer changed their mind"
}

Response

{
  "order_id": "PTH-PRC-2025-0001234",
  "parcel_status": "CANCELLED",
  "cancelled_at": "2025-01-19T14:35:00+06:00",
  "cancellation_reason": "Customer changed their mind"
}

Code Examples

curl -X POST https://api.pathao.com/v1/business/order/PTH-PRC-2025-0001234/cancel \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"cancellation_reason": "Customer changed their mind"}'

POST/v1/business/order/{order_id}/retry

Retry Order

Retry a cancelled delivery. Creates a new delivery attempt reusing the original order details.

Response

{
  "order_id": "PTH-PRC-2025-0001234",
  "parcel_status": "PENDING",
  "charge": 120,
  "retry_count": 1,
  "created_at": "2025-01-19T15:00:00+06:00"
}

Code Examples

curl -X POST https://api.pathao.com/v1/business/order/PTH-PRC-2025-0001234/retry \
  -H "X-API-Key: your_api_key"