---
title: 'jumppoint Open API Documentation'
tags: open-api
---
jumppoint Open API Documentation
===
| Last Updated | Updates |
| -------- | -------- |
| 2023-04-17 | * Enabled Drop Off at pick up store service as origin address to <br/> `POST /v2/shipment`, <br/>`POST /v2/shipment/bulk-create`, <br/>`GET /v2/pick-up-store/list`|
| 2022-09-23 | * Enabled one-shipment-multiple-items feature to <br/>`POST /v2/shipment` request <br/> * `GET /v2/shipment/shipment/{trackingNumber}`,<br/>`GET /v2/label/shipment/{trackingNumber}` for Parent Tracking Number <br/> * `GET /v2/shipment/item/{trackingNumber}`,<br/>`GET /v2/label/item/{trackingNumber}` for Child Item Tracking Number <br/> |
# Table of Contents
[TOC]
---
# 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
* We use Bearer Authentication to authenticate requests. You will need to include `Authorization: Bearer <API Access Token>` in the header for all requests.
* Before you get started, you will need to get your API Access Tokens from our Business Development Team for our Production and Sandbox environments.
* Your token should not be publicly accessible.
*
## Error Message
```json=
{
"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
```json=
{
"statusCode": 429,
"message": "ThrottlerException: Too Many Requests"
}
```
# Tables
## Common Constant and Object
#### paymentMethod
| 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 |
#### origin
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| contactName | string | Name of receiptient | 'Peter Chan' |
| contactPhone | string | Phone number of receiptient | '98745632' |
| address | string | Receiptient Address; <br/> Only applicable when shipment is not delivering to Pick Up Stores; | '新蒲崗大有街31號善美工業大廈'
| floor | string | Floor number of receiptient address (if any); <br/> Only applicable when shipment is not delivering to Pick Up Stores; | '10' |
| room | string | Floor number of receiptient address (if any); <br/> Only applicable when shipment is not delivering to Pick Up Stores; | '01' |
#### destination
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| contactName | string | Name of receiptient | 'Peter Chan' |
| contactPhone | string | Phone number of receiptient | '98745632' |
| address | string | Receiptient Address; <br/> Only applicable when shipment is not delivering to Pick Up Stores; | '新蒲崗大有街31號善美工業大廈'
| floor | string | Floor number of receiptient address (if any); <br/> Only applicable when shipment is not delivering to Pick Up Stores; | '10' |
| room | string | Floor number of receiptient address (if any); <br/> Only applicable when shipment is not delivering to Pick Up Stores; | '01' |
#### 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](#[pickUpStoreCompany])]*
| operationTime | object | Operation Time of Pick Up Store | *[see [operationTime](#operationTime)]* |
| freeStorage | number | Free period after the shipments arriving at the pick up store (in days) <br/> (Storage fee will be charged after this period of time) | 3 |
| providingServices | object | Service Options for Pick Up Stores | *[see [providingServices](#providingServices)]*
#### 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' |
#### providingServices
| Parameter | Type | Description | Example |
| --------- | ---- | ----------- | ------- |
|cashReceipt | boolean |Cash Receipt service availability at pick up store | true |
|dropOff | boolean | Drop Off service availability at pick up store | false |
#### item options
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| id | string | ID used in `POST /shipment` | 'D01' |
| descriptionChi | string | Option Description in Chinese | 'Wine' |
| descriptionEn | string | Option Description in English | '酒' |
# API v1
## Shipment
### `POST /v1/shipment`
:::info
To create a Shipment
:::
#### Resource URL
* Sandbox: `POST https://staging.open-api.jumppoint.io/v1/shipment`
* Production: `POST https://open-api.jumppoint.io/v1/shipment`
#### Resource Information
| Request Content-Type | Response formats | Requires authentication |
| -------- | -------- | -------- |
| `application/json` | `application/json; charset=utf-8` | Yes |
#### Body Parameters
| Name | Type | Required | Description | Example |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| sameDayDelivery | boolean | Yes | `true` for "Same-Day Delivery Service"; <br/> `false` for "Standard Delivery Service" | true |
| origin | object | Yes | Sender information | See [below](#origin-POSTv1) |
| destination | object | Yes | Receipient information | See [below](#destination-POSTv1) |
| pickUpStoreCode | String | Required if this shipment is delivering to our pick up store <br/> (Delivery to pick up stores only applicable to "Standard Delivery Service") | Get from [`GET /pick-up-store/list`](#GET-v1pick-up-storelist) | "KLE47" |
| item | object | Yes | Parcel details | See [below](#item-POSTv1)
| pickUpOnHold | boolean |Only applicable to "Standard Delivery";|Shipment will be on hold.<br/> No pick up date will be assigned and will not being pick up by courier until being notified by calling [`POST /shipment/pick-up-on-hold-release`](#POST-v2pick-up-on-hold-release)|true
| pickUpDate | string | Required for "Same-Day Delivery Service";<br/>Optional for "Standard Delivery;<br/>Not applicable when `pickUpOnHold` is set to true" <br/> Hong Kong Time; | Format: YYYY-MM-DD; <br/> Get from [`GET /date/valid`](#GET-v1datevalid) | "2021-12-31" |
| deliveryDate | string | Required for "Same-Day Delivery Service"; <br/> Hong Kong Time; | Format: YYYY-MM-DD; <br/> Get from [`GET /date/valid`](#GET-v1datevalid) | "2021-12-31" |
| cod | integer | Required if paymentMethod is 'PAID_BY_MERCHANT_COD' or 'CASH_ON_DELIVERY' | Amount you wish to receive from receiptient excluding the shipment fee | 200 |
| orderNotes | string | No | Maximum: 250 characters | "call customer 30 mins before delivery" |
| externalOrderNumber | string | No | Maximum: 50 characters | '000235462' |
| webhookUrl | string | No | See [*Webhook*](#Webhook); <br /> Maximum: 250 characters | 'https://c977-61-244-155-9.ngrok.io/webhook/jumppoint' |
| paymentMethod | string | Yes | See [above](#paymentMethod) | "PAID_BY_RECEIVER" |
##### origin-POSTv1
| 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' |
##### destination-POSTv1
| Name | Type | Required | Description | Example |
| -------- | -------- | -------- | -------- | -------- |
| contactName | string | Yes | Maximum: 30 characters | 'Peter Chan' |
| contactPhone | string | Yes | 8 digits; <br/> Mobile numbers should be used in order to receive SMS | '98745632' |
| address | string | Required if no `pickUpStoreCode` provided | Maximum: 250 characters | '新蒲崗大有街31號善美工業大廈'
| floor | string | No; Applicable only if no `pickUpStoreCode` provided; | Maximum: 10 characters | '10' |
| room | string | No; Applicable only if no `pickUpStoreCode` provided; | Maximum: 10 characters | '01' |
##### item-POSTv1
| Name | Type | Required | Description | Example |
| -------- | -------- | -------- | -------- | -------- |
| dimensionOptionId | string | Yes | Get from [`GET /item/options`](#GET-v1itemoptions) | 'D01' |
| weightOptionId | string | Required for "Same-Day Delivery Service" | Get from [`GET /item/options`](#GET-v1itemoptions) | 'W01' |
| actualWeight | number | Required for "Standard Delivery Service"; <br/> in kg; | DECIMAL(8,2) | 2.1
| temperatureOptionId | string | Required for "Same-Day Delivery Service" | Get from [`GET /item/options`](#GET-v1itemoptions) | 'T01' |
| categoryOptionId | string | Required if no `category` provided | Get from [`GET /item/options`](#GET-v1itemoptions) | 'C203' |
| category | string | Required if no `categoryOptionId` provided | Maximum: 10 characters | 'Toys' |
#### Example Request Body (Same-Day Delivery Service)
```json=
{
"sameDayDelivery": true,
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"item": {
"dimensionOptionId": "D01",
"weightOptionId": "W01",
"temperatureOptionId": "T01",
"categoryOptionId": "C201"
},
"paymentMethod": "PAID_BY_MERCHANT",
"pickUpDate": "2021-10-05",
"deliveryDate": "2021-10-05",
"orderNotes": "call customer 30 mins before delivery",
"externalOrderNumber": "000235462",
"webhookUrl": "https://c977-61-244-155-9.ngrok.io/webhook/jumppoint"
}
```
#### Example Request Body (Standard Delivery Service + Deliver to Pick Up Store)
```json=
{
"sameDayDelivery": false,
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632"
},
"pickUpStoreCode": "KLE48",
"item": {
"dimensionOptionId": "D01",
"actualWeight": 1.3,
"categoryOptionId": "C101"
},
"paymentMethod": "PAID_BY_MERCHANT",
"orderNotes": "fragile"
}
```
#### Example Response
> Status Code: 201 Created
```json=
{
"shipment": {
"trackingNumber": "JP319037069931",
"sameDayDelivery": true,
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632"
},
"pickUpStore": {
"code": "KLE48",
"alias": "新蒲崗自提點",
"address": "大有街31號 善美工業大廈10樓1001室"
},
"item": {
"dimension": "Big: >60cm 大: >60cm",
"temperature": "Room Temperature 室溫",
"weight": "Medium: 5-10kg 中: 5-10kg",
"category": "Wine 酒"
},
"paymentMethod": "PAID_BY_MERCHANT",
"pickUpDate": "2021-10-15",
"deliveryDate": "2021-10-15",
"orderNotes": "call customer 30 mins before delivery",
"externalOrderNumber": "000235462",
"totalCharge": 68
},
"accountBalance": 4249
}
```
#### Example Error Messages
##### Invalid Form Input
```json=
{
"statusCode": 400,
"message": [
"item.categoryOptionId should not be empty",
"item.category should not be empty"
],
"error": "Bad Request"
}
```
##### Invalid `pickUpStoreCode` (Status Code: 404)
```json=
{
"message": "Pick Up Store cannot be found"
}
```
---
### `GET /v1/shipment/{trackingNumber}`
:::info
To retrieve the details of a specific shipment
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v1/shipment/{trackingNumber}`
* Production: `GET https://open-api.jumppoint.io/v1/shipment/{trackingNumber}`
#### 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 | JP319037069928 |
#### Response Parameters
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| trackingNumber | string | Tracking Number of the shipment | 'JP319037069928' |
| refNo | string | Tracking Number of the shipment | 'AIGNITER_EO_002934' |
| externalOrderNumber | string | ExteTracking Number of the shipment | '000234' |
| orderNotes | string | remarks of the shipment | 'Remarks...' |
| orderDate | string | Creation Time of the shipment; at Hong Kong Time; | "2021-06-25 16:57" |
| shipmentState | string | Current status of the shipment; See [shipmentState](#shipmentState-GETv1) | 'On the way to customer' |
| sameDayDelivery | boolean | `true` for “Same-Day Delivery Service”; <br/> `false` for “Standard Delivery Service”; | true |
| pickUpDate | string | Pick Up Date of the shipment; <br/> only for “Same-Day Delivery Service”; | '2021-06-26' |
| deliveryDate | string | Delivery Date of the shipment; <br/> only for “Same-Day Delivery Service”; | '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](#paymentMethod) | 'PAID_BY_MERCHANT' |
| cod | number | Cash On Delivery Amount | 100 |
| origin | object | [Sender Address Details](#origin) | *[see above]* |
externalOrderNumber| destination | object | [Receiptient Address Details](#destination) | *[see above]* |
| pickUpStore | object | [Pick Up Store Details](#pickUpStore) | *[see above]* |
| item | object | [Parcels Details](#item) | *[see below]* |
| statusLogs | array | [Trackings of shipment sorted by time descendingly](#statusLogs) | *[see below for objects in the array]* |
##### shipmentState-GETv1
| 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 | 到達自提點 |
##### item
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| dimensionOption | object | [Dimension Details](#item-options) | *[see above]* |
| weightOption | object | [Weight Details](#item-options); <br/> Only applicable for 'Same-Day Delivery Service'; | *[see above]* |
| actualWeight | number | Actual Weight of parcel (in kg); <br/> Only applicable for 'Standard Delivery Service'; | 2 |
| adjustedWeight | number | Adjusted Weight of parcel (in kg) (if any) | 2.3 |
| temperatureOption | object | [Temperature Details](#item-options); <br/> Only applicable for 'Same-Day Delivery Service' | *[see above]* |
| categoryOption | object | [Category Details](#item-options); <br/> Only applicable if no `'category'` inputted | *[see above]* |
| category | number | Category inputted; <br/> Only applicable if no `'categoryOption'` provided | 'Toys' |
##### statusLogs
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| time | string | format: 'YYYY-MM-DD HH:mm' | '2021-09-27 10:34' |
| status | string | [Shipment State](#shipmentState) | 'Created' |
| remarks | string | (if any) | 'Nobody answered the door 無人應門' |
#### Example Response
```json=
{
"shipment": {
"trackingNumber": "JP319037070058",
"refNo": "JUMPPOINT_EO_003012",
"orderDate": "2021-09-07 18:42",
"shipmentState": "On the way to customer",
"sameDayDelivery": false,
"shipmentFee": 28,
"additionalWeightFee": 0,
"totalFee": 28,
"totalCharge": 28,
"paymentMethod": "PAID_BY_MERCHANT",
"cod": 0,
"orderNotes": "fragile",
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈"
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632"
},
"pickUpStore": {
"code": "KLE48",
"alias": "新蒲崗自提點",
"districtEn": "Wong Tai Sin",
"districtChi": "黃大仙",
"address": "大有街31號 善美工業大廈10樓1001室",
"operationTime": {
"mondayFrom": "09:00",
"mondayTo": "18:00",
"tuesdayFrom": "09:00",
"tuesdayTo": "18:00",
"wednesdayFrom": "09:00",
"wednesdayTo": "18:00",
"thursdayFrom": "09:00",
"thursdayTo": "18:00",
"fridayFrom": "09:00",
"fridayTo": "18:00",
"saturdayFrom": "09:00",
"saturdayTo": "18:00",
"sundayFrom": "09:00",
"sundayTo": "18:00",
"publicHolidayFrom": "09:00",
"publicHolidayTo": "18:00"
},
"freeStorage": 2
},
"item": {
"dimensionOption": {
"id": "D01",
"descriptionChi": "大: >60cm",
"descriptionEn": "Big: >60cm"
},
"actualWeight": 1.3,
"categoryOption": {
"id": "C101",
"descriptionChi": "文件",
"descriptionEn": "Documents"
}
},
"statusLogs": [
{
"time": "2021-09-08 18:39",
"status": "On the way to customer"
},
{
"time": "2021-09-08 18:39",
"status": "Passed to courier"
},
{
"time": "2021-09-08 18:39",
"status": "Arrived at warehouse"
}
]
}
}
```
#### Example Error Messages
##### Invalid `trackingNumber` (Status Code: 404)
```json=
{
"message": "Shipment cannot be found"
}
```
---
## Dates
### `GET /v1/date/valid`
:::info
To retrieve lists of valid Pick-Up and Delivery Dates
:::
#### Notes
:::danger
* Pick-Up and Delivery Dates only apply to shipments with **Same-Day Delivery Service**
* Dates are in local Hong Kong Time
* Delivery services and Pick-Up services are only available on working days, i.e. Monday to Saturday with public holidays excluded
* Cut-off time of delivery would be 20:00 on the day before pick-up date, i.e. cut-off time of delivery on Saturday would be 20:00 on Friday
* Delivery Date should not be earlier than Pick-Up Date
* Delivery Date should not be 3 days later than Pick-Up Date (with Sunday and public holidays excluded)
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v1/date/valid`
* Production: `GET https://open-api.jumppoint.io/v1/date/valid`
#### Resource Information
| Response formats | Requires authentication |
| --------------------------------- | ----------------------- |
| `application/json; charset=utf-8` | Yes |
#### Example Response
```json=
{
"pickUpDates": [
"2021-09-28",
"2021-09-29",
"2021-09-30",
"2021-10-04",
"2021-10-05",
"2021-10-06",
"2021-10-07"
],
"deliveryDates": [
"2021-09-28",
"2021-09-29",
"2021-09-30",
"2021-10-02",
"2021-10-04",
"2021-10-05",
"2021-10-06",
"2021-10-07",
"2021-10-08",
"2021-10-09",
"2021-10-11",
]
}
```
---
## Item
### `GET /v1/item/options`
:::info
To retrieve lists of valid item options
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v1/item/options`
* Production: `GET https://open-api.jumppoint.io/v1/item/options`
#### Resource Information
| Response formats | Requires authentication |
| --------------------------------- | ----------------------- |
| `application/json; charset=utf-8` | Yes |
#### Example Response
```json=
{
"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`; <br/> required; |
|dimensionThirdParty | `id` used in `dimensionOptionId`;<br/> Only valid option when `sameDayDelivery` is `false` and pick up store is from third party(Circle K);<br/>
| temperature | `id` used in `temperatureOptionId`; <br/> required when `sameDayDelivery` is `true`; |
| weight | `id` used in `weightOptionId`; <br/> required when `sameDayDelivery` is `true`; |
---
## Pick Up Stores
### `GET /v1/pick-up-store/list`
:::info
To retrieve lists of Pick Up Stores
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v1/pick-up-store/list`
* Production: `GET https://open-api.jumppoint.io/v1/pick-up-store/list`
#### Resource Information
| Response formats | Requires authentication |
| --------------------------------- | ----------------------- |
| `application/json; charset=utf-8` | Yes |
#### Response Parameters
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| pickUpStores | obeject[] | Returned Pick Up Stores | See [pickUpStore](#pickUpStore) |
#### Notes
:::warning
* `code` used as `pickUpStoreCode` in [`POST /v1/shipment`](#Create-a-Shipment-POST-v1shipment)
* `operationTime` are in local Hong Kong Time
:::
#### Example Response
```json=
{
"pickUpStores": [
{
"code": "KLE48",
"alias": "新蒲崗自提點",
"districtEn": "Wong Tai Sin",
"districtChi": "黃大仙",
"address": "大有街31號 善美工業大廈10樓1001室",
"operationTime": {
"mondayFrom": "09:00",
"mondayTo": "18:00",
"tuesdayFrom": "09:00",
"tuesdayTo": "18:00",
"wednesdayFrom": "09:00",
"wednesdayTo": "18:00",
"thursdayFrom": "09:00",
"thursdayTo": "18:00",
"fridayFrom": "09:00",
"fridayTo": "18:00",
"saturdayFrom": "09:00",
"saturdayTo": "18:00",
"sundayFrom": "09:00",
"sundayTo": "18:00",
"publicHolidayFrom": "09:00",
"publicHolidayTo": "18:00"
},
"freeStorage": 2
}
]
}
```
---
## Label
### `GET /v1/label/{trackingNumber}`
:::info
To retrieve label of specific shipment
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v1/label/{trackingNumber}`
* Production: `GET https://open-api.jumppoint.io/v1/label/{trackingNumber}`
#### 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
:::warning
* The download link will be expired in 10 minutes.
* You should save the PDF file to your device on getting the link.
* You will need to recall the API to get a new link after 10 minutes.
:::
```json=
{
"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**)
```json=
{
"message": "Shipment cannot be found"
}
```
---
# API v2
## Changes from v1 to v2
#### shipmentState-v2
| Status | Description |
| ---------------------------- | ------------- |
| Created | 已建立 |
| Processing | 處理中 |
| Problem Shipment | 出現問題 |
| Completed | 完成 - 已送達 |
| Cancelled | 已取消 |
#### itemState-v2
| 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 | 到達自提點 |
#### statusLogs-v2
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| time | string | format: 'YYYY-MM-DD HH:mm' | '2021-09-27 10:34' |
| status | string | [Shipment/Item State](#shipmentState-v2) | 'Created' |
| remarks | string | (if any) | 'Nobody answered the door 無人應門' |
## Shipment
### `POST /v2/shipment`
:::info
To create a Shipment (with a list of items)
:::
#### Resource URL
* Sandbox: `POST https://staging.open-api.jumppoint.io/v2/shipment`
* Production: `POST https://open-api.jumppoint.io/v2/shipment`
#### Resource Information
| Request Content-Type | Response formats | Requires authentication |
| -------- | -------- | -------- |
| `application/json` | `application/json; charset=utf-8` | Yes |
#### Body Parameters
| Name | Type | Required | Description | Example |
| -------- | -------- | -------- | -------- | -------- |
| sameDayDelivery | boolean | Yes | `true` for "Same-Day Delivery Service"; <br/> `false` for "Standard Delivery Service" | true |
| origin | object | Yes | Sender information | See [below](#origin-POSTv2) |
| dropOffPickUpStoreCode | String | Required if this shipment is to be dropped off at our pick up store <br/> (Drop off at pick up stores only applicable to "Standard Delivery Service") | Get from [`GET /pick-up-store/list`](#GET-v2pick-up-storelist) | "KLE47" |
| destination | object | Yes | Receipient information | See [below](#destination-POSTv2) |
| pickUpStoreCode | String | Required if this shipment is delivering to our pick up store <br/> (Delivery to pick up stores only applicable to "Standard Delivery Service") | Get from [`GET /pick-up-store/list`](#GET-v2pick-up-storelist) | "KLE47" |
| items | array | Yes | Parcel details | See [below](#item-POSTv2) |
| pickUpDate | string | Required for "Same-Day Delivery Service"; <br/> Hong Kong Time; | Format: YYYY-MM-DD; <br/> Get from [`GET /date/valid`](#GET-v2datevalid) | "2021-12-31" |
| deliveryDate | string | Required for "Same-Day Delivery Service"; <br/> Hong Kong Time; | Format: YYYY-MM-DD; <br/> Get from [`GET /date/valid`](#GET-v2datevalid) | "2021-12-31" |
| paymentMethod | string | Yes | See [below](#paymentMethod) | "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 |
| webhookUrl | string | No | See [*Webhook*](#Webhook); <br /> Maximum: 250 characters | 'https://c977-61-244-155-9.ngrok.io/webhook/jumppoint' |
##### origin-POSTv2
| 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' |
##### destination-POSTv2
| Name | Type | Required | Description | Example |
| -------- | -------- | -------- | -------- | -------- |
| contactName | string | Yes | Maximum: 30 characters | 'Peter Chan' |
| contactPhone | string | Yes | 8 digits; <br/> Mobile numbers should be used in order to receive SMS | '98745632' |
| address | string | Required if no `pickUpStoreCode` provided | Maximum: 250 characters | '新蒲崗大有街31號善美工業大廈'
| floor | string | No; Applicable only if no `pickUpStoreCode` provided; | Maximum: 10 characters | '10' |
| room | string | No; Applicable only if no `pickUpStoreCode` provided; | Maximum: 10 characters | '01' |
##### item-POSTv2
| Name | Type | Required | Description | Example |
| -------- | -------- | -------- | -------- | -------- |
| externalOrderNumber | string | No | Maximum: 50 characters | '000235462' |
| dimensionOptionId | string | Yes | Get from [`GET /item/options`](#GET-v2itemoptions) | 'D01' |
| weightOptionId | string | Required for "Same-Day Delivery Service" | Get from [`GET /item/options`](#GET-v2itemoptions) | 'W01' |
| actualWeight | number | Required for "Standard Delivery Service"; <br/> in kg; | DECIMAL(8,2) | 2.1
| temperatureOptionId | string | Required for "Same-Day Delivery Service" | Get from [`GET /item/options`](#GET-v2itemoptions) | 'T01' |
| categoryOptionId | string | Required if no `category` provided | Get from [`GET /item/options`](#GET-v2itemoptions) | 'C203' |
| category | string | Required if no `categoryOptionId` provided | Maximum: 10 characters | 'Toys' |
| itemNotes | string | No | Maximum: 250 characters | "call customer 30 mins before delivery" |
#### Example Request Body (Same-Day Delivery Service)
```json=
{
"sameDayDelivery": true,
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"items": [
{
"externalOrderNumber": "Ext12345",
"dimensionOptionId": "D02",
"weightOptionId": "W01",
"temperatureOptionId": "T01",
"categoryOptionId": "C201",
"itemNotes": "fragile"
},
{
"externalOrderNumber": "Ext12346",
"dimensionOptionId": "D01",
"weightOptionId": "W01",
"temperatureOptionId": "T01",
"categoryOptionId": "C204",
"itemNotes": "call customer 30 mins before delivery"
}
],
"paymentMethod": "PAID_BY_MERCHANT",
"pickUpDate": "2021-10-05",
"deliveryDate": "2021-10-05",
"webhookUrl": "https://c977-61-244-155-9.ngrok.io/webhook/jumppoint"
}
```
#### Example Request Body (Standard Delivery Service + Drop Off at Pick Up Store)
```json=
{
"sameDayDelivery": false,
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
},
"dropOffPickUpStoreCode": "KLE48",
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"items": [
{
"dimensionOptionId": "D01",
"actualWeight": 1.3,
"categoryOptionId": "C101",
"itemNotes": "fragile"
},
],
"paymentMethod": "PAID_BY_MERCHANT"
}
```
#### Example Request Body (Standard Delivery Service + Deliver to Pick Up Store)
```json=
{
"sameDayDelivery": false,
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632"
},
"pickUpStoreCode": "KLE48",
"items": [
{
"dimensionOptionId": "D01",
"actualWeight": 1.3,
"categoryOptionId": "C101",
"itemNotes": "fragile"
},
],
"paymentMethod": "PAID_BY_MERCHANT"
}
```
#### Example Response
> Status Code: 201 Created
```json=
{
"shipment": {
"parentTrackingNumber": "JP319037069931",
"sameDayDelivery": true,
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632"
},
"pickUpStore": {
"code": "KLE48",
"alias": "新蒲崗自提點",
"address": "大有街31號 善美工業大廈10樓1001室"
},
"items": [
{
"itemTrackingNumber": "JP319037069931",
"itemExternalNumber": "Ext12345",
"dimension": "Small: <30cm 小: <30cm",
"temperature": "Room Temperature 室溫",
"weight": "Medium: 5-10kg 中: 5-10kg",
"category": "Wine 酒",
"itemNotes": "fragile"
},
{
"itemTrackingNumber": "JP319037069934",
"itemExternalNumber": "Ext12346",
"dimension": "Big: >60cm 大: >60cm",
"temperature": "Room Temperature 室溫",
"weight": "Medium: 5-10kg 中: 5-10kg",
"category": "Daily Necessities 日用品",
"itemNotes": "call customer 30 mins before delivery"
},
],
"paymentMethod": "PAID_BY_MERCHANT",
"pickUpDate": "2021-10-15",
"deliveryDate": "2021-10-15",
"totalCharge": 68
},
"accountBalance": 4249
}
```
#### Example Error Messages
##### Invalid Form Input
```json=
{
"statusCode": 400,
"message": [
"item.categoryOptionId should not be empty",
"item.category should not be empty"
],
"error": "Bad Request"
}
```
##### Invalid `pickUpStoreCode` (Status Code: 404)
```json=
{
"message": "Pick Up Store cannot be found"
}
```
---
### `POST /v2/shipment/bulk-create`
:::info
To create multiple Shipments (with a list of items)
:::
#### Resource URL
* Sandbox: `POST https://staging.open-api.jumppoint.io/v2/shipment/bulk-create`
* Production: `POST https://open-api.jumppoint.io/v2/shipment/bulk-create`
#### Resource Information
| Request Content-Type | Response formats | Requires authentication |
| -------- | -------- | -------- |
| `application/json` | `application/json; charset=utf-8` | Yes |
#### Body Parameters
| Name | Type | Required | Description | Example |
| -------- | -------- | -------- | -------- | -------- |
| data | Array object | Yes | A list of `create shipment` object | See [above](#POST-v2shipment) create shipment |
#### Example Request Body
```json=
{
"data": [
{
"sameDayDelivery": true,
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"items": [
{
"externalOrderNumber": "Ext12345",
"dimensionOptionId": "D02",
"weightOptionId": "W01",
"temperatureOptionId": "T01",
"categoryOptionId": "C201",
"itemNotes": "fragile"
},
{
"externalOrderNumber": "Ext12346",
"dimensionOptionId": "D01",
"weightOptionId": "W01",
"temperatureOptionId": "T01",
"categoryOptionId": "C204",
"itemNotes": "call customer 30 mins before delivery"
}
],
"paymentMethod": "PAID_BY_MERCHANT",
"pickUpDate": "2021-10-05",
"deliveryDate": "2021-10-05",
"webhookUrl": "https://c977-61-244-155-9.ngrok.io/webhook/jumppoint"
},
{
"sameDayDelivery": true,
"origin": {
"contactName": "Anthony Yip",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"destination": {
"contactName": "Anthony Yip",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "10",
"room": "01"
},
"items": [
{
"externalOrderNumber": "Ext12345",
"dimensionOptionId": "D02",
"weightOptionId": "W01",
"temperatureOptionId": "T01",
"categoryOptionId": "C201",
"itemNotes": "fragile"
},
{
"externalOrderNumber": "Ext12346",
"dimensionOptionId": "D01",
"weightOptionId": "W01",
"temperatureOptionId": "T01",
"categoryOptionId": "C204",
"itemNotes": "call customer 30 mins before delivery"
}
],
"paymentMethod": "PAID_BY_MERCHANT",
"pickUpOnHold": false,
"pickUpDate": "2021-10-05",
"deliveryDate": "2021-10-05",
"webhookUrl": "https://c977-61-244-155-9.ngrok.io/webhook/jumppoint"
}
]
}
```
#### Example Response
> Status Code: 201 Created
```json=
{
"result": "success",
"data": {
"shipment": [
{
"id": "39c49639-1042-4d3d-9324-d1c61cabc9c2",
"trackingNumber": "JP319037076955",
"sameDayDelivery": false,
"pickUpOnHOld": false,
"items": [
{
"itemTrackingNumber": "JP319037076955",
"externalOrderNumber": "1",
"itemNotes": "1",
"dimension": {
"en": "Middle: 31-60cm",
"zh": "中: 31-60cm"
},
"actualWeight": 6,
"category": "1A"
}
],
"paymentMethod": "PAID_BY_MERCHANT",
"totalCharge": "28"
},
{
"id": "66102439-0646-4412-b1e4-4ad027b7c020",
"trackingNumber": "JP319037076965",
"sameDayDelivery": false,
"items": [
{
"itemTrackingNumber": "JP319037076965",
"externalOrderNumber": "2",
"itemNotes": "2",
"dimension": {
"en": "Middle: 31-60cm",
"zh": "中: 31-60cm"
},
"actualWeight": 2,
"category": "2A"
}
],
"paymentMethod": "PAID_BY_MERCHANT",
"totalCharge": "28"
}
]
},
"amountDeducted": true,
"accountBalance": 4249
}
```
#### Example Error Messages
##### Invalid Form Input
```json=
{
"statusCode": 400,
"message": [
"data.0.pickUpDate must be formatted as yyyy-mm-dd",
"data.0.pickUpDate must be a string",
"data.0.pickUpDate should not be empty",
"data.0.deliveryDate must be formatted as yyyy-mm-dd",
"data.0.deliveryDate must be a string",
"data.0.deliveryDate should not be empty",
"data.1.items.0.dimensionOptionId must be a valid enum value"
],
"error": "Bad Request"
}
```
---
### `GET /v2/shipment/shipment/{trackingNumber}`
:::info
To retrieve the details of a specific shipment
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v2/shipment/shipment/{trackingNumber}`
* Production: `GET https://open-api.jumppoint.io/v2/shipment/shipment/{trackingNumber}`
#### 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 | 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' |
| orderDate | string | Creation Time of the shipment; at Hong Kong Time; | "2021-06-25 16:57" |
| shipmentState | string | Current status of the shipment; See [shipmentState](#shipmentState-v2) | 'On the way to customer' |
| sameDayDelivery | boolean | `true` for “Same-Day Delivery Service”; <br/> `false` for “Standard Delivery Service”; | true |
| pickUpDate | string | Pick Up Date of the shipment; <br/> only for “Same-Day Delivery Service”; | '2021-06-26' |
| deliveryDate | string | Delivery Date of the shipment; <br/> only for “Same-Day Delivery Service”; | '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](#paymentMethod) | 'PAID_BY_MERCHANT' |
| cod | decimal(8,2) | Cash On Delivery Amount | 100 |
| isSelfPickUp | boolean | `true` for “Self Pick Up”; <br/> `false` for “To-Door Delivery”; | true |
| noOfItems | number | Total Charge | 2 |
| orderNotes | string | Order Notes (if any) | "call customer before delivery" |
| externalOrderNumber | string | External Order Number <br/> (if any) | "0951358" |
| origin | object | [Sender Address Details](#origin) | *[see above]* |
| destination | object | [Receiptient Address Details](#destination) | *[see above]* |
| pickUpStore | object | [Pick Up Store Details](#pickUpStore) | *[see above]* |
| item | Array | [Parcels Details](#item-v2) | *[see below]* |
| statusLogs | array | [Trackings of shipment sorted by time descendingly](#statusLogs) | *[see below for objects in the array]* |
##### item-v2
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| itemTrackingNumber | string | Tracking Number of the child item | "JP658854693314"|
| itemState | string | Current status of the item; See [itemState](#itemState-v2) | 'On the way to customer' |
| itemNotes | string | Order Notes (if any) | "call customer before delivery" |
| externalOrderNumber | string | External Order Number <br/> (if any) | "0951358" |
| dimensionOption | object | [Dimension Details](#item-options) | *[see above]* |
| weightOption | object | [Weight Details](#item-options); <br/> Only applicable for 'Same-Day Delivery Service'; | *[see above]* |
| actualWeight | number | Actual Weight of parcel (in kg); <br/> Only applicable for 'Standard Delivery Service'; | 2 |
| 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 |
| temperatureOption | object | [Temperature Details](#item-options); <br/> Only applicable for 'Same-Day Delivery Service' | *[see above]* |
| categoryOption | object | [Category Details](#item-options); <br/> Only applicable if no `'category'` inputted | *[see above]* |
| category | number | Category inputted; <br/> Only applicable if no `'categoryOption'` provided | 'Toys' |
| statusLogs | array | [Trackings of item sorted by time descendingly](#statusLogs-v2) | *[see below for objects in the array]* |
#### Example Response
```json=
{
"shipment": {
"trackingNumber": "JP319037070058",
"refNo": "JUMPPOINT_EO_003012",
"orderDate": "2021-09-07 18:42",
"shipmentState": "Completed",
"sameDayDelivery": false,
"shipmentFee": 28,
"additionalWeightFee": 0,
"totalFee": 28,
"totalCharge": 28,
"paymentMethod": "PAID_BY_MERCHANT",
"cod": 0,
"isSelfPickUp": true,
"noOfItems": 2,
"orderNotes": "fragile",
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "13",
"room": "B",
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632"
},
"pickUpStore": {
"code": "KLE48",
"alias": "新蒲崗自提點",
"districtEn": "Wong Tai Sin",
"districtChi": "黃大仙",
"address": "大有街31號 善美工業大廈10樓1001室",
"operationTime": {
"mondayFrom": "09:00",
"mondayTo": "18:00",
"tuesdayFrom": "09:00",
"tuesdayTo": "18:00",
"wednesdayFrom": "09:00",
"wednesdayTo": "18:00",
"thursdayFrom": "09:00",
"thursdayTo": "18:00",
"fridayFrom": "09:00",
"fridayTo": "18:00",
"saturdayFrom": "09:00",
"saturdayTo": "18:00",
"sundayFrom": "09:00",
"sundayTo": "18:00",
"publicHolidayFrom": "09:00",
"publicHolidayTo": "18:00"
},
"freeStorage": 2
},
"items": [
{
"itemTrackingNumber": "JP319037070058",
"itemState": "completed",
"itemNotes": null,
"dimensionOption": {
"id": "D02",
"descriptionChi": "中: 31-60cm",
"descriptionEn": "Medium: 31-60cm"
},
"weightOption": {
"id": "W03",
"descriptionChi": "輕: <5kg",
"descriptionEn": "Light: <5kg"
},
"adjustedWeight": 15,
"adjustedLength": 30,
"adjustedWidth": 30,
"adjustedHeight": 30,
"temperatureOption": {
"id": "T03",
"descriptionChi": "-18度",
"descriptionEn": "-18°C"
},
"categoryOption": {
"id": "C201",
"descriptionChi": "酒",
"descriptionEn": "Wine"
},
"statusLogs": [
{
"time": "2022-08-12 15:06",
"status": "Completed"
},
{
"time": "2022-08-12 15:03",
"status": "On the way to customer"
},
{
"time": "2022-08-12 14:56",
"status": "Arrived at warehouse"
},
{
"time": "2022-08-12 14:56",
"status": "Checked in at warehouse"
},
{
"time": "2022-08-12 14:55",
"status": "On the way to warehouse"
},
{
"time": "2022-08-12 14:52",
"status": "Bulk assign courier"
},
{
"time": "2022-08-12 14:51",
"status": "Confirmed"
}
]
},
{
"itemTrackingNumber": "JP319037070061",
"itemState": "voided",
"itemNotes": null,
"dimensionOption": {
"id": "D03",
"descriptionChi": "小: <30cm",
"descriptionEn": "Small: <30cm"
},
"weightOption": {
"id": "W01",
"descriptionChi": "重: >10kg",
"descriptionEn": "Heavy: >10kg"
},
"adjustedWeight": 15,
"adjustedLength": 30,
"adjustedWidth": 30,
"adjustedHeight": 30,
"temperatureOption": {
"id": "T01",
"descriptionChi": "室溫",
"descriptionEn": "Room Temperature"
},
"categoryOption": {
"id": "C202",
"descriptionChi": "食品",
"descriptionEn": "Food"
},
"statusLogs": [
{
"time": "2022-08-12 15:07",
"status": "Problem item"
},
{
"time": "2022-08-12 15:07",
"status": "Undelivered",
"remarks": "Parcel damaged 貨件破損"
},
{
"time": "2022-08-12 15:03",
"status": "On the way to customer"
},
{
"time": "2022-08-12 14:57",
"status": "Arrived at warehouse"
},
{
"time": "2022-08-12 14:57",
"status": "Checked in at warehouse"
},
{
"time": "2022-08-12 14:55",
"status": "On the way to warehouse"
},
{
"time": "2022-08-12 14:52",
"status": "Bulk assign courier"
},
{
"time": "2022-08-12 14:51",
"status": "Confirmed"
}
]
}
],
"statusLogs": [
{
"time": "2021-09-08 18:39",
"status": "Completed"
},
{
"time": "2021-09-08 18:39",
"status": "Problem Shipment"
}
]
}
}
```
#### Example Error Messages
##### Invalid `trackingNumber` (Status Code: 404)
```json=
{
"message": "Shipment cannot be found"
}
```
---
### `GET /v2/shipment/item/{trackingNumber}`
:::info
To retrieve the details of a specific item
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v2/shipment/item/{trackingNumber}`
* Production: `GET https://open-api.jumppoint.io/v2/shipment/item/{trackingNumber}`
#### 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 | 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' |
| orderDate | string | Creation Time of the shipment; at Hong Kong Time; | "2021-06-25 16:57" |
| shipmentState | string | Current status of the shipment; See [shipmentState](#shipmentState-v2) | 'On the way to customer' |
| sameDayDelivery | boolean | `true` for “Same-Day Delivery Service”; <br/> `false` for “Standard Delivery Service”; | true |
| pickUpDate | string | Pick Up Date of the shipment; <br/> only for “Same-Day Delivery Service”; | '2021-06-26' |
| deliveryDate | string | Delivery Date of the shipment; <br/> only for “Same-Day Delivery Service”; | '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](#paymentMethod) | 'PAID_BY_MERCHANT' |
| cod | decimal(8,2) | Cash On Delivery Amount | 100 |
| isSelfPickUp | boolean | `true` for “Self Pick Up”; <br/> `false` for “To-Door Delivery”; | true |
| noOfItems | number | Total Charge | 2 |
| orderNotes | string | Order Notes (if any) | "call customer before delivery" |
| externalOrderNumber | string | External Order Number <br/> (if any) | "0951358" |
| origin | object | [Sender Address Details](#origin) | *[see above]* |
| destination | object | [Receiptient Address Details](#destination) | *[see above]* |
| pickUpStore | object | [Pick Up Store Details](#pickUpStore) | *[see above]* |
| item | array(1) | [Parcels Details](#item-v2) | *[see below]* |
| statusLogs | array | [Trackings of shipment sorted by time descendingly](#statusLogs-v2) | *[see below for objects in the array]* |
##### item-v2
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| itemTrackingNumber | string | Tracking Number of the child item | "JP658854693314"|
| itemState | string | Current status of the item; See [itemState](#itemState-v2) | 'On the way to customer' |
| itemNotes | string | Order Notes (if any) | "call customer before delivery" |
| externalOrderNumber | string | External Order Number <br/> (if any) | "0951358" |
| dimensionOption | object | [Dimension Details](#item-options) | *[see above]* |
| weightOption | object | [Weight Details](#item-options); <br/> Only applicable for 'Same-Day Delivery Service'; | *[see above]* |
| actualWeight | number | Actual Weight of parcel (in kg); <br/> Only applicable for 'Standard Delivery Service'; | 2 |
| 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 |
| temperatureOption | object | [Temperature Details](#item-options); <br/> Only applicable for 'Same-Day Delivery Service' | *[see above]* |
| categoryOption | object | [Category Details](#item-options); <br/> Only applicable if no `'category'` inputted | *[see above]* |
| category | number | Category inputted; <br/> Only applicable if no `'categoryOption'` provided | 'Toys' |
| statusLogs | array | [Trackings of item sorted by time descendingly](#statusLogs-v2) | *[see below for objects in the array]* |
#### Example Response
```json=
{
"shipment": {
"trackingNumber": "JP135264631722",
"refNo": "JUMPPOINT_EO_003012",
"orderDate": "2021-09-07 18:42",
"shipmentState": "Completed",
"sameDayDelivery": false,
"shipmentFee": 28,
"additionalWeightFee": 0,
"totalFee": 28,
"totalCharge": 28,
"paymentMethod": "PAID_BY_MERCHANT",
"cod": 0,
"isSelfPickUp": true,
"noOfItems": 2,
"orderNotes": "fragile",
"origin": {
"contactName": "Peter Chan",
"contactPhone": "98745632",
"address": "新蒲崗大有街31號善美工業大廈",
"floor": "13",
"room": "B",
},
"destination": {
"contactName": "Peter Chan",
"contactPhone": "98745632"
},
"pickUpStore": {
"code": "KLE48",
"alias": "新蒲崗自提點",
"districtEn": "Wong Tai Sin",
"districtChi": "黃大仙",
"address": "大有街31號 善美工業大廈10樓1001室",
"operationTime": {
"mondayFrom": "09:00",
"mondayTo": "18:00",
"tuesdayFrom": "09:00",
"tuesdayTo": "18:00",
"wednesdayFrom": "09:00",
"wednesdayTo": "18:00",
"thursdayFrom": "09:00",
"thursdayTo": "18:00",
"fridayFrom": "09:00",
"fridayTo": "18:00",
"saturdayFrom": "09:00",
"saturdayTo": "18:00",
"sundayFrom": "09:00",
"sundayTo": "18:00",
"publicHolidayFrom": "09:00",
"publicHolidayTo": "18:00"
},
"freeStorage": 2
},
"items": [
{
"itemTrackingNumber": "JP135264631725",
"itemState": "voided",
"itemNotes": null,
"dimensionOption": {
"id": "D03",
"descriptionChi": "小: <30cm",
"descriptionEn": "Small: <30cm"
},
"weightOption": {
"id": "W01",
"descriptionChi": "重: >10kg",
"descriptionEn": "Heavy: >10kg"
},
"adjustedWeight": 15,
"adjustedLength": 30,
"adjustedWidth": 30,
"adjustedHeight": 30,
"temperatureOption": {
"id": "T01",
"descriptionChi": "室溫",
"descriptionEn": "Room Temperature"
},
"categoryOption": {
"id": "C202",
"descriptionChi": "食品",
"descriptionEn": "Food"
},
"statusLogs": [
{
"time": "2022-08-12 15:07",
"status": "Problem item"
},
{
"time": "2022-08-12 15:07",
"status": "Undelivered",
"remarks": "Parcel damaged 貨件破損"
},
{
"time": "2022-08-12 15:03",
"status": "On the way to customer"
},
{
"time": "2022-08-12 14:57",
"status": "Arrived at warehouse"
},
{
"time": "2022-08-12 14:57",
"status": "Checked in at warehouse"
},
{
"time": "2022-08-12 14:55",
"status": "On the way to warehouse"
},
{
"time": "2022-08-12 14:52",
"status": "Bulk assign courier"
},
{
"time": "2022-08-12 14:51",
"status": "Confirmed"
}
]
}
],
"statusLogs": [
{
"time": "2021-09-08 18:39",
"status": "Completed"
},
{
"time": "2021-09-08 18:39",
"status": "Problem Shipment"
}
]
}
}
```
#### Example Error Messages
##### Invalid `trackingNumber` (Status Code: 404)
```json=
{
"message": "Shipment cannot be found"
}
```
---
### `POST /v2/shipment/pick-up-on-hold-release`
:::info
To release pick up on hold standard delivery shipment. Assign pick up date to shipment and allow shipment being picked up
:::
#### Resource URL
* Sandbox: `POST https://staging.open-api.jumppoint.io/v2/shipment/pick-up-on-hold-release`
* Production: `POST https://open-api.jumppoint.io/v2/shipment/pick-up-on-hold-release`
#### Resource Information
| Request Content-Type | Response formats | Requires authentication |
| -------- | -------- | -------- |
| `application/json` | `application/json; charset=utf-8` | Yes |
#### Body Parameters
| Name | Type | Required | Description | Example |
| -------- | -------- | -------- | -------- | -------- |
| trackingNumber | string | Yes | shipment tracking number that has been pick up on hold | JP135264631722 |
| pickUpDate | string | No |Format: YYYY-MM-DD;<br/>Get from 'GET /date/valid' | 2022-03-10 |
#### Example Request Body
```json=
{
"trackingNumber": "JP135264631722",
"pickUpDate": "2022-03-10"
}
```
#### Example Response
> Status Code: 201 Created
```json=
{
"id": "321ea0ed-0e73-4595-a690-73162e565e22",
"webhookUrl": null,
"mainTrackingNumber": "JP135264631722",
"refNo": "AIGNITER_EO_005222",
"orderDate": "2023-03-09 11:49",
"shipmentState": "Created",
"sameDayDelivery": false,
"pickUpDate": "2023-03-10",
"pickUpOnHold": false,
"labelUrl": null,
"detailedLabelUrl": null,
"shipmentFee": 20,
"additionalWeightFee": 0,
"totalFee": 20,
"totalCharge": 20,
"paymentMethod": "PAID_BY_MERCHANT",
"cashOnDeliveryAmount": 0,
"merchant": {
"name": "Aigniter",
"showSenderOnLabel": true
},
"isSelfPickUp": false,
"noOfItems": 1,
"origin": {
"contactName": "example contact name",
"contactPhone": "00000000",
"lineChi": "九龍西",
"lineEn": "KLN West",
"districtChi": "油尖旺",
"districtEn": "Yau Tsim Mong",
"areaChi": "大角咀",
"areaEn": "Tai Kok Tsui",
"districtGroupChi": "大角咀",
"districtGroupEn": "Tai Kok Tsui",
"address": "address example"
},
"destination": {
"contactName": "example contact name",
"contactPhone": "00000000",
"lineChi": "九龍西",
"lineEn": "KLN West",
"districtChi": "油尖旺",
"districtEn": "Yau Tsim Mong",
"areaChi": "大角咀",
"areaEn": "Tai Kok Tsui",
"districtGroupChi": "大角咀",
"districtGroupEn": "Tai Kok Tsui",
"address": "address example"
},
"items": [
{
"id": "7a56c605-55b0-4d30-a00b-fe2ad8a9119a",
"itemTrackingNumber": "JP319038003416",
"itemExternalNumber": "00000000",
"itemState": "created",
"itemNotes": "00000000",
"dimensionOption": {
"id": "D02",
"descriptionChi": "中: 31-60cm",
"descriptionEn": "Medium: 31-60cm"
},
"actualWeight": 6,
"categoryOption": {
"id": "C103",
"descriptionChi": "日用品",
"descriptionEn": "Daily Necessities"
},
"statusLogs": []
}
],
"statusLogs": [
{
"time": "2023-03-09 11:49",
"status": "Release shipment pick up on hold"
},
{
"time": "2023-03-09 11:49",
"status": "Shipment pick up on hold"
}
]
}
```
#### Example Error Messages
##### Invalid Form Input
```json=
{
"statusCode": 404,
"ERROR_CODE": "TRACKING_NUMBER_NOT_FOUND",
"message": "No matching tracking number was found","error": "Not Found",
}
```
```json=
{
"statusCode": 400,
"ERROR_CODE": "INVALID_SHIPMENT",
"message": "Same Day Delivery Shipment won\'t be pick up on hold",
"error": 'Bad Request',
}
```
---
## Dates
### `GET /v2/date/valid`
:::info
To retrieve lists of valid Pick-Up and Delivery Dates
:::
#### Notes
:::danger
* Pick-Up and Delivery Dates only apply to shipments with **Same-Day Delivery Service**
* Dates are in local Hong Kong Time
* Delivery services and Pick-Up services are only available on working days, i.e. Monday to Saturday with public holidays excluded
* Cut-off time of delivery would be 20:00 on the day before pick-up date, i.e. cut-off time of delivery on Saturday would be 20:00 on Friday
* Delivery Date should not be earlier than Pick-Up Date
* Delivery Date should not be 3 days later than Pick-Up Date (with Sunday and public holidays excluded)
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v2/date/valid`
* Production: `GET https://open-api.jumppoint.io/v2/date/valid`
#### Resource Information
| Response formats | Requires authentication |
| --------------------------------- | ----------------------- |
| `application/json; charset=utf-8` | Yes |
#### Example Response
```json=
{
"pickUpDates": [
"2021-09-28",
"2021-09-29",
"2021-09-30",
"2021-10-04",
"2021-10-05",
"2021-10-06",
"2021-10-07"
],
"deliveryDates": [
"2021-09-28",
"2021-09-29",
"2021-09-30",
"2021-10-02",
"2021-10-04",
"2021-10-05",
"2021-10-06",
"2021-10-07",
"2021-10-08",
"2021-10-09",
"2021-10-11",
]
}
```
---
## Item
### `GET /v2/item/options`
:::info
To retrieve lists of valid item options
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v2/item/options`
* Production: `GET https://open-api.jumppoint.io/v2/item/options`
#### Resource Information
| Response formats | Requires authentication |
| --------------------------------- | ----------------------- |
| `application/json; charset=utf-8` | Yes |
#### Example Response
```json=
{
"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`; <br/> required; |
|dimensionThirdParty | `id` used in `dimensionOptionId`;<br/> Only valid option when `sameDayDelivery` is `false` and pick up store is from third party(Circle K);<br/>
| temperature | `id` used in `temperatureOptionId`; <br/> required when `sameDayDelivery` is `true`; |
| weight | `id` used in `weightOptionId`; <br/> required when `sameDayDelivery` is `true`; |
---
## Pick Up Stores
### `GET /v2/pick-up-store/list`
:::info
To retrieve lists of Pick Up Stores
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v2/pick-up-store/list`
* Production: `GET https://open-api.jumppoint.io/v2/pick-up-store/list`
#### Resource Information
| Response formats | Requires authentication |
| --------------------------------- | ----------------------- |
| `application/json; charset=utf-8` | Yes |
#### Response Parameters
| Parameter | Type | Description | Example |
| -------- | -------- | -------- | -------- |
| pickUpStores | obeject[] | Returned Pick Up Stores | See [pickUpStore](#pickUpStore) |
#### Notes
:::warning
* `code` used as `pickUpStoreCode` in [`POST /v2/shipment`](#Create-a-Shipment-POST-v2shipment)
* `operationTime` are in local Hong Kong Time
:::
#### Example Response
```json=
{
"pickUpStores": [
{
"code": "KLE48",
"alias": "新蒲崗自提點",
"districtEn": "Wong Tai Sin",
"districtChi": "黃大仙",
"address": "大有街31號 善美工業大廈10樓1001室",
"operationTime": {
"mondayFrom": "09:00",
"mondayTo": "18:00",
"tuesdayFrom": "09:00",
"tuesdayTo": "18:00",
"wednesdayFrom": "09:00",
"wednesdayTo": "18:00",
"thursdayFrom": "09:00",
"thursdayTo": "18:00",
"fridayFrom": "09:00",
"fridayTo": "18:00",
"saturdayFrom": "09:00",
"saturdayTo": "18:00",
"sundayFrom": "09:00",
"sundayTo": "18:00",
"publicHolidayFrom": "09:00",
"publicHolidayTo": "18:00"
},
"freeStorage": 2,
"providingServices": {
"cashReceipt": true,
"dropOff": false
}
}
]
}
```
---
## Label
### `GET /v2/label/shipment/{trackingNumber}`
:::info
To retrieve list of labels for all items by PARENT shipment tracking number
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v2/label/shipment/{trackingNumber}`
* Production: `GET https://open-api.jumppoint.io/v2/label/shipment/{trackingNumber}`
#### 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
:::warning
* The download link will be expired in 10 minutes.
* You should save the PDF file to your device on getting the link.
* You will need to recall the API to get a new link after 10 minutes.
:::
```json=
{
"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**)
```json=
{
"message": "Shipment cannot be found"
}
```
### `GET /v2/label/item/{trackingNumber}`
:::info
To retrieve label for specific item by corresponding item tracking number
:::
#### Resource URL
* Sandbox: `GET https://staging.open-api.jumppoint.io/v2/label/item/{trackingNumber}`
* Production: `GET https://open-api.jumppoint.io/v2/label/item/{trackingNumber}`
#### 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
:::warning
* The download link will be expired in 10 minutes.
* You should save the PDF file to your device on getting the link.
* You will need to recall the API to get a new link after 10 minutes.
:::
```json=
{
"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**)
```json=
{
"message": "Shipment cannot be found"
}
```
---
# 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 /v1/shipment`](#POST-v1shipment) requests.
:::warning
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:
```json=
{
"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](#shipmentState-v2) |
### Item's tracking status changed
When your item's tracking status changed, you'll get the event payload as below:
```json=
{
"time": "2021-09-27 10:34",
"shipmentTrackingNumber": "JP319037069928",
"itemTrackingNumber": "JP319037069931",
"itemState": "On the way to customer"
}
```
Another Example:
```json=
{
"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](#itemState-v2) |
| remarks | string | (if any) | 'Nobody answered the door 無人應門' |
Sign in with Wallet
Connect another wallet