Shipping Batch System Overview

Overview

The Shipping Batch System manages the complex process of shipping physical magazines to subscribers. Each issue of the magazine requires thousands of copies to be shipped to subscribers worldwide, with varying requirements:

• Some subscribers receive multiple copies
• International shipping requires different processes
• Gift subscriptions need special attention
• Some shipments are complimentary
• Reshipments must be tracked when magazines are lost or damaged

The system organizes these shipments into “batches” - logical groupings of magazines going out for a particular issue. Each batch contains detailed shipping information, tracks the status of shipments, and maintains financial data for revenue recognition and reporting.

When processing a batch, the system:

1. Identifies which subscribers should receive the current issue
2. Validates shipping addresses
3. Applies special handling rules
4. Generates shipping files for fulfillment
5. Tracks the financial implications of each shipment
6. Handles reshipment requests when needed

This provides a robust framework for managing the physical distribution of magazines while maintaining detailed records for financial and operational reporting.

Operational Flow

1. Pull Creation

• System identifies eligible subscriptions for current issue
• Creates subscription issue records for tracking
• Groups subscriptions into shipping batch
• Validates addresses and quantities
• Applies special handling rules (premium, concierge, etc.)
• Generates initial shipping files for fulfillment

2. Shipping Completion

When batch is marked as shipped:

• Updates subscription issue statuses
• Calculates earned income for financial reporting
• Updates subscription copy counts
• Records shipping dates for tracking

Architecture

The shipping batch system provides an asynchronous framework for processing and tracking magazine issue shipments. It handles both initial shipments and reshipments, with support for multiple subscription types and special handling.

Core Components

1. Controllers

• JC_Shipping_Batch_Controller

  • Manages batch creation and processing
  • Handles AJAX endpoints
  • Controls batch status lifecycle
  • Supports concurrent processing

2. Models

TSJ_Shipping_Batch

• Represents a collection of subscriptions for shipping
• Tracks batch metadata:
  • Issue association
  • Shipping date
  • Batch type (main_file/supplemental)
  • Processing status
  • Subscription counts

TSJ_Shipping_Batch_Subscription

• Links subscriptions to shipping batches
• Stores shipping details:
  • Address information
  • Special handling flags
  • Reship status/reasons
  • Premium/Concierge information
  • Gift status

TSJ_Subscription_Issue

• Links subscriptions to specific issue shipments
• Tracks subscription-specific issue data:
  • Earned income calculations
  • Incremental revenue tracking
  • Issue number association
  • Special handling requirements
  • Shipping batch associations
• Provides crucial financial reporting data for:
  • Earned income reports
  • Revenue recognition
  • Issue-specific analytics
• Maintains relationship between:
  • Individual subscriptions
  • Shipping batches
  • Magazine issues
  • Revenue tracking

3. Database Structure

jc_shipping_batch_subscriptions:
- id
- shipping_batch_id
- subscription_id
- subscription_issue_id
- quantity
- address fields
- reship flags
- special handling
- premium/concierge data

Key Features

1. Batch Processing

• Asynchronous processing using Action Scheduler
• Progress tracking
• Batch status management
• Error handling and recovery

2. Subscription Handling

• Multiple subscription types
• Gift subscriptions
• Premium memberships
• Concierge program support
• International shipping

3. Special Cases

• Reshipment management
• Multi-copy subscriptions
• Premium/Special editions
• Address validation
• Comped subscriptions

Processing Flow

1. Batch Creation
   • Issue selection
   • Batch type determination
   • Pull date assignment
   • Initial status setting
2. Subscription Processing
   • Address validation
   • Special handling checks
   • Quantity verification
   • Status updates
3. Completion
   • Status finalization
   • Download generation
   • Reporting updates

Integration Points

1. WooCommerce
   • Subscription data
   • Customer information
   • Order processing
2. Action Scheduler
   • Batch processing
   • Task queuing
   • Error handling
3. Reporting System
   • Shipping statistics
   • Fulfillment tracking
   • Issue distribution

Security and Validation

1. Permission Checks
   • Customer screens capability
   • AJAX nonce verification
   • User role validation
2. Data Validation
   • Address verification
   • Field length limits
   • Status transitions
3. Error Handling
   • Process logging
   • Recovery mechanisms
   • User notifications