Skip to main content

Get Fee Summary

Calculate the fee breakdown for a shipment.

Endpoint​

POST /v1/fee/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_typerequired
string
Shipment type.
Enum: "local" "intl"
Example: intl
shipping_providerrequired
string
Shipping provider code, local or international.
Reference: Get Rates for valid codes.
Example: fedex_ip_export, sf_expresshk_local
senderrequired
json-string
Sender information.
namerequired
string
Sender full name.
Example: John Doe
mobilerequired
string
Mobile number without country prefix.
Example: 91234567
mobile_prefixrequired
string
Mobile country calling code.
Example: +852
email
string
Sender email address.
Example: john@example.com
addressrequired
string
Street address.
Minimum 5 characters.
Example: Unit 12, 3/F, ABC Building
countryrequired
string
Country code. Determines whether the shipment is treated as local or international.
Reference: Get Country for full list.
Example: HK
recipientrequired
json-string
Recipient information.
namerequired
string
Recipient full name.
Example: Hans Mueller
mobilerequired
string
Mobile number without country prefix.
Example: 98765432
mobile_prefixrequired
string
Mobile country calling code.
Example: +49
email
string
Recipient email address.
Example: david@example.de
addressrequired
string
Street address.
Note: For local pickup-point quotes, you may append the delivery code using the format address^delivery_code.
Reference: Get Pickup Points for valid delivery_code values.
Minimum 5 characters.
Example (local): 香港九龍牛頭角創業街9號2211室^H852M038P
Example (international): Musterstrasse 123
city
string
City name. Used to determine remote area surcharge eligibility.
International shipments only.
Example: Berlin
post_code
string
Postal or ZIP code. Used to determine remote area surcharge eligibility.
International shipments only.
Example: 10115
countryrequired
string
Country code. Determines whether the shipment is treated as local or international.
Reference: Get Country for full list.
Example: DE
shipment_detailrequired
json-string
Shipment and parcel details.
package_typerequired
string
Package type identifier.
Enum: "parcel" "document" "pallet" "envelope"
Example: parcel
parcel_listrequired
array
Array of parcel details. At least one parcel is required.
Example: Reference parcel object below
act_weightrequired
string
Actual parcel weight in kg.
Example: "0.50"
height
string
Parcel height in cm.
Example: "10"
width
string
Parcel width in cm.
Example: "15"
length
string
Parcel length in cm.
Example: "20"
declaration_list
array
Customs declaration items for this parcel.
International shipments only — required when ship_type is intl.
Example: Reference declaration object below
descriptionrequired
string
Item description for customs.
Example: Bluetooth headset
qtyrequired
string
Quantity of items.
Example: "2"
single_pricerequired
string
Declared price per unit.
Example: "50.00"
parcel_items
array
Items in this parcel.
Local shipments only — used in place of declaration_list when ship_type is local.
Example: Reference parcel item object below
namerequired
string
Item name.
Example: Toy
qtyrequired
string
Quantity of items.
Example: "1"
single_valuerequired
string
Single item value in HKD.
Example: "200.00"

Example Request Body International​

{
  "ship_type": "intl",
  "shipping_provider": "fedex_ip_export",
  "sender": {
    "name": "John Doe",
    "mobile": "91234567",
    "mobile_prefix": "+852",
    "email": "johndoe@test.com",
    "address": "Unit 1203, 2 Harbour Road",
    "country": "HK"
  },
  "recipient": {
    "name": "Hans Mueller",
    "mobile": "1512345678",
    "mobile_prefix": "+49",
    "email": "muller@test.com",
    "address": "Musterstrasse 123",
    "city": "Berlin",
    "post_code": "10115",
    "country": "DE"
  },
  "shipment_detail": {
    "package_type": "parcel",
    "parcel_list": [
      {
        "act_weight": "0.50",
        "height": "10",
        "width": "15",
        "length": "20",
        "declaration_list": [
          {
            "description": "Wireless earbuds with charging case",
            "qty": "2",
            "single_price": "50.00"
          }
        ]
      }
    ]
  }
}

Example Request Body Local​

{
  "ship_type": "local",
  "shipping_provider": "sf_expresshk_local",
  "sender": {
    "name": "Fuuffy Chai",
    "mobile": "64105317",
    "mobile_prefix": "852",
    "email": "cs@fuuffy.com",
    "address": "Rm2211, 9 Chong Yip Street, Ngau Tau Kok, Hong Kong"
  },
  "recipient": {
    "name": "小編姐姐",
    "mobile": "64105317",
    "mobile_prefix": "852",
    "email": "cs@fuuffy.com",
    "address": "香港九龍牛頭角創業街9號2211室"
  },
  "shipment_detail": {
    "package_type": "parcel",
    "parcel_list": [
      {
        "act_weight": "0.5",
        "height": "10",
        "width": "14",
        "length": "23",
        "parcel_items": [
          {
            "name": "Toy",
            "qty": "1",
            "single_value": "200.00"
          }
        ]
      }
    ]
  }
}

Example request​

curl -X POST "${API_URL}/v1/fee/get" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "ship_type": "intl",
  "shipping_provider": "fedex_ip_export",
  "sender": {
    "name": "John Doe",
    "mobile": "91234567",
    "mobile_prefix": "+852",
    "email": "johndoe@test.com",
    "address": "Unit 1203, 2 Harbour Road",
    "country": "HK"
  },
  "recipient": {
    "name": "Hans Mueller",
    "mobile": "1512345678",
    "mobile_prefix": "+49",
    "email": "muller@test.com",
    "address": "Musterstrasse 123",
    "city": "Berlin",
    "post_code": "10115",
    "country": "DE"
  },
  "shipment_detail": {
    "package_type": "parcel",
    "parcel_list": [
      {
        "act_weight": "0.50",
        "height": "10",
        "width": "15",
        "length": "20",
        "declaration_list": [
          {
            "description": "Wireless earbuds",
            "qty": "2",
            "single_price": "50.00"
          }
        ]
      }
    ]
  }
}'

Responses​

200 Success​

200 Success

Response schema: application/json
data
json-string
Fee calculation result.
Expand for fields.
ship_type
string
Detected shipment type.
Example: intl
shipping_provider
string
Shipping provider code used for the calculation.
Example: fedex_ip_export
currency
string
Billing currency. Always HKD.
Example: HKD
total_price
string | null
Final total price, after any points/discount deduction.
Example: "410.00"
fee_summary
array
Itemized fee breakdown. Always ends with the total_price item.
key
string
Machine-readable fee item key.
Example: cost_price, remote_surcharge_fee, total_price
value
string
Amount for this fee item, in currency.
label
json-string
Bilingual label for this fee item.
Example: {"en":"Shipping Fee","tc":"運費"}

Response sample

{
  "data": {
    "ship_type": "intl",
    "shipping_provider": "fedex_ip_export",
    "currency": "HKD",
    "total_price": "410.00",
    "fee_summary": [
      {
        "key": "cost_price",
        "value": "350.00",
        "label": {
          "en": "Shipping Fee",
          "tc": "運費"
        }
      },
      {
        "key": "international_processing_fee",
        "value": "20.00",
        "label": {
          "en": "International Processing Fee",
          "tc": "國際處理費"
        }
      },
      {
        "key": "remote_surcharge_fee",
        "value": "40.00",
        "label": {
          "en": "Remote Surcharge",
          "tc": "偏遠附加費"
        }
      },
      {
        "key": "total_price",
        "value": "410.00",
        "label": {
          "en": "Total Fee",
          "tc": "總價"
        }
      }
    ]
  }
}

400 Bad Request​

400 Bad Request

Response schema: application/json
error.code
string
Error code returned by the API.
Example: 400000
error.code_reason
string
Machine-readable error reason.
Example: BAD_REQUEST
error.message
string
Summary of the error.
Example: Bad Request
error.error_trace
array
List of validation or fee-calculation errors.
field
string
Request field that failed, when applicable.
Example: shipping_provider
code
string
Error code for this specific error, when applicable.
Example: 400428
message
string
Human-readable explanation for this error.
Example: shipping_provider is required

Response sample — validation error

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "Bad Request",
    "error_trace": [
      {
        "field": "shipping_provider",
        "message": "shipping_provider is required"
      },
      {
        "field": "shipment_detail",
        "message": "shipment_detail is required"
      }
    ]
  }
}

Response sample — pickup point / courier mismatch

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "Bad Request",
    "error_trace": [
      {
        "field": "shipping_provider",
        "code": "400428",
        "message": "The recipient address resolves to a pickup point, but the selected shipping_provider does not support pickup point delivery. Please use this courier's pickup-point shipping_provider, or remove the pickup point code from the address."
      }
    ]
  }
}

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.

404 Not Found​

404 Not Found

Response schema: application/json
error
json-string
Resource or endpoint 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"
  }
}