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:

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

4. Picking/Packing (Warehouse Processing)

When the warehouse picks/packs the order:

  1. The picker screen displays an alert if an early label was purchased
  2. Shows the early-labeled shipment dimensions/weights
  3. Warns that changing packing will void the early label
  4. 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:

  1. System checks for mismatch between early label and actual packing
  2. If packing matches: Reuses the existing label (no new API call), moves label PDF from order to shipment
  3. If packing changed: Voids early label, resets flag, purchases new labels for actual shipments
  4. 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

# Migration: 20260121000000_add_early_label_columns_to_orders.rb
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

  1. Multi-shipment early labels: Currently early label supports 1 shipment; consider supporting multiple upfront
  2. 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.

Related Documentation