API Reference

uParcel API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

You can use the uParcel API on staging server, which does not affect live data or interact with the real users. The API key you use to authenticate the request determines whether the request from valid user or not.

https://stg.uparcel.co/

Authentication

uParcel API uses API key and Secret key to authenticate and generate access token. You can view and manage your API key and Secret key in the Customer account.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

URL:

https://stg.uparcel.co/api/merchant/auth/

1
2
3
4
5
6
{
    "api_key":"UPARCEL API KEY",
    "secret_key":"UPARCEL SECRET KEY",
    "api_platform":"Open",
    "domain_info":"WEBSITE DOMAIN"
}

                              {
  "data": {
    "access_token": "USER ACCESS TOKEN"
  },
  "result": "SUCCESS",
  "errors": [],
  "status": 200,
  "message": "Access token successfully received."
}
                            
                          

Delivery Type Services

This API is used to list down all the delivery types available at uParcel.

The obtained response shows the following detailed form of the keys:

Data key will consist of delivery_type collection that consists of items that has id_delivery_type key as a unique identifier of the delivery_type.

Status key with the output 200 represents the Success case whereas the output 401 represents the Failure case.

Message key shows the respective message for Success and Failure case.

1
2
3
{
    "access_token":"USER ACCESS TOKEN"
}

              {
  "data": {
    "delivery_type": [{
      "id_delivery_type": 1,
      "delivery_type": "3 hours express",
      "date_time_picker": "0"
    },
    {
      "id_delivery_type": 3,
      "delivery_type": "Next Day Delivery",
      "date_time_picker": "0"
    },
    {
      "id_delivery_type": 4,
      "delivery_type": "Same Day Delivery",
      "date_time_picker": "0"
    },
    {
      "id_delivery_type": 5,
      "delivery_type": "2 way round trip (same day)",
      "date_time_picker": "0"
    },
    {
      "id_delivery_type": 6,
      "delivery_type": "2 Hour Rush",
      "date_time_picker": "0"
    }]
  },
  "result": "SUCCESS",
  "errors": [],
  "status": 200,
  "message": "Delivery type successfully received."
}
              
            

Package Pricing

This API is used to decide the delivery charges based on various parameters like dimension, weight, size and quantity of the parcel to be packed and destination where the particular parcel is to be delivered. The values for vehicle_type can be all, van or lorry.

The obtained response shows the following detailed form of the keys:

Data key will consist of the package pricing collection, each item consists of a unique identifier deliverytype_id, price, delivery_type and currency.

Status key with the output 200 represents the Success case whereas the output 401 represents the Failure case.

Message key shows the respective message for Success and Failure case.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "merchant_info":{
    "access_token":"USER ACCESS TOKEN"
  },
  "packages":[{
    "quantity":"1",
    "weight":{
      "value":"3",
      "units":"kg"
    },
    "dimensions":{
      "length":"10",
      "width":"15",
      "height":"20",
      "units":"cm"
    }
  }],
  "pickup_detail": {
    "pickup_address": "226, Jalan Taman Piasau 4, Piasau, Miri, Sarawak, Malaysia",
    "pickup_pincode": "98000",
    "vehicle_type": "all"
  },
  "destination":{
    "country":"MY",
    "state":"Malaysia",
    "postcode":"415874"
  }
}

              {
  "data":[{
     "deliverytype_id":"1",
     "price":"13",
     "delivery_type":"3 Hours Express",
     "currency":"RM"
  },
  {
     "deliverytype_id":"3",
     "price":"8",
     "delivery_type":"Next Day Delivery",
     "currency":"RM"
  },
  {
     "deliverytype_id":"4",
     "price":"10",
     "delivery_type":"Same Day Delivery",
     "currency":"RM"
  },
  {
     "deliverytype_id":"5",
     "price":"22",
     "delivery_type":"2 Way Round Trip (same day)",
     "currency":"RM"
  },
  {
     "deliverytype_id":"6",
     "price":"20",
     "delivery_type":"2 Hour Rush",
     "currency":"RM"
  }],
  "result":"Success",
  "errors":[],
  "status":200,
  "message":"Package price successfully received."
}
  
              
            

