Overview
Custom text destinations allow you to send product feed data to external systems, custom platforms, or internal tools using plain text file formats. Unlike structured formats such as CSV or JSON, custom text destinations give you complete control over the output format, making them suitable for legacy systems, proprietary integrations, or bespoke documentation requirements.
This guide covers destination configuration, field mapping, delivery options, and troubleshooting for custom text file routing.
Destination Configuration
Setting up a custom text destination
Follow these steps to create and configure a new custom text destination.
- Navigate to the destinations section within your feed configuration panel.
- Select 'Create new destination' and choose 'Custom text' as the destination type.
- Enter a descriptive destination name (used internally for reference only).
- Specify the output file format and structure you require.
- Configure the delivery method (HTTP POST, SFTP, email, or file storage).
- Set the field mapping to determine which product attributes map to your custom text format.
- Define any custom delimiters, line breaks, or text separators needed.
- Test the configuration with a sample product before enabling live delivery.
- Set the delivery schedule (immediate, hourly, daily, or on-demand).
- Save and activate the destination.
Destination configuration fields
| Field | Required | Description | Impact on delivery |
|---|---|---|---|
| destination_name | Yes | Internal identifier for the destination | Used in logs and reporting |
| format_type | Yes | Output format structure (plain text, delimited, fixed-width) | Determines how data is formatted |
| delivery_method | Yes | How the file reaches the external system (HTTP, SFTP, email, storage) | Affects speed and reliability |
| field_delimiter | No | Character separating field values (pipe, comma, tab, custom) | Controls data parsing at destination |
| record_delimiter | No | Character separating records (newline, custom sequence) | Determines record boundaries |
| text_encoding | No | Character encoding for output (UTF-8, ISO-8859-1, ASCII) | Ensures special characters display correctly |
| header_row | No | Whether to include column headers in output | Helps destination system identify fields |
| schedule_frequency | Yes | Delivery timing (immediate, hourly, daily, weekly) | Affects data freshness at destination |
| authentication_method | Conditional | Credentials for delivery (API key, username/password, OAuth token) | Required for secure delivery |
| retry_policy | No | Behaviour on delivery failure (retry count, backoff strategy) | Improves reliability for transient failures |
Field Mapping for Custom Text Output
Mapping product attributes
Custom text destinations require explicit field mapping to transform your product data into the required format. Each product attribute from your source feed must be mapped to a corresponding position or label in the custom text output.
Common mapping patterns include:
- Position-based mapping: Fields appear in a fixed order, with each position representing a specific attribute. This works well for fixed-width text formats or simple pipe-delimited outputs.
- Label-based mapping: Each field is preceded by a label or key, useful when the destination system expects named fields rather than positional data.
- Template-based mapping: You define a template string with placeholders for each attribute, allowing complex custom formatting.
Example field mappings
| Source field | Destination field | Transformation | Notes |
|---|---|---|---|
| id | PRODUCT_ID | No transformation | Unique identifier |
| title | PRODUCT_NAME | Uppercase | Used for display |
| price | PRICE_GBP | Decimal format (2 places) | Currency-specific formatting |
| availability | STOCK_STATUS | Map to custom values (In Stock / Out of Stock) | System-specific vocabulary |
| description | PRODUCT_DESC | First 500 characters | Truncate for legacy system limits |
| image_link | IMAGE_URL | No transformation | Direct URL pass-through |
| brand | BRAND_NAME | No transformation | Manufacturer identifier |
| condition | ITEM_CONDITION | Map to custom values (New / Used / Refurbished) | Standardise terminology |
| product_type | CATEGORY | No transformation | Categorical grouping |
| link | PRODUCT_LINK | No transformation | Landing page URL |
Delivery Methods and Options
HTTP POST delivery
HTTP POST sends your custom text file to a specified endpoint on your external system. This method is ideal for real-time integrations and systems that can receive webhook-style deliveries.
Configuration requirements:
- Target URL (must be HTTPS for production)
- HTTP authentication method (Basic Auth, Bearer token, API key header)
- Request timeout (typically 30 seconds)
- Retry configuration (maximum attempts, backoff interval)
Outcome: Data arrives at the destination within seconds, enabling near-real-time synchronisation.
SFTP delivery
SFTP (SSH File Transfer Protocol) uploads your custom text file to a secure server. This method suits organisations with existing SFTP infrastructure or strict security requirements.
Configuration requirements:
- SFTP server hostname and port
- Username and password or SSH key authentication
- Remote directory path
- File naming convention (static or with timestamp)
Outcome: Files are securely transferred to your server at scheduled intervals, with audit logs for compliance.
Email delivery
Email delivery sends the custom text file as an attachment to specified recipients. This option works for smaller datasets or when human review is part of the workflow.
Configuration requirements:
- Recipient email address(es)
- Email subject line template
- Optional message body text
Outcome: Team members receive the feed data directly, reducing dependency on external dashboards.
Cloud storage delivery
Files can be uploaded to cloud storage services (AWS S3, Google Cloud Storage, Azure Blob Storage) for later retrieval or further processing.
Configuration requirements:
- Storage bucket name and region
- Authentication credentials (access keys, service account)
- Directory path within the bucket
- File retention policy
Outcome: Data is available for integration with data warehouses, analytics platforms, or batch processing systems.
Custom Text Format Examples
Pipe-delimited format
This format uses the pipe character (|) to separate fields, with one product per line.
PRODUCT_ID|PRODUCT_NAME|PRICE_GBP|STOCK_STATUS|CATEGORY
12345|Blue Cotton T-Shirt|19.99|In Stock|Apparel
12346|Red Cotton T-Shirt|19.99|In Stock|Apparel
12347|Green Cotton T-Shirt|24.99|Out of Stock|Apparel
This format is easy to parse and works well with legacy systems that expect simple delimited input.
Fixed-width format
Fixed-width formats allocate a specific number of characters to each field, regardless of content length.
ID NAME PRICE STATUS
12345 Blue Cotton T-Shirt 19.99 In Stock
12346 Red Cotton T-Shirt 19.99 In Stock
12347 Green Cotton T-Shirt 24.99 Out of Stock
Fixed-width is useful for systems with strict field position requirements.
Key-value format
Key-value pairs allow flexible field ordering and are easy to read.
id=12345|name=Blue Cotton T-Shirt|price=19.99|status=In Stock|category=Apparel
id=12346|name=Red Cotton T-Shirt|price=19.99|status=In Stock|category=Apparel
id=12347|name=Green Cotton T-Shirt|price=24.99|status=Out of Stock|category=Apparel
This format is self-documenting and forgiving of field order changes.
Practical Guidance for Merchants
Choosing the right delivery method
Select your delivery method based on your external system's capabilities and your operational requirements.
If your destination system has an HTTP API or webhook capability, use HTTP POST for real-time delivery. This minimises latency and keeps data synchronised throughout the day. Ensure your endpoint is monitored for failures and configure appropriate retry logic.
If you have an existing SFTP infrastructure or require encrypted file transfer for compliance reasons, choose SFTP delivery. This method is reliable for batch processing and works well when your system checks for new files at regular intervals.
If your workflow involves human review or approval before data is processed, email delivery keeps stakeholders informed without requiring them to access a separate dashboard. Combine this with a schedule that matches your review cycle.
For integration with data warehouses or analytics platforms, cloud storage delivery provides a central location where multiple systems can access the same data. This reduces the need for point-to-point integrations.
Optimising field mapping for data quality
Your field mappings directly affect how well your destination system can use the data. Map only the fields your destination system actually needs; excess fields slow down processing and increase file size.
For fields with variable length (like product descriptions), set a character limit to prevent oversized records. Truncate gracefully by cutting at word boundaries rather than mid-word.
When mapping to custom values (such as converting availability status to your system's vocabulary), maintain a documented mapping table. This prevents errors if the source values change and helps new team members understand the transformation logic.
Test your mappings with a small product sample before enabling live delivery. Verify that the output format matches your destination system's expectations and that no data is lost or corrupted during transformation.
Monitoring delivery and troubleshooting
After activating a custom text destination, monitor the first few delivery cycles to confirm successful transmission.
Check delivery logs for errors or warnings. Common issues include authentication failures (verify credentials and permissions), network timeouts (increase timeout value or check firewall rules), and format mismatches (review field mappings against destination system documentation).
If delivery fails repeatedly, verify that the destination endpoint or server is accessible from your network. Some organisations require IP address whitelisting; confirm that your delivery service's IP addresses are permitted.
For SFTP deliveries, confirm that the remote directory path exists and that your credentials have write permissions. For HTTP deliveries, test the endpoint URL manually using a tool like curl to isolate whether the issue is with authentication, network connectivity, or the destination system itself.
Scheduling considerations
Your delivery schedule should balance data freshness with the destination system's processing capacity.
For real-time inventory systems, use immediate or hourly delivery to keep stock levels current. This improves accuracy for out-of-stock products and prevents overselling.
For reporting or analytics systems that process data in batches, daily or weekly delivery is typically sufficient and reduces processing overhead.
Consider your source feed's update frequency when setting the destination schedule. If your product data updates only once daily, scheduling custom text delivery more frequently than that wastes bandwidth without providing fresher data.
Validation and Error Handling
Pre-delivery validation
Before sending data to your destination, the system validates each record to catch errors early.
Validation checks include:
- Required fields: Ensures all mandatory fields have values. If a required field is missing, the entire record is flagged and excluded from delivery.
- Data type validation: Confirms that numeric fields contain only numbers and date fields follow the expected format.
- Field length limits: Ensures field values do not exceed maximum lengths defined in your mapping.
- Format compliance: Verifies that the output matches your specified custom text format (correct delimiters, encoding, line breaks).
Records that fail validation are logged separately so you can investigate and correct the source data.
Retry and error recovery
If delivery fails temporarily (network outage, destination server unavailable), the system automatically retries according to your configured retry policy.
Configurable retry options include:
- Maximum retry attempts: How many times to attempt delivery before giving up (typically 3 to 5 attempts).
- Backoff strategy: How long to wait between retries (exponential backoff spaces retries further apart over time, reducing load on the destination system).
- Error notifications: Whether to alert your team if delivery fails after all retries are exhausted.
After retries are exhausted, failed deliveries are logged and can be manually re-triggered once the issue is resolved.
Summary
Custom text destinations provide flexibility for routing product feed data to external systems, legacy platforms, or proprietary integrations. By configuring the appropriate delivery method, defining clear field mappings, and monitoring delivery logs, you ensure that your product data reaches its destination accurately and on schedule.
Start by selecting a delivery method that matches your destination system's capabilities. Define your field mappings carefully, testing with sample data before enabling live delivery. Monitor the first few delivery cycles and adjust your configuration based on any errors or unexpected behaviour.
For ongoing success, document your field mapping logic, maintain your authentication credentials securely, and review delivery logs periodically to catch issues early. If you need to integrate with additional systems or change your delivery schedule, update your destination configuration and re-test before applying changes to live data.