Skip to content
Maglev docs

Landed cost

A planning range for freight, duties and fees with exclusions and unknowns.

All action kinds · Project workflow

  • Kind: landed_cost
  • Availability: available
  • Registry cost category: none
  • Lifecycle stage IDs: customs_and_import, shipping

The cost category describes model work in the registry; it is not a manufacturing price or a monetary quote. Read maglev actions kinds --json for current availability and schemas.

What this does

Section titled “What this does”

Returns a planning estimate with declared-value calculations. Missing duty or cost information remains unknown. It is not an approved customs assessment.

Input

Section titled “Input”

Send these fields inside the request’s input object. Use only facts you have, and keep unresolved requirements explicit. Optional fields with defaults can be omitted.

Provide cartons or totals. Cartons take precedence when both are present.

Field Type Required Details
cartons object[] No Min items 1. Max items 50
cartons[].lengthCm number If parent supplied Maximum 1000. Greater than 0
cartons[].widthCm number If parent supplied Maximum 1000. Greater than 0
cartons[].heightCm number If parent supplied Maximum 1000. Greater than 0
cartons[].weightKg number If parent supplied Maximum 2000. Greater than 0
cartons[].count integer If parent supplied Minimum 1. Maximum 10000
totals object No
totals.grossWeightKg number If parent supplied Maximum 100000. Greater than 0
totals.volumeM3 number If parent supplied Minimum 0. Maximum 1000
originCity string No Min length 2. Max length 60
destination object No Default: {“country”:“US”}
destination.country “US” If parent supplied
destination.postcode string No Max length 10
destination.state string No Min length 2. Max length 2
destination.city string No Max length 60
modes string[] No Min items 1. Max items 3
declaredValueUsd number Yes Minimum 0. Maximum 100000000
hts string or null No
productCategory string or null No
batteries string No One of: none, contained, packed_with, standalone
Input JSON schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "cartons": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lengthCm": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000
          },
          "widthCm": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000
          },
          "heightCm": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 1000
          },
          "weightKg": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 2000
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000
          }
        },
        "required": [
          "lengthCm",
          "widthCm",
          "heightCm",
          "weightKg",
          "count"
        ]
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "grossWeightKg": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 100000
        },
        "volumeM3": {
          "type": "number",
          "minimum": 0,
          "maximum": 1000
        }
      },
      "required": [
        "grossWeightKg",
        "volumeM3"
      ]
    },
    "originCity": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "destination": {
      "default": {
        "country": "US"
      },
      "type": "object",
      "properties": {
        "country": {
          "type": "string",
          "const": "US"
        },
        "postcode": {
          "type": "string",
          "maxLength": 10
        },
        "state": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        "city": {
          "type": "string",
          "maxLength": 60
        }
      },
      "required": [
        "country"
      ]
    },
    "modes": {
      "minItems": 1,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "air_express",
          "air_freight",
          "ocean_lcl"
        ]
      }
    },
    "declaredValueUsd": {
      "type": "number",
      "minimum": 0,
      "maximum": 100000000
    },
    "hts": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 20
        },
        {
          "type": "null"
        }
      ]
    },
    "productCategory": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "batteries": {
      "type": "string",
      "enum": [
        "none",
        "contained",
        "packed_with",
        "standalone"
      ]
    }
  },
  "required": [
    "declaredValueUsd"
  ],
  "anyOf": [
    {
      "required": [
        "cartons"
      ]
    },
    {
      "required": [
        "totals"
      ]
    }
  ],
  "description": "Provide cartons or totals. Cartons take precedence when both are present."
}

Request the action

Section titled “Request the action”

Prepare action.json with kind: "landed_cost" and an input object matching the schema above.

Replace PROJECT_ID with your saved project ID. Use a new idempotency key for new work and retain it for an identical retry.

Terminal window
maglev actions request PROJECT_ID --input action.json \
  --idempotency-key example-landed-cost-001 --json

Read action.status, action.output, deliveries and any task in the response. Model actions can take several minutes. After a timeout, check saved actions before retrying. See request and recovery behavior.

Output

Section titled “Output”

The schema below describes action.output.result. The saved action.output envelope also contains draft: true and a note. It can be null while an action is running or after a failure; check the status before reading the result. Null or missing facts are unknown; preserve source references and open questions.

This action currently exports an open object schema. Inspect its returned fields and status; an open schema is not a guarantee that a particular field will exist.

Output JSON schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": {}
}