Package Pricing for Multiple Delivery Locations

This API is used to decide the delivery charges based on various parameters like dimension, weight, size and quantity of the parcel to be packed and destination where the particular parcel is to be delivered. The values for vehicle_type can be all, van or lorry.

The obtained response shows the following detailed form of the keys:

Data key will consist of the package pricing collection, each item consists of a unique identifier deliverytype_id, price, delivery_type and currency.

Status key with the output 200 represents the Success case whereas the output 401 represents the Failure case.

Message key shows the respective message for Success and Failure case.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "merchant_info":{
    "access_token":"USER ACCESS TOKEN"
  },
  "delivery_package": [
    {
      "delivery_address": "2238, Jalan Kasban, Meru, Klang, Selangor, Malaysia",
      "delivery_pincode": "41050",
      "delivery_type": 1,
      "dimensions": {
        "height": "10",
        "length": "10",
        "units": "cm",
        "width": "10"
      },
      "product_id": "1",
      "quantity": "1",
      "sku": "Minks medicine",
      "weight": {
        "units": "kg",
        "value": "1"
      }
    },
    {
      "delivery_address": "2238, Jalan Kasban, Meru, Klang, Selangor, Malaysia",
      "delivery_pincode": "41050",
      "delivery_type": 1,
      "dimensions": {
        "height": "10",
        "length": "10",
        "units": "cm",
        "width": "10"
      },
      "product_id": "1",
      "quantity": "1",
      "sku": "Minks medicine",
      "weight": {
        "units": "kg",
        "value": "1"
      }
    }
  ],
  "pickup_detail": {
    "pickup_address": "226, Jalan Taman Piasau 4, Piasau, Miri, Sarawak, Malaysia",
    "pickup_pincode": "98000",
    "vehicle_type": "all"
  }
}

              {
  "data":[
    [
      {
         "deliverytype_id":"1",
         "price":"13",
         "delivery_type":"3 Hours Express",
         "currency":"RM"
      },
      {
         "deliverytype_id":"3",
         "price":"8",
         "delivery_type":"Next Day Delivery",
         "currency":"RM"
      },
      {
         "deliverytype_id":"4",
         "price":"10",
         "delivery_type":"Same Day Delivery",
         "currency":"RM"
      },
      {
         "deliverytype_id":"5",
         "price":"22",
         "delivery_type":"2 Way Round Trip (same day)",
         "currency":"RM"
      },
      {
         "deliverytype_id":"6",
         "price":"20",
         "delivery_type":"2 Hour Rush",
         "currency":"RM"
      }
    ],
    [
      {
         "deliverytype_id":"1",
         "price":"13",
         "delivery_type":"3 Hours Express",
         "currency":"RM"
      },
      {
         "deliverytype_id":"3",
         "price":"8",
         "delivery_type":"Next Day Delivery",
         "currency":"RM"
      },
      {
         "deliverytype_id":"4",
         "price":"10",
         "delivery_type":"Same Day Delivery",
         "currency":"RM"
      },
      {
         "deliverytype_id":"5",
         "price":"22",
         "delivery_type":"2 Way Round Trip (same day)",
         "currency":"RM"
      },
      {
         "deliverytype_id":"6",
         "price":"20",
         "delivery_type":"2 Hour Rush",
         "currency":"RM"
      }
    ]
  ],
  "result":"Success",
  "errors":[],
  "status":200,
  "message":"Package price successfully received."
}
  
              
            

Submit Order

Order Submit API is used in order to post jobs in uParcel platform. This supports single pickup and single drop off locations. The values for vehicle_type can be all, van or lorry.

The obtained response shows the following detailed form of the keys:

Data key will consist of the tracking_number key which has the list of tracking number for the corresponding orders.

Status key with the output 200 represents the Success case whereas the output 401 represents the Failure case.

Message key shows the respective message for Success and Failure case.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
  "merchant_detail":{
    "access_token":"USER ACCESS TOKEN"
  },
  "delivery_package":[{
    "quantity":"1.0000",
    "sku":"blue-t-shirt",
    "product_id":"1",
    "weight":{
      "value":"10.0000",
      "units":"kg"
    },
    "dimensions":{
      "length":"20",
      "width":"20",
      "height":"30",
      "units":"cm"
    }
  },
  {
    "quantity":"1.0000",
    "sku":"black-t-shirt",
    "product_id":"2",
    "weight":{
      "value":"3.0000",
      "units":"kg"
    },
    "dimensions":{
      "length":"10",
      "width":"10",
      "height":"10",
      "units":"cm"
    }
  }],
  "order_id":"MERCHANT ORDER ID",
  "pickup_detail":{
    "name":"Curb",
    "contact_number":"123456789",
    "pickup_address":"226, Jalan Taman Piasau 4, Piasau, Miri, Sarawak, Malaysia",
    "pickup_pincode":"98000",
    "pickup_remark":"Pickup Remark",
    "vehicle_type": "all"
  },
  "customer_detail":{
    "name":"Curb",
    "email":"curb@uparcel.co",
    "contact_number":"123456789",
    "delivery_address":"2238, Jalan Kasban, Meru, Klang, Selangor, Malaysia",
    "delivery_pincode":"41050",
    "delivery_type_name":"Uparcel - Same Day (pickup after 5pm is delivered next morning)",
    "delivery_type":"29",
    "delivery_remark":"Some remarks",
    "api_response_url":"STATUS UPDATE WEBHOOK URL"
  }
}

              {
  "data":{
    "tracking_number": [
        "NA4AUO"
    ],
    "delivery_date":"2019-12-06",
    "delivery_time":""
  },
  "result":"Success",
  "errors":[],
  "status":200,
  "message":"Order successfully placed."
}
  
              
            

Submit Order with Multiple Delivery Locations

This supports single pickup and one or more than one drop off locations. The values for vehicle_type can be all, van or lorry.

The obtained response shows the following detailed form of the keys:

Data key will consist of the tracking_number key which has the list of tracking number for the corresponding orders.

Status key with the output 200 represents the Success case whereas the output 401 represents the Failure case.

Message key shows the respective message for Success and Failure case.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
  "merchant_detail":{
    "access_token":"USER ACCESS TOKEN"
  },
  "delivery_package":[{
    "contact_number": "123456789",
    "delivery_address": "2238, Jalan Kasban, Meru, Klang, Selangor, Malaysia",
    "delivery_pincode": "41050",
    "delivery_type": 3,
    "delivery_type_name": "None",
    "email": "curb@uparcel.co",
    "name": "Curb",
    "quantity":"1.0000",
    "sku":"blue-t-shirt",
    "product_id":"1",
    "weight":{
      "value":"10.0000",
      "units":"kg"
    },
    "dimensions":{
      "length":"20",
      "width":"20",
      "height":"30",
      "units":"cm"
    }
  },
  {
    "contact_number": "123456789",
    "delivery_address": "2238, Jalan Kasban, Meru, Klang, Selangor, Malaysia",
    "delivery_pincode": "41050",
    "delivery_type": 3,
    "delivery_type_name": "None",
    "email": "curb@uparcel.co",
    "name": "Curb",
    "quantity":"1.0000",
    "sku":"black-t-shirt",
    "product_id":"2",
    "weight":{
      "value":"3.0000",
      "units":"kg"
    },
    "dimensions":{
      "length":"10",
      "width":"10",
      "height":"10",
      "units":"cm"
    }
  }],
  "order_id":"MERCHANT ORDER ID",
  "api_response_url": "STATUS UPDATE WEBHOOK URL",
  "pickup_detail":{
    "name":"Curb",
    "contact_number":"123456789",
    "pickup_address":"226, Jalan Taman Piasau 4, Piasau, Miri, Sarawak, Malaysia",
    "pickup_pincode":"98000",
    "pickup_remark":"Pickup Remark",
    "vehicle_type": "all"
  }
}

              {
  "data":{
    "tracking_number": [
        "RM7ZRC",
        "N8EW2K"
    ],
    "delivery_date":"2019-12-06",
    "delivery_time":""
  },
  "result":"Success",
  "errors":[],
  "status":200,
  "message":"Order successfully placed."
}
  
              
            

