README

Channel Lister

Streamlined Multi-Channel eCommerce Product Listing Tool

Channel Lister is a modern Laravel package that simplifies multi-channel eCommerce product listing management. Evolved from the Channel Advisor Master Lister (CAML), it provides a guided product creation experience with dynamic marketplace integration, featuring Amazon SP-API support for real-time listing requirements and automated CSV/JSON export generation.

✨ Key Features

🛒 Multi-Channel Support - Create listings for multiple eCommerce marketplaces
🔄 Dynamic Forms - Auto-generated forms based on real-time marketplace requirements
📊 Amazon SP-API Integration - Native integration with Amazon's Selling Partner API
📝 Flexible Field System - Custom and marketplace-specific field definitions
📋 Smart Validation - Real-time validation with progress tracking
📄 Multiple Export Formats - CSV and JSON export for various platforms
🔍 Existing Listing Lookup - Pre-populate forms from existing marketplace data
📦 Shipping Cost Calculator - Real-time shipping cost calculations with ShipEngine API
⚡ Modern Stack - Built with Laravel, Pest testing, and modern PHP 8.3+

Requires PHP 8.3+

🚀 Quick Start

Install via Composer:

composer require ige/channel-lister

⚡ Automatic Installation (Recommended)

Use the install command for automatic setup:

php artisan channel-lister:install

This command will:

📦 Publish the service provider
🎨 Publish package assets
👁️ Publish customizable views
⚙️ Publish configuration files
🗄️ Publish database migrations
🔧 Automatically register the service provider (supports Laravel 8/9/10/11+)

After installation, run the migrations:

php artisan migrate

🎯 Granular Publishing (Advanced)

For more control over what gets published, you can use specific tags:

📋 Views Only - Customize UI components

php artisan vendor:publish --tag=channel-lister-views

Publishes to: resources/views/vendor/channel-lister/
Use case: Customize field management interface, form components, and layouts

🎨 Frontend Assets Only - For custom build processes

php artisan vendor:publish --tag=channel-lister-frontend-assets

Publishes to: resources/css/vendor/channel-lister/ and resources/js/vendor/channel-lister/
Use case: Integrate with Vite, Webpack, or other build tools

📦 Everything - Complete control

php artisan vendor:publish --tag=channel-lister-resources

Publishes to: resources/vendor/channel-lister/
Use case: Full customization of all resources

🔧 Individual Components

# Configuration only
php artisan vendor:publish --tag=channel-lister-config

# Database migrations only
php artisan vendor:publish --tag=channel-lister-migrations

# Public assets only
php artisan vendor:publish --tag=channel-lister-assets

🛠️ Manual Installation (Alternative)

Alternatively, you can install manually by publishing everything:

php artisan vendor:publish --provider="IGE\ChannelLister\ChannelListerServiceProvider"

Then run the migrations:

php artisan migrate

🛠️ Development Commands

Code Quality & Testing

🚀 Run the entire test suite:

composer test

✅ Run unit tests using PEST:

composer test:unit

⚗️ Run static analysis using PHPStan:

composer test:types

Code Formatting & Refactoring

🧹 Format code with Laravel Pint:

composer lint

✅ Refactor code using Rector:

composer refacto

Development Server

🌐 Launch development server:

composer serve

🗑️ Clear caches:

composer clear

📦 Build assets:

composer build

📊 Amazon SP-API Integration

Channel Lister features comprehensive Amazon Selling Partner API (SP-API) integration for dynamic listing creation. This powerful feature enables:

Search for Amazon product types
Fetch dynamic listing requirements from Amazon
Look up existing listings by identifier (ASIN, GTIN, UPC, EAN, ISBN)
Generate marketplace-specific forms dynamically

⚙️ Configuration

Add the following environment variables to your .env file:

# Amazon SP-API Configuration
AMAZON_SP_API_BASE_URL=https://sellingpartnerapi-na.amazon.com
AMAZON_MARKETPLACE_ID=ATVPDKIKX0DER
AMAZON_SP_API_REGION=us-east-1
AMAZON_SP_API_CLIENT_ID=your_client_id_here
AMAZON_SP_API_CLIENT_SECRET=your_client_secret_here
AMAZON_SP_API_REFRESH_TOKEN=your_refresh_token_here

