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.sg/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.
{
"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.
{
"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": "1 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.
{
"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": "#04-13, Sengkang Square, Compass One, Singapore",
"pickup_pincode": "545078",
"vehicle_type": "all"
},
"destination":{
"country":"SG",
"state":"Singapore",
"postcode":"415874"
}
}{
"data":[{
"deliverytype_id":"1",
"price":"13",
"delivery_type":"3 Hours Express",
"currency":"SGD"
},
{
"deliverytype_id":"3",
"price":"8",
"delivery_type":"Next Day Delivery",
"currency":"SGD"
},
{
"deliverytype_id":"4",
"price":"10",
"delivery_type":"Same Day Delivery",
"currency":"SGD"
},
{
"deliverytype_id":"5",
"price":"22",
"delivery_type":"2 Way Round Trip (same day)",
"currency":"SGD"
},
{
"deliverytype_id":"6",
"price":"20",
"delivery_type":"1 Hour Rush",
"currency":"SGD"
}],
"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.
{
"merchant_info":{
"access_token":"USER ACCESS TOKEN"
},
"delivery_package": [
{
"delivery_address": "#07-406, 470A Fernvale Link, Singapore 791470",
"delivery_pincode": "791470",
"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": "123 #07-406, 470A Fernvale Link, Singapore 791470",
"delivery_pincode": "791470",
"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": "#04-13, Sengkang Square, Compass One, Singapore",
"pickup_pincode": "545078",
"vehicle_type": "all"
}
}{
"data":[
[
{
"deliverytype_id":"1",
"price":"13",
"delivery_type":"3 Hours Express",
"currency":"SGD"
},
{
"deliverytype_id":"3",
"price":"8",
"delivery_type":"Next Day Delivery",
"currency":"SGD"
},
{
"deliverytype_id":"4",
"price":"10",
"delivery_type":"Same Day Delivery",
"currency":"SGD"
},
{
"deliverytype_id":"5",
"price":"22",
"delivery_type":"2 Way Round Trip (same day)",
"currency":"SGD"
},
{
"deliverytype_id":"6",
"price":"20",
"delivery_type":"1 Hour Rush",
"currency":"SGD"
}
],
[
{
"deliverytype_id":"1",
"price":"13",
"delivery_type":"3 Hours Express",
"currency":"SGD"
},
{
"deliverytype_id":"3",
"price":"8",
"delivery_type":"Next Day Delivery",
"currency":"SGD"
},
{
"deliverytype_id":"4",
"price":"10",
"delivery_type":"Same Day Delivery",
"currency":"SGD"
},
{
"deliverytype_id":"5",
"price":"22",
"delivery_type":"2 Way Round Trip (same day)",
"currency":"SGD"
},
{
"deliverytype_id":"6",
"price":"20",
"delivery_type":"1 Hour Rush",
"currency":"SGD"
}
]
],
"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.
{
"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":"12345678",
"pickup_address":"Kaki Bukit Building, Singapore",
"pickup_pincode":"415874",
"pickup_remark":"Pickup Remark",
"vehicle_type": "all"
},
"customer_detail":{
"name":"Curb",
"email":"curb@uparcel.sg",
"contact_number":"12345678",
"delivery_address":"Kaki Bukit Building, Singapore",
"delivery_pincode":"415874",
"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.
{
"merchant_detail":{
"access_token":"USER ACCESS TOKEN"
},
"delivery_package":[{
"contact_number": "12345678",
"delivery_address": "#07-406, 470A Fernvale Link, Singapore 791470",
"delivery_pincode": "791470",
"delivery_type": 3,
"delivery_type_name": "None",
"email": "curb@uparcel.sg",
"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": "12345678",
"delivery_address": "#07-406, 470A Fernvale Link, Singapore 791470",
"delivery_pincode": "791470",
"delivery_type": 3,
"delivery_type_name": "None",
"email": "curb@uparcel.sg",
"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":"12345678",
"pickup_address":"Kaki Bukit Building, Singapore",
"pickup_pincode":"415874",
"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.
{
"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.
{
"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.
{
"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.) |