{ "components": { "parameters": { "IdempotencyKey": { "description": "Client-chosen unique key. Same key + same payload within 24h returns the cached response; same key + different payload returns 409 conflict.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 255, "type": "string" } }, "IdempotencyKeyOptional": { "description": "Optional. If supplied, the request is reserved/replayed idempotently for 24h; if omitted, the operation still runs safely (it is naturally idempotent at the resource level). 可選 — 如有提供會以冪等方式保留/重播；如無提供，操作仍可安全執行（本身具冪等性）。", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } }, "TrackingNumberPath": { "description": "Merdi tracking number (e.g. IM1234567890).", "in": "path", "name": "tracking_number", "required": true, "schema": { "type": "string" } } }, "responses": { "BadRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Validation error." }, "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Idempotency-Key conflict OR duplicate URL on webhook creation." }, "CountryList": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/Country" }, "type": "array" } }, "type": "object" } ] } } }, "description": "Supported destination countries." }, "InsufficientFunds": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Wallet balance too low to cover the shipment total (live mode only)." }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Resource not found (or cross-tenant / cross-livemode — D4 enforcement collapses all three to the same 404)." }, "NotImplemented": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Endpoint reserved but not yet wired (e.g. /v1/rates)." }, "RateLimited": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Exceeded per-second or per-day quota. Retry-After header indicates wait time." }, "RateQuotes": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "$ref": "#/components/schemas/PublicQuoteResponse" } }, "type": "object" } ] } } }, "description": "Quote options for the lane (entitlement-scoped)." }, "ServiceTierList": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/PublicServiceTier" }, "type": "array" } }, "type": "object" } ] } } }, "description": "Service tiers the account is entitled to (carrier-assigned only)." }, "ShipmentCancelled": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "$ref": "#/components/schemas/PublicShipmentCancelResponse" } }, "type": "object" } ] } } }, "description": "Shipment cancelled (or already-cancelled snapshot on idempotent replay)." }, "ShipmentCreated": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "$ref": "#/components/schemas/PublicShipmentCreateResponse" } }, "type": "object" } ] } } }, "description": "Shipment created. Includes pricing snapshot + dispatch result. Status 201." }, "ShipmentDetail": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "$ref": "#/components/schemas/ShipmentDetail" } }, "type": "object" } ] } } }, "description": "Shipment detail incl. events." }, "ShipmentListPage": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ShipmentSummary" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "Page of shipment summaries + next_cursor." }, "TrackingDetail": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Shipment tracking detail (broad lookup, projected fields)." }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Missing / invalid / revoked / wrong-mode Bearer token." }, "WebhookCreated": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "$ref": "#/components/schemas/WebhookCreateResponse" } }, "type": "object" } ] } } }, "description": "Webhook endpoint created. PLAINTEXT SECRET in response — capture it." }, "WebhookDeliveryRecord": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } }, "type": "object" } ] } } }, "description": "Test fire result." }, "WebhookList": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Webhook" }, "type": "array" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "Account's webhook endpoints." }, "WebhookRevoked": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReturn" } } }, "description": "Webhook endpoint marked inactive." }, "WebhookSecretRotated": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "properties": { "id": { "type": "string" }, "rotated_at": { "format": "date-time", "type": "string" }, "secret": { "description": "Plaintext whsec_* signing secret — shown EXACTLY ONCE.", "type": "string" }, "secret_last4": { "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "New plaintext signing secret — capture it; no recovery path." }, "WebhookSignedSample": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "properties": { "headers": { "properties": { "Content-Type": { "example": "application/json", "type": "string" }, "X-Merdi-Event-Id": { "type": "string" }, "X-Merdi-Event-Type": { "type": "string" }, "X-Merdi-Signature": { "example": "t=1700000000,v1=", "type": "string" } }, "type": "object" }, "payload": { "description": "Parsed convenience copy of raw_body — for display only; do not re-stringify to verify.", "type": "object" }, "raw_body": { "description": "The EXACT string the signature was computed over. Verify against THIS, never a re-serialized object.", "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "A signed sample event. No delivery was attempted." } }, "schemas": { "ApiReturn": { "properties": { "data": {}, "message": { "type": "string" }, "status": { "type": "integer" }, "sysCode": { "type": "string" } }, "required": [ "status", "message" ], "type": "object" }, "Country": { "properties": { "code": { "type": "string" }, "name": { "properties": { "en": { "type": "string" }, "zh_hk": { "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "CreateShipmentRequest": { "additionalProperties": false, "properties": { "goods_category": { "default": "general", "maxLength": 64, "type": "string" }, "ioss_number": { "description": "EU IOSS number (IM + 10 digits). Overrides the account-level default for this shipment; EU destinations only. With IOSS, EU VAT prepay is not charged and the number is forwarded to the carrier. The number must belong to your account — your own saved IOSS or a marketplace platform IOSS registered to you (contact support to add one); anything else returns 400 IOSS_NOT_OWNED.", "pattern": "^IM\\d{10}$", "type": "string" }, "items": { "items": { "additionalProperties": false, "properties": { "country_of_manufacture": { "description": "ISO-2 country of manufacture. Part of the distinct-item key for the EU per-item temporary levy.", "maxLength": 2, "type": "string" }, "description": { "maxLength": 200, "minLength": 1, "type": "string" }, "hs_code": { "description": "Harmonized System code. First 6 digits, with description + country_of_manufacture, define a distinct item for the EU per-item temporary levy.", "maxLength": 20, "type": "string" }, "is_cspc": { "description": "EU customs: whether the goods are subject to CSPC regulation. Forwarded to YunExpress (is_cspc).", "type": "boolean" }, "merchant_product_id": { "description": "EU customs: merchant product identifier — your SKU / product code, or the platform ASIN (Amazon). Forwarded to YunExpress (mpid).", "maxLength": 200, "type": "string" }, "mfr_id_nonstd": { "description": "EU customs: non-standardised manufacturer product identifier (model number, batch number, serial number, etc.). Forwarded to YunExpress (nspid).", "maxLength": 200, "type": "string" }, "mfr_id_std": { "description": "EU customs: standardised manufacturer product identifier (EAN/UPC, GTIN, GS1 barcode). Forwarded to YunExpress (spid).", "maxLength": 200, "type": "string" }, "quantity": { "exclusiveMinimum": true, "maximum": 10000, "minimum": 0, "type": "integer" }, "sku": { "description": "Your own SKU / product identifier for this item. Optional, no effect on pricing.", "maxLength": 64, "type": "string" }, "unit_price_hkd": { "maximum": 1000000, "minimum": 0, "type": "number" } }, "required": [ "description", "quantity" ], "type": "object" }, "maxItems": 100, "type": "array" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "type": "object" }, "parcels": { "items": { "additionalProperties": false, "properties": { "height_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" }, "length_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" }, "weight_kg": { "exclusiveMinimum": true, "maximum": 1000, "minimum": 0, "type": "number" }, "width_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" } }, "required": [ "weight_kg" ], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "payment_type": { "default": "prepaid", "enum": [ "prepaid", "cod" ], "type": "string" }, "recipient": { "additionalProperties": false, "properties": { "address": { "maxLength": 500, "minLength": 1, "type": "string" }, "city": { "maxLength": 100, "minLength": 1, "type": "string" }, "contact_name": { "maxLength": 100, "minLength": 1, "type": "string" }, "country_code": { "maxLength": 2, "minLength": 2, "type": "string" }, "district": { "maxLength": 100, "type": "string" }, "phone": { "maxLength": 40, "minLength": 1, "type": "string" }, "postal_code": { "maxLength": 20, "type": "string" } }, "required": [ "contact_name", "phone", "country_code", "city", "address" ], "type": "object" }, "reference_no": { "maxLength": 64, "type": "string" }, "selected_surcharges": { "description": "Opt-in surcharge codes, e.g. [\"SIGNATURE\",\"INSURANCE\"]. Eligibility is per service code + destination — check opt_in_availability on POST /v1/rates first. Signature is carrier-gated (cosmetics line; US priority via a carrier-product switch); on the US priority line signature and insurance are mutually exclusive.", "items": { "maxLength": 64, "type": "string" }, "maxItems": 16, "type": "array" }, "sender": { "additionalProperties": false, "properties": { "address": { "maxLength": 500, "minLength": 1, "type": "string" }, "city": { "maxLength": 100, "minLength": 1, "type": "string" }, "contact_name": { "maxLength": 100, "minLength": 1, "type": "string" }, "country_code": { "maxLength": 2, "minLength": 2, "type": "string" }, "district": { "maxLength": 100, "type": "string" }, "phone": { "maxLength": 40, "minLength": 1, "type": "string" }, "postal_code": { "maxLength": 20, "type": "string" } }, "required": [ "contact_name", "phone", "country_code", "city", "address" ], "type": "object" }, "service_tier_id": { "description": "Service Code to book (e.g. HKASTDGGSTCM) — list the codes your account can use via GET /v1/service_tiers. The wire name service_tier_id is historical and kept for backwards compatibility.", "maxLength": 64, "minLength": 1, "type": "string" }, "tags": { "items": { "maxLength": 64, "type": "string" }, "maxItems": 20, "type": "array" } }, "required": [ "service_tier_id", "recipient", "parcels" ], "type": "object" }, "CreateWebhookRequest": { "additionalProperties": false, "properties": { "description": { "default": "", "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "shipment.created", "shipment.picked_up", "shipment.in_transit", "shipment.out_for_delivery", "shipment.delivered", "shipment.exception", "shipment.returned", "shipment.cancelled", "*" ], "type": "string" }, "maxItems": 32, "minItems": 1, "type": "array" }, "url": { "format": "uri", "maxLength": 2048, "type": "string" } }, "required": [ "url", "events" ], "type": "object" }, "PublicAddressInput": { "additionalProperties": false, "properties": { "address": { "maxLength": 500, "minLength": 1, "type": "string" }, "city": { "maxLength": 100, "minLength": 1, "type": "string" }, "contact_name": { "maxLength": 100, "minLength": 1, "type": "string" }, "country_code": { "maxLength": 2, "minLength": 2, "type": "string" }, "district": { "maxLength": 100, "type": "string" }, "phone": { "maxLength": 40, "minLength": 1, "type": "string" }, "postal_code": { "maxLength": 20, "type": "string" } }, "required": [ "contact_name", "phone", "country_code", "city", "address" ], "type": "object" }, "PublicItemInput": { "additionalProperties": false, "properties": { "country_of_manufacture": { "description": "ISO-2 country of manufacture. Part of the distinct-item key for the EU per-item temporary levy.", "maxLength": 2, "type": "string" }, "description": { "maxLength": 200, "minLength": 1, "type": "string" }, "hs_code": { "description": "Harmonized System code. First 6 digits, with description + country_of_manufacture, define a distinct item for the EU per-item temporary levy.", "maxLength": 20, "type": "string" }, "is_cspc": { "description": "EU customs: whether the goods are subject to CSPC regulation. Forwarded to YunExpress (is_cspc).", "type": "boolean" }, "merchant_product_id": { "description": "EU customs: merchant product identifier — your SKU / product code, or the platform ASIN (Amazon). Forwarded to YunExpress (mpid).", "maxLength": 200, "type": "string" }, "mfr_id_nonstd": { "description": "EU customs: non-standardised manufacturer product identifier (model number, batch number, serial number, etc.). Forwarded to YunExpress (nspid).", "maxLength": 200, "type": "string" }, "mfr_id_std": { "description": "EU customs: standardised manufacturer product identifier (EAN/UPC, GTIN, GS1 barcode). Forwarded to YunExpress (spid).", "maxLength": 200, "type": "string" }, "quantity": { "exclusiveMinimum": true, "maximum": 10000, "minimum": 0, "type": "integer" }, "sku": { "description": "Your own SKU / product identifier for this item. Optional, no effect on pricing.", "maxLength": 64, "type": "string" }, "unit_price_hkd": { "maximum": 1000000, "minimum": 0, "type": "number" } }, "required": [ "description", "quantity" ], "type": "object" }, "PublicParcelInput": { "additionalProperties": false, "properties": { "height_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" }, "length_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" }, "weight_kg": { "exclusiveMinimum": true, "maximum": 1000, "minimum": 0, "type": "number" }, "width_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" } }, "required": [ "weight_kg" ], "type": "object" }, "PublicQuoteResponse": { "additionalProperties": false, "properties": { "available_opt_in_surcharges": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "name_zh": { "type": "string" } }, "required": [ "code", "name_zh", "description" ], "type": "object" }, "type": "array" }, "data": { "items": { "additionalProperties": false, "properties": { "available": { "description": "An option can be returned but not bookable — e.g. a zoned destination without a postal code. When false, see unavailable_reason.", "type": "boolean" }, "carrier": { "additionalProperties": false, "nullable": true, "properties": { "code": { "type": "string" }, "dispatch_mode": { "enum": [ "B2C", "B2B" ], "type": "string" }, "product_code": { "type": "string" } }, "required": [ "code", "product_code", "dispatch_mode" ], "type": "object" }, "eta_days_max": { "nullable": true, "type": "integer" }, "eta_days_min": { "nullable": true, "type": "integer" }, "free_pickup": { "type": "boolean" }, "freight_hkd": { "type": "number" }, "is_standard_service": { "type": "boolean" }, "name": { "additionalProperties": false, "properties": { "en": { "type": "string" }, "zh": { "type": "string" } }, "required": [ "en", "zh" ], "type": "object" }, "opt_in_availability": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "nullable": true, "type": "string" }, "selectable": { "type": "boolean" } }, "required": [ "code", "selectable", "reason" ], "type": "object" }, "type": "array" }, "product_code": { "description": "Merdi product container the service code belongs to (entitlement unit, e.g. HKASTD). null on legacy tiers. NOT the carrier's product code — see carrier.product_code.", "nullable": true, "type": "string" }, "rate_table_code": { "type": "string" }, "rate_table_version": { "type": "integer" }, "reg_fee_hkd": { "type": "number" }, "service_options": { "items": { "additionalProperties": false, "properties": { "is_vas": { "type": "boolean" }, "label_zh": { "type": "string" }, "layer_key": { "type": "string" }, "option_code": { "type": "string" } }, "required": [ "layer_key", "option_code", "label_zh", "is_vas" ], "type": "object" }, "type": "array" }, "service_tier_id": { "type": "string" }, "supports_cod": { "type": "boolean" }, "surcharge_conflicts": { "description": "Selected opt-in surcharges that could NOT be applied to this option (e.g. insurance after the US-priority signature carrier switch).", "items": { "type": "string" }, "type": "array" }, "surcharges": { "items": { "additionalProperties": false, "properties": { "amount_hkd": { "type": "number" }, "basis": { "description": "Human-readable explanation of how the surcharge was computed.", "type": "string" }, "code": { "type": "string" }, "is_estimate": { "type": "boolean" }, "name_zh": { "type": "string" } }, "required": [ "code", "name_zh", "amount_hkd", "is_estimate", "basis" ], "type": "object" }, "type": "array" }, "total_hkd": { "type": "number" }, "unavailable_reason": { "nullable": true, "type": "string" }, "zone": { "description": "Pricing zone for zoned destinations (AU Z1/Z2/Z3). null unless the destination is zoned AND destination_postal_code resolved a zone.", "nullable": true, "type": "string" } }, "required": [ "service_tier_id", "name", "eta_days_min", "eta_days_max", "free_pickup", "supports_cod", "freight_hkd", "reg_fee_hkd", "surcharges", "total_hkd", "rate_table_code", "rate_table_version", "zone", "product_code", "is_standard_service", "service_options", "available", "unavailable_reason", "opt_in_availability", "surcharge_conflicts", "carrier" ], "type": "object" }, "type": "array" }, "ioss_notice": { "additionalProperties": false, "nullable": true, "properties": { "cap_exceeded": { "type": "boolean" }, "declared_cap_hkd": { "nullable": true, "type": "number" }, "eu_ioss_country": { "type": "boolean" }, "using_ioss": { "type": "boolean" }, "vat_hint": { "nullable": true, "type": "string" } }, "required": [ "eu_ioss_country", "using_ioss", "vat_hint", "declared_cap_hkd", "cap_exceeded" ], "type": "object" } }, "required": [ "data", "available_opt_in_surcharges", "ioss_notice" ], "type": "object" }, "PublicRateOption": { "additionalProperties": false, "properties": { "available": { "description": "An option can be returned but not bookable — e.g. a zoned destination without a postal code. When false, see unavailable_reason.", "type": "boolean" }, "carrier": { "additionalProperties": false, "nullable": true, "properties": { "code": { "type": "string" }, "dispatch_mode": { "enum": [ "B2C", "B2B" ], "type": "string" }, "product_code": { "type": "string" } }, "required": [ "code", "product_code", "dispatch_mode" ], "type": "object" }, "eta_days_max": { "nullable": true, "type": "integer" }, "eta_days_min": { "nullable": true, "type": "integer" }, "free_pickup": { "type": "boolean" }, "freight_hkd": { "type": "number" }, "is_standard_service": { "type": "boolean" }, "name": { "additionalProperties": false, "properties": { "en": { "type": "string" }, "zh": { "type": "string" } }, "required": [ "en", "zh" ], "type": "object" }, "opt_in_availability": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "nullable": true, "type": "string" }, "selectable": { "type": "boolean" } }, "required": [ "code", "selectable", "reason" ], "type": "object" }, "type": "array" }, "product_code": { "description": "Merdi product container the service code belongs to (entitlement unit, e.g. HKASTD). null on legacy tiers. NOT the carrier's product code — see carrier.product_code.", "nullable": true, "type": "string" }, "rate_table_code": { "type": "string" }, "rate_table_version": { "type": "integer" }, "reg_fee_hkd": { "type": "number" }, "service_options": { "items": { "additionalProperties": false, "properties": { "is_vas": { "type": "boolean" }, "label_zh": { "type": "string" }, "layer_key": { "type": "string" }, "option_code": { "type": "string" } }, "required": [ "layer_key", "option_code", "label_zh", "is_vas" ], "type": "object" }, "type": "array" }, "service_tier_id": { "type": "string" }, "supports_cod": { "type": "boolean" }, "surcharge_conflicts": { "description": "Selected opt-in surcharges that could NOT be applied to this option (e.g. insurance after the US-priority signature carrier switch).", "items": { "type": "string" }, "type": "array" }, "surcharges": { "items": { "additionalProperties": false, "properties": { "amount_hkd": { "type": "number" }, "basis": { "description": "Human-readable explanation of how the surcharge was computed.", "type": "string" }, "code": { "type": "string" }, "is_estimate": { "type": "boolean" }, "name_zh": { "type": "string" } }, "required": [ "code", "name_zh", "amount_hkd", "is_estimate", "basis" ], "type": "object" }, "type": "array" }, "total_hkd": { "type": "number" }, "unavailable_reason": { "nullable": true, "type": "string" }, "zone": { "description": "Pricing zone for zoned destinations (AU Z1/Z2/Z3). null unless the destination is zoned AND destination_postal_code resolved a zone.", "nullable": true, "type": "string" } }, "required": [ "service_tier_id", "name", "eta_days_min", "eta_days_max", "free_pickup", "supports_cod", "freight_hkd", "reg_fee_hkd", "surcharges", "total_hkd", "rate_table_code", "rate_table_version", "zone", "product_code", "is_standard_service", "service_options", "available", "unavailable_reason", "opt_in_availability", "surcharge_conflicts", "carrier" ], "type": "object" }, "PublicServiceTier": { "additionalProperties": false, "properties": { "carrier": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "dispatch_mode": { "enum": [ "B2C", "B2B" ], "type": "string" }, "product_code": { "type": "string" } }, "required": [ "code", "product_code", "dispatch_mode" ], "type": "object" }, "delivery_mode": { "enum": [ "resell", "imile" ], "type": "string" }, "destination_countries": { "items": { "type": "string" }, "type": "array" }, "eta_days_max": { "type": "integer" }, "eta_days_min": { "type": "integer" }, "id": { "type": "string" }, "is_standard_service": { "description": "True on the default standard line (currently HKASTDGGSTCM).", "type": "boolean" }, "name": { "additionalProperties": false, "properties": { "en": { "type": "string" }, "zh_hk": { "nullable": true, "type": "string" } }, "required": [ "en", "zh_hk" ], "type": "object" }, "origin_countries": { "items": { "type": "string" }, "type": "array" }, "product_code": { "description": "Merdi product container the service code belongs to (the entitlement unit, e.g. HKASTD). null on legacy tiers that predate pricing-model v2. NOT the same thing as carrier.product_code — that is the upstream carrier's own reference.", "nullable": true, "type": "string" }, "service_options": { "description": "The code's dimensions: cargo_type (GG/CS) × air_service (ST/PR) × tail_service (CM/PS). Empty on legacy tiers.", "items": { "additionalProperties": false, "properties": { "is_vas": { "type": "boolean" }, "label_zh": { "type": "string" }, "layer_key": { "type": "string" }, "option_code": { "type": "string" } }, "required": [ "layer_key", "option_code", "label_zh", "is_vas" ], "type": "object" }, "type": "array" }, "standard_for_countries": { "description": "Destination countries (ISO alpha-2) for which this code is the per-country standard. Absent ⇒ use is_standard_service.", "items": { "type": "string" }, "type": "array" }, "status": { "type": "string" } }, "required": [ "id", "name", "product_code", "is_standard_service", "service_options", "origin_countries", "destination_countries", "eta_days_min", "eta_days_max", "delivery_mode", "status", "carrier" ], "type": "object" }, "PublicShipmentCancelResponse": { "additionalProperties": false, "properties": { "cancelled_at": { "type": "string" }, "id": { "type": "string" }, "refund_hkd": { "description": "0 on idempotent replay or in test mode.", "type": "number" }, "status": { "enum": [ "cancelled" ], "type": "string" }, "tracking_number": { "type": "string" } }, "required": [ "id", "tracking_number", "status", "cancelled_at", "refund_hkd" ], "type": "object" }, "PublicShipmentCreateResponse": { "additionalProperties": false, "properties": { "created_at": { "type": "string" }, "dispatch": { "additionalProperties": false, "nullable": true, "properties": { "carrier_code": { "nullable": true, "type": "string" }, "error": { "nullable": true, "type": "string" }, "label_pdf_url": { "nullable": true, "type": "string" }, "status": { "type": "string" }, "waybill_number": { "nullable": true, "type": "string" } }, "required": [ "status", "carrier_code", "waybill_number", "label_pdf_url", "error" ], "type": "object" }, "id": { "description": "Tracking number — public-facing canonical id.", "type": "string" }, "livemode": { "type": "boolean" }, "parcels": { "items": { "additionalProperties": false, "properties": { "height_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" }, "length_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" }, "weight_kg": { "exclusiveMinimum": true, "maximum": 1000, "minimum": 0, "type": "number" }, "width_cm": { "exclusiveMinimum": true, "maximum": 500, "minimum": 0, "type": "number" } }, "required": [ "weight_kg" ], "type": "object" }, "type": "array" }, "pricing_snapshot": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "freight_hkd": { "type": "number" }, "rate_table_code": { "type": "string" }, "rate_table_version": { "type": "integer" }, "reg_fee_hkd": { "type": "number" }, "surcharges": { "items": { "additionalProperties": false, "properties": { "amount_hkd": { "type": "number" }, "code": { "type": "string" } }, "required": [ "code", "amount_hkd" ], "type": "object" }, "type": "array" }, "total_hkd": { "type": "number" } }, "required": [ "freight_hkd", "reg_fee_hkd", "surcharges", "total_hkd", "currency", "rate_table_code", "rate_table_version" ], "type": "object" }, "recipient": { "additionalProperties": false, "properties": { "address": { "maxLength": 500, "minLength": 1, "type": "string" }, "city": { "maxLength": 100, "minLength": 1, "type": "string" }, "contact_name": { "maxLength": 100, "minLength": 1, "type": "string" }, "country_code": { "maxLength": 2, "minLength": 2, "type": "string" }, "district": { "maxLength": 100, "type": "string" }, "phone": { "maxLength": 40, "minLength": 1, "type": "string" }, "postal_code": { "maxLength": 20, "type": "string" } }, "required": [ "contact_name", "phone", "country_code", "city", "address" ], "type": "object" }, "reference_no": { "nullable": true, "type": "string" }, "sender": { "additionalProperties": false, "nullable": true, "properties": { "address": { "maxLength": 500, "minLength": 1, "type": "string" }, "city": { "maxLength": 100, "minLength": 1, "type": "string" }, "contact_name": { "maxLength": 100, "minLength": 1, "type": "string" }, "country_code": { "maxLength": 2, "minLength": 2, "type": "string" }, "district": { "maxLength": 100, "type": "string" }, "phone": { "maxLength": 40, "minLength": 1, "type": "string" }, "postal_code": { "maxLength": 20, "type": "string" } }, "required": [ "contact_name", "phone", "country_code", "city", "address" ], "type": "object" }, "service_tier_id": { "type": "string" }, "status": { "type": "string" }, "tracking_number": { "type": "string" } }, "required": [ "id", "tracking_number", "status", "service_tier_id", "livemode", "reference_no", "recipient", "sender", "parcels", "pricing_snapshot", "dispatch", "created_at" ], "type": "object" }, "PublicShipmentDetail": { "additionalProperties": false, "properties": { "carrier_code": { "nullable": true, "type": "string" }, "created_at": { "type": "string" }, "delivered_at": { "nullable": true, "type": "string" }, "destination": { "additionalProperties": false, "properties": { "country": { "nullable": true, "type": "string" }, "district": { "nullable": true, "type": "string" } }, "required": [ "country", "district" ], "type": "object" }, "dispatch_status": { "nullable": true, "type": "string" }, "events": { "items": { "additionalProperties": false, "properties": { "carrier_code": { "type": "string" }, "carrier_name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "event_at": { "description": "Event timestamp (ISO 8601).", "type": "string" }, "location": { "nullable": true, "type": "string" }, "status_label": { "description": "Human-friendly status label.", "type": "string" } }, "required": [ "event_at", "location", "description", "status_label", "carrier_code", "carrier_name" ], "type": "object" }, "type": "array" }, "id": { "description": "Tracking number — public-facing canonical id.", "type": "string" }, "label_pdf_url": { "description": "Carrier label PDF URL. Populated by the Phase 5 dispatch step (LIVE-mode only — test-mode shipments skip dispatch). Polling GET /api/v1/shipments/{id} after a synchronous POST /api/v1/shipments is the canonical 'wait for label' pattern. Once non-null, fetch directly (no Authorization required — presigned OSS).", "nullable": true, "type": "string" }, "last_mile_tracking_number": { "description": "Final-mile carrier tracking number (e.g. USPS), populated once the upstream carrier hands the parcel to the last-mile carrier and our fee-puller learns the number. THIS is typically the number to push to marketplaces (eBay/Amazon) + show the buyer, since it's recognised by the delivering carrier's own tracker. Null until the last-mile leg is assigned.", "nullable": true, "type": "string" }, "livemode": { "type": "boolean" }, "service_tier": { "nullable": true, "type": "string" }, "status": { "enum": [ "draft", "label_created", "picked_up", "in_transit", "out_for_delivery", "delivered", "exception", "cancelled", "returned" ], "type": "string" }, "waybill_number": { "description": "First-leg carrier waybill assigned at dispatch (e.g. Yun Express `YT…`). Distinct from `id` (our canonical Merdi number) and from `last_mile_tracking_number` (the final-mile carrier).", "nullable": true, "type": "string" } }, "required": [ "id", "status", "service_tier", "destination", "carrier_code", "dispatch_status", "label_pdf_url", "waybill_number", "last_mile_tracking_number", "livemode", "created_at", "delivered_at", "events" ], "type": "object" }, "PublicShipmentDispatch": { "additionalProperties": false, "properties": { "carrier_code": { "nullable": true, "type": "string" }, "error": { "nullable": true, "type": "string" }, "label_pdf_url": { "nullable": true, "type": "string" }, "status": { "type": "string" }, "waybill_number": { "nullable": true, "type": "string" } }, "required": [ "status", "carrier_code", "waybill_number", "label_pdf_url", "error" ], "type": "object" }, "PublicShipmentEvent": { "additionalProperties": false, "properties": { "carrier_code": { "type": "string" }, "carrier_name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "event_at": { "description": "Event timestamp (ISO 8601).", "type": "string" }, "location": { "nullable": true, "type": "string" }, "status_label": { "description": "Human-friendly status label.", "type": "string" } }, "required": [ "event_at", "location", "description", "status_label", "carrier_code", "carrier_name" ], "type": "object" }, "PublicShipmentListResponse": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "created_at": { "type": "string" }, "delivered_at": { "nullable": true, "type": "string" }, "destination_country": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "livemode": { "type": "boolean" }, "service_tier": { "nullable": true, "type": "string" }, "status": { "enum": [ "draft", "label_created", "picked_up", "in_transit", "out_for_delivery", "delivered", "exception", "cancelled", "returned" ], "type": "string" } }, "required": [ "id", "status", "service_tier", "destination_country", "livemode", "created_at", "delivered_at" ], "type": "object" }, "type": "array" }, "next_cursor": { "nullable": true, "type": "string" } }, "required": [ "data", "next_cursor" ], "type": "object" }, "PublicShipmentSummary": { "additionalProperties": false, "properties": { "created_at": { "type": "string" }, "delivered_at": { "nullable": true, "type": "string" }, "destination_country": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "livemode": { "type": "boolean" }, "service_tier": { "nullable": true, "type": "string" }, "status": { "enum": [ "draft", "label_created", "picked_up", "in_transit", "out_for_delivery", "delivered", "exception", "cancelled", "returned" ], "type": "string" } }, "required": [ "id", "status", "service_tier", "destination_country", "livemode", "created_at", "delivered_at" ], "type": "object" }, "PublicWalletBalance": { "additionalProperties": false, "properties": { "available": { "description": "Spendable balance = balance minus the sum of open holds. The order-create gate rejects new shipments that would push this below zero.", "type": "number" }, "balance": { "description": "Raw wallet balance. Can go negative after settle if the carrier's recomputed fee exceeds the frozen quote.", "type": "number" }, "currency": { "description": "ISO 4217 wallet currency. Defaults to HKD.", "type": "string" }, "held": { "description": "Funds reserved by open holds against in-flight shipments (balance minus available).", "type": "number" } }, "required": [ "balance", "available", "held", "currency" ], "type": "object" }, "PublicWebhook": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "consecutive_failures": { "minimum": 0, "type": "integer" }, "created_at": { "type": "string" }, "description": { "type": "string" }, "disabled_at": { "nullable": true, "type": "string" }, "events": { "items": { "enum": [ "shipment.created", "shipment.picked_up", "shipment.in_transit", "shipment.out_for_delivery", "shipment.delivered", "shipment.exception", "shipment.returned", "shipment.cancelled", "*" ], "type": "string" }, "type": "array" }, "id": { "type": "string" }, "last_delivery_at": { "nullable": true, "type": "string" }, "livemode": { "type": "boolean" }, "secret_last4": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "events", "description", "active", "livemode", "secret_last4", "created_at", "last_delivery_at", "consecutive_failures", "disabled_at" ], "type": "object" }, "PublicWebhookCreateResponse": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "consecutive_failures": { "minimum": 0, "type": "integer" }, "created_at": { "type": "string" }, "description": { "type": "string" }, "disabled_at": { "nullable": true, "type": "string" }, "events": { "items": { "enum": [ "shipment.created", "shipment.picked_up", "shipment.in_transit", "shipment.out_for_delivery", "shipment.delivered", "shipment.exception", "shipment.returned", "shipment.cancelled", "*" ], "type": "string" }, "type": "array" }, "id": { "type": "string" }, "last_delivery_at": { "nullable": true, "type": "string" }, "livemode": { "type": "boolean" }, "secret": { "description": "Plaintext signing secret — returned ONLY in the POST /api/v1/webhooks response and the rotate response. List + detail + test endpoints never include this. Capture it at creation; rotation requires POST /api/v1/webhooks/{id}/rotate.", "type": "string" }, "secret_last4": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "events", "description", "active", "livemode", "secret_last4", "created_at", "last_delivery_at", "consecutive_failures", "disabled_at", "secret" ], "type": "object" }, "PublicWebhookDelivery": { "additionalProperties": false, "properties": { "attempt_count": { "minimum": 0, "type": "integer" }, "completed_at": { "nullable": true, "type": "string" }, "created_at": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "enum": [ "shipment.created", "shipment.picked_up", "shipment.in_transit", "shipment.out_for_delivery", "shipment.delivered", "shipment.exception", "shipment.returned", "shipment.cancelled" ], "type": "string" }, "id": { "type": "string" }, "response": { "additionalProperties": false, "nullable": true, "properties": { "body_excerpt": { "type": "string" }, "duration_ms": { "type": "integer" }, "status": { "type": "integer" } }, "required": [ "status", "body_excerpt", "duration_ms" ], "type": "object" }, "state": { "enum": [ "pending", "delivered", "failed" ], "type": "string" }, "webhook_endpoint_id": { "type": "string" } }, "required": [ "id", "webhook_endpoint_id", "event_type", "event_id", "state", "attempt_count", "response", "created_at", "completed_at" ], "type": "object" }, "QuoteRequest": { "additionalProperties": false, "properties": { "cod": { "type": "boolean" }, "declared_value_hkd": { "maximum": 10000000, "minimum": 0, "type": "number" }, "destination_country": { "maxLength": 2, "minLength": 2, "type": "string" }, "destination_postal_code": { "description": "Destination postal code. Required for accurate zoned pricing (AU Z1/Z2/Z3) — without it, zoned options return available=false with a reason.", "maxLength": 20, "type": "string" }, "goods_category": { "maxLength": 64, "minLength": 1, "type": "string" }, "selected_surcharges": { "items": { "maxLength": 64, "type": "string" }, "maxItems": 16, "type": "array" }, "weight_kg": { "exclusiveMinimum": true, "maximum": 1000, "minimum": 0, "type": "number" } }, "required": [ "weight_kg", "destination_country", "goods_category" ], "type": "object" }, "ShipmentDetail": { "allOf": [ { "$ref": "#/components/schemas/ShipmentSummary" }, { "properties": { "carrier_code": { "nullable": true, "type": "string" }, "destination": { "properties": { "country": { "nullable": true, "type": "string" }, "district": { "nullable": true, "type": "string" } }, "type": "object" }, "dispatch_status": { "nullable": true, "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/TrackingEvent" }, "type": "array" }, "label_pdf_url": { "description": "Carrier label PDF — presigned URL, no Authorization header required. Populated by the Phase 5 dispatch step (LIVE-mode only; test-mode shipments stay null). Poll GET /v1/shipments/{id} after a synchronous create until this is non-null.", "format": "uri", "nullable": true, "type": "string" }, "last_mile_tracking_number": { "description": "Final-mile carrier tracking number (e.g. USPS), populated once the upstream carrier hands off to the last-mile carrier. Typically the number to push to marketplaces (eBay/Amazon) + show the buyer. Null until the last-mile leg is assigned.", "nullable": true, "type": "string" }, "waybill_number": { "description": "Carrier-side waybill / tracking ID assigned at dispatch. Distinct from the canonical Merdi tracking_number — this is what shows on the carrier's own tracker (Yun Express, etc.).", "nullable": true, "type": "string" } }, "type": "object" } ] }, "ShipmentStatus": { "enum": [ "draft", "label_created", "picked_up", "in_transit", "out_for_delivery", "delivered", "exception", "cancelled", "returned" ], "type": "string" }, "ShipmentSummary": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "format": "date-time", "nullable": true, "type": "string" }, "destination_country": { "nullable": true, "type": "string" }, "id": { "description": "Tracking number — public-facing canonical id.", "type": "string" }, "livemode": { "type": "boolean" }, "service_tier": { "nullable": true, "type": "string" }, "status": { "$ref": "#/components/schemas/ShipmentStatus" } }, "type": "object" }, "TrackingEvent": { "properties": { "carrier_code": { "type": "string" }, "carrier_name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "event_at": { "format": "date-time", "type": "string" }, "location": { "nullable": true, "type": "string" }, "status_label": { "type": "string" } }, "type": "object" }, "Webhook": { "properties": { "active": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "disabled_at": { "format": "date-time", "nullable": true, "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": "array" }, "id": { "type": "string" }, "last_delivery_at": { "format": "date-time", "nullable": true, "type": "string" }, "livemode": { "type": "boolean" }, "secret_last4": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "WebhookCreateResponse": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "secret": { "description": "Plaintext signing secret — shown EXACTLY ONCE in this response. Capture it; no recovery path.", "type": "string" } }, "required": [ "secret" ], "type": "object" } ] }, "WebhookDelivery": { "properties": { "attempt_count": { "type": "integer" }, "completed_at": { "format": "date-time", "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "event_id": { "type": "string" }, "event_type": { "$ref": "#/components/schemas/WebhookEvent" }, "id": { "type": "string" }, "response": { "nullable": true, "properties": { "body_excerpt": { "type": "string" }, "duration_ms": { "type": "integer" }, "status": { "type": "integer" } }, "type": "object" }, "state": { "enum": [ "pending", "delivered", "failed" ], "type": "string" }, "webhook_endpoint_id": { "type": "string" } }, "type": "object" }, "WebhookEvent": { "enum": [ "shipment.created", "shipment.picked_up", "shipment.in_transit", "shipment.out_for_delivery", "shipment.delivered", "shipment.exception", "shipment.returned", "shipment.cancelled", "*" ], "type": "string" }, "WebhookEventEnvelope": { "additionalProperties": false, "description": "Webhook event envelope — the JSON body POSTed to subscribed receiver URLs. Verify the X-Merdi-Signature header (t=,v1=) against the raw body before trusting it.", "properties": { "created_at": { "description": "Event creation timestamp (ISO 8601).", "type": "string" }, "data": { "additionalProperties": {}, "description": "Per-event data bag. Always includes tracking_number and status; additional fields vary by event type (e.g. delivered_at on shipment.delivered).", "type": "object" }, "event_id": { "description": "Unique id for this event delivery (UUID). Also echoed in the X-Merdi-Event-Id header; use it to dedupe redelivered events.", "type": "string" }, "event_type": { "description": "Concrete event type. A delivered event always has one specific type — never the subscription wildcard '*'. Also echoed in the X-Merdi-Event-Type header.", "enum": [ "shipment.created", "shipment.picked_up", "shipment.in_transit", "shipment.out_for_delivery", "shipment.delivered", "shipment.exception", "shipment.returned", "shipment.cancelled" ], "type": "string" }, "livemode": { "description": "True for live-mode events, false for test-mode events.", "type": "boolean" } }, "required": [ "event_id", "event_type", "livemode", "created_at", "data" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "Bearer token in the Authorization header. mk_live_* for production data, mk_test_* for sandbox. Mint via the admin issuance script (Phase D adds self-serve).", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "name": "Merdi Express", "url": "https://merdiexpress.com" }, "description": "B2B public API for tracking, orders, service tiers, and webhook subscriptions. Stripe-style Bearer auth + Idempotency-Key on mutating endpoints + per-key rate limiting (100 req/sec, 10000 req/day default). \n\nBASE URL: every endpoint is served from `https://merdiexpress.com/api/v1/`. The `/api/v1` prefix is embedded in every path key (so SDK generators that ignore the `servers` field still produce correct URLs). For convenience, requests to `https://merdiexpress.com/v1/*` are 308-redirected to `https://merdiexpress.com/api/v1/*` — but please update any base URL config to the canonical `/api/v1/` form.\n\nSee https://merdiexpress.com/developers for docs + key issuance.", "title": "Merdi Express Public API", "version": "1.1.0" }, "openapi": "3.0.3", "paths": { "/api/v1/countries": { "get": { "responses": { "200": { "$ref": "#/components/responses/CountryList" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "summary": "List supported destination countries", "tags": [ "reference" ] } }, "/api/v1/rates": { "post": { "description": "Quotes are entitlement-scoped: options come from the Service Codes your account can book — resolved from BOTH entitlement tracks (Product Code entitlements and assigned rate cards) — and each option carries the pricing-model v2 metadata (product_code, service_options, is_standard_service). Zoned destinations (currently AU) price by postal-code zone: supply destination_postal_code, or zoned options come back available=false with unavailable_reason. Opt-in surcharges (e.g. SIGNATURE, INSURANCE) can be passed in selected_surcharges; per-option eligibility is returned in opt_in_availability and surcharges that could not be applied are listed in surcharge_conflicts. EU destinations include an ioss_notice block showing the VAT-prepay picture without IOSS — IOSS itself is applied at shipment create (ioss_number / account default), so using_ioss is always false here. Engine rejections return 400 INVALID_FIELD whose message is the engine's actual reason; data.field classifies it — rate_card (entitlement / pricing setup; also the fallback), declared_value_hkd (destination declared-value cap), parcels (size over carrier limit) — and data.errors lists every reason.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/RateQuotes" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Get rate quotes", "tags": [ "rates" ] } }, "/api/v1/service_tiers": { "get": { "description": "Entitlement-scoped (2026-06-10): returns only the Service Codes the calling account can book — resolved from BOTH entitlement tracks (Product Code entitlements and assigned rate cards) — and that have a carrier assignment (fulfillable), the same rule the quote engine applies. No entitlements yet → 200 with an empty list (ask your account manager to assign a Product Code). Each tier carries the pricing-model v2 fields: product_code (the Merdi product container / entitlement unit, e.g. HKASTD — null on legacy tiers, and NOT the same thing as carrier.product_code, which is the upstream carrier's own reference), is_standard_service, and service_options (the cargo / air / last-mile dimensions).", "parameters": [ { "description": "Filter by carrier dispatch mode.", "in": "query", "name": "dispatch_mode", "schema": { "enum": [ "B2C", "B2B" ], "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/ServiceTierList" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "List service tiers the account can use", "tags": [ "service_tiers" ] } }, "/api/v1/shipments": { "get": { "description": "Cursor-based pagination. Filters: status, updated_after. Slim list-view shape — call /v1/shipments/{id} for full detail with events.", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous response's next_cursor field.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/ShipmentStatus" } }, { "in": "query", "name": "updated_after", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/ShipmentListPage" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "List the authenticated account's shipments", "tags": [ "shipments" ] }, "post": { "description": "Re-quotes the selected service tier server-side, deducts the wallet in live mode (test mode skips), dispatches to the carrier, and returns the full shipment record with pricing snapshot + dispatch result. Requires Idempotency-Key. service_tier_id takes a Service Code (e.g. HKASTDGGSTCM) — list yours via GET /v1/service_tiers. Optional selected_surcharges opts into SIGNATURE / INSURANCE where eligible (check opt_in_availability on POST /v1/rates; on the US priority line signature and insurance are mutually exclusive). Optional ioss_number (IM + 10 digits) overrides the account-level IOSS default for this shipment; EU destinations only.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentRequest" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/ShipmentCreated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Create a shipment", "tags": [ "shipments" ] } }, "/api/v1/shipments/{shipment_id}": { "get": { "description": "shipment_id accepts the tracking number. Filters by clientId + livemode — your shipment only. Distinct from GET /v1/tracking/{tn} which is intentionally broader (tracking-widget use case).", "parameters": [ { "in": "path", "name": "shipment_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/ShipmentDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Get detail for a single shipment", "tags": [ "shipments" ] } }, "/api/v1/shipments/{shipment_id}/cancel": { "post": { "description": "Only `label_created` (and `draft` if any exist) are cancellable; anything past first carrier scan returns 400 INVALID_FIELD(status). Idempotent — cancel-then-cancel returns the existing snapshot with `refund_hkd=0`. Live mode refunds the wallet by the original total; test mode does not (test create skipped the deduction).", "parameters": [ { "in": "path", "name": "shipment_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "$ref": "#/components/responses/ShipmentCancelled" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Cancel a pre-pickup shipment", "tags": [ "shipments" ] } }, "/api/v1/tracking/{tracking_number}": { "get": { "description": "Returns the public tracking projection (status, destination country/district, event timeline) for the given tracking number. Authenticated but NOT clientId-scoped — any valid Bearer key can look up any tracking number (rate-limit applies). Designed for B2B clients to power their own tracking pages.", "parameters": [ { "$ref": "#/components/parameters/TrackingNumberPath" } ], "responses": { "200": { "$ref": "#/components/responses/TrackingDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Get tracking information for a shipment", "tags": [ "tracking" ] } }, "/api/v1/wallet/balance": { "get": { "description": "Read the authenticated account's prepaid wallet balance. Poll to monitor funds proactively: because shipment creation is gated on `available`, POST /api/v1/shipments can start rejecting on insufficient funds the instant available dips below the next quote. `held` = open holds against in-flight shipments; `available` = `balance` - `held`. Read-only; no Idempotency-Key.", "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiReturn" }, { "properties": { "data": { "$ref": "#/components/schemas/PublicWalletBalance" } }, "type": "object" } ] } } }, "description": "Current wallet balance." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Get wallet balance", "tags": [ "wallet" ] } }, "/api/v1/webhooks": { "get": { "responses": { "200": { "$ref": "#/components/responses/WebhookList" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "List the account's webhook endpoints", "tags": [ "webhooks" ] }, "post": { "description": "Returns the plaintext signing secret EXACTLY ONCE in the response.secret field. Capture it; no recovery path — rotation = delete + recreate. Requires Idempotency-Key header.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/WebhookCreated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Register a webhook endpoint", "tags": [ "webhooks" ] } }, "/api/v1/webhooks/{webhook_id}": { "delete": { "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "$ref": "#/components/responses/WebhookRevoked" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Revoke a webhook endpoint", "tags": [ "webhooks" ] } }, "/api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver": { "post": { "description": "Re-fires the ORIGINAL event_id + event_type + payload to the endpoint and returns the NEW delivery record. The stable event_id lets a well-behaved receiver dedupe this redeliver against the original attempt. Manual debug action (sibling to test-fire); Idempotency-Key not required.", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/WebhookDeliveryRecord" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Re-send a previously-failed webhook delivery", "tags": [ "webhooks" ] } }, "/api/v1/webhooks/{webhook_id}/rotate": { "post": { "description": "Generates a fresh whsec_* signing secret and replaces the encrypted blob on the endpoint doc. The new plaintext secret is returned EXACTLY ONCE — capture it. Endpoint id, url, events, and delivery history are preserved. Recommended pattern: customer accepts both old + new secrets for a brief overlap window while in-flight deliveries drain.", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/WebhookSecretRotated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Rotate a webhook signing secret", "tags": [ "webhooks" ] } }, "/api/v1/webhooks/{webhook_id}/sample": { "get": { "description": "Returns a fully-signed sample webhook event WITHOUT delivering it anywhere. The killer feature for integrators on private staging / localhost / CI that can't receive inbound webhooks: feed the returned `raw_body` + `X-Merdi-Signature` straight into your receiver's verification code and confirm — before production — that your HMAC check accepts a real Merdi signature. IMPORTANT: verify against `raw_body` exactly as returned, NOT a re-serialized object (JSON key order / whitespace changes the HMAC input).", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/WebhookSignedSample" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Get a signed sample event (no delivery)", "tags": [ "webhooks" ] } }, "/api/v1/webhooks/{webhook_id}/test": { "post": { "description": "Sends a fully-signed shipment.delivered event with payload.is_test=true. Returns the WebhookDelivery record (status code, body excerpt, latency) so you can confirm your receiver handled it.", "parameters": [ { "in": "path", "name": "webhook_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/WebhookDeliveryRecord" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "summary": "Fire a synthetic test event to a webhook endpoint", "tags": [ "webhooks" ] } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "description": "Production — endpoints live under /api/v1/* (the /api/v1 prefix is embedded in every path key so parsers that ignore the `servers` field still resolve to the correct URL).", "url": "https://merdiexpress.com" } ], "tags": [ { "description": "Track shipments by tracking number.", "name": "tracking" }, { "description": "List + look up the authenticated account's shipments.", "name": "shipments" }, { "description": "Available shipping service tiers + their assigned carriers.", "name": "service_tiers" }, { "description": "Webhook subscription + test fire.", "name": "webhooks" }, { "description": "Rate quotes (placeholder — coming with the Phase 4 billing engine).", "name": "rates" }, { "description": "Reference data (countries).", "name": "reference" }, { "description": "Prepaid wallet balance.", "name": "wallet" } ] }