Custom CSV Configuration: Technical Documentation and Field Mapping

Overview

Custom CSV configuration allows merchants to export product data in a tailored format suited to specific distribution channels, internal systems, or custom workflows. Rather than conforming to a single predefined feed structure, you can define which fields to include, how to label them, and where the exported file should be stored or delivered.

This article covers the technical setup of custom CSV destinations, field configuration options, and practical implementation steps to ensure data integrity and successful delivery.

Understanding Custom CSV Destinations

A custom CSV destination is a technical configuration that defines:

• Which product fields to include in the export
• Column headers and naming conventions
• Data formatting and delimiter rules
• File storage location or delivery endpoint
• Export frequency and scheduling
• Data transformation rules (if applicable)

Unlike standard channel integrations that enforce specific field requirements, custom CSV gives you control over the output structure. This flexibility is valuable when:

• Integrating with proprietary systems that expect a particular column layout
• Feeding data to multiple channels with different field requirements
• Creating internal reporting or analytics files
• Preparing data for manual review or compliance checks
• Exporting to systems that do not support standard feed formats

Setting Up Your Custom CSV Configuration

Defining the Destination

When you create a new custom CSV destination, you specify:

• Destination name: A clear internal identifier for this export configuration
• File format: CSV encoding, delimiter (comma, semicolon, tab), and quote handling
• Storage location: Where the file will be saved or delivered (SFTP, cloud storage, API endpoint, or local directory)
• Authentication credentials: If required by your storage destination
• File naming pattern: Static name or dynamic naming using timestamps or other variables

Selecting and Mapping Fields

Product data fields must be explicitly selected for inclusion in the CSV. Common fields available for mapping include:

• id: Unique product identifier (required for most use cases)
• title: Product name or headline
• description: Full product description or summary
• price: Current selling price
• brand: Manufacturer or brand name
• gtin: Global Trade Item Number (EAN, UPC, ISBN)
• mpn: Manufacturer Part Number
• image_link: Primary product image URL
• link: Product landing page URL
• availability: Stock status (in stock, out of stock, preorder)
• condition: Product condition (new, refurbished, used)
• google_product_category: Category classification
• product_type: Internal product category
• item_group_id: Variant grouping identifier

For each field, you define:

• Column header: The exact name that will appear in the CSV (e.g., 'Product ID', 'SKU', 'Item Code')
• Data source: Which product field to pull data from
• Transformation rules: Any formatting, filtering, or calculation applied before export (currency conversion, text truncation, conditional logic)
• Default value: Fallback data if the source field is empty

Configuring Data Transformations

Custom CSV destinations support data transformation at export time:

• Text formatting: Convert to uppercase, lowercase, title case, or trim whitespace
• Numeric formatting: Set decimal places for prices, apply currency symbols, or multiply values
• Conditional logic: Include or exclude rows based on field values (e.g., export only items marked as 'in stock')
• String concatenation: Combine multiple fields into a single column (e.g., brand + product type)
• URL encoding: Escape special characters in URLs or text fields
• Date formatting: Standardise date output to match expected format (DD/MM/YYYY)

Technical Documentation Destination Setup

When configuring a custom CSV as a technical documentation destination, ensure that:

1. Field definitions are documented: Maintain a data dictionary describing each column, its source, and any transformations applied
2. Validation rules are clear: Document which fields are required, which are optional, and any format constraints
3. Error handling is specified: Define how missing data, invalid values, or transformation failures are handled
4. Audit trails are maintained: Log export timestamps, record counts, and any data quality issues detected
5. Schema stability is managed: Version your CSV configuration so downstream systems can adapt when fields or formats change

CSV Integration Workflows

Export Scheduling and Delivery

Custom CSV destinations support multiple delivery mechanisms:

• Scheduled exports: Automatic file generation on a defined schedule (hourly, daily, weekly)
• Event-triggered exports: File generation when product data changes
• Manual exports: On-demand file generation via API or user interface
• Incremental exports: Only changed records since the last export (delta feeds)
• Full exports: Complete product catalogue every run

Delivery options include:

• SFTP: Secure file transfer to a remote server
• HTTP POST: Send the file to an API endpoint
• Cloud storage: Upload to AWS S3, Google Cloud Storage, or Azure Blob Storage
• Email: Deliver the file as an attachment
• Local storage: Save to a directory accessible to your systems

Data Quality and Validation

Before delivery, the export process validates:

• Field completeness: Checks that required fields contain data
• Format compliance: Ensures dates, numbers, and URLs match expected patterns
• Encoding integrity: Verifies that special characters are correctly escaped
• Row count thresholds: Alerts if the export contains significantly fewer records than expected
• Duplicate detection: Identifies and handles duplicate product records

If validation fails, the system can:

• Halt export and notify administrators
• Deliver the file with a warning log
• Automatically retry after a delay
• Fallback to the previous successful export

Practical Implementation Guidance

Step 1: Audit Your Data Requirements

Before creating a custom CSV configuration, document what your destination system actually needs:

• List every field the downstream system expects
• Note the exact column header names
• Specify required data format (e.g., prices as '10.99' or '10,99')
• Identify any fields that need transformation or combination
• Confirm whether the system needs all products or a filtered subset

Step 2: Create the Destination Configuration

In your feed management interface:

1. Navigate to Destinations or Custom Exports
2. Select 'Create New Custom CSV Destination'
3. Enter a descriptive name (e.g., 'Internal Analytics Export' or 'Affiliate Network Feed')
4. Choose your storage method and enter connection details
5. Set the file naming pattern and export schedule
6. Save the destination configuration

Step 3: Map Product Fields

For each field required by your destination:

1. Add a new field mapping
2. Enter the exact column header name
3. Select the source product field
4. Configure any transformation rules
5. Set a default value if the field may be empty
6. Mark the field as required or optional
7. Test the mapping with sample data

Step 4: Test and Validate

1. Generate a test export with a small product sample
2. Verify the CSV structure matches expectations
3. Check that data transformations are applied correctly
4. Confirm the file is delivered to the correct location
5. Validate that downstream systems can read and process the file
6. Monitor the first few scheduled exports for errors

Step 5: Monitor and Maintain

• Review export logs regularly for validation warnings or delivery failures
• Track record counts to detect unexpected data loss
• Update field mappings if product data structure changes
• Document any changes to the configuration for audit purposes
• Test recovery procedures if exports fail

Destination Management Architecture

Custom CSV destinations are managed through:

• Configuration API: Programmatic creation and modification of destinations
• File transfer protocols: SFTP, HTTPS, cloud storage SDKs for delivery
• Scheduling engine: Cron-like scheduling for automated exports
• Transformation engine: Rules-based data processing before export
• Logging and monitoring: Audit trails, error notifications, and performance metrics
• Access control: Role-based permissions for viewing, creating, and modifying destinations

Common Use Cases

Internal Analytics: Export product catalogue to your data warehouse with custom column names and aggregated metrics.

Multi-channel Distribution: Create separate CSV exports for different affiliate networks, each with its own field requirements and formatting rules.

Compliance and Reporting: Generate regulatory reports with specific fields, date ranges, and calculated values.

Inventory Synchronisation: Export stock levels and SKUs to your warehouse management system in the exact format it expects.

Content Management: Feed product data to your website CMS with descriptions, images, and category mappings.

Summary

Custom CSV configuration provides the flexibility to export product data in any structure your business requires. By carefully mapping fields, defining transformations, and testing delivery, you can integrate with systems that do not support standard feed formats. Document your configuration thoroughly, monitor exports for errors, and maintain version control over schema changes. This approach ensures reliable data flow to internal systems, reporting tools, and custom integrations.