Shipment special services

Configure special handling requirements for shipments containing batteries, dry ice, dangerous goods, or requiring a signature.

GraphQL

Special services are added at the carton level when creating a shipment via the shipmentCreateWorkflow mutation. Use specialServices to declare the type of special handling required, and specialServiceDetails for any additional configuration that service requires.

Carrier support varies. Confirm with your carrier that the selected service level supports the special service you need before submitting a shipment.

Batteries

Use BATTERY in specialServices when a carton contains lithium-ion or lithium-metal batteries. You must also provide batteryDetail nested inside specialServiceDetails.

Note: batteryDetail must be nested inside specialServiceDetails, not passed directly on the carton. Passing it at the carton level will result in a validation error.

Battery shipment example

"shipmentCartons": [
  {
    "specialServices": ["BATTERY"],
    "specialServiceDetails": {
      "batteryDetail": {
        "material": "LITHIUM_ION",
        "packingType": "BATTERY_INSIDE_EQUIPMENT"
      }
    }
  }
]

Battery material types:

LITHIUM_ION — Lithium-ion battery (rechargeable)
LITHIUM_METAL — Lithium-metal battery (non-rechargeable)

Battery packing types:

BATTERY_INSIDE_EQUIPMENT — Battery is contained inside an item in the package
BATTERY_ONLY — The package contains only a battery or batteries
BATTERY_PACKAGED_WITH_EQUIPMENT — Battery is packaged with the equipment but not contained inside it

Signature options

Use SIGNATURE_OPTION in specialServices to require a signature upon delivery. Provide signatureOptionDetail nested inside specialServiceDetails to specify the signature type.

Signature option example

"shipmentCartons": [
  {
    "specialServices": ["SIGNATURE_OPTION"],
    "specialServiceDetails": {
      "signatureOptionDetail": {
        "signatureOptionType": "ADULT"
      }
    }
  }
]

Signature option types:

ADULT — Adult signature required (recipient must be of legal age)
DIRECT — Direct signature required (someone at the address must sign)
INDIRECT — Indirect signature allowed (neighbor or building manager may sign)
DEFAULT — Uses the default signature behavior for the selected service level
NONE — No signature required

Alcohol

Alcohol shipments are handled through Zonos's excise duties feature, which calculates the applicable excise taxes based on product measurements like volume and ABV. See the excise duties guide to configure alcohol shipments.

Dry ice

Use DRY_ICE in specialServices when a carton contains dry ice as a refrigerant. Provide dryIceDetail nested inside specialServiceDetails with the weight of dry ice in the carton.

Dry ice shipment example

"shipmentCartons": [
  {
    "specialServices": ["DRY_ICE"],
    "specialServiceDetails": {
      "dryIceDetail": {
        "weight": 0.5,
        "weightUnit": "KILOGRAM"
      }
    }
  }
]

Dangerous goods

Use DANGEROUS_GOODS in specialServices when a carton contains hazardous materials that require special carrier handling and documentation beyond the battery special service.

Dangerous goods example

"shipmentCartons": [
  {
    "specialServices": ["DANGEROUS_GOODS"]
  }
]

For detailed guidance on shipping hazardous materials including restrictions by carrier, see the hazmat shipping guide.

Combining special services

Multiple special services can be combined in a single carton by passing multiple values in the specialServices array.

Multiple special services example

"shipmentCartons": [
  {
    "specialServices": ["BATTERY", "SIGNATURE_OPTION"],
    "specialServiceDetails": {
      "batteryDetail": {
        "material": "LITHIUM_ION",
        "packingType": "BATTERY_INSIDE_EQUIPMENT"
      },
      "signatureOptionDetail": {
        "signatureOptionType": "DIRECT"
      }
    }
  }
]

Book a demo