# Shipping Calculator (Optional)
CHANNEL_LISTER_SHIPSTATION_API_KEY=your_shipengine_api_key_here
CHANNEL_LISTER_SHIPSTATION_BASE_URL=https://api.shipengine.com/v1

Note: The system now uses OAuth 2.0 with automatic token refresh. You only need to provide your client credentials and refresh token - access tokens are managed automatically.

📋 Usage

Product Type Search: Use the Amazon product type search component to find and select the appropriate product type for your listing.
Dynamic Form Generation: Once a product type is selected, the system will fetch the listing requirements from Amazon SP-API and generate the appropriate form fields.
Existing Listing Lookup: Enter an identifier (ASIN, GTIN, etc.) to look up and pre-populate form fields from an existing Amazon listing.

🔗 API Endpoints

Product Type & Requirements:

POST /api/amazon-listing/search-product-types - Search for Amazon product types
POST /api/amazon-listing/listing-requirements - Get listing requirements for a product type
POST /api/amazon-listing/existing-listing - Look up existing listing by identifier

Form Submission & Management:

POST /api/amazon-listing/submit - Submit listing form data
POST /api/amazon-listing/validate - Validate a listing
POST /api/amazon-listing/generate-file - Generate CSV/JSON files
GET /api/amazon-listing/listings - Get all listings with pagination
GET /api/amazon-listing/listings/{id} - Get specific listing details
GET /api/amazon-listing/listings/{id}/download - Download generated files

🔐 Token Management

The system includes robust SP-API token management with:

Automatic token refresh - Tokens are refreshed automatically before expiration
Caching - Valid tokens are cached to reduce API calls
Error handling - Comprehensive error handling for authentication failures
Rate limiting - Built-in protection against API rate limits
Debugging - Console command for checking token status

Debug Token Status

Use the console command to check your Amazon SP-API token status:

php artisan channel-lister:amazon-token-status

# Force refresh token
php artisan channel-lister:amazon-token-status --refresh

Authentication Flow

Initial Setup: Configure your client credentials and refresh token
Automatic Management: The system automatically obtains and refreshes access tokens
Request Authentication: All SP-API calls are automatically authenticated
Error Recovery: Failed authentication attempts trigger automatic token refresh

📝 Form Submission Workflow

The system provides a complete workflow for creating Amazon listings:

1. Product Type Selection

Search and select appropriate Amazon product type
System fetches dynamic listing requirements from SP-API
Form fields are generated based on Amazon's current requirements

2. Form Completion

Fill out dynamically generated form fields
Real-time validation feedback
Progress tracking showing completion percentage
Support for existing listing lookup and pre-population

3. Validation & Processing

Save Draft: Store form data without validation
Validate: Comprehensive validation against Amazon requirements
Business Rules: SKU uniqueness, price validation, dimension consistency
Required Fields: Automatic detection of missing required fields

4. File Generation

CSV Export: Amazon-compatible CSV format for bulk upload
JSON Export: Structured data for API integration
Field Mapping: Automatic mapping to Amazon feed column names
Data Transformation: Amazon-specific formatting (prices, dimensions, etc.)

5. Download & Submission

Secure file downloads with proper MIME types
Files ready for Amazon Seller Central upload
Persistent storage with listing history

✅ Validation Features

Amazon Requirements: Dynamic validation based on current SP-API requirements
Field Types: String, numeric, boolean, enum validation
Constraints: Length limits, regex patterns, value ranges
Business Logic: SKU uniqueness, price consistency, dimension validation
Real-time Feedback: Instant validation results and progress tracking

📦 Shipping Cost Calculator

Channel Lister includes a powerful shipping cost calculator that integrates with ShipEngine API to provide real-time shipping rates from major carriers (UPS, FedEx, USPS). This feature helps sellers accurately estimate shipping costs for their products, improving pricing decisions and customer experience.

✨ Features

Real-time Rate Shopping - Get live rates from multiple carriers simultaneously
Dimensional Weight Calculation - Automatic calculation for different carrier divisors
IP Geolocation - Detect origin location automatically from user's IP
Manual Entry Fallback - Enter shipping costs manually when API is unavailable
Smart Integration - Seamlessly integrated into cost-related form fields
Carrier Comparison - Compare rates across UPS, FedEx, and USPS
Auto-fill Dimensions - Pull package dimensions from existing form fields

