Skip to main content

Get Rates

Retrieve shipping rates and available courier options for a shipment.

Endpoint​

POST /v1/rates/get

Request​

Header Parameters​

ParameterTypeRequiredExampleDescription
AuthorizationstringYesBearer YOUR_ACCESS_TOKENBearer access token used for authentication.
Content-TypestringYesapplication/jsonRequest body content type.

Request Body Schema​

application/json
ship_type
string
Shipment type. Defaults to local if not provided.
Example: intl
Expand for valid values.
Supported values:
ValueDescription
localLocal shipment
intlInternational shipment
senderrequired
json-string
Sender information.
countryrequired
string
Sender country. Uses ISO 3166-1 alpha-2 code or full country name.
Reference: Get Country for full list.
Example: Hong Kong
recipientrequired
json-string
Recipient information.
countryrequired
string
Recipient country. Uses ISO 3166-1 alpha-2 code or full country name.
Reference: Get Country for full list.
Example: Singapore
postal_code
string
Recipient postal code. Used to determine remote area surcharge eligibility.
Example: 238801
shipment_detailrequired
json-string
Shipment details.
package_typerequired
string
Package type identifier.
Enum: "parcel" "document" "pallet"
Example: parcel
currency
string
Currency for declared values. Defaults to HKD if not provided.
Example: USD
Expand for valid values.
Supported values:
CodeDescription
HKDHong Kong Dollar
USDUS Dollar
EUREuro
CNYChinese Yuan
GBPBritish Pound
AEDUAE Dirham
ARSArgentine Peso
AUDAustralian Dollar
BRLBrazilian Real
CADCanadian Dollar
CHFSwiss Franc
CZKCzech Koruna
DKKDanish Krone
EGPEgyptian Pound
HUFHungarian Forint
IDRIndonesian Rupiah
ILSIsraeli Shekel
INRIndian Rupee
JPYJapanese Yen
KESKenyan Shilling
KRWSouth Korean Won
MOPMacanese Pataca
MXNMexican Peso
MYRMalaysian Ringgit
NOKNorwegian Krone
NZDNew Zealand Dollar
PHPPhilippine Peso
PLNPolish Zloty
RUBRussian Ruble
SARSaudi Riyal
SEKSwedish Krona
SGDSingapore Dollar
THBThai Baht
TRYTurkish Lira
TWDNew Taiwan Dollar
ZARSouth African Rand
parcel_listrequired
array
Array of parcels. At least one required.
Example: Reference parcel object below
length
string
Length in cm.
Example: 35
width
string
Width in cm.
Example: 25
height
string
Height in cm.
Example: 15
act_weightrequired
string
Actual weight in kg.
Example: 0.5
quantity
string
Number of parcels in this shipment.
Example: 1

Example Request Body​

{
  "ship_type": "intl",
  "sender": {
    "country": "Hong Kong"
  },
  "recipient": {
    "country": "Singapore",
    "postal_code": "238801"
  },
  "shipment_detail": {
    "package_type": "parcel",
    "currency": "USD",
    "parcel_list": [
      {
        "length": "10",
        "width": "14",
        "height": "12",
        "act_weight": "5",
        "quantity": "1"
      }
    ]
  }
}

Example request​

curl -X POST "${API_URL}/v1/rates/get" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "ship_type": "intl",
  "sender": { "country": "Hong Kong" },
  "recipient": { "country": "Singapore", "postal_code": "238801" },
  "shipment_detail": {
    "package_type": "parcel",
    "currency": "USD",
    "parcel_list": [{ "length": "10", "width": "14", "height": "12", "act_weight": "1", "quantity": "1" }]
  }
}'

Responses​

200 Success​

200 Success

Response schema: application/json
data
json-string
Response data container.
data.rates
array
Array of rate objects. At least one required.
Example: Reference rate object below
shipping_provider
string
Shipping provider code.
cost_price
string
Total shipping cost.
display_name
string
Display name of shipping option.
delivery_time
string
Estimated delivery time in days (e.g. 3-5).
price_sign
string
Currency code (e.g. HKD).
rate_break_down
json-string
Breakdown of charges: base_rate, remote_surcharge, extra_large_package_fee.
data.ship_type
string
Shipment type (local or intl).
data.sender
json-string
Sender details.
data.recipient
json-string
Recipient details.
data.shipment_detail
json-string
Shipment details.

Response sample

{
  "data": {
    "rates": [
      {
        "shipping_provider": "upshk_import_saver",
        "cost_price": "415",
        "display_name": "UPS 優比速 (Express Saver)",
        "delivery_time": "3-5",
        "price_sign": "HKD",
        "rate_break_down": {
          "base_rate": "415",
          "remote_surcharge": "0",
          "extra_large_package_fee": "0"
        }
      },
      {
        "shipping_provider": "upshk_import_saver",
        "cost_price": "431",
        "display_name": "UPS 優比速 (Expedited)",
        "delivery_time": "3-5",
        "price_sign": "HKD",
        "rate_break_down": {
          "base_rate": "431",
          "remote_surcharge": "0",
          "extra_large_package_fee": "0"
        }
      }
    ],
    "ship_type": "intl",
    "sender": { "country": "US" },
    "recipient": { "country": "HK" },
    "shipment_detail": {
      "package_type": "parcel",
      "parcel_list": [
        {
          "length": "35",
          "width": "25",
          "height": "15",
          "act_weight": "0.5",
          "quantity": "1"
        }
      ]
    }
  }
}

400 Bad Request​

400 Bad Request

Response schema: application/json
code
string
Error code returned by the API.
Example: 400000
code_reason
string
Machine-readable error reason.
Example: BAD_REQUEST
message
string
Summary of the error.
Example: Bad Request
error_trace
array
List of validation errors (field and message per item).
field
string
Request field that failed (dot notation).
message
string
Human-readable explanation for this error.

Response sample

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "Bad Request",
    "error_trace": [
      { "field": "sender.country", "message": "Sender country is required" },
      { "field": "recipient.country", "message": "Recipient country is required" },
      { "field": "shipment_detail.parcel_list", "message": "Parcel list is required and must be an array" },
      { "field": "shipment_detail.package_type", "message": "Package type is required" }
    ]
  }
}

401 Unauthorized​

401 Unauthorized

Response schema: application/json
code
string
Error code (e.g. 401000, 401020).
Example: 401000
code_reason
string
Machine-readable reason.
Example: UNAUTHORIZED
message
string
Human-readable message.
Example: Unauthorized

Response sample

{
  "error": {
    "code": "401000",
    "code_reason": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

403 Forbidden​

403 Forbidden

Response schema: application/json
error
json-string
Access forbidden for this resource.

Response sample

{
  "error": {
    "code": "403000",
    "code_reason": "FORBIDDEN",
    "message": "Forbidden"
  }
}

404 Not Found​

404 Not Found

Response schema: application/json
error
json-string
Resource or endpoint not found.

Response sample

{
  "error": {
    "code": "404000",
    "code_reason": "NOT_FOUND",
    "message": "Not Found"
  }
}

500 Failure​

500 Failure

Response schema: application/json
code
string
Error code returned by the API.
Example: 500999
code_reason
string
Machine-readable error reason.
Example: API_ERROR
message
string
Human-readable message.
Example: Api Error, please contact customer service

Response sample

{
  "error": {
    "code": "500999",
    "code_reason": "API_ERROR",
    "message": "Api Error, please contact customer service"
  }
}