To submit conversion data to impact.com via a batch modification file, first identify the action you need to perform. This guide contains different reference sections that allow you to: modify or reverse conversion data, approve an action, identify a conversion event, or assign partner credit.
Action processing reference
Use these fields to modify or reverse action data in bulk after a conversion has occurred.
Modification fields
Use these fields to process modifications or approvals of partner-driven actions. You can apply changes at either the order level or item level, depending on whether the change affects the entire order or specific items within it.
| Field | Level | Required? | Description | Editable? | Note for use | Format | Example |
|---|---|---|---|---|---|---|---|
ActionID | Order/Item | Conditionally Required | An action’s unique identifier, used to specify which action you want to modify. | Non-editable | Recommended when the deduplication window is short. At least one identifier path must be provided (ActionID or OrderId/Oid + ActionTrackerId). | Integer (10) | 12345 |
Oid / OrderId | Order/Item | Conditionally Required | Value you assign to the order—typically an order ID or confirmation number. | Non-editable | Required when using ActionTrackerID. At least one identifier path must be provided (ActionID or OrderId/Oid + ActionTrackerId). | String (64) | T52324111211 |
ActionTrackerID | Order/Item | Conditionally Required | Value impact.com assigns to the Event Type that tracked the action. | Non-editable | Required when using OrderId/Oid. At least one identifier path must be provided (ActionID or OrderId/Oid + ActionTrackerId). | Integer (10) | 98765 |
Amount* | Order/Item | Conditionally Required | Total amount of the order/item, pre-tax, pre-shipping, and post-discount. | Editable | Set the new total amount for the order. If you modify Quantity, this field requires modification too. | Decimal (8,2) | 1234.99 |
CurrencyCode/ Currency | Order | Optional | The 3-character currency code of the purchase, used for exchange rate calculations. Defaults to your impact.com account currency if not provided. | Editable | Set the revenue currency of the action. Defaults to your impact.com account currency if not provided. | String (3) | USD |
CustomerStatus | Order | Optional | The customer’s status at the time of conversion. | Editable | Set the customer’s status at the time of conversion (e.g., New). | String (30) | New |
SKU* | Item | Required | Unique stock-keeping unit (SKU) of the product. | Non-editable | Provide the SKU of the item you want to modify. Must be included for each item. | String (255) | ABC123 |
Quantity* | Item | Optional | Quantity of the item that was purchased in the order. | Editable | Set the new quantity of items in the order. | Integer | 1 |
Category* | Item | Optional | Category for the product - can be automatically pulled if a product catalog has been uploaded. | Editable | Set the category of the item. | String (255) | Footwear |
Reason* | Order/Item | Required | Your reason for modifying the action data. | Editable | Provide a valid reason code for the modification. For item-level modifications, include a Reason for each item. | String | ITEM_RETURNED (See supported values) |
*When modifying multiple items in an order, these fields must be included for each item. The identifier fields are always included only once per order.
Tip: If you want to approve actions, Approve needs to be set up as a custom disposition code. You can then submit the approval with its reason code as you would a modification.
Reversal fields
Use these fields to process reversals of partner-driven actions. You can apply reversals at the order level to reverse an entire order, or at the item level to reverse individual items within an order.
| Field | Level | Required? | Description | Editable? | Note for use | Format | Example |
|---|---|---|---|---|---|---|---|
ActionID | Order/Item | Conditionally Required | An action’s unique identifier, used to specify which action you want to modify. | Non-editable | Recommended when the deduplication window is short. At least one identifier path must be provided (ActionID or OrderId/Oid + ActionTrackerId). | Integer (10) | A12345 |
Oid / OrderId | Order/Item | Conditionally Required | Value you assign to the order—typically an order ID or confirmation number. | Non-editable | Required when using ActionTrackerID. At least one identifier path must be provided (ActionID or OrderId/Oid + ActionTrackerId). | String (64) | T52324111211 |
ActionTrackerID | Order/Item | Conditionally Required | Value impact.com assigns to the Event Type that tracked the action. | Non-editable | Required when using OrderId/Oid. At least one identifier path must be provided (ActionID or OrderId/Oid + ActionTrackerId). | Integer (10) | 98765 |
Amount* | Order/Item | Conditionally Required | Total amount of the order/item, pre-tax, pre-shipping, and post-discount. | Editable | Adjust accordingly when reversing an item, or set to 0 to reverse the order (unless original order Amount = 0). If original order Amount = 0, leave Amount unchanged to avoid misclassifying as a modification. | Decimal (8,2) | 0 |
SKU* | Item | Required | Unique stock-keeping unit of the product. | Non-editable | Provide the SKU value of the item you want to reverse. | String (255) | ABC123 |
Quantity* | Item | Optional | Quantity of the item that was purchased in the order. | Editable | Set the new quantity of items in the order. | Integer | 0 |
Reason* | Order/Item | Required | Your reason for reversing the action data. | Editable | Provide a valid reason code for the reversal. | String | RETURN |
*When reversing multiple items in an order, these fields must be included for each item. The identifier fields are always included only once per order.
Warning: If original order Amount = 0, leave Amount unchanged to avoid misclassifying as a modification.
Additional optional fields
While the fields above are those most commonly used in modifications and reversals, these additional fields can also be submitted when needed. Include them only when you want to modify them.
| Field | Level | Description | Editable? | Format | Example |
|---|---|---|---|---|---|
PaymentType | Order | Method of payment used for this conversion. | Editable | STRING (32) | CREDIT |
OrderSubtotal | Order | Subtotal of the order before discounts, taxes, shipping, or other costs. | Editable | DECIMAL | 49.99 |
OrderDiscount | Order | Total discount applied to the order. Automatically subtracted from the order total. Exclude shipping discounts. | Editable | DECIMAL (12,2) | 3.99 |
OrderShipping | Order | Cost of shipping for this conversion. Total sale amount used for payout excludes shipping. | Editable | DECIMAL (14,2) | 9.99 |
OrderTax | Order | Cost of tax for this conversion. Total sale amount used for payout excludes tax. | Editable | DECIMAL (14,2) | 8.99 |
OrderMargin | Order | Total margin on the conversion (revenue less costs). Typically provided through product catalog. | Editable | DECIMAL (14,2) | 12.34 |
GiftPurchase | Order | Indicates if the order is a gift purchase. Submit true for gift, false otherwise. | Editable | BOOLEAN | true/false |
LocationId | Order | Unique identifier for the location in accommodations or similar contexts. | Editable | STRING (64) | SBHOTEL |
LocationName | Order | Name of the location in accommodations or similar contexts. | Editable | STRING (64) | Fess Parker |
LocationType | Order | Category of the location in accommodations or similar contexts. | Editable | STRING (64) | Hotel |
ItemSubCategory | Item | Subcategory for the product, if applicable. Can be automatically pulled from a product catalog. | Editable | STRING (255) | Metalsmithing |
Name | Item | Name of the product. Can be automatically appended via product catalog. | Editable | STRING (255) | Iron Anvil |
ItemMpn | Item | Manufacturer part number (MPN) for the product. Can be pulled from a product catalog. | Editable | STRING (64) | 123456789 |
ItemBrand | Item | Brand name of the product. Can be automatically pulled from a product catalog. | Editable | STRING (64) | Acme Corp |
ItemDiscount | Item | Discount applied to each product of this type, not the entire line item. | Editable | DECIMAL (12,2) | 2.99 |
ItemPromoCode | Item | Promotional code applied to this item. Does not work with unique tracking codes for partners. | Editable | STRING (255) | ITEMDISCOUNT10 |
ItemTotalDiscount | Item | Discount applied to this line item. Automatically subtracted from ItemSubTotal to determine final sale amount for payout/reporting. | Editable | DECIMAL (12,2) | 49.99 |
ItemDeliveryType | Item | Type of delivery method for this item. | Editable | STRING (64) | EXPRESS |
Conversion details reference
The references below let you manage the contextual details of a conversion. You can assign a conversion to a specific program, define its event type, or credit the correct partner without altering the underlying order data.
Event type fields
Use these fields to define what type of conversion occurred, e.g., online sale / app install. You should submit Event Type data when initially sending a conversion. It's also possible to modify this data before the action locks, if needed.
| Field | Description | Required? | Format (Size) | Example | Notes |
|---|---|---|---|---|---|
ActionTrackerId | Unique identifier for the event type (or action tracker) that tracked this conversion. Normal web: Settings → Events Types. Mobile App: Settings → Mobile App | Required, unless EventTypeCode is provided | INTEGER (10) | 1000 | Also known as EventTrackerID |
EventTypeCode | Configurable string value for the event type that identifies it when submitting conversions. To view or configure this value, see Settings → Events Types → Actions → View/Edit → "Codes" in the platform. | Required, unless ActionTrackerId is provided | STRING (128) | SALE | |
EventCode | Custom identifier for the event that occurred in your mobile app that you want to report (e.g., INSTALL, SIGN-UP, SALE, etc.) | Required, when submitting mobile conversions | STRING (128) | INSTALL | With Mobile events, the ActionTrackerId is specific to the mobile type (E.g., iOS, Android). EventCode is submitted to distinguish between the different mobile events (INSTALL, SIGN-UP, SALE, etc.) |
EventDate | The date and time when the conversion event occurred; use ISO 8601 format. | Required | DATETIME (ISO 8601) | 2038-01-19T03:14:08Z | NOW is also an accepted value, but should only be used when a datetime in ISO 8601 format cannot be provided. NOW records the time the event is processed, not when it occurred. If delays or outages happen, this may result in incorrect EventDate values. |
DispositionCode | Configurable string value for the event type that will modify the conversion's Reporting State and/or Action State, depending on what's been configured. | Optional | STRING (64) | ORDER RETURNED | Disposition codes are used to change the Reporting State of the action (report status partners can see), and/or Action State (i.e., approved, rejected, modified). See Settings → Events Types → … → Disposition Codes in the platform. |
Attribution fields
Use these fields to determine which partner receives credit for a conversion and how the consumer journey is evaluated. You can submit attribution data when reporting new conversions. Attribution details can also sometimes be updated for a conversion after it locks, if your setup allows.
Note: At least one attribution key is required. See the Required column below for more details.
| Parameter Name | Type | Description | Required | Example | Notes |
|---|---|---|---|---|---|
ClickId | STRING (64) | An identifier for a referred click that represents the consumer's journey. When a visitor lands on your page via an impact.com tracking link, this value is generated and appended as a query string parameter, which should be captured for conversion reporting. | Required, unless another attribution parameter is provided Required when you or your partners are passing SubIds or a SharedId | QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0 | If available, it's generally always recommended to pass the ClickId value when reporting a conversion. Also note that any generated ClickId value can be associated with multiple clicks — it is not unique to an individual click. |
CustomerId | STRING (255) | A unique identifier that you (or your systems) generate for the customer driving this conversion. These IDs should be non-identifying (e.g. plain text email addresses are not permitted). | Required, unless another attribution parameter is provided | R523GSSD2342333FSCSA | This key will be used for insights reporting along with conversion chaining. |
CustomProfileId | STRING (70) | An id used to uniquely identify a user on your property (regardless of whether they are signed in or not). | Required, unless another attribution parameter is provided | POOWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0 | Common examples include anonymous user cookies and IDFVs. |
OrderPromoCode || PromoCode | STRING (255) | The promotional code associated with this conversion. Note that this only works as an attribution key if this code was assigned as a unique tracking code to a particular partner. In that case, that partner will win credit for this conversion. Otherwise, this will be reported as the promo code used for an order. | Required (if available), unless another attribution parameter is provided | ACMEPARTNER | To use promo codes as an attribution key, they need to be configured in Ad Settings and validated in the Event Type Settings screen of the platform. When using, OrderPromoCode is preferred over PromoCode. |
UniqueUrl | STRING (255) | Only used if you have issued unique URLs to partners for tracking purposes. You may send the unique URL here that referred this conversion. Note that these must first be set up in your account before they can be used for attribution. | Required (if available), unless another attribution parameter is provided | https://www.example.com/acmepartner | Learn more about Unique URLs. |
GoogAId | STRING (36) | Google Advertising Id associated with the mobile device the customer converted on. | Required (if available), unless another attribution parameter is provided | cdda802e-fb9c-47ad-9866-0794d394c912 | Used for attribution purposes. Typically only available for Android in-app conversions. |
AppleIfa | STRING (36) | Apple Id for Advertising (IDFA) associated with the mobile device the customer converted on. | Required (if available), unless another attribution parameter is provided | EA7583CD-A667-48BC-B806-42ECB2B48606 | Used for attribution purposes. Typically only available for iOS in-app conversions. |
AppleIfv | STRING (36) | Apple ID for Vendors (IDFV) associated with the mobile device the customer converted on. | Required (if available), unless another attribution parameter is provided | AEBE52E7-03EE-455A-B3C4-E57283966239 | Used for attribution purposes. Typically only available for iOS in-app conversions. |
MediaId || MediaPartnerId | INTEGER (10) | ID of the partner or media source that will automatically receive credit for the conversion. By passing this value, you force them to win credit for this conversion, bypassing the consumer journey. Only used in specific cases where forced attribution is required — do not submit this value otherwise. | Only used and required for "Forced Attribution" (read description & notes) | 1234567 | Only pass a value for this parameter if you have no other attribution keys or are forcing attribution to a specific partner or media source intentionally. Do not use this attribution parameter if you or your partners are passing any SubIds or SharedIds. |
IpAddress | STRING (128) | The customer's public IP address when driving the conversion. The IP address is used to help the system identify fraudulent activity. The IP address will only be used for attribution in the case of installs. | Optional, primarily used for mobile app tracking | 72.194.216.61 || 2001:0db8:85a3:0000:0000:8a2e:0370:7334 | Supports both IPv4 and IPv6 addresses. |
PhoneNumber | STRING | Phone number the customer called in call tracking conversions. If call tracking is configured to use unique phone numbers, value is used to match the conversion to the originating call record. | Only used and required for Call Tracking (read description & notes) | 15558675309 | |
CallerId | STRING | Unique identifier of the customer in call tracking conversions. Value is used to match the conversion to the originating call record. | Only used and required for Call Tracking (read description & notes) | ||
CountryCode | STRING (2) | Two-letter country code of the customer's phone country code; use ISO 3166-1 alpha-2. | Only used and required for Call Tracking (read description & notes) | US | (See countrycode.org) |
Program fields
Use this field to associate a conversion with a specific impact.com program (formerly known as a campaign). Every conversion must belong to a program.
| Parameter Name | Type | Description | Required | Example | Notes |
|---|---|---|---|---|---|
| CampaignId | INTEGER (10) | Unique identifier for the campaign (or program) that the conversion is associated with. | Required | 1000 | This value is always required when submitting conversions. |
Advanced scenarios reference
These references are relevant only to specific tracking configurations, e.g., parent-child events or phone call events.
Chained action fields
Chained actions allow impact.com to associate follow-up events with an original conversion, e.g., a ticket sale with an initial reservation. Use these fields to link together multiple related conversion events.
| Parameter Name | Format (Size) | Description | Requirement | Example | Notes |
|---|---|---|---|---|---|
CustomerId | STRING (255) | A unique identifier that you (or your systems) generate for the customer driving this conversion. These IDs should be non-identifying (e.g. plain text email addresses are not permitted). | Required | R523GSSD2342333FSCSA | This key will be used for insights reporting along with conversion chaining. In the case of chained actions, for the Child Tracker, you should pass the same customer ID as that of the Parent event or else it won't chain the actions. |
Call conversion fields
Warning: Native phone number tracking is being deprecated and is planned for removal in the future. For alternative solutions, use a supported 3rd-party provider like Invoca.
Use these fields when reporting conversions that originate from tracked phone calls. This data is only required for call tracking integrations and should not be sent for web or app conversions.
| Parameter name | Format | Requirement | Description |
|---|---|---|---|
CampaignId | INTEGER | Required | Unique identifier for the campaign (or program) that the call conversion is associated with. |
MediaId | INTEGER | Required | Unique identifier for the partner or media source. |
EventDate | DATETIME (ISO 8601) | Required | ISO 8601 format of the date and time when the call conversion event occurred. |
ActionTrackerId | INTEGER | Required | Unique identifier for the action tracker (i.e., event type) that's tracking the phone call. |
CallProvider | STRING | Required | The vendor or client who is sending the call event data |
CallSessionId | STRING | Required | A unique session ID that the vendor or client uses to identify the call. |
CallerId | STRING | Required | The phone number of the originating call, used to match the final conversion. |
CalledPhoneNumber | STRING | Required | The destination phone number or the phone number that received the call. |
CallDuration | STRING | Required | Total duration (in seconds) of the call. |
TalkDuration | STRING | Required | Actual talk duration (in seconds) of the call. |
AdId | INTEGER | Optional | Unique identifier for the ad associated with the call conversion. |
CallStatus | STRING | Optional | This value indicates the final outcome of the call. If the field is not present in request, we make it ANSWER by default. Valid values are: UNKNOWN_CALLERID, FAILURE, CONGESTION, INCOMPLETE, CANCEL, IVR_DROPOFF, NO_TRANSFER_ATTEMPT, ANSWER |
CallerPhoneNumberCountry | STRING | Optional | Two-digit country code for the originating phone number (ISO 3166 alpha-2). When NULL, defaults to US. |
CalledPhoneNumberCountry | STRING | Optional | Two-digit country code for the called phone number (ISO 3166 alpha-2). When NULL, defaults to US. |
SubId1 | STRING | Optional | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them. |
SubId2 | STRING | Optional | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them. |
SubId3 | STRING | Optional | This value is specific and only available to the media partner. This is the placeholder where Media Partner can add data points that they want impact.com to report back to them. |
ClickId | STRING | Optional | Unique case-sensitive identifier generated by impact.com of a referring click, used to construct a consumer journey. |
Country | STRING | Optional | Country of the CallerId - as identified by the call tracking vendor. |
City | STRING | Optional | City of the CallerId - as identified by the call tracking vendor. |
Region | STRING | Optional | Region of the CallerId - as identified by the call tracking vendor. |
Zip | INTEGER | Optional | Zip of the CallerId - As identified by the call tracking vendor. |
RepeatCaller | STRING | Optional | Repeat vs New call to indicate whether the caller was recorded as a repeat caller by the call tracking vendor. |
PhoneType | STRING | Optional | The type of phone (i.e., landline, mobile). |
CallRecording | STRING | Optional | Unique URL of the call recording. |
IvrDuration | STRING | Optional | Duration in seconds that the call spent in the IVR tree. |
Keypresses | STRING | Optional | List of unique key names that were pressed during the call. |
Key1 | STRING | Optional | Name of the first key that was pressed. |
Key2 | STRING | Optional | Name of the second key that was pressed. |
Key3 | STRING | Optional | Name of the third key that was pressed. |
Key4 | STRING | Optional | Name of the fourth key that was pressed. |
TrafficSource | STRING | Optional | Source of the transaction (referring media source). |
OptInSms | STRING | Optional | Whether the caller opted in to receive an SMS promotion. |
UserAgent | STRING | Optional | The user agent of the conversion generator. |
DispositionName | STRING | Optional | The Conversion Event Name. |
SaleAmount | CURRENCY | Optional | If Sale Conversion, Sale Amount |
ReferenceId | STRING | Optional | Customer Disposition Code for reference. |
CustomConversionEvent1Name | STRING | Optional | Custom name for reporting on conversion events |
CustomConversionEvent2Name | STRING | Optional | Custom name for reporting on conversion events |
CustomConversionEvent3Name | STRING | Optional | Custom name for reporting on conversion events |
CustomConversionEvent1Value | STRING | Optional | Custom value for reporting on conversion events |
CustomConversionEvent2Value | STRING | Optional | Custom value for reporting on conversion events |
CustomConversionEvent3Value | STRING | Optional | Custom value for reporting on conversion events |
VendorEventId | STRING | Optional | Will be unique for call event and unique for the conversion event. |
PromoNumberDescription | STRING | Optional | Describes the called phone number |
CustomCallEvent1Name | STRING | Optional | Custom name for reporting on call events |
CustomCallEvent2Name | STRING | Optional | Custom name for reporting on call events |
CustomCallEvent3Name | STRING | Optional | Custom name for reporting on call events |
CustomCallEvent1Value | STRING | Optional | Custom value for reporting on call events |
CustomCallEvent2Value | STRING | Optional | Custom value for reporting on call events |
CustomCallEvent3Value | STRING | Optional | Custom value for reporting on call events |
Optional reporting fields reference
Use these fields to add extra context to a conversion for reporting or troubleshooting. These fields are all optional and enhance reporting, segmentation, and analytics. If you don’t need this data in your reports, you can leave these fields out.
| Parameter Name | Type | Description | Required/Optional | Example |
|---|---|---|---|---|
Money1-3 | DECIMAL (18,3) | General decimal fields for any financial data. Appears in reports. | Optional | 12345.678 |
Numeric1-3 | DECIMAL (18,3) | General decimal fields for any numeric data. Appears in reports. | Optional | 987654.321 |
Date1-3 | STRING (30) | General date fields for any date/datetime. Appears in reports. When you create payout group rules using a date field (such as | Optional | 2038-01-19 |
SubId1-3 | STRING (255) | General fields used for event-level reporting purposes. | Optional | |
Text1-50 | STRING (64) | General text fields for adding any text data. Modifiable and appears in reports. | Optional | |
UserAgent | STRING (255) | Describes the user agent associated with the conversion. | Optional | Mozilla/5.0 |
CustomerStatus | STRING (30) | Customer status at the time of conversion. | Optional | New |
CustomerCity | STRING (255) | Customer's city during conversion. | Optional | Amsterdam |
CustomerCountry | STRING (255) | Customer's country during conversion. | Optional | Netherlands |
CustomerPostCode | STRING (255) | Customer's postal code during conversion. | Optional | 1011 AC |
CustomerRegion | STRING (255) | Customer's region during conversion. | Optional | North Holland |
DeviceModel | STRING (255) | Device model used during conversion. | Optional | iPhone 13 Pro |
DeviceMfr | STRING (255) | Device manufacturer used during conversion. | Optional | Apple |
AppPackage | STRING (255) | App package name used during conversion. | Optional | com.example.app |
AppInstallRef | STRING (255) | App installation reference during conversion. | Optional | Ref12345 |
AppVer | STRING (255) | App version during conversion. | Optional | 1.0.0 |
PropertyId | STRING (255) | Property ID associated with the conversion. | Optional | Property123 |
IrAppId | STRING (255) | IR App ID associated with the conversion. | Optional | IRApp123 |
Referral Landing Page | STRING (255) | URL of the landing page where the referral originated. | Optional | https://example.com/referral |
Referral Subaccount ID | STRING (255) | ID of the referral subaccount. | Optional | SubID123 |
Referral Subaccount Name | STRING (255) | Name of the referral subaccount. | Optional | SubName |
Referral Ad Program | STRING (255) | Ad program associated with the referral. | Optional | AdProgram123 |
Referral Ad Type | STRING (255) | Ad type associated with the referral. | Optional | Display |
Referral Ad Group | STRING (255) | Ad group associated with the referral. | Optional | AdGroup123 |
Referral Traffic Type | STRING (255) | Type of traffic associated with the referral. | Optional | Organic |
Referral URL | STRING (255) | URL of the referral source. | Optional | <https://example.com> |
Path Media Count | INTEGER | Number of media elements in the conversion path. | Optional | 5 |
Path Channel Count | INTEGER | Number of channels in the conversion path. | Optional | 3 |
Path Steps | INTEGER | Number of steps in the conversion path. | Optional | 10 |
Site Category | STRING (255) | Category of the site where the conversion occurred. | Optional | E-commerce |
Site Version | STRING (255) | Version of the site where the conversion occurred. | Optional | v1.0 |
Hear About Us | STRING (255) | How the customer heard about the business. | Optional | Social Media |
TrackingConsent | BOOLEAN | Indicates whether the user has provided consent to be tracked. | Optional | true |
Note | STRING (255) | General field used for event-level reporting purposes. Modifiable and requires MediaPartnerId. | Optional | Hello, World! |