Get Rates

Retrieve shipping rates and available courier options for a shipment.

Endpoint

POST /v1/rates/get

Request

Header Parameters

---

Parameter	Type	Required	Example	Description
Authorization	string	Yes	Bearer YOUR_ACCESS_TOKEN	Bearer access token used for authentication.
Content-Type	string	Yes	application/json	Request 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:

Value	Description
local	Local shipment
intl	International 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

shipment_detailrequired

json-string

Shipment details.

package_typerequired

string

Package type identifier.

Enum: "parcel" "document" "pallet"

Example: parcel

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"
  },
  "shipment_detail": {
    "package_type": "parcel",
    "parcel_list": [
      {
        "length": "10",
        "width": "14",
        "height": "12",
        "act_weight": "1",
        "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" },
  "shipment_detail": {
    "package_type": "parcel",
    "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"
  }
}