Service Codes

A Service Code is the orderable service unit on Merdi Express. It is the value you put in the service_tier_id field (e.g. HKASTDGGSTCM) — the field name is historical and kept unchanged for backwards compatibility.

The three-layer model

Since 2026-06-10 the service catalog is a three-layer model. Your account is entitled at the Product Code level; every Service Code under an entitled Product Code is bookable.

Product Code (product container — entitlement level, NOT orderable)
 └─ HKASTD = origin HK + price list A (public) + product type STD (standard)
      │ one Product Code contains many…
      ▼
Service Code (orderable unit = service_tier_id in the API)
 └─ HKASTDGGSTCM = HKASTD + GG general goods (battery-ok) + ST standard air + CM combined last-mile
      │ each Service Code × destination (× zone) resolves to one…
      ▼
Rate Table (price table — versioned, immutable)
 └─ RT-HKASTDGGSTCM-US-v1 (value-added service prices pre-composed into the brackets)

Code anatomy

A Service Code = Product Code + three dimension segments, in fixed order:

Not every combination exists. Delivery-day figures are estimate conventions (not guarantees) — read each code's eta_days_min / eta_days_max from the API response.

Current codes

This table is a 2026-06-10 snapshot. Always read the live list — and each code's destinations and ETA — from GET /v1/service_tiers. Do not hardcode this table.

Legacy codes US-GEN-PUB-001 / US-GEN-PUB-002 / HK-ST-GG-01 / HK-US-SE-GG-01 / HKUSSTCS01 were retired and deleted on 2026-06-10 and now return 404 — migrate to HKASTDGGSTCM (or the matching line above).

Standard vs value-added

The code with is_standard_service: true is the default standard line (currently HKASTDGGSTCM). “Value-added” means a dimension-level upgrade — priority air (PR), postal last-mile (PS), the cosmetics line (CS) — flagged is_vas: true inside service_options.

Note: opt-in surcharges such as signature / insurance (selected_surcharges) are a separate layer, not a Service Code dimension — see the POST /v1/shipments reference.

Fetch your codes

GET /v1/service_tiers returns the Service Codes your account is entitled to (via Product Code) and that are fulfillable. Put the chosen id into service_tier_id on POST /v1/shipments. Match the cargo dimension to your goods (cosmetics → CS line).

curl "https://merdiexpress.com/api/v1/service_tiers" \
  -H "Authorization: Bearer mk_test_rh9ABekJfP31cN7sQ8jKvLwY"

# optional filter: /api/v1/service_tiers?dispatch_mode=B2C

{
  "status": 200,
  "message": "OK",
  "data": [
    {
      "id": "HKASTDGGSTCM",
      "name": { "en": "香港發貨公開價標準服務", "zh_hk": "香港發貨公開價標準服務" },
      "product_code": "HKASTD",
      "is_standard_service": true,
      "service_options": [
        { "layer_key": "cargo_type", "option_code": "GG", "label_zh": "普貨（帶電）", "is_vas": false },
        { "layer_key": "air_service", "option_code": "ST", "label_zh": "標準", "is_vas": false },
        { "layer_key": "tail_service", "option_code": "CM", "label_zh": "綜合", "is_vas": false }
      ],
      "origin_countries": ["HK"],
      "destination_countries": ["AU", "CA", "DE", "ES", "FR", "GB", "IE", "IT", "NL", "US"],
      "eta_days_min": 8,
      "eta_days_max": 12,
      "delivery_mode": "resell",
      "status": "Active",
      "carrier": { "code": "yunexpress", "product_code": "HKTHZXR", "dispatch_mode": "B2C" }
    }
  ]
}

The two product_code fields

The response carries two fields named product_code with completely different meanings — do not confuse them: