EN 
Developer's API
API Documentation
Issue an Access Token post
Issue an Access Token from Refresh Token post
Create a New Store post
Create a New Order post
Create a Bulk Order post
Get Order Short Info get
Get List of Cities get
Get zones inside a particular city get
Get areas inside a particular zone get
Price Calculation Api post
Get Merchant Store Info get
Webhook Integration
Pathao Courier Merchant API Integration Documentation
Summary
Pathao API uses OAuth 2.0. There are 2 requests being sent here. 1st request is for getting the access token. This access token should be saved in the database (or any persistent store) for future use. 2nd request is for creating a new order. This uses the access token previously saved.
For understanding these APIs, we are providing Sandbox/Test Environment's Credentials here. And later you can easily integrate for Production/Live Environment by using your Live Credentials
Merchant API Credentials
Now you can easily integrate Pathao Courier Merchant API's into your website.
Sandbox/Test Environment Credentials
| Field name | Description |
|---|---|
| base_url | https://courier-api-sandbox.pathao.com |
| client_id | 7N1aMJQbWm |
| client_secret | wRcaibZkUdSNz2EI9ZyuXLlNrnAv0TdPUPXMnD39 |
| username | test@pathao.com |
| password | lovePathao |
| grant_type | password |
Production/Live Environment
| Field name | Description |
|---|---|
| base_url | https://api-hermes.pathao.com |
| client_id | You can see client_id from merchant api credentials section. |
| client_secret | You can see client_secret from merchant api credentials section. |
Issue an Access Token
Endpoint:
/aladdin/api/v1/issue-token For any kind of access to the Pathao Courier Merchant API, you need to issue an access token first. This token will be used to authenticate your API requests.
curl --location '{{base_url}}/aladdin/api/v1/issue-token' \
+ --header 'Content-Type: application/json' \
+ --data-raw '{
+ "client_id": "{{client_id}}",
+ "client_secret": "{{client_secret}}",
+ "grant_type": "password",
+ "username": "{{your_email}}",
+ "password": "{{your_password}}"
+ }'Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| client_id | string | Yes | Test/Production environment Client Id. |
| client_secret | string | Yes | Test/Production environment Client Secret. |
| grant_type | string | Yes | Must use grant type password for issue token api. |
| username | string | Yes | Test environment/your login email address. |
| password | string | Yes | Test environment/your login password |
Success Response: Status Code 200
{
+ token_type: "Bearer",
+ expires_in: 432000,
+ access_token: "ISSUED_ACCESS_TOKEN",
+ refresh_token: "ISSUED_REFRESH_TOKEN"
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| token_type | string | No | It will always be Bearer. |
| expires_in | integer | No | Token expiry time in seconds |
| access_token | string | No | Your Authenticated token for making API calls |
| refresh_token | string | No | Your refresh token for regenerating access token |
Issue an Access Token from Refresh Token
Endpoint:
/aladdin/api/v1/issue-token In order to generate a new access token, you can use the refresh token to obtain a new access token.
curl --location '{{base_url}}/aladdin/api/v1/issue-token' \
+ --header 'Content-Type: application/json' \
+ --data '{
+ "client_id": "{{your_client_id}}",
+ "client_secret": "{{client_secret}}",
+ "grant_type": "refresh_token"
+ "refresh_token": "ISSUED_REFRESH_TOKEN",
+ }'Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| client_id | string | Yes | Your Client Id generated by Pathao Courier. |
| client_secret | string | Yes | Your Client Secret generated by Pathao Courier. |
| grant_type | string | Yes | Must use grant type refresh_token for refresh token api. |
| refresh_token | string | Yes | Provide your refresh token in order to generate access_token |
Success Response: Status Code 200
{
+ token_type: "Bearer",
+ expires_in: 432000,
+ access_token: "ISSUED_ACCESS_TOKEN",
+ refresh_token: "ISSUED_REFRESH_TOKEN"
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| token_type | string | No | Your access token type |
| expires_in | integer | No | Token expiry time in seconds |
| access_token | string | No | Your Authenticated token for making API calls |
| refresh_token | string | No | Your refresh token for regenerating access token |
Create a New Store
Endpoint:
/aladdin/api/v1/stores To create a Store in Pathao Courier Merchant API, you need to provide the required information. The CURL for the POST Request is given, Use this as a reference. The API will return a success response with the created store details.
curl --location '{{base_url}}/aladdin/api/v1/stores' \
+ --header 'Content-Type: application/json' \
+ --header 'Authorization: Bearer {{access_token}}' \
+ --data '{
+ "name": "Demo Store",
+ "contact_name": "Test Merchant",
+ "contact_number": "017XXXXXXXX",
+ "secondary_contact": "015XXXXXXXX",
+ "otp_number": "017XXXXXXXX",
+ "address": "House 123, Road 4, Sector 10, Uttara, Dhaka-1230, Bangladesh",
+ "city_id": {{city_id}},
+ "zone_id": {{zone_id}},
+ "area_id": {{area_id}}
+ }'Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| name | string | Yes | Name of the store. Store name length should be between 3 to 50 characters. |
| contact_name | string | Yes | Contact person of the store need for issue related communication. Contact person name length should be between 3 to 50 characters. |
| contact_number | string | Yes | Store contact person phone number. Contact number length should be 11 characters. |
| secondary_contact | string | No | Store contact person secondary phone number. Secondary contact number length should be 11 characters. This field is optional. |
| otp_number | string | No | OTP for orders from this order will be sent to this number |
| address | string | Yes | Merchant Store address. Address length should be between 15 to 120 characters. |
| city_id | integer | Yes | Recipient city_id |
| zone_id | integer | Yes | Recipient zone_id |
| area_id | integer | Yes | Recipient area_id |
Success Response: Status Code 200
{
+ message: "Store created successfully, Please wait one hour for approval.",
+ type: "success",
+ code: 200,
+ data: {
+ store_name: "Demo Store"
+ }
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| store_name | string | No | The name of the store that you created. |
Create a New Order
Endpoint:
/aladdin/api/v1/orders To create a New order in Pathao Courier Merchant API, you need to provide the required information. The CURL for the POST Request is given, Use this as a reference. The API will return a success response with the created order details.
curl --location '{{base_url}}/aladdin/api/v1/orders' \
+ --header 'Content-Type: application/json' \
+ --header 'Authorization: Bearer {{access_token}}' \
+ --data '{
+ "store_id": {{merchant_store_id}},
+ "merchant_order_id": "{{merchant_order_id}}",
+ "recipient_name": "Demo Recipient",
+ "recipient_phone": "017XXXXXXXX",
+ "recipient_address": "House 123, Road 4, Sector 10, Uttara, Dhaka-1230, Bangladesh",
+ "delivery_type": 48,
+ "item_type": 2,
+ "special_instruction": "Need to Delivery before 5 PM",
+ "item_quantity": 1,
+ "item_weight": "0.5",
+ "item_description": "this is a Cloth item, price- 3000",
+ "amount_to_collect": 900
+ }'Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| store_id | integer | Yes | store_id is provided by the merchant and not changeable. This store ID will set the pickup location of the order according to the location of the store. |
| merchant_order_id | string | No | Optional parameter, merchant order info/tracking id |
| recipient_name | string | Yes | Parcel receivers name. Name length should be between 3 to 100 characters. |
| recipient_phone | string | Yes | Parcel receivers contact number. Recipient phone length should be 11 characters. |
| recipient_secondary_phone | string | No | Parcel receivers secondary contact number. Recipient secondary phone length should be 11 characters. This field is optional. |
| recipient_address | string | Yes | Parcel receivers full address. Address length should be between 10 to 220 characters. |
| recipient_city | integer | No | Parcel receiver’s city_id. This is an optional parameter, so do not send a null value. If not included in the request payload, then our system will populate it automatically based on the recipient_address you will be provided. |
| recipient_zone | integer | No | Parcel receiver’s zone_id. This is an optional parameter, so do not send a null value. If not included in the request payload, then our system will populate it automatically based on the recipient_address you will be provided. |
| recipient_area | integer | No | Parcel receiver’s area_id. This is an optional parameter. If not included in the request payload, then our system will populate it automatically based on the recipient_address you will be provided. |
| delivery_type | integer | Yes | 48 for Normal Delivery, 12 for On Demand Delivery |
| item_type | integer | Yes | 1 for Document, 2 for Parcel |
| special_instruction | string | No | Any special instruction you may want to provide to us. |
| item_quantity | integer | Yes | Quantity of your parcels |
| item_weight | float | Yes | Minimum 0.5 KG to Maximum 10 kg. Weight of your parcel in kg |
| item_description | string | No | You can provide a description of your parcel |
| amount_to_collect | integer | Yes | Recipient Payable Amount. Default should be 0 in case of NON Cash-On-Delivery(COD)The collectible amount from the customer. |
Success Response: Status Code 200
{
+ message: "Order Created Successfully",
+ type: "success",
+ code: 200,
+ data: {
+ consignment_id: "{{ORDER_CONSIGNMENT_ID}}",
+ merchant_order_id: "{{merchant_order_id}}",
+ order_status: "Pending",
+ delivery_fee: 80
+ }
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| consignment_id | string | No | A unique identifier for the consignment. |
| merchant_order_id | string | Yes | The order id you provided to keep track of your order. |
| order_status | string | No | Your current order status |
| delivery_fee | number | No | Your parcel delivery fee |
Create a Bulk Order
Endpoint:
/aladdin/api/v1/orders/bulk To create a multiple orders at a time in Pathao Courier Merchant API, you need to provide the required information. The CURL for the POST Request is given, Use this as a reference. The API will return a success response with the created order details.
curl --location '{{base_url}}/aladdin/api/v1/orders/bulk' \
+ --header 'Content-Type: application/json; charset=UTF-8' \
+ --header 'Authorization: Bearer {{access_token}}' \
+ --data '{
+ "orders": [
+ {
+ "store_id": {{merchant_store_id}},
+ "merchant_order_id": "{{merchant_order_id}}",
+ "recipient_name": "Demo Recipient One",
+ "recipient_phone": "017XXXXXXXX",
+ "recipient_address": "House 123, Road 4, Sector 10, Uttara, Dhaka-1230, Bangladesh",
+ "delivery_type": 48,
+ "item_type": 2,
+ "special_instruction": "Do not put water",
+ "item_quantity": 2,
+ "item_weight": "0.5",
+ "amount_to_collect": 100,
+ "item_description": "This is a Cloth item, price- 3000"
+ },
+ {
+ "store_id": {{merchant_store_id}},
+ "merchant_order_id": "{{merchant_order_id}}",
+ "recipient_name": "Demo Recipient Two",
+ "recipient_phone": "015XXXXXXXX",
+ "recipient_address": "House 3, Road 14, Dhanmondi, Dhaka-1205, Bangladesh",
+ "delivery_type": 48,
+ "item_type": 2,
+ "special_instruction": "Deliver before 5 pm",
+ "item_quantity": 1,
+ "item_weight": "0.5",
+ "amount_to_collect": 200,
+ "item_description": "Food Item, Price 1000"
+ }
+ ]
+ }'Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| orders | array of order object | Yes | An array of order objects is required to send within the request body. |
Order Object
| Field name | Field type | Required | Description |
|---|---|---|---|
| store_id | integer | Yes | store_id is provided by the merchant and not changeable. This store ID will set the pickup location of the order according to the location of the store |
| merchant_order_id | string | No | Optional parameter, merchant order info/tracking id |
| recipient_name | string | Yes | Parcel receivers name. Name length should be between 3 to 100 characters. |
| recipient_phone | string | Yes | Parcel receivers contact number. Recipient phone length should be 11 characters. |
| recipient_secondary_phone | string | No | Parcel receivers secondary contact number. Recipient secondary phone length should be 11characters. This field is optional. |
| recipient_address | string | Yes | Parcel receivers full address. Address length should be between 10 to 220 characters. |
| recipient_city | integer | No | Parcel receiver’s city_id. This is an optional parameter, so do not send a null value. If not included in the request payload, then our system will populate it automatically based on the recipient_address you will be provided. |
| recipient_zone | integer | No | Parcel receiver’s zone_id. This is an optional parameter, so do not send a null value. If not included in the request payload, then our system will populate it automatically based on the recipient_address you will be provided. |
| recipient_area | integer | No | Parcel receiver’s area_id. This is an optional parameter. If not included in the request payload, then our system will populate it automatically based on the recipient_address you will be provided. |
| delivery_type | integer | Yes | 48 for Normal Delivery, 12 for On Demand Delivery |
| item_type | integer | Yes | 1 for Document, 2 for Parcel |
| special_instruction | string | No | Any special instruction you may want to provide to us. |
| item_quantity | integer | Yes | Quantity of your parcels |
| item_weight | float | Yes | Minimum 0.5 KG to Maximum 10 kg. Weight of your parcel in kg. |
| item_description | string | No | You can provide a description of your parcel. |
| amount_to_collect | integer | Yes | Recipient Payable Amount. Default should be 0 in case of NON Cash-On-Delivery(COD)The collectible amount from the customer. |
Success Response: Status Code 202
{
+ message: "Your bulk order creation request is accepted,<br> please wait some time to complete order creation.",
+ type: "success",
+ code: 202,
+ data: true
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| code | integer | No | Http response code for bulk order creation. |
| data | boolean | Yes | Data field is true if bulk order creation is accepted. |
Get Order Short Info
Endpoint:
/aladdin/api/v1/orders/{{consignment_id}}/info Get a short summary of your specific order
curl --location '{{base_url}}/aladdin/api/v1/orders/{{consignment_id}}/info' \
+ --header 'Authorization: Bearer {{access_token}}' \
+ --data ''Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| consignment_id | string | Yes | This unique id is used to identify the consignment. |
Success Response: Status Code 200
{
+ message: "Order info",
+ type: "success",
+ code: 200,
+ data: {
+ consignment_id: "{{consignment_id}}",
+ merchant_order_id: "{{merchant_order_id}}",
+ order_status: "Pending",
+ order_status_slug: "Pending",
+ updated_at: "2024-11-20 15:11:40",
+ invoice_id: null
+ }
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| consignment_id | string | No | A unique identifier for the consignment |
| merchant_order_id | string | Yes | The order id you provided |
| order_status_slug | string | No | Current status of your order |
Get List of Cities
Endpoint:
/aladdin/api/v1/city-list Get a summary of your current stores
curl --location '{{base_url}}/aladdin/api/v1/city-list' \
+ --header 'Content-Type: application/json; charset=UTF-8' \
+ --header 'Authorization: Bearer {{access_token}}' \
+ --data ''Success Response: Status Code 200
{
+ message: "City successfully fetched.",
+ type: "success",
+ code: 200,
+ data: {
+ data: [
+ {
+ city_id: 1,
+ city_name: "Dhaka"
+ },
+ {
+ city_id: 2,
+ city_name: "Chittagong"
+ },
+ {
+ city_id: 4,
+ city_name: "Rajshahi"
+ }
+ ]
+ }
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| city_id | integer | No | A unique identifier for the city |
| city_name | string | No | Formal city name |
Get zones inside a particular city
Endpoint:
/aladdin/api/v1/cities/{{city_id}}/zone-list Get List of Zones withing a particular City
curl --location '{{base_url}}/aladdin/api/v1/cities/{{city_id}}/zone-list' \
+ --header 'Content-Type: application/json; charset=UTF-8' \
+ --header 'Authorization: Bearer {{access_token}}' \
+ --data ''Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| city_id | integer | Yes | A unique identifier for the city |
Success Response: Status Code 200
{
+ message: "Zone list fetched.",
+ type: "success",
+ code: 200,
+ data: {
+ data: [
+ {
+ zone_id: 298,
+ zone_name: "60 feet"
+ },
+ {
+ zone_id: 1070,
+ zone_name: "Abdullahpur Uttara"
+ },
+ {
+ zone_id: 1066,
+ zone_name: "Abul Hotel "
+ }
+ ]
+ }
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| zone_id | integer | No | A unique identifier for the zone |
| zone_name | string | No | Formal zone name |
Get areas inside a particular zone
Endpoint:
/aladdin/api/v1/zones/{{zone_id}}/area-list Get List of Areas withing a particular Zone
curl --location '{{base_url}}/aladdin/api/v1/zones/{{zone_id}}/area-list' \
+ --header 'Content-Type: application/json; charset=UTF-8' \
+ --header 'Authorization: Bearer {{access_token}}' \
+ --data ''Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| zone_id | integer | Yes | A unique identifier for the zone |
Success Response: Status Code 200
{
+ message: "Area list fetched.",
+ type: "success",
+ code: 200,
+ data: {
+ data: [
+ {
+ area_id: 37,
+ area_name: " Bonolota",
+ home_delivery_available: true,
+ pickup_available: true
+ },
+ {
+ area_id: 3,
+ area_name: " Road 03",
+ home_delivery_available: true,
+ pickup_available: true
+ },
+ {
+ area_id: 4,
+ area_name: " Road 04",
+ home_delivery_available: true,
+ pickup_available: true
+ }
+ ]
+ }
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| area_id | integer | No | A unique identifier for the area |
| area_name | string | No | Formal area name |
| home_delivery_available | boolean | No | Shows if home delivery available or not |
| pickup_available | boolean | No | Shows if pickup available or not |
Price Calculation Api
Endpoint:
/aladdin/api/v1/merchant/price-plan To calculate price of the order use this post api
curl --location '{{base_url}}/aladdin/api/v1/merchant/price-plan'
+ --header 'Content-Type: application/json; charset=UTF-8'
+ --header 'Authorization: Bearer {{issue_token}}'
+ --data '{
+ "store_id": "{{merchant_store_id}}",
+ "item_type": 2,
+ "delivery_type": 48,
+ "item_weight": 0.5,
+ "recipient_city": {{city_id}},
+ "recipient_zone": {{zone_id}}
+ }'Request parameters
| Field name | Field type | Required | Description |
|---|---|---|---|
| store_id | integer | Yes | store_id is provided by the merchant and not changeable. This store ID will set the pickup location of the order according to the location of the store. |
| item_type | integer | Yes | 1 for Document, 2 for Parcel |
| delivery_type | integer | Yes | 48 for Normal Delivery, 12 for On Demand Delivery |
| item_weight | float | Yes | Minimum 0.5 KG to Maximum 10 kg. Weight of your parcel in kg |
| recipient_city | integer | Yes | Parcel receivers city_id |
| recipient_zone | integer | Yes | Parcel receivers zone_id |
Success Response: Status Code 200
{
+ message: "price",
+ type: "success",
+ code: 200,
+ data: {
+ price: 80,
+ discount: 0,
+ promo_discount: 0,
+ plan_id: 69,
+ cod_enabled: 1,
+ cod_percentage: 0.01,
+ additional_charge: 0,
+ final_price: 80
+ }
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| price | integer | No | Calculated price for given item |
| discount | integer | No | Discount for the given item |
| promo_discount | integer | No | Promo discount for the given item |
| plan_id | integer | No | Price plan id for the given item |
| cod_percentage | float | No | Cash on delivery percentage |
| additional_charge | integer | No | If there is any additional charge for the given item |
| final_price | number | No | Your final price for the given item |
Get Merchant Store Info
Endpoint:
/aladdin/api/v1/stores Get a summary of your current stores
curl --location '{{base_url}}/aladdin/api/v1/stores' \
+ --header 'Content-Type: application/json; charset=UTF-8' \
+ --header 'Authorization: Bearer {{access_token}}', \
+ --data ''Success Response: Status Code 200
{
+ message: "Store list fetched.",
+ type: "success",
+ code: 200,
+ data: {
+ data: [
+ {
+ store_id: "{{merchant_store_id}}",
+ store_name: "{{merchant_store_name}}",
+ store_address: "House 123, Road 4, Sector 10, Uttara, Dhaka-1230, Bangladesh",
+ is_active: 1,
+ city_id: "{{city_id}}",
+ zone_id: "{{zone_id}}",
+ hub_id: "{{hub_id}}",
+ is_default_store: false,
+ is_default_return_store: false
+ }
+ ],
+ total: 1,
+ current_page: 1,
+ per_page: 1000,
+ total_in_page: 1,
+ last_page: 1,
+ path: "{{base_url}}/aladdin/api/v1/stores",
+ to: 1,
+ from: 1,
+ last_page_url: "{{base_url}}/aladdin/api/v1/stores?page=1",
+ first_page_url: "{{base_url}}/aladdin/api/v1/stores?page=1"
+ }
+}Response data
| Field name | Field type | Optional | Description |
|---|---|---|---|
| store_id | integer | No | A unique identifier for the store |
| store_name | string | Yes | The name of the store |
| store_address | string | No | Address of the store |
| is_active | integer | No | 1 for active store & 0 for deactivated store. |
| city_id | integer | No | The city id of the store. |
| zone_id | integer | No | The zone id of the store. |
| hub_id | integer | No | The hub ID within which the store is located. |
| is_default_store | integer | No | 1 if the store is default_store otherwise 0. |
| is_default_return_store | integer | No | 1 if the store is default_return_store otherwise 0. |
