Ship with Walmart (SWW) Integration

Walmart's "Ship with Walmart" API integration provides discounted shipping rates for Walmart marketplace orders, enabling label purchasing and tracking directly from Heatwave.

Overview

When processing Walmart marketplace orders, the system can:

• Retrieve discounted shipping rates from Walmart's carrier partnerships (FedEx, USPS)
• Display rates alongside regular carriers for comparison in the shipping workflow
• Purchase shipping labels via Walmart's API
• Download label PDFs and attach to shipments
• Populate tracking numbers automatically
• Void/discard labels if needed

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                        Rate Retrieval Flow                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Delivery needs shipping ──► Is Walmart Order? ──► Fetch SWW Rates      │
│                                     │                    │              │
│                                     No                   ▼              │
│                                     │        Merge with FedEx/UPS rates │
│                                     ▼                    │              │
│                              Skip SWW ────────────────►──┘              │
│                                                         │               │
│                                                         ▼               │
│                                              Display combined rates     │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                        Label Purchase Flow                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  User selects SWW rate ──► Create Label API ──► Download Label PDF      │
│                                                        │                │
│                                                        ▼                │
│                                              Create Shipment record     │
│                                                        │                │
│                                                        ▼                │
│                                              Populate tracking number   │
│                                                        │                │
│                                                        ▼                │
│                                      Trigger ship confirmation to Walmart│
└─────────────────────────────────────────────────────────────────────────┘

Key Components

Services

Service	Purpose
Edi::Walmart::ShipWithWalmart	Core API client for SWW endpoints
Shipping::WalmartSeller	Shipping carrier class following Shipping::Base pattern
Edi::Walmart::ShippingLabelPurchaser	Orchestrates label purchase workflow

API Endpoints Used

Endpoint	Method	Purpose
/v3/shipping/labels/carriers	GET	List available carriers (USPS, FedEx)
/v3/shipping/labels/carriers/{id}/package-types	GET	Package types per carrier
/v3/shipping/labels/shipping-estimates	POST	Get rate estimates
/v3/shipping/labels	POST	Create/purchase label
/v3/shipping/labels/{id}	GET	Download label PDF
/v3/shipping/labels/{id}	DELETE	Void/discard label

Usage

Automatic Rate Retrieval

For Walmart marketplace orders, SWW rates are automatically included in shipping rate comparison:

# In Delivery#retrieve_shipping_costs
# Walmart order info is automatically detected and passed to WyShipping
if order&.edi_orchestrator_partner&.start_with?('walmart_seller')
  options[:walmart_order_info] = {
    partner: order.edi_orchestrator_partner.to_sym,
    po_number: order.edi_po_number,
    deliver_by_date: order.requested_deliver_by
  }
end

Manual Rate Retrieval

orchestrator = Edi::Walmart::Orchestrator.new(:walmart_seller_us)
sww_client = Edi::Walmart::ShipWithWalmart.new(orchestrator)

result = sww_client.get_shipping_estimates(
  purchase_order_id: 'PO-12345',
  from_address: { street1: '123 Warehouse St', city: 'Chicago', state: 'IL', zip: '60601', country: 'US' },
  to_address: { street1: '456 Customer Ave', city: 'New York', state: 'NY', zip: '10001', country: 'US' },
  packages: [{ weight: 5.0, length: 12, width: 10, height: 8 }],
  sku: 'ITEM-SKU',
  quantity: 1,
  deliver_by_date: 7.days.from_now.to_date,
  ship_by_date: Date.current
)

if result.success
  result.estimates.each do |est|
    puts "#{est[:carrier_name]} #{est[:service_name]}: $#{est[:price]}"
  end
end

Label Purchase

# After user selects a SWW rate
purchaser = Edi::Walmart::ShippingLabelPurchaser.new(shipment)
result = purchaser.purchase_label(selected_rate)

if result.success
  puts "Tracking: #{result.tracking_number}"
  puts "Label ID: #{result.label_id}"
  # Label PDF automatically attached to shipment.uploads
end

Void Label

purchaser = Edi::Walmart::ShippingLabelPurchaser.new(shipment)
result = purchaser.void_label

if result[:success]
  puts "Label voided successfully"
end

Database Schema

Shipment Model Extensions

New JSONB column sww_metadata with typed accessors:

# In Shipment model
jsonb_accessor :sww_metadata,
               sww_carrier: :string,        # Actual carrier: USPS, FedEx, UPS
               sww_service_type: :string,   # e.g., USPS_GROUND_ADVANTAGE
               sww_purchased_at: :datetime,
               sww_po_number: :string

Additional column:

• sww_label_id (string) - For voiding labels

Carrier Handling

For SWW shipments, carrier data is stored in two places:

• shipment.carrier = "WalmartSeller" - Indicates this is a SWW shipment (matches shipping_option)
• shipment.sww_carrier = "USPS" / "FedEx" - The actual underlying carrier from Walmart

This dual storage allows:

• UI to identify SWW shipments and display appropriate badges
• Tracking to use the actual carrier's tracking system
• EDI confirms to send correct carrier info to Walmart

ShippingCost Rate Data

SWW rates store additional fields in rate_data:

