Action & Conversion Field References
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.
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.
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.
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.
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.
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
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
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
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
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
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
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
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 and notes)
1234567
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
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 or 2001:0db8:85a3:0000:0000:8a2e:0370:7334
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 and 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 and 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 and notes)
US
Note: 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.
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.
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.
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 has been deprecated. 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.
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.
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.
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!
Last updated