Safe Ship Pro Documentation

Installation Guide

Standard Installation

1. Download the plugin ZIP file from your account
2. Navigate to WordPress Admin → Plugins → Add New
3. Click "Upload Plugin" and select the ZIP file
4. Click "Install Now" and then "Activate"
5. Go to Safe Ship Pro → License to enter your license key

Manual Installation

If you prefer to install manually via FTP:

1. Extract the ZIP file to /wp-content/plugins/safe-ship-pro/
2. Activate the plugin through the WordPress Plugins menu
3. Configure your settings in the admin panel

Post-Installation Setup

Configuration

General Settings

Navigate to Safe Ship Pro → Settings → General Settings to configure basic options:

Display Customization

// Example: Custom protection label
Protection Label: "Package Insurance"
Description: "Protect your order against shipping issues"

// Logo and branding
Protection Logo: Upload company logo
Provider Name: "Your Insurance Provider"
Provider Link: "https://provider.com"

Claims Settings

Plugin Features

Core Features Overview

Advanced Features

Technical Features

Shipping Protection

How It Works

The shipping protection system integrates seamlessly into your WooCommerce checkout process:

1. Customer adds products to cart
2. Protection option appears at checkout
3. Fee is calculated based on your settings
4. Customer toggles protection on or off
5. Fee is added to order if selected
6. Order is marked as protected

Fee Calculation Methods

// Example calculation
cartTotal = $150.00
percentage = 1.5% (0.015)
calculatedFee = $150.00 * 0.015 = $2.25

// Apply min/max constraints
minFee = $0.99
maxFee = $9.99
finalFee = Math.max(minFee, Math.min(calculatedFee, maxFee))
// Result: $2.25 (within range)

// Simple flat fee
cartTotal = $150.00
flatFee = $3.99
finalFee = $3.99
// Result: $3.99 (regardless of cart value)

Product Eligibility

Control which products are eligible for shipping protection:

• Global Settings - Enable/disable protection site-wide
• Category Exclusions - Exclude entire product categories
• Individual Products - Override settings per product
• Virtual Products - Automatically excluded

Claims Management

Claims Workflow

The claims system provides a complete workflow from submission to resolution:

Claim Statuses

File Upload Support

Customers can upload supporting evidence with their claims:

• Supported Formats - JPG, PNG, PDF files
• File Size Limits - 5MB per file maximum
• Multiple Files - Upload multiple evidence files
• Secure Storage - Files stored in protected directory

Analytics Dashboard

Key Metrics

The analytics dashboard provides comprehensive insights into your shipping protection performance:

Visual Charts

Interactive charts powered by Chart.js provide visual insights:

• Daily Protection Data - Line chart showing protection adoption over time
• Claims by Type - Pie chart breakdown of claim categories
• Claims by Status - Doughnut chart of claim status distribution
• Revenue Trends - Bar chart showing protection revenue trends

Dashboard Widget

Key metrics are also available as a WordPress dashboard widget for quick access:

// Dashboard widget shows:
- Protected orders count
- Total protection fees collected
- Total claims filed
- Pending claims requiring attention

User Guide

For Customers

Tracking Your Claims

• Status Updates - Receive email notifications when status changes
• Claim History - View all claims in your account
• Details View - See complete claim information and status
• Response Times - Typical review time is 1-3 business days

Admin Guide

Managing Protected Orders

Protected orders are easily identifiable in your WooCommerce admin:

• Order List - Protected orders show protection status
• Order Details - Protection information in order meta box
• Protection Amount - Fee amount clearly displayed
• Quick Actions - Create claims directly from order page

Processing Claims

Bulk Actions

Efficiently manage multiple claims:

• Filter claims by status, date, or type
• Bulk status updates for multiple claims
• Export claim data for external analysis
• Search claims by customer or order details

Analytics Review

Regular analytics review helps optimize your protection offering:

Developer Guide

Plugin Architecture

Safe Ship Pro follows WordPress coding standards with a modular architecture:

safe-ship-pro/
├── admin/                  # Admin-specific functionality
│   ├── css/               # Admin stylesheets
│   ├── js/                # Admin JavaScript
│   ├── partials/          # Admin template files
│   └── class-safe-ship-pro-admin.php
├── includes/              # Core plugin classes
│   ├── class-safe-ship-pro.php
│   ├── class-safe-ship-pro-protection.php
│   ├── class-safe-ship-pro-claims.php
│   ├── class-safe-ship-pro-analytics.php
│   └── class-safe-ship-pro-emails.php
├── public/                # Public-facing functionality
│   ├── css/               # Frontend stylesheets
│   ├── js/                # Frontend JavaScript
│   ├── partials/          # Frontend templates
│   └── class-safe-ship-pro-public.php
└── languages/             # Translation files

