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 `Date1–3`), any date range you specify is start‑inclusive and end‑exclusive: The start date is included in the range, but the end date is excluded from the range. For example, if you set a payout group rule for: `Date1 is between 2024‑08‑01 and 2024‑09‑30`, conversions where `Date1` is 2024‑08‑01 up to and including 2024‑09‑29 will match the payout group and 2024‑09‑30 will not match the payout group.	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!