Shipping estimate

Chargeable weight, freight ranges and source references.

All action kinds · Project workflow

• Kind: shipping_estimate
• Availability: available
• Registry cost category: none
• Lifecycle stage IDs: 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

Returns a planning estimate for the supported China-to-US lane. Preserve its sources, exclusions and unknown values; it is not a binding carrier quote or booking.

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 or null	No
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": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 100000000
        },
        {
          "type": "null"
        }
      ]
    },
    "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"
      ]
    }
  },
  "anyOf": [
    {
      "required": [
        "cartons"
      ]
    },
    {
      "required": [
        "totals"
      ]
    }
  ],
  "description": "Provide cartons or totals. Cartons take precedence when both are present."
}

Example request

Synthetic example for action.json; adapt it to your reviewed brief.

{
  "kind": "shipping_estimate",
  "input": {
    "cartons": [
      {
        "lengthCm": 20,
        "widthCm": 15,
        "heightCm": 10,
        "weightKg": 2,
        "count": 1
      }
    ],
    "destination": {
      "country": "US"
    },
    "modes": [
      "air_express"
    ],
    "batteries": "none"
  }
}

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

maglev actions request PROJECT_ID --input action.json \
  --idempotency-key example-shipping-estimate-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

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": {}
}