Core Classes

Custom Development

Fee Calculation Customization

/**
 * Custom protection fee calculation
 */
function custom_protection_fee($fee, $cart_total) {
    // Custom logic for fee calculation
    if ($cart_total > 100) {
        return $cart_total * 0.02; // 2% for orders over $100
    } else if ($cart_total > 50) {
        return $cart_total * 0.025; // 2.5% for orders $50-$100
    }
    return $fee; // Use default calculation
}
add_filter('safe_ship_pro_protection_fee', 'custom_protection_fee', 10, 2);

Custom Email Templates

Override email templates by placing them in your theme:

// Template location in your theme:
your-theme/
└── safe-ship-pro/
    └── emails/
        ├── protection-confirmation.php
        ├── claim-notification.php
        └── claim-status-update.php

// Template hierarchy (checked in order):
1. your-theme/safe-ship-pro/emails/template-name.php
2. plugin/public/partials/emails/template-name.php

Database Schema

CREATE TABLE wp_safe_ship_pro_claims (
    id mediumint(9) NOT NULL AUTO_INCREMENT,
    date_created datetime NOT NULL,
    date_updated datetime NOT NULL,
    user_id bigint(20) NOT NULL,
    order_id bigint(20) NOT NULL,
    claim_type varchar(50) NOT NULL,
    claim_reason text NOT NULL,
    claim_status varchar(20) DEFAULT 'pending',
    admin_notes text,
    attachments text,
    PRIMARY KEY (id),
    KEY user_id (user_id),
    KEY order_id (order_id),
    KEY claim_status (claim_status)
);

Order Meta Fields

// Protection-related order meta
_safe_ship_pro_protection_added  // 'yes' if protection added
_safe_ship_pro_protection_amount // Protection fee amount

// HPOS-compatible access
$order = wc_get_order($order_id);
$has_protection = $order->get_meta('_safe_ship_pro_protection_added', true) === 'yes';
$protection_amount = $order->get_meta('_safe_ship_pro_protection_amount', true);

API Reference

REST API Endpoints

GET /wp-json/safe-ship-pro/v1/stats

Response:
{
    "protection_rate": 65.5,
    "total_revenue": 1250.00,
    "total_claims": 15,
    "approval_rate": 85.7,
    "date_range": {
        "from": "2024-01-01",
        "to": "2024-01-31"
    }
}

GET /wp-json/safe-ship-pro/v1/claims

Parameters:
- status: pending|processing|approved|denied|completed
- limit: number of results (default: 20)
- offset: pagination offset

Response:
{
    "claims": [
        {
            "id": 123,
            "order_id": 456,
            "type": "damaged",
            "status": "processing",
            "date_created": "2024-01-15T10:30:00",
            "customer": {
                "name": "John Doe",
                "email": "john@example.com"
            }
        }
    ],
    "total": 45,
    "pages": 3
}

AJAX Endpoints

Submit Claim

// Submit new claim via AJAX
jQuery.ajax({
    url: ajaxurl,
    type: 'POST',
    data: {
        action: 'safe_ship_pro_submit_claim',
        order_id: 123,
        claim_type: 'damaged',
        claim_reason: 'Package arrived with damaged contents',
        security: nonce
    },
    success: function(response) {
        if (response.success) {
            alert('Claim submitted successfully!');
            location.reload();
        } else {
            alert('Error: ' + response.data.message);
        }
    }
});

Update Claim Status

// Admin: Update claim status
jQuery.ajax({
    url: ajaxurl,
    type: 'POST',
    data: {
        action: 'safe_ship_pro_update_claim',
        claim_id: 123,
        status: 'approved',
        admin_notes: 'Claim approved based on evidence provided',
        security: nonce
    },
    success: function(response) {
        // Handle response
    }
});

Helper Functions

/**
 * Check if order has protection
 */
function order_has_protection($order_id) {
    $order = wc_get_order($order_id);
    return $order->get_meta('_safe_ship_pro_protection_added', true) === 'yes';
}

/**
 * Get protection amount for order
 */
function get_protection_amount($order_id) {
    $order = wc_get_order($order_id);
    return floatval($order->get_meta('_safe_ship_pro_protection_amount', true));
}

