Shipment special services

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.

"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.

"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.

"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.

"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.

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