{
  sww_carrier_id: 'FedEx',
  sww_service_type: 'SMART_POST',
  sww_estimated_delivery: '2025-01-03T04:59:00.000Z',
  sww_transit_days: 7,
  sww_carrier_name: 'FedEx',
  sww_service_name: 'FedEx Ground Economy',
  sww_price: 7.62
}

UI Integration

Rate Display

SWW rates are displayed with a distinctive "Ship with Walmart" prefix:

Ship with Walmart: FedEx Ground Economy - $7.62 (7 days)
Ship with Walmart: USPS Ground Advantage - $9.82 (6 days)

Helper Methods

<%# In delivery views %>
<%= format_shipping_rate_with_sww_badge(shipping_cost) %>

<%# Inline badge %>
<%= sww_badge %> <%# Renders: <span class="badge bg-primary">Ship with Walmart</span> %>

<%# Check if SWW rate %>
<% if is_sww_rate?(shipping_cost) %>
  <!-- Show SWW-specific info -->
<% end %>

Configuration

Orchestrator Settings

SWW is controlled via feature flags in Edi::Walmart::Orchestrator:

walmart_seller_us: {
  # ... other settings
  ship_with_walmart_enabled: true, # Enable SWW discounted shipping rates
  ship_with_walmart_remote_path: "https://marketplace.walmartapis.com/v3/shipping/labels",
  transporter_profile: :walmart_seller_us_api
}

walmart_seller_ca: {
  # ... other settings
  ship_with_walmart_enabled: true, # Enable SWW discounted shipping rates
  ship_with_walmart_remote_path: "https://marketplace.walmartapis.com/v3/shipping/labels",
  transporter_profile: :walmart_seller_ca_api
}

To disable SWW for a partner, set ship_with_walmart_enabled: false.

Credentials

Uses standard Walmart Marketplace API credentials configured in credentials.yml:

walmart_seller_us_api:
  client_id: '...'
  client_secret: '...'
  api_host: marketplace.walmartapis.com
  auth_url: https://marketplace.walmartapis.com/v3/token

EDI Ship Confirmation

When shipping labels are purchased, the system sends EDI confirmation messages to Walmart.

Carrier Mapping

The ShipCodeMapper handles carrier info for EDI messages:

# For SWW shipments, uses sww_carrier from metadata
carrier_info = Edi::Walmart::ShipCodeMapper.carrier_info(shipment)
# Returns:
# {
#   carrierName: { carrier: "FedEx" },      # or { otherCarrier: "CustomCarrier" }
#   methodCode: "Ground Economy",            # Extracted from delivery's selected_shipping_cost
#   trackingNumber: "9400111899223...",
#   trackingURL: "https://..."
# }

If shipment.carrier is "WalmartSeller", the mapper automatically:

1. Uses shipment.sww_carrier for the actual carrier name
2. Extracts the method from delivery.selected_shipping_cost.description

Method Extraction from Description

For SWW shipments, the method is extracted from the actual shipping cost description:

• "Ship with Walmart: FedEx Ground Economy" → method: Ground Economy
• "Ship with Walmart: USPS Ground Advantage" → method: Ground Advantage

The logic strips "Ship with Walmart: " and the carrier name prefix to get the actual method.

Error Handling

API Errors

All API calls return structured result objects:

result = sww_client.get_shipping_estimates(...)
if result.success
  # Use result.estimates
else
  Rails.logger.error("SWW Error: #{result.error}")
end

Label Purchase Failures

result = purchaser.purchase_label(rate)
if !result.success
  # result.error contains the error message
  # No tracking number populated
  # No label attached
end

Troubleshooting

No SWW Rates Displayed

1. Verify the order is from Walmart marketplace (order.edi_orchestrator_partner.start_with?('walmart_seller'))
2. Check that order.edi_po_number is present
3. Verify API credentials are configured correctly
4. Check Rails logs for SWW API errors

Label Creation Failed

1. Check the selected rate has valid sww_carrier_id and sww_service_type
2. Verify addresses are valid and complete
3. Check package dimensions are within carrier limits
4. Review Walmart API response in logs

Label Not Attached

1. Check Upload.uploadify_from_data succeeded
2. Verify the shipment has an uploads association
3. Check for file system or storage errors

Date/Time Handling

Walmart API uses Unix timestamps in milliseconds (UTC):

# Walmart timestamp: 1768608013378 (milliseconds since epoch)
# Parsed: 2026-01-16 21:20:13.378 UTC

# Parsing (in OrderMessageProcessor)
Time.zone.at(timestamp / 1000.0)  # Float division preserves milliseconds

# Reverse conversion (to send to Walmart)
Date.parse("20260118").to_time(:utc).to_i * 1000

All Walmart datetime fields are UTC-based.

Related Documentation

• doc/refactoring/shipping/ - Shipping system documentation
• doc/features/WALMART_EARLY_LABEL_PURCHASE.md - Early label purchase flow
• .agents/skills/webhooks/SKILL.md - Webhook handling patterns
• Edi::Walmart::Orchestrator - Walmart EDI configuration

API Reference

See Walmart Marketplace documentation:

• Buy Shipping
• Ship with Walmart API