The conversion object

📘

Notes

  • Attributes ending with [i] indicate that it's indexed (e.g, ItemSku1, ItemSku2, etc.). These are mostly used when reporting multiple items within a conversion.

  • The number in parentheses next to an attribute (e.g., "(34)") indicates the maximum character length.

Attributes


CampaignId integer (10)

Unique identifier for your program (or campaign) on impact.com. Viewable in the platform by selecting your account name from the top left corner—your campaign ID is the integer in gray type under Programs section.


EventTypeId integer (10)

Unique identifier for the event type (or action tracker) that tracked this conversion. Functionally identical to ActionTrackerId.


EventTypeCode string (64)

Configurable string value for the event type that identifies it when submitting conversions. To view or configure this value, see Events Types → Actions → View/Edit → "Codes" in the platform.


EventDate datetime

Time and date when the conversion event actually took place, in ISO 8601 format. Alternatively, submit NOW for impact.com to use the date & time when the conversion is submitted.


OrderId string (64)

Your unique identifier for the order associated with this conversion. For example, in a retail sale, this could be the Order ID you've assigned the customer for their purchase. Note that an OrderId value only needs to be unique to the action tracker.


CustomProfileId string (70)

Unique identifier used to identify a visitor on your website (regardless of whether they're signed in). Common examples include anonymous user cookies and IDFVs.


ClickId string (64)

Unique case-sensitive identifier generated by impact.com of a referring click, used to construct a consumer journey. This value is usually passed onto the landing page after a click redirect occurs under the query string parameter name clickid. Configured on the Gateway Settings screen.


CustomerId string (255)

Unique identifier that you generate for the customer that converted. These values must be non-identifying (e.g., plain text email addresses are not permitted). Used for Optimize reporting and conversion chaining.


CustomerEmail string (255)

The email address you have on file for this customer. Primarily used to improve attribution for the conversion (particularly in cross-device situations). This field can either be hashed ahead of time using the SHA1 function or can be sent in plain text and will be subsequently hashed by the system. All values are hashed a second time using a SHA-256 function before storing.


OrderPromoCode string (255)

Promo code used for the order tracked by the conversion. 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.


GoogAid string (36)

Google Advertising ID associated with the mobile device the customer converted on. 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. 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. Used for attribution purposes. Typically only available for iOS in-app conversions.


UniqueUrl string (255)

Unique URL for a partner or source that referred the conversion. Only used if you've configured and assigned Unique Domains to your partners.


CustomerStatus string (255)

Status of the customer, such as NEW or EXISTING. Before being passed, values must be configured in the Customer Status Mapping section when editing an event type, found in the event type settings section of the platform.


PropertyId integer

For mobile app conversions, this value is the "System App ID" of your app in impact.com. Found in Settings → Mobile Apps


TrackingConsent boolean

Indicates whether the user has provided consent to be tracked at the moment of the request. Derived from your consent management platform or through frameworks like Apple’s ATT (App Tracking Transparency) available on iOS.

To implement TrackingConsent for iOS traffic, your app must request user permission to be tracked (available on iOS 14+, see Apple's App Tracking Transparency). Once your app starts requesting this permission, you can start passing the TrackingConsent parameter. The TrackingConsent value you pass is based on the user's AuthorizationStatus.

TrackingConsentAuthorizationStatus
trueauthorized
falsedenied
notDetermined
restricted

CustomerCity string (128)

City where the customer converted.


CustomerRegion string (128)

Region where the customer converted. (e.g., EMEA, AMER, APAC).


CustomerCountry string (128)

Country where the customer converted.


CustomerPostCode string (32)

Postal (or "ZIP") code where the customer converted.


DispostionCode string (64)

If you have a custom disposition code configured in event type settings, you can submit that value as a default disposition for the action that results from this conversion.


IpAddress string (128)

IP address of the customer. 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.


UserAgent string (1024)

User agent of the customer, used to provide device reporting.


OrderDiscount decimal (12,2)

For sales, this is the discount applied to the order overall. Amount is automatically subtracted from the order total on processing. If item amounts are used, this discount will be subtracted proportionally from each item amount sent in. Note that typically you will want to exclude shipping discounts from this field.


OrderSubTotalPostDiscount decimal

The subtotal of the order after discounts, taxes, shipping, and any other costs. If you're submitting item-level data, this value should not be submitted.


OrderShipping decimal (14,2)

Primarily used for retail sales. This is the cost of shipping for this conversion. Note that the total sale amount used for payout purposes will not include shipping costs.


OrderTax decimal (14,2)

Primarily used for retail sales. This is the cost of tax for this conversion. Note that the total sale amount used for payout purposes will not include shipping costs.


OrderMargin decimal (14,2)

Primarily used for retail sales. This is the total margin made on the conversion (revenue less costs). Typically this is provided either at an item level through the ItemMargin field or through the product catalog.


ItemSku[i] string (255)

Unique identifier for the item—usually the stock-keeping unit (SKU) identifier of the product.


ItemName[i] string (255)

The name for the product referenced. Can also be automatically appended through uploading a product catalog.


ItemCategory[i] string (255)

Category for the product referenced at the item level. Can also be automatically pulled if a product catalog has been uploaded.


ItemSubCategory[i] string (255)

If applicable, the subcategory for the product referenced at the item level. Can also be automatically pulled if a product catalog has been uploaded.


ItemMpn[i] string (64)

Manufacturer part number (MPN) for the product referenced. Can also be automatically pulled if a product catalog has been uploaded.


ItemBrand[i] string (64)

Brand name for the product referenced. Can also be automatically pulled if a product catalog has been uploaded.


ItemDiscount[i] decimal (12,2)

Discount applied to each item purchased of this type (not to the entire line item).


ItemPrice[i] decimal

Individual unit price for each product in this line item. This is multiplied by the ItemQuantity (and discounts are subtracted) to derive the ItemSubTotal. Note that this field should not be sent if ItemSubtotal is passed.


ItemQuantity[i] integer

Quantity of the item that was purchased in the order, expressed as a whole number.


ItemPromoCode[i] integer (255)

Promotional code applied to the item for the order. Note that this parameter does not work with unique tracking codes setup for particular partners.


ItemTotalDiscount[i] decimal (12,2)

Discount applied to this line item (not just for each product of this type). Note that this amount is automatically subtracted from the ItemSubTotal to determine the final sale amount for payout and reporting purposes.


ItemSubTotal[i] decimal (14,2)

Total price for this line item (all products purchased of this type). The final value will be determined by subtracting the corresponding discounts from this value. Note that this field should not be sent if ItemPrice is passed.


ItemDeliveryType[i] decimal (64)

Type of delivery method specified for this item (e.g. INSTORE).


GiftPurchase boolean

If you're tracking gift purchases, you can submit true to report the order in the conversion as a gift purchase or false if the order isn't a gift purchase.


LocationId string (64)

Primarily used for accommodations, this is the unique identifier for the location specified in this conversion.


LocationName string (64)

Primarily used for accommodations, this is the name for the location specified in this conversion.


LocationType string (64)

Primarily used for accommodations, this is the category for the location specified in this conversion.


PaymentType string (32)

This method of payment used for this conversion (e.g. Credit).


CurrencyCode currency (3)

Three-letter ISO 4217 alpha code representing the currency. If not sent, your account's default currency will be used.


AppPackage string (255)

Package name for the mobile app the user installed. Only for mobile conversions. Note that this is also picked up through the PropertyId field.


AppInstallRef string (255)

Only for Android conversions. Install referrer passed from the Google Play Store when the app is installed. Usually, the value passed from impact.com tracking links will be clickid={clickidvalue}.


AppName string (255)

Name of the mobile app. Only for mobile conversions.


AppVer integer

Version of the mobile app. Only for mobile conversions.


DeviceMfr enum (255)

For a conversion in a native app, reports the manufacturer of the device the user made the conversion on. This value is expected to be programmatically retrieved from your app and passed in the request.


DeviceModel enum (255)

For a conversion in a native app, reports the model of the device the user made the conversion on. This value is expected to be programmatically retrieved from your app and passed in the request.


More attributes


View more attributes

Note string (255)

General field used to pass information for event-level reporting purposes.


Text1 string (64)

General text field that accepts strings of any text data you want to send. Appears in your reports.


Text2 string (64)

General text field that accepts strings of any text data you want to send. Appears in your reports.


Text3 string (64)

General text field that accepts strings of any text data you want to send. Appears in your reports.


Numeric1 decimal (18,2)

General numeral field that accepts any numeric data you want to send. Appears in your reports.


Numeric2 decimal (18,2)

General numeral field that accepts any numeric data you want to send. Appears in your reports.


Numeric3 decimal (18,2)

General numeral field that accepts any numeric data you want to send. Appears in your reports.


Money1 decimal (18,2)

General numeral field that accepts any money or financial numeric data you want to send. Appears in your reports.


Money2 decimal (18,2)

General numeral field that accepts any money or financial numeric data you want to send. Appears in your reports.


Money3 decimal (18,2)

General numeral field that accepts any money or financial numeric data you want to send. Appears in your reports.


Date1 datetime

General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports.


Date2 datetime

General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports.


Date3 datetime

General field that accepts a date and time in ISO 8601 format you want to send. Appears in your reports.


PhoneNumber integer

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.


CallerId string

Unique identifier of the customer in call tracking conversions. Value is used to match the conversion to the originating call record.


CountryCode string

Primary used for conversions over the phone, this is the ISO 3166-1 alpha-2 two-letter country code of the the number called by the customer.


MediaId integer

Unique identifier of the partner or source to which you want to force attribution. Only used if you cannot pass any other attribution key as this bypasses the consumer journey mapping process. By passing this value, you force them to win credit for this conversion.


SubId1 string (255)

Only used if you are specifying the MediaId directly and have no other means to tie this conversion to a click or impression. Custom text field typically used by partners to segment their traffic.


SubId2 string (255)

Only used if you are specifying the MediaId directly and have no other means to tie this conversion to a click or impression. Custom text field typically used by partners to segment their traffic.


SubId3 string (255)

Only used if you are specifying the MediaId directly and have no other means to tie this conversion to a click or impression. Custom text field typically used by partners to segment their traffic.


SharedId string (255)

Only used if you are specifying the MediaId directly and have no other means to tie this conversion to a click or impression. Custom text field typically used by partners to share traffic segments with the brands they work with.

Example requests

{
  "CampaignId": "3641",
  "EventTypeId": "8180",
  "EventDate": "NOW",
  "OrderId": "9217374917471",
  "ClickId": "QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0",
  "CustomerId": "BCZ2WVSH674563PDPYOTM3AXDQ",
  "CustomerEmail": "[email protected]",
  "OrderPromoCode": "10OFF-ROCKET",
  "CustomerStatus": "NEW",
  "CustomerPostCode": "15122",
  "CurrencyCode": "USD",
  "OrderDiscount": "5",
  "IpAddress": "72.194.216.61",
  "ItemSku1": "12345",
  "ItemName1": "Ninjago",
  "ItemCategory1": "Lego",
  "ItemQuantity1": "2",
  "ItemPrice1": "10",
  "ItemSku2": "78909",
  "ItemName2": "Barbie",
  "ItemCategory2": "Dolls",
  "ItemQuantity2": "1",
  "ItemPrice2": "6.99"
}
{
  "CampaignId": "3641",
  "EventTypeId": "8180",
  "EventDate": "2020-05-05T00:23:42Z",
  "OrderId": "9217374917471",
  "ClickId": "QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0",
  "CustomerId": "BCZ2WVSH674563PDPYOTM3AXDQ",
  "CustomerStatus": "NEW",
  "Text1": "CounterOffer",
  "ItemSku1": "SV-1122",
  "ItemName1": "Emerald Card",
  "ItemCategory1": "Rewards",
  "ItemQuantity1": "1",
  "ItemPrice1": "0",
}
{
  "CampaignId": "3641",
  "EventTypeId": "8180",
  "EventDate": "NOW",
  "OrderId": "9217374917471",
  "ClickId": "QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0",
  "CustomerId": "BCZ2WVSH674563PDPYOTM3AXDQ",
  "CustomerEmail": "[email protected]",
  "GoogAId": "EA7583CD-A667-48BC-B806-42ECB2B48606",
  "CustomProfileId": "POOWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0",
  "PropertyId": "3090",
  "CustomerStatus": "NEW",
  "CurrencyCode": "USD",
  "IpAddress": "72.194.216.61",
  "ItemSku1": "12345",
  "ItemName1": "Premium Monthly Subscription",
  "ItemCategory1": "Premium",
  "ItemQuantity1": "1",
  "ItemPrice1": "9.99",
}
{
  "CampaignId": "3641",
  "EventTypeId": "8180",
  "EventDate": "2020-01-04T00:23:45Z",
  "OrderId": "9217374917471",
  "ClickId": "QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0",
  "CustomerId": "BCZ2WVSH674563PDPYOTM3AXDQ",
  "CustomerEmail": "[email protected]",
  "GoogAId": "EA7583CD-A667-48BC-B806-42ECB2B48606",
  "CustomProfileId": "POOWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0",
  "PropertyId": "3090",
  "OrderDiscount": "50.00",
  "CustomerStatus": "RETURNING",
  "CurrencyCode": "USD",
  "IpAddress": "72.194.216.61",
  "LocationType": "Independent",
  "ItemSku1": "12345",
  "ItemName1": "Opaque Hotel",
  "ItemCategory1": "Suite",
  "ItemQuantity1": "2",
  "ItemPrice1": "150.00",
}
{
  "CampaignId": "3641",
  "EventTypeCode": "INSTALL",
  "EventDate": "2020-01-04T00:23:45Z",
  "OrderId": "9217374917471",
  "ClickId": "QiiWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0",
  "GoogAId": "EA7583CD-A667-48BC-B806-42ECB2B48606",
  "CustomProfileId": "POOWXOVnrQ3SQHl24jQjyxBGUkmzfJ3i1VHrWM0",
  "PropertyId": "3090",
  "IpAddress": "72.194.216.61",
}

Example response


{
  "Status": "QUEUED",
  "QueuedUri": "/Advertisers/<AccountSID>/APISubmissions/<SubmissionID>"
}