Walmart Ship with Walmart (SWW) - Early Label Purchase Flow

Overview

This feature allows purchasing shipping labels early for Walmart Marketplace orders using Ship with Walmart (SWW), sending tracking information to Walmart immediately when an order is released to the warehouse, rather than waiting for the warehouse to complete pick/pack processing.

Purpose

Faster tracking delivery: Send tracking to Walmart as soon as the order is released, improving seller metrics
Meet delivery promises: Ensure tracking is registered early to avoid late shipment penalties
Simplified warehouse flow: Warehouse uses pre-purchased labels at ship time

How It Works

1. Order Import (EDI)

When a Walmart order is imported via EDI, purchase_label_early is automatically set to true by default. This ensures all Walmart orders benefit from early tracking delivery.

2. Order Entry (Shipping Page)

Users can toggle the “Purchase shipping label early” checkbox on the shipping page to enable/disable early label purchase for individual orders.

3. Label Purchase (Release to Warehouse)

When the order transitions to awaiting_deliveries state:

System automatically purchases a shipping label via Walmart SWW API
Label PDF is stored as an order attachment (category: early_ship_label)
EDI ship confirmation is sent to Walmart with tracking info
Metadata stored in early_label_metadata JSONB column

4. Picking/Packing (Warehouse Processing)

When the warehouse picks/packs the order:

The picker screen displays an alert if an early label was purchased
Shows the early-labeled shipment dimensions/weights
Warns that changing packing will void the early label
Staff can choose to match the early label packing or override

5. Ship-Labeling (Label Assignment)

When the warehouse completes picking and performs ship-labeling:

System checks for mismatch between early label and actual packing
If packing matches: Reuses the existing label (no new API call), moves label PDF from order to shipment
If packing changed: Voids early label, resets flag, purchases new labels for actual shipments
Shipment(s) marked as label_complete

6. Voiding Labels

Auto-Void (State Transitions)

If order transitions OUT of awaiting_deliveries to:

cancelled
fraudulent
in_cr_hold

The early label is automatically voided via API. The purchase_label_early flag is preserved so it will purchase again when re-released.

Auto-Void (Mismatch Detection)

When picking is completed, if the actual packing differs from the early label:

System compares shipment count, dimensions, and weights
Triggers if: different shipment count, or >20% / >2 inches / >1 lb difference
Early label is voided via API
purchase_label_early flag is reset to false
Flash message warns user that early label was voided
New labels are purchased via normal flow

Manual Void (Void Shipments Action)

If user clicks “Void Shipments” on the delivery:

Early label is voided (if not yet transferred to shipment)
purchase_label_early flag is reset to false
Next ship-label will go through normal flow

Database Schema

add_column :orders, :purchase_label_early, :boolean, default: false, null: false
add_column :orders, :early_label_metadata, :jsonb, default: {}

early_label_metadata Structure

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "USPS",
  "sww_label_id": "abc123",
  "service_type": "USPS_GROUND_ADVANTAGE",
  "purchased_at": "2026-01-21T10:00:00Z",
  "delivery_id": 12345,
  "voided_at": null,
  "void_reason": null,
  "early_label_shipments_count": 1,
  "early_label_shipments_data": [
    {
      "id": 123456,
      "length": 12.0,
      "width": 10.0,
      "height": 8.0,
      "weight": 5.0,
      "container_type": "carton"
    }
  ]
}

Key Files

File	Purpose
`app/models/order.rb`	State machine hooks, label purchase/void logic, mismatch detection
`app/models/delivery.rb`	`void_shipments` integration
`app/services/edi/walmart/shipping_label_purchaser.rb`	Reuse early label at ship-label time
`app/services/edi/walmart/confirm_message_processor.rb`	EDI ship confirmation with carrier info
`app/services/edi/walmart/ship_code_mapper.rb`	Maps SWW carrier to Walmart EDI codes
`app/controllers/orders_controller.rb`	Flash messages for UI feedback
`app/controllers/deliveries_controller.rb`	Mismatch detection at complete_picked
`app/views/orders/shipping.html.erb`	Checkbox and status display
`app/views/deliveries/picked.html.erb`	Early label alert with dimensions
`app/models/upload.rb`	`early_ship_label` category

Order Methods

# Check if order has active early label
order.has_early_purchased_label?

# Check if eligible for SWW
order.walmart_sww_eligible?

# Check if early label shipments match current packing
# Returns { match: true/false, reason: 'description of mismatch' }
order.early_label_shipments_match?(delivery)

# Manually void early label
order.void_early_label!(reason: 'Manual void', reset_flag: true)

# Get early label upload
order.early_label_upload

# Get stored early label shipment data
order.early_label_shipments_data
order.early_label_shipments_count

UI States

State	Display
No early label, SWW eligible	Checkbox shown
Early label purchased	Green success alert with tracking
Early label voided	Warning alert + checkbox shown
Labels already on shipments	Success alert (labels exist)

Walmart API Considerations

Tracking Updates

Walmart allows updating tracking within 24 hours of original shipment OR before first carrier scan
Use processMode: PARTIAL_UPDATE to update tracking
Multiple confirm messages allowed for different line items

Known Limitations

Early label is for 1 shipment based on existing suggested shipments
Must have at least one shipment created before early label purchase
If actual packing differs significantly, early label is voided and new labels purchased

Implemented Features

Mismatch Detection (Completed)

At complete_picked time, the system detects if:

Number of shipments differs from early label (early = 1, actual = 2+)
Dimensions/weights significantly different (>20% or >2 inches / >1 lb)

Mismatch Handling (Completed)

When mismatch is detected:

Early label is voided via Walmart API
purchase_label_early flag is reset to false
Flash warning informs user of the void
Normal ship-labeling flow purchases new labels for actual shipments
EDI confirm message sent with correct carrier info

TODO / Future Enhancements

Multi-shipment early labels: Currently early label supports 1 shipment; consider supporting multiple upfront
Dimension estimation improvements: Use historical data to better estimate packaging

Development/Testing

In development mode, the system uses a mock PDF (test/sww_label_mock_pdf.pdf) since the Walmart sandbox doesn’t return real label PDFs.