⚙️ Configuration

Add the following environment variables to your .env file:

# ShipEngine API Configuration
CHANNEL_LISTER_SHIPSTATION_API_KEY=your_shipengine_api_key_here
CHANNEL_LISTER_SHIPSTATION_BASE_URL=https://api.shipengine.com/v1

Note: The system gracefully handles missing API keys by providing manual entry options for shipping costs. ShipEngine API usage incurs costs based on your plan - see ShipEngine pricing for details.

📋 Usage

The shipping calculator appears as an integrated button within cost-related form fields:

Automatic Detection: Click "Calculate Shipping" button on any shipping cost field
Location Setup: System detects your location via IP or enter ZIP codes manually
Package Details: Enter dimensions (length, width, height) and weight
Auto-fill: Use existing form data to populate dimensions automatically
Rate Comparison: View rates from multiple carriers sorted by price
Selection: Click desired rate to populate the form field

🔗 API Endpoints

Shipping Calculator Endpoints:

GET /api/shipping/check-api - Check if ShipEngine API key is available
GET /api/shipping/location - Get user location from IP address
POST /api/shipping/calculate - Calculate shipping rates for package
GET /api/shipping/carriers - Get available carriers from ShipEngine
POST /api/shipping/dimensional-weight - Calculate dimensional weight only

📊 Dimensional Weight Calculation

The system automatically calculates dimensional weight using carrier-specific divisors:

UPS Commercial: 139 cubic inches per pound
FedEx: 139 cubic inches per pound
USPS: 166 cubic inches per pound

Billable Weight: The greater of actual weight or dimensional weight is used for rate calculation.

🎯 Integration Details

The shipping calculator integrates seamlessly with the form system:

Field Detection: Automatically appears on fields with "shipping", "cost", or similar names
Modal Interface: Clean, user-friendly modal with step-by-step workflow
Responsive Design: Works on desktop and mobile devices
Error Handling: Graceful fallbacks when API is unavailable
Caching: Efficient rate caching to minimize API calls

💡 Manual Entry Mode

When ShipEngine API is not configured or unavailable:

System automatically switches to manual entry mode
Users can enter estimated shipping costs directly
All functionality remains available without API dependency
Clear messaging indicates manual entry is required

🔧 Development & Testing

The shipping calculator includes comprehensive test coverage and follows Laravel best practices:

Service Layer: Clean separation of concerns with ShippingCalculatorService
API Integration: Robust HTTP client with error handling
Form Components: Reusable Blade components with JavaScript integration
Validation: Input validation for dimensions, ZIP codes, and weights
Testing: Full test suite covering happy paths and error conditions

🔧 Form Field Configuration & Customization

Channel Lister provides a powerful and flexible form field system that allows you to fully customize the listing creation experience. You can manage fields for different marketplaces, add new marketplaces, and customize field behavior through the ChannelListerField model and management interface.

⚡ Quick Setup with Default Fields

Use the seeding command to populate your database with pre-configured fields for ChannelAdvisor/Rithum and Amazon:

php artisan channel-lister:seed-fields

Command Options:

--force - Force seeding even if fields already exist (overwrites existing fields)

What this command does:

📦 Seeds 27 default fields for common marketplace operations
🏪 Includes fields for ChannelAdvisor/Rithum integration
🛒 Includes Amazon-specific product type fields
⚙️ Sets up proper field ordering, validation, and grouping
🔄 Handles different input types (text, select, currency, etc.)

🎛️ Field Management Interface

Access the field management interface via the channel-lister-field routes:

Available Routes:

// Web interface for field management
Route::resource('/channel-lister-field', ChannelListerFieldController::class)

Management Operations:

📋 List Fields - /channel-lister-field - View all fields with filtering by marketplace
➕ Create Field - /channel-lister-field/create - Add new custom fields
👁️ View Field - /channel-lister-field/{id} - View field details
✏️ Edit Field - /channel-lister-field/{id}/edit - Modify existing fields
🗑️ Delete Field - /channel-lister-field/{id} - Remove fields (with confirmation)

📊 ChannelListerField Model

The ChannelListerField model is the core of the field system:

Model Attributes:

