Implementation

For an FTP/Email integration, there are three main steps you'll need to consider:

• Capture the im_ref query string parameter value: the exact method in which you capture and store this value is up to your discretion and specific requirements. This is a required parameter when submitting conversion data — impact.com uses this value (and others) for attribution.
• Create a .CSV file: impact.com provides examples and a full parameter reference for conversion data that you can customize to include the specific conversion data needed.
• Submit the .CSV file: depending on your event type, you'll submit your .CSV file either via Impact FTP/FTPS/SFTP (i.e., upload a file to an impact.com FTP server), submit your .CSV file via email (i.e., sent to a specific address as an attachment that then uploads the file via FTP), or instruct impact.com to pull the file from your own FTP server.

Capture & store im_ref

impact.com will dynamically populate an im_ref value in your landing page URL (e.g. https://www.example.com/store/product1?im_ref=1234567) when visitors are directed to your site from an impact.com tracking link. The query string parameter name is im_ref.

The im_ref value should be captured and stored in the browser (e.g., in a first-party cookie) and available if the same visitor returns directly to your site in another session.

If, during the customer journey, the website URL changes from one domain to another, the stored im_ref value should be passed and stored under the new domain.

Create a .CSV file

Reporting conversions at the item level is generally recommended for most circumstances. At a minimum, impact.com expects an item-level conversion data .CSV file to have the following headers:

CampaignId,ActionTrackerId,EventDate,OrderId,ClickId,CustomerId,CurrencyCode,Amount,Category,Sku,Quantity

Tip: It's highly recommended to include as much data as possible – refer to the full Conversions Data Reference document for a full list of conversion data parameters.

Parameter	Description
CampaignId	A unique identifier for your impact.com account's Program (or CampaignId). Available in your Tech Plan document.
ActionTrackerId	A unique identifier for your impact.com account's Event Type (or Action Tracker). Available in your Tech Plan document.
EventDate	The time, date, and time zone of when the event occurred in ISO 8601 format. This value cannot be older than 88 days — impact.com doesn't process conversions with an event date older than 88 days from the date submitted.
OrderId	The unique identifier for the order associated with this conversion. Typically generated by your site's e-commerce system.
PromoCode	(Optional) A promotional code associated with the conversion. Can be used as an alternative attribution method if configured in your program.
ClickId	The unique identifier for the visitor that converted. Appended as the query string parameter im_ref to your site's landing page when they first visit.
CustomerId	A unique identifier for the visitor that converted — typically an ID that your site or e-commerce system assigns to a visitor. Do not use personally identifiable information (PII).
FirstPartyProfileId	(Optional) A first-party identifier for the visitor. Used as an alternative attribution signal when ClickId is unavailable.
MediaPartnerId	(Optional) The impact.com ID of the partner to attribute this conversion to. Use when ClickId is unavailable and you know the partner.
CurrencyCode	Three-letter ISO 4217 code for the currency used in the conversion.
Amount	The subtotal of the item as set by the SKU. This value is pre-tax, pre-shipping, and pre-discounts.
Category	The name of the category that the item belongs to.
Sku	The stock-keeping unit assigned to the item.
Quantity	The quantity of this item within the order.

Each item within an order should be submitted as a new line in the file:

CampaignId,ActionTrackerId,EventDate,OrderId,ClickId,CustomerId,CurrencyCode,Amount,Category,Sku,Quantity
1000,4321,2021-11-23T18:00:22+00:00,01928374,QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0,BCZ2WVSH674563PDPYOTM3AXDQ,USD,42.50,Blacksmithing,A-198237465,1
1000,4321,2021-11-23T18:00:22+00:00,01928374,QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0,BCZ2WVSH674563PDPYOTM3AXDQ,USD,13.50,Sporting Goods,A-91827645,1

.CSV formatting requirements

Requirement	Description
File format	Must be .CSV comma-separated. Files with semicolons, pipes, and tabs will cause the file to be rejected.
Decimal separator	Use a period (.), not a comma. For example, submitting 943,39 instead of 943.39 will inflate the amount.
EventDate format	Must be dd-MMM-yyyy HH:mm:ss z (e.g., 01-AUG-2017 23:55:24 PST) or ISO-8601 (e.g., 2017-08-01T23:55:24-08:00). You can also use NOW to submit the current timestamp.
OrderId	Must be unique per action. Reusing an existing OrderId returns OID_DUPLICATE. If resubmitting a corrected action, append a suffix (e.g., ORD123_1).
Multi-item orders	Rows sharing the same OrderId must be consecutive in the file. Non-consecutive rows with the same OrderId will error as OID_DUPLICATE.
CurrencyCode	ISO 4217 format (e.g., USD). The code must match your account's configured currency. If omitted, defaults to USD.
Encoding	UTF-8, no BOM.
Filename	Adding a timestamp (e.g., conversions_20260605.csv) is recommended. Uploading a file with the same name as one still processing will return a 551 error.
Column headers	Column headers are case-sensitive (e.g., clickid, ClickID, and ClickId are treated as different columns).

Excel users: Excel converts large numeric IDs (such as ClickId values) to scientific notation. Always format these columns as Text before populating them, or export via a .CSV editor that doesn't apply number formatting.

Submit the .CSV file

Each section below covers the basics of submitting a conversion data .CSV file — to learn more, see Submit Conversion Data via FTP or Email in the impact.com Help Center.

Processing limits: The FTP processing limit is 500,000 records per hour. impact.com recommends keeping individual files under 10,000 records. If you need to submit larger volumes, split the file into multiple batches. After submitting, allow 15-30 minutes for submission. Files submitted via Partner FTP (pull method) may take up to 24 hours to appear.

impact.com uses different hostnames depending on how you submit your file. Use the one that matches your submission method:

Hostname	Used for
batch.impact.com	Direct FTP/FTPS/SFTP upload (impact.com FTP method).
import.impact.com	Email-submitted file ingestion.
products.impact.com	Product catalog/feed uploads.

Impact FTP

Note: You'll need your impact.com FTP server credentials from your impact.com account.

To access your FTP credentials:

1. Log in to your impact.com account.
2. From the top navigation bar, select [User profile] → Settings.
3. In the Program column, under Tracking, select Event Types.
4. Find the event type with a Type of "Impact FTP".
5. Hover your cursor over the row of the FTP event type, select [More] → View / Edit.
6. Select the View IR FTP Credentials button in the upper-right of the screen to access your credentials.

   • Alternatively, you can select the pencil icon on the far right of the Tracking Method row.
   • Under Upload file to system FTP Server, select Email FTP Username and Password.
   • Any account user with the Admin or Implementation Specialist roles or with the Technical Settings permission should receive an email with the FTP credentials.
7. Use an FTP client to connect to the impact.com FTP server with the following data:

   Server	ftp://batch.impact.com
   Port	21
   Transfer Mode	Passive (PASV)

   • Connect using Passive (PASV) mode. Active mode connections are blocked by most corporate firewalls and will result in a 425 Can't open data connection error. Confirm this setting in your FTP client before connecting.
8. Once connected, upload your file to the current directory. You won't be able to see files within the directory.
9. After at least 30 minutes have passed, go to the impact.com platform and from the top navigation bar, select [User profile] → Settings.
10. In the left column, under the Technical section, select File Submissions.
11. On the FTP File Submissions screen, you should see your file upload in the list.

Email

Before you begin: Email submission must be enabled by your impact.com implementation engineer or account manager. Once enabled, your unique submission email address will be available in your Tech Plan document. If you don't have a Tech Plan or can't locate the address, contact support.

1. In the To field, input the unique impact.com email address assigned to your account. Do not include any other emails — impact.com only looks at the first email address.
2. Upload your .CSV file as a file attachment to the email.
3. Send the email.
4. After 30 minutes, go to the impact.com platform and from the top navigation bar, select [User profile] → Settings.
5. In the left column, under the Technical section, select File Submissions.
6. On the FTP File Submissions screen, you should see your file upload in the list.

Partner FTP

Note: You'll need to provide impact.com with login credentials for your FTP server.

1. From the top navigation bar, select [User profile] → Settings.
2. In the right column, go to the Tracking section and select Event Types.

1. Next to the Tracking line item, confirm that you've provided a valid Server URL, Username, Password, Port, and Directory.
2. Place your .CSV file in the specified directory. impact.com will pull this file from your FTP server within 24 hours.
3. After at least 24 hours has passed, go to the impact.com platform and from the top navigation bar, select [User profile] → Settings.
4. In the left column, under the Technical section, select File Submissions.
5. On the FTP File Submissions screen, you should see your file upload in the list.

How retrieval works

• impact.com polls your FTP server once every 24 hours and retrieves any new files in the configured directory.
• Files are matched by filename. impact.com will not re-process a file with the same name it has already retrieved. Use a timestamp in the filename (e.g., conversions_20260605.csv) to ensure each submission is treated as new.
• Avoid using the prefixes ir_, imp_, or impact_ in filenames — these are reserved by impact.com's internal processing system.
• If no new files are found during a polling cycle, no action is taken and no error is logged.

Error codes

When impact.com processes your file, row-level errors are logged in the FTP File Submissions report. A file can show as Processed while individual rows have errored. Check the batch log after every submission.

For a complete reference, see impact.com Error Codes Reference and Batch Submit Conversion Data.

Error Codes reference

Error	Description	Fix
NO_REFERRERS_FOUND	No click or referral matched this conversion.	Ensure ClickId / im_ref maps to a tracked click. For chained events, verify the parent event was attributed to a contracted partner.
OLD_DUPLICATE	An action with this OrderId already exists.	Use a unique OrderId. For multi-item orders, ensure rows sharing an OrderId are consecutive. To correct a prior submission, reverse the original first, then resubmit with a modified OID.
INVALID_EVENT_DATE	EventDate is in the wrong format or older than 88 days.	Use dd-MMM-yyyy HH:mm:ss z or ISO-8601. Confirm the date is within the 88-day window.
CLICK_AFTER_CONVERSION_EVENT	The click timestamp is later than the conversion EventDate.	Check your EventDate value and timezone — the conversion must occur after the associated click.
ALREADY_LOCKED	The action's locking period has passed.	Plan modification uploads before your program's locking window closes.
OUTSIDE_PARENT_ASSOC_WINDOW	A child action was submitted after the association window expired.	Submit child events within the association window defined in your contract.
INVALID_CURRENCY	CurrencyCode in a modification file doesn't match the original.	Ensure CurrencyCode matches what was submitted with the original conversion.

Once the impact.com app is fully installed, you can begin end-to-end testing to ensure everything is working properly. Learn how to proceed with End-to-End Testing.

1. From the top navigation bar, select [User profile] → Settings.
2. In the right column, under Technical, select File Submissions.

   • Confirm your file appears with a status of Processed. If you submitted via email and the file doesn't appear within 30 minutes, try re-sending from a different email address or switch to direct FTP.
   • A file can show as Processed while individual rows have errored out. See the Error codes reference above for fixes.
   • Verify actions appear in the Advanced Action Listing report. File Submissions confirms delivery, while the report confirms the data was ingested correctly.
   • Confirm that each action was credited to the expected partner.

Modifying or reversing actions: Modifying or reversing a previously submitted conversion uses a different file format than the initial conversion upload. Do not reuse the conversion template for this purpose.

Actions lock after your program's configured locking period. Once locked, they can no longer be modified via file upload — plan corrections before the locking window closes.

To reverse a conversion, submit a reversal file with the original OrderId before resubmitting a corrected record with a new or suffixed OrderId (e.g., ORD123_1).