> For the complete documentation index, see [llms.txt](https://integrations.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/ftp-online-sale/implementation.md).
# 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:
```csv
CampaignId,ActionTrackerId,EventDate,OrderId,ClickId,CustomerId,CurrencyCode,Amount,Category,Sku,Quantity
```
{% hint style="info" %}
**Tip:** It's highly recommended to include as much data as possible – refer to the full [Conversions Data Reference document](https://integrations.impact.com/brand-api-reference/reference/action-and-conversion-field-references) for a full list of conversion data parameters.
{% endhint %}
| 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](https://en.wikipedia.org/wiki/ISO_8601). 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:
```csv
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). |
{% hint style="warning" %}
**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.
{% endhint %}
## 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](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/submit-conversion-data-via-ftp-or-email) in the impact.com Help Center.
{% hint style="success" %}
**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.
{% endhint %}
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[^1]/SFTP[^2] upload (impact.com FTP method). |
| `import.impact.com` | Email-submitted file ingestion. |
| `products.impact.com` | Product catalog/feed uploads. |
### Impact FTP
{% hint style="success" %}
**Note:** You'll need your impact.com FTP server credentials from your impact.com account.
{% endhint %}
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**](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml).
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**](https://app.impact.com/secure/advertiser/accountSettings/techintegration/ftp-file-submissions-flow.ihtml).
11. On the *FTP File Submissions* screen, you should see your file upload in the list.
### Email
{% hint style="success" %}
**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](https://app.impact.com/support/portal.ihtml).
{% endhint %}
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**](https://app.impact.com/secure/advertiser/accountSettings/techintegration/ftp-file-submissions-flow.ihtml).
6. On the *FTP File Submissions* screen, you should see your file upload in the list.
### Partner FTP
{% hint style="success" %}
**Note:** You'll need to provide impact.com with login credentials for your FTP server.
{% endhint %}
1. From the top navigation bar, select  **\[User profile] → Settings**.
2. In the right column, go to the *Tracking* section and select [**Event Types**](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml).
3. Next to the *Tracking* line item, confirm that you've provided a valid **Server URL**, **Username**, **Password**, **Port**, and **Directory**.
4. Place your .CSV file in the specified directory. impact.com will pull this file from your FTP server within 24 hours.
5. After at least 24 hours has passed, go to the impact.com platform and from the top navigation bar, select  **\[User profile] → Settings**.
6. In the left column, under the *Technical* section, select [**File Submissions**](https://app.impact.com/secure/advertiser/accountSettings/techintegration/ftp-file-submissions-flow.ihtml).
7. 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](https://help.impact.com/brand/what-would-you-like-to-learn-about/account-administration/account-settings/send-data-to-impactcom/access-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](https://help.impact.com/other/reference-documentation/impactcom-error-codes-reference) and [Batch Submit Conversion Data](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/submit-and-modify-conversion-data/submit-conversion-data/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](/integration-guides/end-to-end-tests.md).
1. From the top navigation bar, select  **\[User profile] → Settings**.
2. In the right column, under *Technical*, select [**File Submissions**](https://app.impact.com/secure/advertiser/accountSettings/techintegration/ftp-file-submissions-flow.ihtml).
* 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](#error-codes) above for fixes.
* Verify actions appear in the [Advanced Action Listing](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/multi-program-reports/performance-reports-for-brands/advanced-action-listing-report) report. *File Submissions* confirms delivery, while the report confirms the data was ingested correctly.
* Confirm that each action was credited to the expected partner.
{% hint style="warning" %}
**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`).
{% endhint %}
[^1]: FTP with TLS/SSL encryption. Uses port 21. This is what impact.com's `batch.impact.com` server uses.
[^2]: A completely separate protocol that runs over SSH, typically on port 22. impact.com does not use SFTP for this integration.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/ftp-online-sale/implementation.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.