Jumppoint Open API v3 Documentation

Table of Contents

Overview

All API endpoints listed in this documentation are relative to

  1. Production: https://open-api.jumppoint.io/
  2. Sandbox: https://staging.open-api.jumppoint.io/

Authentication

Error Message





{
  "statusCode": 401,
  "message": "Unauthorized"
}

Rate Limit

Rate limiting is applied. All endpoints have a limit of 10 requests per second. You will be blocked once you make the maximum amount of requests.

Error Message





{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

API

Changelogs

Shipment

POST /v3/shipment

To create a Shipment (with a list of items)

Resource URL

Resource Information

Request Content-Type Response formats Requires authentication
application/json application/json; charset=utf-8 Yes

Body Parameters

Name Type Required Description Example
externalOrderNumber string No Order number for your own reference A00001
shipmentCategory string Yes Specify the type of your shipment
See below		 parcel / freight
origin object Yes Sender information Parcel to-door: See below
Parcel drop-off: See below
Freight: See below
destination object Yes Receipient information Parcel to-door: See below
Parcel drop-off: See below
Freight: See below
items array Yes Parcel details See below
pickUpDate string Yes Hong Kong Time
Format: YYYY-MM-DD;
Must be after today, excluding Sunday and public holidays		 "2021-12-31"
pickUpTimeslot string Yes Hong Kong Time
Format: HH:mm-HH:mm;		 "10:30-13:00"
or null for not designated
See below
deliveryDate string No Hong Kong Time
Format: YYYY-MM-DD;
Must be after pickUpDate, excluding Sunday and public holidays		 "2021-12-31"
deliveryTimeslot string No Hong Kong Time
Format: HH:mm-HH:mm;		 "15:00-18:00"
or null for not designated
See below
paymentMethod string Yes See below "PAID_BY_RECEIVER"
cod decimal(8,2) Required if paymentMethod is 'PAID_BY_MERCHANT_COD' or 'CASH_ON_DELIVERY' Amount you wish to receive from receiptient excluding the shipment fee 200
notes string No Special note to be marked on the shipment
Maximum: 250 characters		 Fragile - handle with care
webhookUrl string No See Webhook;
Maximum: 250 characters		 'https://c977-61-244-155-9.ngrok.io/webhook/jumppoint'
origin-parcel-todoor-POSTv3
Name Type Required Description Example
contactName string Yes Maximum: 30 characters 'Peter Chan'
contactPhone string Yes 8 digits '98745632'
address string Yes Maximum: 250 characters '新蒲崗大有街31號善美工業大廈'
floor string No Maximum: 10 characters '10'
room string No Maximum: 10 characters '01'
origin-parcel-dropoff-POSTv3
Name Type Required Description Example
contactName string Yes Maximum: 30 characters 'Peter Chan'
contactPhone string Yes 8 digits '98745632'
store string Yes Get from GET /pick-up-store/list?isDropOff=1 'HKPANY'
origin-freight-POSTv3
Name Type Required Description Example
contactName string Yes Maximum: 30 characters 'Peter Chan'
contactPhone string Yes 8 digits '98745632'
address string Yes Maximum: 250 characters '新蒲崗大有街31號善美工業大廈'
floor string No Maximum: 10 characters '10'
room string No Maximum: 10 characters '01'
freightType string Yes See below 'b2b'
addressType string Yes b2b options: See below
shuttling options: See below		 'airport'
destination-parcel-todoor-POSTv3
Name Type Required Description Example
contactName string Yes Maximum: 30 characters 'Peter Chan'
contactPhone string Yes 8 digits;
Mobile numbers should be used in order to receive SMS		 '98745632'
address string Yes Maximum: 250 characters '新蒲崗大有街31號善美工業大廈'
floor string Yes Maximum: 10 characters '10'
room string Yes Maximum: 10 characters '01'
destination-parcel-store-POSTv3
Name Type Required Description Example
contactName string Yes Maximum: 30 characters 'Peter Chan'
contactPhone string Yes 8 digits '98745632'
store string Yes Get from GET /pick-up-store/list 'OK123'
destination-freight-POSTv3
Name Type Required Description Example
contactName string Yes Maximum: 30 characters 'Peter Chan'
contactPhone string Yes 8 digits '98745632'
address string Yes Maximum: 250 characters '新蒲崗大有街31號善美工業大廈'
floor string No Maximum: 10 characters '10'
room string No Maximum: 10 characters '01'
freightType string Yes See below 'b2b'
addressType string Yes b2b options: See below
shuttling options: See below		 'airport'
item-POSTv3
Name Type Required Description Example
externalOrderNumber string No Maximum: 50 characters '000235462'
dimension string Yes See below 'D01'
actualWeight number Required for standard parcel delivery (i.e. no delivery date specified)
in kg;		 DECIMAL(8,2) 2.15
weight string Required for any other types of delivery See below 'W01'
temperature string Required See below 'T01'
category string Required if no categoryOther provided For parcel standard delivery: See below
For other types of delivery: See below		 'C203'
categoryOther string Required if no category provided Maximum: 10 characters 'Toys'
notes string No Maximum: 250 characters "call customer 30 mins before delivery"
pick-up-timeslots
Parcel pick-up timeslots
Value Temperature
null Room-temperature
null Cold-chain
Freight pick-up timeslots
Value Temperature
null Room-temperature
null Cold-chain
delivery-timeslots
Parcel delivery timeslots
Value Temperature
null Room-temperature
11:00-16:00 Cold-chain Express only
16:00-20:00 Cold-chain Express only
null Cold-chain
Freight delivery timeslots
Value Temperature
null Room-temperature
11:00-16:00 Cold-chain Express only
16:00-20:00 Cold-chain Express only
null Cold-chain

Example Request Body

Self-pickup parcel (please via GET /v3/pick-up-store/list to check the "store" code of the available pickup stores )






























{
    "externalOrderNumber": "dummySE",
    "shipmentCategory": "parcel",
    "origin":{
        "contactName": "Kelvin Sender",
        "contactPhone": "99999999",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "destination":{
        "contactName": "tester",
        "contactPhone": "99999999",
        "store": "SE0000"
    },
    "items":[
        {
            "externalOrderNumber": "dummySE01",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T01",
            "categoryOther": "Something",
            "notes": "testing"
        }
    ],
    "pickUpDate": "2025-10-16",
    "paymentMethod": "PAID_BY_MERCHANT",
    "notes":"testing"
}
Non-temperature control standard parcel











































{
    "externalOrderNumber": "non-temp-standard-parcel-1",
    "shipmentCategory": "parcel",
    "origin":{
        "contactName": "Kelvin Sender",
        "contactPhone": "67891234",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "destination":{
        "contactName": "Kelvin Receiver",
        "contactPhone": "67891234",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "items":[
        {
            "externalOrderNumber": "item-001",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T01",
            "categoryOther": "Something",
            "notes": "nice one"
        },
                {
            "externalOrderNumber": "item-002",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T01",
            "categoryOther": "Something",
            "notes": "nice one2"
        }
    ],
    "pickUpDate": "2024-12-14",
    // "pickUpTimeslot": "",
    // "deliveryDate": "",
    // "DeliveryTimeslot": "",
    "paymentMethod": "PAID_BY_MERCHANT",
    "notes":"hello testing standard"
    // "webhookUrl":""
}
Non-temperature control express parcel











































{
    "externalOrderNumber": "non-temp-express-parcel-1",
    "shipmentCategory": "parcel",
    "origin":{
        "contactName": "Kelvin Sender",
        "contactPhone": "67891234",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "destination":{
        "contactName": "Kelvin Receiver",
        "contactPhone": "67891234",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "items":[
        {
            "externalOrderNumber": "express-item-001",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T01",
            "categoryOther": "Something",
            "notes": "nice one"
        },
                {
            "externalOrderNumber": "express-item-002",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T01",
            "categoryOther": "Something",
            "notes": "nice one2"
        }
    ],
    "pickUpDate": "2024-12-16",
    // "pickUpTimeslot": "",
    "deliveryDate": "2024-12-16",
    // "DeliveryTimeslot": "",
    "paymentMethod": "PAID_BY_MERCHANT",
    "notes":"hello testing standard"
    // "webhookUrl":""
}
Temperature control express parcel











































{
    "externalOrderNumber": "temp-express-parcel-1",
    "shipmentCategory": "parcel",
    "origin":{
        "contactName": "Kelvin Sender",
        "contactPhone": "67891234",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "destination":{
        "contactName": "Kelvin Receiver",
        "contactPhone": "67891234",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "items":[
        {
            "externalOrderNumber": "temp-express-item-001",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T02",
            "categoryOther": "Something",
            "notes": "nice one"
        },
                {
            "externalOrderNumber": "temp-express-item-002",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T02",
            "categoryOther": "Something",
            "notes": "nice one2"
        }
    ],
    "pickUpDate": "2024-12-14",
    // "pickUpTimeslot": "",
    "deliveryDate": "2024-12-16",
    // "DeliveryTimeslot": "",
    "paymentMethod": "PAID_BY_MERCHANT",
    "notes":"hello testing express"
    // "webhookUrl":""
}
Temperature control same-day parcel











































{
    "externalOrderNumber": "temp-sameday-parcel-1",
    "shipmentCategory": "parcel",
    "origin":{
        "contactName": "Kelvin Sender",
        "contactPhone": "67891234",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "destination":{
        "contactName": "Kelvin Receiver",
        "contactPhone": "67891234",
        "address":"新蒲崗大有街31號善美工業大廈",
        "floor": "10",
        "room": "A"
    },
    "items":[
        {
            "externalOrderNumber": "temp-express-item-001",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T02",
            "categoryOther": "Something",
            "notes": "nice one"
        },
                {
            "externalOrderNumber": "temp-express-item-002",
            "dimension":"D01",
            "actualWeight": 2,
            "temperature": "T02",
            "categoryOther": "Something",
            "notes": "nice one2"
        }
    ],
    "pickUpDate": "2024-12-16",
    // "pickUpTimeslot": "",
    "deliveryDate": "2024-12-16",
    // "DeliveryTimeslot": "",
    "paymentMethod": "PAID_BY_MERCHANT",
    "notes":"hello testing same-day"
    // "webhookUrl":""
}

Example Response














































































{
    "status": "Success",
    "data": {
        "shipment": {
            "refNo": "AIGNITER_EO_011244",
            "trackingNumber": "JP319037246154",
            "origin": {
                "contactName": "Kelvin Sender",
                "contactPhone": "67891234",
                "address": "新蒲崗大有街31號善美工業大廈",
                "floor": "10",
                "room": "A"
            },
            "destination": {
                "contactName": "Kelvin Receiver",
                "contactPhone": "67891234",
                "address": "新蒲崗大有街31號善美工業大廈",
                "floor": "10",
                "room": "A"
            },
            "shipmentCategory": "parcel",
            "temperature": "non",
            "speed": "standard",
            "state": "created",
            "createdAt": "2024-12-16 15:52",
            "pickUpDate": "2024-12-17",
            "pickUpTimeslot": "10:30-13:30",
            "deliveryDate": "Invalid date",
            "deliveryTimeslot": "15:00-18:00",
            "paymentMethod": "PAID_BY_MERCHANT",
            "shipmentFee": 27,
            "additionalWeightFee": 0,
            "totalFee": 27,
            "totalCharge": 27,
            "items": [
                {
                    "trackingNumber": "JP319037246154",
                    "externalOrderNumber": "item-001",
                    "waybillTrackingNumber": "JP319037246154",
                    "state": "created",
                    "statusLogs": [
                        {
                            "time": "2024-12-16 15:52",
                            "status": "Created"
                        }
                    ],
                    "dimension": "D01",
                    "temperature": "T01",
                    "categoryOther": "Something",
                    "actualWeight": 2,
                    "cargoValue": null,
                    "notes": "nice one"
                },
                {
                    "trackingNumber": "JP319037246173",
                    "externalOrderNumber": "item-002",
                    "waybillTrackingNumber": "JP319037246173",
                    "state": "created",
                    "statusLogs": [
                        {
                            "time": "2024-12-16 15:52",
                            "status": "Created"
                        }
                    ],
                    "dimension": "D01",
                    "temperature": "T01",
                    "categoryOther": "Something",
                    "actualWeight": 2,
                    "cargoValue": null,
                    "notes": "nice one2"
                }
            ]
        },
        "amountDeducted": true,
        "accountBalance": 99779064.99
    }
}

GET /v3/shipment/{trackingNumber}

To retrieve the details of a specific shipment

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Request Parameters

Name Type Required Description Example
trackingNumber string Yes Tracking Number of the shipment / any items belonging to the shipment you wish to retrieve JP319037069928

Response Parameters

Parameter Type Description Example
trackingNumber string Tracking Number of the parent shipment 'JP319037069928'
refNo string Tracking Number of the parent shipment 'AIGNITER_EO_002934'
externalOrderNumber string External Order Number
(if any)		 "0951358"
orderDate string Creation Time of the shipment; at Hong Kong Time; "2021-06-25 16:57"
state string Current status of the shipment; See shipmentState 'On the way to customer'
temperature string non/single/multi 'non'
speed string same-day/express/standard 'express'
pickUpDate string Pick Up Date of the shipment '2021-06-26'
deliveryDate string Delivery Date of the shipment '2021-06-27'
shipmentFee number Shipment Fee 68
additionalWeightFee number Additional Weight Fee - a surcharge for exceeding certain weight; 2
totalFee number Shipment Fee + Additional Weight Fee 70
totalCharge number Total Charge 70
paymentMethod string Payment Method 'PAID_BY_MERCHANT'
cod decimal(8,2) Cash On Delivery Amount 100
notes string Order Notes (if any) "call customer before delivery"
origin object Sender Address Details [see below]
destination object Receiptient Address Details [see below]
items Array Item Details [see below]
statusLogs array Trackings of shipment sorted by time descendingly [see below for objects in the array]

origin-v3

Parameter Type Description Example
contactName string Name of sender 'Peter Chan'
contactPhone string Phone number of sender '98745632'
address string Sender Address;
Only applicable when shipment is not drop-off at Pick Up Stores;		 '新蒲崗大有街31號善美工業大廈'
store string Drop-off store;
Only applicable when shipment is drop-off at Pick Up Stores;		 Get from GET /pick-up-store/list?isDropOff=1
floor string Floor number of sender address (if any);
Only applicable when shipment is not delivering to Pick Up Stores;		 '10'
room string Floor number of sender address (if any);
Only applicable when shipment is not delivering to Pick Up Stores;		 '01'
freightType string Only with freight shipment 'b2b'
addressType string Only available with freight shipment 'hotel_receiving_department'

destination-v3

Parameter Type Description Example
contactName string Name of receiptient 'Peter Chan'
contactPhone string Phone number of receiptient '98745632'
address string Receiptient Address;
Only applicable when shipment is not delivering to Pick Up Stores;		 '新蒲崗大有街31號善美工業大廈'
floor string Floor number of receiptient address (if any);
Only applicable when shipment is not delivering to Pick Up Stores;		 '10'
room string Floor number of receiptient address (if any);
Only applicable when shipment is not delivering to Pick Up Stores;		 '01'
freightType string Only applicable with freight shipment 'b2b'
addressType string Only applicable with freight shipment 'hotel_receiving_department'
item-v3
Parameter Type Description Example
trackingNumber string Tracking Number of the child item "JP658854693314"
state string Current status of the item; See itemState 'On the way to customer'
externalOrderNumber string External Order Number
(if any)		 "0951358"
dimension string Dimension Details [see below]
actualWeight number Actual Weight of parcel (in kg);
Only applicable for standard parcel delivery;		 2
weight string Weight Details;
Applicable for any other types of deliveries		 [see below]
adjustedWeight number Adjusted Weight of parcel (in kg) (if any) 2.3
adjustedLength number Adjusted Length of parcel (in cm) (if any) 10.2
adjustedWidth number Adjusted Width of parcel (in cm) (if any) 10.2
adjustedHeight number Adjusted Height of parcel (in cm) (if any) 5.5
temperature string Temperature Details; [see below]
category string Category Details;
Only applicable if no 'category' inputted		 [see below]
statusLogs array Trackings of item sorted by time descendingly [see below for objects in the array]
notes string Order Notes (if any) "call customer before delivery"

statusLogs-v3

Parameter Type Description Example
time string format: 'YYYY-MM-DD HH:mm' '2021-09-27 10:34'
status string Shipment/Item State 'Created'
remarks string (if any) 'Nobody answered the door 無人應門'

Example Response











































































{
    "shipment": {
        "refNo": "AIGNITER_EO_006810",
        "trackingNumber": "JP319037093644",
        "origin": {
            "contactName": "123",
            "contactPhone": "12341234",
            "address": "12312312313213",
            "freightType": "b2b",
            "addressType": "airport"
        },
        "destination": {
            "contactName": "123",
            "contactPhone": "12341234",
            "address": "123123",
            "freightType": "b2b",
            "addressType": "airport"
        },
        "shipmentCategory": "freight",
        "temperature": "non",
        "speed": "standard",
        "state": "cancelled",
        "createdAt": "2024-09-24 18:42",
        "pickUpDate": "2024-09-26",
        "pickUpTimeslot": "10:30-13:30",
        "deliveryDate": "2024-09-27",
        "deliveryTimeslot": "15:00-18:00",
        "paymentMethod": "PAID_BY_MERCHANT",
        "shipmentFee": 340,
        "additionalWeightFee": 0,
        "totalFee": 340,
        "totalCharge": 340,
        "items": [
            {
                "trackingNumber": "JP319037093644",
                "externalOrderNumber": "123",
                "waybillTrackingNumber": "JP319037093644",
                "state": "created",
                "statusLogs": [
                    {
                        "time": "2024-09-24 18:42",
                        "status": "Created"
                    }
                ],
                "dimension": "D02",
                "temperature": "T01",
                "categoryOther": "car parts",
                "cargoValue": 4400,
                "unit": "pallet",
                "quantity": 1,
                "notes": "Sensitive to moisture"
            },
            {
                "trackingNumber": "JP319037093649",
                "externalOrderNumber": "1232",
                "waybillTrackingNumber": "JP319037093649",
                "state": "created",
                "statusLogs": [
                    {
                        "time": "2024-09-24 18:42",
                        "status": "Created"
                    }
                ],
                "dimension": "D02",
                "temperature": "T01",
                "categoryOther": "motor",
                "cargoValue": 4400,
                "unit": "pallet",
                "quantity": 1,
                "notes": "Right-side up"
            }
        ]
    }
}

Example Error Messages

Invalid trackingNumber (Status Code: 404)



{
  "message": "Shipment cannot be found"
}

Item

GET /v3/item/options

To retrieve lists of valid item options

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Request Parameters

Name Type Required Description Example
isTemperature boolean Required TODO true
isStandard boolean Required TODO true
itemTypeId string Required TODO TODO 'e6ce5827-3209-44f5-a989-0aa9efba8bfc'

Example Response

















































































































{
    "options": {
        "categoryStandard": [
            {
                "id": "C101",
                "descriptionEn": "Documents",
                "descriptionChi": "文件"
            },
            {
                "id": "C102",
                "descriptionEn": "Electronic Products",
                "descriptionChi": "電子產品"
            },
            {
                "id": "C103",
                "descriptionEn": "Daily Necessities",
                "descriptionChi": "日用品"
            },
            {
                "id": "C104",
                "descriptionEn": "Clothes",
                "descriptionChi": "服飾"
            },
            {
                "id": "C105",
                "descriptionEn": "Food",
                "descriptionChi": "食品"
            }
        ],
        "categorySameDay": [
            {
                "id": "C201",
                "descriptionEn": "Wine",
                "descriptionChi": "酒"
            },
            {
                "id": "C202",
                "descriptionEn": "Food",
                "descriptionChi": "食品"
            },
            {
                "id": "C203",
                "descriptionEn": "Electronic Products",
                "descriptionChi": "電子產品"
            },
            {
                "id": "C204",
                "descriptionEn": "Daily Necessities",
                "descriptionChi": "日用品"
            }
        ],
        "dimension": [
            {
                "id": "D01",
                "descriptionEn": "Big: >60cm",
                "descriptionChi": "大: >60cm"
            },
            {
                "id": "D02",
                "descriptionEn": "Medium: 31-60cm",
                "descriptionChi": "中: 31-60cm"
            },
            {
                "id": "D03",
                "descriptionEn": "Small: <30cm",
                "descriptionChi": "小: <30cm"
            }
        ],
        "temperature": [
            {
                "id": "T01",
                "descriptionEn": "Room Temperature",
                "descriptionChi": "室溫"
            },
            {
                "id": "T02",
                "descriptionEn": "0-4°C",
                "descriptionChi": "0-4度"
            },
            {
                "id": "T03",
                "descriptionEn": "-18°C",
                "descriptionChi": "-18度"
            }
        ],
        "dimensionThirdParty": [
            {
                "id": "D04",
                "descriptionEn": "Circle K: LWH < 90cm, Weight < 5kg",
                "descriptionChi": "Circle K: 長闊高總和<90cm，重<5kg"
            }
        ],
        "weight": [
            {
                "id": "W01",
                "descriptionEn": "Heavy: >10kg",
                "descriptionChi": "重: >10kg"
            },
            {
                "id": "W02",
                "descriptionEn": "Medium: 5-10kg",
                "descriptionChi": "中: 5-10kg"
            },
            {
                "id": "W03",
                "descriptionEn": "Light: <5kg",
                "descriptionChi": "輕: <5kg"
            }
        ]
    }
}

Usage

Option Type Usage
categoryStandard id used in categoryOptionId where sameDayDelivery is false
categorySameDay id used in categoryOptionId where sameDayDelivery is true
dimension id used in dimensionOptionId;
required;
dimensionThirdParty id used in dimensionOptionId;
Only valid option when sameDayDelivery is false and pick up store is from third party(Circle K);
temperature id used in temperatureOptionId;
required when sameDayDelivery is true;
weight id used in weightOptionId;
required when sameDayDelivery is true;

Label

GET /v3/label/shipment/{trackingNumber}

To retrieve list of labels for all items by PARENT shipment tracking number

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Request Parameters

Name Type Required Description Example
trackingNumber string Required Tracking Number of the shipment you wish to retrieve label JP319037069928

Example Response




{
  "labelUrl": "https://jumppoint-development.s3.ap-northeast-1.amazonaws.com/expressOrderLabels/preGenDetailed/JP319037069934.pdf?AWSAccessKeyId=AKIARLW6QBGRI3STRUXC&Expires=1632380064&Signature=hk71K9wFi7UQUPt3AvemsrOWvPM%3D"
}

Example Error Messages

Invalid trackingNumber (Status Code: 404)



{
  "message": "Shipment cannot be found"
}

GET /v3/label/item/{trackingNumber}

To retrieve label for specific item by corresponding item tracking number

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Request Parameters

Name Type Required Description Example
trackingNumber string Required Tracking Number of the shipment you wish to retrieve label JP319037069928

Example Response




{
  "labelUrl": "https://jumppoint-development.s3.ap-northeast-1.amazonaws.com/expressOrderLabels/preGenDetailed/JP319037069934.pdf?AWSAccessKeyId=AKIARLW6QBGRI3STRUXC&Expires=1632380064&Signature=hk71K9wFi7UQUPt3AvemsrOWvPM%3D"
}

Example Error Messages

Invalid trackingNumber (Status Code: 404)



{
  "message": "Shipment cannot be found"
}

Pick Up Stores

GET /v3/pick-up-store/list

To retrieve lists of Pick Up Stores for pick-up or drop-off

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Request Parameters

Parameter Type Description Example
isDropOff boolean If true,return Pick Up Stores available for drop off See pickUpStore
isPickUp boolean If true,return Pick Up Stores available for pick up See pickUpStore

Response Parameters

Parameter Type Description Example
pickUpStores obeject[] Returned Pick Up Stores See below

pickUpStore

Parameter Type Description Example
code string Unique code of Pick Up Store 'KLE48'
alias string Alias of Pick Up Store '新蒲崗自提點'
districtEn string District of Pick Up Store in English 'Wong Tai Sin'
districtChi string District of Pick Up Store in Chinese '黃大仙'
address string Address of Pick Up Store '新蒲崗大有街31號善美工業大廈'
pickUpStoreCompany object information of Pick Up Store Company(if it belongs to any) [see pickUpStoreCompany]
operationTime object Operation Time of Pick Up Store [see operationTime]
freeStorage number Free period after the shipments arriving at the pick up store (in days)
(Storage fee will be charged after this period of time)		 3
isCashReceipt boolean Cash Receipt service availability at pick up store true
isDropOff boolean Drop Off service availability at pick up store false
isPickUp boolean Pick Up service availability at pick up store false

pickUpStoreCompany

Parameter Type Description Example
nameChi string Chinese Name of the company 'OK便利店'
nameEn string English Name of the company 'Circle K'
alias string Alias of the company 'OK'

operationTime

Parameter Type Description Example
mondayFrom string Opening time on Monday in 'HH:mm' (if any) '09:00'
mondayTo string Closing time on Monday in 'HH:mm' (if any) '18:00'
tuesdayFrom string Opening time on Tuesday in 'HH:mm' (if any) '09:00'
tuesdayTo string Closing time on Tuesday in 'HH:mm' (if any) '18:00'
wednesdayFrom string Opening time on Wednesday in 'HH:mm' (if any) '09:00'
wednesdayTo string Closing time on Wednesday in 'HH:mm' (if any) '09:00'
thursdayFrom string Opening time on Thursday in 'HH:mm' (if any) '18:00'
thursdayTo string Closing time on Thursday in 'HH:mm' (if any) '09:00'
fridayFrom string Opening time on Friday in 'HH:mm' (if any) '18:00'
fridayTo string Closing time on Friday in 'HH:mm' (if any) '09:00'
saturdayFrom string Opening time on Saturday in 'HH:mm' (if any) '18:00'
saturdayTo string Closing time on Saturday in 'HH:mm' (if any) '09:00'
sundayFrom string Opening time on Sunday in 'HH:mm' (if any) '18:00'
sundayTo string Closing time on Sunday in 'HH:mm' (if any) '09:00'
publicHolidayFrom string Opening time on Public Holidays in 'HH:mm' (if any) '18:00'
publicHolidayTo string Closing time of Public Holidays in 'HH:mm' (if any) '18:00'

Notes

Example Response
















































































{
  "pickUpStores": [
    {
            "id": "21fb72a1-b59b-433c-9045-c4321d02d3b2",
            "code": "HKI10",
            "alias": "樹熊屋自取站",
            "contactPhone": "90827761",
            "externalRouteCode": null,
            "phoneAreaCode": "852",
            "area": {
                "en": "",
                "zh": "",
                "sc": "",
                "full": ""
            },
            "district": {
                "en": "",
                "zh": "",
                "sc": "",
                "full": ""
            },
            "region": {
                "en": "",
                "zh": "",
                "sc": "",
                "full": ""
            },
            "address": "西環德輔道西343號均益2期地下10號舖（近商場干諾道西出入口）",
            "pickUpStoreCompany": null,
            "operationTime": {
                "monday": {
                    "from": "13:00",
                    "to": "19:00",
                    "isClosed": false
                },
                "tuesday": {
                    "from": "13:00",
                    "to": "19:00",
                    "isClosed": false
                },
                "wednesday": {
                    "from": "13:00",
                    "to": "19:00",
                    "isClosed": false
                },
                "thursday": {
                    "from": "13:00",
                    "to": "19:00",
                    "isClosed": false
                },
                "friday": {
                    "from": "13:00",
                    "to": "19:00",
                    "isClosed": false
                },
                "saturday": {
                    "from": "13:00",
                    "to": "19:00",
                    "isClosed": false
                },
                "sunday": {
                    "from": null,
                    "to": null,
                    "isClosed": true
                },
                "publicHoliday": {
                    "from": null,
                    "to": null,
                    "isClosed": true
                }
            },
            "freeStorage": 2,
            "isDropOff": false,
            "isReturnDropOff": false,
            "isPickUp": true,
            "isCashReceipt": true
        }
  ]
}

Tables

Common Constants

shipmentState-v3
Status Description
Created 已建立
Confirmed 已確認
Passed to courier 速遞員已拎件
Not able to receive products 無法拎件
On the way to warehouse 前往貨倉中
Arrived at warehouse 到達貨倉
Sending to another warehouse 轉貨倉
On the way to customer 送貨中
Undelivered 無法送達
Completed 完成 - 已送達
Rejected 拒絕訂單
Scheduled for redeliver 將再次派送
Problem shipment 出現問題
On the way to pick up store 前往自提點中
Arrived at pick up store 到達自提點

itemState-v3

Status Description
Created 已建立
Confirmed 已確認
Passed to courier 速遞員已拎件
Not able to receive products 無法拎件
On the way to warehouse 前往貨倉中
Arrived at warehouse 到達貨倉
Sending to another warehouse 轉貨倉
On the way to customer 送貨中
Undelivered 無法送達
Completed 完成 - 已送達
Rejected 拒絕訂單
Scheduled for redeliver 將再次派送
Problem shipment 出現問題
On the way to pick up store 前往自提點中
Arrived at pick up store 到達自提點

shipment-category

Value Description
parcel Parcel
freight Freight

freight-type

Value Description
b2b B2B
shuttling Shuttling

address-type

address-type-b2b
Value Description
hotel_receiving_department Hotel receiving department
supermarket_receiving_department Supermarket receiving department
centralised_warehouse Centralised warehouse
store Store
public_warehouse Public warehouse
private_warehouse Private warehouse
airport Airport
pier Pier
others Other
address-type-shuttling
Value Description
hk Hong Kong Island
kl Kowloon
nt New Territories

item-dimension

Value Description
D01 Big: >60cm
D02 Medium: 31-60cm
D03 Small: <30cm
D04 Circle K: LWH < 90cm, Weight < 5kg

item-weight

Value Description
W01 Heavy: >10kg
W02 Medium: 5-10kg
W03 Light: <5kg

item-temperature

Value Description
T01 Room Temperature
T02 0-4°C
T03 -18°C
T04 17-20°C

item-cateogry

item-cateogry-parcel-standard
Value Description
C101 Documents
C102 Electronic Products
C103 Daily Necessities
C104 Clothes
C105 Food
C106 Alcohol
item-cateogry-non-parcel-standard
Value Description
C201 Wine
C202 Food
C203 Electronic Products
C204 Daily Necessities

payment-method

Value Description Shipment Fee Cash on Delivery
PAID_BY_MERCHANT 寄件人支付運費 Deducted from your account balance -
PAID_BY_MERCHANT_COD 寄件人付運費，貨款到付 Deducted from your account balance Received on delivery
PAID_BY_RECEIVER 收件人到付運費 Received on delivery -
CASH_ON_DELIVERY 貨物及運費到付 Received on delivery Received on delivery

Webhook

jumppoint can send webhook event to notify your application when there are shipment status updates.

The payload for each webhook event will include information about the related API response. Your provided endpoint should be set up to receive a HTTP POST request, and must always return a 200 HTTP response.

Configuring your Webhooks Settings

You can register your webhook endpoint (URL) by inputting webhookUrl in your POST /v3/shipment requests.

We recommend returning a 200 HTTP response immediately or we will consider the webhook POST action to have failed.

Webhook Events

Shipment's tracking status changed

When your shipment's tracking status changed, you'll get the event payload as below:






{
  "time": "2021-09-27 10:34",
  "trackingNumber": "JP319037069928",
  "status": "Completed"
}
Explanation
Parameter Type Description Example
time string format: 'YYYY-MM-DD HH:mm' '2021-09-27 10:34'
trackingNumber string Tracking Number of the shipment JP319037069928
status string Updated status of the shipment See Shipment State

Item's tracking status changed

When your item's tracking status changed, you'll get the event payload as below:







{
  "time": "2021-09-27 10:34",
  "shipmentTrackingNumber": "JP319037069928",
  "itemTrackingNumber": "JP319037069931",
  "itemState": "On the way to customer"
}

Another Example:








{
  "time": "2021-09-27 10:34",
  "shipmentTrackingNumber": "JP319037069928",
  "itemTrackingNumber": "JP319037069931",
  "itemState": "Undelivered",
  "remarks": "Nobody answered the door 無人應門"
}
Explanation
Parameter Type Description Example
time string format: 'YYYY-MM-DD HH:mm' '2021-09-27 10:34'
shipmentTrackingNumber string Tracking Number of the shipment JP319037069928
itemTrackingNumber string Tracking Number of the item JP319037069931
itemState string Updated status of the shipment See Item State
remarks string (if any) 'Nobody answered the door 無人應門'