$field = new ChannelListerField([
    'ordering' => 1,                    // Display order (integer)
    'field_name' => 'Product Title',    // Internal field name
    'display_name' => 'Title',          // User-facing label
    'tooltip' => 'Enter product title', // Help text
    'example' => 'Blue Widget Pro',     // Example value
    'marketplace' => 'amazon',          // Target marketplace
    'input_type' => 'text',            // Field input type
    'input_type_aux' => null,          // Additional input options
    'required' => true,                // Whether field is required
    'grouping' => 'Product Details',   // Form section grouping
    'type' => 'custom',               // Field type (custom/channeladvisor)
]);

Available Input Types:

text - Standard text input
textarea - Multi-line text input
select - Dropdown selection (uses input_type_aux for options)
checkbox - Boolean checkbox
currency - Currency input with formatting
decimal - Decimal number input
integer - Whole number input
url - URL input with validation
comma-separated - Multi-value comma-separated input
custom - Special custom components (UPC generator, shipping calculator, etc.)
alert - Display informational alerts

Field Types:

custom - User-defined fields for specific business needs
channeladvisor - Fields designed for ChannelAdvisor/Rithum integration

Useful Scopes:

// Get fields for specific marketplace
ChannelListerField::forMarketplace('amazon')->get();

// Get only required fields
ChannelListerField::required()->get();

// Get fields by grouping
ChannelListerField::byGrouping('Product Details')->get();

// Get ordered fields
ChannelListerField::ordered()->get(); // ascending
ChannelListerField::ordered('desc')->get(); // descending

// Chain scopes for complex queries
ChannelListerField::forMarketplace('ebay')
    ->required()
    ->ordered()
    ->get();

🛒 Adding New Marketplaces

You can easily add support for new marketplaces by creating fields with custom marketplace keys:

// Add fields for a new marketplace (e.g., 'etsy')
ChannelListerField::create([
    'ordering' => 1,
    'field_name' => 'Etsy Category',
    'display_name' => 'Product Category',
    'marketplace' => 'etsy',           // New marketplace key
    'input_type' => 'select',
    'input_type_aux' => 'Clothing||Electronics||Home & Garden',
    'required' => true,
    'grouping' => 'Etsy Specific',
    'type' => 'custom',
]);

Marketplace Display Names:

The system automatically generates display names for marketplaces using the ChannelLister::marketplaceDisplayName() method:

amazon → "Amazon"
ebay → "eBay"
walmart → "Walmart"
custom-marketplace → "Custom Marketplace"

🔧 Advanced Field Configuration

Select Field Options:

For select fields, use the input_type_aux field to define options:

// Simple options
'input_type_aux' => 'Small||Medium||Large'

// Key-value pairs
'input_type_aux' => 'sm==Small||md==Medium||lg==Large'

// From code
$field->input_type_aux = ['Option 1', 'Option 2', 'Option 3'];

Custom Field Components:

Special custom components are available via the custom input type:

// UPC generator component  
'input_type' => 'custom',
'input_type_aux' => '', // UPC generation logic

// Amazon product type search
'input_type' => 'custom', 
'input_type_aux' => 'amazon-product-type-search',

// Shipping cost calculator
'field_name' => 'Cost Shipping',
'input_type' => 'custom', // Automatically triggers shipping calculator

Validation Patterns:

Use input_type_aux for regex validation on text fields:

'input_type' => 'text',
'input_type_aux' => '^[A-Z0-9-]{5,20}$', // SKU format validation

🎯 Practical Examples

Example 1: Adding Shopify Support

// Create Shopify-specific fields
$fields = [
    [
        'ordering' => 1,
        'field_name' => 'shopify_handle',
        'display_name' => 'URL Handle', 
        'marketplace' => 'shopify',
        'input_type' => 'text',
        'required' => true,
        'grouping' => 'Shopify Settings',
        'type' => 'custom',
    ],
    [
        'ordering' => 2,
        'field_name' => 'shopify_tags',
        'display_name' => 'Product Tags',
        'marketplace' => 'shopify', 
        'input_type' => 'comma-separated',
        'required' => false,
        'grouping' => 'Shopify Settings',
        'type' => 'custom',
    ],
];

foreach ($fields as $field) {
    ChannelListerField::create($field);
}

Example 2: Custom Validation Field

