shipping_cost_estimate
Estimate domestic or international shipping cost, chargeable weight, transit time and common shipping surcharges using shipment dimensions, weight, origin, destination and service level. Estimates are not guaranteed carrier quotes; duties and taxes are excluded.
When to use
Use when an agent needs to estimate delivery cost for a physical shipment before purchasing, selling, importing, exporting or selecting a shipping option.
Selection guidance
Role: primary. route and shipment cost estimation; chargeable-weight planning; choosing a service level
Not for: customs or tax determination; a guaranteed carrier quote; vehicle valuation
Use cases
- international shipping estimate
- domestic shipping estimate
- calculate volumetric weight
- compare shipping options
- ecommerce shipping
- freight planning
- procurement logistics
- marketplace delivery cost
Access
- REST:
POST https://api.rafidsystem.com/api/v1/logistics/shipping-cost-estimate - x402:
POST https://api.rafidsystem.com/api/v1/x402/logistics/shipping-cost-estimate - MCP tool:
shipping_cost_estimate - Free preview:
POST https://api.rafidsystem.com/api/v1/preview/shipping_cost_estimate
Price: $0.25 USD per call. Payment options are deployment-configured; inspect /api/v1/payment-methods. Prices and payment semantics are unchanged from the canonical registry.
Example input
{
"origin": {
"country": "CN",
"postalCode": "518000",
"city": "Shenzhen"
},
"destination": {
"country": "OM",
"postalCode": "100",
"city": "Muscat"
},
"shipment": {
"weightKg": 8,
"lengthCm": 45,
"widthCm": 35,
"heightCm": 30,
"quantity": 1
},
"shippingMode": "air",
"serviceLevel": "standard",
"currency": "USD"
}Example output
{
"estimatedCost": {
"min": 55,
"max": 78,
"currency": "USD"
},
"recommendedEstimate": 66.5,
"actualWeightKg": 8,
"volumetricWeightKg": 9.45,
"chargeableWeightKg": 9.45,
"shippingMode": "air",
"serviceLevel": "standard",
"estimatedTransitDays": {
"min": 4,
"max": 8
},
"costBreakdown": {
"baseFreight": 48,
"fuelSurcharge": 9,
"handling": 6,
"remoteAreaSurcharge": 0,
"oversizeSurcharge": 0,
"estimatedOtherFees": 4
},
"rateSource": "heuristic_estimate",
"provider": null,
"dutiesAndTaxes": {
"included": false,
"estimatedAmount": null,
"note": "Import duties and taxes are not included in the shipping estimate."
},
"confidence": {
"level": "low",
"reason": "Illustrative heuristic data; no live carrier quote or configured internal route rate is assumed."
},
"assumptions": [
"Illustrative example only; no live carrier quote."
],
"riskFlags": [
{
"code": "HEURISTIC_ESTIMATE",
"severity": "medium",
"message": "This is a heuristic estimate, not an official carrier quote."
}
],
"options": [],
"recommendedOptionReason": null,
"generatedAt": "2026-01-01T00:00:00.000Z"
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"origin": {
"type": "object",
"properties": {
"country": {
"type": "string",
"minLength": 1,
"maxLength": 2
},
"postalCode": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"city": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"country"
],
"additionalProperties": false
},
"destination": {
"type": "object",
"properties": {
"country": {
"type": "string",
"minLength": 1,
"maxLength": 2
},
"postalCode": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"city": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"country"
],
"additionalProperties": false
},
"shipment": {
"type": "object",
"properties": {
"weightKg": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100000
},
"lengthCm": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1000
},
"widthCm": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1000
},
"heightCm": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 1000
},
"quantity": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"declaredValue": {
"type": "number",
"minimum": 0,
"maximum": 100000000
},
"category": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"weightKg",
"quantity"
],
"additionalProperties": false
},
"shippingMode": {
"default": "auto",
"type": "string",
"enum": [
"courier",
"air",
"sea",
"road",
"postal",
"auto"
]
},
"serviceLevel": {
"default": "auto",
"type": "string",
"enum": [
"economy",
"standard",
"express",
"auto"
]
},
"currency": {
"default": "USD",
"type": "string",
"minLength": 1,
"maxLength": 3
}
},
"required": [
"origin",
"destination",
"shipment",
"shippingMode",
"serviceLevel",
"currency"
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"estimatedCost": {
"type": "object",
"properties": {
"min": {
"type": "number",
"minimum": 0
},
"max": {
"type": "number",
"minimum": 0
},
"currency": {
"type": "string"
}
},
"required": [
"min",
"max",
"currency"
],
"additionalProperties": false
},
"recommendedEstimate": {
"type": "number",
"minimum": 0
},
"actualWeightKg": {
"type": "number",
"exclusiveMinimum": 0
},
"volumetricWeightKg": {
"type": "number",
"minimum": 0
},
"chargeableWeightKg": {
"type": "number",
"exclusiveMinimum": 0
},
"shippingMode": {
"type": "string",
"enum": [
"courier",
"air",
"sea",
"road",
"postal"
]
},
"serviceLevel": {
"type": "string",
"enum": [
"economy",
"standard",
"express"
]
},
"estimatedTransitDays": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"max": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"costBreakdown": {
"type": "object",
"properties": {
"baseFreight": {
"type": "number",
"minimum": 0
},
"fuelSurcharge": {
"type": "number",
"minimum": 0
},
"handling": {
"type": "number",
"minimum": 0
},
"remoteAreaSurcharge": {
"type": "number",
"minimum": 0
},
"oversizeSurcharge": {
"type": "number",
"minimum": 0
},
"estimatedOtherFees": {
"type": "number",
"minimum": 0
}
},
"required": [
"baseFreight",
"fuelSurcharge",
"handling",
"remoteAreaSurcharge",
"oversizeSurcharge",
"estimatedOtherFees"
],
"additionalProperties": false
},
"rateSource": {
"type": "string",
"enum": [
"live_carrier",
"internal_estimate",
"heuristic_estimate"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"dutiesAndTaxes": {
"type": "object",
"properties": {
"included": {
"type": "boolean",
"const": false
},
"estimatedAmount": {
"type": "null"
},
"note": {
"type": "string"
}
},
"required": [
"included",
"estimatedAmount",
"note"
],
"additionalProperties": false
},
"confidence": {
"type": "object",
"properties": {
"level": {
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"reason": {
"type": "string"
}
},
"required": [
"level",
"reason"
],
"additionalProperties": false
},
"assumptions": {
"type": "array",
"items": {
"type": "string"
}
},
"riskFlags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high"
]
},
"message": {
"type": "string"
}
},
"required": [
"code",
"severity",
"message"
],
"additionalProperties": false
}
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"shippingMode": {
"type": "string",
"enum": [
"courier",
"air",
"sea",
"road",
"postal"
]
},
"serviceLevel": {
"type": "string",
"enum": [
"economy",
"standard",
"express"
]
},
"estimatedCost": {
"type": "object",
"properties": {
"min": {
"type": "number",
"minimum": 0
},
"max": {
"type": "number",
"minimum": 0
},
"currency": {
"type": "string"
}
},
"required": [
"min",
"max",
"currency"
],
"additionalProperties": false
},
"estimatedTransitDays": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"max": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"rateSource": {
"type": "string",
"enum": [
"live_carrier",
"internal_estimate",
"heuristic_estimate"
]
},
"provider": {
"type": [
"string",
"null"
]
}
},
"required": [
"shippingMode",
"serviceLevel",
"estimatedCost",
"estimatedTransitDays",
"rateSource",
"provider"
],
"additionalProperties": false
}
},
"recommendedOptionReason": {
"anyOf": [
{
"type": "string",
"enum": [
"lowest_estimated_cost",
"shortest_transit",
"balanced_cost_and_time"
]
},
{
"type": "null"
}
]
},
"generatedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"estimatedCost",
"recommendedEstimate",
"actualWeightKg",
"volumetricWeightKg",
"chargeableWeightKg",
"shippingMode",
"serviceLevel",
"estimatedTransitDays",
"costBreakdown",
"rateSource",
"provider",
"dutiesAndTaxes",
"confidence",
"assumptions",
"riskFlags",
"options",
"recommendedOptionReason",
"generatedAt"
],
"additionalProperties": false
}Category: Logistics Intelligence · hierarchy: primary · idempotent: yes · side effects: no