Shipping fee API development documentation

what can be done

• Freight Calculation - Enter the weight of the package (or length, width and volume), and return the package's sea express shipping fee (RMB).
• Get rate - Query the current per kilogram rate, surcharge threshold and volume conversion coefficient, which is convenient for you to calculate or cache on the front end.

All responses are in JSON, in a unified envelope format: when successful, success: true with data; when failed, success: false with error code and message.

Base URL

Authentication header (choose one)

Method A — Bearer Token (recommended)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Method B — X-API-Key

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

The API Key starts with lk_live_. Please keep safe and never put into front-end JavaScript or public Git repositories; all calls should be made from your server side.

Rate Limit

Each key has a request limit per minute, and the response header will report the remaining limit:

header	illustrate
X-RateLimit-Limit	Number of requests allowed per minute
X-RateLimit-Remaining	Number of requests remaining this minute
Retry-After	Number of seconds to wait for time limit exceeded (HTTP 429)

For the best front-end experience, it is recommended to cache the /rates results for a few minutes and calculate them with the same formula on your own server. Only call /quote for verification during the critical steps of placing an order.

GET /api/v1/freight/rates

Lists all currently enabled shipping methods and rates. No parameters are required.

ask

curl https://0523.tw/api/v1/freight/rates \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "success": true,
  "currency": "CNY",
  "data": [
    {
      "method": "sea",
      "name_zh": "海快",
      "name_en": "Sea Express",
      "rate_per_kg": 10,
      "surcharge": 20,
      "min_threshold": 15,
      "volume_divisor": 10000,
      "currency": "CNY"
    }
  ]
}

GETPOST /api/v1/freight/quote

The sea express shipping fee is calculated based on the weight/volume size of the package. Both GET (query string) and POST (JSON or form) are acceptable.

Request parameters

parameter	Type	Required	illustrate
weight	number	Optional*	Actual weight in kilograms (kg).
length	number	Optional*	Length, unit is centimeters (cm).
width	number	Optional*	Width in centimeters (cm).
height	number	Optional*	Height, unit is centimeters (cm).
method	string	Optional	The shipping method is currently sea (sea express). When omitted, sea is assumed.

Request example (GET)

curl "https://0523.tw/api/v1/freight/quote?weight=8&method=sea" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Request example (POST JSON)

curl -X POST https://0523.tw/api/v1/freight/quote \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"weight": 5, "length": 40, "width": 30, "height": 30}'

Response 200

{
  "success": true,
  "data": {
    "method": "sea",
    "method_name_zh": "海快",
    "method_name_en": "Sea Express",
    "currency": "CNY",
    "currency_symbol": "¥",
    "actual_weight": 5,
    "volume_weight": 3.6,
    "volume_divisor": 10000,
    "billable_weight": 5,
    "billable_basis": "actual",
    "rate_per_kg": 10,
    "freight": 50,
    "surcharge": 20,
    "surcharge_applied": true,
    "min_threshold": 15,
    "total_fee": 70
  }
}

Response field description

field	illustrate
actual_weight	Actual weight (kg). 0 if not provided.
volume_weight	Volume (volume) weight (kg) = length × width × height ÷ 10000. 0 if no size is provided.
billable_weight	Billable weight (kg) = max (actual weight, volumetric weight).
billable_basis	Billing is based on :actual (based on actual weight) or volumetric (based on volume).
freight	Basic freight = billing weight × rate per kilogram (excluding surcharges).
surcharge	The actual surcharge for this transaction (0 if not triggered).
surcharge_applied	Whether to trigger surcharge (billing weight < threshold).
total_fee	The final freight receivable is (RMB, rounded to the nearest whole number).

HTTP	error	illustrate
401	missing_api_key	No API Key is provided. Please add Authorization or X-API-Key header.
401	invalid_api_key	API Key is invalid.
403	key_suspended / key_revoked / key_expired	Key has been deactivated/revoked/expired.
403	insufficient_scope	The key does not have the freight:read permission.
422	validation_failed	Parameter format error (type, range).
422	missing_parameters	No weight or full length/width/height provided.
422	unsupported_method	method is not in the available list.
429	rate_limit_exceeded	Exceeding the request limit per minute, see Retry-After.

0337.tw is the Laravel mall. It is recommended to package the shipping fee API into a backend Service and call: during the checkout process:

• After getting the total weight (kg)/volume of the shopping cart at checkout, call /api/v1/freight/quote on the backend , and set the returned total_fee as the shipping fee.
• The key is placed in .env (for example, LUCKY_FREIGHT_KEY) and read with config(). Do not hard-code it in your code or front end.
• When the call fails (timeout / 429), the rate cached in /rates is calculated locally using the same formula as a backup to ensure uninterrupted checkout.
• The amount is in RMB; if the mall settles the bill in New Taiwan Dollars, please apply the exchange rate conversion yourself.

Laravel Example (Http facade)

// app/Services/LuckyFreightService.php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;

class LuckyFreightService
{
    public function quote(float $weight): int
    {
        $res = Http::withToken(config('services.lucky.freight_key'))  // 讀 .env
            ->acceptJson()
            ->timeout(8)
            ->get('https://0523.tw/api/v1/freight/quote', [
                'weight' => $weight,
                'method' => 'sea',
            ]);

        if ($res->successful()) {
            return (int) $res->json('data.total_fee');  // 人民幣
        }

        // 後備:用快取費率本地計算,結帳不中斷
        return $this->fallbackQuote($weight);
    }
}

Add 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] in config/services.php, and then inject LuckyFreightService into the checkout Controller to obtain the freight.

technical support: howyunqisoftware@gmail.com

API version: v1 (stable). Any breaking changes will be released with a new version number (v2), v1 will remain compatible.

Change history: 2026-06-01 — Freight API v1 is online (Hai Express, priced in RMB).