ChannelListerField::create([
    'ordering' => 10,
    'field_name' => 'model_number',
    'display_name' => 'Model Number',
    'tooltip' => 'Enter manufacturer model number (letters, numbers, hyphens only)',
    'example' => 'ABC-123-XYZ',
    'marketplace' => 'common',
    'input_type' => 'text',
    'input_type_aux' => '^[A-Z0-9-]{3,50}$', // Validation regex
    'required' => true,
    'grouping' => 'Product Information',
    'type' => 'custom',
]);

Example 3: Dynamic Select Field

ChannelListerField::create([
    'ordering' => 5,
    'field_name' => 'condition',
    'display_name' => 'Product Condition',
    'marketplace' => 'common',
    'input_type' => 'select',
    'input_type_aux' => 'new==New||used-like-new==Used - Like New||used-good==Used - Good||used-acceptable==Used - Acceptable',
    'required' => true,
    'grouping' => 'Product Details',
    'type' => 'custom',
]);

🔍 Field Management Best Practices

📋 Consistent Ordering - Use meaningful ordering values (10, 20, 30) to allow easy insertion
🏷️ Clear Naming - Use descriptive field_name and display_name values
📝 Helpful Tooltips - Provide context and examples for complex fields
🎯 Logical Grouping - Group related fields together for better UX
✅ Proper Validation - Use appropriate input types and validation patterns
🌍 Marketplace Specific - Use marketplace keys consistently across your application

🔧 Programmatic Field Management

// Create fields programmatically
$marketplaceFields = [
    'tiktok' => [
        ['field_name' => 'tiktok_category', 'display_name' => 'TikTok Category'],
        ['field_name' => 'tiktok_hashtags', 'display_name' => 'Hashtags'],
    ]
];

foreach ($marketplaceFields as $marketplace => $fields) {
    foreach ($fields as $index => $fieldData) {
        ChannelListerField::create(array_merge($fieldData, [
            'marketplace' => $marketplace,
            'ordering' => ($index + 1) * 10,
            'input_type' => 'text',
            'required' => false,
            'grouping' => ucfirst($marketplace) . ' Settings',
            'type' => 'custom',
        ]));
    }
}

This flexible field system allows you to adapt Channel Lister to any marketplace or business requirement while maintaining a consistent, user-friendly interface.

📄 License

This package is open-sourced software licensed under the MIT license.

🙏 Credits

Originally evolved from the Channel Advisor Master Lister (CAML)
Built with Laravel framework
Testing powered by Pest PHP
Package structure based on Laravel Package Skeleton by Spatie

📞 Support

For support, issues, or feature requests, please open an issue on GitHub.

tr3mulant / channel-lister

Maintainers

Package info

Statistics

Security

README

Channel Lister

✨ Key Features

🚀 Quick Start

⚡ Automatic Installation (Recommended)

🎯 Granular Publishing (Advanced)

📋 Views Only - Customize UI components

🎨 Frontend Assets Only - For custom build processes

📦 Everything - Complete control

🔧 Individual Components

🛠️ Manual Installation (Alternative)

🛠️ Development Commands

Code Quality & Testing

Code Formatting & Refactoring

Development Server

📊 Amazon SP-API Integration

⚙️ Configuration

📋 Usage

🔗 API Endpoints

🔐 Token Management

Debug Token Status

Authentication Flow

📝 Form Submission Workflow

1. Product Type Selection

2. Form Completion

3. Validation & Processing

4. File Generation

5. Download & Submission

✅ Validation Features

📦 Shipping Cost Calculator

✨ Features

⚙️ Configuration

📋 Usage

🔗 API Endpoints

📊 Dimensional Weight Calculation

🎯 Integration Details

💡 Manual Entry Mode

🔧 Development & Testing

🔧 Form Field Configuration & Customization

⚡ Quick Setup with Default Fields

🎛️ Field Management Interface

📊 ChannelListerField Model

Model Attributes:

Available Input Types:

Field Types:

Useful Scopes:

🛒 Adding New Marketplaces

🔧 Advanced Field Configuration

Select Field Options:

Custom Field Components:

Validation Patterns:

🎯 Practical Examples

Example 1: Adding Shopify Support

Example 2: Custom Validation Field

Example 3: Dynamic Select Field

🔍 Field Management Best Practices

🔧 Programmatic Field Management

📄 License

🙏 Credits

📞 Support