/**
 * Get claims for order
 */
function get_order_claims($order_id) {
    global $wpdb;
    $table_name = $wpdb->prefix . 'safe_ship_pro_claims';
    
    return $wpdb->get_results($wpdb->prepare(
        "SELECT * FROM $table_name WHERE order_id = %d ORDER BY date_created DESC",
        $order_id
    ));
}

Hooks & Filters

Action Hooks

/**
 * Fired when protection is added to order
 */
do_action('safe_ship_pro_protection_added', $order_id, $protection_amount);

/**
 * Fired before protection fee calculation
 */
do_action('safe_ship_pro_before_fee_calculation', $cart_total);

/**
 * Fired after protection option is displayed
 */
do_action('safe_ship_pro_after_protection_display');

/**
 * Fired when new claim is submitted
 */
do_action('safe_ship_pro_claim_submitted', $claim_id, $order_id);

/**
 * Fired when claim status is updated
 */
do_action('safe_ship_pro_claim_updated', $claim_id, $order_id, $new_status);

/**
 * Fired when claim is approved
 */
do_action('safe_ship_pro_claim_approved', $claim_id, $order_id);

/**
 * Fired when claim is denied
 */
do_action('safe_ship_pro_claim_denied', $claim_id, $order_id, $reason);

Filter Hooks

/**
 * Modify protection fee calculation
 */
$fee = apply_filters('safe_ship_pro_protection_fee', $fee, $cart_total);

/**
 * Customize protection label
 */
$label = apply_filters('safe_ship_pro_protection_label', $label);

/**
 * Modify protection description
 */
$description = apply_filters('safe_ship_pro_protection_description', $description);

/**
 * Control product eligibility
 */
$eligible = apply_filters('safe_ship_pro_product_eligible', $eligible, $product_id);

/**
 * Customize email subjects
 */
$subject = apply_filters('safe_ship_pro_email_subject', $subject, $type, $order_id);

/**
 * Modify email templates
 */
$template = apply_filters('safe_ship_pro_email_template', $template, $type);

/**
 * Filter email recipients
 */
$recipients = apply_filters('safe_ship_pro_email_recipients', $recipients, $type);

Custom Hook Examples

Auto-approve Small Claims

/**
 * Auto-approve claims under $25
 */
function auto_approve_small_claims($claim_id, $order_id) {
    $order = wc_get_order($order_id);
    $order_total = $order->get_total();
    
    if ($order_total < 25) {
        // Auto-approve the claim
        global $wpdb;
        $table_name = $wpdb->prefix . 'safe_ship_pro_claims';
        
        $wpdb->update(
            $table_name,
            ['claim_status' => 'approved', 'admin_notes' => 'Auto-approved (order under $25)'],
            ['id' => $claim_id],
            ['%s', '%s'],
            ['%d']
        );
        
        // Trigger status update action
        do_action('safe_ship_pro_claim_updated', $claim_id, $order_id, 'approved');
    }
}
add_action('safe_ship_pro_claim_submitted', 'auto_approve_small_claims', 10, 2);

Custom Protection Fee Logic

/**
 * Tiered protection fee based on cart value
 */
function tiered_protection_fee($fee, $cart_total) {
    if ($cart_total < 50) {
        return 2.99; // Flat $2.99 for orders under $50
    } else if ($cart_total < 100) {
        return $cart_total * 0.02; // 2% for $50-$100
    } else {
        return min($cart_total * 0.015, 9.99); // 1.5% max $9.99 for $100+
    }
}
add_filter('safe_ship_pro_protection_fee', 'tiered_protection_fee', 10, 2);

Troubleshooting

Common Issues

Debug Mode

Enable WordPress debug mode to troubleshoot issues:

// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

// Log file location
/wp-content/debug.log

Database Issues

Manual Table Creation

If automatic table creation fails, create manually:

CREATE TABLE wp_safe_ship_pro_claims (
    id mediumint(9) NOT NULL AUTO_INCREMENT,
    date_created datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
    date_updated datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
    user_id bigint(20) NOT NULL,
    order_id bigint(20) NOT NULL,
    claim_type varchar(50) NOT NULL,
    claim_reason text NOT NULL,
    claim_status varchar(20) NOT NULL DEFAULT 'pending',
    admin_notes text,
    attachments text,
    PRIMARY KEY (id)
);

Performance Issues

Plugin Conflicts

Common plugin conflicts and solutions:

Frequently Asked Questions