Cancel Order

This API is used to cancel the already submitted order.

The obtained response shows the following detailed form of the keys:

Status key with the output 200 represents the Success case whereas the output 401 represents the Failure case.

Message key shows the respective message for Success and Failure case.

1
2
3
4
5
6
{
  "merchant_detail":{
    "access_token":"USER ACCESS TOKEN"
  },
  "order_id":"MERCHANT ORDER ID"
}

              {
  "data":[],
  "result":"Success",
  "errors":[],
  "status":200,
  "message":"Order successfully cancelled."
}
  
              
            

Parcel Tracking Status

This API is used to track the parcel, and to get the status of the parcel.

The obtained response shows the following detailed form of the keys:

Data key consist of the properties associated with the tracking code provided namely id_order_status, tracking_code, remarks, receiver_name, image_name, parcel_image_name, undelivered_image, latitude, longitude, address, created_date, id_order_delivery, id_general_status, general_status_label

Status key with the output 200 represents the Success case whereas the output 401 represents the Failure case.

Message key shows the respective message for Success and Failure case.

1
2
3
4
5
6
7
8
{
  "tracking_number":[
    "NA4AUO"
  ],
  "merchant_detail":{
    "access_token":"USER ACCESS TOKEN"
  }
}

              {
  "data": [{
     "id_order_status":1510,
     "tracking_code":"NA4AUO",
     "remarks":"",
     "receiver_name":"",
     "image_name":"",
     "parcel_image_name":"",
     "undelivered_image":"",
     "latitude":null,
     "longitude":null,
     "address":"",
     "created_date":"2019-12-05T12:28:23.244605Z",
     "id_order_delivery":1330,
     "id_general_status":4,
     "general_status_label":"Pending Acceptance"
  }],
  "result":"Success",
  "errors":[],
  "status":200,
  "message":"Parcel status successfully listed."
}
  
              
            

Job Status List

This API is used to list down all possible job status available at uParcel.

The obtained response shows the following detailed form of the keys:

Data key consist of job_status key that stores a collection of all the job status, each item has a id_status unique identifier and status name

Status key with the output 200 represents the Success case whereas the output 401 represents the Failure case.

Message key shows the respective message for Success and Failure case.

1
2
3
{
  "access_token":"USER ACCESS TOKEN"
}

              {
  "data": [{
    "job_status": [{
       "id_status":4,
       "status":"Pending Acceptance"
    },
    {
       "id_status":5,
       "status":"Pick up in Progress"
    },
    {
       "id_status":6,
       "status":"Picked"
    },
    {
       "id_status":7,
       "status":"Item Picked Up"
    },
    {
       "id_status":8,
       "status":"Delivered"
    },
    {
       "id_status":9,
       "status":"Undelivered"
    },
    {
       "id_status":23,
       "status":"Two Way Delivered"
    },
    {
       "id_status":24,
       "status":"Two Way Undelivered"
    }
  }],
  "result":"Success",
  "errors":[],
  "status":200,
  "message":"Job status successfully received."
}
  
              
            

Errors

uParcel uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with uParcel's servers (these are rare).

200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing(incorrect) a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on uParcels's end. (These are rare.)

API Documentation

API Reference

Authentication

Delivery Type Services

Package Pricing

Package Pricing for Multiple Delivery Locations

Submit Order

Submit Order with Multiple Delivery Locations

Cancel Order

Parcel Tracking Status

Job Status List

Errors