Overview

This feature lets you purchase UPS shipping labels through ShipStation for Amazon FBA HAZMAT cartons. It is designed for suppliers who cannot use Amazon Partnered Carrier labels for HAZMAT shipments. The system creates per-carton UPS labels via ShipStation, merges them into per-shipment PDFs, sends them to suppliers alongside FBA content labels, and uploads tracking numbers back to Amazon automatically.

Use Cases

• HAZMAT inventory where Amazon labels are restricted
• Prepaid inbound freight with your preferred UPS rates (UPS Walleted)
• Suppliers who need a single email containing PO + FBA labels + carrier labels
• Automated tracking upload back to Amazon for ASN compliance

Getting Started

Prerequisites

• Business-level ShipStation is configured and active
  • Settings: Dropship Labels enabled with ShipStation API Key/Secret
  • Validation passes: ShipStation.valid?(business)
• Supplier is configured for prepaid/HAZMAT
  • Supplier settings: supplier.settings(:supplier_fba_shipments).hazmat_ship_station = true
  • Supplier must select a ShipStation Warehouse
  • Supplier must set a Prepaid Inbound Carrier (alpha code) for prepaid/HAZMAT flows
• Item is flagged prepaid HAZMAT
  • supplier_catalog_item.prepaid_hazmat_at set (or supplier-specific rules)

Configuration Steps

1. Business: Enable ShipStation under Settings → Dropship Labels and enter API credentials.
2. Supplier: Edit supplier → set Prepaid Inbound Carrier and select ShipStation Warehouse.
3. Supplier: Enable HAZMAT ShipStation in Supplier FBA Shipments settings.
4. Catalog Item: Mark item as Prepaid HAZMAT (or ensure your supplier rule covers it).
5. Create an Inbound Plan for the HAZMAT item and proceed through label generation.

Tip: The plan page surfaces a HAZMAT badge and shows Carrier Label and FBA Labels per shipment.

Configuration Options

• Supplier → FBA Shipments
  • hazmat_ship_station (boolean): Enable ShipStation label purchase for HAZMAT
  • prepaid_inbound_carrier (alpha code): Required for prepaid/HAZMAT planning
  • ship_station_warehouse_id (select): Required to issue ShipStation labels
• Business → Dropship Labels
  • ship_station (boolean), ship_station_api_key, ship_station_api_secret
• Defaults used for labels
  • Carrier Code: ups_walleted
  • Service Code: ups_ground
  • Package Code: package

Feature Details

Compliance & Limitations

• We do not purchase special HAZMAT services, nor upload SDS/MSDS to carriers.
• Labels purchased are standard UPS Ground labels.
• We assume your organization has verified the product can legally ship via ground.
• You are responsible for properly identifying, marking, and labeling cartons to meet carrier and regulatory requirements.

Flow Summary

1. Inbound Plan is created and progresses through packing/placement steps.
2. For HAZMAT/prepaid plans, system will purchase per-carton UPS labels via ShipStation.
3. Per-carton labels are merged into a per-shipment “Carrier Label” PDF.
4. Email to supplier includes FBA content labels and Carrier labels.
5. Tracking numbers from ShipStation are uploaded to Amazon on confirmation.

Where it lives (core logic)

• ShipStation client (auth, orders, labels): app/models/concerns/ship_station.rb
• Per-shipment label purchase: InboundPlanShipment#purchase_hazmat_carrier_labels!
• Per-carton label purchase and payload: InboundPlanShipmentBox#purchase_hazmat_label!
• HAZMAT plan detector and tracking uploader: InboundPlan#prepaid_hazmat_labels?, #upload_tracking_details
• Jobs that orchestrate purchase + tracking: InboundPlanMailerJob, InboundPlanPurchaseOrderBuilderJob, InboundPlanTrackingDetailUploadJob
• Email attachments (merge FBA + Carrier 4x6): SupplierPurchaseOrder#email_with_shipment_labels!

Amazon tracking upload

Tracking numbers are pulled from ShipStation shipment transport details (trackingNumber) and posted to SP-API via update_shipment_tracking_details so your ASN reflects carrier tracking per carton.

Examples

Validate ShipStation configuration

business = Business.find(1)
ShipStation.valid?(business) # => true

Purchase labels for a single shipment

plan = InboundPlan.find(1234)
shipment = plan.inbound_plan_shipments.first

# Will buy per-carton UPS labels on ShipStation, then merge into a single PDF
shipment.purchase_hazmat_carrier_labels!

# Inspect merged Carrier Label
shipment.hazmat_label.attached? # => true

Full flow via jobs (recommended)

# System jobs will auto-purchase and then upload tracking for HAZMAT plans
AdminJob.debounce(InboundPlanMailerJob.new(plan.id))

# or, if your supplier uses multiple shipments/POs
AdminJob.debounce(InboundPlanPurchaseOrderBuilderJob.new(plan.id))

Manually trigger tracking upload (idempotent)

InboundPlanTrackingDetailUploadJob.new.perform(plan.id)

API Integration

• ShipStation
  • Create/Update Order: /orders/createorder
  • Create Label for Order: /orders/createlabelfororder
  • Get Rates: /shipments/getrates
• Amazon SP-API (Inbound)
  • Upload tracking per carton: update_shipment_tracking_details

Troubleshooting

• ShipStation not configured: ArgumentError: SETTINGS INCORRECT
  • Enable Dropship Labels and set API Key/Secret; ensure ShipStation.valid? returns true.
• Payment issue: ShipStation Account Missing Payment
  • Resolve subscription/payment in ShipStation.
• Supplier missing warehouse
  • Set ship_station_warehouse_id on the Supplier edit page.
• Prepaid carrier missing
  • Set prepaid_inbound_carrier on Supplier before creating plans.
• Labels didn’t attach to shipment
  • Ensure every carton has a purchased label; the system merges all per-carton labels into the shipment Carrier Label.
• Tracking not uploaded
  • Job guardrails: plan must be HAZMAT/prepaid and have Carrier Labels attached; re-run InboundPlanTrackingDetailUploadJob.

Related Features

• FBA Shipping Labels (Amazon Collect)
• AutoShip to FBA
• Shipping Label Email Delivery

Images

Place screenshots in /public-documentation/assets/images/ using descriptive names, for example:

• shipstation-hazmat-ups-labels-supplier-config.png (Supplier configuration screen)
• shipstation-hazmat-ups-labels-plan-view.png (Plan detail with Carrier Label) Include meaningful alt text and keep images optimized for the web.