Overview
Custom text integration allows merchants to route product data to destinations using plain text formats with flexible field mapping. This guide explains how to configure custom text sources and destinations, map your product fields, and ensure data reaches the correct endpoint in the format your system requires.
Unlike structured formats such as XML or JSON, custom text destinations give you direct control over field delimiters, line breaks, and output structure. This is particularly useful when integrating with legacy systems, proprietary platforms, or services that require specific text-based input formats.
Understanding Custom Text Sources and Destinations
What is a Custom Text Source?
A custom text source is your incoming product data feed in plain text format. The source defines how your original product information is structured, including which fields are present, how they are separated, and any special formatting rules.
When you configure a custom text source, you specify:
- The field delimiter (comma, tab, pipe, semicolon, or custom character)
- Whether your data includes a header row
- The character encoding (UTF-8, ISO-8859-1, etc.)
- Line termination style (CRLF or LF)
The system uses this configuration to parse your incoming data correctly and extract individual product fields for mapping.
What is a Custom Text Destination?
A custom text destination is where your product data is sent after processing and field mapping. Custom text destinations allow you to transform your data into a specific text format required by a third-party system, partner platform, or internal process.
Custom text destinations are configured separately from sources. You define the output format, field order, and delimiter structure that the receiving system expects. This separation of source and destination configuration gives you flexibility to accept data in one format and deliver it in another.
Field Mapping for Custom Text Integration
Basic Mapping Principles
Field mapping connects your source product fields to destination fields. For custom text integration, this means specifying which source field should populate each position in your output text file.
Consider this example:
- Your source data has fields: product_id, product_name, price, stock_level
- Your destination requires: id, title, cost, availability
You would map source product_id to destination id, source product_name to destination title, and so on. The system then outputs each product record using the destination field order and delimiter.
Handling Missing or Optional Fields
When a source field is empty or missing, the destination text still needs to maintain proper structure. Configure how the system handles gaps:
- Empty string (leaves the field blank but preserves delimiters)
- Default value (inserts a fallback value like 'N/A' or '0')
- Field omission (removes the field from that record)
Choosing the correct handling method prevents parsing errors on the receiving end and ensures data integrity.
Field Transformation Rules
Custom text destinations often require field values in specific formats. Common transformations include:
- Price formatting (remove currency symbols, set decimal places to 2)
- Date conversion (output dates as DD/MM/YYYY or timestamp)
- Text encoding (escape special characters, remove line breaks from descriptions)
- Boolean conversion (output true/false as 1/0 or yes/no)
- URL encoding (encode spaces and special characters in URLs)
Apply transformation rules during mapping to ensure the receiving system can parse your data without errors.
Configuring Custom Text Sources
Step 1: Define Source Structure
Examine your incoming product feed and identify:
- What character separates fields (comma, tab, pipe, etc.)
- Whether the first row contains field names or product data
- Total number of fields per record
- Any fields that may be empty for some products
Step 2: Set Encoding and Line Termination
Specify the character encoding your source file uses. Most modern systems use UTF-8, but legacy systems may use ISO-8859-1 or Windows-1252. Incorrect encoding causes special characters and non-ASCII text to display as corrupted symbols.
Set line termination to match your source format. Windows systems typically use CRLF (carriage return + line feed), while Unix/Linux systems use LF (line feed only).
Step 3: Map Source Fields
For each column in your source data, assign a field name. These names are used when creating destination mappings. Use clear, descriptive names like 'product_id', 'product_name', 'price', 'description', 'image_url', 'availability'.
If your source file includes a header row, the system can auto-detect field names. If not, manually enter them in the order they appear in your data.
Configuring Custom Text Destinations
Step 1: Define Output Structure
Determine the exact format your destination system requires:
- Which fields must be included and in what order
- What character should separate fields
- Whether to include a header row
- Any special formatting for specific fields
Obtain this specification from your destination platform's technical documentation or integration team.
Step 2: Set Destination Field Order
Custom text destinations output fields in the order you specify. List destination fields in the exact sequence required by the receiving system. The order matters: the first destination field receives data from the first mapped source field, the second destination field from the second mapped source, and so on.
Step 3: Configure Delimiter and Formatting
Select the delimiter that separates fields in your output text:
- Comma (CSV format)
- Tab (TSV format)
- Pipe character (|)
- Semicolon
- Custom character
Choose the delimiter your destination system expects. Using the wrong delimiter causes the receiving system to misparse your data.
Specify whether to include a header row. Some systems require column names in the first row; others expect data only. Check your destination's requirements.
Practical Implementation Workflow
For Merchants Setting Up Custom Text Distribution
-
Contact your destination system provider and obtain their text format specification. This should detail field names, order, delimiters, and any required transformations.
-
Export a sample of your product data in its current format (CSV, JSON, XML, or database export).
-
In your feed management system, create a custom text source using your current data format. Parse a sample file to verify the source configuration correctly reads your fields.
-
Create a custom text destination matching your destination system's specification. Enter destination field names in the required order.
-
Map each source field to the corresponding destination field. Apply any necessary transformations (price formatting, date conversion, etc.).
-
Generate a test export with a small batch of products (10-20 records). Manually verify the output matches your destination's format specification.
-
Submit the test file to your destination system's validation tool or import process. Confirm that the system parses all fields correctly and products are created without errors.
-
If validation passes, configure the full feed export. Set the update frequency (daily, weekly, real-time) based on your destination's requirements.
-
Monitor the first few exports for errors or data quality issues. Check your destination system's logs or dashboard to confirm products are being received and processed.
Troubleshooting Common Issues
Delimiter mismatch: If the destination system reports parsing errors or creates products with combined fields, verify you selected the correct delimiter. Re-export with the delimiter your destination actually requires.
Missing fields: If some products lack required data, check whether your source contains that field. If not, configure a default value during destination mapping so every product has a value for required fields.
Character encoding errors: If special characters (accents, symbols, non-ASCII text) appear corrupted in the destination system, verify your source encoding matches the encoding setting in your custom text source configuration.
Field order problems: If the destination system creates products with incorrect field assignments, double-check that destination fields are listed in the exact order your destination system expects.
Summary
Custom text integration provides flexibility for merchants who need to deliver product data in plain text formats to third-party systems or legacy platforms. Success depends on precise configuration of your source and destination formats, accurate field mapping, and applying necessary data transformations.
Start by obtaining your destination system's exact format specification. Configure your custom text source to correctly parse your incoming product data. Create a matching custom text destination with the required field order and delimiters. Map source fields to destination fields with appropriate transformations. Test with a small batch of products before enabling full export.
This approach ensures your product data reaches your destination system in the correct format, ready for immediate processing and use.